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,322 @@
1
+ # 常见错误对照表
2
+
3
+ 执行过程中遇到问题时,先查阅本文件。
4
+
5
+ ---
6
+
7
+ ## 来源质量问题
8
+
9
+ ### 错误1:收集到的都是二手摘要,没有一手资料
10
+
11
+ **表现**:
12
+ - 阶段1结束时,发现所有资料都是"某某博客转载"、"技术公众号整理"
13
+ - 资料中大量"据说"、"有人认为",没有明确出处
14
+
15
+ **根因**:
16
+ - 没有优先使用 `context7:query-docs` 查官方文档
17
+ - 搜索关键词不当,搜到的都是二手整理
18
+
19
+ **解决方案**:
20
+ 1. 停止进入阶段2,返回阶段1
21
+ 2. 使用 `context7:query-docs` 搜索官方文档
22
+ 3. 如果官方文档不足,使用 `exa:web_search_exa` 时增加过滤条件:
23
+ - 权重偏好:官方站点 > Medium > Dev.to > 个人博客
24
+ - 时间过滤:最近3年内
25
+ - 排除关键词:"转载"、"整理自"
26
+
27
+ **预防措施**:
28
+ - 阶段1结束时,检查来源类型分布(参见 `rules/quality-gates.md`)
29
+ - 至少1份一手资料,三手资料占比 <50%
30
+
31
+ ---
32
+
33
+ ## Sub-agent 使用问题
34
+
35
+ ### 错误2:主进程直接读取原始 URL
36
+
37
+ **表现**:
38
+ - 主进程直接调用 `fetchWebContent` 读取长篇文章
39
+ - 上下文在阶段2后迅速膨胀
40
+
41
+ **根因**:
42
+ - 违反核心原则"主进程不直接读原文"
43
+ - 误认为"只是读一下,不会占用太多上下文"
44
+
45
+ **解决方案**:
46
+ 1. 立即停止读取
47
+ 2. 为该资料派发 Sub-agent,使用 `references/sub-agent-prompt.md` 的标准指令
48
+ 3. 等待 Sub-agent 返回 JSON 知识报告
49
+
50
+ **预防措施**:
51
+ - 阶段2开始前,重读 `rules/core-principles.md`
52
+ - 只有资料 <500 字时才允许主进程直接读取
53
+
54
+ ---
55
+
56
+ ### 错误3:Sub-agent 串行派发,而非并行
57
+
58
+ **表现**:
59
+ - 依次为每份资料派发 Sub-agent,等上一个完成后再派发下一个
60
+ - 总耗时 = 单个 Sub-agent 耗时 × 资料数量
61
+
62
+ **根因**:
63
+ - 误解"并行"的含义
64
+ - 担心并行派发会导致混乱
65
+
66
+ **解决方案**:
67
+ - 在同一个 message 中为所有资料各派发一个 Sub-agent
68
+ - 示例(伪代码):
69
+ ```
70
+ Agent({
71
+ description: "提取资料1知识",
72
+ prompt: [使用 sub-agent-prompt.md 模板,资料=资料1]
73
+ })
74
+ Agent({
75
+ description: "提取资料2知识",
76
+ prompt: [使用 sub-agent-prompt.md 模板,资料=资料2]
77
+ })
78
+ ...
79
+ ```
80
+
81
+ **预防措施**:
82
+ - 阶段2开始前,重读 `rules/core-principles.md` 的"Sub-agent 必须并行启动"
83
+
84
+ ---
85
+
86
+ ## 冲突处理问题
87
+
88
+ ### 错误4:两份资料矛盾,静默选择了新的
89
+
90
+ **表现**:
91
+ - 阶段3合并大纲时,发现资料A说方案X,资料B说方案Y
92
+ - 直接选择了资料B的方案Y,理由是"B更权威"或"B更新"
93
+ - 大纲中没有标注 `[VERSION_CONFLICT]`
94
+
95
+ **根因**:
96
+ - 违反核心原则"矛盾必须保留"
97
+ - 误认为"消除矛盾"是任务目标
98
+
99
+ **解决方案**:
100
+ 1. 回退到合并大纲前的状态
101
+ 2. 重新执行分级三问,保留双方观点
102
+ 3. 使用 `rules/output-format.md` 的版本冲突格式标注
103
+
104
+ **预防措施**:
105
+ - 阶段3开始前,重读 `rules/core-principles.md` 的"矛盾必须保留"
106
+ - 看到"但是"、"不过"、"然而"等转折词时,停下来思考是否遇到了冲突
107
+
108
+ ---
109
+
110
+ ## 版本混淆问题
111
+
112
+ ### 错误5:把不同时代的方案混在一起
113
+
114
+ **表现**:
115
+ - 教程中同时出现 jQuery 的 `$.ajax` 和现代 `fetch` API,没有说明各自适用场景
116
+ - 没有在大纲中按 `tech_era` 隔离分组
117
+
118
+ **根因**:
119
+ - Sub-agent 知识报告中的 `tech_era` 字段为空或被忽略
120
+ - 阶段3合并时没有检查技术年代差异
121
+
122
+ **解决方案**:
123
+ 1. 回到阶段3,检查所有知识点的 `tech_era` 字段
124
+ 2. 将不同 `tech_era` 的同名概念强制隔离:
125
+ ```markdown
126
+ ## AJAX 请求方式
127
+
128
+ ### jQuery 时代(2016年前)
129
+ [描述 $.ajax 用法]
130
+
131
+ ### 现代浏览器(ES6+)
132
+ [描述 fetch API 用法]
133
+
134
+ > [版本差异] **版本差异**:现代项目推荐使用 `fetch`,jQuery 方案仍可用但不推荐。
135
+ ```
136
+
137
+ **预防措施**:
138
+ - 阶段2派发 Sub-agent 时,强调 `tech_era` 字段的重要性
139
+ - 阶段3分级三问第2问增加检查:"是否来自不同技术年代?"
140
+
141
+ ---
142
+
143
+ ## 撰写问题
144
+
145
+ ### 错误6:章节写不下去却强行填充
146
+
147
+ **表现**:
148
+ - 某段话反复改写多次,仍不满意
149
+ - 写出了自己无法解释的内容
150
+ - 用模糊的词汇("一般来说"、"通常"、"某种程度上")回避细节
151
+
152
+ **根因**:
153
+ - 触发了卡顿信号但没有识别(参见 `rules/quality-gates.md`)
154
+ - 误认为"必须写完才能停"
155
+
156
+ **解决方案**:
157
+ 1. 立即停止当前章节撰写
158
+ 2. 识别卡顿原因:
159
+ - 来源不足? → 返回阶段2,针对该子主题补充搜索
160
+ - 概念理解不透? → 返回阶段1,查阅一手资料
161
+ - 需要新资料? → 进入阶段3.5补充搜索
162
+ 3. 向用户报告:"我在撰写'第X章'时遇到卡顿 — [原因]。建议[解决方案],是否同意?"
163
+
164
+ **预防措施**:
165
+ - 阶段4开始前,重读 `rules/quality-gates.md` 的"卡顿信号"章节
166
+ - 写作过程中主动自检:"我能用口语向别人解释这段内容吗?"
167
+
168
+ ---
169
+
170
+ ### 错误7:分级三问变成过滤器
171
+
172
+ **表现**:
173
+ - 阶段3合并大纲时,剔除了"太简单"的知识点
174
+ - 初学阶段章节很少,直接从熟练阶段开始
175
+
176
+ **根因**:
177
+ - 误解分级三问的目的(是分类,不是过滤)
178
+ - 认为"简单的内容不值得写进教程"
179
+
180
+ **解决方案**:
181
+ 1. 回退到阶段3开始前
182
+ 2. 重新执行分级三问,所有知识点都应进入大纲
183
+ 3. 特别注意:初学阶段内容宁多勿少
184
+
185
+ **预防措施**:
186
+ - 阶段3开始前,重读 `rules/core-principles.md` 的"分级三问是分类工具"
187
+ - 自检:"我是否剔除了某个知识点?原因是什么?"
188
+
189
+ ---
190
+
191
+ ## 迭代问题
192
+
193
+ ### 错误8:阶段5.5 所有反馈都用"通俗解释"处理
194
+
195
+ **表现**:
196
+ - 用户反馈"工作方式不清楚",只增加了通俗解释,没有绘图
197
+ - 用户反馈"参数太多",只解释了参数含义,没有制作对照表
198
+
199
+ **根因**:
200
+ - 没有读取 `references/feedback-types.md` 进行反馈类型匹配
201
+ - 用单一策略处理所有反馈
202
+
203
+ **解决方案**:
204
+ 1. 回到收到用户反馈的时刻
205
+ 2. 读取 `references/feedback-types.md`,识别反馈类型
206
+ 3. 按优先级执行对应策略(流程类 → 必须绘图)
207
+
208
+ **预防措施**:
209
+ - 阶段5.5开始前,在 TODO list 中加入:"收到反馈后,先读 feedback-types.md"
210
+ - 流程类反馈必须调用 drawio MCP,不能用纯文字替代
211
+
212
+ ---
213
+
214
+ ### 错误9:流程类反馈用纯文字描述
215
+
216
+ **表现**:
217
+ - 用户说"git stash 工作方式不清楚"
218
+ - 只写了一段"首先...然后...最后..."的文字描述
219
+ - 没有调用 drawio MCP 绘制流程图
220
+
221
+ **根因**:
222
+ - 违反阶段5.5的强制规则"流程类反馈必须绘图"
223
+ - 低估了流程图的价值
224
+
225
+ **解决方案**:
226
+ 1. 删除纯文字描述(或保留作为补充)
227
+ 2. 调用 drawio MCP 绘制流程图
228
+ 3. 导出 .drawio 文件到 `diagrams/` 目录
229
+ 4. 在教程中插入引用(参见 `references/feedback-types.md`)
230
+
231
+ **预防措施**:
232
+ - 看到"工作方式"、"执行流程"、"怎么运行"等关键词 → 立即想到"必须绘图"
233
+ - 全局 CLAUDE.md 已强制 drawio 触发规则,遵守即可
234
+
235
+ ---
236
+
237
+ ## 其他问题
238
+
239
+ ### 错误10:示例代码无法运行
240
+
241
+ **表现**:
242
+ - 用户反馈"示例代码报错"
243
+ - 代码中有未定义的变量、缺失的依赖
244
+
245
+ **根因**:
246
+ - 没有遵守 `references/example-structures.md` 的质量标准
247
+ - 示例代码是"伪代码"而非"可运行代码"
248
+
249
+ **解决方案**:
250
+ 1. 检查示例代码是否满足:
251
+ - [通过] 可以直接运行(或按 README 说明运行)
252
+ - [通过] 有清晰的注释
253
+ - [通过] 依赖已声明(如 package.json)
254
+ 2. 如果不满足,修正后重新生成示例
255
+
256
+ **预防措施**:
257
+ - 阶段4写示例代码前,重读 `references/example-structures.md`
258
+ - 自检:"我能在本地运行这段代码吗?"
259
+
260
+ ---
261
+
262
+ ### 错误11:最终通读由 AI 完成
263
+
264
+ **表现**:
265
+ - 阶段6输出教程后,AI 自己又读了一遍并说"我检查过了,没问题"
266
+ - 没有等待用户反馈
267
+
268
+ **根因**:
269
+ - 违反核心原则"最终通读是用户的工作"
270
+ - 误认为"自我审阅"是负责任的表现
271
+
272
+ **解决方案**:
273
+ 1. 停止自我审阅
274
+ 2. 向用户说明:"终极教程已完成,请您通读验收。"
275
+ 3. 等待用户反馈
276
+
277
+ **预防措施**:
278
+ - 阶段6开始前,重读 `rules/core-principles.md` 的"最终通读是用户的工作"
279
+ - 提醒自己:"用户才是学习者,他们的理解障碍才是真实信号"
280
+
281
+ ---
282
+
283
+ ### 错误12:一次大补丁修改多处,部分未匹配导致文件损坏
284
+
285
+ **症状**:
286
+ - 用一个补丁同时修改文件多个位置,其中几处未匹配原文
287
+ - 未匹配的内容被追加到文件末尾或列表符号丢失,文件结构损坏
288
+
289
+ **解决方案**:
290
+ 1. 小步修改:每次补丁只改一处,应用成功再改下一处
291
+ 2. 每处修改后读回该区域验证(不要凭"修改成功"的返回就假设结果正确)
292
+ 3. 发现损坏后,先完整读取受影响区域再修复,不要继续叠加补丁
293
+
294
+ **预防措施**:
295
+ - 跨文件、跨区域的批量修改拆成独立步骤执行
296
+ - 对长文件的修改先读目标区域,确认待替换文本精确匹配
297
+
298
+ ---
299
+
300
+ ## 快速诊断流程
301
+
302
+ ```
303
+ 遇到问题
304
+ ↓
305
+ 是阶段几的问题?
306
+ ↓
307
+ ├─ 阶段1(收集资料)→ 查"来源质量问题"
308
+ ├─ 阶段2(Sub-agent)→ 查"Sub-agent 使用问题"
309
+ ├─ 阶段3(合并大纲)→ 查"冲突处理问题"或"版本混淆问题"
310
+ ├─ 阶段4(撰写教程)→ 查"撰写问题"
311
+ ├─ 阶段5.5(交互完善)→ 查"迭代问题"
312
+ └─ 其他 → 查"其他问题"
313
+ ```
314
+
315
+ ---
316
+
317
+ ## 未列出的问题
318
+
319
+ 如果遇到本文未列出的问题:
320
+ 1. 检查是否违反了 `rules/` 目录下的任一硬规则
321
+ 2. 查阅对应阶段的 `workflows/` 文件
322
+ 3. 如果仍无法解决,向用户报告:"我遇到了[问题描述],这不在已知坑点列表中。建议暂停,由您判断如何处理。"
@@ -0,0 +1,222 @@
1
+ # Sub-agent 知识提取指令模板
2
+
3
+ 阶段2派发 Sub-agent 前,必须使用此模板。
4
+
5
+ ---
6
+
7
+ ## 标准指令格式
8
+
9
+ ```
10
+ 你是知识提取专家。请深度阅读以下资料,提取所有知识点,输出一份结构化「知识报告」。
11
+
12
+ 资料来源:[文件路径 / URL]
13
+ 资料处理:[直接读取 / 使用 fetchWebContent 抓取]
14
+ 主题领域:[学习主题]
15
+ 来源类型:[一手 / 二手 / 三手]
16
+
17
+ 输出严格按照以下 JSON,不输出其他内容:
18
+
19
+ {
20
+ "source": "资料标题或 URL",
21
+ "source_type": "primary | secondary | tertiary",
22
+ "tech_era": "技术年代,如 '2016年前 jQuery 时代' 或 '现代 React 18+',无法判断则填 null",
23
+ "topic_context": {
24
+ "origin": "该资料主题怎么来的:诞生背景、解决的历史问题(基于原文,无则 null,不臆造)",
25
+ "evolution": "关键演进/版本脉络(基于原文,无则 null)",
26
+ "current_status": "当前发展现状与前景:成熟度、主流程度、趋势(基于原文,无则 null)",
27
+ "applications": "典型应用场景:被用在哪些真实场景(基于原文,无则 null)"
28
+ },
29
+ "knowledge_points": [
30
+ {
31
+ "id": "kp-001",
32
+ "title": "知识点标题",
33
+ "level": "初学 | 熟练 | 精通",
34
+ "summary": "4-6句话:是什么 + 为什么重要 + 什么时候用 + 怎么用(关键原理)。下游将仅凭此报告撰写教程,信息量必须足够。",
35
+ "source_excerpt": "从原文直接摘录的关键段落(50-200字),用于下游阶段验证事实准确性。必须逐字引用,不要改写。",
36
+ "key_example": "最能说明该知识点的代码片段(可选,如原文有)",
37
+ "is_domain_specific": true
38
+ }
39
+ ],
40
+ "conflicts": [
41
+ {
42
+ "topic": "冲突的知识点主题",
43
+ "this_doc_says": "本资料的观点/方案",
44
+ "conflict_type": "version_diff | deprecated | approach_diff",
45
+ "evidence": "本资料给出的依据"
46
+ }
47
+ ],
48
+ "coverage_gaps": ["本资料明显缺失但该主题应涵盖的内容"]
49
+ }
50
+ ```
51
+
52
+ ---
53
+
54
+ ## 字段说明
55
+
56
+ ### source_type(来源类型)
57
+
58
+ | 值 | 含义 | 示例 |
59
+ |---|------|------|
60
+ | `primary` | 一手资料 | 官方文档、RFC、创始人博客、源代码仓库 |
61
+ | `secondary` | 二手资料 | 知名技术博客、经过验证的教程、书籍 |
62
+ | `tertiary` | 三手资料 | 转载文章、未注明来源的博客、过时教程 |
63
+
64
+ ### tech_era(技术年代)
65
+
66
+ **目的**:识别知识点所处的技术时代,避免将不同年代的方案混淆。
67
+
68
+ **示例**:
69
+ - `"2016年前 jQuery 时代"` — DOM 操作主流用 jQuery
70
+ - `"ES6+ 现代 JavaScript"` — 箭头函数、Promise 成为标准
71
+ - `"React 18+ 并发特性时代"` — Suspense、useTransition 可用
72
+ - `null` — 无法判断或跨时代通用
73
+
74
+ **判断依据**:
75
+ - 文章发布时间
76
+ - 提到的框架版本
77
+ - 使用的语法特性(如 var vs let/const)
78
+
79
+ ### topic_context(主题背景,用于章节导言)
80
+
81
+ **目的**:为下游"主题导言"提供素材——让每章开头能交代"是什么 / 怎么来的 / 发展现状 / 应用情况",帮助学习者先建立初步认知。
82
+
83
+ **硬约束**:四个字段都必须基于原文。原文没有的填 null,**绝不根据先验知识臆造**起源或前景,否则会污染教程的事实性。
84
+
85
+ | 字段 | 采集内容 |
86
+ |------|---------|
87
+ | `origin` | 该主题/技术的诞生背景、解决的历史问题 |
88
+ | `evolution` | 关键演进节点、版本脉络 |
89
+ | `current_status` | 当前成熟度、主流程度、发展趋势 |
90
+ | `applications` | 典型应用场景、实际使用者 |
91
+
92
+ ### level(学习等级)
93
+
94
+ | 等级 | 判断依据 |
95
+ |------|---------|
96
+ | `初学` | 入门必须理解;是其他概念的前提;教程第一章通常涵盖的内容 |
97
+ | `熟练` | 日常开发频繁使用;不掌握无法完成实际项目 |
98
+ | `精通` | 底层原理、性能调优、高级设计模式;官方文档 Advanced 章节 |
99
+
100
+ **优先级**:如果一时难以判断,先归入 `熟练`,主进程会在阶段3重新分类。
101
+
102
+ ### conflict_type(冲突类型)
103
+
104
+ | 类型 | 含义 | 示例 |
105
+ |------|------|------|
106
+ | `version_diff` | 不同版本的实现方式差异 | Vue 2 vs Vue 3 的响应式系统 |
107
+ | `deprecated` | 旧方案已废弃 | React class component vs function component |
108
+ | `approach_diff` | 同一问题的不同解决思路 | CSS-in-JS vs CSS Modules |
109
+
110
+ ### is_domain_specific
111
+
112
+ - `true` — 该知识点专属于当前学习主题(如 React Hooks 专属于 React)
113
+ - `false` — 通用知识(如 JavaScript Promise 可用于任何 JS 项目)
114
+
115
+ ---
116
+
117
+ ## 提取要求
118
+
119
+ 你的核心使命:**从这份资料中提取足够丰富的信息,让下游的教学设计师仅凭你的报告就能撰写出有深度的教程章节。** 你的报告质量直接决定了最终教程的质量天花板。
120
+
121
+ ### 1. 完整性
122
+
123
+ - **不要遗漏**:即使某段内容看起来"太简单"或"不重要",也应提取
124
+ - **包含隐性知识**:如"最佳实践"、"常见误区"、"性能建议"
125
+ - **summary 必须有深度**:不能只是标题复述。必须包含四个方面:
126
+ - **是什么**(概念定义,技术本质)
127
+ - **为什么重要**(解决了什么问题?不学会有什么后果?)
128
+ - **什么时候用**(适用场景和边界条件)
129
+ - **怎么用**(核心用法/机制,2-3句话说清楚关键原理)
130
+ - **source_excerpt 必填**:从原文中摘取最能代表该知识点核心论述的段落(50-200字),用于下游验证事实准确性
131
+
132
+ ### 2. 准确性
133
+
134
+ - **原文为准**:summary 必须基于原文,不能根据你的先验知识补充
135
+ - **标注不确定**:如果原文描述模糊,在 summary 中注明"原文表述不清"
136
+ - **source_excerpt 逐字引用**:必须是原文的直接摘录,不要改写或概括
137
+
138
+ ### 3. 冲突识别
139
+
140
+ - **主动对比**:与你的先验知识对比,发现不一致时记录在 `conflicts`
141
+ - **不要自作主张**:不要判断对错,只记录"本资料怎么说"
142
+
143
+ ### 4. 缺口识别
144
+
145
+ - **横向对比**:根据主题领域,判断该资料是否遗漏了常见话题
146
+ - **示例**:一份"Python 异步编程"教程没有提到 `asyncio.gather`,应记录在 `coverage_gaps`
147
+
148
+ ### 5. 主题背景采集(topic_context)
149
+
150
+ - 通读资料后,为本资料覆盖的核心主题填写 `topic_context` 的四个字段
151
+ - **只写原文支持的内容**:起源、演进、现状、应用如原文未提及,对应字段填 null
152
+ - 这是章节导言的唯一可靠来源——宁可留 null,也不要用先验知识编造历史或前景
153
+
154
+ ---
155
+
156
+ ## 输出示例
157
+
158
+ ```json
159
+ {
160
+ "source": "React 官方文档 - Hooks 介绍",
161
+ "source_type": "primary",
162
+ "tech_era": "React 16.8+ Hooks 时代",
163
+ "topic_context": {
164
+ "origin": "Hooks 在 React 16.8(2019)引入,解决 class 组件逻辑复用难、生命周期逻辑分散的问题",
165
+ "evolution": "状态逻辑复用方案的演进:mixin → HOC / render props → Hooks",
166
+ "current_status": "已成为函数组件的主流范式,官方推荐默认使用",
167
+ "applications": "现代 React 项目的状态管理与副作用处理"
168
+ },
169
+ "knowledge_points": [
170
+ {
171
+ "id": "kp-001",
172
+ "title": "useState 基本用法",
173
+ "level": "初学",
174
+ "summary": "useState 是 React 16.8 引入的核心 Hook,用于在函数组件中添加局部状态。它解决了函数组件无法持有状态的根本限制,使得开发者无需将函数组件改写为 class 组件。当组件需要记住用户输入、切换开关、计数等交互数据时使用。useState 接收初始值,返回一个包含当前状态值和更新函数的数组,React 通过闭包机制保存状态并在状态变化时触发重渲染。",
175
+ "source_excerpt": "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.",
176
+ "key_example": "const [count, setCount] = useState(0);",
177
+ "is_domain_specific": true
178
+ },
179
+ {
180
+ "id": "kp-002",
181
+ "title": "状态更新的异步性",
182
+ "level": "熟练",
183
+ "summary": "React 中的 setState(包括 useState 的更新函数)不会立即修改状态值,而是将更新请求加入队列,在下次渲染时批量处理。这个设计是为了性能优化——避免每次状态变更都触发一次重渲染。理解这个异步性对于编写正确的状态更新逻辑至关重要:需要基于旧值计算新值时,必须使用函数式更新 `setCount(prev => prev + 1)` 而非直接 `setCount(count + 1)`,否则在连续更新时会读到过期的闭包值。",
184
+ "source_excerpt": "State updates may be asynchronous. React may batch multiple setState() calls into a single update for performance. Because this.props and this.state may be updated asynchronously, you should not rely on their values for calculating the next state.",
185
+ "key_example": "setCount(prevCount => prevCount + 1);",
186
+ "is_domain_specific": true
187
+ }
188
+ ],
189
+ "conflicts": [
190
+ {
191
+ "topic": "何时使用 useReducer 而非 useState",
192
+ "this_doc_says": "当状态逻辑复杂或涉及多个子值时使用 useReducer",
193
+ "conflict_type": "approach_diff",
194
+ "evidence": "官方文档明确建议复杂状态用 useReducer"
195
+ }
196
+ ],
197
+ "coverage_gaps": [
198
+ "没有提到 useState 的惰性初始化(传入函数避免重复计算)"
199
+ ]
200
+ }
201
+ ```
202
+
203
+ ---
204
+
205
+ ## 常见错误
206
+
207
+ | 错误 | 后果 | 正确做法 |
208
+ |------|------|---------|
209
+ | 只提取标题级概念,忽略段落细节 | 主进程无法撰写详细内容 | 每个段落的核心论点都应成为一个知识点 |
210
+ | summary 写成标题复述 | 阶段4 agent 无足够信息撰写教程,导致概念堆叠 | summary 必须包含"是什么+为什么重要+什么时候用+怎么用"四要素 |
211
+ | 不记录 conflicts | 主进程无法发现矛盾 | 与先验知识不一致时必须记录 |
212
+ | coverage_gaps 留空 | 主进程无法判断需要补充搜索 | 至少列出1-2个该领域常见但本资料未覆盖的话题 |
213
+ | source_excerpt 为空或改写 | 阶段4.5 内容质量验证无法对照源材料 | source_excerpt 必须是逐字引用的原文摘录 |
214
+ | topic_context 凭先验知识臆造 | 教程导言出现资料中没有的"起源/前景",事实性被污染 | 原文未提及就填 null,只写资料支持的背景 |
215
+
216
+ ---
217
+
218
+ ## 并行派发注意事项
219
+
220
+ - **同一轮启动**:主进程应在同一个 message 中为所有资料各派发一个 Sub-agent
221
+ - **独立上下文**:每个 Sub-agent 只看一份资料,不共享其他 Sub-agent 的结果
222
+ - **统一格式**:所有 Sub-agent 返回的 JSON 格式必须一致,方便主进程批量处理