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,173 @@
|
|
|
1
|
+
# 核心原则(硬规则)
|
|
2
|
+
|
|
3
|
+
这些规则在整个流程中始终有效,任何阶段违反时必须立即停止。
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. 主进程不直接读原文
|
|
8
|
+
|
|
9
|
+
**规则**:主进程不直接阅读原始资料全文(URL、PDF、长篇 Markdown),始终通过 Sub-agent 获取压缩的结构化**知识报告**。
|
|
10
|
+
|
|
11
|
+
**原因**:每份资料读取时产生大量上下文。主进程逐一阅读会导致上下文膨胀,后期质量下降。
|
|
12
|
+
|
|
13
|
+
**执行方式**:
|
|
14
|
+
- 主进程只负责**调度和合并**
|
|
15
|
+
- 每份资料由独立 Sub-agent 深度阅读
|
|
16
|
+
- Sub-agent 返回 JSON 格式的知识报告(参见 `references/sub-agent-prompt.md`)
|
|
17
|
+
- 主进程上下文始终保持精简
|
|
18
|
+
|
|
19
|
+
**例外情况**:
|
|
20
|
+
- 用户提供的资料 <500 字 → 可直接读取
|
|
21
|
+
- 快速参考模式且资料总数 ≤3 份 → 可串行读取
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 2. Sub-agent 必须并行启动
|
|
26
|
+
|
|
27
|
+
**规则**:阶段2派发 Sub-agent 时,在**同一轮**中为所有资料各启动一个 Sub-agent,全部并行,不等待任何一个完成再启动下一个。
|
|
28
|
+
|
|
29
|
+
**降级说明**:若环境不支持 Sub-agent(如工具调用受限),改为串行处理:
|
|
30
|
+
- 逐份资料读取并提取知识报告
|
|
31
|
+
- 在本地工作区记录 JSON 报告
|
|
32
|
+
- 每份处理完立即输出报告再处理下一份
|
|
33
|
+
- 避免一次性读入所有资料
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## 3. 矛盾必须保留
|
|
38
|
+
|
|
39
|
+
**规则**:绝不静默解决矛盾。遇到资料之间的冲突观点时:
|
|
40
|
+
- 保留双方观点和各自的 `evidence`
|
|
41
|
+
- 在大纲中标注 `[VERSION_CONFLICT]`,记录来源
|
|
42
|
+
- 不同 `tech_era`(技术年代)的方案强制隔离,不合并
|
|
43
|
+
|
|
44
|
+
**错误示例**:
|
|
45
|
+
- [错误] "文档A说方案X,但文档B更新,所以采用文档B的方案Y"
|
|
46
|
+
- [错误] "这两份资料矛盾,我选择来自官方文档的说法"
|
|
47
|
+
|
|
48
|
+
**正确示例**:
|
|
49
|
+
- [正确] 在大纲中标注:
|
|
50
|
+
```
|
|
51
|
+
特性C:一句话描述
|
|
52
|
+
[VERSION_CONFLICT]
|
|
53
|
+
- 旧方案(jQuery 时代):xxx | 来源:文档A | 依据:xxx
|
|
54
|
+
- 新方案(React 18+):xxx | 来源:文档B | 依据:xxx
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## 4. 分级三问是分类工具,不是过滤器
|
|
60
|
+
|
|
61
|
+
**规则**:阶段3的"分级三问"目的是**给每个知识点找到正确的位置**,不是过滤掉它。
|
|
62
|
+
|
|
63
|
+
**三个问题**:
|
|
64
|
+
1. 这个知识点属于哪个学习等级?(初学/熟练/精通)
|
|
65
|
+
2. 是否与已有条目完全重复?(相同内容、相同角度)
|
|
66
|
+
3. 来源是否可靠?
|
|
67
|
+
|
|
68
|
+
**处理原则**:
|
|
69
|
+
- 所有知识点都应进入大纲(即使是"待验证"状态)
|
|
70
|
+
- **唯一真正剔除的**:与已有条目内容和角度**完全相同**的副本
|
|
71
|
+
- 初学阶段内容**宁多勿少** — 学习教程需要系统完整性
|
|
72
|
+
|
|
73
|
+
**错误示例**:
|
|
74
|
+
- [错误] "这个知识点太简单,不放进大纲"
|
|
75
|
+
- [错误] "只有一份来源,可靠性不足,剔除"
|
|
76
|
+
|
|
77
|
+
**正确示例**:
|
|
78
|
+
- [正确] "这个知识点只有一份来源,标注【待验证】纳入大纲,提示用户后续查阅官方文档确认"
|
|
79
|
+
- [正确] "来自不同技术年代的同名概念,按 `tech_era` 隔离分组,不合并"
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## 5. 定义优先,类比辅助
|
|
84
|
+
|
|
85
|
+
**规则**:每个专业概念必须先给出准确的技术定义(范畴、关键属性、边界条件),再视抽象程度决定是否补充类比。类比之后必须回到精确表述。
|
|
86
|
+
|
|
87
|
+
**原因**:
|
|
88
|
+
- 类比帮助建立直觉,但无法传递边界条件和精确语义
|
|
89
|
+
- 只有类比没有定义,学习者掌握的是"感觉"而非可迁移的专业认知
|
|
90
|
+
- 教程的长期价值在于专业准确,而非通俗印象
|
|
91
|
+
|
|
92
|
+
**执行方式**:
|
|
93
|
+
- 章节撰写:先写"定义"块(必选),再写"通俗类比"(可选),类比后加一句回归精确表述
|
|
94
|
+
- 质量验证:缺定义或定义模糊视为事实准确性缺陷,而非可接受的"通俗化"
|
|
95
|
+
|
|
96
|
+
**错误示例**:
|
|
97
|
+
- [错误] "就像餐厅服务员……" — 只有类比,没有技术定义
|
|
98
|
+
- [错误] "某种程度上可以理解为……" — 模糊化边界,用比喻替代定义
|
|
99
|
+
|
|
100
|
+
**正确示例**:
|
|
101
|
+
- [正确] "事件循环(event loop)是 JavaScript 运行时的调度机制,负责从消息队列中取出任务并依次执行,确保单线程非阻塞。通俗来说,就像……对应到技术上,关键是:每次只执行一个任务,执行完才取下一个。"
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## 6. 最终通读是用户的工作
|
|
106
|
+
|
|
107
|
+
**规则**:AI 不做最后的自我审阅。草稿完成后,通读和最终质量判断由用户完成。
|
|
108
|
+
|
|
109
|
+
**原因**:
|
|
110
|
+
- AI 对自己写的内容有认知偏差
|
|
111
|
+
- 用户才是学习者,他们的理解障碍才是真实信号
|
|
112
|
+
|
|
113
|
+
**执行方式**:
|
|
114
|
+
- 阶段5/5.5:等待用户反馈,根据反馈精准修改
|
|
115
|
+
- 阶段6:展示目录概览,说明"终极教程已完成,请您通读验收"
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## 7. 阶段出口门控
|
|
120
|
+
|
|
121
|
+
**规则**:进入下一阶段前,必须确认本阶段的出口门控条件全部通过。任一条件未通过时,不得进入下一阶段,必须先补充完成未通过项。
|
|
122
|
+
|
|
123
|
+
**出口门控条件**(定义在各 workflow 文件末尾)至少应覆盖:
|
|
124
|
+
- 本阶段核心产物已生成并保存
|
|
125
|
+
- 本阶段关键决策已获用户确认(如需用户确认)
|
|
126
|
+
- 无未解决的卡顿信号或质量警告
|
|
127
|
+
- session-state.md 已更新
|
|
128
|
+
|
|
129
|
+
**执行方式**:
|
|
130
|
+
- 每个阶段完成时,对照该阶段 workflow 文件末尾的出口门控逐项检查
|
|
131
|
+
- 全部通过 → 写入 session-state.md → 进入下一阶段
|
|
132
|
+
- 有未通过 → 补充缺失项 → 重新检查 → 严禁"先进入下一阶段再补"
|
|
133
|
+
|
|
134
|
+
**错误示例**:
|
|
135
|
+
- [错误] "大纲差不多了,先进入阶段4写着,边写边补"
|
|
136
|
+
- [错误] "session-state 等后面一起补"
|
|
137
|
+
- [错误] "质量报告还没生成,但不影响撰写,先跳过"
|
|
138
|
+
|
|
139
|
+
**正确示例**:
|
|
140
|
+
- [正确] "阶段3出口门控:知识点分级三问通过、版本冲突已标注、大纲已保存、风险扫描已完成、session-state 已更新——全部通过,进入阶段4"
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## 8. 名实一致:内容变了,框架表述必须同步
|
|
145
|
+
|
|
146
|
+
**规则**:修改任何文件时,若改动改变了文件的实际内容范围或角色,必须同步修正该文件的标题、头部定位声明,以及所有指向它的索引与引用。
|
|
147
|
+
|
|
148
|
+
**原因**:局部修补只改内容不改框架,会导致文档名义与实质脱节(例如内容已扩成全领域年表,标题却仍写着单一领域)。读者和接手的 agent 都靠标题和定位声明理解文件角色。
|
|
149
|
+
|
|
150
|
+
**执行方式**:
|
|
151
|
+
- 动手改文件前,先读其标题与头部定位声明,确认"这个文件在全局中扮演什么角色"
|
|
152
|
+
- 修改后对照检查:标题、定位声明、索引条目是否仍与实际内容一致
|
|
153
|
+
- 不一致时,按文件的全局角色整体重规划,而不是只在局部打补丁
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## 9. 存量事实必须核验
|
|
158
|
+
|
|
159
|
+
**规则**:事实性内容(日期、数字、版本号、人名归属、URL)一律对照一手来源核实,不因"已存在于工作区或既有文档中"而默认正确。
|
|
160
|
+
|
|
161
|
+
**执行方式**:
|
|
162
|
+
- 审计、盘点、引用存量内容时,对其中的事实性陈述抽查一手来源
|
|
163
|
+
- 发现错误时修正并留痕(注明修正日期与依据)
|
|
164
|
+
- 无法核实的标注「待核实」,不静默保留也不静默删除
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## 违反处理
|
|
169
|
+
|
|
170
|
+
如果发现自己违反了上述任一规则(包括第5条"定义优先,类比辅助"):
|
|
171
|
+
1. 立即停止当前操作
|
|
172
|
+
2. 向用户报告:"我违反了核心原则第X条([规则名]),需要回退到阶段Y重新执行"
|
|
173
|
+
3. 等待用户确认后再继续
|
|
@@ -0,0 +1,355 @@
|
|
|
1
|
+
# 输出格式规范
|
|
2
|
+
|
|
3
|
+
所有生成的教程内容必须遵循以下格式标准。
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. 语言规范
|
|
8
|
+
|
|
9
|
+
### 主体语言
|
|
10
|
+
- **教程正文**:简体中文
|
|
11
|
+
- **代码注释**:中文
|
|
12
|
+
|
|
13
|
+
### 专业术语处理
|
|
14
|
+
- **保留英文原文**:API 名称、框架名、技术术语
|
|
15
|
+
- **中文注解跟随**:首次出现时用括号补充中文解释
|
|
16
|
+
|
|
17
|
+
**示例**:
|
|
18
|
+
```markdown
|
|
19
|
+
[正确] 正确:`useState`(状态钩子)、`event loop`(事件循环)
|
|
20
|
+
[错误] 错误:将 `useState` 翻译为"使用状态"并替换
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 2. 版本冲突输出格式
|
|
26
|
+
|
|
27
|
+
### 方案对比型(多个方案共存)
|
|
28
|
+
|
|
29
|
+
```markdown
|
|
30
|
+
> [版本差异] **版本差异**:该功能有多种历史实现方案。
|
|
31
|
+
>
|
|
32
|
+
> | 方案 | 适用版本 | 状态 |
|
|
33
|
+
> |------|---------|------|
|
|
34
|
+
> | 旧方案描述 | v1.x | [不推荐] 仍可用,但不推荐 |
|
|
35
|
+
> | 新方案描述 | v2.x+ | [推荐] 推荐使用 |
|
|
36
|
+
>
|
|
37
|
+
> **Why:** [为什么有这个差异,技术演进背景]
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### 彻底废弃型(旧方案已移除)
|
|
41
|
+
|
|
42
|
+
```markdown
|
|
43
|
+
> [已过时] **已过时**:`旧API名` 在 vX.X 中已彻底移除,使用将报错。
|
|
44
|
+
>
|
|
45
|
+
> **迁移方案**:请使用 `新API名`
|
|
46
|
+
>
|
|
47
|
+
> **迁移示例**:
|
|
48
|
+
> ```javascript
|
|
49
|
+
> // 旧代码(v1.x)
|
|
50
|
+
> oldAPI()
|
|
51
|
+
>
|
|
52
|
+
> // 新代码(v2.x+)
|
|
53
|
+
> newAPI()
|
|
54
|
+
> ```
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## 3. 章节模板
|
|
60
|
+
|
|
61
|
+
### 标准章节结构
|
|
62
|
+
|
|
63
|
+
```markdown
|
|
64
|
+
## 章节标题 `[初学]`
|
|
65
|
+
|
|
66
|
+
> [初学] 本章等级:初学
|
|
67
|
+
>
|
|
68
|
+
> **[目标] 学完本章你应该能**:[具体可验证的 2-3 条能力]
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
### 导言
|
|
73
|
+
|
|
74
|
+
**是什么**:[本章主题的领域定位与核心价值,1-2句]
|
|
75
|
+
**怎么来的**:[起源与关键演进节点,基于资料]
|
|
76
|
+
**发展现状与前景**:[当前成熟度与趋势,基于资料]
|
|
77
|
+
**典型应用**:[2-3个真实使用场景]
|
|
78
|
+
|
|
79
|
+
> 如上述信息来源资料中未提及,可省略对应项。
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
### [知识点标题]
|
|
84
|
+
|
|
85
|
+
**定义**:[准确的专业定义——范畴、关键属性、边界条件。该用术语就用,不为通俗牺牲精确。]
|
|
86
|
+
|
|
87
|
+
> [类比] **通俗类比(概念抽象时可选)**:[日常场景打比方]。对应到技术上:[回到精确表述]
|
|
88
|
+
|
|
89
|
+
**为什么需要它?**
|
|
90
|
+
|
|
91
|
+
[解决什么实际问题,不掌握会遇到什么麻烦]
|
|
92
|
+
|
|
93
|
+
### 示例
|
|
94
|
+
|
|
95
|
+
\```语言
|
|
96
|
+
// 示例代码
|
|
97
|
+
\```
|
|
98
|
+
|
|
99
|
+
> [完整示例] **完整示例**:[tutorial-examples/01-hello-world/](../tutorial-examples/01-hello-world/) — 可直接运行验证
|
|
100
|
+
|
|
101
|
+
### 注意事项
|
|
102
|
+
|
|
103
|
+
- 常见误区或坑
|
|
104
|
+
- 版本差异(如有)
|
|
105
|
+
|
|
106
|
+
### 前置知识(可选)
|
|
107
|
+
|
|
108
|
+
> [前置] **需要先了解**:[第1章 基础概念](./01-基础概念.md#核心术语) — 如果还不熟悉,建议先阅读。
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### 等级标记
|
|
112
|
+
|
|
113
|
+
| 等级 | 标记 | 判断标准 |
|
|
114
|
+
|------|------|---------|
|
|
115
|
+
| 初学 | [初学] | 入门必须理解,是其他概念的前提 |
|
|
116
|
+
| 熟练 | [熟练] | 日常开发频繁使用,不掌握无法完成实际项目 |
|
|
117
|
+
| 精通 | [精通] | 底层原理、性能调优、高级设计模式 |
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## 4. 示例代码规范
|
|
122
|
+
|
|
123
|
+
### 内联代码块(简短演示)
|
|
124
|
+
|
|
125
|
+
**适用场景**:
|
|
126
|
+
- 单文件
|
|
127
|
+
- 少于 30 行
|
|
128
|
+
- 无需依赖安装即可理解
|
|
129
|
+
|
|
130
|
+
**格式**:
|
|
131
|
+
```markdown
|
|
132
|
+
### 示例:基本用法
|
|
133
|
+
|
|
134
|
+
\```javascript
|
|
135
|
+
// 示例代码
|
|
136
|
+
const example = 'hello';
|
|
137
|
+
\```
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### 独立示例文件(完整可运行)
|
|
141
|
+
|
|
142
|
+
**适用场景**:参见决策表(`references/example-structures.md`)
|
|
143
|
+
|
|
144
|
+
**目录结构**:
|
|
145
|
+
```
|
|
146
|
+
tutorial-examples/
|
|
147
|
+
├── 01-hello-world/
|
|
148
|
+
│ ├── README.md ← 必选:运行方式、预期输出
|
|
149
|
+
│ ├── index.js
|
|
150
|
+
│ └── package.json
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
**README.md 模板**:
|
|
154
|
+
```markdown
|
|
155
|
+
# [知识点名称] 示例
|
|
156
|
+
|
|
157
|
+
## 运行方式
|
|
158
|
+
\```bash
|
|
159
|
+
pnpm install
|
|
160
|
+
node index.js
|
|
161
|
+
\```
|
|
162
|
+
|
|
163
|
+
## 预期输出
|
|
164
|
+
\```
|
|
165
|
+
Hello, World!
|
|
166
|
+
\```
|
|
167
|
+
|
|
168
|
+
## 知识点说明
|
|
169
|
+
- 这个示例演示了什么概念
|
|
170
|
+
- 关键行或关键函数的作用
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
**教程中的引用方式**:
|
|
174
|
+
```markdown
|
|
175
|
+
> [完整示例] **完整示例**:[tutorial-examples/01-hello-world/](../tutorial-examples/01-hello-world/) — 可直接运行验证
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### 示例代码来源标注
|
|
179
|
+
|
|
180
|
+
| 来源 | 是否标注 | 标注方式 |
|
|
181
|
+
|------|---------|---------|
|
|
182
|
+
| 从原始资料提取/改编 | 否 | 无需标注 |
|
|
183
|
+
| AI 补充(内联代码) | 是 | `<!-- 示例由 AI 补充 -->` |
|
|
184
|
+
| AI 补充(独立文件) | 否 | 独立文件无需标注 |
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## 5. 教程整体结构
|
|
189
|
+
|
|
190
|
+
### 快速参考模式(单文件)
|
|
191
|
+
|
|
192
|
+
```
|
|
193
|
+
[主题]-notes.md
|
|
194
|
+
├── 学习模式说明
|
|
195
|
+
├── 核心概念大纲
|
|
196
|
+
├── 关键知识点(按等级分组)
|
|
197
|
+
└── 参考资源
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### 完整教程模式(多文件)
|
|
201
|
+
|
|
202
|
+
```
|
|
203
|
+
[主题]-tutorial/
|
|
204
|
+
├── 00-学习路线图.md
|
|
205
|
+
├── 01-基础入门.md [初学]
|
|
206
|
+
├── 02-核心概念.md [初学 → 熟练]
|
|
207
|
+
├── 03-进阶特性.md [熟练]
|
|
208
|
+
├── 04-高级与原理.md [精通]
|
|
209
|
+
├── 05-参考资源.md
|
|
210
|
+
└── tutorial-examples/ ← 需要完整文件结构的示例
|
|
211
|
+
├── 01-hello-world/
|
|
212
|
+
├── 02-state-hook/
|
|
213
|
+
└── ...
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
**文件命名规则**:
|
|
217
|
+
- 章节文件:`序号-章节名.md`(如 `01-基础入门.md`)
|
|
218
|
+
- 示例目录:`序号-知识点英文短名/`(如 `01-hello-world/`)
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## 6. 学习路线图格式
|
|
223
|
+
|
|
224
|
+
```markdown
|
|
225
|
+
# [主题] 学习路线图
|
|
226
|
+
|
|
227
|
+
## 建议学习顺序
|
|
228
|
+
|
|
229
|
+
> 适合零基础学习者从头开始。已有基础可从第 N 章起。
|
|
230
|
+
|
|
231
|
+
### 阶段一:初学(建议用时:X 小时)
|
|
232
|
+
```
|
|
233
|
+
第1章 基础概念 ← 从这里开始
|
|
234
|
+
第2章 环境搭建
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
### 阶段二:熟练(建议用时:X 小时)
|
|
238
|
+
```
|
|
239
|
+
第3章 核心 API
|
|
240
|
+
第4章 实战项目
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
### 阶段三:精通(建议用时:自学探索)
|
|
244
|
+
```
|
|
245
|
+
第5章 底层原理
|
|
246
|
+
第6章 性能优化
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
## 各章节关键检查点
|
|
250
|
+
|
|
251
|
+
| 章节 | 学完后应该能做什么 |
|
|
252
|
+
|------|-----------------|
|
|
253
|
+
| 第1章 | 理解基本概念,能解释术语 |
|
|
254
|
+
| 第2章 | 搭建开发环境,运行第一个示例 |
|
|
255
|
+
| ... | ... |
|
|
256
|
+
|
|
257
|
+
## 学习建议
|
|
258
|
+
|
|
259
|
+
- **必学章节**:第1-3章(覆盖日常使用场景)
|
|
260
|
+
- **选学章节**:第4-5章(深入理解原理)
|
|
261
|
+
- **实战建议**:每章至少运行一个 tutorial-examples/ 中的示例
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
---
|
|
265
|
+
|
|
266
|
+
## 7. 参考资源章节格式
|
|
267
|
+
|
|
268
|
+
```markdown
|
|
269
|
+
# 参考资源
|
|
270
|
+
|
|
271
|
+
## 一手资料(官方权威)
|
|
272
|
+
|
|
273
|
+
| 资源 | 类型 | 备注 |
|
|
274
|
+
|------|------|------|
|
|
275
|
+
| [官方文档](URL) | 官方文档 | 最权威,优先查阅 |
|
|
276
|
+
| [RFC 标准](URL) | 技术规范 | 标准定义 |
|
|
277
|
+
|
|
278
|
+
## 二手资料(社区推荐)
|
|
279
|
+
|
|
280
|
+
| 资源 | 类型 | 备注 |
|
|
281
|
+
|------|------|------|
|
|
282
|
+
| [知名博客](URL) | 技术博客 | 实战经验 |
|
|
283
|
+
|
|
284
|
+
## 三手资料(仅供参考)
|
|
285
|
+
|
|
286
|
+
| 资源 | 类型 | 备注 |
|
|
287
|
+
|------|------|------|
|
|
288
|
+
| [转载文章](URL) | 转载 | 需交叉验证 |
|
|
289
|
+
|
|
290
|
+
## 资料来源说明
|
|
291
|
+
|
|
292
|
+
本教程整合自以上资料,并经过以下处理:
|
|
293
|
+
- 去重合并:相同内容保留最权威来源
|
|
294
|
+
- 冲突标注:不同观点均保留并注明版本差异
|
|
295
|
+
- 补充标注:阶段5.5用户反馈后补充的内容已标注
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
## 8. 补充内容标注规范
|
|
301
|
+
|
|
302
|
+
### 标注类型
|
|
303
|
+
|
|
304
|
+
| 补充类型 | 标注方式 |
|
|
305
|
+
|---------|---------|
|
|
306
|
+
| AI 补充的通俗解释 | `<!-- 补充:通俗解释 -->` |
|
|
307
|
+
| 阶段4撰写期绘图请求(待主进程绘制) | `<!-- DIAGRAM-REQUEST id=XX-XX type=flowchart desc="..." -->` |
|
|
308
|
+
| 主进程绘制完成的流程图 | 图表说明中注明"辅助理解示意图" |
|
|
309
|
+
| 绘制失败、需用户补图 | `> [需人工绘图] **此处建议配图**:[desc]。请绘制后放入 \`diagrams/\` 并替换本行。` |
|
|
310
|
+
| 阶段5.5补充搜索的新资料 | 在"05-参考资源.md"中注明"补充于阶段5.5" |
|
|
311
|
+
|
|
312
|
+
### 标注示例
|
|
313
|
+
|
|
314
|
+
```markdown
|
|
315
|
+
### 核心概念:事件循环(event loop)
|
|
316
|
+
|
|
317
|
+
**定义**:事件循环是 JavaScript 运行时的调度机制。它持续监视调用栈(call stack)和消息队列(message queue):当调用栈为空时,将队列中的第一个消息取出并执行对应的回调函数。这个机制使单线程的 JavaScript 能够以非阻塞方式处理 I/O 操作。
|
|
318
|
+
|
|
319
|
+
<!-- 补充:通俗解释 -->
|
|
320
|
+
> [类比] **通俗类比(概念抽象时可选)**:就像餐厅服务员——先记下所有点餐(任务入队),等厨房有空(调用栈清空)再逐一上菜(执行回调)。对应到技术上:关键是**调用栈必须清空**,事件循环才会取下一个任务;同步代码阻塞调用栈,异步回调等到下一次循环。
|
|
321
|
+
|
|
322
|
+
> [流程图] **流程图**:[查看事件循环工作流程](../diagrams/02_event-loop_workflow.drawio) — 辅助理解示意图
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
---
|
|
326
|
+
|
|
327
|
+
## 格式自检清单
|
|
328
|
+
|
|
329
|
+
生成教程后,自检:
|
|
330
|
+
- [ ] 所有专业术语首次出现时有中文注解
|
|
331
|
+
- [ ] 每个知识点有准确的"定义"块(范畴、关键属性、边界条件),不以类比替代
|
|
332
|
+
- [ ] 如有类比,类比之后有回到精确表述的一句话
|
|
333
|
+
- [ ] 每个章节开头有"导言"(是什么/怎么来的/现状/应用,素材来自资料)
|
|
334
|
+
- [ ] 版本冲突使用表格格式,有"Why"说明
|
|
335
|
+
- [ ] 章节有等级标记([初学]/[熟练]/[精通])
|
|
336
|
+
- [ ] 示例代码要么是内联短代码,要么有独立可运行文件
|
|
337
|
+
- [ ] 学习路线图有建议用时和检查点
|
|
338
|
+
- [ ] 参考资源按一手/二手/三手分类
|
|
339
|
+
- [ ] 补充内容有明确标注
|
|
340
|
+
- [ ] 绘图请求已处理:成功→正式引用链接,失败→人工占位标记
|
|
341
|
+
|
|
342
|
+
---
|
|
343
|
+
|
|
344
|
+
## 8. 列表优先于表格
|
|
345
|
+
|
|
346
|
+
优先使用列表;仅在多维度对比确有必要时使用表格。
|
|
347
|
+
|
|
348
|
+
| 场景 | 推荐格式 |
|
|
349
|
+
|------|---------|
|
|
350
|
+
| 单一维度的信息枚举(如"X 包含以下组件:A、B、C") | 无序列表 |
|
|
351
|
+
| 有先后顺序的流程或步骤 | 有序列表 |
|
|
352
|
+
| 多维度横向对比(≥ 3 个对比维度) | 表格 |
|
|
353
|
+
| 多个选项的场景/成本/适用性对比 | 表格 |
|
|
354
|
+
|
|
355
|
+
**判断标准**:如果列表形式也能清晰表达,就不要用表格。表格列数控制在 4 列以内。超过 4 列应拆分为多个小表或改用分组列表。
|