analyze-agent-codebase

Agent 代码库分析

从真实入口、调用链、状态变化和持久化边界还原系统如何运行。文档用于解释设计意图，但架构结论必须回到可执行代码和测试证据。

分析边界

• 先遵守目标仓库的 AGENTS.md、CLAUDE.md、文档导航和只读规则。
• 默认只读。只有用户明确要求创建或维护分析文档时才写文件，不顺手修改实现。
• 以源码、依赖装配、配置、schema、migration 和测试为实现证据。
• 每个重要结论标为 已确认、推断 或 未知；推断说明依据，未知不凭常见框架行为补齐。
• 重要结论给出代码位置和相关 symbol；跨模块行为给出入口到副作用的调用链。
• 不因名称中出现 agent、memory、plan、tool 或 middleware 就认定对应能力存在。
• 使用用户要求的语言；未指定时沿用用户输入语言。

选择分析范围

根据用户目标选择最小充分范围：

1. 定向机制问题：只追踪回答该问题所需的纵向切片。
2. 代码库架构报告：覆盖用户指定的多个机制，并形成整体运行时图景。
3. 专题文档集：用户明确要求沉淀多篇文档或完整分析时，读取 分析轴与专题文档。

如果仓库已有同类分析，先检查其范围、依据和版本；更新正确归宿，不建立重复总览。

工作流

1. 固定范围

记录：

• 仓库根目录和可用的 revision；
• 用户关心的问题、排除项和交付形式；
• 主要语言、构建入口和生成代码目录；
• 开始时的工作区状态。

区分生产源码、测试、生成物、vendor、fixture、示例和历史文档，不把测试夹具或示例当作生产路径。

2. 建立运行时骨架

先从真实入口向内追踪：

入口
  → 配置与依赖装配
  → Agent 或工作流构造
  → 执行与调度循环
  → 模型、工具、协作和持久化副作用
  → 事件、恢复和展示

优先寻找 binary/package 入口、路由注册、factory、registry、核心状态类型和持久化边界。动态注册系统继续追到加载器、宏、装饰器或配置解析器，直到能够解释具体实现如何进入运行时。

3. 追踪纵向切片

为每个问题选择一个真实触发场景，沿调用链追到：

输入 → 权限与校验 → 状态转换 → 外部副作用 → 结果 → 错误与恢复

完整分析时，从 reference 中选择代码里真实存在的分析轴，不为了填满清单虚构子系统。

4. 建立证据表

边读边记录，不在最后凭印象补引用：

结论	状态	代码证据	测试或运行证据	限制或反证
<可证伪的完整句子>	已确认 / 推断 / 未知	<path:line + symbol 或调用链>	<test / fixture / trace>	<冲突、动态边界或缺口>

证据必须支持完整结论。例如认定“支持子 Agent”时，应说明谁创建、如何传递上下文、隔离边界在哪里，以及结果如何返回调用者。

5. 形成架构判断

从证据中说明：

• 哪一层拥有控制权和状态真源；
• 主要同步与异步流程如何连接；
• 上下文、会话恢复、长期记忆和业务历史分别由谁负责；
• Tool、Skill、prompt 和 permission 如何连接但保持职责分离；
• 错误、重试、取消、幂等和恢复边界到哪里为止；
• 文档主张与生产实现有哪些一致、漂移或尚未接通之处。

详细分类判据由 reference 负责。

6. 交叉验证

• 用测试、fixture、schema 或可执行路径核对关键调用链。
• 对关键 symbol 做反向引用，确认它进入生产装配而不是孤立实现。
• 检查 feature flag、平台分支、adapter 和替代入口，避免把一个实现概括成全系统行为。
• 测试只证明实际覆盖的行为；没有运行的验证明确标为 not_run。
• 用户没有禁止读取文档时，对照权威文档并记录代码—文档漂移。

7. 交付

先给结论和系统图景，再给证据与限制。通常包含：

• 分析范围、revision 和排除项；
• 运行时拓扑与关键端到端流程；
• 用户点名机制的结论和证据状态；
• 主要设计取舍、真实约束和代码—文档漂移；
• 高价值未知项及继续验证方式；
• 代码位置或专题文档阅读顺序。

不要大段复制源码或已有文档。引用最小必要片段，并以路径、symbol 和解释为主。