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.
- package/client/client.js +452 -0
- package/cordis.patch.yml +20 -16
- package/index.js +19 -0
- package/package.json +42 -13
- package/skills/dsh-learn-mode/SKILL.md +7 -5
- 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
|
@@ -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:询问用户选择"快速参考"还是"完整教程"模式。
|
|
@@ -0,0 +1,402 @@
|
|
|
1
|
+
# 工作区文件结构规范 (Workspace File Structure Specification)
|
|
2
|
+
|
|
3
|
+
> 版本: 1.0
|
|
4
|
+
> 适用范围: learn-synthesizer v0.0.5+
|
|
5
|
+
> 规范对象: 所有阶段产出的中间文件、验证报告、最终交付物
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 目录
|
|
10
|
+
|
|
11
|
+
1. [问题陈述](#1-问题陈述)
|
|
12
|
+
2. [设计原则](#2-设计原则)
|
|
13
|
+
3. [规范工作区结构](#3-规范工作区结构)
|
|
14
|
+
4. [文件命名规则](#4-文件命名规则)
|
|
15
|
+
5. [文件分类与生命周期](#5-文件分类与生命周期)
|
|
16
|
+
6. [README.md 模板](#6-readmemd-模板)
|
|
17
|
+
7. [各阶段集成改动](#7-各阶段集成改动)
|
|
18
|
+
8. [现有工作区迁移指南](#8-现有工作区迁移指南)
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 1. 问题陈述
|
|
23
|
+
|
|
24
|
+
### 当前存在的问题
|
|
25
|
+
|
|
26
|
+
以实际产出工作区 `数据处理与模型训练教程` 为例,暴露了以下问题:
|
|
27
|
+
|
|
28
|
+
#### 1.1 命名不一致
|
|
29
|
+
|
|
30
|
+
| 问题 | 实例 | 影响 |
|
|
31
|
+
|------|------|------|
|
|
32
|
+
| **知识报告编号** | `report-02.json` 起步(01 丢失),跳跃编号 | 无法确定是否有遗漏 |
|
|
33
|
+
| **验证报告命名** | `verify-ch01-03.md`、`verify-ch10-11-14.md` | 范围不规则(有的连续、有的跳号),无法从文件名推断实际覆盖范围 |
|
|
34
|
+
| **中英文混用** | `资料清单.md`(中文)vs `domain-overview.md`(英文) | 风格不统一,部分用户看不懂英文文件名 |
|
|
35
|
+
| **序号填充** | diagrams 用 2 位补零(`01-01`),knowledge-reports 编号 `02` 也是补零,但各文件命名没有统一规范 | 排序可能乱 |
|
|
36
|
+
|
|
37
|
+
#### 1.2 目录结构混乱
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
当前工作区根目录(10+ 个文件平铺):
|
|
41
|
+
├── MISSION.md ← 顶层文档
|
|
42
|
+
├── session-state.md ← 会话状态
|
|
43
|
+
├── 资料清单.md ← 阶段1
|
|
44
|
+
├── domain-overview.md ← 阶段3.0
|
|
45
|
+
├── importance-ratings.json ← 阶段3
|
|
46
|
+
├── outline.md ← 阶段3
|
|
47
|
+
├── outline-stats.json ← 阶段3
|
|
48
|
+
├── quality-report.md ← 阶段4.5
|
|
49
|
+
├── verify-ch01-03.md ← 阶段4.5
|
|
50
|
+
├── verify-ch04-06.md ← 阶段4.5(共5个验证文件)
|
|
51
|
+
├── ...
|
|
52
|
+
├── diagrams/ ← 阶段4
|
|
53
|
+
├── knowledge-reports/ ← 阶段2
|
|
54
|
+
└── 数据处理与模型训练-tutorial/ ← 阶段6 最终交付
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
**问题:** 中间产物(`verify-*.md`、`quality-report.md`、`outline.md`)与永久文档(`MISSION.md`、`session-state.md`)混在一起。用户打开工作区后无法一眼分辨哪些是过程文件、哪些是交付物。
|
|
58
|
+
|
|
59
|
+
#### 1.3 缺少元数据
|
|
60
|
+
|
|
61
|
+
- 没有 `README.md`:用户(或未来的自己)不清楚目录含义
|
|
62
|
+
- 没有文件索引:逐一打开才知道内容
|
|
63
|
+
- 没有生命周期说明:哪些可以删、哪些必须保留
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## 2. 设计原则
|
|
68
|
+
|
|
69
|
+
1. **一眼可辨**:从文件名和目录位置就能判断文件性质(中间/最终/元数据)
|
|
70
|
+
2. **统一序数**:所有与章节/资料关联的文件使用一致的零填充格式(`NN` = 2位补零,章节号≥10 也只需 2 位)
|
|
71
|
+
3. **英文优先**:技术性文件名使用英文(便于脚本处理);面向用户的说明用中文
|
|
72
|
+
4. **内部分离**:中间产物收入 `_internal/` 目录,与最终交付物隔离
|
|
73
|
+
5. **自文档化**:每个工作区必须包含 `README.md`
|
|
74
|
+
6. **可追溯**:中间产物命名包含阶段标识,可回溯到生成它的 workflow
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## 3. 规范工作区结构
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
{主题}-workspace/ ← 工作区根目录
|
|
82
|
+
│
|
|
83
|
+
├── README.md ← [永久] 工作区说明(模板见 §6)
|
|
84
|
+
├── MISSION.md ← [永久] 学习使命(阶段 0.5 产出)
|
|
85
|
+
├── session-state.md ← [持久] 会话状态(各阶段更新)
|
|
86
|
+
├── understanding-map.md ← [永久] 学习进度跟踪(阶段 6 产出)
|
|
87
|
+
├── 00-地图.md ← [永久] 领域地图层(阶段 3 产出,主轴≠概念依赖时;规模大了拆为 00-地图/ 目录)
|
|
88
|
+
│
|
|
89
|
+
├── _internal/ ← [中间] 所有构建过程产物
|
|
90
|
+
│ ├── 01-collect/ ← 阶段 1 产物
|
|
91
|
+
│ │ └── source-list.md ← 资料清单(原 资料清单.md)
|
|
92
|
+
│ │
|
|
93
|
+
│ ├── 02-extract/ ← 阶段 2 产物
|
|
94
|
+
│ │ └── kp-NN-{shortname}.json ← 知识报告(原 report-NN.json)
|
|
95
|
+
│ │
|
|
96
|
+
│ ├── 03-merge/ ← 阶段 3 产物
|
|
97
|
+
│ │ ├── domain-overview.md
|
|
98
|
+
│ │ ├── importance-ratings.json
|
|
99
|
+
│ │ ├── outline.md
|
|
100
|
+
│ │ └── outline-stats.json
|
|
101
|
+
│ │
|
|
102
|
+
│ └── 04-verify/ ← 阶段 4.5 产物
|
|
103
|
+
│ ├── quality-report.md
|
|
104
|
+
│ └── verify-NN-{range}.md ← 验证报告(按章节批次)
|
|
105
|
+
│
|
|
106
|
+
├── tutorial/ ← [最终] 教程交付物(阶段 4-6 产出)
|
|
107
|
+
│ ├── 00-学习路线图.md
|
|
108
|
+
│ ├── {模块名}/ ← 按模块分组的章节
|
|
109
|
+
│ │ ├── 01-{章节标题}.md
|
|
110
|
+
│ │ ├── 02-{章节标题}.md
|
|
111
|
+
│ │ └── ...
|
|
112
|
+
│ ├── {NN}-{参考资源}.md ← 外部参考资源索引
|
|
113
|
+
│ └── reference/ ← 独立参考文档(阶段 4.2 产出)
|
|
114
|
+
│ ├── GLOSSARY.md
|
|
115
|
+
│ ├── COMMANDS.md
|
|
116
|
+
│ ├── TEMPLATES.md
|
|
117
|
+
│ └── TROUBLESHOOTING.md
|
|
118
|
+
│
|
|
119
|
+
└── diagrams/ ← [最终] drawio 图表(阶段 4 产出)
|
|
120
|
+
└── ch{NN}-{seq:02d}_{name}.drawio
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### 结构说明
|
|
124
|
+
|
|
125
|
+
| 层级 | 目录/文件 | 性质 | 用户需要关心? |
|
|
126
|
+
|------|----------|------|-------------|
|
|
127
|
+
| 根 | `README.md` | 永久 | ✅ 第一个看的文件 |
|
|
128
|
+
| 根 | `MISSION.md` | 永久 | ✅ 学习目标 |
|
|
129
|
+
| 根 | `session-state.md` | 持久 | ⚠️ AI 维护,用户不需要手动编辑 |
|
|
130
|
+
| 根 | `understanding-map.md` | 永久 | ✅ 跟踪学习进度 |
|
|
131
|
+
| 根 | `00-地图.md` | 永久 | ✅ 领域地图层(主轴≠概念依赖时存在) |
|
|
132
|
+
| `_internal/` | 全部内容 | 中间 | ❌ 构建过程产物,用户不需要查看 |
|
|
133
|
+
| `tutorial/` | 全部内容 | 最终 | ✅ 核心交付物 |
|
|
134
|
+
| `diagrams/` | drawio 文件 | 最终 | ✅ 图表源文件,可编辑复用 |
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## 4. 文件命名规则
|
|
139
|
+
|
|
140
|
+
### 4.1 通用规则
|
|
141
|
+
|
|
142
|
+
| 规则 | 说明 | 示例 |
|
|
143
|
+
|------|------|------|
|
|
144
|
+
| 序号补零 | 章节号/资料号统一用 2 位补零(`01`-`99`) | `ch01` ✓ / `ch1` ✗ |
|
|
145
|
+
| 英文优先 | 技术性文件名用英文小写 + 连字符 | `domain-overview.md` ✓ |
|
|
146
|
+
| 中文保留场景 | 面向用户的文件名可用中文,但内部索引用英文 | `tutorial/01-数据清洗.md` ✓ |
|
|
147
|
+
| 版本标记 | 增量更新时在文件内用 `[NEW in V1.1]` 标注,不在文件名中加版本号 | — |
|
|
148
|
+
| 禁止特殊字符 | 文件名不含空格、括号、中文标点 | `kp-01-huggingface.md` ✓ / `kp-01 (HuggingFace).md` ✗ |
|
|
149
|
+
|
|
150
|
+
### 4.2 按文件类型的命名规则
|
|
151
|
+
|
|
152
|
+
#### 知识报告(`_internal/02-extract/`)
|
|
153
|
+
|
|
154
|
+
```
|
|
155
|
+
格式: kp-{index:02d}-{source-shortname}.json
|
|
156
|
+
规则:
|
|
157
|
+
- index: 资料序号,从 01 开始连续递增
|
|
158
|
+
- source-shortname: 资料简称(英文小写+连字符,≤30字符)
|
|
159
|
+
- 必须从 01 开始,不允许跳号
|
|
160
|
+
- 如果某份资料提取失败被跳过,保留序号占位并记录到 session-state
|
|
161
|
+
|
|
162
|
+
示例:
|
|
163
|
+
kp-01-official-syllabus.json ← 资料1: 竞赛官方讲义
|
|
164
|
+
kp-02-huggingface-transformers.json
|
|
165
|
+
kp-03-peft-lora.json
|
|
166
|
+
kp-07-pandas-sklearn.json
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
#### 验证报告(`_internal/04-verify/`)
|
|
170
|
+
|
|
171
|
+
```
|
|
172
|
+
格式: verify-{batch-index:02d}-ch{start:02d}-ch{end:02d}.md
|
|
173
|
+
规则:
|
|
174
|
+
- batch-index: 验证批次号,从 01 开始
|
|
175
|
+
- start/end: 该批次覆盖的章节范围,2位补零
|
|
176
|
+
- 如果批次只覆盖单个章节: verify-{batch:02d}-ch{num:02d}.md
|
|
177
|
+
|
|
178
|
+
示例:
|
|
179
|
+
verify-01-ch01-ch03.md ← 第1批: 验证 1-3 章
|
|
180
|
+
verify-02-ch04-ch06.md ← 第2批: 验证 4-6 章
|
|
181
|
+
verify-03-ch07-ch09.md
|
|
182
|
+
verify-04-ch10-ch11.md ← 注意: ch10-ch11,不是 ch10-11-14(范围必须连续)
|
|
183
|
+
verify-05-ch12-ch14.md
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
#### 图表文件(`diagrams/`)
|
|
187
|
+
|
|
188
|
+
```
|
|
189
|
+
格式: ch{chapter:02d}-{seq:02d}_{description}.drawio
|
|
190
|
+
规则:
|
|
191
|
+
- chapter: 所属章节号,2位补零
|
|
192
|
+
- seq: 该章节内图序号,从 01 开始
|
|
193
|
+
- description: 图表描述(英文小写+连字符,或保留中文)
|
|
194
|
+
|
|
195
|
+
示例:
|
|
196
|
+
ch01-01_data-processing-pipeline.drawio
|
|
197
|
+
ch04-02_labelstudio-sft-workflow.drawio
|
|
198
|
+
ch06-01_layer-wise-investigation.drawio
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
#### 教程章节(`tutorial/{模块}/`)
|
|
202
|
+
|
|
203
|
+
```
|
|
204
|
+
格式: {chapter:02d}-{章节标题}.md
|
|
205
|
+
规则:
|
|
206
|
+
- chapter: 章节序号,2位补零
|
|
207
|
+
- 标题: 可含中文
|
|
208
|
+
- 00 预留给学习路线图
|
|
209
|
+
- 最后一个序号预留给参考资源索引
|
|
210
|
+
|
|
211
|
+
示例:
|
|
212
|
+
00-学习路线图.md
|
|
213
|
+
模块一-数据处理与标注/
|
|
214
|
+
01-数据处理闭环与数据清洗.md
|
|
215
|
+
02-数据格式转换:从业务表到SFT.md
|
|
216
|
+
...
|
|
217
|
+
模块二-模型训练与评估/
|
|
218
|
+
06-训练环境与参数高效微调.md
|
|
219
|
+
...
|
|
220
|
+
15-参考资源.md
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## 5. 文件分类与生命周期
|
|
226
|
+
|
|
227
|
+
### 5.1 三类文件
|
|
228
|
+
|
|
229
|
+
| 类别 | 存放位置 | 生命周期 | 用户操作 |
|
|
230
|
+
|------|---------|---------|---------|
|
|
231
|
+
| **永久** | 工作区根目录 | 与工作区同寿,绝不删除 | 阅读、编辑 |
|
|
232
|
+
| **持久** | 工作区根目录 | AI 持续更新,不主动删除 | 不手动编辑 |
|
|
233
|
+
| **中间** | `_internal/` | 阶段完成后可归档,教程交付后可整体删除 | 不需要关心 |
|
|
234
|
+
|
|
235
|
+
### 5.2 逐文件分类
|
|
236
|
+
|
|
237
|
+
| 文件 | 类别 | 产生阶段 | 说明 |
|
|
238
|
+
|------|------|---------|------|
|
|
239
|
+
| `README.md` | 永久 | 阶段 0(初始创建) | 阶段 6 最终更新 |
|
|
240
|
+
| `MISSION.md` | 永久 | 阶段 0.5 | 用户可随时修改 |
|
|
241
|
+
| `session-state.md` | 持久 | 各阶段(AI 写入) | 流水线断点续传用,用户不编辑 |
|
|
242
|
+
| `understanding-map.md` | 永久 | 阶段 6 | 用户标记学习进度 |
|
|
243
|
+
| `_internal/01-collect/source-list.md` | 中间 | 阶段 1 | 归档后用户不需要 |
|
|
244
|
+
| `_internal/02-extract/kp-*.json` | 中间 | 阶段 2 | 阶段 4 质量验证时回溯用,交付后可删除 |
|
|
245
|
+
| `_internal/03-merge/*` | 中间 | 阶段 3 | 大纲构建过程记录 |
|
|
246
|
+
| `_internal/04-verify/*` | 中间 | 阶段 4.5 | 质量验证记录,交付后可删除 |
|
|
247
|
+
| `tutorial/*` | 最终 | 阶段 4-6 | 核心交付物 |
|
|
248
|
+
| `tutorial/reference/*` | 最终 | 阶段 4.2 | 独立参考文档 |
|
|
249
|
+
| `diagrams/*` | 最终 | 阶段 4 | 图表源文件 |
|
|
250
|
+
|
|
251
|
+
### 5.3 清理规则
|
|
252
|
+
|
|
253
|
+
阶段 6 完成后,面向用户给出清理建议:
|
|
254
|
+
|
|
255
|
+
```
|
|
256
|
+
教程已交付。
|
|
257
|
+
|
|
258
|
+
[可选] 工作区中的 `_internal/` 目录包含构建过程的中间文件
|
|
259
|
+
(知识提取报告、验证记录、大纲草稿等),这些文件在教程交付后
|
|
260
|
+
不再需要。如希望精简工作区,可以删除 `_internal/` 整个目录。
|
|
261
|
+
|
|
262
|
+
要保留的内容:
|
|
263
|
+
✅ README.md
|
|
264
|
+
✅ MISSION.md
|
|
265
|
+
✅ session-state.md
|
|
266
|
+
✅ understanding-map.md
|
|
267
|
+
✅ tutorial/(教程交付物)
|
|
268
|
+
✅ diagrams/(图表源文件)
|
|
269
|
+
|
|
270
|
+
可安全删除:
|
|
271
|
+
❌ _internal/(整个目录)
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
## 6. README.md 模板
|
|
277
|
+
|
|
278
|
+
每个新工作区在创建时必须生成 `README.md`。阶段 6 交付时更新。
|
|
279
|
+
|
|
280
|
+
```markdown
|
|
281
|
+
# {主题} — 学习教程工作区
|
|
282
|
+
|
|
283
|
+
> 由 learn-synthesizer 生成 | 创建日期: {YYYY-MM-DD} | 最后更新: {YYYY-MM-DD}
|
|
284
|
+
|
|
285
|
+
## 这是什么
|
|
286
|
+
|
|
287
|
+
本工作区包含 [{主题}] 的系统学习教程。
|
|
288
|
+
教程聚焦于 [{Mission.Why}],目标为 [{Mission.Success}]。
|
|
289
|
+
|
|
290
|
+
## 目录导航
|
|
291
|
+
|
|
292
|
+
| 想看什么 | 打开 |
|
|
293
|
+
|---------|------|
|
|
294
|
+
| 📖 开始学习 | [`tutorial/00-学习路线图.md`](tutorial/00-学习路线图.md) |
|
|
295
|
+
| 🎯 为什么学 | [`MISSION.md`](MISSION.md) |
|
|
296
|
+
| 📝 学习进度追踪 | [`understanding-map.md`](understanding-map.md) — 学完一部分回来打勾 |
|
|
297
|
+
| 📋 术语速查 | [`tutorial/reference/GLOSSARY.md`](tutorial/reference/GLOSSARY.md) |
|
|
298
|
+
| ⌨️ 命令速查 | [`tutorial/reference/COMMANDS.md`](tutorial/reference/COMMANDS.md) |
|
|
299
|
+
| 📐 配置模板 | [`tutorial/reference/TEMPLATES.md`](tutorial/reference/TEMPLATES.md) |
|
|
300
|
+
| 🐛 常见错误 | [`tutorial/reference/TROUBLESHOOTING.md`](tutorial/reference/TROUBLESHOOTING.md) |
|
|
301
|
+
| 🗂️ 图表源文件 | [`diagrams/`](diagrams/) |
|
|
302
|
+
|
|
303
|
+
## 目录结构说明
|
|
304
|
+
|
|
305
|
+
- `tutorial/` — 📖 教程交付物(核心内容,你应该从这里开始)
|
|
306
|
+
- `diagrams/` — 🗂️ 流程图/架构图源文件(.drawio 格式,可编辑)
|
|
307
|
+
- `_internal/` — 🔧 构建过程产物(不需要关心,可删除)
|
|
308
|
+
- `MISSION.md` — 🎯 学习目标和范围
|
|
309
|
+
- `understanding-map.md` — 📝 学习进度地图(学完一章回来标记)
|
|
310
|
+
|
|
311
|
+
## 渐进深化
|
|
312
|
+
|
|
313
|
+
这不仅是教程——它是一个持续陪伴的知识空间。学完后可以回来:
|
|
314
|
+
|
|
315
|
+
1. "我学完了第 X-Y 章" → AI 标记已掌握,推荐后续路径
|
|
316
|
+
2. "第 X 章太浅了,帮我深挖" → 补充搜索,重写该章
|
|
317
|
+
3. "[主题] 出新版本了" → 增量更新
|
|
318
|
+
4. "帮我生成配套练习" → 生成 quiz + coding exercise
|
|
319
|
+
5. "按我现在进度,推荐下一步" → 分析进度,推荐优先补缺
|
|
320
|
+
|
|
321
|
+
## 生成信息
|
|
322
|
+
|
|
323
|
+
- 学习模式: {快速参考 / 完整教程}
|
|
324
|
+
- 资料来源: {N} 份(一手 {A} / 二手 {B} / 三手 {C})
|
|
325
|
+
- 质量验证: 合格率 {X}%,教学质量均分 {X.X}/5.0
|
|
326
|
+
- learn-synthesizer 版本: v{version}
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
---
|
|
330
|
+
|
|
331
|
+
## 7. 各阶段集成改动
|
|
332
|
+
|
|
333
|
+
### 7.1 需要修改的 workflow 文件
|
|
334
|
+
|
|
335
|
+
| 文件 | 改动 |
|
|
336
|
+
|------|------|
|
|
337
|
+
| `stage1-collect.md` | 资料清单保存路径从根目录 `资料清单.md` → `_internal/01-collect/source-list.md` |
|
|
338
|
+
| `stage2-extract.md` | 知识报告保存路径从 `knowledge-reports/report-NN.json` → `_internal/02-extract/kp-NN-{shortname}.json`;新增短名称要求 |
|
|
339
|
+
| `stage3-merge.md` | 大纲产物保存路径从根目录 → `_internal/03-merge/` |
|
|
340
|
+
| `stage4-write.md` | 教程章节产出路径无变化(已在 `tutorial/` 下);确保图表命名使用 `ch{NN}-{seq}_{desc}.drawio` |
|
|
341
|
+
| `stage4-ref-extract.md` | 参考文档产出路径无变化(已在 `tutorial/reference/` 下) |
|
|
342
|
+
| `stage4.5-verify.md` | 验证报告保存路径从根目录 → `_internal/04-verify/`;文件名使用 `verify-{batch}-ch{start}-ch{end}.md` 格式 |
|
|
343
|
+
| `stage6-finalize.md` | 增加 README.md 更新步骤;增加清理建议;引用 `understanding-map.md`(已在根目录) |
|
|
344
|
+
| `SKILL.md` | session-state.md 格式模板中的路径更新;RACK 表增加新条目 |
|
|
345
|
+
|
|
346
|
+
### 7.2 向后兼容
|
|
347
|
+
|
|
348
|
+
- 现有工作区不强制迁移(参见 §8 迁移指南)
|
|
349
|
+
- `session-state.md` 中的旧路径作为历史记录保留
|
|
350
|
+
- 新工作区创建时直接采用本规范
|
|
351
|
+
|
|
352
|
+
---
|
|
353
|
+
|
|
354
|
+
## 8. 现有工作区迁移指南
|
|
355
|
+
|
|
356
|
+
对于已生成的工作区(如 `数据处理与模型训练教程`),执行以下迁移:
|
|
357
|
+
|
|
358
|
+
### 步骤1:创建 `_internal/` 目录结构
|
|
359
|
+
|
|
360
|
+
```bash
|
|
361
|
+
mkdir -p _internal/01-collect
|
|
362
|
+
mkdir -p _internal/02-extract
|
|
363
|
+
mkdir -p _internal/03-merge
|
|
364
|
+
mkdir -p _internal/04-verify
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
### 步骤2:移动文件
|
|
368
|
+
|
|
369
|
+
| 原路径 | 新路径 |
|
|
370
|
+
|--------|--------|
|
|
371
|
+
| `资料清单.md` | `_internal/01-collect/source-list.md` |
|
|
372
|
+
| `knowledge-reports/report-*.json` | `_internal/02-extract/kp-*.json`(重命名) |
|
|
373
|
+
| `domain-overview.md` | `_internal/03-merge/domain-overview.md` |
|
|
374
|
+
| `importance-ratings.json` | `_internal/03-merge/importance-ratings.json` |
|
|
375
|
+
| `outline.md` | `_internal/03-merge/outline.md` |
|
|
376
|
+
| `outline-stats.json` | `_internal/03-merge/outline-stats.json` |
|
|
377
|
+
| `quality-report.md` | `_internal/04-verify/quality-report.md` |
|
|
378
|
+
| `verify-ch*.md` | `_internal/04-verify/`(保持原名,或按规范重命名) |
|
|
379
|
+
|
|
380
|
+
### 步骤3:创建 README.md
|
|
381
|
+
|
|
382
|
+
按 §6 模板生成,填入实际数据。
|
|
383
|
+
|
|
384
|
+
### 步骤4:更新 session-state.md
|
|
385
|
+
|
|
386
|
+
将阶段输出中的文件路径更新为新路径。
|
|
387
|
+
|
|
388
|
+
---
|
|
389
|
+
|
|
390
|
+
## 附录 A:当前工作区问题对照
|
|
391
|
+
|
|
392
|
+
以 `数据处理与模型训练教程` 为例:
|
|
393
|
+
|
|
394
|
+
| # | 问题 | 具体表现 | 本规范解决 |
|
|
395
|
+
|---|------|---------|-----------|
|
|
396
|
+
| 1 | 知识报告从 02 开始 | `report-02.json`(01 丢失) | 要求从 01 开始连续编号 |
|
|
397
|
+
| 2 | 验证报告范围不规则 | `verify-ch10-11-14.md`(跳过了 12-13,但10-11,14 分在同一批次) | 格式化为 `verify-NN-chXX-chYY.md`(连续范围) |
|
|
398
|
+
| 3 | 中间文件散落根目录 | 10+ 个文件(verify×5 + quality-report + outline + ...) | 收入 `_internal/` 子目录 |
|
|
399
|
+
| 4 | 没有 README.md | 用户不知道从哪里开始 | 阶段 0 创建模板,阶段 6 最终填充 |
|
|
400
|
+
| 5 | 中英文命名混用 | `资料清单.md` vs `domain-overview.md` | 内部用英文,用户面向用中文 |
|
|
401
|
+
| 6 | diagrams 命名含中文 | `01-01_数据处理五阶段闭环.drawio` | 允许中文(draw.io 本身支持),但序号格式已规范 |
|
|
402
|
+
| 7 | session-state 引用旧路径 | 指向根目录的 verify 文件 | 更新为新路径 |
|