feat(repo): 整理 Qoder Skills 和 MCP 配置到仓库
- 添加 5 个用户级别 Skills: - auto-commit: 自动 Git 提交 - karpathy-guidelines: 编码规范指南 - opencli-websearch: 多源网络搜索 - pdf-reader: PDF 内容提取 - repo-analyzer: 项目深度分析 - 添加 Playwright MCP 配置 (21 个浏览器自动化工具) - 创建完整的 README.md 文档说明
This commit is contained in:
274
skills/repo-analyzer/SKILL.md
Normal file
274
skills/repo-analyzer/SKILL.md
Normal file
@@ -0,0 +1,274 @@
|
||||
---
|
||||
name: repo-analyzer
|
||||
description: Use when the user mentions "分析项目"、"分析仓库"、"分析 GitHub"、"项目分析"、"源码分析"、"架构分析"、"代码分析"、"学习这个项目"、"研究这个框架"、"看看这个库怎么实现的"、"对比两个项目"、"项目评测"、"框架评测"
|
||||
---
|
||||
|
||||
# Git 项目深度分析技能
|
||||
|
||||
深度分析开源项目并生成专业架构报告。报告是有深度洞察的技术研究，读完后读者能理解业务问题、掌握架构设计、产生自己的思考。
|
||||
|
||||
## When to Use
|
||||
|
||||
- 分析开源项目的架构和设计
|
||||
- 对比两个同类项目的设计差异
|
||||
- 深入研究一个框架或库的实现思路
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- 简单的代码问题或调试
|
||||
- 单文件分析或代码审查
|
||||
- 不涉及架构层面的代码修改
|
||||
|
||||
## 输出语言
|
||||
|
||||
默认中文。如果用户使用其他语言提问，则跟随用户语言。
|
||||
|
||||
## 核心原则
|
||||
|
||||
### 1. 业务视角优先
|
||||
|
||||
从"这个项目解决什么问题"出发，不是"这个文件里有什么函数"。
|
||||
|
||||
| 不要 | 要 |
|
||||
|------|-----|
|
||||
| `handleRequest(ctx)` 函数接收一个 Context 参数... | 请求进来后，系统会经过鉴权、限流、路由分发三个阶段... |
|
||||
| `interface MessageQueue { push(); pop() }` | 模块间通过消息队列解耦，生产者只管投递，消费者按优先级拉取 |
|
||||
|
||||
### 2. 抽象层次把控：不贴代码，讲设计
|
||||
|
||||
默认在设计模式和架构层面描述，**非必要情况下不贴原始代码**。重点突出流程、逻辑、设计思想，用架构图（Mermaid）、流程图、表格来表达，而非代码片段。只有设计特别精妙、项目自创独特概念、或实现是核心卖点时才展示代码，且必须先用自然语言解释。
|
||||
|
||||
### 3. 全局关联
|
||||
|
||||
每个局部分析都必须连接到项目整体设计哲学——这是区分"代码说明书"和"架构分析"的关键。详见 [analysis-guide.md](references/analysis-guide.md) 的全局关联章节。
|
||||
|
||||
### 4. 启发性写作
|
||||
|
||||
目标是让读者**学到东西、产生思考**，而不是获得一份代码说明书。像资深工程师在白板前讲解——有观点、有推理、有对比。详见 [analysis-guide.md](references/analysis-guide.md) 的启发性写作章节。
|
||||
|
||||
### 5. 深度洞察：Why > What（强制）
|
||||
|
||||
每个设计决策必须解释动机、权衡、替代方案代价。描述"是什么"只是起点，解释"为什么"才是分析的价值所在。每个核心模块和整体架构都要回答：
|
||||
- **为什么这样设计？** 不只是"用了什么模式"，而是"为什么适合这个场景"
|
||||
- **如果不这样会怎样？** 替代方案的代价
|
||||
- **与业界最佳实践的差距？** 领先之处和改进空间
|
||||
- **如果让你重新设计？** 展示更深层理解
|
||||
- **系统性设计哲学？** 贯穿整个项目的风格（如"约定优于配置"、"零成本抽象"）
|
||||
|
||||
示例：
|
||||
> ❌ 路由系统采用了中间件模式，支持链式调用。
|
||||
>
|
||||
> ✅ 路由系统选择了洋葱模型而非线性管道。线性管道实现更简单，但洋葱模型让每个中间件都能同时处理请求和响应阶段——这对日志、计时、错误恢复至关重要。Express 当年选择线性模型，后来不得不用各种 hack 处理响应后逻辑，Koa 吸取教训才转向洋葱模型。如果让我重新设计，我会考虑加入中间件依赖声明，让框架自动排序——这是 Fastify 的做法，能避免顺序导致的隐蔽 bug。
|
||||
|
||||
### 补充要求
|
||||
|
||||
- **代码为准** — 一切结论有代码依据，标注 `文件路径` 或 `文件路径:行号范围`，禁止模糊表述
|
||||
- **有温度** — 像资深工程师给新同事做 onboarding，加入主观评价和建议，避免 AI 味套话
|
||||
- **重点深入次要简略** — 核心创新点深入分析，通用工具函数一句话带过
|
||||
- **批判性思考** — 与业界实践对比，指出真实问题，不回避缺陷。参考 [analysis-guide.md](references/analysis-guide.md)
|
||||
- **行文流畅易懂** — 整体行文需要流畅自然，让入门的工程师也能看懂并学习到东西。避免过于学术化或堆砌术语
|
||||
- **拒绝流水账** — 每个模块要体现深度细节，不能一句带过或泛泛而谈。每个模块如果合适要加上对应的 Mermaid 架构图，让读者看完有启发、能学到设计精髓
|
||||
|
||||
## 分析工作流
|
||||
|
||||
**灵活性原则**：以下所有阶段和章节都是建议性的指引，不是必须严格执行的清单。agent 应根据当前分析的项目特性动态决策——如果某个阶段或环节对当前项目没有意义，可以跳过或简化。一切以最终报告的质量为准。
|
||||
|
||||
### 阶段 1: 项目获取与初始化
|
||||
|
||||
1. 解析用户输入（支持 `owner/repo`、GitHub/GitLab/Gitee URL、本地路径、项目名称）
|
||||
2. 创建工作区：在用户主目录下创建 `repo-analyses/${REPO_NAME}-{YYYYMMDD}` 目录作为 `$WORK_DIR`（跨平台：macOS/Linux 使用 `$HOME`，Windows 使用 `$USERPROFILE` 或 `$HOME`）
|
||||
3. 如果用户提供本地路径则跳过 clone，否则 `git clone --depth=1` 克隆仓库
|
||||
4. 获取基本元数据（Star、Fork、贡献者、代码统计）
|
||||
|
||||
### 阶段 2: 项目规模评估与分析模式选择
|
||||
|
||||
1. **统计有效代码行数**（排除可跳过代码），按模块列出分布
|
||||
- 可跳过代码定义：测试代码、构建/部署配置（Dockerfile、CI yaml 等）、自动生成代码（protobuf 生成、lock 文件等）、示例/文档代码
|
||||
- 使用 `find` + `wc -l` 或 `cloc` 等工具统计，按顶层目录分组
|
||||
2. **向用户报告代码规模**，使用 AskUserQuestion 让用户选择分析模式：
|
||||
|
||||
| 模式 | 核心模块覆盖率 | 次要模块覆盖率 | 适用场景 |
|
||||
|------|-------------|-------------|---------|
|
||||
| 快速分析 | ≥30% | ≥10% | 快速了解项目全貌 |
|
||||
| 标准分析（推荐） | ≥60% | ≥30% | 常规架构分析 |
|
||||
| 深度分析 | ≥90% | ≥60% | 深入研究每个设计决策 |
|
||||
|
||||
3. 将代码规模统计和用户选择的分析模式写入 `drafts/03-plan.md`，后续阶段据此控制分析深度
|
||||
|
||||
**覆盖率计算规则**：
|
||||
- 覆盖率 = 通过 Read 工具实际请求过的行范围之并集 / 文件总行数
|
||||
- 对于大文件（>500 行），必须分段读取，确保以下关键段落被覆盖：
|
||||
- 文件头部的类型定义和导入（前 100 行）
|
||||
- 核心业务逻辑函数（通过目录结构或函数名定位）
|
||||
- 文件尾部的测试代码（如有）
|
||||
- 只读了文件的一小部分（<30%）不计入覆盖率，视为「未读」
|
||||
- 自动生成代码（proto 生成、lock 文件等）可降低覆盖率要求：扫描结构即可，不需要逐行阅读
|
||||
|
||||
### 阶段 3: 外部调研 + 项目文档研读（先搜再读）
|
||||
|
||||
1. WebSearch 搜索项目评价、对比、架构讨论（至少 3-5 次搜索）
|
||||
2. **遍历项目官网**（如果存在）：
|
||||
- 从 README 或 GitHub 页面提取官网 URL
|
||||
- 使用 WebFetch/tavily_crawl 遍历官网关键页面（首页、Features、Use Cases、Comparison、Blog 等）
|
||||
- 重点提取：产品定位语（tagline）、典型使用场景、官方竞品对比、用户案例/testimonial
|
||||
- 官网内容往往是理解"为什么需要这个产品"的最佳来源，比代码和技术文档更直接
|
||||
3. **通读项目自带文档**：
|
||||
- 架构文档（`architecture/`、`docs/`、`design/` 等目录）
|
||||
- CONTRIBUTING.md、AGENTS.md 等开发者指引
|
||||
- RFC、ADR（Architecture Decision Records）、设计提案等
|
||||
- 这些文档往往包含开发者的设计思路、权衡取舍、历史决策背景，是理解"为什么这样设计"的第一手资料
|
||||
- 将文档中的关键设计决策和思路摘录到调研笔记中
|
||||
4. 整理调研发现写入 `drafts/03-research.md`，必须包含以下结构化段落（信息不足则标注"未找到"）：
|
||||
- **项目解决的核心问题**：用 1-3 个具体场景描述痛点（谁、在什么情况下、遇到什么问题、现有方案为什么不够）
|
||||
- **竞品/同类项目对比**：列出 3-5 个最相关的竞品，说明各自定位差异和技术路线差异
|
||||
- **为什么需要单独做这个项目**：不能用现有方案组合解决吗？这个项目的独特价值主张是什么？
|
||||
- **项目背后的组织动机**（如适用）：商业公司的战略考量、开源社区的生态定位
|
||||
5. 生成分析规划写入 `drafts/03-plan.md`
|
||||
|
||||
### 阶段 4: 项目特征识别 + 自适应提问
|
||||
|
||||
这是核心阶段。不使用固定问题列表，而是根据项目特征生成针对性问题。
|
||||
|
||||
**步骤：**
|
||||
|
||||
1. **快速扫描**：扫描入口文件、目录结构、依赖声明、项目文档、README
|
||||
2. **识别项目核心特征**：
|
||||
- 项目类型与定位（库/框架/应用/工具）
|
||||
- 规模与成熟度
|
||||
- 设计风格信号（类型体操、极简 API、配置驱动等）
|
||||
- 技术栈特点（新兴技术、多语言、特定运行时）
|
||||
- 社区定位（核心基础设施、应用层工具、教学项目等）
|
||||
3. **从特征中提炼问题**：根据观察到的项目特征生成针对性问题。问题应该帮助聚焦分析方向，而不是走流程
|
||||
|
||||
**思维过程**——每个观察都可能暗示一个值得问用户的问题：
|
||||
- 观察到的技术选择 → 问动机（不常见的技术组合？自己实现了通常用第三方库解决的功能？）
|
||||
- 观察到的架构特征 → 问优先级（性能优化痕迹？复杂的插件/扩展系统？）
|
||||
- 观察到的设计张力 → 问取舍（简单性 vs 灵活性？向后兼容的包袱？）
|
||||
- 观察到的项目定位 → 问受众（目标用户是谁？在生态中是替代还是填补空白？）
|
||||
|
||||
**维度启发**——什么样的项目特征暗示什么样的分析角度：
|
||||
- 小而精的库 → API 设计哲学、边界划定；大型框架 → 模块化策略、向后兼容、生态治理
|
||||
- 使用新兴技术 → 为什么选择它、迁移成本；多语言/多范式 → 语言边界设计
|
||||
- 大量泛型/类型体操 → 类型安全 vs 复杂度权衡；极简 API → 简单性如何实现、牺牲了什么
|
||||
|
||||
**好问题的特征**：具体（基于代码中观察到的现象）、有分析价值（答案会影响分析方向）、用户能答（问关注点和偏好，不问需要深入代码才能回答的技术细节）、不重复（不问通过代码就能回答的问题）
|
||||
4. **向用户提问**：使用 AskUserQuestion 工具向用户提问，每次不超过 3 个问题
|
||||
- 其中一个问题应确认**报告开头的详略程度**：对于知名项目，用户可能不需要冗长的产品介绍和竞品对比，只想直接进入代码分析。询问用户是否需要场景化引入和竞品定位章节，还是直接从项目全景和代码分析开始
|
||||
5. **不限轮次**：可多轮提问直到方向明确，分析过程中发现新的关键分歧点可以再追问
|
||||
|
||||
**关键原则**：问题完全由项目特征驱动，不预设类别。不同项目应该产生完全不同的问题。
|
||||
|
||||
### 阶段 5: 动态报告结构设计
|
||||
|
||||
根据用户回答 + 项目特征，设计本次报告的章节结构。
|
||||
|
||||
**步骤：**
|
||||
|
||||
1. **综合信息**：结合阶段 3 的调研、阶段 4 的项目特征和用户回答
|
||||
2. **设计章节结构**：不使用固定模板，但必须满足骨架约束（见下方）
|
||||
3. **输出报告大纲**：将设计好的报告大纲输出给用户确认后再继续
|
||||
4. **识别模块**：追踪核心数据流，识别 N 个逻辑模块（按业务功能划分），分为核心模块和次要模块
|
||||
5. **设计模块叙事线**：确定模块在报告中的呈现顺序和过渡逻辑，不按目录结构排列，而是按读者理解的最佳路径组织：
|
||||
- 选择叙事主线：数据流驱动（请求从进入到离开经过哪些模块）、分层驱动（从底层到上层）、或问题驱动（从核心问题到解决方案逐层展开）
|
||||
- 每两个相邻模块之间写明过渡逻辑：上一个模块的输出/问题/局限 → 引出下一个模块的必要性
|
||||
- 将叙事线写入 `drafts/05-modules-plan.md`，格式示例：模块 A →[A 的输出需要 B 来消费]→ 模块 B →[B 解决了 X 但引出 Y 问题]→ 模块 C
|
||||
6. **写入计划**：输出模块清单和报告大纲写入 `drafts/05-modules-plan.md`
|
||||
|
||||
**骨架约束**（报告不规定具体章节，但必须满足）：
|
||||
- 有**场景化问题引入**（用具体场景讲清楚项目解决什么问题、现有方案的不足、为什么需要这个项目——素材来自阶段 3 调研笔记）。**注意**：如果用户在阶段 4 表示不需要冗长介绍（如项目已经很知名），可以精简或跳过此章节，直接从项目全景开始
|
||||
- 有**竞品定位**（与同类项目的关键差异，不是功能清单对比，而是设计哲学和技术路线的差异）。**注意**：同上，用户可选择跳过
|
||||
- 有**项目全景**（让读者快速理解项目是什么、解决什么问题）
|
||||
- 有**深度分析**（核心设计的 Why、权衡、与业界对比）
|
||||
- 有**评价与启发**（诚实的优缺点、读者能从中学到什么）
|
||||
- 有**架构可视化**（Mermaid 图表）
|
||||
- 所有结论有代码依据
|
||||
|
||||
### 阶段 6: 并行深度分析（subagent 团队）
|
||||
|
||||
必须使用 Agent 工具并行启动 subagent。参考 [module-analysis-guide.md](references/module-analysis-guide.md) 中的 prompt 模板和协作规范。
|
||||
|
||||
每个 subagent 的 prompt 中必须包含项目整体设计哲学和全局视角要求，确保模块分析不是孤立的。
|
||||
|
||||
每个 subagent 的 prompt 中还必须包含该模块的叙事上下文（来自阶段 5 的叙事线设计）：前一个模块讲了什么、读者带着什么问题进入本模块、本模块需要为下一个模块铺垫什么。subagent 应在草稿开头用 1-2 句衔接前一模块，草稿结尾用 1 句铺垫下一模块。
|
||||
|
||||
每个 subagent 的 prompt 末尾必须附加覆盖率要求（参考 module-analysis-guide.md 中的覆盖率要求段落），告知当前分析模式和最低覆盖率目标，要求草稿末尾附覆盖率明细表。
|
||||
|
||||
**subagent 写入策略**：
|
||||
对于大模块（文件总行数 > 5000 行），必须在 subagent prompt 中要求增量写入草稿：
|
||||
- 每完成一个子系统/子模块的分析后，立即将该部分写入草稿文件
|
||||
- 第一个子系统用 Write 创建文件，后续子系统用 Edit 追加
|
||||
- 不要等全部文件读完再一次性写入
|
||||
- 覆盖率明细表在最后追加
|
||||
|
||||
**主 agent 等待纪律**：
|
||||
- subagent 启动后，主 agent 不得阅读 subagent 负责的源码文件
|
||||
- 主 agent 在等待期间应专注于：阅读项目文档（architecture/、docs/）、外部调研、设计报告骨架、准备阶段 8 的融合框架
|
||||
- 判断 subagent 是否卡住的标准：output 文件超过 5 分钟无新增行。只有确认卡住后，主 agent 才可以接管该模块的分析
|
||||
- **严禁提前合并**：必须等所有 subagent 全部完成后，再开始阶段 7 和阶段 8 的合并工作。不要在部分 subagent 还在运行时就开始写最终报告
|
||||
|
||||
### 阶段 7: 交叉验证 + 质量管控（主 agent）
|
||||
|
||||
**7.1 覆盖率门控**：
|
||||
1. 读取每个 `drafts/06-module-*.md` 末尾的覆盖率明细表
|
||||
2. 快速检查：每个草稿末尾是否有覆盖率表、合计行是否标注达标（✅/❌）
|
||||
3. 只有标注 ❌ 或缺少覆盖率表的模块才需要深入检查
|
||||
4. 不达标模块 → 主 agent 自动补充阅读未覆盖的关键文件，将补充发现追加到对应草稿
|
||||
5. 补充后仍不达标 → 向用户报告哪些模块未达标及原因（如文件过大、二进制文件等）
|
||||
|
||||
**7.2 抽查验证**：
|
||||
1. 从每个核心模块草稿中选取 2-3 个关键结论
|
||||
2. 回到源码逐行验证结论准确性
|
||||
3. 发现偏差则修正草稿中的对应内容
|
||||
|
||||
**7.3 交叉验证**：
|
||||
1. 交叉验证【待主 agent 验证】标注的跨模块结论
|
||||
2. 综合回答探索问题，识别跨模块设计模式
|
||||
3. 验证全局关联：每个模块的分析是否都连接到了项目整体设计哲学
|
||||
4. 写入 `drafts/07-cross-validation.md`
|
||||
|
||||
### 阶段 8: 多源融合与最终报告（主 agent）
|
||||
|
||||
1. 提炼架构洞察和系统性设计哲学
|
||||
2. 基于阶段 3 调研结果深化竞品对比（仅在阶段 3 信息不足时补充搜索）
|
||||
3. 提出"如果重新设计"的改进建议
|
||||
4. 写入 `drafts/08-insights.md`
|
||||
5. **多源融合**：以阶段 5 设计的报告章节结构为骨架，从各草稿中抽取内容填充。同一概念在多个草稿中出现时，取最详细版本并补充其他版本独有信息。融合后消除所有"见草稿 X"、"详见附录"等跳转指示
|
||||
- **叙事连贯**：按阶段 5 设计的叙事线组织模块章节。每个模块章节的开头必须有 1-2 句过渡，连接上一个模块的结论或问题。避免"接下来我们分析 X 模块"这种生硬转折，改用自然过渡（如"Gateway 完成了请求的认证和路由，但它只负责'谁可以进来'，不负责'进来之后能做什么'。这个行为控制的职责，由策略引擎承担。"）
|
||||
6. **分段写入**：最终报告通常超过 500 行，先 Write 前几个章节（200-300 行），后续用 Edit 追加，每次追加前 Read 确认末尾位置
|
||||
7. **覆盖率汇总**：将覆盖率数据汇总写入 `drafts/08-coverage.md`（不放入最终报告）
|
||||
- 数据直接从各 subagent 草稿末尾的覆盖率明细表中提取，不需要主 agent 重新计算
|
||||
- 如果主 agent 在阶段 7 补充了阅读，将补充的行数加到对应模块的「已读行数」中
|
||||
- 汇总表格式：
|
||||
|
||||
| 模块 | 类型 | 文件数 | 有效代码行 | 已读行数 | 覆盖率 | 达标 |
|
||||
|------|------|--------|-----------|---------|--------|------|
|
||||
| ... | 核心/次要 | ... | ... | ... | ...% | ✅/❌ |
|
||||
|
||||
8. 汇总生成最终报告（不包含覆盖率章节）
|
||||
|
||||
### 草稿文件清单
|
||||
|
||||
所有中间过程保存到 `$WORK_DIR/drafts/`：
|
||||
|
||||
| 阶段 | 文件 |
|
||||
|------|------|
|
||||
| 3 | `03-research.md`, `03-plan.md` |
|
||||
| 5 | `05-modules-plan.md` |
|
||||
| 6 | `06-module-{name}.md`（subagent 生成） |
|
||||
| 7 | `07-cross-validation.md` |
|
||||
| 8 | `08-insights.md`, `08-coverage.md` |
|
||||
|
||||
文件写入分块，单次不超过 300 行或 15KB。
|
||||
|
||||
## 特殊场景
|
||||
|
||||
- **超大型项目（>50000 行）**：优先分析核心模块，使用 Agent 并行分析
|
||||
- **对比分析模式**：两个项目分别完成阶段 1-4，然后在阶段 5 设计对比式报告结构，骨架约束中增加"设计决策对比"和"选型建议"
|
||||
|
||||
## 输出要求
|
||||
|
||||
1. 最终报告为单一 markdown 文件：`$WORK_DIR/ANALYSIS_REPORT.md`
|
||||
2. 大量使用 Mermaid 图表展示架构、流程、数据流
|
||||
3. 面向需要理解业务架构的开发者
|
||||
4. 亮点和问题的评价思维框架参考 [analysis-guide.md](references/analysis-guide.md)
|
||||
5. 分析哲学和深度标准参考 [analysis-guide.md](references/analysis-guide.md)
|
||||
166
skills/repo-analyzer/references/analysis-guide.md
Normal file
166
skills/repo-analyzer/references/analysis-guide.md
Normal file
@@ -0,0 +1,166 @@
|
||||
# 分析哲学与思维框架
|
||||
|
||||
## 核心立场
|
||||
|
||||
分析的目标是让读者**学到东西、产生思考**，而不是获得一份代码说明书。好的分析像一位资深工程师在白板前讲解——有观点、有推理、有对比，读完后读者能参与架构讨论。
|
||||
|
||||
每个评价都需要：代码依据、对比基准、推理过程。"代码质量不错"不是评价，"项目在错误处理上采用了统一的 Result 类型而非异常，这让错误路径在类型层面可见，代价是增加了调用方的样板代码——对于这个强调可靠性的基础设施项目来说，这个权衡是合理的"才是评价。
|
||||
|
||||
## 从项目特征中发现值得深挖的点
|
||||
|
||||
不要套用模板。每个项目都有自己的"有趣之处"，发现它们的方法：
|
||||
|
||||
**追问设计动机**：看到一个设计选择时，问"为什么不用更常见的方案？"如果答案是"没有特别原因"，这可能是一个改进点；如果答案揭示了深层约束，这就是值得展开的洞察。
|
||||
|
||||
**寻找张力点**：好的架构是在矛盾需求之间找平衡。寻找项目中的张力——性能 vs 可读性、灵活性 vs 简单性、一致性 vs 自治性。这些张力点往往是最有分析价值的地方。
|
||||
|
||||
**识别设计哲学**：大多数成熟项目有贯穿始终的设计风格（"约定优于配置"、"零成本抽象"、"显式优于隐式"）。识别这个哲学，然后检验它是否被一致地贯彻——不一致的地方往往有故事。
|
||||
|
||||
**关注边界**：模块边界、抽象层边界、系统边界——边界的设计往往比内部实现更能体现架构思考。一个模块内部可以随时重写，但边界一旦确定就很难改。
|
||||
|
||||
## 如何发现真正的设计亮点
|
||||
|
||||
亮点是**在特定约束下做出的聪明权衡**，不是"代码整洁"或"注释完善"这种泛泛之谈。
|
||||
|
||||
### 发现方法
|
||||
|
||||
**对比法**："如果是我来设计，我会怎么做？"——如果你的第一反应方案和项目的方案不同，深入比较两者的权衡，往往能发现项目方案的精妙之处。
|
||||
|
||||
**追问法**："这个设计解决了什么不明显的问题？"——表面上看起来过度设计的地方，可能是在防御一个你还没注意到的边界情况。
|
||||
|
||||
**场景法**："在极端场景下会怎样？"——高并发、网络分区、数据量暴增、下游服务挂掉——好的设计在极端场景下优雅降级，差的设计在极端场景下崩溃。
|
||||
|
||||
**演进法**："这个设计是如何演变到现在的？"——git 历史和代码中的注释有时能揭示设计演进的故事，当前的"复杂"设计可能是多次踩坑后的智慧结晶。
|
||||
|
||||
### 亮点的层次
|
||||
|
||||
| 层次 | 示例 | 分析价值 |
|
||||
|------|------|----------|
|
||||
| 架构级 | 独特的模块化策略、创新的扩展机制 | 高——值得深入展开 |
|
||||
| 设计模式级 | 巧妙的状态管理、优雅的错误传播 | 中——值得一段解释 |
|
||||
| 实现级 | 精巧的算法选择、高效的数据结构 | 视情况——只有当它体现设计思想时才值得展开 |
|
||||
|
||||
## 如何写出有启发性的分析
|
||||
|
||||
### 对比式思考
|
||||
|
||||
每个设计决策都存在于一个选择空间中。好的分析不只描述"选了什么"，还要说明"没选什么以及为什么"。
|
||||
|
||||
> ❌ 该项目使用事件驱动架构进行模块间通信。
|
||||
>
|
||||
> ✅ 模块间通信选择了事件总线而非直接调用。直接调用更简单、调试更容易，但会让模块间产生编译期依赖——任何模块的接口变更都会波及调用方。事件总线的代价是运行时才能发现通信错误，但换来了模块可以独立开发和部署。对于这个插件化架构来说，这个权衡是合理的。
|
||||
|
||||
### 反事实推理
|
||||
|
||||
"如果不这样做会怎样"是检验设计必要性的利器。如果去掉一个设计元素后系统仍然正常工作，那它可能是过度设计；如果会导致严重问题，那就值得深入解释。
|
||||
|
||||
### 设计权衡三角
|
||||
|
||||
大多数架构决策涉及三个维度的权衡。找到这三个维度并说明项目在哪个方向上做了倾斜，比简单说"好"或"不好"有价值得多。
|
||||
|
||||
常见的权衡三角：
|
||||
- 简单性 / 灵活性 / 性能
|
||||
- 一致性 / 可用性 / 分区容忍
|
||||
- 开发速度 / 运行时安全 / 学习曲线
|
||||
|
||||
## 全局关联
|
||||
|
||||
**每个局部分析都必须连接到项目整体设计哲学。** 这是区分"代码说明书"和"架构分析"的关键。
|
||||
|
||||
做法：
|
||||
- 分析一个模块时，先说明它在整个系统中扮演什么角色
|
||||
- 解释一个设计决策时，说明它如何服务于项目的整体设计哲学
|
||||
- 发现一个问题时，评估它对整个系统的影响范围
|
||||
- 描述模块间协作时，解释这种协作模式是否与项目其他部分一致
|
||||
|
||||
反面教材：孤立地分析每个模块，最后拼在一起——这样的报告读起来像一堆独立的代码审查，缺乏整体叙事。
|
||||
|
||||
## 叙事连贯
|
||||
|
||||
**模块分析不是独立章节的拼接，而是一条有逻辑的叙事线。**
|
||||
|
||||
好的模块叙事像一本书的章节——每章结尾自然引出下一章的主题。读者不需要目录就能理解为什么先讲 A 再讲 B。
|
||||
|
||||
常见的叙事主线：
|
||||
- **数据流驱动**：跟随一个请求从进入系统到返回响应的完整路径，沿途讲解每个模块的职责。适合 Web 框架、API 网关等请求驱动的系统
|
||||
- **分层驱动**：从最底层的基础设施讲到最上层的用户接口，每层依赖下层的能力。适合操作系统、编译器等分层架构
|
||||
- **问题驱动**：从核心业务问题出发，逐步引入解决每个子问题的模块。适合领域复杂的业务系统
|
||||
|
||||
反面教材：按目录结构或字母顺序排列模块——这样的报告读起来像一本字典，不像一篇分析。
|
||||
|
||||
过渡句示例：
|
||||
> ✅ Gateway 完成了请求的认证和路由分发，但它只负责"谁可以进来"，不负责"进来之后能做什么"。这个行为控制的职责，由沙箱运行时的策略引擎承担。
|
||||
>
|
||||
> ❌ 接下来我们分析策略引擎模块。
|
||||
|
||||
## 深度标准
|
||||
|
||||
### 有深度的分析长这样
|
||||
|
||||
> 路由系统选择了基数树（radix tree）而非哈希表。哈希表查找是 O(1)，但不支持参数路由（`/users/:id`）和通配符——要支持这些就得退化为线性扫描。基数树在静态路由上接近 O(1)，同时天然支持前缀匹配，让参数路由和通配符成为一等公民。代价是实现复杂度高、内存占用略大，但对于一个以路由性能为卖点的框架来说，这个投入是值得的。值得注意的是，Fastify 和 Hono 也做了同样的选择，这已经成为高性能路由的事实标准。
|
||||
|
||||
特征：有具体的技术推理、有量化的权衡、有业界对比、有"为什么适合这个项目"的判断。
|
||||
|
||||
### 没有深度的分析长这样
|
||||
|
||||
> 路由系统采用了高效的数据结构来存储和匹配路由，支持参数路由和通配符匹配，性能表现优秀。
|
||||
|
||||
特征：泛泛而谈、没有具体技术细节、没有推理过程、换一个项目也能用。
|
||||
|
||||
## 批判性思考指引
|
||||
|
||||
### 如何诚实评价
|
||||
|
||||
- **有代码依据**：每个评价都要指向具体的代码证据，不能凭印象
|
||||
- **有对比基准**：说"好"或"不好"时，对比的是什么？业界最佳实践？同类项目？项目自身的设计目标？
|
||||
- **区分"不同"和"不好"**：非主流的设计选择不等于错误，可能是在不同约束下的合理权衡
|
||||
|
||||
### 如何与业界对比
|
||||
|
||||
- 选择真正可比的项目（同领域、同规模、同目标用户）
|
||||
- 对比设计选择而非实现质量——不同项目有不同的成熟度
|
||||
- 承认各自的约束差异——一个 2 人项目和一个 200 人项目面对的问题不同
|
||||
|
||||
### 如何指出问题而不流于吹毛求疵
|
||||
|
||||
- 只指出架构级别的问题，不纠结命名风格或代码格式
|
||||
- 解释问题的实际影响——"这会导致什么具体后果"
|
||||
- 如果可能，提供改进方向（不需要完整方案）
|
||||
- 承认项目的约束——有些"问题"在特定约束下是合理的妥协
|
||||
|
||||
### 如何识别真正的问题
|
||||
|
||||
问题是**对系统产生实际影响的架构缺陷**，不是命名风格或代码格式。
|
||||
|
||||
**影响面分析**：这个问题影响多少模块？影响的是核心路径还是边缘场景？影响面越大，问题越值得指出。
|
||||
|
||||
**演进风险**：这个问题现在可能不严重，但随着项目增长会恶化吗？"技术债务"的本质是利息——现在不还，将来要付更多。
|
||||
|
||||
**替代方案可行性**：指出问题时，心里要有一个可行的改进方向。如果你想不到更好的方案，那可能不是问题，而是在当前约束下的合理妥协。
|
||||
|
||||
### 问题的层次
|
||||
|
||||
| 层次 | 示例 | 如何表述 |
|
||||
|------|------|----------|
|
||||
| 架构级 | 循环依赖、职责混乱、单点瓶颈 | 详细分析影响 + 改进方向 |
|
||||
| 设计级 | 抽象泄漏、过度设计、状态管理混乱 | 说明具体后果 + 对比更好的做法 |
|
||||
| 工程级 | 测试策略缺失、可观测性不足 | 简要指出 + 建议 |
|
||||
|
||||
### 评价的诚实性
|
||||
|
||||
- 项目质量高就多写亮点，不需要凑问题
|
||||
- 项目有明显缺陷就直说，不需要找补
|
||||
- 承认不确定性——"从代码来看可能是 X，但也可能有我没看到的约束"
|
||||
- 区分"设计选择"和"设计缺陷"——非主流不等于错误
|
||||
|
||||
### 综合评价维度
|
||||
|
||||
不使用固定评分表，但评价应覆盖以下维度（根据项目特征选择最相关的）：
|
||||
|
||||
- **架构设计**：模块化程度、关注点分离、扩展性
|
||||
- **设计哲学一致性**：项目是否贯彻了自己的设计理念
|
||||
- **工程成熟度**：测试、文档、错误处理、可观测性
|
||||
- **生态适应性**：在目标生态中的定位是否合理
|
||||
- **演进健康度**：技术债务水平、架构是否支持未来演进
|
||||
|
||||
每个维度的评价都要有具体依据，不要给出没有论证的分数。
|
||||
150
skills/repo-analyzer/references/module-analysis-guide.md
Normal file
150
skills/repo-analyzer/references/module-analysis-guide.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# 模块分析指南
|
||||
|
||||
## 核心方法
|
||||
|
||||
按业务功能划分模块，不按文件或目录。一个逻辑模块可能跨越多个文件，一个文件也可能包含多个模块的部分实现。
|
||||
|
||||
分析深度标准：**交给另一个 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 只读分析（不看源码）能画出模块架构图
|
||||
Reference in New Issue
Block a user