罗斯蒙德开源项目全知

概述

开源项目全知

概述

把一个陌生开源项目变成「能看懂、能跑起来、能改得动、能评估出要投多少人」的状态。

五条核心原则：

1. 讲清楚是主业，问清楚是例外 —— 用户丢了项目就从头讲到尾，一个字不问；只有带需求且需求有歧义时才开口问。假设表是"告知"，输出的同时继续干活，绝不停下来等回复。
2. 结论必带出处 —— 每条架构判断、每个能力点都要有 文件路径:行号 或文档 URL。没读到的代码不臆测，写"未验证"。
3. Demo 必须开箱即用 —— 不是片段演示，是能跑起来的东西：含构建文件、配置、依赖、运行步骤、完整注释。
4. 踩坑点要能防问题 —— 每条必须写清「现象 → 原因 → 解决 → 如何避免」。只写"注意版本兼容"这种空话等于没写。
5. 需求有歧义必须先问清 —— 用户带需求来时，理解错了后面全废。唯一允许多轮追问的环节，但必须批处理（一次摊开 ≤5 问、每问带默认选项、最多 3 轮），问不清不许开始评估。

何时使用 / 何时不用

用： 丢一个代码文件夹/仓库让讲解整个项目（默认场景）、接手陌生开源项目、调研某个库要不要用、需要快速产出可运行示例、要给别人写上手文档、评估某开源项目能否满足既定需求并估算改造工作量。

不用： 已有项目日常开发、只需要查某个 API 用法（直接看文档更快）、做通用代码规范审查或安全审计（本技能只做需求驱动的代码核查，不做全量 review）。

入口场景决定走哪条路

先判断用户属于哪种场景，别一上来就把阶段 R 那套澄清表掏出来。

场景 A 是默认场景。 用户只是丢了个文件夹让讲项目 —— 老老实实走主线，一个字都不要问，直接扫描、直接出报告，假设写在报告头部即可。只有场景 B/C 才启用阶段 R 的澄清与评估。

路由铁律：

• 用户没有提出任何需求/功能项 → 绝不进入阶段 R，不做任何澄清追问，不许问"你打算用它做什么"
• 用户提了需求 → 阶段 R 才生效；且主线产出不能因此缩水（除非用户明确说"只要评估"）

用户一句话里既有项目名又有需求（场景 B）→ 两条都走：阶段 0-3 打底（拿到架构与能力清单），阶段 R 出结论。用户要的是结论，不要因为没跑完七阶段就不给评估结论。

主流程（阶段 0-6）· 场景 A 默认走这条

阶段 0 · 最小扫描与假设声明（不等待）

《假设确认表》是"告知"不是"卡流程"——输出的同时就往下干活，不许停下来等回复。（例外：场景 B/C 的需求歧义，走阶段 R 澄清表，见 references/assumption-form.md。）

先做最小扫描（读 README / 目录结构 / 构建文件），然后输出《假设确认表》：

## 假设声明（不用回复，我已按此开始；有改动随时说）

| 项 | 我的判断 | 依据 | 如需修改请直接改这一行 |
|----|----------|------|------------------------|
| 项目 | Spring Boot 3.2 | pom.xml:12 | |
| 技术栈 | Java 17 + Maven + Spring MVC | pom.xml, src/main | |
| 你的目标 | 集成开发（把能力用进自己项目） | 默认 | 概览 / 集成 / 二次开发 / 排障 |
| 产出深度 | 标准（约 2 小时阅读量） | 默认 | 概览(30min) / 标准(2h) / 深入(半天) |
| Demo 形态 | 完整可运行工程 | 框架类项目自动判定 | 完整工程 / 单文件示例 |
| Demo 场景 | 依赖注入三种方式对比 | 默认按高频能力选 | |
| 重点关注 | DI 容器、自动配置、扩展点 | 框架类默认 | |

**你不用回复，我已按以上假设开始；有改动随时说，我针对性调整。**

场景 A（用户只是丢文件夹让讲项目）：这张表可以压缩成报告头部的一行假设声明

（> 本产出基于以下假设：目标=集成开发 | 深度=标准 | Demo=完整工程），

不必单独摆一张表让用户确认——用户要的是讲解，不是填表。

深度与形态的自动判定规则见 references/assumption-form.md。

场景 B/C（用户带了需求时）：确认表照出，另加一行「需求评估：是」，并同时附一张《需求澄清确认表》（两张表一次发，用户回一句「确认，Q1=B」即可），然后转阶段 R。

用户没回应/只给了路径 → 立刻按假设执行完整主线，一条都不问。

阶段 1 · 获取与扫描

python scripts/scan_project.py <项目路径> -o scan-report.json

有本地路径优先读本地；无本地路径则用 WebSearch/WebFetch 查官方文档、README、源码仓库，不得臆造目录结构。

扫描器输出：模块树、构建文件与依赖、入口类、代码量分布、配置清单、框架特征（含 Spring 注解统计）。

场景 A 快速通道（用户丢了文件夹说"讲一下这个项目"）：扫描完不停顿，一路做到阶段 6，五件套一件都不能省：

"讲解"不等于念目录。 输出类清单、贴大段源码、罗列文件树都算不合格——要讲清「为什么这么设计」「我想改 XX 该动哪里」「它和我手上的活有什么关系」。

阶段 2 · 架构分析

加载 references/architecture-analysis.md。产出：

• 分层结构（每层职责 + 代表类 + 路径）
• 模块依赖关系（谁依赖谁，有无循环）
• 核心调用链（从入口到关键实现，标注 3-5 条主链路）
• 扩展机制（SPI / 插件 / 钩子 / 配置点）

每条结论挂 路径:行号。

阶段 3 · 能力清单

加载 references/capability-list.md。产出三级清单：

每条能力写：一句话说明 + 适用场景 + 最小用法片段 + 代码位置 + 高频度标记（★★★/★★/★）。

高频度判定依据：示例中出现次数、@since/文档篇幅、配置项的默认开启情况。判定依据要写出来，不能拍脑袋。

阶段 4 · Demo 生成

加载 references/demo-generation.md。按阶段0 判定的形态产出：

• 框架类项目（Spring、Django、Express 等）→ 完整可运行工程：构建文件 + 目录结构 + 配置 + 源码 + README
• 工具类库（某个 SDK、算法库）→ 单文件示例 + 运行说明

Demo 硬要求：

• 注释覆盖关键行 —— 每个关键 API 调用、每个配置项都要注释为什么这么写
• 可运行 —— 依赖版本写死，不写 latest
• 有验证步骤 —— 跑完能观察到什么
• 生成后跑 scripts/check_demo.py

阶段 5 · 踩坑点

加载 references/pitfalls.md。四段式，每条：

### 坑 N：<一句话现象>
- **现象**：（用户会看到的确切报错或行为）
- **原因**：（底层机理）
- **解决**：（可复制的命令或代码）
- **如何避免**：（编码习惯 / 配置约定 / 检查项）

优先级：环境依赖 > 版本兼容 > 配置错误 > API 误用 > 性能陷阱。只写真实会发生且能预防的，不凑数。

阶段 6 · 上手指南与交付自检

加载 references/quickstart-guide.md 产出全流程指南：环境准备 → 获取代码 → 构建 → 跑通 → 验证 → 常见下一步。

最后按 templates/onboarding-report.md 组装，跑交付自检清单。

阶段 R · 需求满足度评估（条件触发）

触发（缺一不可）：① 用户明确提出了需求或功能项；② 要判断"能不能做/改哪里/多久/缺什么"。典型说法："能不能支持 XX""要改哪些地方""大概多久""这几个功能点哪些要自己开发"。

不触发（必须严守）：用户只是丢一个文件夹/仓库让讲项目、问"这是干嘛的""怎么跑起来"、问某个 API 怎么用 —— 这些一律走主线，不许弹需求澄清表，不许问"你打算用它做什么"。拿不准就走主线：主线产出对任何用户都有用，误发一张澄清表则是在制造摩擦。位置：依赖阶段2/3 的架构与能力清单做证据，故排在阶段3 之后；用户只要结论时可与阶段4-6 并行压缩。

R1 澄清的三条硬约束（违反即不合格）：

• 每轮 ≤5 个问题，一次摊开——不许连环单问
• 每问必须带 A/B/C 选项 + 默认值（用户不回就按默认走）
• 最多 3 轮；第 3 轮仍有歧义 → 冻结为「假设值」并进风险清单，不再追问

R3 每条 FR 的九个字段：用户原话 / 判定 / 能否实现 / 判定依据（路径:行号 或未命中说明）/ 实现方式 / 修改位置（文件:行号） / 工作量（档位+人日+估算依据） / 风险与波及面 / 验证方式。

工作量档位：XS 0.5 · S 1-2 · M 3-5 · L 1-2 人周 · XL >2 人周（→ 建议换方案）。报告头部必须写明估算前提（含什么、不含什么）。

产出按 templates/requirement-fit-report.md 组装，跑 scripts/check_fit_report.py。

硬规则

1. 讲解是主业，评估是分支 —— 用户没提需求 → 走完整主线（五件套），不许进入阶段 R、不许追问用途；用户提了需求也不能因此砍掉主线产出
2. 假设先行，不卡流程 —— 阶段0 的确认表是"告知"，输出的同时就往下干；用户未回应则按假设出全量报告，绝不等回复
3. 结论必有出处 —— 无 路径:行号 或 URL 的判断不许写；未读到的代码标注"未验证"
4. Demo 开箱即用 —— 必须有构建文件、依赖版本、运行步骤、验证方法
5. 踩坑点四段式 —— 缺「如何避免」一条的踩坑点视为不合格
6. 不臆测 —— 检索不到就说检索不到，不用训练记忆冒充源码事实
7. 需求歧义必须先问清 —— 唯一允许多轮追问的环节，但必须批处理（≤5问/轮 + 默认选项 + ≤3轮）；基线未冻结不许开始 R2
8. 判定必有代码证据 —— 每条 FR 要么给出 路径:行号，要么写明检索了哪些关键词、在哪些目录搜的；"我记得它没这功能"不算依据
9. 工作量必有估算依据与前提 —— 只写"3 人天"不给依据视为不合格；脱离前提的工时可当作废
10. 不涵盖项必须给补充方案 —— 只说"不支持""要自己开发"视为没评估；必须给 ≥2 条路径 + 推荐 + 升级影响

资源

流程纪律

• [ ] 是否正确识别了入口场景（A 讲解 / B 项目+需求 / C 单点诉求）？
• [ ] 场景 A 是否一条都没问、没让用户填表、没停下来等回复？
• [ ] 场景 A 五件套是否齐全（一句话结论 / 架构 / 能力清单 / Demo / 踩坑+指南）？
• [ ] 讲解是否讲清了"为什么这么设计、想改 XX 动哪里"，而不是念目录贴源码？
• [ ] 阶段0 是否输出了假设确认表（或压缩为报告头部的假设声明）？
• [ ] 用户没提需求时，是否完全没有弹需求澄清表？
• [ ] 阶段2 每条架构结论是否有 路径:行号？
• [ ] 阶段3 能力是否分了三级？高频度判定依据是否写明？
• [ ] 阶段4 Demo 是否有构建文件 + 依赖版本 + 运行步骤 + 验证方法？
• [ ] check_demo.py 是否跑过且无 ERROR？
• [ ] 阶段5 每条踩坑点是否四段齐全（尤其「如何避免」）？
• [ ] 阶段6 指南是否包含：环境 → 获取 → 构建 → 跑通 → 验证 → 下一步？
• [ ] 是否有任何结论是凭记忆写的、没有出处？

阶段 R 附加（带需求时必查）：

• [ ] 需求是否拆成原子项 FR-xx？
• [ ] 歧义项是否走了澄清表？是否批处理（≤5问/轮、带默认、≤3轮）而非连环单问？
• [ ] 需求基线是否冻结后才开始代码审查？假设值是否单独标注？
• [ ] 每条 FR 的四分类与「能否实现」是否一致（无自相矛盾）？
• [ ] 每条是否给了修改位置（文件:行号）与工作量（档位+人日+依据）？
• [ ] 报告头部是否写明估算前提？
• [ ] ❌ 不涵盖项是否都给了补齐路径 + 推荐 + 升级影响？
• [ ] 汇总是否有总人日区间、关键路径、风险 Top3、明确建议？
• [ ] check_fit_report.py 是否跑过且无 ERROR？

版本记录