dsh-learn-mode 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/client/client.js +452 -0
  2. package/cordis.patch.yml +20 -16
  3. package/index.js +19 -0
  4. package/package.json +42 -13
  5. package/skills/dsh-learn-mode/SKILL.md +7 -5
  6. package/skills/learn-synthesizer/SKILL.md +278 -0
  7. package/skills/learn-synthesizer/analysis/workspace-file-convention.md +402 -0
  8. package/skills/learn-synthesizer/evals/evals.json +72 -0
  9. package/skills/learn-synthesizer/references/axis-types.md +20 -0
  10. package/skills/learn-synthesizer/references/example-structures.md +291 -0
  11. package/skills/learn-synthesizer/references/feedback-types.md +296 -0
  12. package/skills/learn-synthesizer/references/gotchas.md +322 -0
  13. package/skills/learn-synthesizer/references/sub-agent-prompt.md +222 -0
  14. package/skills/learn-synthesizer/rules/core-principles.md +173 -0
  15. package/skills/learn-synthesizer/rules/output-format.md +355 -0
  16. package/skills/learn-synthesizer/rules/quality-gates.md +209 -0
  17. package/skills/learn-synthesizer/scripts/pdf_to_md.py +124 -0
  18. package/skills/learn-synthesizer/templates/MISSION.md +38 -0
  19. package/skills/learn-synthesizer/templates/deep-dive.md +73 -0
  20. package/skills/learn-synthesizer/templates/map-evolution.md +38 -0
  21. package/skills/learn-synthesizer/templates/understanding-map.md +42 -0
  22. package/skills/learn-synthesizer/workflows/stage0.5-mission.md +141 -0
  23. package/skills/learn-synthesizer/workflows/stage1-collect.md +214 -0
  24. package/skills/learn-synthesizer/workflows/stage2-extract.md +254 -0
  25. package/skills/learn-synthesizer/workflows/stage2.5-importance.md +197 -0
  26. package/skills/learn-synthesizer/workflows/stage3-merge.md +492 -0
  27. package/skills/learn-synthesizer/workflows/stage3.5-gap.md +317 -0
  28. package/skills/learn-synthesizer/workflows/stage4-chapter-agent.md +342 -0
  29. package/skills/learn-synthesizer/workflows/stage4-ref-extract.md +111 -0
  30. package/skills/learn-synthesizer/workflows/stage4-write.md +355 -0
  31. package/skills/learn-synthesizer/workflows/stage4.5-verify.md +327 -0
  32. package/skills/learn-synthesizer/workflows/stage5-review.md +196 -0
  33. package/skills/learn-synthesizer/workflows/stage5.5-iterate.md +297 -0
  34. package/skills/learn-synthesizer/workflows/stage6-finalize.md +310 -0
  35. package/skills/learn-synthesizer/workflows/stage6-progressive.md +173 -0
  36. package/skills-provider.mjs +99 -0
  37. package/workbench-host.mjs +425 -0
@@ -0,0 +1,317 @@
1
+ # 阶段3.5:缺口识别与针对性补充(条件进入)
2
+
3
+ 大纲合并完成后,进入本阶段进行结构性缺失检查。
4
+
5
+ **注意**:本阶段为**条件进入**阶段——AI 必须先执行风险扫描(见下方 §3.5.1),满足 SKILL.md 阶段决策树中任一风险信号时触发,不满足时跳过。AI 不得在未做风险扫描的情况下自行跳过本阶段。
6
+
7
+ ---
8
+
9
+ ## 3.5.1 缺口扫描
10
+
11
+ 读取阶段3生成的大纲,逐章节扫描以下风险信号:
12
+
13
+ ### 风险类型表
14
+
15
+ | 风险类型 | 判断标准 | 严重程度 |
16
+ |---------|---------|---------|
17
+ | **来源单一** | 某章节的所有知识点来自同一份资料 | 中 |
18
+ | **覆盖不足** | coverage_gaps 中提到的主题在大纲中没有对应章节 | 高 |
19
+ | **冲突未解** | 某知识点有 VERSION_CONFLICT 但双方证据都来自三手资料 | 中 |
20
+
21
+ ### 扫描方法
22
+
23
+ **来源单一检测**:
24
+ ```
25
+ For 每个章节 in 大纲:
26
+ 提取该章节所有知识点的来源列表
27
+ If 来源列表中所有项都指向同一份资料:
28
+ 标记该章节为"来源单一"
29
+ ```
30
+
31
+ **覆盖不足检测**:
32
+ ```
33
+ 汇总所有 Sub-agent 报告中的 coverage_gaps
34
+ For 每个缺失主题 in coverage_gaps:
35
+ If 大纲中没有对应章节:
36
+ 标记为"覆盖不足"
37
+ ```
38
+
39
+ **冲突未解检测**:
40
+ ```
41
+ For 每个标记为 VERSION_CONFLICT 的知识点:
42
+ 检查冲突双方的来源类型
43
+ If 双方都是 tertiary(三手资料):
44
+ 标记为"冲突未解"
45
+ ```
46
+
47
+ ---
48
+
49
+ ## 3.5.2 生成缺口报告
50
+
51
+ 向用户展示扫描结果:
52
+
53
+ ```markdown
54
+ ## 大纲质量检查报告
55
+
56
+ ### [检查] 来源单一(X个章节)
57
+
58
+ | 章节 | 唯一来源 | 风险说明 |
59
+ |------|---------|---------|
60
+ | 第2章"分支管理" | 《Pro Git》 | 仅来自一本书,可能遗漏新特性或最佳实践 |
61
+ | ... | ... | ... |
62
+
63
+ **建议**:补充官方文档或实战博客,增强内容可信度。
64
+
65
+ ---
66
+
67
+ ### [警告] 覆盖不足(X个主题)
68
+
69
+ | 缺失主题 | 来源 | 重要程度 |
70
+ |---------|------|---------|
71
+ | `git worktree` 多工作区管理 | 在《Pro Git》的 coverage_gaps 中被提及 | 中 — 现代 Git 工作流常用 |
72
+ | ... | ... | ... |
73
+
74
+ **建议**:为这些主题补充搜索,确保教程完整性。
75
+
76
+ ---
77
+
78
+ ### [待验证] 冲突待验证(X处)
79
+
80
+ | 知识点 | 冲突双方观点 | 问题 |
81
+ |--------|------------|------|
82
+ | `git reset` 的安全性 | 文档A说"危险操作",文档B说"可控操作" | 双方都是转载博客,缺乏权威依据 |
83
+ | ... | ... | ... |
84
+
85
+ **建议**:查阅官方文档验证哪种说法正确。
86
+
87
+ ---
88
+
89
+ ## 决策
90
+
91
+ 是否需要针对这些章节补充搜索?
92
+ - **建议补充的章节数**:X个
93
+ - **预计新增资料**:每章节最多3篇,累计最多15篇
94
+ - **补充后将重新执行**:阶段2(Sub-agent精读)→ 阶段3(合并大纲)
95
+
96
+ 请回复:
97
+ - "是" — 开始补充搜索
98
+ - "否" — 跳过此阶段,直接进入阶段4
99
+ - "部分补充" — 请指定需要补充的章节编号
100
+ ```
101
+
102
+ ---
103
+
104
+ ## 3.5.3 用户决策处理
105
+
106
+ ### 决策1:用户选择"否"(跳过)
107
+
108
+ 直接进入阶段4,不执行补充。
109
+
110
+ 向用户确认:
111
+ > "已跳过缺口补充,将基于现有大纲进入阶段4撰写教程。"
112
+
113
+ ### 决策2:用户选择"是"(全部补充)
114
+
115
+ 进入 3.5.4 补充搜索流程。
116
+
117
+ ### 决策3:用户选择"部分补充"
118
+
119
+ 询问用户具体章节编号,然后仅对指定章节执行 3.5.4 补充搜索流程。
120
+
121
+ ---
122
+
123
+ ## 3.5.4 补充搜索策略
124
+
125
+ ### 补充数量控制
126
+
127
+ | 限制项 | 上限 | 原因 |
128
+ |--------|------|------|
129
+ | 单章节补充资料数 | 3篇 | 避免单章节过度膨胀 |
130
+ | 总补充资料数 | 15篇 | 避免二次上下文膨胀 |
131
+ | 单轮补充主题数 | 5个 | 避免用户等待时间过长 |
132
+
133
+ ### 搜索顺序
134
+
135
+ **优先级顺序**:
136
+ 1. 覆盖不足(高严重程度) — 缺失主题需要尽快补充
137
+ 2. 冲突未解(中严重程度) — 影响教程可信度
138
+ 3. 来源单一(中严重程度) — 锦上添花
139
+
140
+ ### 搜索方式
141
+
142
+ **针对每个需要补充的章节**:
143
+
144
+ #### 步骤1:确定搜索关键词
145
+
146
+ 基于章节主题和缺失内容,生成搜索关键词。
147
+
148
+ **示例**:
149
+ - 章节:"分支管理"
150
+ - 缺失主题:"git worktree"
151
+ - 搜索关键词:"git worktree tutorial"、"git worktree 最佳实践"
152
+
153
+ #### 步骤2:优先查阅官方文档
154
+
155
+ ```
156
+ 使用 context7:query-docs 查询:
157
+ - 输入:主题名 + 缺失概念
158
+ - 期望:官方文档中对该概念的说明
159
+ ```
160
+
161
+ **如果找到** → 记录为"补充资料1",继续步骤3
162
+
163
+ **如果未找到** → 跳到步骤3
164
+
165
+ #### 步骤3:搜索高质量博客
166
+
167
+ ```
168
+ 使用 exa:web_search_exa 搜索:
169
+ - 关键词:[主题] + [缺失概念] + "best practices"
170
+ - 权重偏好:Medium > Dev.to > 个人博客
171
+ - 时间过滤:最近3年内
172
+ ```
173
+
174
+ 返回结果后,选择前2篇(与官方文档合计不超过3篇)。
175
+
176
+ #### 步骤4:标注补充来源
177
+
178
+ 在补充资料列表中记录:
179
+ ```markdown
180
+ ## 补充资料记录(阶段3.5)
181
+
182
+ | 章节 | 补充资料 | 来源类型 | 补充原因 |
183
+ |------|---------|---------|---------|
184
+ | 第2章 | [Git Worktree 官方文档](URL) | 一手 | 覆盖不足 — 原大纲缺失 worktree 主题 |
185
+ | 第2章 | [实战:Git Worktree 工作流](URL) | 二手 | 覆盖不足 — 补充实战案例 |
186
+ | 第5章 | [Git Reset 官方手册](URL) | 一手 | 冲突未解 — 验证安全性争议 |
187
+ ```
188
+
189
+ ---
190
+
191
+ ## 3.5.5 重新执行阶段2和3
192
+
193
+ 补充搜索完成后:
194
+
195
+ ### 步骤1:为新资料派发 Sub-agent
196
+
197
+ 使用与阶段2相同的流程(参见 `workflows/stage2-extract.md`):
198
+ - 为每份新资料各派发一个 Sub-agent
199
+ - 使用标准的知识提取指令(参见 `references/sub-agent-prompt.md`)
200
+ - 收集新的知识报告
201
+
202
+ ### 步骤2:增量合并大纲
203
+
204
+ **不要重新生成整个大纲**,而是将新知识点合并进已有大纲:
205
+
206
+ ```
207
+ For 每个新知识报告:
208
+ For 每个新知识点:
209
+ 匹配到对应章节
210
+ 执行分级三问(参见 workflows/stage3-merge.md)
211
+ If 与已有知识点不重复:
212
+ 插入到对应章节的合适位置
213
+ 标注"补充于阶段3.5"
214
+ ```
215
+
216
+ ### 步骤3:更新缺口报告
217
+
218
+ 重新扫描大纲,检查是否仍有未解决的缺口。
219
+
220
+ 向用户汇报:
221
+ > "补充完成。已为X个章节补充Y份资料,新增Z个知识点。
222
+ >
223
+ > 剩余未解决缺口:[如果还有,列出;如果没有,说"无"]
224
+ >
225
+ > 是否需要继续补充?"
226
+
227
+ ---
228
+
229
+ ## 3.5.6 迭代上限
230
+
231
+ 最多执行2轮补充(每轮最多15份资料),总计最多30份新资料。
232
+
233
+ **达到上限时**:
234
+ > "已进行2轮补充,累计新增30份资料。继续补充可能导致教程过于庞大。建议:
235
+ > 1. 基于现有内容进入阶段4撰写
236
+ > 2. 或者将主题拆分成多个独立教程
237
+ >
238
+ > 您的选择?"
239
+
240
+ ---
241
+
242
+ ## 3.5.7 跳过条件(自动判断)
243
+
244
+ 如果大纲扫描结果显示**所有指标都通过**:
245
+ - [通过] 没有"来源单一"章节
246
+ - [通过] 没有"覆盖不足"主题
247
+ - [通过] 没有"冲突未解"问题
248
+
249
+ **自动跳过本阶段**,向用户说明:
250
+ > "大纲质量检查通过,所有章节都有多来源支持,覆盖完整。可以直接进入阶段4撰写教程。
251
+ >
252
+ > 是否需要额外补充资料?(通常不需要)"
253
+
254
+ 用户回复"不需要" → 进入阶段4
255
+
256
+ ---
257
+
258
+ ## 3.5.8 与阶段5.5的区别
259
+
260
+ | 维度 | 阶段3.5(缺口识别) | 阶段5.5(交互式完善) |
261
+ |------|------------------|-------------------|
262
+ | 触发时机 | 阶段3大纲合并后 | 阶段5人工审核后 |
263
+ | 检查对象 | 大纲结构 | 教程具体内容 |
264
+ | 问题类型 | 整个主题缺失、来源单一、冲突未解 | 表达不清、术语难懂、流程复杂 |
265
+ | 解决方式 | 补充搜索新资料 → 派发 Sub-agent | 优化表达、绘图、补充示例 |
266
+ | 是否需要新资料 | 是 | 通常不需要 |
267
+ | AI主动性 | AI 主动扫描并建议 | 完全基于用户反馈 |
268
+
269
+ ---
270
+
271
+ ## 3.5.9 保存会话状态
272
+
273
+ 补充完成并更新大纲后,更新工作区的 `session-state.md`:
274
+
275
+ ```markdown
276
+ # 会话状态
277
+ 主题: [主题名]
278
+ 更新时间: [当前时间]
279
+ 学习模式: [快速参考 / 完整教程]
280
+ 工作区: [工作区绝对路径]
281
+
282
+ ---
283
+
284
+ ## 进度
285
+ 当前阶段: 4
286
+ 已完成阶段: 1, 2, 3, 3.5
287
+
288
+ ## 阶段输出
289
+ - **阶段1**: 资料清单.md — [N]份资料
290
+ - **阶段2**: `_internal/02-extract/` — [X]个知识点(含补充)
291
+ - **阶段3**: outline.md, outline-stats.json
292
+ - **阶段3.5**: 已补充[Y]份资料,大纲新增[Z]个知识点
293
+
294
+ ## 阶段4 章节状态
295
+ 已完成: (暂无)
296
+ 待完成:
297
+ - [根据更新后的 outline.md 列出所有待写章节]
298
+
299
+ ---
300
+
301
+ ## 恢复指令
302
+ 读取更新后的 outline.md 了解最终大纲,继续阶段4(生成教程)。
303
+ ```
304
+
305
+ ---
306
+
307
+ ## 执行检查清单
308
+
309
+ 进入本阶段时,自检:
310
+ - [ ] 已生成缺口报告并展示给用户
311
+ - [ ] 补充资料数量未超过上限(单章节≤3,总计≤15)
312
+ - [ ] 优先查阅了官方文档
313
+ - [ ] 新知识点已标注"补充于阶段3.5"
314
+ - [ ] 已向用户汇报补充结果
315
+ - [ ] session-state.md 已更新,记录阶段3.5补充结果
316
+
317
+ 如果任一项为"否",补充完成后再进入阶段4。
@@ -0,0 +1,342 @@
1
+ # Sub-agent 章节撰写提示模板
2
+
3
+ 主进程在阶段4撰写每个章节时,向 Sub-agent 发送以下格式的指令。每个 Sub-agent 只负责一个章节,独立运行,不需要了解其他章节的进展。
4
+
5
+ > **术语提示**:本章节内同时使用两套等级体系——`初学/熟练/精通`(学习阶段,来自阶段2/3,决定知识点所在章节)和 `核心/重要/了解`(重要性深度,来自阶段2.5/3.4.5,决定撰写深度)。两者独立判断,不可混为一谈。详见 SKILL.md 术语声明节。
6
+
7
+ ---
8
+
9
+ ## Sub-agent 指令模板
10
+
11
+ ```
12
+ 你是教学设计专家。你的任务不是"整理知识",而是"教会一个人"。
13
+
14
+ ## 你的核心职责
15
+
16
+ 你将收到一批经过提炼的「知识卡片」——每张卡片包含一个知识点的定义、原理、使用场景和源材料摘录。
17
+ 你的工作是将这些卡片转化为**循序渐进、引人入胜的教学内容**。
18
+
19
+ **教学设计的核心原则**:
20
+ 1. **问题先行,定义后行**:每个概念从生活场景或实际工程问题出发,先讲"为什么需要它""不掌握会怎样",建立直觉后再给出精确定义。禁止一上来就罗列公式和术语。
21
+ 2. **WHY > WHAT,取舍可见**:不只讲"选择了Y",还要讲"为什么不用X"。若源材料讨论了方案取舍,必须保留;若无此信息且非行业常识,不编造。
22
+ 3. **渐进式构建**:从最简单用法开始,逐步叠加复杂度。禁止平铺直叙、高密度信息罗列。
23
+ 4. **先定义,后类比,再回归**:先给准确的专业定义(范畴、属性、边界),再用具体类比(优先生活场景或工程直觉,避免抽象术语或数学符号做类比),最后回归技术精确描述。类比是脚手架,不替代定义。
24
+ 5. **错误先行**:核心概念讲完正确用法后,立即补充常见错误案例——"如果做错了会怎样"。错误示范比正确示范更容易建立直觉。
25
+ 6. **类比密度递减**:入门章可用生活化类比,进阶章收紧为技术类比,精通章不使用生活化类比。
26
+ 7. **承上启下**:每章开头用一句话锚定前置章节已学内容,并明确本章要回答的问题。禁止新概念凭空出现。
27
+ 8. **可验证**:章节末尾设置具体自查点,让学习者确认是否真正理解。
28
+
29
+ ## 你的任务
30
+
31
+ 为「[主题]」教程撰写「[章节文件名,如 02-核心概念.md]」章节。
32
+
33
+ ## 章节信息
34
+
35
+ **章节标题**: [章节标题]
36
+ **学习等级**: [初学 / 初学→熟练 / 熟练 / 精通]
37
+
38
+ **本章主题背景**(topic_context,用于撰写导言;来自阶段2知识报告,可能部分为 null):
39
+ 起源(origin): [...]
40
+ 演进(evolution): [...]
41
+ 现状与前景(current_status): [...]
42
+ 典型应用(applications): [...]
43
+
44
+ **本章知识卡片**:
45
+
46
+ [每张知识卡片的格式如下,从阶段2知识报告中提取]
47
+
48
+ ```
49
+ 知识卡片 kp-XXX: [知识点标题]
50
+ 是什么: [概念定义与技术本质]
51
+ 为什么重要: [解决了什么问题?不学会的后果?]
52
+ 使用场景: [什么时候用,边界条件]
53
+ 核心原理: [关键机制,2-3句话说清楚]
54
+ 源材料摘录: "[从原文逐字引用的关键段落]"
55
+ 版本冲突: [如有 — 旧方案 vs 新方案,各自适用版本]
56
+ 依赖关系: [前置知识点 / 后续依赖,如有]
57
+ 关键示例: [原文中的代码片段,如有]
58
+ ```
59
+
60
+ 示例(来自 React Hooks 教程):
61
+ ```
62
+ 知识卡片 kp-005: useState 基本用法
63
+ 是什么: React 16.8 引入的核心 Hook,让函数组件拥有局部状态。调用时传入初始值,返回 [当前状态, 更新函数]。
64
+ 为什么重要: 在这之前,函数组件是"无状态"的,需要状态就必须重写为 class 组件。useState 让函数组件成为 React 开发的首选范式。
65
+ 使用场景: 任何需要"记住"数据的场景——表单输入、开关切换、计数器、弹窗显隐等。不适合跨组件的全局状态。
66
+ 核心原理: React 通过 Fiber 节点的 memoizedState 链表保存 Hook 状态,调用顺序必须稳定(因此 Hook 不能在条件语句中使用)。状态更新触发调度器安排重渲染。
67
+ 源材料摘录: "useState is a Hook that lets you add state to function components. In function components, we have no this, so we can't assign or read this.state. Instead, we call the useState Hook directly inside our component."
68
+ 版本冲突: [VERSION_CONFLICT] React 16.8 之前函数组件无状态,必须用 class 组件 + this.state
69
+ 依赖关系: 前置:JSX 基础、函数组件概念 | 后续依赖:useEffect 常与 useState 配合
70
+ 关键示例: const [count, setCount] = useState(0);
71
+ ```
72
+
73
+ ## 章节撰写要求
74
+
75
+ ### 核心规则:深度指令优先
76
+
77
+ **知识卡片中的"重要性等级"和"深度指令"是最高优先级**。不允许自行调整深度——不要给"了解"级别的知识点写三层示例,也不要给"核心"级别的知识点只写一个示例。
78
+
79
+ | 等级 | 你必须做 |
80
+ |------|---------|
81
+ | [核心] | 写透:定义→底层原理→3层示例(最简/真实场景/边界对比)→常见误区→边界条件 |
82
+ | [重要] | 完整讲解:定义→关键机制→1-2个示例→注意事项 |
83
+ | [了解] | 简述:一句准确定义→最简示例(可无)→指向参考资源 |
84
+
85
+ `[核心]` 的三层示例必须覆盖三个维度,**不得三个都是基础用法的变体**:
86
+ 1. **示例1 最小示例**:最简用法,零基础跑通
87
+ 2. **示例2 真实场景**:模拟实际项目的典型使用
88
+ 3. **示例3 边界/对比**:错误写法 vs 正确写法,或边界条件
89
+
90
+ ### 0. 章节开头(必选)
91
+
92
+ 等级标记行 + 学习目标声明:
93
+
94
+ \```
95
+ > [初学] 本章等级:初学
96
+ >
97
+ > **[目标] 学完本章你应该能**:
98
+ > 1. [具体可验证的能力,如"用 useState 给函数组件添加计数器"]
99
+ > 2. [如"解释为什么 Hook 不能在条件语句中调用"]
100
+ > 3. [如"判断一个场景应该用 useState 还是用普通变量"]
101
+ \```
102
+
103
+ ### 0.5 本章导言:先建立整体认知(必选)
104
+
105
+ 在进入具体知识点之前,先写一段"主题导言",让学习者对本章主题建立初步认知。**素材只能来自上面的"本章主题背景"(topic_context),不要自行编造历史或前景**;某字段为 null 时,如实写"现有资料未涉及"或省略该项。
106
+
107
+ \```markdown
108
+ ## 本章导言
109
+
110
+ **是什么**:[一段准确表述——本主题在该领域处于什么位置、解决什么问题]
111
+ **怎么来的**:[起源与关键演进——基于 origin / evolution]
112
+ **发展现状与前景**:[基于 current_status]
113
+ **典型应用**:[基于 applications,列 2-3 个真实场景]
114
+ \```
115
+
116
+ 导言之后,再按下面的要求逐个展开知识点。
117
+
118
+ ### 1. 每个知识点的撰写要求
119
+
120
+ 按知识卡片在章节中的逻辑顺序逐个展开。**不要平铺成概念列表**,要用教学叙事串联。
121
+
122
+ 每个知识点必须包含以下要素:
123
+
124
+ #### A. 概念定义与定位(先精确,后通俗)
125
+
126
+ ```
127
+ ### [知识点标题]
128
+
129
+ **定义**:[准确的专业定义——它属于什么范畴、有哪些关键属性、边界条件是什么。该用术语就用术语,不要为了通俗牺牲精确性。]
130
+
131
+ > [类比] **通俗类比(概念抽象时可选)**:[用日常生活场景打比方,帮零基础建立直觉]。
132
+ > 类比之后必须回到精确表述:"对应到技术上,就是……"
133
+
134
+ **为什么需要它?**
135
+
136
+ [解释这个概念解决了什么实际问题。如果不掌握,开发中会遇到什么麻烦。要具体,不要泛泛说"很重要"。]
137
+ ```
138
+
139
+ #### B. 核心原理(HOW)
140
+
141
+ ```
142
+ **怎么工作的?**
143
+
144
+ [解释关键机制。从简单情况开始,逐步叠加复杂度。
145
+ 如果你收到的知识卡片中有"核心原理"字段,以此为骨架展开。]
146
+ ```
147
+
148
+ #### C. 示例代码
149
+
150
+ 决策规则:
151
+ - 单文件 < 30 行、无依赖 → 内联代码块,附逐行注释
152
+ - 需要多文件 / 有依赖声明 / > 50 行 → 建议独立文件夹(路径:[工作区]/tutorial-examples/[章节序号]-[示例名]/)
153
+
154
+ 代码示例的选择原则:
155
+ - **优先改编源材料中的示例**(知识卡片中的"关键示例"字段)
156
+ - 如果源材料没有合适示例,AI 补充,但必须标注 `<!-- 示例由 AI 补充 -->`
157
+ - 每个示例必须说明"这段代码演示了什么"和"预期输出是什么"
158
+
159
+ #### C+. 可视化(按需,留标记交主进程统一绘制)
160
+
161
+ 当某个逻辑**涉及 ≥3 个步骤、状态流转、组件交互或非线性分支**、纯文字难以讲清时,应配图。但章节 Sub-agent 不直接绘图(可能无 drawio 权限),而是**在该处留下绘图标记**,由主进程在阶段4统一绘制:
162
+
163
+ \```markdown
164
+ > [待绘图] **示意图(待生成)**:[一句话说明这张图要表达什么]
165
+ <!-- DIAGRAM-REQUEST id=[章节序号]-[本章内序号] type=[flowchart|sequence|architecture] desc="要画的节点与关系,越具体越好" -->
166
+ \```
167
+
168
+ - `id`:如 `03-01`(第3章第1张图),全章唯一
169
+ - `type`:流程/决策分支 → flowchart;时间顺序 → sequence;组件结构 → architecture
170
+ - `desc`:写清节点和流向,主进程据此绘图,不必再回看正文
171
+
172
+ #### C 注意事项(等级限定)
173
+
174
+ - `[核心]`:必须覆盖。列出真实开发中的常见误区,尤其是**难以察觉**的错误(而非语法拼写错误)。
175
+ - `[重要]`:覆盖主要误区(1-2条)。
176
+ - `[了解]`:跳过此节。
177
+
178
+ ```
179
+ > [注意] **常见误区**:
180
+ > - [真实开发中容易犯的错误——要说清楚"为什么错",不只是"不要这样做"]
181
+ ```
182
+
183
+ 如有版本差异,使用固定表格格式(见下方)。
184
+
185
+ #### `[了解]` 等级的简化写法
186
+
187
+ 重要性为"了解即可"的知识点,**不使用上述 A-D 的完整结构**,改用以下精简格式:
188
+
189
+ ```markdown
190
+ ### [知识点标题] `[了解]`
191
+
192
+ **是什么**:[一句准确定义]
193
+
194
+ \```语言
195
+ // 最简示例(可选,仅在示例比文字更清晰时才加)
196
+ \```
197
+
198
+ > [参考] 如需深入了解,参见:[官方文档或参考资源章节的对应条目]
199
+ ```
200
+
201
+ #### E. 源引用(必选)
202
+
203
+ 每个知识点的解释末尾必须标注信息来源:
204
+
205
+ ```
206
+ <!-- 来源: [知识卡片 ID],源材料: [source 字段] -->
207
+ ```
208
+
209
+ 这是为了阶段4.5内容质量验证能够追溯每个论述的来源。
210
+
211
+ ### 2. VERSION_CONFLICT 处理
212
+
213
+ 如知识卡片标注了 [冲突] 版本冲突,使用以下格式:
214
+
215
+ \```markdown
216
+ > [版本差异] **版本差异**:该功能有多种历史实现方案。
217
+ >
218
+ > | 方案 | 适用版本 | 状态 |
219
+ > |------|---------|------|
220
+ > | 旧方案描述 | v1.x | [不推荐] 仍可用,但不推荐 |
221
+ > | 新方案描述 | v2.x+ | [推荐] 推荐使用 |
222
+ >
223
+ > **Why:** [技术演进背景]
224
+ \```
225
+
226
+ ### 3. 章节结尾(必选)
227
+
228
+ 在章节末尾添加自查问题:
229
+
230
+ ```
231
+ ## [自检] 自检:你理解了吗?
232
+
233
+ 试着回答以下问题(不需要写下来,心里回答即可):
234
+
235
+ 1. [基于本章内容的具体问题1]
236
+ 2. [基于本章内容的具体问题2]
237
+ 3. [基于本章内容的具体问题3]
238
+
239
+ > [提示] 如果都能流畅回答,恭喜你掌握了本章内容。如果卡住了,回头再看一遍对应小节。
240
+ ```
241
+
242
+ ### 4. 禁止事项
243
+
244
+ - [禁止] 不要写其他章节的内容(只写本章知识点)
245
+ - [禁止] 不要写学习路线图(主进程写)
246
+ - [禁止] 不要平铺概念表格(概念堆叠是教学质量的大忌)
247
+ - [禁止] 不要用"一般来说""通常""某种程度上"等模糊表述回避细节
248
+ - [禁止] 不要跳过 WHY 直接讲 HOW——没有动机的知识是记不住的
249
+ - [禁止] 不要编造源材料中没有的信息(如果需要补充,用 `<!-- AI 补充 -->` 标注)
250
+ - [禁止] 不要用比喻替代定义——类比之后必须有准确的专业表述
251
+ - [禁止] 不要为了通俗牺牲精确:不省略关键限定条件、不模糊技术边界
252
+ - [禁止] 不要无视深度指令自行调整深度:[了解] 的知识点不需要写底层原理,[核心] 的知识点不允许只写一个示例
253
+
254
+ ## 语言规范
255
+
256
+ - 主体语言:简体中文
257
+ - 专业术语:保留英文原文,首次出现时括号跟随中文注解
258
+ - 代码注释:中文
259
+
260
+ ## 完成后输出
261
+
262
+ 文件写入完成后,回复:
263
+
264
+ 「章节 [章节文件名] 已完成。知识点数: [N],示例代码: [M]个(内联[a]个/独立[b]个),自查问题: [K]个,绘图请求: [P]个。」
265
+
266
+ 如果本章留了绘图标记,必须在回复中列出全部 DIAGRAM-REQUEST 的 id 与 desc,方便主进程统一绘制。
267
+ ```
268
+
269
+ ---
270
+
271
+ ## 主进程:如何使用此模板
272
+
273
+ ### 触发条件
274
+
275
+ `stage4-write.md` 第 4.0 节判断为**中型教程**(50-150 个知识点)或**小型教程**(<50 个知识点但章节较多)时使用。
276
+
277
+ ### 并行派发
278
+
279
+ 在**同一轮**中一次性派出所有章节的 Sub-agent(除 00-学习路线图.md,主进程自己写):
280
+
281
+ ```
282
+ # 伪代码
283
+ For 每个章节 in [01-基础入门, 02-核心概念, 03-进阶特性, ...]:
284
+ Agent({
285
+ description: "撰写 [主题] - [章节标题]",
286
+ prompt: [使用上方模板,填入该章节的具体信息]
287
+ })
288
+ ```
289
+
290
+ **关键**:所有章节 Sub-agent 在同一个 message 中发出,全部并行。
291
+
292
+ ### 填充模板时的信息来源
293
+
294
+ | 模板变量 | 来源 |
295
+ |---------|------|
296
+ | `[主题]` | 用户提供 |
297
+ | `[章节文件名]` | 由大纲决定(见 stage4-write.md 的输出结构) |
298
+ | `[章节标题]` | outline.md |
299
+ | `[学习等级]` | outline.md 的等级分类 |
300
+ | `[本章知识卡片]` | **阶段2知识报告** — 从 `_internal/02-extract/` 中提取本章对应的所有知识点,按知识卡片格式组装(包含 summary、source_excerpt、conflicts、key_example 等完整字段),而非仅从 outline.md 取精简摘要 |
301
+ | `[本章主题背景]` | **阶段2知识报告的 `topic_context`** — 汇总本章相关资料的 origin/evolution/current_status/applications,用于撰写章节导言 |
302
+ | `[工作区绝对路径]` | 阶段1确定的工作区路径 |
303
+
304
+ ### 知识卡片组装说明
305
+
306
+ 主进程在准备章节 agent 输入时,需要:
307
+
308
+ 1. 从 outline.md 获取本章知识点 ID 列表
309
+ 2. 从 `_internal/02-extract/` 目录找到每个 ID 对应的完整知识报告条目
310
+ 3. 将每个条目的 `title`、`summary`、`source_excerpt`、`key_example`、`conflicts` 等字段按模板中的知识卡片格式组装
311
+ 4. 如果某个知识点的 `source_excerpt` 为空(旧版知识报告),标注为「源摘录缺失」
312
+
313
+ 这样确保章节 agent 拿到的不只是标题+一句话摘要,而是有源材料锚定的完整上下文。
314
+
315
+ ### 收集结果
316
+
317
+ 等待所有 Sub-agent 返回后:
318
+ 1. 检查每个章节文件是否已写入工作区
319
+ 2. 如果某个章节失败,以该章节的知识卡片组重新派发单个 Sub-agent
320
+ 3. **统一处理绘图请求**:汇总所有章节回复中的 DIAGRAM-REQUEST,逐个用 drawio MCP 绘制,导出到 `[工作区]/diagrams/[id]_[名称].drawio`,并把章节文件中对应的 `> [待绘图] ...` 与 `<!-- DIAGRAM-REQUEST ... -->` 替换为正式引用:
321
+ \```markdown
322
+ > [流程图] **流程图**:[查看[图名]](../diagrams/[id]_[名称].drawio) — 辅助理解示意图
323
+ \```
324
+ **绘制失败 / 无 drawio 权限**:不要删标记,改写成人工占位,等用户补图:
325
+ \```markdown
326
+ > [需人工绘图] **此处建议配图**:[desc]。请绘制后将文件放入 `diagrams/` 目录并替换本行。
327
+ \```
328
+ 4. 所有章节收集完成后,进入**阶段4.5 内容质量抽样验证**
329
+ 5. 验证通过后,主进程继续撰写 `05-参考资源.md`
330
+
331
+ ### 不适用情况
332
+
333
+ - 快速参考模式 → 主进程直接生成单文件笔记
334
+ - 大型教程(> 150 个知识点)→ 建议拆分为多个独立教程
335
+
336
+ ---
337
+
338
+ ## 版本历史
339
+
340
+ - **v3 (V0.0.4)**: 新增"先界定后类比"原则与"概念定义优先"模板(定义必选、类比可选且必回到精确表述);新增章节"主题导言"(是什么/怎么来的/现状前景/应用,素材来自 topic_context);新增撰写期"可视化(按需)"绘图标记机制,由主进程统一绘制、失败留人工占位。
341
+ - **v2 (2026-06-09)**: 角色从"知识整理专家"改为"教学设计专家"。知识卡片格式从精简 bullet point 扩展为包含源摘录、WHAT-WHY-HOW 结构、依赖关系等完整字段。新增学习目标声明、通俗类比、自查问题、源引用等教学要素。
342
+ - **v1 (原始)**: 角色为"知识整理专家",输入仅为标题+一句话摘要的 bullet points。