把一个真实代码库转化为一套可追溯、可机检、可续传的工程学习资产的 Agent Skill。 默认交付第一册项目源码与工程实现；第二、三册需用户明确提出。每条源码结论都保留可复检的证据。
- 一、30 秒理解它
- 二、它和「源码讲解 Prompt」有什么不同
- 三、安装
- 四、快速开始
- 五、它到底产出什么
- 六、它怎么跑：七阶段 A~G
- 七、批次教材的十七节结构
- 八、质量怎么保证：闸门 / SSOT / 血证 / 判据版本
- 九、自带工具（21 个脚本）
- 十、仓库结构
- 十一、证据等级
- 十二、硬约束与能力边界
- 十三、从 V1 升级到 V2
- 十四、常见问题
- 十五、相关文档
- 许可证
给 Agent 一个陌生项目，它会按下面这条链路推进，每一步都落盘、都可续传：
陌生项目
└─ A 项目考古 ──────► 四份基础地图（全景 / 覆盖矩阵 / 概念词典 / 完整性地图）
└─ B 业务建模 ──────► 角色 + 端到端闭环 + 核心对象与约束
└─ C 架构推导 ──────► 运行时 / 依赖 / 请求 / 异步 / 数据 / 部署 六张图
└─ D 全文件教材化 ──► 第一册：逐批的完整源码讲解（17 节结构，★类全类贴码）
└─ E 底层穿透 ──────► 第二册：Prediction → Evidence → Experiment → Correction
└─ F Vibecoding ────► 第三册：Architecture Challenge / 重构 / 跨领域迁移
└─ G 验证与归档 ────► 构建·测试·启动证据、已知限制、索引与能力账本
默认只推进第一册；第二册实验与第三册架构挑战只有用户明确请求时才创建。执行实际 Issue 时，工程日志独立于被学习项目存放。
| 常见做法 | 本 Skill |
|---|---|
| 让 AI "讲一下这个项目"，产出一段说明 | 默认逐批产出第一册；其他册按用户明确请求启用 |
| 讲解质量靠"模型自觉" | 113 项技能自检 + 批次闸门复检，保留人工语义审读 |
| 贴代码靠模型手打，行号经常是编的 | 代码块由 inject_source.py 从真实源码逐行注入，行号零漂移；④ 行号一致性逐处核对 |
| "已扫描"≈"已讲解"≈"已验证" | 三者严格区分，禁止互相冒充；没跑过的必须写"未实测" |
| 讲完一个文件就算过 | ② ★反向完整度：★ 类源文件的每一条有效行都要在讲解里出现 |
| 讲清"这行为什么这么写"就算好 | 还必须写【怎么用】【上下游】【怎么接】——合上文件知道怎么调、怎么扩展 |
| 规则改了没人知道 | 判据有版本号（当前 v2.31）+ 变更登记表 + 回归集比对，改动必须走三件套 |
设计上有一条主线：判据只在它能识别的形态上生效，于是"改变形态就能绕过它"是最大的漏洞。
spec/血证档案.md 里的 H1~H29 就是这条主线上踩过的 29 次真实事故——每条判据背后都钉着一次"当时为什么会漏"。
这是一个标准 Agent Skill 目录。把 skills/replicate-learning/ 整个复制到所用 Agent 的 skills 目录即可：
# WorkBuddy
cp -r skills/replicate-learning ~/.workbuddy/skills/
# Claude Code
cp -r skills/replicate-learning ~/.claude/skills/
# 其他 Agent（Codex 等）
cp -r skills/replicate-learning ~/.agents/skills/最小可用只需 SKILL.md，但强烈建议整目录安装——模型会按意图去读 references/、spec/、scripts/、examples/，缺文件会导致闸门跑不起来。
安装后先自检（必须两条都 PASS 才进真实项目）：
cd ~/.workbuddy/skills/replicate-learning # 换成你的实际安装路径
python scripts/skill_selfcheck.py # 期望：检查项 122，失败 0 → PASS ✅
python scripts/v2_selfcheck.py # 期望：V2 self-check: PASS (6 contract entries)单元测试（可选，12 个
test_*.py共 165 项）：python -m unittest discover -s scripts -p "test_*.py" -t scriptsWindows 提示：若把工具输出重定向到文件却看到
UnicodeEncodeError，说明用的是旧版本脚本—— 现行脚本入口已统一把 stdout/stderr 切到 UTF-8（lecture_checks.configure_stdio()）。
第一次使用，提供项目根目录和教材目录即可：
- 被学习项目根目录（要学哪个项目）
- 教材目录（默认写进目标项目的
NOTES/；不希望教材进版本库时可用项目外隔离副本）
执行具体 Issue 时才需要工程日志目录；默认位于目标项目同级 .replicate-learning-log/<项目名>/。
然后用自然语言触发：
学习这个项目：/path/to/my-project
继续学习
讲解第 3 批
验证这个核心机制
给这个项目出一个 Issue 并走完整工程流程
验收当前学习结果
首次运行会先建立四份基础地图，再进入第一批：
NOTES/
00-系统全景地图.md
项目文件覆盖矩阵.md
概念词典.md
阶段对照-完整性地图.md
教学讲解/00-总索引.md
续传原则：进度只认状态文件，不认聊天记忆。上下文不足时先落盘再停，下次从"下一步入口"继续。
提速路径（第二轮提速重构后的实际流水线，每一步都有工具、都先验后写）：
batch_trace start 计时开批（分步耗时：准备/写作/注入/修复/终检/验证/归档）
→ batch_manifest prepare 本批源码 hash 清单（**一次把本批全部源文件传齐**）
→ new_batch --plan --batch-json --skeleton 17 节骨架（与终稿分开两个文件）+ 稳定源码槽位 + batch.json/annotations.json
→ batch_preflight 注入前预检：★ 签名缺口 / 密度连段 / 坏注释键 / 片段参数 / **清单是否覆盖全部源文件**
→ 模型写分片（parts/*.md） 解释、因果、回放、⑫
→ batch_build 骨架 + 分片 + 注释计划 → 重建终稿（四种"假重建"配置直接拒绝）
→ gate_lecture --json --manifest 结构化结果（规则 ID / 状态 / 核验对象数 / 哈希）
→ sync_gate_result --result-json --apply 验哈希后盖章 ⑯，盖章后复跑并记录最终哈希
→ publish_batch --record 一份批次记录更新覆盖矩阵/总索引/阶段页/状态（冲突零写入）；已发布行回修走同一工具的 update_line op
第一次做全库扫描与四份基础地图；每批只读本批源码、调用方与相关测试。普通批次无需重读全部黄金样例 （开批一次取最小样例包，闸门报哪条形态再按规则 ID 补读）或运行全库闸门；修改公共判据、批量收尾时再跑全库回归。 Java 和 Python 执行同一事实核对标准，注释语法与检查档位按语言选择。
NOTES/
教学讲解/第一册-项目源码与工程实现/ ← 是什么、怎么工作
教学讲解/第二册-实验与机制验证/ ← 用户明确请求后建立
教学讲解/第三册-架构挑战与独立重构/ ← 用户明确请求后建立
第一册 · 项目源码与工程实现 回答「这个项目是什么、解决什么业务问题、每个文件和关键代码如何工作」：系统全景与业务闭环、模块/进程/数据依赖、全文件覆盖矩阵、逐件源码讲解、调用链与失败边界、L0-L4 底层穿透。
第二册 · 实验与机制验证 回答「为什么它这样工作？改变或删除它之后会发生什么」，顺序强制为：
Prediction（先预测）→ Evidence（查证据）→ Experiment（做实验）→ Correction（复盘修正）
不能把推断写成事实；跑不起来要写明命令、错误原文、排查范围和剩余风险。
第三册 · 架构挑战与独立重构 回答「如果不照抄原项目，我会怎样设计、替换和迁移这个系统」：Architecture Challenge、等价实现、Replacement / Modification / Reconstruction、Trade-off、跨领域 Transfer。
.replicate-learning-log/<项目名>/
Issue/ 问题原文与用户初始判断
Context/ 交给 AI 的上下文包
Review/ diff 审查意见
Debug/ 调试过程
Delivery/ 交付与验收记录
记录 Issue 原文、AI 调查、上下文包、代码 diff、用户审查意见、测试与调试、最终状态、AI 失误样本、能力账本证据。
Understand → Investigate → Predict → Plan → Delegate → Review → Test → Accept
- 用户不需要手写核心生产代码，但要参与关键预测、架构判断、diff 审查和最终验收；
- 最终状态只能由用户确认，AI 不得自行宣布完成：
Accept/Accept with known risk/Reject and revise/Blocked with evidence。
| 阶段 | 一句话 | 产出 |
|---|---|---|
| A 项目考古 | 扫全仓（含构建/配置/测试/脚本/部署/前端，不只业务源码），建四份基础地图 | 全景地图 / 覆盖矩阵 / 概念词典 / 完整性地图 |
| B 业务建模 | 从角色、场景、规则、状态、异常、审计重建业务；不许拿"用了某框架"当业务解释 | 角色 + 端到端闭环 + 核心对象与约束 |
| C 架构推导 | 运行时/依赖/请求/异步/数据/部署六张图，每个重要选择给替代方案与代价 | 六张图 + 选择理由（全部回链真实类/方法/表） |
| D 全文件教材化 | 按业务闭环分批（不按目录）；每个文件有唯一覆盖状态，排除也要有理由 | 批次讲解 + 覆盖矩阵更新 |
| E 底层穿透 | 关键机制至少剥一层：源码证据 / 框架替你做了什么 / 不用的等价实现 / 失败时间线 | L0-L4 穿透卡 |
| F Vibecoding | 展示"如何让 AI 正确完成"：上下文、拆批、审 diff、反馈闭环、识别幻觉 | ⑫ 八条 + 八段提示词 |
| G 验证与归档 | 构建/测试/启动/最小链路验证并记录命令与输出；没实际运行不得声称已验证 | 验证证据 + 已知限制 + 索引 |
底层穿透的层级（防止只学到"调用姿势"，换框架即归零）：
| 层级 | 含义 |
|---|---|
L0 源码证据 |
真实源码、依赖源码、字节码或官方实现位置 |
L1 机制拆解 |
框架替项目自动完成的具体步骤 |
L2 等价实现 |
不依赖当前框架的可读示范，并写明省略了哪些生产边界 |
L3 设计取舍 |
替代方案、代价、具体失败时间线 |
L4 故障实证 |
实际破坏、日志、堆栈或数据变化；无法运行时必须写"未实测"并退回 L3 |
阶段 G 的完成条件：① 纳入范围文件都有讲解链接或排除理由；② 每个核心闭环有端到端链路；③ 每个核心模块有架构位置、依赖方向、数据流；④ 关键机制有源码证据或推断标记；⑤ 教材落盘并有总索引；⑥ 验证命令与结果可追溯。 构建/运行失败时照样产出教材，但必须写入失败命令、完整关键错误、失败层级、已排查范围、未解决原因与风险。
每批教材统一为 17 节（①~⑯ + 索引节）。节序的权威来源是 references/批次讲解全文模板.md
（由 new_batch.py 抽取骨架），不是任何历史批次。
| 节 | 内容 |
|---|---|
| ① | 在系统全景中的位置（盒状全景图 + 跨批关系） |
| ② | 业务场景与端到端闭环（流水线图 + 分支流预告） |
| ③ | 文件清单与一句话职责（源文件 / 配置资源 / 测试 三张表） |
| ④ | 新概念白话解释（宽表全量 + 核心概念深潜） |
| ⑤ | 批前两个内部清单（外部调用穿透清单 + 九列讲解骨架清单） |
| ⑥ | 逐件讲解（完整代码 + 逐行要点表 + 边界副作用 +【怎么用】/【上下游】/【怎么接】） |
| ⑦ | 调用链、数据流、状态变化、边界与接入路径 |
| ⑧ | L0-L4 底层穿透卡 |
| ⑨ | 八股讲解（本批涉及的面试考点：考点 / 一句话定义 / 为什么考 / 本批落点 + 速查表） |
| ⑩ | 失败反例 |
| ⑪ | 测试视角 |
| ⑫ | Vibecoding 视角（八条 + 八段提示词） |
| ⑬ | 验证证据与已知限制 |
| ⑭ | 复习问答（题后紧跟答案） |
| ⑮ | 前置知识 / 后续依赖 / 未覆盖项 / 下一批入口 |
| ⑯ | 教材质量自检（六项，须引用 §6.4 条目号 + 判据版本） |
| 索引 | 本批回链与导航 |
三条最容易踩的硬要求：
- ★ 核心类禁止摘录式贴码——必须全类注入并逐行比对（源文件每条有效行都在讲解里，覆盖 ≥ 99.5%）。用"取
:L最大值"的粗检查会漏报"整节缺失"。 - ⑤ 用法与接入的位置固定在件末：排在「逐行要点表」之后、件内
---之前。 - ⑫ 禁止回顾语——必须以"你现在接到这个需求、该能力尚不存在、从零构建"为起点；"回顾性重构""本批已实现"这类表述直接 FAIL。
python scripts/gate_lecture.py <批次.md> --src <源码根> --json <结果.json> # 结构化结果（推荐）| 项 | 查什么 |
|---|---|
| ⓪ 结构 | 节数 = 17、一级节标题形态、围栏偶数且配对、占位符 = 0、⑫ 八条 = 8 |
| ① 正向保真 | 每个代码块逐行都能在源码或本批快照里找到（防止编代码） |
| ② ★反向完整 | ★ 类源文件的每一条有效行都要出现在讲解里（防止"讲过"= 只讲了一半） |
| ③ 注释密度 | 连续 ≥ 8 行无注释 = 不合格；条数 ≥ 关键行 ÷ 12 |
| ④ 行号一致性 | // :Lnn 必须就是该内容真正所在的行 |
| ⑤ 用法与接入 | 每件必须写【怎么用】/【上下游】/（抽象件）【怎么接】 |
| ⑥ 散文符号真实性 | 正文里的 Xxx.java:NN、件标题声明的 .java 等必须真实存在 |
退出码非 0 即不过关，首行打印判据版本。任何一项不过关当场修、修完复跑，全过才允许 commit。
--json 出的是结构化结果：每条检查带稳定规则 ID（挂 spec/00-质量契约.json 条款）、五个互斥状态
（PASS/FAIL/REPORT/NOT_CHECKED/ERROR）、核验对象数与定位；核验对象为 0 记 NOT_CHECKED，不算通过。
⑯ 段由它渲染：sync_gate_result.py --result-json <结果.json> --apply（先验契约版本与正文/清单哈希，
盖章后自动复跑一次完整闸门并单独记录最终哈希）。
python scripts/batch_preflight.py --src <源码根> --plan <注释计划.json> [--manifest <清单.json>] [--lecture <批次.md>]它 import 闸门本身，用同一套函数先算一遍：★ 签名缺口几个、哪些块有多长无注释连段、该补哪几行，
外加注释键是否为真实行号、是否落在 Python 多行字符串/反斜杠续行这类"注了也不生效"的位置。
预检说什么，终检就说什么——不再靠"跑闸门试错"。
| 层 | 文件 | 作用 |
|---|---|---|
| 单一真源 | spec/00-质量契约.json |
每条要求 = id / 层级 / 判据原文 / gate 锚点 / SKILL 锚点 / 模板锚点 / 血证编号 |
| 血证档案 | spec/血证档案.md |
H1~H29：每条规则背后的真实事故。想放宽判据前必读 |
| 判据版本 | references/第一册质量细则.md §6.6 |
当前 v2.31；任何判据变更必须走三件套 |
| 技能自检 | scripts/skill_selfcheck.py |
122 项，对账 SSOT ↔ 质量细则 ↔ 模板 ↔ gate，防规则丢失 |
判据变更三件套（缺一即视为未完成）：
- 递增
GATE_VERSION，并在 §6.6 变更登记表加一行（版本 / 日期 / 改了什么 / 影响面 / 存量工单）； - 跑回归集，
--baseline逐字段比对——"不该变的判定必须一字不变"； - 公告与工单：把"新增/收紧的项 + 会变红的批次清单"写进宿主项目状态页。
层级说明：L1 = 机械门（闸门精确判定，所有批次必须过）；L2 = 内容契约（闸门查"有没有"，对不对要人读）；L3 = 教学增益（不假装机械可验，由 ⑯ 自检 + 抽样人审）。
| 脚本 | 干什么 |
|---|---|
gate_lecture.py |
闸门：一次跑完七项判定，输出判据版本与缺口；--json 出结构化结果（稳定规则 ID / 状态 / 核验对象数 / 哈希）；--manifest 显式指定本批源码清单（供盖章核对） |
gate_all.py |
全库记分卡 + 判据回归比对（--baseline 逐字段比对，变化即 FAIL） |
skill_selfcheck.py |
技能文档一致性自检（SSOT ↔ 质量细则 ↔ 模板 ↔ gate 对账，122 项） |
v2_selfcheck.py |
V2 入口与产物契约检查 |
batch_trace.py |
批次分步计时器（JSONL）：把"一小时到底花在哪"拆成准备/写作/注入/修复/终检/验证/归档 |
batch_preflight.py |
开批预检：注入前就用闸门同口径报出 ★ 签名缺口、密度连段与可补注行、坏注释键；并要求清单覆盖注释计划里的全部源文件（缺件 FAIL） |
new_batch.py |
新批次脚手架：从模板生成 17 节骨架（--skeleton，与终稿 --out 分开）；--plan 时逐件写稳定源码槽位并派生唯一一份可编辑 annotations.json 与 batch.json |
batch_build.py |
从「骨架 + 分片 + 注释计划」重建终稿（--dry-run 预览、--check 比对、失败不写盘）；构建前 fail-closed 拦住骨架=终稿 / annotations 指回原始计划 / 分片目录为空 / 某节仍是模板占位原文（缺分片） |
publish_batch.py |
用一份批次记录更新覆盖矩阵/总索引/阶段页/状态：先验后写、冲突零写入、幂等、--git-add 只加点名文件；已发布行的回修走第五种 op update_line（anchor 回修后仍唯一命中 + expect 整行原文 + 按行现状判幂等） |
study_scope.py |
默认第一册与显式扩展册范围解析、旧状态迁移 |
batch_manifest.py |
本批 Java/Python 等源文件 hash 清单与变更检查 |
assemble_batch.py |
把 17 节骨架和完整章节片段确定性组装，局部返工只换片段 |
inject_source.py |
源码块注入：优先按槽位（块身份 = 槽位 ID + 源路径 + sha256）注入，旧 anchor/contains 兼容并告警 |
lecture_checks.py |
检查结果的统一 schema 与规则登记表（状态词表 / SSOT 条款映射 / 哈希绑定校验） |
safe_edit.py |
局部安全编辑工具：围栏护栏 + 整节重写，跨围栏替换一律拒绝 |
callsite.py |
调用点提取：输出「声明 / 使用调用点 / 仅提及」三段（写【怎么用】的证据来源） |
fix_lineno.py |
行号标注修正：重写真行号，并把作废的 // :N 升级为 :Lnn |
annotate_gaps.py |
③ 注释缺口定位器：算出满足判据所需的最小标注点集合 |
sync_gate_result.py |
把闸门结果写进 ⑯ 段：--result-json 从结构化结果渲染，验哈希后才盖章，盖章后复跑并记最终哈希 |
fix_circled_sections.py |
修复一级节标题带圈数字丢失（丢码会让整节检查静默失效） |
polish_fix.py |
⑥/⑫ 排版整形（断段、列表化、标记段空行） |
工具随技能发布：规程里写着"必须做"的步骤，其执行工具必须在
scripts/下、被文档引用、被自检覆盖。留在会话临时目录里的脚本等于没有。
replicate-learning/
├── README.md 本文件
├── LICENSE Apache-2.0
├── 总方案.md V2 总体方案
├── docs/ 方案与验收过程文档
├── gate_all.json 全库闸门记分卡样例
└── skills/replicate-learning/ ★ 要安装的就是这个目录
├── SKILL.md 入口 + 意图路由（58 行：可执行入口，长表与细则按需读）
├── docs/ (3) 安装与执行边界、通用学习方法、V2 试运行手册（archive/）
├── examples/ (2) 黄金样例（Java / Python）
├── references/ (30) 执行协议 + 全部讲解与工程模板 + 黄金样例节选
├── scripts/ (21) 上表 21 个工具（另有 11 个 test_*.py 行为自测）
├── spec/ (7) 质量契约 SSOT、血证档案、操作手册、阶段工作流
└── tests/fixtures/ 回归夹具（batch48 真实批次 + py_mini 合成边界用例）
入口是 skills/replicate-learning/SKILL.md。触发后先按意图读 references/第一册执行协议.md（扩展册看 V2执行协议.md），再按任务类型读对应模板——不要求把全部文档一次性装入上下文。
每个重要结论必须标注一种证据：
| 等级 | 含义 |
|---|---|
事实-源码 |
可以回链到真实文件、类、方法或行号 |
事实-实测 |
由命令、测试、日志、堆栈或实验得到 |
事实-历史 |
由 Git 提交、差异或 blame 得到 |
外部事实 |
来自官方文档、依赖源码或协议规范 |
推断 |
根据现象和代码推导，尚未直接验证 |
性能、并发、安全、故障和生产行为这类结论，不允许用模型记忆代替证据。
硬约束（详见 SKILL.md 与 references/第一册质量细则.md）：
- 教材写入被学习项目
NOTES/；工程日志独立保存，不污染目标项目。 - 默认只生成第一册；第二、三册必须由用户明确提出。未请求的册不建目录、不记欠账。
- 关键机制先有预测或证据，再实现或实验；不得把推断写成事实。
- AI 完成检索、写作、脚本与代码劳动；用户只参与关键预测、设计、审查和验收。
- AI 不得自行宣布交付完成，最终状态只能由用户确认。
- 每次结束前必须落盘状态、产物、失败证据和下一步入口；上下文不足时也先落盘。
当前不承诺：自动评分用户回答、自动生成复杂 Benchmark、全自动故障注入、多 Agent 自动协作、对任意项目一次性生成全部教材、AI 不经人工审查即可保证代码正确。
首轮试运行的最小验收集：四份基础地图 + 第一册一个源码批次 + 源码与测试证据 + 批次闸门 + 人工语义审读。实验、架构挑战和 Issue 闭环按明确任务分别验收。
V1（判据停在 2.14）专注"第一册源码讲解"，V2 在此之上补了三件事：
| 维度 | V1 | V2 |
|---|---|---|
| 教材 | 第一册 | 默认第一册；第二、三册按用户明确请求启用 |
| 工程训练 | 无独立载体 | 独立工程日志 + Issue 八步协议 + 能力账本 |
| 受众 | 讲给"读者" | 同时讲给"要动手改它的人"（⑫ Vibecoding 视角 +【怎么用】/【怎么接】） |
| 判据 | 2.14 | 2.31（含教材类/记录类文件形态判定、注释标记按语言取前缀、件段边界只认正文、⑨ 八股讲解等） |
升级方式：删除旧目录，整个替换为 skills/replicate-learning/。旧版产物无需迁移，但旧批次按新判据跑闸门时，收紧项对未声明版本的存量批次默认走报告档（不追溯），不生效追溯红。
Q：一定要 Java 项目吗？
不。判据 2.22 起注释标记按语言取前缀（// / # / --），已在 Python + TypeScript 项目上首跑验证。但每上一次新语言/新形态都要回头看判据是否还认得它——H27 就是这么来的。
Q：教材会污染我的项目仓库吗？
教材默认就地写入目标项目 NOTES/（推荐，教材随项目走）。若项目的 .gitignore 会忽略它或你不希望入库，可改用项目外隔离副本。开工时 Skill 会检查并给选项。
Q：AI 说"这一批已完成"，我可以信吗？
以闸门退出码为准，不以模型的自我陈述为准。跑 gate_lecture.py，退出码 0 且首行判据版本符合预期才算过；最终交付永远由你 Accept。
Q：判据一改，我的旧批次全变红了怎么办？ 这正是 §6.6 要防的。新判据对未声明版本的存量批次默认走报告档；任何变更必须跑回归集并逐字段比对，"不该变的判定必须一字不变"。
Q：改了 Skill 之后要做什么？
① 先改 spec/00-质量契约.json；② 同步 SKILL.md / 模板 / gate 三处投影；③ 跑 skill_selfcheck.py 全绿；④ 判据有变按三件套登记；⑤ 同步所有安装副本。
仓库级
技能级（skills/replicate-learning/）
- SKILL.md — 入口、意图路由、硬约束
- 安装与执行边界 — 能保证什么 / 不能保证什么
- V2 执行协议 — 每次开工/续传先读
- 操作手册：闸门与工具 — 每天干活时读
- 血证档案 — H1~H29，想放宽判据前必读
- 质量契约 SSOT — 单一真源
- 七阶段工作流
- V2 试运行手册