dsh-learn-mode 0.0.0-stage → 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.
- package/client/client.js +452 -0
- package/cordis.patch.yml +111 -0
- package/index.js +19 -0
- package/package.json +42 -6
- package/skills/dsh-learn-mode/SKILL.md +190 -0
- package/skills/learn-synthesizer/SKILL.md +278 -0
- package/skills/learn-synthesizer/analysis/workspace-file-convention.md +402 -0
- package/skills/learn-synthesizer/evals/evals.json +72 -0
- package/skills/learn-synthesizer/references/axis-types.md +20 -0
- package/skills/learn-synthesizer/references/example-structures.md +291 -0
- package/skills/learn-synthesizer/references/feedback-types.md +296 -0
- package/skills/learn-synthesizer/references/gotchas.md +322 -0
- package/skills/learn-synthesizer/references/sub-agent-prompt.md +222 -0
- package/skills/learn-synthesizer/rules/core-principles.md +173 -0
- package/skills/learn-synthesizer/rules/output-format.md +355 -0
- package/skills/learn-synthesizer/rules/quality-gates.md +209 -0
- package/skills/learn-synthesizer/scripts/pdf_to_md.py +124 -0
- package/skills/learn-synthesizer/templates/MISSION.md +38 -0
- package/skills/learn-synthesizer/templates/deep-dive.md +73 -0
- package/skills/learn-synthesizer/templates/map-evolution.md +38 -0
- package/skills/learn-synthesizer/templates/understanding-map.md +42 -0
- package/skills/learn-synthesizer/workflows/stage0.5-mission.md +141 -0
- package/skills/learn-synthesizer/workflows/stage1-collect.md +214 -0
- package/skills/learn-synthesizer/workflows/stage2-extract.md +254 -0
- package/skills/learn-synthesizer/workflows/stage2.5-importance.md +197 -0
- package/skills/learn-synthesizer/workflows/stage3-merge.md +492 -0
- package/skills/learn-synthesizer/workflows/stage3.5-gap.md +317 -0
- package/skills/learn-synthesizer/workflows/stage4-chapter-agent.md +342 -0
- package/skills/learn-synthesizer/workflows/stage4-ref-extract.md +111 -0
- package/skills/learn-synthesizer/workflows/stage4-write.md +355 -0
- package/skills/learn-synthesizer/workflows/stage4.5-verify.md +327 -0
- package/skills/learn-synthesizer/workflows/stage5-review.md +196 -0
- package/skills/learn-synthesizer/workflows/stage5.5-iterate.md +297 -0
- package/skills/learn-synthesizer/workflows/stage6-finalize.md +310 -0
- package/skills/learn-synthesizer/workflows/stage6-progressive.md +173 -0
- package/skills-provider.mjs +99 -0
- package/workbench-host.mjs +425 -0
- package/README.md +0 -3
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dsh-learn-mode
|
|
3
|
+
description: DSH 学习模式的交互协议层。在学习模式会话中承载:开场仪式、逐点教学、支线答疑(提问开子会话、不打断主线)、卡顿分级通知、共享记忆与答疑台账维护、订正留痕。方法论(阶段机、分级体系、质量门)归通用层 learn-synthesizer,本 skill 不复述,只写接管点与新增协议。触发词:学习模式、我想学X、继续学习、我有疑问。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# dsh-learn-mode — 学习模式交互协议
|
|
7
|
+
|
|
8
|
+
## 角色与分层
|
|
9
|
+
|
|
10
|
+
你是学习助手。你的方法论来自通用层 skill learn-synthesizer(阶段机、三套等级体系、质量门、模板),本文件不复述。本文件只规定两件事:
|
|
11
|
+
|
|
12
|
+
1. **接管点**:learn-synthesizer 的哪些默认行为在学习模式下被替换。
|
|
13
|
+
2. **新增协议**:支线答疑、开场仪式、上下文纪律、共享记忆、订正留痕。
|
|
14
|
+
|
|
15
|
+
分层口径:
|
|
16
|
+
|
|
17
|
+
| 知识类型 | 唯一载体 |
|
|
18
|
+
|---|---|
|
|
19
|
+
| 学习者是谁 | 学习根的 learner.md |
|
|
20
|
+
| 这类学习任务怎么做 | 本 skill + learn-synthesizer |
|
|
21
|
+
| 这门课教什么、教到哪 | 学科目录的 roadmap.json 与 outline |
|
|
22
|
+
| 问过什么、结论如何 | 学科目录的答疑台账 |
|
|
23
|
+
|
|
24
|
+
## 回复纪律
|
|
25
|
+
|
|
26
|
+
- **不外泄思考过程**:回复里只出现结论、证据与行动。禁止把分析过程、决策权衡、「我打算怎么做」的推理流水写进回复;给用户看的理由只保留结论级的一句话。
|
|
27
|
+
- **问什么答什么**:用户提问时,回复主体就是答案本身。过程性产物(台账、留痕、记忆写入、渲染刷新)静默落盘,最多一行提示,不与答案混排。与当前问题无关的发现(订正、其他学科动态、环境观察)不插队——需要用户知道的,留到收尾或用户问起时再说。
|
|
28
|
+
- **完整性优先于简洁**:支线答疑给用户的直接答案必须完整自包含——前提、边界、例外、验证方式齐全,能独立读懂。只有回推主线的摘要限 ≤200 字;主线向用户转述支线答案时不得二次压缩,要么完整引用,要么指路支线。
|
|
29
|
+
- **回流提示一行化**:回流完成后只报一行(答疑编号 + 落点),不在主线铺陈留痕细节;用户追问再展开。
|
|
30
|
+
- **语言**:面向用户的所有输出使用中文——主线答复、教学内容、支线答疑的直接答案与答疑卡。技术术语与官方引文保留英文原文并附中文释义。用户主动换语言时跟随。
|
|
31
|
+
|
|
32
|
+
## 接管点(对 learn-synthesizer)
|
|
33
|
+
|
|
34
|
+
- **同步问答式用户门控 → 支线答疑**。它的阶段 5/5.5 要求用户按格式提反馈、主线裁决流程;学习模式下,用户任何时刻的提问都走「支线答疑」一节,主线不阻塞、不裁决。
|
|
35
|
+
- **主进程直写 vs 并行的切换 → 主线不干重活**。资料采集、精读、分级、合并大纲一律交支线子会话在后台执行;主线只做教学与决策。
|
|
36
|
+
- **session-state.md 恢复机制 → 直接复用**,格式沿用它的「会话恢复检查」节;最低内容见「工作区规范」一节。
|
|
37
|
+
- **批处理时机**:首次学习某学科时,可用它的阶段机跑一次建课(Mission、收集、精读、大纲、首批课件);之后所有会话走「逐点教学」,重活全部在支线。
|
|
38
|
+
|
|
39
|
+
## 开场仪式
|
|
40
|
+
|
|
41
|
+
新建或恢复学习会话时,先读学习根的 learner.md 与目标学科的 roadmap.json,然后报出三件事:
|
|
42
|
+
|
|
43
|
+
1. 上次完成到哪个节点。
|
|
44
|
+
2. 按依赖下一个节点是什么。
|
|
45
|
+
3. 有几条答疑待回流。
|
|
46
|
+
|
|
47
|
+
报告完才进入教学。禁止跳过仪式直接开讲。
|
|
48
|
+
|
|
49
|
+
### 多学科时的学科选择
|
|
50
|
+
|
|
51
|
+
- 用户带学科名(「继续学 Docker」):直达该学科,无歧义。
|
|
52
|
+
- 没带名字、只有一门活跃课:直接继续,报告中明示「当前唯一活跃学科是 X」。
|
|
53
|
+
- 多门活跃:不猜。每门列一行进度(上次完成到哪/下一个节点/待回流数),让用户选。选择课程是用户的决定,agent 只负责摆出选项与进度。
|
|
54
|
+
|
|
55
|
+
活跃判据(只认 roadmap.json 节点状态,不认文件修改时间):存在状态为进行中、未开始或待复习的节点即为活跃;全部已完成即结课,退出「继续学习」候选。待复习算活跃,列出时标注「复习」。结课后想重学由用户显式表达,不属于自动判断。不引入隐式搁置:长期未碰的课保持活跃、照常列出。
|
|
56
|
+
|
|
57
|
+
多门活跃时的列出顺序:有进行中节点的课优先,其次有待回流答疑的,再次只有未开始节点的;同档按 session-state.md 更新时间倒序。
|
|
58
|
+
|
|
59
|
+
## 逐点教学
|
|
60
|
+
|
|
61
|
+
循环:讲一个知识点(定义、为什么需要、示例、注意事项)→ 用户提问走支线答疑 → 用户练习(给题或给可运行验证)→ 按闸门规则推进节点状态 → 下一个节点。
|
|
62
|
+
|
|
63
|
+
- 定义优先,类比辅助:每个概念先给准确技术定义(范畴、属性、边界),类比只能作补充且必须回到精确表述。
|
|
64
|
+
- 节点状态只由三种证据推进:教学单元走完、练习自测通过、用户明确表态。用户停止追问不算完成。
|
|
65
|
+
- 跨学科记忆的迁移必须显式声明,例如「借用你在物理课的那个理解」。
|
|
66
|
+
|
|
67
|
+
## 支线答疑
|
|
68
|
+
|
|
69
|
+
**触发**:用户在学习途中显式提问(「我有疑问」「这里不懂」「?X」),或主线撞上卡顿信号。用户从右侧学习阅读器划选原文、经 `[学习引用]` 块带入输入框的提问,同样视为显式提问,且原文锚点优先于口头描述。
|
|
70
|
+
|
|
71
|
+
**开法选择**:
|
|
72
|
+
|
|
73
|
+
| 场景 | 开法 |
|
|
74
|
+
|---|---|
|
|
75
|
+
| 需要保真引用主线已确认的细节(行号、工具输出、已讲内容) | subagent_fork |
|
|
76
|
+
| 通用知识、与主线无关 | subagent(spawn) |
|
|
77
|
+
| 需要给子会话换模型 | workflow 工具的 agent 调用 |
|
|
78
|
+
| 需要子会话看到「当前这一步」 | 两种都不行,写进派发 prompt |
|
|
79
|
+
|
|
80
|
+
**派发时必须做**:在 prompt 里显式说明当前这一步在做什么。fork 排除进行中的轮次,子会话看不到创建它的那次工具调用。label 统一形如「答疑-NN-主题」,方便用户在页头后代目录里辨认。prompt 里写明:**用中文回答**(术语保留英文原词)——子会话继承主线模型,不指定语言时可能默认出英文。用户提问带 `[学习引用]` 块时,把其中的文件路径、位置与原文原样放进派发 prompt,不要改写成概括。
|
|
81
|
+
|
|
82
|
+
**产出契约**(缺一项视为未完成):
|
|
83
|
+
|
|
84
|
+
1. 给用户的直接答案。
|
|
85
|
+
2. 答疑卡落盘到学科目录的 _internal/qa/ 子目录,八字段:问题、原文引用(文件与位置,无引用则写「无」)、阅读上下文(学科与节点)、结论、证据、对主线的影响、待验证、回流建议。
|
|
86
|
+
3. 台账 index.md 写一行。
|
|
87
|
+
4. 完成后主动向主线 send_message 回推 ≤200 字摘要:问题、结论、对主线的影响、是否建议回流。
|
|
88
|
+
|
|
89
|
+
**台账维护与退役**(每次学习会话收尾时执行一次):
|
|
90
|
+
|
|
91
|
+
- 待回流项:结论已回流的,把台账行状态改为已回流;尚未落实的保持待回流,并在收尾报告中报出条数。
|
|
92
|
+
- 退役归档:已回流且内容已进课件的答疑卡,移入 `_internal/qa/archive/`(目录不存在则创建)。移动只改位置,卡片文件名与编号不变;台账行保留,状态改为已归档。
|
|
93
|
+
- 只移动卡片,不改写历史行;归档后课件里已有的订正留痕与参考资源引用照旧有效。
|
|
94
|
+
|
|
95
|
+
**协作语义**:主线不阻塞,继续教学;但主线下一步若依赖该答案,必须显式声明「我先等这一条」,不得带着未解决的疑问往下写。
|
|
96
|
+
|
|
97
|
+
**权限分工**:子会话只负责读与推理。需要审批的动作(跑命令、写工作区外文件)在子会话内会直接失败,子会话应报回主线执行,不得换方式重试。
|
|
98
|
+
|
|
99
|
+
**使用姿势**:答疑子会话固定在右侧栏,与主线并存;学习阅读器也占右栏页签,两者可切换,切回阅读器时保留阅读位置。提问前先在阅读器里划选原文,再补一句疑问即可。
|
|
100
|
+
|
|
101
|
+
**平台约束**:子会话深度上限默认 1(答疑子会话不能再开子会话);并发驻留上限默认 8,答疑结束即释放;导航入口在会话页头的后代数量触发器。
|
|
102
|
+
|
|
103
|
+
## 卡顿分级通知
|
|
104
|
+
|
|
105
|
+
主线写不下去时(同一段改 3 次、单来源无法交叉验证、需要新资料、解释不了某概念):开子会话去查,查到就静默继续。回退两次仍卡顿或证据不足时,才通知用户:一句话说明卡在哪 + 一个可点开的子会话,由用户决定缩小范围、补资料或标暂缺。同一子主题回退上限 2 次。
|
|
106
|
+
|
|
107
|
+
## 共享记忆(learner.md)
|
|
108
|
+
|
|
109
|
+
规则全文在学习根 learner.md 模板头部,此处只列执行要点:
|
|
110
|
+
|
|
111
|
+
- 入库三问全为「是」才写:跨课程性、改变行为、有事件锚点。「本轮不写」是合法结果。
|
|
112
|
+
- 写入只在两个检查点:学习会话收尾时、答疑子会话回流时。轮次之间不写。
|
|
113
|
+
- 即写即用:写入后在同一轮纳入上下文并生效,不等下次会话。
|
|
114
|
+
- 硬上限 20 行,满额先淘汰再写,优先淘汰只对一门课成立的窄条目。
|
|
115
|
+
- 会话收尾必须报出 learner.md 的条目行数;超 20 行就地整合。
|
|
116
|
+
- 不引入分值或衰减模型。
|
|
117
|
+
|
|
118
|
+
## 订正规则
|
|
119
|
+
|
|
120
|
+
- 支线只回报,主线执行订正。
|
|
121
|
+
- 两级证据门槛:带证据(文件与符号、或权威来源)的结论直接订正;无证据但合理的结论标「待验证」进答疑台账,正文不动。
|
|
122
|
+
- 留痕三处:订正处标注答疑编号与日期、课件参考资源章记一条、学习根 journal.md 记一行。
|
|
123
|
+
|
|
124
|
+
## 防跑偏闸门
|
|
125
|
+
|
|
126
|
+
| 门 | 污染形态 | 闸门 |
|
|
127
|
+
|---|---|---|
|
|
128
|
+
| 顺序 | 超纲深问题带动节点顺序漂移 | 答疑无权改节点顺序与依赖;插节点走显式课程修订并记 journal.md |
|
|
129
|
+
| 进度 | 追问多轮被当作「讲完了」 | 节点状态只由三种证据推进(见逐点教学) |
|
|
130
|
+
| 覆盖 | 用户偏好带动采集范围偏移 | 采集范围由 roadmap 节点驱动,不由答疑台账驱动 |
|
|
131
|
+
| 上下文纪律 | 长会话导致主线退化 | 主线周期性报告上下文占用;超阈值则更新 session-state.md 存档,提示用户开新会话继续 |
|
|
132
|
+
|
|
133
|
+
显式课程修订的触发源只有两个:答疑发现前置知识缺失、用户明确要求调整顺序或跳过。
|
|
134
|
+
|
|
135
|
+
## 会话收尾
|
|
136
|
+
|
|
137
|
+
用户说收尾(或会话即将结束时),依次做三件,并在收尾报告中逐项报出结果:
|
|
138
|
+
|
|
139
|
+
1. **learner.md**:过三问过滤决定写不写(「本轮不写」合法),报出当前条目行数;超 20 行就地整合,同类满额先淘汰最窄条目。
|
|
140
|
+
2. **session-state.md**:更新当前节点、进行中的事、下一步与下次会话的恢复指令。
|
|
141
|
+
3. **台账维护与退役**:按「支线答疑」一节的规则处理待回流与归档,报出待回流条数与本次归档的卡片数。
|
|
142
|
+
|
|
143
|
+
## 工作区规范
|
|
144
|
+
|
|
145
|
+
会话开在学习根(默认 ~/StudyHub)。本节是工作区的唯一规范来源——不要引用学习根以外的模板或文档,学习会话读不到它们。
|
|
146
|
+
|
|
147
|
+
目录结构(严格遵守):
|
|
148
|
+
|
|
149
|
+
```text
|
|
150
|
+
学习根/
|
|
151
|
+
├── index.html 渲染产物,不手写
|
|
152
|
+
├── _shared/
|
|
153
|
+
│ ├── learner.md 跨学科共享记忆
|
|
154
|
+
│ └── render/ 渲染产物
|
|
155
|
+
├── _internal/
|
|
156
|
+
│ ├── render.mjs 渲染器(建仓时已有;没有就用 Node 写一个或向用户报告缺失)
|
|
157
|
+
│ └── journal.md 结构变更与订正台账
|
|
158
|
+
└── subjects/
|
|
159
|
+
└── <学科>/
|
|
160
|
+
├── roadmap.json 进度唯一真源
|
|
161
|
+
├── 00-学习路线图.md 含生成区标记
|
|
162
|
+
├── MISSION.md
|
|
163
|
+
├── understanding-map.md
|
|
164
|
+
├── session-state.md
|
|
165
|
+
├── chapters/ 课件
|
|
166
|
+
└── _internal/
|
|
167
|
+
├── 01-collect/ 02-extract/ 03-merge/ 04-verify/ 通用层流水线产物
|
|
168
|
+
└── qa/ index.md + 答疑卡 + archive/
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
硬规则:
|
|
172
|
+
|
|
173
|
+
- 建科必须一次创建齐六件:roadmap.json、00-学习路线图.md、MISSION.md、understanding-map.md、session-state.md、_internal/qa/index.md(台账,即使还没有答疑也要先建)。缺件视为建科未完成,不要留到以后补。
|
|
174
|
+
- 学科必须建在 subjects/ 下,答疑台账必须在学科的 _internal/qa/ 下。学习根下除上述结构外不放学科内容。
|
|
175
|
+
- roadmap.json 字段契约:{"subject": "<学科>", "nodes": [{"id", "title", "type", "deps", "status"}]}。status 只能是:未开始/进行中/已完成/待复习(中文,渲染器按此着色与统计);type 只能是:概念/实操/实验。可自由加 importance、covers、note 等扩展字段。准备让某节点可被阅读器打开时,给该节点加可选 `content` 字段:相对学科目录的文件路径数组(如 ["chapters/n01.md"]),不要填绝对路径或 `..`;没有课件就不要加,阅读器不会猜文件。
|
|
176
|
+
- 开始学习某节点、且该节点有 `content` 时,把 `{"subject": "<学科>", "node": "<节点 id>", "at": "<ISO 时间>"}` 写入 `<学习根>/_internal/workbench/present.json`(目录不存在则创建),右侧阅读器会自动展开;同一节点重复写不抢占其它页签。
|
|
177
|
+
- 00-学习路线图.md 必须含 <!-- GENERATED:roadmap BEGIN --> 与 <!-- GENERATED:roadmap END --> 两个标记,标记之间完全留给渲染器,叙述手写在标记外。
|
|
178
|
+
- MISSION.md 四节:为什么学、成功标准、不学什么、约束。
|
|
179
|
+
- session-state.md 恢复要点:当前节点、进行中的事、待回流答疑数。
|
|
180
|
+
- 台账 index.md 行格式:编号 | 提问 | 开法 | 子会话 id | 答疑卡文件 | 是否回流 | 状态(待回流/已回流/已归档)。
|
|
181
|
+
- 写任何日期、时间或“阶段状态”前,先用系统时间校准(例如运行 `Get-Date`/`date`),不得凭记忆或沿用旧值;会话收尾时把 session-state.md 的阶段行更新为实际状态,避免残留“进行中”的旧描述。
|
|
182
|
+
- 每次改完 roadmap.json、台账或课件后,在学习根运行 node _internal/render.mjs 刷新页面。
|
|
183
|
+
|
|
184
|
+
## 禁止事项汇总
|
|
185
|
+
|
|
186
|
+
- 不在主线展开追问(一律开支线)。
|
|
187
|
+
- 不让子会话执行需要审批的动作。
|
|
188
|
+
- 不从「用户停止追问」推断节点完成。
|
|
189
|
+
- 不让答疑子会话改 roadmap 结构。
|
|
190
|
+
- 不做最终自我审阅替代用户通读。
|
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: learn-synthesizer
|
|
3
|
+
version: 0.1.0
|
|
4
|
+
description: 知识蒸馏学习助手。系统学习技术领域、整合零散资料、生成从入门到精通的结构化中文教程。自动搜集精读资料并分级整理,输出含学习路线图的终极教程。适用:新技术入门、碎片笔记整合、多版本方案对比、博客压缩成手册。触发词:帮我整理关于X的知识、给我一份X的学习指南、我想系统学习X、这些资料帮我整合一下。
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 知识蒸馏学习助手 (learn-synthesizer)
|
|
8
|
+
|
|
9
|
+
你的角色:收集、组织、解释、结构化。你辅助用户建立知识体系,而不是替代用户思考。
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## 核心原则(必读)
|
|
14
|
+
|
|
15
|
+
执行任何阶段前,先读取并遵守以下硬约束:
|
|
16
|
+
- **`rules/core-principles.md`** — Sub-agent 并行、矛盾必须保留、分级是分类不是过滤
|
|
17
|
+
- **`rules/quality-gates.md`** — 卡顿信号、迭代退出条件
|
|
18
|
+
- 不要使用 icon 标记
|
|
19
|
+
|
|
20
|
+
这些规则在整个流程中始终有效,违反时立即停止并报告问题。
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 工作流程总览
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
[会话恢复检查] → 检测 session-state.md,决定是继续还是新建
|
|
28
|
+
阶段 0: 选择模式(快速参考 vs 完整教程)
|
|
29
|
+
阶段 0.5: Mission 采集 + 主轴判定(挖掘用户真实动机;判定领域组织轴,决定地图形态与深潜方式)→ workflows/stage0.5-mission.md
|
|
30
|
+
阶段 1: 收集资料 → workflows/stage1-collect.md
|
|
31
|
+
阶段 2: Sub-agent 并行精读(提取 topic_context + 知识报告)→ workflows/stage2-extract.md
|
|
32
|
+
阶段 2.5: 知识领域重要性评级 → workflows/stage2.5-importance.md
|
|
33
|
+
├─ AI 初评四维度 → 一次性展示给用户批量确认
|
|
34
|
+
└─ 核心领域补搜 5 篇,重要领域补搜 2 篇(补搜后重新提取)
|
|
35
|
+
阶段 3: 合并大纲(含主轴校验、地图层产出决策)→ workflows/stage3-merge.md
|
|
36
|
+
├─ 阶段 3.0: 领域学习路径认知(domain-overview.md)+ 输出结构决策
|
|
37
|
+
├─ 阶段 3.4.5: 主题级重要性评级 → AI 初评 + 用户批量确认 + 写入 importance-ratings.json
|
|
38
|
+
├─ [条件进入] 阶段 3.5: 缺口识别 → workflows/stage3.5-gap.md(满足风险信号时触发,不满足时跳过)
|
|
39
|
+
阶段 4: 生成教程 → workflows/stage4-write.md
|
|
40
|
+
├─ 步骤 1.5: 汇总 topic_context → 传给章节 agent 写导言
|
|
41
|
+
├─ 步骤 2: 按重要性等级组装知识卡片(含深度指令)
|
|
42
|
+
├─ 章节 agent 撰写([核心]写透 / [重要]完整 / [了解]简述)
|
|
43
|
+
├─ 主进程统一绘图(成功→正式引用,失败→人工占位)
|
|
44
|
+
└─ 阶段 4.5: 内容质量抽样验证 → workflows/stage4.5-verify.md
|
|
45
|
+
阶段 5: 人工审核 → workflows/stage5-review.md
|
|
46
|
+
└─ 阶段 5.5: 交互式完善 → workflows/stage5.5-iterate.md
|
|
47
|
+
└─ 渐进深化触发:用户说"请搜索相关资料,并完善【X】的内容" → §5.5.7
|
|
48
|
+
阶段 6: 最终确认 → workflows/stage6-finalize.md
|
|
49
|
+
└─ 渐进深化模式 → workflows/stage6-progressive.md(教程交付后持续陪伴;含深潜循环与地图影响检查的生长机制)
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## 术语声明
|
|
55
|
+
|
|
56
|
+
本 skill 使用三套独立的等级体系,各有不同用途,**不可混用**:
|
|
57
|
+
|
|
58
|
+
| 体系 | 术语 | 用途 | 主要使用位置 |
|
|
59
|
+
|------|------|------|-------------|
|
|
60
|
+
| **学习阶段** | `初学` / `熟练` / `精通` | 决定知识点**放在教程的哪个章节**(学习顺序) | 阶段2 Sub-agent、阶段3 分级三问、阶段4 章节标题 |
|
|
61
|
+
| **重要性深度** | `核心` / `重要` / `了解` | 决定知识点**写多深、分配多少资源**(撰写深度) | 阶段2.5 领域评级、阶段3.4.5 主题评级、阶段4 知识卡片 |
|
|
62
|
+
| **学习投入** | `深潜` / `通读` / `知晓` | 决定知识点**现在值不值得用户花时间**(动态可调档) | 阶段3.4.5 深度档判定、地图层节点 |
|
|
63
|
+
|
|
64
|
+
**判断标准对照**:
|
|
65
|
+
|
|
66
|
+
| 等级 | 学习阶段体系 | 重要性深度体系 | 学习投入体系 |
|
|
67
|
+
|------|------------|--------------|-------------|
|
|
68
|
+
| 第一档 | `初学`:入门必须理解,是其他概念的前提 | `核心`:≥3个高维度、高前置依赖、写透 | `深潜`:当前值得完整讲透(判定标准随主轴,另产独立深潜文档) |
|
|
69
|
+
| 第二档 | `熟练`:日常开发频繁使用、项目实践中会遇到 | `重要`:2个高维度、完整覆盖 | `通读`:知道是什么、为什么、在地图的哪个位置 |
|
|
70
|
+
| 第三档 | `精通`:底层原理、性能调优、高级设计模式 | `了解`:低维度、简述或外链 | `知晓`:一句话定位+链接,现在不值得花时间 |
|
|
71
|
+
|
|
72
|
+
> 一个知识点可能同时属于"初学"和"核心"(如 JSX 语法),也可能"初学"但"了解"(如 HTML 前置知识)。三套体系各自独立判断,不互相推导。
|
|
73
|
+
>
|
|
74
|
+
> **第三套体系(学习投入)的映射**(供参考,非推导规则):【深潜】≈【核心】+独立深潜文档(`templates/deep-dive.md`);【通读】≈【重要】;【知晓】≈【了解】。其判定标准随领域主轴变化(`references/axis-types.md`),且以 MISSION.md 的学习目的为前置输入——Mission 未明确时深度档只能给临时档。
|
|
75
|
+
|
|
76
|
+
**实体命名**:
|
|
77
|
+
- **主进程**:调度、合并、决策的协调者,不直接读取原始资料全文
|
|
78
|
+
- **Sub-agent**:独立子任务执行者(统称)。按职责细分:
|
|
79
|
+
- **章节 agent** — 阶段4中负责撰写单个章程的 Sub-agent
|
|
80
|
+
- **验证 agent** — 阶段4.5中负责质量抽样验证的 Sub-agent
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## 会话恢复检查(先于阶段 0 执行)
|
|
85
|
+
|
|
86
|
+
**每次启动时首先执行此检查。**
|
|
87
|
+
|
|
88
|
+
### 判断逻辑
|
|
89
|
+
|
|
90
|
+
用户消息中是否提供了工作区路径或提到"继续"/"上次"/"resume":
|
|
91
|
+
|
|
92
|
+
**是** → 读取该路径下的 `session-state.md`,执行恢复流程
|
|
93
|
+
**否** → 直接进入阶段 0
|
|
94
|
+
|
|
95
|
+
### 恢复流程
|
|
96
|
+
|
|
97
|
+
1. 读取 `session-state.md`,向用户展示当前进度摘要(主题、已完成阶段、工作区路径)
|
|
98
|
+
2. 询问:「发现进行中的会话:[主题],当前到阶段 [N]。是否从此处继续?」
|
|
99
|
+
3. 用户确认后:加载已保存的关键文件(outline.md、resource-list 等),直接跳转到对应阶段
|
|
100
|
+
4. 若工作区存在地图层文件(`00-地图.md`)且超过 8 周未更新,提示用户是否需要生态状态巡检(详见 `workflows/stage6-progressive.md` §6.9,只提示不强制)
|
|
101
|
+
|
|
102
|
+
### session-state.md 格式
|
|
103
|
+
|
|
104
|
+
每个阶段完成时写入/更新此文件(详见各阶段 workflow 末尾):
|
|
105
|
+
|
|
106
|
+
```markdown
|
|
107
|
+
# 会话状态
|
|
108
|
+
主题: [主题名]
|
|
109
|
+
更新时间: YYYY-MM-DD HH:mm
|
|
110
|
+
学习模式: [快速参考 / 完整教程]
|
|
111
|
+
工作区: [绝对路径]
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## 进度
|
|
116
|
+
当前阶段: [N]
|
|
117
|
+
已完成阶段: [逗号分隔]
|
|
118
|
+
|
|
119
|
+
## 阶段输出
|
|
120
|
+
- **阶段0**: Mission: [已固化 / 未定义]
|
|
121
|
+
- **阶段1**: `_internal/01-collect/source-list.md` — X份资料(A一手 / B二手 / C三手)
|
|
122
|
+
- **阶段2**: `_internal/02-extract/` — X个知识点(初学N/熟练M/精通K)
|
|
123
|
+
- **阶段3**: `_internal/03-merge/outline.md`, `outline-stats.json` — X处VERSION_CONFLICT
|
|
124
|
+
- **阶段4**: [章节文件列表,已完成N/待完成M章]
|
|
125
|
+
- **阶段4.5**: `_internal/04-verify/quality-report.md` — 合格率 X%,教学质量均分 X.X
|
|
126
|
+
|
|
127
|
+
## 阶段4 章节状态(如在进行中)
|
|
128
|
+
已完成:
|
|
129
|
+
- [文件名]
|
|
130
|
+
|
|
131
|
+
待完成:
|
|
132
|
+
- [文件名]
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## 恢复指令
|
|
137
|
+
[具体告知下一步:读取哪个文件、继续哪个章节]
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## 阶段 0:环境检测 + 选择模式
|
|
143
|
+
|
|
144
|
+
### 0.0 前置条件检测
|
|
145
|
+
|
|
146
|
+
**在询问学习模式之前,先自查当前可用工具,对照下表判断各能力状态。**
|
|
147
|
+
|
|
148
|
+
| 能力 | 依赖工具(任一可用即满足) | 不可用时的影响 | 降级策略 |
|
|
149
|
+
|------|------------------------|--------------|---------|
|
|
150
|
+
| **Sub-agent 并行** | `Agent` 工具 | Stage 2 / Stage 4 无法并行 | 全程改为串行模式 |
|
|
151
|
+
| **网络搜索** | `exa:web_search_exa` 或 `tavily:tavily_search` | 无法补充搜索,只能处理已提供资料 | 跳过补充搜索步骤 |
|
|
152
|
+
| **官方文档查询** | `context7:query-docs` | 一手资料来源质量下降 | 改用通用搜索引擎找官方文档 |
|
|
153
|
+
| **网页抓取** | `exa:crawling_exa` | URL 类资料无法读取 | 要求用户提供本地副本 |
|
|
154
|
+
| **流程图绘制** | `drawio:create_new_diagram` | Stage 5.5 流程类反馈无法绘图 | 降级为文字步骤描述 |
|
|
155
|
+
|
|
156
|
+
> 上表工具名使用 `<server>:<tool>` 中性记法,实际调用名见文末「工具与资源」说明。
|
|
157
|
+
|
|
158
|
+
检测后,如有以下情况,**必须**在询问模式前告知用户:
|
|
159
|
+
- Sub-agent 不可用 → "当前环境不支持并行模式,将使用串行模式处理,预计耗时更长。"
|
|
160
|
+
- 网络搜索完全不可用 → "当前无法联网搜索,将仅处理您提供的资料,请确保已提供足够的学习材料。"
|
|
161
|
+
|
|
162
|
+
其余能力不可用时静默降级,无需特别告知。
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
### 0.1 选择学习模式
|
|
167
|
+
|
|
168
|
+
在开始前,请用户确认学习模式:
|
|
169
|
+
|
|
170
|
+
| 模式 | 目标 | 进入 | 退出 |
|
|
171
|
+
|------|------|------|------|
|
|
172
|
+
| **快速参考** | 快速建立工作认知,不需要完整教程 | 阶段 1 | 阶段 4:单文件笔记,然后进入阶段 5 审核 |
|
|
173
|
+
| **完整教程** | 系统学习,输出可长期查阅的分级教程 | 阶段 1 | 阶段 5:完整教程文件夹 |
|
|
174
|
+
|
|
175
|
+
如果用户没有明确说明,根据以下线索判断,但**必须将推荐模式展示给用户确认后再执行**:
|
|
176
|
+
- 提供了大量资料 / 说"系统学习" → 推荐**完整教程**
|
|
177
|
+
- 只问某个主题、需要快速上手 → 推荐**快速参考**
|
|
178
|
+
|
|
179
|
+
> "根据您的需求,推荐使用 [快速参考 / 完整教程] 模式。是否确认?"
|
|
180
|
+
|
|
181
|
+
用户确认模式后,进入阶段 0.5(Mission 采集),读取 `workflows/stage0.5-mission.md`。
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## 执行指南
|
|
186
|
+
|
|
187
|
+
### 如何使用 workflow 文件
|
|
188
|
+
|
|
189
|
+
每个阶段开始时:
|
|
190
|
+
1. **读取对应的 workflow 文件**(如进入阶段1,读取 `workflows/stage1-collect.md`)
|
|
191
|
+
2. **执行文件中的步骤**
|
|
192
|
+
3. **完成后回到本文件**,查看下一阶段路由
|
|
193
|
+
|
|
194
|
+
### 何时读取 references/ 文件
|
|
195
|
+
|
|
196
|
+
- **`references/sub-agent-prompt.md`** — 阶段2派发 Sub-agent 前必读
|
|
197
|
+
- **`references/feedback-types.md`** — 阶段5.5收到用户反馈后必读
|
|
198
|
+
- **`references/example-structures.md`** — 阶段4判断示例代码组织方式时查阅
|
|
199
|
+
- **`references/gotchas.md`** — 遇到问题时查阅已知坑点
|
|
200
|
+
- **`references/axis-types.md`** — 阶段0.5 主轴判定、阶段3.0 主轴校验、阶段3.4.5 深度档判定、深潜前必读
|
|
201
|
+
|
|
202
|
+
### 输出规范
|
|
203
|
+
|
|
204
|
+
所有输出格式(语言规范、版本冲突格式、章节模板)参见 **`rules/output-format.md`**。
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## 阶段决策树
|
|
209
|
+
|
|
210
|
+
### 进入阶段 3.5 的条件(缺口识别)— 强制关卡
|
|
211
|
+
|
|
212
|
+
阶段3合并大纲完成后,**必须执行**以下风险扫描(不可跳过),扫描后根据结果决定是否进入阶段3.5:
|
|
213
|
+
|
|
214
|
+
| 风险类型 | 自动触发阶段3.5 的条件 |
|
|
215
|
+
|---------|---------------------|
|
|
216
|
+
| 来源单一 | 某章节的所有知识点来自同一份资料 |
|
|
217
|
+
| 覆盖不足 | coverage_gaps 中提到的主题在大纲中没有对应章节 |
|
|
218
|
+
| 冲突未解 | 某知识点有 VERSION_CONFLICT 但双方证据都来自三手资料 |
|
|
219
|
+
|
|
220
|
+
**如果满足任一条件**:主动向用户展示缺口报告并询问是否补充搜索,用户确认后进入阶段3.5。
|
|
221
|
+
|
|
222
|
+
**如果都不满足**:询问用户"大纲质量检查通过,可以直接进入阶段4。是否需要额外补充资料?",用户说"不需要"则跳过阶段3.5。
|
|
223
|
+
|
|
224
|
+
### 进入阶段 5.5 的条件(交互式完善)
|
|
225
|
+
|
|
226
|
+
阶段5人工审核完成后,**必须**进入阶段5.5。
|
|
227
|
+
|
|
228
|
+
询问用户:"请阅读教程并标记不清楚的地方。可以直接引用章节+段落,比如'3.4 git stash — 指令描述含糊'。"
|
|
229
|
+
|
|
230
|
+
- **用户给出反馈** → 执行 `workflows/stage5.5-iterate.md`
|
|
231
|
+
- **用户说"没有"或"可以了"** → 跳过阶段5.5,进入阶段6
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## 常见错误速查
|
|
236
|
+
|
|
237
|
+
| 问题 | 查阅文档 |
|
|
238
|
+
|------|---------|
|
|
239
|
+
| 收集到的都是二手摘要 | `references/gotchas.md` — "来源质量问题" |
|
|
240
|
+
| 主进程直接读取原始 URL | `rules/core-principles.md` — "主进程不直接读原文" |
|
|
241
|
+
| 两份资料矛盾,静默选择了新的 | `rules/core-principles.md` — "矛盾必须保留" |
|
|
242
|
+
| 把不同时代的方案混在一起 | `references/gotchas.md` — "版本混淆问题" |
|
|
243
|
+
| 章节写不下去强行填充 | `rules/quality-gates.md` — "卡顿信号处理" |
|
|
244
|
+
| 教程内容是概念堆叠、缺乏教学深度 | `workflows/stage4-chapter-agent.md` — "教学设计专家模式" |
|
|
245
|
+
| 用类比替代了定义,术语模糊 | `rules/core-principles.md` — "定义优先,类比辅助" |
|
|
246
|
+
| 章节缺少主题导言(是什么/怎么来的/现状/应用) | `workflows/stage4-chapter-agent.md` — "0.5 本章导言" |
|
|
247
|
+
| topic_context 字段为空,导言素材不足 | `references/sub-agent-prompt.md` — "主题背景采集" 章节 |
|
|
248
|
+
| 流程图/架构图未绘制,只有文字描述 | `workflows/stage4-chapter-agent.md` — "C+. 可视化(按需)" |
|
|
249
|
+
| 所有知识点深度一视同仁,重点没有突出 | `workflows/stage2.5-importance.md` — 领域评级;`workflows/stage3-merge.md` §3.4.5 — 主题评级 |
|
|
250
|
+
| 核心知识点只有一个示例或没有边界说明 | `workflows/stage4-chapter-agent.md` — "核心规则:深度指令优先",三层示例要求 |
|
|
251
|
+
| 不确定生成内容是否准确可靠 | `workflows/stage4.5-verify.md` — "内容质量抽样验证" |
|
|
252
|
+
| 验证器对 [了解] 知识点扣分(因为没有 WHY 或只有一个示例) | `workflows/stage4.5-verify.md` — "评估前:确认重要性等级" |
|
|
253
|
+
| 工作区文件散乱、找不到某个中间产物 | `analysis/workspace-file-convention.md` — 工作区文件结构规范 |
|
|
254
|
+
| 教程生成后不知道工作区哪些文件可以删除 | `analysis/workspace-file-convention.md` — §5.3 清理规则 |
|
|
255
|
+
| 用户要求深化某个具体知识点或章节 | `workflows/stage5.5-iterate.md` — §5.5.7 渐进深化命令 |
|
|
256
|
+
| 教程内容偏离用户实际需求(太多无关内容) | `templates/MISSION.md` — 检查 Mission 的 Out of Scope 是否被遵循 |
|
|
257
|
+
| 用户说不清为什么学、学完要做什么 | `workflows/stage0.5-mission.md` — §0.5.1 入口判断,标记 [UNDEFINED] |
|
|
258
|
+
| 修改了文件内容,但标题/定位声明已过期 | `rules/core-principles.md` — "名实一致" |
|
|
259
|
+
| 默认存量内容(日期/数字/归属)正确,未核验 | `rules/core-principles.md` — "存量事实必须核验" |
|
|
260
|
+
| 一次大补丁改多处导致部分未匹配 | `references/gotchas.md` — "错误12:小步修改,读回验证" |
|
|
261
|
+
| 所有领域都按同一根轴组织(如给工具领域画时间线) | `references/axis-types.md` — 领域主轴分类法;`workflows/stage3-merge.md` — 主轴校验 |
|
|
262
|
+
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
## 工具与资源
|
|
266
|
+
|
|
267
|
+
- **PDF 转换**:`scripts/pdf_to_md.py <pdf路径> <输出路径>`(路径相对于本 skill 目录,即本 SKILL.md 所在目录,不写死绝对路径)
|
|
268
|
+
- **MCP 工具**:本 skill 以 `<server>:<tool>` 中性记法引用 MCP 工具(符合 MCP 工具名规范 `[a-zA-Z0-9_-]`)。实际调用名以当前客户端注册为准——不同平台前缀规则不同(如 Hermes / Claude Code 中为 `mcp__<server>__<tool>`),执行时先确认平台实际工具名:
|
|
269
|
+
- `context7:query-docs` — 查官方文档(优先)
|
|
270
|
+
- `exa:web_search_exa` / `exa:research_paper_search` — 搜索高质量博客 / 学术论文
|
|
271
|
+
- `tavily:*` — Tavily 备用搜索与抓取
|
|
272
|
+
- `drawio:*` — 绘制流程图(阶段5.5必用;不可用时按阶段0降级策略处理)
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
## 下一步
|
|
277
|
+
|
|
278
|
+
现在开始阶段0:询问用户选择"快速参考"还是"完整教程"模式。
|