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,111 @@
1
+ # 阶段4.2:生成独立参考文档
2
+
3
+ 在所有章节撰写完成后、内容质量验证之前,从教程正文中自动提取独立参考文档。这些文档独立于教程正文,方便用户日后快速查阅。
4
+
5
+ ---
6
+
7
+ ## 4.2.1 提取规则
8
+
9
+ 从已完成的教程章节文件中,按以下规则提取内容:
10
+
11
+ ### 术语表(`reference/GLOSSARY.md`)
12
+
13
+ **提取源**:所有章节中加粗或代码块标注的专业术语,以及首次出现时附带中文注解的英文术语。
14
+
15
+ **输出格式**:
16
+
17
+ ```markdown
18
+ # 术语表: {主题}
19
+
20
+ | 术语 | 英文 | 定义 | 首次出现 |
21
+ |------|------|------|---------|
22
+ | 容器 | Container | 一个隔离的用户空间实例,拥有独立的进程、网络、文件系统 | §2.1 |
23
+ | 镜像 | Image | 容器的只读模板,包含运行应用所需的代码、运行时、库 | §2.2 |
24
+ ```
25
+
26
+ ### 命令速查表(`reference/COMMANDS.md`)
27
+
28
+ **提取源**:所有章节的代码块中以 CLI 命令形式出现的行。
29
+
30
+ **输出格式**:
31
+
32
+ ```markdown
33
+ # 命令速查: {主题}
34
+
35
+ ## {类别1}
36
+ | 命令 | 作用 | 常用参数 |
37
+ |------|------|---------|
38
+ | docker build -t name . | 构建镜像 | --no-cache 跳过缓存 |
39
+ | docker run -d --name n image | 启动容器 | -p 端口映射, -v 挂载卷 |
40
+
41
+ ## {类别2}
42
+ ...
43
+ ```
44
+
45
+ ### 配置模板(`reference/TEMPLATES.md`)
46
+
47
+ **提取源**:`tutorial-examples/` 中的配置文件(Dockerfile、docker-compose.yml、package.json 等),以及章节中作为"模板"呈现的代码块。
48
+
49
+ **输出格式**:
50
+
51
+ ```markdown
52
+ # 配置模板: {主题}
53
+
54
+ ## {模板名称}
55
+ \```{语言}
56
+ {完整模板代码}
57
+ \```
58
+ **说明**:{模板用途和关键配置项解释}
59
+ ```
60
+
61
+ ### 常见错误速查(`reference/TROUBLESHOOTING.md`)
62
+
63
+ **提取源**:所有章节中出现的错误信息、注意事项、坑点描述。
64
+
65
+ **输出格式**:
66
+
67
+ ```markdown
68
+ # 常见错误速查: {主题}
69
+
70
+ | 错误 | 原因 | 解决 | 参考 |
71
+ |------|------|------|------|
72
+ | port is already allocated | 端口被占用 | 改用其他端口或停止占用容器 | §3.2 |
73
+ ```
74
+
75
+ ---
76
+
77
+ ## 4.2.2 内容回链
78
+
79
+ 提取完成后,在每个教程章节的末尾追加引用块:
80
+
81
+ ```markdown
82
+ > **快速查阅**:相关命令速查见 [`reference/COMMANDS.md`](../reference/COMMANDS.md) | 术语定义见 [`reference/GLOSSARY.md`](../reference/GLOSSARY.md)
83
+ ```
84
+
85
+ 同时在章节正文中,将重复出现的命令表格改为引用而非复制粘贴:
86
+
87
+ ```markdown
88
+ ## 3.2 构建镜像
89
+
90
+ 常用命令已收录在 [命令速查表](../reference/COMMANDS.md#镜像管理),
91
+ 这里只解释核心工作流。
92
+ ```
93
+
94
+ ---
95
+
96
+ ## 4.2.3 完整性检查
97
+
98
+ 生成后逐文件检查:
99
+
100
+ - [ ] `GLOSSARY.md` 至少包含 10 个术语
101
+ - [ ] `COMMANDS.md` 至少覆盖 3 个命令类别
102
+ - [ ] `TEMPLATES.md` 至少包含 2 个可用模板
103
+ - [ ] `TROUBLESHOOTING.md` 至少包含 5 条记录
104
+
105
+ 若任一项不满足,检查对应教程章节是否遗漏了可提取的内容。
106
+
107
+ ---
108
+
109
+ ## 4.2.4 保存会话状态
110
+
111
+ 参考文档生成后,更新 `session-state.md` 中阶段4的输出记录,追加 `reference/` 文件列表。
@@ -0,0 +1,355 @@
1
+ # 阶段4:生成教程草稿
2
+
3
+ 基于大纲和重要性评级撰写教程,**重点知识深写,次要知识简写**,不一视同仁。
4
+
5
+ ---
6
+
7
+ ## 4.0 撰写策略选择
8
+
9
+ 读取 `importance-ratings.json` 确认评级结果已存在。若阶段2.5/3.4.5未执行(快速参考模式或极小型教程),按"重要"等级对待所有知识点。
10
+
11
+ 根据教程规模选择调度策略:
12
+
13
+ | 规模 | 知识点总数 | 策略 |
14
+ |------|-----------|------|
15
+ | 小型 | <50个 | 主进程串行撰写 |
16
+ | 中型 | 50-150个 | **章节级并行 Sub-agent** |
17
+ | 大型 | >150个 | 建议拆分成多个独立教程 |
18
+
19
+ **中型教程**:在同一轮并行派出所有章节 Sub-agent,主进程只调度。
20
+
21
+ ---
22
+
23
+ ## 4.1 输出格式规范
24
+
25
+ **必须先读取** `rules/output-format.md` 了解所有输出格式标准。
26
+
27
+ 核心要点:
28
+ - 主体语言:简体中文
29
+ - 专业术语:保留英文,中文注解括号跟随
30
+ - 版本冲突:使用表格格式
31
+ - 章节模板:包含等级标记([初学]/[熟练]/[精通])
32
+
33
+ 详细规范参见 `rules/output-format.md`。
34
+
35
+ ---
36
+
37
+ ## 4.2 输出物形式(阶段3.0已决定,此处确认)
38
+
39
+ 输出形式在**阶段3.0**已根据主题宽窄做出决定,并记录在 `session-state.md`。进入阶段4前确认该决定:
40
+
41
+ | 阶段3.0决定 | 阶段4操作 |
42
+ |-----------|---------|
43
+ | 文件夹(多文件) | 按下方多文件结构生成 |
44
+ | 单文件 | 生成 `[主题]-tutorial.md`(字数不设阈值,依主题内容而定) |
45
+ | 快速参考 | 生成 `[主题]-notes.md`,含大纲 + 关键笔记 |
46
+
47
+ 如阶段3.0未记录,回退到按主题宽窄判断(不以字数阈值为准)。
48
+
49
+ ### 多文件教程结构
50
+
51
+ ```
52
+ [主题]-tutorial/
53
+ ├── 00-学习路线图.md
54
+ ├── 01-基础入门.md [初学]
55
+ ├── 02-核心概念.md [初学 → 熟练]
56
+ ├── 03-进阶特性.md [熟练]
57
+ ├── 04-高级与原理.md [精通]
58
+ ├── 05-参考资源.md
59
+ └── tutorial-examples/ ← 需要完整文件结构的示例
60
+ ├── 01-hello-world/
61
+ │ ├── README.md
62
+ │ ├── index.js
63
+ │ └── package.json
64
+ └── ...
65
+ ```
66
+
67
+ ---
68
+
69
+ ## 4.3 撰写流程
70
+
71
+ ### 步骤1:生成学习路线图
72
+
73
+ 创建 `00-学习路线图.md`(参见 `rules/output-format.md` 的学习路线图格式):
74
+
75
+ - 建议学习顺序(按等级分阶段)
76
+ - 各章节关键检查点
77
+ - 学习建议(必学章节、选学章节)
78
+
79
+ ### 步骤1.5:准备主题背景(topic_context)
80
+
81
+ 从 `_internal/02-extract/` 中汇总本章相关资料的 `topic_context` 字段,合并 origin/evolution/current_status/applications(null 的字段省略,不补全),填入章节 agent 指令模板的"本章主题背景"占位符。
82
+
83
+ 这是章节"导言"的唯一原材料来源,章节 agent 不得自行编造导言内容。
84
+
85
+ ### 步骤2:按重要性分流准备知识卡片
86
+
87
+ 在派发章节 agent 之前,主进程为每个章节组装知识卡片,并**附加该知识点的重要性等级和深度指令**。
88
+
89
+ #### 知识卡片组装流程
90
+
91
+ 1. 从 `outline.md` 获取本章知识点 ID 列表
92
+ 2. 从 `_internal/02-extract/` 找到每个 ID 的完整知识报告条目
93
+ 3. 从 `importance-ratings.json` 的 `topics` 数组查找该知识点的 `level` 和 `depth`
94
+ 4. 按等级组装不同深度的知识卡片(格式见下方):
95
+
96
+ ```
97
+ 知识卡片 kp-XXX: [知识点标题]
98
+ 重要性等级: [核心] / [重要] / [了解]
99
+ 深度指令: [撰写深度说明,见下方对照表]
100
+ 是什么: [...]
101
+ 为什么重要: [...]
102
+ 使用场景: [...]
103
+ 核心原理: [...]
104
+ 源材料摘录: "[...]"
105
+ 版本冲突: [如有]
106
+ 依赖关系: [如有]
107
+ 关键示例: [如有]
108
+ ```
109
+
110
+ #### 深度指令对照表
111
+
112
+ 章节 agent 严格按"深度指令"执行,不得自行调整深度。
113
+
114
+ | 等级 | 深度指令 | 示例数 | 原理深度 | 边界/误区 |
115
+ |------|---------|--------|---------|---------|
116
+ | [核心] | 必须写透:定义→原理→3个从简到复杂的示例→常见误区→边界条件 | ≥3个 | 必须解释底层机制 | 必须覆盖 |
117
+ | [重要] | 完整讲解:定义→原理→1-2个示例→注意事项 | 1-2个 | 简述关键机制即可 | 覆盖主要误区 |
118
+ | [了解] | 简述:一句定义→一个最简示例→指向参考资源 | 0-1个 | 不展开 | 不覆盖 |
119
+
120
+ #### 核心知识点的三层示例要求
121
+
122
+ `[核心]` 等级的 3 个示例必须覆盖三个维度,不允许三个示例都是"基础用法"的重复:
123
+
124
+ | 示例层次 | 目的 |
125
+ |---------|------|
126
+ | 示例1:最小可用示例 | 演示最基本用法,零基础能跑通 |
127
+ | 示例2:真实场景示例 | 模拟实际项目中的典型使用方式 |
128
+ | 示例3:边界/对比示例 | 展示常见错误写法 vs 正确写法,或边界条件 |
129
+
130
+ 5. 如果某知识点的 `source_excerpt` 为空,标注「源摘录缺失」
131
+
132
+ #### 章节 agent 派发
133
+
134
+ 填入知识卡片(含深度指令)后,按 `workflows/stage4-chapter-agent.md` 模板并行派发所有章节 agent。
135
+
136
+ ### 步骤3:逐章节撰写内容(由 Sub-agent 或主进程执行)
137
+
138
+ **每完成一个章节文件后,立即更新 session-state.md 的"阶段4 章节状态"**,将该章节从"待完���"移到"已完成"。
139
+
140
+ 每个知识点的撰写深度**严格按知识卡片中的深度指令执行**(详见 `workflows/stage4-chapter-agent.md`):
141
+
142
+ - `[核心]`:定义 → 原理 → 3层示例 → 误区 → 边界
143
+ - `[重要]`:定义 → 原理 → 1-2个示例 → 注意事项
144
+ - `[了解]`:一句定义 → 最简示例 → 指向参考资源
145
+
146
+ #### 示例代码决策
147
+
148
+ 参见 `references/example-structures.md`:
149
+ - 单文件 < 30 行 → 内联
150
+ - 需多文件/依赖/ > 50 行 → 独立文件夹
151
+ - **优先改编源材料示例**(知识卡片中的 `key_example`),源材料无合适示例时 AI 补充并标注
152
+
153
+ ### 步骤4:生成参考资源章节
154
+
155
+ - 一手资料(官方权威)
156
+ - 二手资料(社区推荐)
157
+ - 三手资料(仅供参考)
158
+ - 资料来源说明
159
+
160
+ ---
161
+
162
+ ## 4.4 卡顿信号处理
163
+
164
+ **必须先读取** `rules/quality-gates.md` 了解卡顿信号。
165
+
166
+ ### 触发条件
167
+
168
+ 写作过程中出现以下任一情况:
169
+ - 某段话反复改写三次以上,仍不满意
170
+ - 该章节只有一份来源,无法交叉验证
171
+ - 需要用到阶段1没有收集的新资料
172
+ - 写出了一个自己无法用口语向别人解释的概念
173
+
174
+ ### 处理措施
175
+
176
+ **不要强行写完**,而是:
177
+ 1. 立即停止当前章节撰写
178
+ 2. 识别卡顿原因
179
+ 3. 返回阶段2,针对该子主题重新派发 Sub-agent
180
+ 4. 等待新知识报告后再继续撰写
181
+
182
+ ---
183
+
184
+ ## 4.4.5 生成独立参考文档
185
+
186
+ 所有章节撰写完成后,在进入质量验证之前,执行参考文档提取。
187
+
188
+ 读取 `workflows/stage4-ref-extract.md`,从已完成的教程章节中自动提取以下文档到 `[主题]-tutorial/reference/` 目录:
189
+
190
+ - `GLOSSARY.md` — 术语表(专业术语定义速查)
191
+ - `COMMANDS.md` — 命令速查表(CLI 命令按类别分组)
192
+ - `TEMPLATES.md` — 配置模板(可直接复用的配置文件)
193
+ - `TROUBLESHOOTING.md` — 常见错误速查(错误信息+解决方案)
194
+
195
+ 提取完成后,在各章节末尾追加引用块,并在正文中将重复的命令表格改为引用。
196
+
197
+ ---
198
+
199
+ ## 4.5 内容质量抽样验证
200
+
201
+ **在进入人工审核(阶段5)之前,必须执行本阶段的质量验证。**
202
+
203
+ 完整的验证流程、评估维度和 agent 指令模板,详见 **`workflows/stage4.5-verify.md`**。以下是集成到阶段4流水线中的关键步骤摘要。
204
+
205
+ ### 为什么需要这一步
206
+
207
+ 章节 agent 可能因为输入不足、理解偏差或"脑补"而产生低质量内容。阶段4.5参照大模型微调中的"数据质量评估与抽样检验",在用户看到内容前拦截事实错误和概念堆叠问题。
208
+
209
+ ### 验证流程摘要
210
+
211
+ 1. **随机抽样**:从所有章节中按比例抽取知识点(小型30%/中型20%/大型15%)
212
+ 2. **派发验证 agent**:每个抽样知识点一个独立验证 agent,并行运行。对照阶段2知识报告的 `summary` + `source_excerpt` 评估生成内容
213
+ 3. **四维度打分**:事实准确性(30%) / 完整性(25%) / 教学价值(30%) / 示例相关性(15%)
214
+ 4. **汇总判定**:合格率≥80% 且 教学质量均分≥3.5 → 通过;否则重新生成或向用户报告
215
+ 5. **生成验证报告**:在工作区输出 `_internal/04-verify/quality-report.md`
216
+
217
+ **pedagogy < 2 分强制不通过**:教学价值是底线,概念堆叠不可接受。
218
+
219
+ 详细指令参见 `workflows/stage4.5-verify.md`。
220
+
221
+ ---
222
+
223
+ ## 4.6 撰写完成后的检查
224
+
225
+ ### 自检清单
226
+
227
+ - [ ] 所有章节都有等级标记([初学]/[熟练]/[精通])
228
+ - [ ] 版本冲突使用表格格式
229
+ - [ ] 示例代码可运行(或按 README 说明运行)
230
+ - [ ] 专业术语保留英文 + 中文注解
231
+ - [ ] 每个核心概念至少有一个示例
232
+ - [ ] 学习路线图完整
233
+ - [ ] 参考资源按来源类型分类
234
+
235
+ ### 文件检查
236
+
237
+ 如果是多文件教程:
238
+ - [ ] 文件命名符合规范(序号-章节名.md)
239
+ - [ ] 章节间引用链接正确
240
+ - [ ] tutorial-examples/ 中的示例有 README.md
241
+
242
+ ---
243
+
244
+ ## 4.7 向用户展示草稿
245
+
246
+ 完成后,向用户说明:
247
+
248
+ > "教程草稿已生成,保存在 [路径]。
249
+ >
250
+ > **内容概览**:
251
+ > - 学习路线图:1 份
252
+ > - 教程章节:N 章(初学 X 章 / 熟练 Y 章 / 精通 Z 章)
253
+ > - 示例代码:K 个(内联 M 个 / 独立文件 N 个)
254
+ > - 参考资源:P 份
255
+ >
256
+ > 请查阅草稿内容,然后进入阶段5进行审核。"
257
+
258
+ ---
259
+
260
+ ## 4.8 保存会话状态
261
+
262
+ 所有章节撰写完成后,更新工作区的 `session-state.md`:
263
+
264
+ ```markdown
265
+ # 会话状态
266
+ 主题: [主题名]
267
+ 更新时间: [当前时间]
268
+ 学习模式: [快速参考 / 完整教程]
269
+ 工作区: [工作区绝对路径]
270
+
271
+ ---
272
+
273
+ ## 进度
274
+ 当前阶段: 5
275
+ 已完成阶段: 1, 2, 3, 4, 4.5
276
+
277
+ ## 阶段输出
278
+ - **阶段1**: 资料清单.md — [N]份资料
279
+ - **阶段2**: _internal/02-extract/ — [X]个知识点
280
+ - **阶段3**: outline.md, outline-stats.json
281
+ - **阶段4**: [列出所有已生成的章节文件] — 共[N]章全部完成
282
+ - **阶段4.5**: quality-report.md — 合格率 [X]%,教学质量均分 [X.X]
283
+
284
+ ---
285
+
286
+ ## 恢复指令
287
+ 所有章节已撰写完成且通过质量验证,教程位于工作区根目录。继续阶段5(人工审核),向用户展示目录概览并请求反馈。
288
+ ```
289
+
290
+ ---
291
+
292
+ ## 4.9 进入下一阶段
293
+
294
+ 读取 `workflows/stage5-review.md` 执行阶段5。
295
+
296
+ ---
297
+
298
+ ## 常见问题
299
+
300
+ **Q1:快速参考模式和完整教程模式的区别?**
301
+
302
+ A:
303
+ | 维度 | 快速参考 | 完整教程 |
304
+ |------|---------|---------|
305
+ | 输出 | 单文件笔记 | 多文件文件夹 |
306
+ | 内容深度 | 核心概念大纲 + 关键要点 | 详细解释 + 完整示例 + 注意事项 |
307
+ | 示例代码 | 简短内联 | 内联 + 独立可运行文件 |
308
+ | 学习路线图 | 可选 | 必须 |
309
+
310
+ **Q2:某个概念在多个章节中都出现,是否重复撰写?**
311
+
312
+ A:
313
+ - 第一次出现:详细解释
314
+ - 后续出现:简短提及 + 回链到首次出现的章节
315
+
316
+ 示例:
317
+ ```markdown
318
+ ## 状态管理(第3章)
319
+ [详细解释 useState]
320
+
321
+ ## 副作用处理(第4章)
322
+ 在处理副作用时,也需要用到状态管理。关于 `useState` 的详细说明,请参见 [第3章 状态管理](./03-状态管理.md)。
323
+ ```
324
+
325
+ **Q3:示例代码来自原始资料还是 AI 生成?**
326
+
327
+ A:
328
+ - 优先从原始资料提取/改编
329
+ - 资料不足时 AI 补充
330
+ - 内联代码块需标注 `<!-- 示例由 AI 补充 -->`
331
+ - 独立文件无需标注
332
+
333
+ **Q4:教程撰写到一半发现大纲有问题,是否需要返回阶段3?**
334
+
335
+ A:
336
+ - 小问题(个别知识点分级不当)→ 继续撰写,在阶段5让用户反馈
337
+ - 大问题(整个章节缺失、逻辑矛盾)→ 立即停止,向用户说明问题,询问是否返回阶段3
338
+
339
+ ---
340
+
341
+ ## 执行检查清单
342
+
343
+ 完成阶段4后,自检:
344
+ - [ ] 输出格式符合 `rules/output-format.md`
345
+ - [ ] 所有章节都已撰写完成
346
+ - [ ] 示例代码符合 `references/example-structures.md` 规范
347
+ - [ ] 学习路线图完整(完整教程模式)
348
+ - [ ] 参考资源章节完整
349
+ - [ ] 未触发卡顿信号(如果触发,已返回阶段2补充)
350
+ - [ ] **阶段4.5 内容质量验证已执行并通过**(或已记录问题并修复)
351
+
352
+ - [ ] 每章完成后已及时更新 session-state.md 章节状态
353
+ - [ ] 所有章节完成后已写入最终 session-state.md
354
+
355
+ 如果任一项为"否",补充完成后再进入阶段5。