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,214 @@
1
+ # 阶段1:收集资料
2
+
3
+ 处理用户提供的资料,评估来源质量,确认是否补充搜索。
4
+
5
+ ---
6
+
7
+ ## 1.1 处理用户提供的资料
8
+
9
+ 根据资料类型采用不同处理方式:
10
+
11
+ | 类型 | 处理方式 | 工具 |
12
+ |------|---------|------|
13
+ | URL 链接 | 抓取全文 | `exa:crawling_exa` 或 `tavily:tavily_extract` |
14
+ | Markdown 文件路径 | 直接读取 | Read 工具 |
15
+ | PDF 文件路径 | 先转换再读取 | `scripts/pdf_to_md.py` |
16
+
17
+ ### PDF 转换命令
18
+
19
+ ```bash
20
+ python "<skill目录>/scripts/pdf_to_md.py" <pdf路径> <输出路径>
21
+ ```
22
+
23
+ **说明**:`<skill目录>` 指本 skill 的安装目录(即 SKILL.md 所在目录)。路径因平台而异,不要写死。
24
+
25
+ ---
26
+
27
+ ## 1.2 来源质量分级
28
+
29
+ 对每份资料评估来源类型:
30
+
31
+ | 类型 | 示例 | 权重 | 可信度 |
32
+ |------|------|------|--------|
33
+ | **一手资料**(优先) | 官方文档、RFC、创始人博客、源代码仓库 | 高 | 最权威 |
34
+ | **二手资料**(可用) | 知名技术博客、经过验证的教程、技术书籍 | 中 | 可信 |
35
+ | **三手资料**(谨慎) | 转载文章、未注明来源的博客、过时教程 | 低 | 需交叉验证 |
36
+
37
+ ### 目标资料数量
38
+
39
+ | 学习模式 | 推荐资料数 |
40
+ |---------|-----------|
41
+ | 快速参考 | 3-8 份 |
42
+ | 完整教程 | 8-20 份 |
43
+
44
+ ### 质量检查门
45
+
46
+ 收集完成后,统计来源类型分布,检查是否满足最低要求(参见 `rules/quality-gates.md` 的"来源质量检查"):
47
+
48
+ | 检查项 | 最低要求 |
49
+ |--------|---------|
50
+ | 一手资料 | ≥1 份 |
51
+ | 三手资料占比 | <50% |
52
+
53
+ **不达标处理**:
54
+ - 没有一手资料 → 必须补充搜索官方文档
55
+ - 三手资料占比 >50% → 警告用户,建议补充权威来源
56
+
57
+ ---
58
+
59
+ ## 1.3 确认是否补充搜索
60
+
61
+ ### Mission 驱动的搜索关键词
62
+
63
+ 在生成搜索建议之前,先检查工作区中是否存在 `MISSION.md`:
64
+
65
+ **若 Mission 已固化**:搜索关键词从 `"{主题} 教程"` 改为 `"{主题} {Mission.Why 中的场景}"`。同时在搜索关键词中排除 `Out of Scope` 中列出的领域。
66
+
67
+ ```
68
+ 示例:
69
+ Mission.Why = "部署 Node 应用到服务器"
70
+ 搜索词: "Docker 部署 Node 应用"、"docker-compose Node 生产环境"
71
+ 排除词: "K8s"、"Docker Swarm"(Out of Scope)
72
+ ```
73
+
74
+ **若 Mission 为 [UNDEFINED]**:使用传统通用搜索关键词(`"{主题} 入门"`、`"{主题} 最佳实践"`),但在搜索建议展示时提示用户:"Mission 未指定,将使用通用搜索范围。可随时补写 Mission 来缩小范围。"
75
+
76
+ ### 用户确认环节
77
+
78
+ 读取完用户提供的资料后,分析覆盖情况,**主动询问用户**:
79
+
80
+ > "已读取 N 份资料,主要覆盖了 [xxx]。建议额外搜索以下内容补充缺失部分:
81
+ > 1. [建议搜索词]
82
+ > 2. [...]
83
+ >
84
+ > 是否继续?(本轮最多额外搜索 5 篇,优先使用 context7 查官方文档)"
85
+
86
+ ### 补充搜索规则
87
+
88
+ - **每轮上限**:5 篇
89
+ - **超出处理**:需用户再次确认
90
+ - **搜索顺序**:
91
+ 1. 优先使用 `context7:query-docs` 查官方文档
92
+ 2. 再用 `exa:web_search_exa` 搜索高质量博客
93
+
94
+ ### 用户回复处理
95
+
96
+ | 用户回复 | 处理方式 |
97
+ |---------|---------|
98
+ | "是" / "继续" / "需要" | 执行补充搜索,每个建议搜索词查询1-2篇 |
99
+ | "否" / "不需要" / "跳过" | 直接进入阶段2 |
100
+ | "部分补充" + 指定编号 | 仅对指定的搜索词执行补充 |
101
+
102
+ ---
103
+
104
+ ## 1.4 记录资料清单
105
+
106
+ 收集完成后,在工作区创建 `_internal/01-collect/source-list.md`(先创建 `_internal/01-collect/` 目录),记录所有资料的元信息:
107
+
108
+ ```markdown
109
+ # [主题] 资料清单
110
+
111
+ ## 用户提供资料(X份)
112
+
113
+ | 序号 | 资料名称 | 来源类型 | 格式 | 备注 |
114
+ |------|---------|---------|------|------|
115
+ | 1 | React 官方文档 | 一手 | URL | https://react.dev |
116
+ | 2 | React Hooks 教程 | 二手 | Markdown | 本地文件 |
117
+ | ... | ... | ... | ... | ... |
118
+
119
+ ## 补充搜索资料(Y份)
120
+
121
+ | 序号 | 资料名称 | 来源类型 | 搜索词 | 备注 |
122
+ |------|---------|---------|--------|------|
123
+ | 1 | useState 官方说明 | 一手 | "React useState" | 使用 context7 查询 |
124
+ | ... | ... | ... | ... | ... |
125
+
126
+ ## 来源质量统计
127
+
128
+ - 一手资料:X 份(占比 X%)
129
+ - 二手资料:Y 份(占比 Y%)
130
+ - 三手资料:Z 份(占比 Z%)
131
+ - 总计:N 份
132
+ ```
133
+
134
+ ---
135
+
136
+ ## 1.5 保存会话状态
137
+
138
+ 在进入下一阶段前,更新工作区的 `session-state.md`:
139
+
140
+ ```markdown
141
+ # 会话状态
142
+ 主题: [主题名]
143
+ 更新时间: [当前时间]
144
+ 学习模式: [快速参考 / 完整教程]
145
+ 工作区: [工作区绝对路径]
146
+
147
+ ---
148
+
149
+ ## 进度
150
+ 当前阶段: 2
151
+ 已完成阶段: 1
152
+
153
+ ## 阶段输出
154
+ - **阶段1**: `_internal/01-collect/source-list.md` — [N]份资料([A]一手 / [B]二手 / [C]三手)
155
+
156
+ ---
157
+
158
+ ## 恢复指令
159
+ 读取工作区下的 `_internal/01-collect/source-list.md` 了解已收集的资料,继续阶段2(Sub-agent 并行精读)。
160
+ ```
161
+
162
+ ---
163
+
164
+ ## 1.6 进入下一阶段
165
+
166
+ 确认资料收集完成后,向用户说明:
167
+
168
+ > "资料收集完成,共 N 份资料(一手 X 份 / 二手 Y 份 / 三手 Z 份)。
169
+ >
170
+ > 现在进入阶段2:为每份资料派发 Sub-agent 进行深度精读。"
171
+
172
+ 然后读取 `workflows/stage2-extract.md` 执行阶段2。
173
+
174
+ ---
175
+
176
+ ## 常见问题
177
+
178
+ **Q1:用户提供的 PDF 文件很大(>100页),是否全部转换?**
179
+
180
+ A:先询问用户:"PDF 文件较大,是否有特定章节需要提取?" 如果用户指定章节,使用 `--pages` 参数:
181
+ ```bash
182
+ python scripts/pdf_to_md.py <pdf路径> <输出路径> --pages "1-10,25-30"
183
+ ```
184
+
185
+ **Q2:URL 抓取失败怎么办?**
186
+
187
+ A:尝试以下方案:
188
+ 1. 切换到另一个抓取工具(`exa:crawling_exa` ↔ `tavily:tavily_extract`)
189
+ 2. 询问用户是否可以提供该资料的本地副本
190
+ 3. 跳过该资料,继续处理其他资料
191
+
192
+ **Q3:用户没有提供资料,只提供了一个学习主题(如"React"),怎么办?**
193
+
194
+ A:直接进入补充搜索模式:
195
+ 1. 使用 `context7:query-docs` 查询官方文档
196
+ 2. 生成3-5个常见搜索词(如"React 入门"、"React Hooks"、"React 最佳实践")
197
+ 3. 每个搜索词查询2-3篇高质量资料
198
+ 4. 向用户展示找到的资料清单,询问是否满意
199
+
200
+ ---
201
+
202
+ ## 执行检查清单
203
+
204
+ 完成阶段1后,自检:
205
+ - [ ] 所有用户提供的资料已处理(URL 抓取 / PDF 转换 / Markdown 读取)
206
+ - [ ] 来源质量分级已完成
207
+ - [ ] 已在 `_internal/01-collect/` 下创建 source-list.md
208
+ - [ ] 来源质量满足最低要求(≥1份一手资料,三手资料<50%)
209
+ - [ ] 已询问用户是否补充搜索
210
+ - [ ] 资料总数在合理范围内(快速参考 3-8 份,完整教程 8-20 份)
211
+
212
+ - [ ] session-state.md 已创建并记录阶段1输出
213
+
214
+ 如果任一项为"否",补充完成后再进入阶段2。
@@ -0,0 +1,254 @@
1
+ # 阶段2:Sub-agent 并行精读
2
+
3
+ 为每份资料派发独立的 Sub-agent 进行深度阅读,返回结构化知识报告。
4
+
5
+ ---
6
+
7
+ ## 2.1 派发 Sub-agent
8
+
9
+ **核心原则**:在**同一轮**中为所有资料各启动一个 Sub-agent,全部并行,不等待任何一个完成再启动下一个。
10
+
11
+ ### 并行派发示例
12
+
13
+ ```
14
+ # 伪代码示例
15
+ For 每份资料 in 资料清单:
16
+ Agent({
17
+ description: "提取[资料名称]知识",
18
+ prompt: [读取 references/sub-agent-prompt.md,填入资料信息]
19
+ })
20
+ ```
21
+
22
+ **关键**:所有 `Agent()` 调用在同一个 message 中发出。
23
+
24
+ ---
25
+
26
+ ## 2.2 Sub-agent 指令生成
27
+
28
+ **必须先读取** `references/sub-agent-prompt.md` 获取标准指令模板。
29
+
30
+ ### 填充模板
31
+
32
+ 模板中需要填充的变量:
33
+
34
+ | 变量 | 来源 | 示例 |
35
+ |------|------|------|
36
+ | `[文件路径 / URL]` | 阶段1的资料清单 | `https://react.dev` 或 `/path/to/file.md` |
37
+ | `[直接读取 / 使用 fetchWebContent 抓取]` | 根据资料类型 | URL → 抓取;本地文件 → 直接读取 |
38
+ | `[学习主题]` | 用户提供的主题 | "React Hooks" |
39
+ | `[一手 / 二手 / 三手]` | 阶段1的来源质量分级 | "一手" |
40
+
41
+ ### 生成的指令示例
42
+
43
+ ```
44
+ 你是知识提取专家。请深度阅读以下资料,提取所有知识点,输出一份结构化「知识报告」。
45
+
46
+ 资料来源:https://react.dev/reference/react/useState
47
+ 资料处理:使用 fetchWebContent 抓取
48
+ 主题领域:React Hooks
49
+ 来源类型:一手
50
+
51
+ 输出严格按照以下 JSON,不输出其他内容:
52
+ {
53
+ "source": "资料标题或 URL",
54
+ "source_type": "primary | secondary | tertiary",
55
+ "tech_era": "技术年代,如 '2016年前 jQuery 时代' 或 '现代 React 18+',无法判断则填 null",
56
+ "topic_context": { "origin": "...", "evolution": "...", "current_status": "...", "applications": "..." },
57
+ "knowledge_points": [...],
58
+ "conflicts": [...],
59
+ "coverage_gaps": [...]
60
+ }
61
+ ```
62
+
63
+ 完整 JSON schema 参见 `references/sub-agent-prompt.md`。
64
+
65
+ ---
66
+
67
+ ## 2.3 降级处理(环境不支持 Sub-agent)
68
+
69
+ 如果当前环境不支持 Sub-agent(如工具调用受限),改为**串行处理**:
70
+
71
+ ### 串行流程
72
+
73
+ ```
74
+ For 每份资料 in 资料清单:
75
+ 1. 读取该资料内容
76
+ 2. 主进程执行知识提取(按照 sub-agent-prompt.md 的要求)
77
+ 3. 输出 JSON 知识报告到本地文件:`_internal/02-extract/kp-[NN:02d]-[资料简称].json`(先创建 `_internal/02-extract/` 目录)
78
+ 4. 清理该资料内容(主进程只保留 JSON 报告)
79
+ 5. 进入下一份资料
80
+ ```
81
+
82
+ **注意**:
83
+ - 串行时主进程上下文会增长,但仍比"一次性读入所有资料"好
84
+ - 每份资料处理完后立即输出报告,避免累积
85
+ - 不推荐使用降级模式(效率低,质量差),仅在无 Sub-agent 时使用
86
+
87
+ ---
88
+
89
+ ## 2.4 等待所有 Sub-agent 完成
90
+
91
+ 并行派发后,等待所有 Sub-agent 返回结果。
92
+
93
+ ### 收集知识报告
94
+
95
+ 每个 Sub-agent 返回的 JSON 知识报告应包含以下字段(参见 `references/sub-agent-prompt.md`):
96
+
97
+ ```json
98
+ {
99
+ "source": "资料标题",
100
+ "source_type": "primary | secondary | tertiary",
101
+ "tech_era": "技术年代或 null",
102
+ "topic_context": {
103
+ "origin": "主题起源/解决的历史问题,基于原文,无则 null",
104
+ "evolution": "演进脉络,基于原文,无则 null",
105
+ "current_status": "发展现状与前景,基于原文,无则 null",
106
+ "applications": "典型应用场景,基于原文,无则 null"
107
+ },
108
+ "knowledge_points": [
109
+ {
110
+ "id": "kp-001",
111
+ "title": "知识点标题",
112
+ "level": "初学 | 熟练 | 精通",
113
+ "summary": "核心内容 + 使用场景",
114
+ "key_example": "代码片段(可选)",
115
+ "is_domain_specific": true/false
116
+ }
117
+ ],
118
+ "conflicts": [
119
+ {
120
+ "topic": "冲突主题",
121
+ "this_doc_says": "本资料观点",
122
+ "conflict_type": "version_diff | deprecated | approach_diff",
123
+ "evidence": "依据"
124
+ }
125
+ ],
126
+ "coverage_gaps": ["缺失内容"]
127
+ }
128
+ ```
129
+
130
+ ### 保存知识报告
131
+
132
+ 将每个 Sub-agent 返回的 JSON 保存到工作区:
133
+
134
+ ```
135
+ 工作区/
136
+ └── _internal/
137
+ └── 02-extract/
138
+ ├── kp-01-{shortname}.json ← 资料1的知识报告
139
+ ├── kp-02-{shortname}.json ← 资料2的知识报告
140
+ └── ...
141
+ ```
142
+
143
+ **命名说明**:
144
+ - `NN`:资料序号,2 位补零,从 01 开始连续递增,不跳号
145
+ - `{shortname}`:资料简称,英文小写 + 连字符,≤30 字符(如 `huggingface-transformers`、`peft-lora`)
146
+ - 若某份资料提取失败被跳过,保留序号占位并记录到 session-state
147
+ - 先创建目录 `_internal/02-extract/`(如不存在)
148
+
149
+ ---
150
+
151
+ ## 2.5 质量检查
152
+
153
+ 所有知识报告收集完成后,进行质量检查:
154
+
155
+ ### 检查项
156
+
157
+ | 检查项 | 检查方式 | 不合格处理 |
158
+ |--------|---------|-----------|
159
+ | JSON 格式正确 | 解析 JSON | 提示该 Sub-agent 重新生成 |
160
+ | 知识点数量 | 统计 `knowledge_points` 数组长度 | 少于3个 → 可能资料质量差或提取不充分 |
161
+ | `tech_era` 字段 | 检查是否为 null | 如果重要概念的 `tech_era` 为 null,提示 Sub-agent 补充 |
162
+ | `conflicts` 识别 | 检查是否有冲突记录 | 如果资料明显与主流方案不同但没有 `conflicts`,提示 Sub-agent 重新识别 |
163
+
164
+ ### 统计信息
165
+
166
+ 汇总所有知识报告,向用户展示:
167
+
168
+ > "Sub-agent 精读完成。
169
+ >
170
+ > **知识报告统计**:
171
+ > - 资料总数:N 份
172
+ > - 知识点总数:X 个(初学 Y 个 / 熟练 Z 个 / 精通 W 个)
173
+ > - 发现冲突:K 处
174
+ > - 覆盖缺口:M 项
175
+ >
176
+ > 现在进入阶段3:合并大纲。"
177
+
178
+ ---
179
+
180
+ ## 2.6 保存会话状态
181
+
182
+ 更新工作区的 `session-state.md`:
183
+
184
+ ```markdown
185
+ # 会话状态
186
+ 主题: [主题名]
187
+ 更新时间: [当前时间]
188
+ 学习模式: [快速参考 / 完整教程]
189
+ 工作区: [工作区绝对路径]
190
+
191
+ ---
192
+
193
+ ## 进度
194
+ 当前阶段: 3
195
+ 已完成阶段: 1, 2
196
+
197
+ ## 阶段输出
198
+ - **阶段1**: 资料清单.md — [N]份资料([A]一手 / [B]二手 / [C]三手)
199
+ - **阶段2**: `_internal/02-extract/` — [X]个知识点(初学[a]/熟练[b]/精通[c]),[K]处冲突,[M]项缺口
200
+
201
+ ---
202
+
203
+ ## 恢复指令
204
+ 读取工作区下的 `_internal/02-extract/` 目录获取所有知识报告,继续阶段3(合并大纲)。
205
+ ```
206
+
207
+ ---
208
+
209
+ ## 2.7 进入下一阶段
210
+
211
+ 读取 `workflows/stage3-merge.md` 执行阶段3。
212
+
213
+ ---
214
+
215
+ ## 常见问题
216
+
217
+ **Q1:某个 Sub-agent 超时或失败怎么办?**
218
+
219
+ A:
220
+ 1. 检查失败原因(网络问题?资料过大?)
221
+ 2. 重试该 Sub-agent(最多2次)
222
+ 3. 如果仍失败,询问用户:"资料 [名称] 处理失败,是否跳过该资料继续?"
223
+
224
+ **Q2:Sub-agent 返回的知识点太少(<3个),是否正常?**
225
+
226
+ A:
227
+ - 如果资料本身很短(<500字)→ 正常
228
+ - 如果资料很长但知识点很少 → 可能 Sub-agent 提取不充分,建议重新派发
229
+
230
+ **Q3:不同 Sub-agent 提取到了相同的知识点怎么办?**
231
+
232
+ A:这是正常现象(多份资料可能讲相同内容)。阶段3的"分级三问"会处理去重。
233
+
234
+ **Q4:Sub-agent 返回的 JSON 格式不正确怎么办?**
235
+
236
+ A:
237
+ 1. 提示该 Sub-agent:"返回的 JSON 格式不正确,请严格按照模板输出。"
238
+ 2. 如果重试2次仍失败,手动修正 JSON 格式(如补全缺失的括号)
239
+ 3. 记录该资料"需要人工复核"
240
+
241
+ ---
242
+
243
+ ## 执行检查清单
244
+
245
+ 完成阶段2后,自检:
246
+ - [ ] 所有资料都已派发 Sub-agent(并行或串行)
247
+ - [ ] 所有知识报告已收集并保存到本地
248
+ - [ ] 知识报告 JSON 格式正确
249
+ - [ ] 已统计知识点总数、冲突数、缺口数
250
+ - [ ] 主进程上下文精简(只保留 JSON 报告,不保留原始资料内容)
251
+
252
+ - [ ] session-state.md 已更新,记录阶段2知识点统计
253
+
254
+ 如果任一项为"否",补充完成后再进入阶段3。
@@ -0,0 +1,197 @@
1
+ # 阶段2.5:知识领域重要性评级
2
+
3
+ Sub-agent 精读完成后、合并大纲前执行。目的:只有对某个领域掌握充分的资料,才能建立正确完整的主题(不遗漏、不错误拆分)。因此**资料补充必须在大纲之前完成**。
4
+
5
+ ---
6
+
7
+ ## 2.5.1 粗粒度主题聚合
8
+
9
+ 浏览所有知识报告(报告为约400字的压缩 JSON,可直接浏览;若报告数超过 25 份,先按标题/主题字段粗聚合,仅浏览各领域的代表性报告,避免上下文膨胀),将知识点按主题领域聚合为若干"知识领域"——对应最终教程中每个 Markdown 文件的覆盖范围。
10
+
11
+ **这不是正式大纲**,只是识别"有哪些独立领域"。
12
+
13
+ **聚合方法**:
14
+ - 扫描所有 `knowledge_points` 的 `title` 和 `summary`,按语义归组
15
+ - 跨多份资料反复出现的同一主题归为一个领域
16
+ - 粒度:一个领域 = 最终一个 `.md` 文件的内容范围
17
+
18
+ **示例(React 教程)**:
19
+ ```
20
+ 领域A:组件基础(JSX、函数组件、Props)
21
+ 领域B:Hooks(useState、useEffect、自定义 Hook)
22
+ 领域C:状态管理(Context API、Redux 生态)
23
+ 领域D:性能优化(memo、useMemo、Profiler)
24
+ 领域E:路由(React Router)
25
+ ```
26
+
27
+ ---
28
+
29
+ ## 2.5.2 AI 初评
30
+
31
+ 对每个领域从四个维度打分,推导建议等级。
32
+
33
+ **前置条件**:评级前先读取 MISSION.md(如已固化)——重要性评级的目的是服务学习目的,Mission 的 Why/Success 是评级的输入而非可选项。Mission 为 [UNDEFINED] 时按通用标准评级,并在展示时提示"补写 Mission 后等级可能需要重评"。
34
+
35
+ ### 评判维度
36
+
37
+ | 维度 | 高 | 中 | 低 |
38
+ |------|---|---|---|
39
+ | **前置依赖度** | ≥2 个其他领域依赖它 | 1 个领域依赖 | 无其他领域依赖 |
40
+ | **使用频率** | 典型项目每天用 | 每周偶尔用 | 很少用或随时查文档替代 |
41
+ | **误解后果** | 产生 bug / 安全问题 | 代码质量明显下降 | 几乎无影响 |
42
+ | **领域核心性** | 该技术独有的核心特性 | 通用但重要 | 边缘特性或可查文档 |
43
+
44
+ ### 等级判定规则
45
+
46
+ | 等级 | 判定条件 |
47
+ |------|---------|
48
+ | **核心必掌握** | ≥3 个维度为"高";或"前置依赖度"为"高"且其他 ≥1 个为"高" |
49
+ | **重要** | 2 个维度为"高";或多个维度为"中" |
50
+ | **了解即可** | 主要为"低"或"中",且无高前置依赖 |
51
+
52
+ > 符合主轴高档判定标准(见 `references/axis-types.md`)的核心领域,额外标注【深潜候选】,供阶段3.4.5 深度档判定参考。
53
+
54
+ ### Mission 相关性加权(后处理)
55
+
56
+ 以上四维度评分完成后,若工作区中存在已固化的 `MISSION.md`,对每个领域执行以下校正:
57
+
58
+ | Mission 相关性 | 判定标准 | 校正规则 |
59
+ |---------------|---------|---------|
60
+ | **直接相关** | 该领域与 Mission.Why 描述的场景直接对应 | 等级自动升一档(了解→重要,重要→核心。核心不变) |
61
+ | **间接相关** | 虽非直接场景,但属于 Mission.Success 的前提条件 | 等级不变,但在向用户展示的评级表中标注 `[Mission 相关]` |
62
+ | **无关(Out of Scope)** | 该领域在 Mission.Out of Scope 中被明确列出 | 等级强制降为"了解即可",在评级表中标注 `[已排除]` |
63
+
64
+ > "Mission 相关性加权"不影响四维度原始评分,仅在校正后的展示等级上体现。原始评分保留供后续参考。
65
+
66
+ ---
67
+
68
+ ## 2.5.3 向用户展示初评结果(一次性批量确认)
69
+
70
+ 展示以下格式,让用户一次性确认或指出需要调整的项:
71
+
72
+ ```
73
+ > **知识领域重要性评级——请确认或指出需调整项,然后回复"确认"**
74
+ >
75
+ > | 知识领域 | 前置依赖 | 使用频率 | 误解后果 | 领域核心性 | Mission 相关 | 建议等级 | 补充搜索计划 |
76
+ > |---------|---------|---------|---------|-----------|------------|---------|------------|
77
+ > | 组件基础 | 高 | 每天 | bug | 核心特性 | 直接相关 ↑ | **核心必掌握** | 补搜 5 篇 |
78
+ > | Hooks | 高 | 每天 | bug | 核心特性 | 直接相关 ↑ | **核心必掌握** | 补搜 5 篇 |
79
+ > | 状态管理 | 中 | 每天 | 代码质量 | 通用 | 间接相关 | **重要** | 补搜 2 篇 |
80
+ > | 性能优化 | 低 | 偶尔 | 几乎无 | 核心特性 | — | **重要** | 补搜 2 篇 |
81
+ > | 路由 | 低 | 偶尔 | 几乎无 | 通用 | — | **了解即可** | 不补搜 |
82
+ >
83
+ > Mission 未固化时省略"Mission 相关"列。校正规则参见上方"Mission 相关性加权"。
84
+ ```
85
+
86
+ 用户确认后继续。
87
+
88
+ ---
89
+
90
+ ## 2.5.4 补充专项搜索
91
+
92
+ 按等级执行补充搜索:
93
+
94
+ | 等级 | 额外搜索篇数 | 搜索方向 |
95
+ |------|------------|---------|
96
+ | **核心必掌握** | 5 篇 | 官方文档深层页、常见误区、边界条件、进阶用法专项内容 |
97
+ | **重要** | 2 篇 | 官方文档或高质量博客 |
98
+ | **了解即可** | 0 篇 | 使用阶段1已有资料,不补搜 |
99
+
100
+ ### 搜索关键词设计原则
101
+
102
+ 针对**该领域的难点和边界**,不要泛搜领域名称:
103
+
104
+ ```
105
+ [错误] "React Hooks"(太泛,搜出来都是入门介绍)
106
+ [正确] "React useState stale closure pitfalls"(针对高频误区)
107
+ [正确] "React useEffect cleanup timing edge cases"(针对边界条件)
108
+ [正确] "React useEffect dependency array rules"(针对规则的深度解释)
109
+ ```
110
+
111
+ ### 搜索与提取
112
+
113
+ 1. 按 `workflows/stage1-collect.md` 的搜索方式执行(先 context7,再 exa)
114
+ 2. 为每份补充资料派发 Sub-agent(与阶段2相同)
115
+ 3. 新知识报告保存到 `_internal/02-extract/`,文件名加 `-supplement-[领域]` 后缀
116
+
117
+ 所有补充 Sub-agent 在同一轮并行派发(参见 `rules/core-principles.md`)。
118
+
119
+ ---
120
+
121
+ ## 2.5.5 保存评级结果
122
+
123
+ 将确认后的评级写入工作区 `importance-ratings.json`(供后续阶段3.x、阶段4引用):
124
+
125
+ ```json
126
+ {
127
+ "domains": [
128
+ {
129
+ "domain": "Hooks",
130
+ "level": "core",
131
+ "rationale": "所有函数组件状态/副作用的基础,误解导致闭包 bug,高频使用"
132
+ },
133
+ {
134
+ "domain": "性能优化",
135
+ "level": "important",
136
+ "rationale": "核心特性但使用频率偶尔,误解后果有限"
137
+ },
138
+ {
139
+ "domain": "路由",
140
+ "level": "reference",
141
+ "rationale": "通用知识,边缘特性,随查随用"
142
+ }
143
+ ],
144
+ "topics": []
145
+ }
146
+ ```
147
+
148
+ `topics` 数组在阶段3.x评级完成后填入。
149
+
150
+ 更新 `_internal/01-collect/source-list.md`,在末尾追加补充区域:
151
+
152
+ ```markdown
153
+ ## 阶段2.5 专项补充资料
154
+
155
+ | 序号 | 资料 | 来源类型 | 针对领域 | 领域等级 |
156
+ |------|------|---------|---------|---------|
157
+ | 1 | [资料名/URL] | 一手 | Hooks | 核心必掌握 |
158
+ | 2 | [资料名/URL] | 二手 | Hooks | 核心必掌握 |
159
+ ```
160
+
161
+ 更新 `session-state.md`:
162
+
163
+ ```markdown
164
+ ## 进度
165
+ 当前阶段: 3
166
+ 已完成阶段: 1, 2, 2.5
167
+
168
+ ## 阶段输出
169
+ - **阶段2.5**: importance-ratings.json — 领域评级(核心[X]个/重要[Y]个/了解[Z]个),补充资料[N]篇
170
+ ```
171
+
172
+ ---
173
+
174
+ ## 2.5.6 进入阶段3
175
+
176
+ 向用户说明:
177
+
178
+ > "专项补充完成。
179
+ >
180
+ > **评级统计**:核心必掌握 [X] 个,重要 [Y] 个,了解即可 [Z] 个
181
+ > **补充资料**:核心领域补搜 [A] 篇,重要领域补搜 [B] 篇
182
+ >
183
+ > 现在进入阶段3:基于完整资料合并大纲。"
184
+
185
+ 读取 `workflows/stage3-merge.md` 执行阶段3。
186
+
187
+ ---
188
+
189
+ ## 执行检查清单
190
+
191
+ - [ ] 所有知识报告已浏览,粗粒度主题聚合完成
192
+ - [ ] 每个领域四维度评分已完成,初评表已展示
193
+ - [ ] 用户已批量确认(或修改后确认)评级
194
+ - [ ] 核心领域已补搜 ≥5 篇,重要领域已补搜 ≥2 篇
195
+ - [ ] 补充资料 Sub-agent 已并行派发并完成
196
+ - [ ] importance-ratings.json 已保存(domains 数组)
197
+ - [ ] session-state.md 已更新