aszerW
c3ea38c045
- 添加 5 个用户级别 Skills: - auto-commit: 自动 Git 提交 - karpathy-guidelines: 编码规范指南 - opencli-websearch: 多源网络搜索 - pdf-reader: PDF 内容提取 - repo-analyzer: 项目深度分析 - 添加 Playwright MCP 配置 (21 个浏览器自动化工具) - 创建完整的 README.md 文档说明
151 lines
7.5 KiB
Markdown
151 lines
7.5 KiB
Markdown
# 模块分析指南
|
||
|
||
## 核心方法
|
||
|
||
按业务功能划分模块，不按文件或目录。一个逻辑模块可能跨越多个文件，一个文件也可能包含多个模块的部分实现。
|
||
|
||
分析深度标准：**交给另一个 AI 能仅凭报告复现系统的设计**。读者能理解模块的设计思路、职责边界、与其他模块的协作方式，并能参与架构讨论。
|
||
|
||
## 全局视角要求
|
||
|
||
**每个模块的分析都必须回答两个全局问题：**
|
||
|
||
1. **在整个项目中的角色**：这个模块为什么存在？去掉它系统会怎样？它服务于项目的哪个核心目标？
|
||
2. **与其他模块的设计协同**：它和其他模块之间的契约是什么？这种协作模式是否与项目整体的设计哲学一致？
|
||
|
||
孤立地分析模块是最常见的错误。一个模块的设计选择往往是被其他模块的约束所驱动的——不理解这些约束，就无法理解设计动机。
|
||
|
||
## 模块分析完整性四要素
|
||
|
||
每个核心模块的分析必须覆盖以下四个要素，缺任何一项都不算完整：
|
||
|
||
1. **核心数据结构** — 贴关键接口/类型定义（不是全部，只贴理解设计必需的）
|
||
2. **执行流程** — 用文字或 Mermaid 时序图描述调用链，标注源文件路径和行号
|
||
3. **设计决策** — 为什么选这个方案，不选另一个，权衡了什么
|
||
4. **模块间依赖** — 谁调用谁，数据怎么流转，共享了什么状态
|
||
|
||
检验标准：如果另一个 AI 只读你的分析（不看源码），能否画出这个模块的架构图并解释它的工作原理？如果不能，说明缺了某个要素。
|
||
|
||
必须包含：业务问题、设计思路和架构模式、核心流程（Mermaid 图）、协作关系、设计权衡。
|
||
不需要包含：完整类型定义、所有函数签名、所有参数列表、错误枚举逐项说明。
|
||
|
||
## 模块识别方法
|
||
|
||
1. **业务功能角度** — 项目提供哪些核心业务能力？
|
||
2. **数据流角度** — 数据从输入到输出经过哪些转换阶段？
|
||
3. **职责角度** — 业务需求变化时，哪些代码需要一起改？
|
||
|
||
## 分析深度
|
||
|
||
- **核心模块**（创新点、架构关键组件）：设计思路讲透、核心流程有图有解读、设计决策解释权衡、协作关系画清楚
|
||
- **次要模块**（工具函数、标准封装）：一句话职责 + 文件路径 + 特别之处
|
||
|
||
## Subagent 并行分析
|
||
|
||
阶段 6 必须使用 Agent 工具为每个核心模块启动独立 subagent 并行分析。
|
||
|
||
调度策略：
|
||
- 每个核心模块 → 一个独立 Agent subagent（`subagent_type: "general-purpose"`）
|
||
- 所有次要模块 → 合并到一个 Agent subagent 批量处理
|
||
- 所有 subagent 在同一消息中并行启动
|
||
|
||
### 核心模块 Subagent Prompt 模板
|
||
|
||
```
|
||
你是一位资深架构师，正在对 {项目名} 的「{模块名}」模块进行深度分析。
|
||
|
||
## 背景信息
|
||
- 项目定位: {一句话描述}
|
||
- 整体架构: {简述架构风格和核心设计}
|
||
- 项目设计哲学: {贯穿项目的核心设计理念}
|
||
- 该模块在系统中的位置: {与其他模块的关系}
|
||
- 叙事上下文: {该模块在报告叙事线中的位置——前一个模块讲了什么、读者带着什么问题进入本模块、本模块需要为下一个模块铺垫什么}
|
||
|
||
## 需要分析的文件
|
||
{文件路径列表}
|
||
|
||
## 分析结构
|
||
用自然语言描述设计意图，默认不暴露函数名/参数名/类型定义，只有设计特别精妙时才附代码片段。
|
||
|
||
1. 在项目中的角色 — 这个模块为什么存在？去掉它系统会怎样？
|
||
2. 解决什么问题 — 业务背景，没有它系统会怎样
|
||
3. 设计思路 — 方案及理由、放弃的替代方案、核心设计模式
|
||
4. 核心数据结构 — 贴理解设计必需的关键接口/类型定义（不是全部）
|
||
5. 核心业务流程 — Mermaid 流程图 + 自然语言解读，标注源文件路径和行号
|
||
6. 与其他模块的设计协同 — 依赖谁、谁依赖它、协作方式、共享状态、这种协作模式是否与项目整体设计哲学一致。跨模块结论用【待主 agent 验证】标注
|
||
7. 关键设计决策 — 1-3 个最重要的决策及权衡（为什么选这个方案，替代方案的代价）
|
||
8. Deep Research 洞察 — 替代方案代价、业界对比、如果重新设计
|
||
9. 扩展点（如适用）
|
||
10. 亮点与问题 — 涉及文件列表
|
||
|
||
## 全局视角要求
|
||
你的分析必须将模块放在项目整体语境中——设计选择如何服务整体哲学、边界为何这样划、变化会如何影响其他模块。（详见文件头部"全局视角要求"）
|
||
|
||
## 相关探索问题
|
||
{问题列表}
|
||
将答案融入各节中。
|
||
|
||
## 写入策略
|
||
对于大模块（文件总行数 > 5000 行），必须增量写入草稿：
|
||
- 每完成一个子系统/子模块的分析后，立即将该部分写入草稿文件
|
||
- 第一个子系统用 Write 创建文件，后续子系统用 Edit 追加
|
||
- 不要等全部文件读完再一次性写入
|
||
- 覆盖率明细表在最后追加
|
||
|
||
## 输出
|
||
写入 {work_dir}/drafts/06-module-{模块名}.md，单次写入不超过 300 行。
|
||
|
||
## 覆盖率要求
|
||
当前分析模式: {分析模式}，核心模块最低覆盖率: {最低覆盖率}%。
|
||
草稿末尾必须附覆盖率明细表（格式：文件名 | 总行数 | 已读行数 | 覆盖率% | 未读原因），最后一行为合计行并标注达标✅/未达标❌。
|
||
「已读」指通过 Read 工具实际读取过的行。覆盖率未达标时必须继续阅读直到达标。
|
||
```
|
||
|
||
### 次要模块批量 Prompt 模板
|
||
|
||
```
|
||
你是一位资深架构师，正在对 {项目名} 的次要模块进行批量分析。
|
||
|
||
## 背景信息
|
||
- 项目定位: {一句话描述}
|
||
- 整体架构: {简述}
|
||
- 项目设计哲学: {贯穿项目的核心设计理念}
|
||
|
||
## 需要分析的次要模块
|
||
{模块列表：名称、职责假设、文件范围}
|
||
|
||
## 每个模块输出
|
||
1. 职责（一句话）
|
||
2. 在项目整体中的角色（一句话）
|
||
3. 实现方式（一句话）
|
||
4. 如有特别之处，展开说明
|
||
5. 涉及文件列表
|
||
|
||
写入 {work_dir}/drafts/06-module-secondary.md
|
||
|
||
## 覆盖率要求
|
||
当前分析模式: {分析模式}，次要模块最低覆盖率: {最低覆盖率}%。
|
||
草稿末尾必须附覆盖率明细表（格式：文件名 | 总行数 | 已读行数 | 覆盖率% | 未读原因），最后一行为合计行并标注达标✅/未达标❌。
|
||
「已读」指通过 Read 工具实际读取过的行。覆盖率未达标时必须继续阅读直到达标。
|
||
```
|
||
|
||
### Subagent 协作规范
|
||
|
||
- **只分析分配的文件**，不越界
|
||
- **跨模块推断用【待主 agent 验证】标注**，主 agent 在阶段 7 交叉验证
|
||
- **深度优先于广度**，宁可把一个核心流程讲透
|
||
- **全局视角**，将模块放在项目整体语境中分析，解释设计选择如何服务于项目整体
|
||
- **叙事衔接**，草稿开头用 1-2 句说明本模块与前一个模块的关系，草稿结尾用 1 句铺垫下一个模块
|
||
|
||
## 质量检查
|
||
|
||
- [ ] 模块按业务功能划分，不是按文件/目录
|
||
- [ ] 每个模块解释了"在项目中的角色"和"为什么这样设计"
|
||
- [ ] 四要素完整：核心数据结构、执行流程（含文件路径行号）、设计决策、模块间依赖
|
||
- [ ] 核心流程用 Mermaid 图展示
|
||
- [ ] 关键接口/类型定义已贴出（只贴理解设计必需的）
|
||
- [ ] 没有暴露不必要的函数名、参数名、类型定义
|
||
- [ ] 协作关系清晰，共享状态已标注
|
||
- [ ] 每个模块的分析都连接到了项目整体设计哲学
|
||
- [ ] 检验：另一个 AI 只读分析（不看源码）能画出模块架构图
|