这里面向准备阅读、修改或审查 Peri 源码的贡献者。用户操作说明仍以文档总览为入口；本节关注代码放在哪里、跨层变更需要同时检查什么。
先建立一张地图
Peri 的终端交互主路径是：
peri-tui → peri-acp → peri-agent::run_react_loop这条简化路径表达调用入口，不代表所有 crate 只有线性依赖。模型协议、公共契约、资源访问、中间件和控制面分别由专门 crate 承担。当前 workspace 的完整依赖关系以根 Cargo.toml、各 crate manifest 和 docs/standards/architecture-contracts.md 为准。
执行核心
peri-agent 管理会话、消息、RCRA 阶段和 Agent 执行权；run_react_loop 是循环入口。
协议边界
peri-acp 接收 ACP 请求并把 Agent 事件协议化；TUI 不直接驱动 Agent 循环。
能力装配
peri-middlewares 提供工具、Skills、MCP、审批、Hook、SubAgent 等能力；生产链顺序由 Agent 层蓝本约束。
终端界面
peri-tui 消费 ACP 通知并维护交互状态、消息视图和面板。
更完整的职责图和跨层不变量见总体架构。
按任务找入口
| 任务 | 先读 | 稳定代码入口 |
|---|---|---|
| Agent loop、Compact、模型调用、工具 trait | docs/code-index/peri-agent.md、架构契约、Rust 规范 |
peri-agent/src/agent/、peri-agent/src/agent/compact_v2/、peri-agent/src/session/ |
| Session、Prompt、事件映射、ACP transport | docs/code-index/peri-acp.md、架构契约 |
peri-acp/src/session/、peri-acp/src/prompt/、peri-acp/src/event/ |
| MCP、Skills、Plugin、SubAgent、HITL、Hook | docs/code-index/peri-middlewares.md、架构契约 |
peri-middlewares/src/ |
| TUI 输入、消息流、面板、通知 | docs/code-index/peri-tui.md、TUI 与 Rust 规范 |
peri-tui/src/kit/ |
| E2E | docs/standards/testing.md |
e2e/ |
loader 不会自动继承父目录规则；进入某个模块前，按任务显式读取对应的 docs/code-index/ 与 docs/standards/ 文档。
事实优先级
当文档和实现不一致时，按以下顺序判断：
- 代码与契约测试
docs/standards/- 模块
CLAUDE.md docs/design/- active spec
- 历史记录
历史 issue 能解释一个设计为什么出现，不能覆盖当前代码。设计文档可能同时包含目标状态和已实现基线，引用前要确认它的状态说明。
跨层改动检查
修改以下对象前，先读 docs/standards/architecture-contracts.md：
- ACP 边界和序列化格式
- frozen prompt 与项目指引加载
- Agent 事件链和终止语义
- 工具 direct/deferred 可见性
- 中间件生产顺序
- cancel、keepgoing 和会话生命周期
- 配置、日志、错误和遥测中的 secret
跨层事件变更通常至少涉及 Agent 发射、协议映射、ACP 转发和 TUI 消费。只修改枚举或单个 handler，不构成完整实现。
常用验证
# 先跑受影响 crate 的目标测试
cargo test -p peri-agent --lib <test_name>
cargo test -p peri-acp --lib mapper
cargo test -p peri-middlewares --lib <test_name>
cargo test -p peri-tui --lib <test_name>
# 文档注释和全局质量门
cargo test --workspace --doc
cargo clippy --workspace --all-targets -- -D warnings
lefthook run pre-commit目标测试应先于全 workspace 测试。测试命令证明的范围要与结论一致：mapper 测试能证明映射分支，不会自动证明 TUI 已正确消费。