架构全景

agentprof 是一个 5 crate 的 Rust workspace（core / adapters / storage / tui / cli，外加构建辅助 xtask）。 agentprof-core 是依赖图的叶子（零 workspace 依赖），agentprof-cli 是唯一组装层（依赖所有其他 crate）。 项目级关键决策由 25 份 ADR 锁定，连同 L1/L2/L3 三级文档体系一起，构成「读了 30 分钟就能动手贡献」的知识地基。

5 个 crate 的角色与依赖

记一句话：core 在最底下，cli 在最上面，中间没有循环。

👇 三张卡片分别讲：① 依赖图与无环规则 · ② L1/L2/L3 三级文档体系 · ③ 25 份 ADR 索引。每张都给「为什么 / agentprof 怎么做 / 其他选择」。

1 5-crate 依赖图 + 无环规则 点击展开

🗺️ 依赖图

图：5 crate 依赖关系。cli 在顶层，依赖所有其他 crate；tui / adapters / storage 在中间层，只依赖 core；core 是叶子。实际 SVG 在 T19 渲染落盘。

agentprof-cli  ──▶  agentprof-tui
       │                │
       ├──────────────▶ agentprof-adapters ──▶ agentprof-core
       │                                          ▲
       └──▶ agentprof-storage ───────────────────┘

🤔 为什么这样切

三条硬规则：① core 必须是叶子 — 它绝不能 use agentprof_adapters::... 或任何 workspace crate，这样核心数据模型可以独立单元测试、独立发版、独立 reuse；② cli 是唯一组装层 — 所有子命令逻辑只能放 agentprof-cli，不允许 lib crate 依赖它，保持 lib / bin 边界；③ 依赖图无环 — lib crate 之间不能有 cycle。

✅ agentprof 怎么做

CI 用 cargo metadata + grep 校验无环。workspace [lints] 段统一开 clippy::missing_docs_in_private_items、clippy::unwrap_used = "deny" 等，配合 docs/architecture.md §3「Crate 边界」与 .github/copilot-instructions.md §3 的硬规则。

🔀 其他选择

mono-crate（所有代码塞一个 lib）— 上手最简单，但难做单元测试和分层；10+ 微 crate — 边界更清晰但编译期、维护成本大幅上升。5 crate workspace 是 Rust 生态在中型 CLI 工具上的标准做法（参考 cargo / rust-analyzer 自己的拆分）。

9 阶段 pipeline 一览

对外开发流程也用同一套约束 — 见 .github/copilot-instructions.md §5。九个 stage 每个挂一个主 skill：

★ = project skill（.github/skills/，跟随 clone）；其余 = obra/superpowers 全局 plugin。Stage 5 / 6 是横切层，可在主线任意点切入；完成后回原 stage。

下一步

本课给出了 5 crate 是什么、依赖怎么排、文档怎么分层、决策怎么记。接下来的 Wiki 课会逐 crate 深入 — 下一课「agentprof-core 深度解读」拆解 data model、analyzer、tokenizer 的内部结构。

📂 相关源码： agentprof-cli/main.rs  Cli

📂 相关源码： agentprof-core/lib.rs  agentprof_core