analyze-agent-codebase

# Agent 代码库分析 从真实入口、调用链、状态变化和持久化边界还原系统如何运行。文档用于解释设计意图，但架构结论必须回到可执行代码和测试证据。 ## 分析边界 - 先遵守目标仓库的 `AGENTS.md`、`CLAUDE.md`、文档导航和只读规则。 - 默认只读。只有用户明确要求创建或维护分析文档时才写文件，不顺手修改实现。 - 以源码、依赖装配、配置、schema、migration 和测试为实现证据。 - 每个重要结论标为 `已确认`、`推断` 或 `未知`；推断说明依据，未知不凭常见框架行为补齐。 - 重要结论给出代码位置和相关 symbol；跨模块行为给出入口到副作用的调用链。 - 不因名称中出现 `agent`、`memory`、`plan`、`tool` 或 `middleware` 就认定对应能力存在。 - 使用用户要求的语言；未指定时沿用用户输入语言。 ## 选择分析范围 根据用户目标选择最小充分范围： 1. **定向机制问题**：只追踪回答该问题所需的纵向切片。 2. **代码库架构报告**：覆盖用户指定的多个机制，并形成整体运行时图景。 3. **专题文档集**：用户明确要求沉淀多篇文档或完整分析时，读取 [分析轴与专题文档](references/dossier-structure.md)。 如果仓库已有同类分析，先检查其范围、依据和版本；更新正确归宿，不建立重复总览。 ## 工作流 ### 1. 固定范围 记录： - 仓库根目录和可用的 revision； - 用户关心的问题、排除项和交付形式； - 主要语言、构建入口和生成代码目录； - 开始时的工作区状态。 区分生产源码、测试、生成物、vendor、fixture、示例和历史文档，不把测试夹具或示例当作生产路径。 ### 2. 建立运行时骨架 先从真实入口向内追踪： ```text 入口 → 配置与依赖装配 → Agent 或工作流构造 → 执行与调度循环 → 模型、工具、协作和持久化副作用 → 事件、恢复和展示 ``` 优先寻找 binary/package 入口、路由注册、factory、registry、核心状态类型和持久化边界。动态注册系统继续追到加载器、宏、装饰器或配置解析器，直到能够解释具体实现如何进入运行时。 ### 3. 追踪纵向切片 为每个问题选择一个真实触发场景，沿调用链追到： ```text 输入 → 权限与校验 → 状态转换 → 外部副作用 → 结果 → 错误与恢复 ``` 完整分析时，从 reference 中选择代码里真实存在的分析轴，不为了填满清单虚构子系统。 ### 4. 建立证据表 边读边记录，不在最后凭印象补引用： | 结论 | 状态 | 代码证据 | 测试或运行证据 | 限制或反证 | | --- | --- | --- | --- | --- | | `<可证伪的完整句子>` | 已确认 / 推断 / 未知 | `<path:line + symbol 或调用链>` | `<test / fixture / trace>` | `<冲突、动态边界或缺口>` | 证据必须支持完整结论。例如认定“支持子 Agent”时，应说明谁创建、如何传递上下文、隔离边界在哪里，以及结果如何返回调用者。 ### 5. 形成架构判断 从证据中说明： - 哪一层拥有控制权和状态真源； - 主要同步与异步流程如何连接； - 上下文、会话恢复、长期记忆和业务历史分别由谁...