Module analyzer

中文模块分析器

概览

使用本技能从真实代码出发，分析指定模块的功能、职责边界、调用链、依赖关系、数据/状态流、关键代码和风险点，并输出中文 Markdown 文档与 Mermaid 图。优先依据源码、测试、配置、路由注册、生成代码和项目文档，不用猜测替代证据。

写入文档前，先读取：

• references/source-reading-practices.md：按源码阅读实践建立阅读路线，尤其是入口、抽象、粘合层、主流程、实现细节和验证。
• references/output-contract.md：按输出契约组织文件、图表、关键流程、关键代码和源码引用。

输入识别

从用户请求或仓库上下文中解析：

• 目标模块：路径、包名、功能名、路由、服务、页面、组件族、类族或 API。
• 输出位置：用户指定时遵循指定目录；未指定时优先使用仓库已有文档区或模块附近合理目录，并说明假设。若无明显位置，先询问一次。
• 分析边界：纳入直接相关的调用方、被调用方、配置、测试、文档和生成代码；避免无必要地扩展到整个仓库。
• 输出语言：正文使用中文；代码标识、文件路径、命令、Mermaid node id 保持原样或 ASCII 友好。

工作流

1. 读取本地协作规则和技能 references。

   • 从仓库根目录到目标目录逐级检查 AGENTS.md。
   • 若规则冲突，遵循距离目标文件最近的规则。
   • 读取 references/source-reading-practices.md 和 references/output-contract.md，按目标复杂度裁剪输出，但不要省略关键流程和关键代码。

2. 建立阅读前提和入口地图。

   • 先确认目标模块的用户可见功能、配置项、运行方式、相关 README/设计文档/测试文档。
   • 使用 rg --files、rg、manifest、配置文件和路由文件识别入口、公开 API、命令、导出函数/类、页面、组件、测试和相关文档。
   • 前端模块重点检查路由、状态、hooks/components、API client、生成类型和测试。
   • 后端模块重点检查路由注册、schema/model、service、repository、依赖注入、任务队列、持久化和测试。
   • 输出前在 00-index.md 中按职责分组列出已读源码，不机械罗列无关文件。

3. 分层阅读模块结构。

   • 先读抽象定义：类型、schema、DTO、实体、接口、公开导出和领域对象关系。
   • 再读粘合层：middleware、hook、callback、async/Promise 编排、依赖注入、adapter、生成 client、框架注册点。
   • 最后读实现层：业务逻辑、控制逻辑、错误处理、数据转换、核心算法、副作用和底层交互。

4. 追踪关键执行路径。

   • 从用户可见或外部可调用入口开始。
   • 先追踪正常主路径，再追踪重要错误分支、提前返回、权限/校验失败、重试、降级和异步边界。
   • 沿验证、编排、数据访问、状态变化、副作用和返回结果向下追踪。
   • 每条关键流程先用简洁准确的中文说明触发条件、调用链、数据变化、外部副作用、错误分支和返回结果，再配 Mermaid 图辅助理解。
   • 明确区分“源码已确认”和“基于上下文推断”；不确定处写成待确认。

5. 提炼关键代码。

   • 选择真正影响理解或维护的代码：入口分发、核心编排、领域规则、状态迁移、数据映射、关键算法、错误处理、副作用封装。
   • 每段关键代码都附仓库相对路径和行号，并解释“为什么关键”“它承担什么决策或转换”“改动它会影响什么”。
   • 避免贴大段源码；优先摘录短片段或用伪代码概括，再给精确源码引用。

6. 梳理依赖和边界。

   • 按职责分组文件，不机械罗列所有文件。
   • 标出上游调用者、下游依赖、共享工具、生成代码、外部服务、存储、缓存、队列和配置。
   • 记录循环依赖、隐藏耦合、职责重叠或边界异常，仅在它们影响理解或维护时展开。

7. 生成中文文档。

   • 按 references/output-contract.md 的文件集合输出。
   • 关键结论尽量附仓库相对路径和行号，例如 frontend/src/example.ts:42。
   • 使用 Mermaid 展示架构、时序、依赖和数据/状态流。

8. 自检后交付。

   • 检查 Markdown 标题、Mermaid fence、图表标签、源码引用、占位内容和不确定声明。
   • 确认图表与文字互相一致。
   • 仅在仓库已有便宜的文档检查命令时运行。

Mermaid 约束

• 架构与依赖视图优先使用 flowchart LR 或 flowchart TD。
• 时间顺序清晰的调用链使用 sequenceDiagram。
• 类/类型关系是核心时使用 classDiagram；否则用 flowchart。
• Mermaid node id 使用简单 ASCII，例如 Entry、Service、ApiClient。
• 标签包含中文、空格、标点、斜杠或括号时加引号。
• 图过密时拆成多个小图，不输出难以阅读的大图。

质量标准

• 只记录代码实际行为，不把意图当事实。
• 不确定结论要显式标注来源和待确认点。
• 关键流程解析不能只给 Mermaid 图或只写摘要；要先用简洁准确的语言讲清入口、主路径、分支、数据变化、副作用和返回，再用图辅助表达。
• 关键代码不能只列文件；要解释承担的职责、决策点和改动影响。
• 文档要服务于新成员理解、调试和改动该模块。
• 生成文档中的路径使用仓库相对路径，不写机器相关绝对路径，除非用户明确要求。