dsh-learning-assistant 0.0.1 → 0.1.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 (69) hide show
  1. package/README.md +41 -7
  2. package/assets/collect/README.md +55 -0
  3. package/assets/skills/course-inbox-sync.md +182 -0
  4. package/assets/skills/course-material-digest.md +173 -0
  5. package/assets/skills/one-to-one-tutor.md +320 -0
  6. package/assets/tools/pdf/pdf-render.ps1 +30 -0
  7. package/assets/tools/pptx-digest.py +99 -0
  8. package/assets/tools/pptx-map.py +98 -0
  9. package/assets/tools/pptx-media.py +101 -0
  10. package/assets/tools/qq-group-msg.py +258 -0
  11. package/assets/tools/qq-group-sync.py +265 -0
  12. package/docs//345/215/217/344/275/234/345/274/200/345/217/221.md +18 -10
  13. package/lib/client.js +110 -0
  14. package/lib/{index.d.mts → index.d.ts} +3 -1
  15. package/lib/index.js +392 -0
  16. package/package.json +8 -7
  17. package/src/client/settings.tsx +6 -4
  18. package/src/index.ts +36 -11
  19. package/src/practice/learn/api.mjs +393 -0
  20. package/src/practice/learn/cli.mjs +175 -0
  21. package/src/practice/learn/curriculum.mjs +292 -0
  22. package/src/practice/learn/handoff.mjs +73 -0
  23. package/src/practice/learn/jsonschema.mjs +171 -0
  24. package/src/practice/learn/mapping.mjs +90 -0
  25. package/src/practice/learn/progress.mjs +247 -0
  26. package/src/practice/learn/schema/curriculum.schema.json +88 -0
  27. package/src/practice/learn/schema/handoff.schema.json +56 -0
  28. package/src/practice/learn/schema/node-practice-map.schema.json +28 -0
  29. package/src/practice/learn/schema/progress.schema.json +66 -0
  30. package/src/practice/learn/schemas.mjs +53 -0
  31. package/src/practice/learn/store.mjs +247 -0
  32. package/src/practice/public/app.js +883 -0
  33. package/src/practice/public/index.html +19 -0
  34. package/src/practice/public/ink.js +349 -0
  35. package/src/practice/public/learn.css +20 -0
  36. package/src/practice/public/learn.js +329 -0
  37. package/src/practice/public/style.css +326 -0
  38. package/src/practice/public/vendor/katex/contrib/auto-render.min.js +1 -0
  39. package/src/practice/public/vendor/katex/fonts/KaTeX_AMS-Regular.woff2 +0 -0
  40. package/src/practice/public/vendor/katex/fonts/KaTeX_Caligraphic-Bold.woff2 +0 -0
  41. package/src/practice/public/vendor/katex/fonts/KaTeX_Caligraphic-Regular.woff2 +0 -0
  42. package/src/practice/public/vendor/katex/fonts/KaTeX_Fraktur-Bold.woff2 +0 -0
  43. package/src/practice/public/vendor/katex/fonts/KaTeX_Fraktur-Regular.woff2 +0 -0
  44. package/src/practice/public/vendor/katex/fonts/KaTeX_Main-Bold.woff2 +0 -0
  45. package/src/practice/public/vendor/katex/fonts/KaTeX_Main-BoldItalic.woff2 +0 -0
  46. package/src/practice/public/vendor/katex/fonts/KaTeX_Main-Italic.woff2 +0 -0
  47. package/src/practice/public/vendor/katex/fonts/KaTeX_Main-Regular.woff2 +0 -0
  48. package/src/practice/public/vendor/katex/fonts/KaTeX_Math-BoldItalic.woff2 +0 -0
  49. package/src/practice/public/vendor/katex/fonts/KaTeX_Math-Italic.woff2 +0 -0
  50. package/src/practice/public/vendor/katex/fonts/KaTeX_SansSerif-Bold.woff2 +0 -0
  51. package/src/practice/public/vendor/katex/fonts/KaTeX_SansSerif-Italic.woff2 +0 -0
  52. package/src/practice/public/vendor/katex/fonts/KaTeX_SansSerif-Regular.woff2 +0 -0
  53. package/src/practice/public/vendor/katex/fonts/KaTeX_Script-Regular.woff2 +0 -0
  54. package/src/practice/public/vendor/katex/fonts/KaTeX_Size1-Regular.woff2 +0 -0
  55. package/src/practice/public/vendor/katex/fonts/KaTeX_Size2-Regular.woff2 +0 -0
  56. package/src/practice/public/vendor/katex/fonts/KaTeX_Size3-Regular.woff2 +0 -0
  57. package/src/practice/public/vendor/katex/fonts/KaTeX_Size4-Regular.woff2 +0 -0
  58. package/src/practice/public/vendor/katex/fonts/KaTeX_Typewriter-Regular.woff2 +0 -0
  59. package/src/practice/public/vendor/katex/katex.min.css +1 -0
  60. package/src/practice/public/vendor/katex/katex.min.js +1 -0
  61. package/src/practice//346/234/215/345/212/241.mjs +443 -0
  62. package/src/practice//346/240/241/351/252/214/351/242/230/347/233/256.mjs +114 -0
  63. package/src/practice//347/255/211/345/276/205/346/217/220/344/272/244.mjs +100 -0
  64. package/src/practice-service.ts +99 -0
  65. package/src/practice-tool.ts +91 -0
  66. package/src/skills.ts +156 -0
  67. package/lib/client.d.mts +0 -10
  68. package/lib/client.mjs +0 -87
  69. package/lib/index.mjs +0 -29
@@ -0,0 +1,247 @@
1
+ // 学习进度(progress):**掌握状态的唯一权威来源**。
2
+ //
3
+ // 硬规则(方案 §2.3、§3):
4
+ // - mastered 只能由导师批改流程显式判定后写入,且必须带可追溯证据(答卷/批改记录)
5
+ // - 网页分数不构成掌握判定:recordScore() 只更新 last_score/attempts,绝不写 mastered
6
+ // - 先修未完成时不允许标记 mastered(除非显式 override_prereq,并留痕)
7
+ // - 任何状态变化写进 history,成绩与历史记录不被抹除
8
+ import path from 'node:path';
9
+ import { checkOrThrow } from './schemas.mjs';
10
+ import {
11
+ subjectFile, readJson, writeJsonVersioned, ensureDataRoot, assertSafeId, assertNodeId, nowIso,
12
+ WORKSPACE, exists,
13
+ } from './store.mjs';
14
+
15
+ export const PROGRESS_FILE = 'progress.json';
16
+ export const STATUSES = ['not_started', 'in_progress', 'mastered', 'needs_review'];
17
+
18
+ export async function loadProgress(subjectId) {
19
+ return readJson(subjectFile(assertSafeId(subjectId, 'subject_id'), PROGRESS_FILE), null);
20
+ }
21
+
22
+ function blankNode() {
23
+ return {
24
+ status: 'not_started',
25
+ attempts: 0,
26
+ last_score: null,
27
+ last_studied_at: null,
28
+ attempt_refs: [],
29
+ misconception_refs: [],
30
+ mastered_at: null,
31
+ judged_by: null,
32
+ override_prereq: null,
33
+ };
34
+ }
35
+
36
+ // 按 curriculum 初始化进度:已存在的节点状态**原样保留**(重规划不清空成绩)
37
+ export async function initProgressFor(subjectId, cur) {
38
+ const id = assertSafeId(subjectId, 'subject_id');
39
+ const prev = await loadProgress(id);
40
+ const nodes = {};
41
+ for (const n of cur.nodes) {
42
+ nodes[n.id] = (prev && prev.nodes && prev.nodes[n.id]) ? prev.nodes[n.id] : blankNode();
43
+ }
44
+ // 被移出计划的旧节点不删除:挂到 _detached,历史成绩仍可追溯
45
+ const detached = {};
46
+ if (prev && prev.nodes) {
47
+ for (const [k, v] of Object.entries(prev.nodes)) {
48
+ if (!nodes[k]) detached[k] = v;
49
+ }
50
+ }
51
+ const next = {
52
+ schema_version: 1,
53
+ subject_id: id,
54
+ curriculum_revision: cur.revision,
55
+ updated_at: nowIso(),
56
+ current_node_id: (prev && prev.current_node_id && nodes[prev.current_node_id])
57
+ ? prev.current_node_id
58
+ : firstAvailable(cur, nodes),
59
+ nodes,
60
+ ...(Object.keys(detached).length ? { _detached: detached } : {}),
61
+ history: (prev && prev.history) || [],
62
+ };
63
+ await checkOrThrow('progress', next);
64
+ await writeJsonVersioned(subjectFile(id, PROGRESS_FILE), next, 'progress');
65
+ return next;
66
+ }
67
+
68
+ // 可进入的节点:先修全部 mastered 且自身未 mastered
69
+ export function availableNodes(cur, prog) {
70
+ const nodes = cur.nodes || [];
71
+ const st = (id) => (prog && prog.nodes && prog.nodes[id] ? prog.nodes[id].status : 'not_started');
72
+ return nodes.filter((n) => st(n.id) !== 'mastered' && n.prerequisites.every((p) => st(p) === 'mastered'));
73
+ }
74
+
75
+ function firstAvailable(cur, nodes) {
76
+ const st = (id) => (nodes[id] ? nodes[id].status : 'not_started');
77
+ const free = (cur.nodes || []).filter((n) => n.prerequisites.every((p) => st(p) === 'mastered'));
78
+ const inprog = free.find((n) => st(n.id) === 'in_progress');
79
+ return (inprog || free[0] || (cur.nodes || [])[0] || {}).id ?? null;
80
+ }
81
+
82
+ // 锁定原因(给网页显示,不编造)
83
+ export function lockReason(cur, prog, nodeId) {
84
+ const node = (cur.nodes || []).find((n) => n.id === nodeId);
85
+ if (!node) return `节点 ${nodeId} 不在当前计划中`;
86
+ const st = (id) => (prog && prog.nodes && prog.nodes[id] ? prog.nodes[id].status : 'not_started');
87
+ const unmet = node.prerequisites.filter((p) => st(p) !== 'mastered');
88
+ if (!unmet.length) return null;
89
+ const names = unmet.map((p) => {
90
+ const pn = (cur.nodes || []).find((n) => n.id === p);
91
+ return pn ? `${p}(${pn.title})` : p;
92
+ });
93
+ return `先修未完成:${names.join('、')}`;
94
+ }
95
+
96
+ /* ---------- 写:作答记录(不构成掌握判定) ---------- */
97
+
98
+ // 网页提交/批改消费时调用。只更新成绩与尝试次数,**绝不写 mastered**。
99
+ export async function recordScore(subjectId, nodeId, { score = null, attemptRef = null, misconceptionRefs = [], at = nowIso() } = {}) {
100
+ const id = assertSafeId(subjectId, 'subject_id');
101
+ const nid = assertNodeId(nodeId);
102
+ const prog = await loadProgress(id);
103
+ if (!prog) throw new Error(`科目 ${id} 还没有进度文件(先确认计划)`);
104
+ if (!prog.nodes[nid]) throw new Error(`进度中没有节点 ${nid}`);
105
+ const cur = prog.nodes[nid];
106
+ const next = {
107
+ ...prog,
108
+ updated_at: nowIso(),
109
+ nodes: {
110
+ ...prog.nodes,
111
+ [nid]: {
112
+ ...cur,
113
+ attempts: cur.attempts + 1,
114
+ last_score: score === null ? cur.last_score : Number(score),
115
+ last_studied_at: at,
116
+ attempt_refs: attemptRef && !cur.attempt_refs.includes(attemptRef)
117
+ ? [...cur.attempt_refs, attemptRef] : cur.attempt_refs,
118
+ misconception_refs: [...new Set([...cur.misconception_refs, ...misconceptionRefs])],
119
+ // 只从 not_started 进入 in_progress;已 mastered 不因一次低分自动降级(由导师判定)
120
+ status: cur.status === 'not_started' ? 'in_progress' : cur.status,
121
+ },
122
+ },
123
+ history: [...(prog.history || []), {
124
+ at, node_id: nid,
125
+ from: cur.status,
126
+ to: cur.status === 'not_started' ? 'in_progress' : cur.status,
127
+ judged_by: 'record',
128
+ evidence: attemptRef ? [attemptRef] : [],
129
+ reason: score === null ? '记录作答(不改掌握状态)' : `记录作答得分 ${score}`,
130
+ }],
131
+ };
132
+ await checkOrThrow('progress', next);
133
+ await writeJsonVersioned(subjectFile(id, PROGRESS_FILE), next, 'progress');
134
+ return next;
135
+ }
136
+
137
+ /* ---------- 写:导师判定(唯一能写 mastered 的入口) ---------- */
138
+
139
+ // verdict: 'mastered' | 'needs_review' | 'in_progress'
140
+ // 必须带 evidence(真实存在的答卷/批改路径),否则拒绝——杜绝「纯口头说会了」
141
+ export async function applyVerdict(subjectId, nodeId, {
142
+ verdict, evidence = [], by = 'tutor', reason = '', score = null, at = nowIso(), overridePrereq = null, curriculum = null,
143
+ } = {}) {
144
+ const id = assertSafeId(subjectId, 'subject_id');
145
+ const nid = assertNodeId(nodeId);
146
+ if (!['mastered', 'needs_review', 'in_progress'].includes(verdict)) {
147
+ const e = new Error(`verdict 非法:${verdict}(只能是 mastered / needs_review / in_progress)`);
148
+ e.code = 'BAD_VERDICT';
149
+ throw e;
150
+ }
151
+ const ev = (evidence || []).map(String).filter(Boolean);
152
+ if (verdict === 'mastered' && ev.length === 0) {
153
+ const e = new Error(`节点 ${nid} 不能无证据标记 mastered:必须给出答卷/批改记录路径(evidence)`);
154
+ e.code = 'NO_EVIDENCE';
155
+ throw e;
156
+ }
157
+ // 证据必须真实存在:掌握记录要能追溯到答卷/批改结果,不接受凭空写的路径
158
+ const missingEvidence = [];
159
+ for (const p of ev) {
160
+ const abs = path.resolve(WORKSPACE, p);
161
+ if (!abs.startsWith(WORKSPACE + path.sep) || !(await exists(abs))) missingEvidence.push(p);
162
+ }
163
+ if (missingEvidence.length) {
164
+ const e = new Error(`证据文件不存在,不能据此判定掌握:\n - ` + missingEvidence.join('\n - '));
165
+ e.code = 'BAD_EVIDENCE';
166
+ e.errors = missingEvidence;
167
+ throw e;
168
+ }
169
+ const prog = await loadProgress(id);
170
+ if (!prog) throw new Error(`科目 ${id} 还没有进度文件`);
171
+ if (!prog.nodes[nid]) throw new Error(`进度中没有节点 ${nid}`);
172
+
173
+ // 先修门槛:未完成不得直接掌握(除非显式 override 并留痕)
174
+ if (verdict === 'mastered' && curriculum) {
175
+ const node = (curriculum.nodes || []).find((n) => n.id === nid);
176
+ const st = (x) => (prog.nodes[x] ? prog.nodes[x].status : 'not_started');
177
+ const unmet = node ? node.prerequisites.filter((p) => st(p) !== 'mastered') : [];
178
+ if (unmet.length && !overridePrereq) {
179
+ const e = new Error(`先修未完成,不能标记 mastered:${unmet.join('、')}(如确需跳级,请显式传 overridePrereq 并说明理由)`);
180
+ e.code = 'PREREQ_UNMET';
181
+ e.errors = unmet;
182
+ throw e;
183
+ }
184
+ }
185
+
186
+ const cur = prog.nodes[nid];
187
+ const nextNode = {
188
+ ...cur,
189
+ status: verdict,
190
+ attempts: cur.attempts,
191
+ last_score: score === null ? cur.last_score : Number(score),
192
+ last_studied_at: at,
193
+ attempt_refs: [...new Set([...cur.attempt_refs, ...ev])],
194
+ mastered_at: verdict === 'mastered' ? at : (verdict === 'needs_review' ? cur.mastered_at : null),
195
+ judged_by: String(by),
196
+ override_prereq: overridePrereq ? String(overridePrereq) : cur.override_prereq,
197
+ };
198
+ const next = {
199
+ ...prog,
200
+ updated_at: nowIso(),
201
+ current_node_id: verdict === 'mastered' ? pickNext(prog, nextNode, nid, curriculum) : nid,
202
+ nodes: { ...prog.nodes, [nid]: nextNode },
203
+ history: [...(prog.history || []), {
204
+ at, node_id: nid, from: cur.status, to: verdict,
205
+ judged_by: String(by), evidence: ev,
206
+ reason: String(reason || ''),
207
+ }],
208
+ };
209
+ await checkOrThrow('progress', next);
210
+ await writeJsonVersioned(subjectFile(id, PROGRESS_FILE), next, 'progress');
211
+ return next;
212
+ }
213
+
214
+ // 推进到下一个可进入节点;找不到就停在原地(不编造)
215
+ function pickNext(prog, updatedNode, nid, curriculum) {
216
+ if (!curriculum) return nid;
217
+ const merged = { ...prog, nodes: { ...prog.nodes, [nid]: updatedNode } };
218
+ const st = (x) => (merged.nodes[x] ? merged.nodes[x].status : 'not_started');
219
+ const next = (curriculum.nodes || []).find(
220
+ (n) => n.id !== nid && st(n.id) !== 'mastered' && n.prerequisites.every((p) => st(p) === 'mastered')
221
+ );
222
+ return next ? next.id : nid;
223
+ }
224
+
225
+ /* ---------- 汇总(网页顶部展示用) ---------- */
226
+
227
+ export function summarize(cur, prog) {
228
+ const nodes = (cur && cur.nodes) || [];
229
+ const st = (id) => (prog && prog.nodes && prog.nodes[id] ? prog.nodes[id] : blankNode());
230
+ const count = { mastered: 0, in_progress: 0, not_started: 0, needs_review: 0 };
231
+ const needReview = [];
232
+ for (const n of nodes) {
233
+ const s = st(n.id).status;
234
+ count[s] = (count[s] || 0) + 1;
235
+ if (s === 'needs_review') needReview.push({ id: n.id, title: n.title });
236
+ }
237
+ const current = prog && prog.current_node_id ? nodes.find((n) => n.id === prog.current_node_id) : null;
238
+ return {
239
+ total: nodes.length,
240
+ ...count,
241
+ current_node: current ? { id: current.id, title: current.title } : null,
242
+ needs_review: needReview,
243
+ curriculum_revision: cur ? cur.revision : null,
244
+ status: cur ? cur.status : 'none',
245
+ active: !!(cur && cur.status === 'active' && cur.confirmed_at),
246
+ };
247
+ }
@@ -0,0 +1,88 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "title": "curriculum(课程计划:草案 / 已确认 / 已归档)",
4
+ "type": "object",
5
+ "required": [
6
+ "schema_version", "subject", "subject_id", "title", "goal",
7
+ "revision", "status", "created_at", "updated_at", "nodes"
8
+ ],
9
+ "additionalProperties": false,
10
+ "definitions": {
11
+ "sourceRef": {
12
+ "type": "object",
13
+ "required": ["path", "location"],
14
+ "additionalProperties": false,
15
+ "properties": {
16
+ "path": { "type": "string", "minLength": 1, "maxLength": 400 },
17
+ "location": { "type": "string", "minLength": 1, "maxLength": 300 },
18
+ "missing": { "type": "boolean" },
19
+ "size": { "type": ["integer", "null"] },
20
+ "mtime_ms": { "type": ["number", "null"] }
21
+ }
22
+ },
23
+ "node": {
24
+ "type": "object",
25
+ "required": [
26
+ "id", "title", "objective", "prerequisites", "source_refs",
27
+ "kind", "estimated_minutes", "quiz_refs"
28
+ ],
29
+ "additionalProperties": false,
30
+ "properties": {
31
+ "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
32
+ "title": { "type": "string", "minLength": 1, "maxLength": 120 },
33
+ "objective": { "type": "string", "minLength": 1, "maxLength": 1000 },
34
+ "prerequisites": {
35
+ "type": "array", "items": { "type": "string" }, "uniqueItems": true
36
+ },
37
+ "source_refs": {
38
+ "type": "array", "items": { "$ref": "#/definitions/sourceRef" }
39
+ },
40
+ "kind": { "enum": ["concept", "practice", "review"] },
41
+ "estimated_minutes": { "type": "integer", "minimum": 1, "maximum": 600 },
42
+ "quiz_refs": {
43
+ "type": "array", "items": { "type": "string" }, "uniqueItems": true
44
+ },
45
+ "notes": { "type": "string", "maxLength": 2000 }
46
+ }
47
+ }
48
+ },
49
+ "properties": {
50
+ "schema_version": { "const": 1 },
51
+ "subject": { "type": "string", "minLength": 1, "maxLength": 80 },
52
+ "subject_id": { "type": "string", "pattern": "^[^\\\\/:*?\"<>|\\x00-\\x1f]{1,40}$" },
53
+ "title": { "type": "string", "minLength": 1, "maxLength": 120 },
54
+ "goal": { "type": "string", "maxLength": 2000 },
55
+ "revision": { "type": "integer", "minimum": 1 },
56
+ "status": { "enum": ["draft", "active", "archived"] },
57
+ "created_at": { "type": "string", "minLength": 1 },
58
+ "updated_at": { "type": "string", "minLength": 1 },
59
+ "confirmed_at": { "type": ["string", "null"] },
60
+ "confirmed_by": { "type": ["string", "null"] },
61
+ "based_on": {
62
+ "type": ["integer", "null"],
63
+ "description": "本版本基于的上一版 revision;草案修订时填写,用于差异对比与旧版本追溯"
64
+ },
65
+ "change_note": { "type": "string", "maxLength": 2000 },
66
+ "proposed_by": { "type": ["string", "null"] },
67
+ "fixture": { "type": "boolean" },
68
+ "materials": {
69
+ "type": "array",
70
+ "items": {
71
+ "type": "object",
72
+ "required": ["path", "location"],
73
+ "additionalProperties": false,
74
+ "properties": {
75
+ "path": { "type": "string", "minLength": 1, "maxLength": 400 },
76
+ "location": { "type": "string", "minLength": 1, "maxLength": 300 },
77
+ "missing": { "type": "boolean" },
78
+ "size": { "type": ["integer", "null"] },
79
+ "mtime_ms": { "type": ["number", "null"] }
80
+ }
81
+ }
82
+ },
83
+ "missing": { "type": "array", "items": { "type": "string" } },
84
+ "open_questions": { "type": "array", "items": { "type": "string" } },
85
+ "notes": { "type": "string", "maxLength": 4000 },
86
+ "nodes": { "type": "array", "items": { "$ref": "#/definitions/node" } }
87
+ }
88
+ }
@@ -0,0 +1,56 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "title": "handoff(模块交接:短小、结构化,取代聊天全文进入下一模块)",
4
+ "type": "object",
5
+ "required": [
6
+ "schema_version", "subject_id", "node_id", "created_at",
7
+ "curriculum_revision", "completed", "unfinished", "mastery_evidence",
8
+ "open_questions", "misconceptions", "next_node", "material_refs", "session"
9
+ ],
10
+ "additionalProperties": false,
11
+ "definitions": {
12
+ "sourceRef": {
13
+ "type": "object",
14
+ "required": ["path", "location"],
15
+ "additionalProperties": false,
16
+ "properties": {
17
+ "path": { "type": "string", "minLength": 1, "maxLength": 400 },
18
+ "location": { "type": "string", "minLength": 1, "maxLength": 300 },
19
+ "missing": { "type": "boolean" },
20
+ "size": { "type": ["integer", "null"] },
21
+ "mtime_ms": { "type": ["number", "null"] }
22
+ }
23
+ }
24
+ },
25
+ "properties": {
26
+ "schema_version": { "const": 1 },
27
+ "subject_id": { "type": "string", "pattern": "^[^\\\\/:*?\"<>|\\x00-\\x1f]{1,40}$" },
28
+ "node_id": { "type": "string", "minLength": 1, "maxLength": 64 },
29
+ "created_at": { "type": "string", "minLength": 1 },
30
+ "curriculum_revision": { "type": "integer", "minimum": 1 },
31
+ "completed": { "type": "array", "items": { "type": "string" } },
32
+ "unfinished": { "type": "array", "items": { "type": "string" } },
33
+ "mastery_evidence": {
34
+ "type": "array",
35
+ "items": { "type": "string", "minLength": 1 },
36
+ "description": "必须指向真实存在的答卷文件;没有证据不能写 mastered"
37
+ },
38
+ "open_questions": { "type": "array", "items": { "type": "string" } },
39
+ "misconceptions": { "type": "array", "items": { "type": "string" } },
40
+ "next_node": { "type": ["string", "null"] },
41
+ "material_refs": { "type": "array", "items": { "$ref": "#/definitions/sourceRef" } },
42
+ "session": {
43
+ "type": "object",
44
+ "required": ["isolation"],
45
+ "additionalProperties": false,
46
+ "properties": {
47
+ "isolation": {
48
+ "enum": ["automatic", "manual", "unknown"],
49
+ "description": "automatic=平台程序化新会话;manual=用户手动新开会话;unknown=未验证"
50
+ },
51
+ "note": { "type": "string", "maxLength": 1000 },
52
+ "dsn_session_id": { "type": ["string", "null"] }
53
+ }
54
+ }
55
+ }
56
+ }
@@ -0,0 +1,28 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "title": "node-practice-map(节点 ↔ 练习/答卷 的显式映射)",
4
+ "type": "object",
5
+ "required": ["schema_version", "subject_id", "curriculum_revision", "updated_at", "links"],
6
+ "additionalProperties": false,
7
+ "properties": {
8
+ "schema_version": { "const": 1 },
9
+ "subject_id": { "type": "string", "pattern": "^[^\\\\/:*?\"<>|\\x00-\\x1f]{1,40}$" },
10
+ "curriculum_revision": { "type": "integer", "minimum": 1 },
11
+ "updated_at": { "type": "string", "minLength": 1 },
12
+ "links": {
13
+ "type": "array",
14
+ "items": {
15
+ "type": "object",
16
+ "required": ["node_id", "practice_id", "course"],
17
+ "additionalProperties": false,
18
+ "properties": {
19
+ "node_id": { "type": "string", "minLength": 1, "maxLength": 64 },
20
+ "practice_id": { "type": "string", "minLength": 1, "maxLength": 120 },
21
+ "course": { "type": "string", "minLength": 1, "maxLength": 80 },
22
+ "note": { "type": "string", "maxLength": 500 },
23
+ "created_at": { "type": "string" }
24
+ }
25
+ }
26
+ }
27
+ }
28
+ }
@@ -0,0 +1,66 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "title": "progress(学习进度:掌握状态的唯一权威来源)",
4
+ "type": "object",
5
+ "required": [
6
+ "schema_version", "subject_id", "curriculum_revision",
7
+ "updated_at", "current_node_id", "nodes"
8
+ ],
9
+ "additionalProperties": false,
10
+ "definitions": {
11
+ "nodeProgress": {
12
+ "type": "object",
13
+ "required": [
14
+ "status", "attempts", "last_score", "last_studied_at",
15
+ "attempt_refs", "misconception_refs"
16
+ ],
17
+ "additionalProperties": false,
18
+ "properties": {
19
+ "status": { "enum": ["not_started", "in_progress", "mastered", "needs_review"] },
20
+ "attempts": { "type": "integer", "minimum": 0 },
21
+ "last_score": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
22
+ "last_studied_at": { "type": ["string", "null"] },
23
+ "attempt_refs": { "type": "array", "items": { "type": "string" } },
24
+ "misconception_refs": { "type": "array", "items": { "type": "string" } },
25
+ "mastered_at": { "type": ["string", "null"] },
26
+ "judged_by": { "type": ["string", "null"] },
27
+ "override_prereq": { "type": ["string", "null"] },
28
+ "notes": { "type": "string", "maxLength": 2000 }
29
+ }
30
+ },
31
+ "historyEntry": {
32
+ "type": "object",
33
+ "required": ["at", "node_id", "from", "to", "judged_by", "evidence"],
34
+ "additionalProperties": false,
35
+ "properties": {
36
+ "at": { "type": "string", "minLength": 1 },
37
+ "node_id": { "type": "string", "minLength": 1 },
38
+ "from": { "type": "string", "minLength": 1 },
39
+ "to": { "type": "string", "minLength": 1 },
40
+ "judged_by": { "type": "string", "minLength": 1 },
41
+ "evidence": { "type": "array", "items": { "type": "string" } },
42
+ "reason": { "type": "string", "maxLength": 1000 }
43
+ }
44
+ }
45
+ },
46
+ "properties": {
47
+ "schema_version": { "const": 1 },
48
+ "subject_id": { "type": "string", "pattern": "^[^\\\\/:*?\"<>|\\x00-\\x1f]{1,40}$" },
49
+ "curriculum_revision": { "type": "integer", "minimum": 1 },
50
+ "updated_at": { "type": "string", "minLength": 1 },
51
+ "current_node_id": { "type": ["string", "null"] },
52
+ "nodes": {
53
+ "type": "object",
54
+ "additionalProperties": { "$ref": "#/definitions/nodeProgress" }
55
+ },
56
+ "_detached": {
57
+ "type": "object",
58
+ "description": "被移出当前计划的旧节点:不删除,历史成绩仍可追溯",
59
+ "additionalProperties": { "$ref": "#/definitions/nodeProgress" }
60
+ },
61
+ "history": {
62
+ "type": "array",
63
+ "items": { "$ref": "#/definitions/historyEntry" }
64
+ }
65
+ }
66
+ }
@@ -0,0 +1,53 @@
1
+ // schema 装载与校验:四份数据契约的唯一入口。
2
+ // 任何写盘前都必须过这里,避免「看起来对」的数据污染学习进度。
3
+ import fsp from 'node:fs/promises';
4
+ import path from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+ import { validate } from './jsonschema.mjs';
7
+
8
+ const HERE = path.dirname(fileURLToPath(import.meta.url));
9
+ const SCHEMA_DIR = path.join(HERE, 'schema');
10
+
11
+ const cache = new Map();
12
+
13
+ export async function loadSchema(name) {
14
+ if (cache.has(name)) return cache.get(name);
15
+ const file = path.join(SCHEMA_DIR, `${name}.schema.json`);
16
+ const s = JSON.parse(await fsp.readFile(file, 'utf8'));
17
+ cache.set(name, s);
18
+ return s;
19
+ }
20
+
21
+ export const SCHEMA_NAMES = ['curriculum', 'progress', 'handoff', 'node-practice-map'];
22
+
23
+ // 返回错误数组(空数组=通过)
24
+ export async function check(name, data) {
25
+ return validate(await loadSchema(name), data);
26
+ }
27
+
28
+ // 不通过就抛,错误信息带 schema 名与逐条原因
29
+ export async function checkOrThrow(name, data) {
30
+ const errs = await check(name, data);
31
+ if (errs.length) {
32
+ const e = new Error(`${name} 数据不符合 schema:\n - ` + errs.join('\n - '));
33
+ e.code = 'SCHEMA_INVALID';
34
+ e.errors = errs;
35
+ throw e;
36
+ }
37
+ return true;
38
+ }
39
+
40
+ // 启动时自检:schema 文件本身能被解析(防止 schema 写坏导致校验静默失效)
41
+ export async function selfCheckSchemas() {
42
+ const out = [];
43
+ for (const n of SCHEMA_NAMES) {
44
+ try {
45
+ const s = await loadSchema(n);
46
+ if (!s || typeof s !== 'object') throw new Error('不是对象');
47
+ out.push({ schema: n, ok: true });
48
+ } catch (e) {
49
+ out.push({ schema: n, ok: false, error: String(e.message || e) });
50
+ }
51
+ }
52
+ return out;
53
+ }