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.
- package/README.md +41 -7
- package/assets/collect/README.md +55 -0
- package/assets/skills/course-inbox-sync.md +182 -0
- package/assets/skills/course-material-digest.md +173 -0
- package/assets/skills/one-to-one-tutor.md +320 -0
- package/assets/tools/pdf/pdf-render.ps1 +30 -0
- package/assets/tools/pptx-digest.py +99 -0
- package/assets/tools/pptx-map.py +98 -0
- package/assets/tools/pptx-media.py +101 -0
- package/assets/tools/qq-group-msg.py +258 -0
- package/assets/tools/qq-group-sync.py +265 -0
- package/docs//345/215/217/344/275/234/345/274/200/345/217/221.md +18 -10
- package/lib/client.js +110 -0
- package/lib/{index.d.mts → index.d.ts} +3 -1
- package/lib/index.js +392 -0
- package/package.json +8 -7
- package/src/client/settings.tsx +6 -4
- package/src/index.ts +36 -11
- package/src/practice/learn/api.mjs +393 -0
- package/src/practice/learn/cli.mjs +175 -0
- package/src/practice/learn/curriculum.mjs +292 -0
- package/src/practice/learn/handoff.mjs +73 -0
- package/src/practice/learn/jsonschema.mjs +171 -0
- package/src/practice/learn/mapping.mjs +90 -0
- package/src/practice/learn/progress.mjs +247 -0
- package/src/practice/learn/schema/curriculum.schema.json +88 -0
- package/src/practice/learn/schema/handoff.schema.json +56 -0
- package/src/practice/learn/schema/node-practice-map.schema.json +28 -0
- package/src/practice/learn/schema/progress.schema.json +66 -0
- package/src/practice/learn/schemas.mjs +53 -0
- package/src/practice/learn/store.mjs +247 -0
- package/src/practice/public/app.js +883 -0
- package/src/practice/public/index.html +19 -0
- package/src/practice/public/ink.js +349 -0
- package/src/practice/public/learn.css +20 -0
- package/src/practice/public/learn.js +329 -0
- package/src/practice/public/style.css +326 -0
- package/src/practice/public/vendor/katex/contrib/auto-render.min.js +1 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_AMS-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Caligraphic-Bold.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Caligraphic-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Fraktur-Bold.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Fraktur-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Main-Bold.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Main-BoldItalic.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Main-Italic.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Main-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Math-BoldItalic.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Math-Italic.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_SansSerif-Bold.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_SansSerif-Italic.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_SansSerif-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Script-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Size1-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Size2-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Size3-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Size4-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/fonts/KaTeX_Typewriter-Regular.woff2 +0 -0
- package/src/practice/public/vendor/katex/katex.min.css +1 -0
- package/src/practice/public/vendor/katex/katex.min.js +1 -0
- package/src/practice//346/234/215/345/212/241.mjs +443 -0
- package/src/practice//346/240/241/351/252/214/351/242/230/347/233/256.mjs +114 -0
- package/src/practice//347/255/211/345/276/205/346/217/220/344/272/244.mjs +100 -0
- package/src/practice-service.ts +99 -0
- package/src/practice-tool.ts +91 -0
- package/src/skills.ts +156 -0
- package/lib/client.d.mts +0 -10
- package/lib/client.mjs +0 -87
- package/lib/index.mjs +0 -29
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
// 课程计划(curriculum):草案 → 用户确认 → active。
|
|
2
|
+
//
|
|
3
|
+
// 硬规则(方案 §2.4、§4-A/C):
|
|
4
|
+
// - 只有 status=active 且 confirmed_at 非空的计划才算「有效计划」
|
|
5
|
+
// - 模型不能静默重排:任何改动都产出新 revision,并保留旧版本
|
|
6
|
+
// - 节点 ID 稳定,不随排序变化
|
|
7
|
+
// - source_refs 必须能定位;缺材料标 missing,禁止编造页码/来源
|
|
8
|
+
import path from 'node:path';
|
|
9
|
+
import { checkOrThrow } from './schemas.mjs';
|
|
10
|
+
import {
|
|
11
|
+
subjectDir, subjectFile, readJson, writeJsonVersioned, ensureDataRoot,
|
|
12
|
+
checkSourceRef, assertSafeId, assertNodeId, nowIso, exists, safeId,
|
|
13
|
+
} from './store.mjs';
|
|
14
|
+
|
|
15
|
+
export const CURRICULUM_FILE = 'curriculum.json';
|
|
16
|
+
export const META_FILE = 'meta.json';
|
|
17
|
+
|
|
18
|
+
/* ---------- 读取 ---------- */
|
|
19
|
+
|
|
20
|
+
export async function loadCurriculum(subjectId) {
|
|
21
|
+
const id = assertSafeId(subjectId, 'subject_id');
|
|
22
|
+
const cur = await readJson(subjectFile(id, CURRICULUM_FILE), null);
|
|
23
|
+
if (cur && cur.subject_id !== id) {
|
|
24
|
+
const e = new Error(`curriculum.json 的 subject_id(${cur.subject_id}) 与目录名(${id}) 不一致`);
|
|
25
|
+
e.code = 'SUBJECT_MISMATCH';
|
|
26
|
+
throw e;
|
|
27
|
+
}
|
|
28
|
+
return cur;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export async function loadMeta(subjectId) {
|
|
32
|
+
return readJson(subjectFile(assertSafeId(subjectId, 'subject_id'), META_FILE), null);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
// 是否是一份「有效计划」:唯一判据,网页与导师流程共用
|
|
36
|
+
export function isActive(cur) {
|
|
37
|
+
return !!cur && cur.status === 'active' && !!cur.confirmed_at;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/* ---------- 校验 ---------- */
|
|
41
|
+
|
|
42
|
+
// 结构 + 语义校验:节点 ID 唯一、先修指向存在的节点、无先修环、来源引用可定位
|
|
43
|
+
export async function validateCurriculum(cur, { strictSources = true } = {}) {
|
|
44
|
+
await checkOrThrow('curriculum', cur);
|
|
45
|
+
const errs = [];
|
|
46
|
+
const ids = new Set();
|
|
47
|
+
for (const n of cur.nodes) {
|
|
48
|
+
if (ids.has(n.id)) errs.push(`节点 ID 重复:${n.id}(ID 必须稳定且唯一)`);
|
|
49
|
+
ids.add(n.id);
|
|
50
|
+
}
|
|
51
|
+
for (const n of cur.nodes) {
|
|
52
|
+
for (const p of n.prerequisites) {
|
|
53
|
+
if (p === n.id) errs.push(`节点 ${n.id} 把自己列为先修`);
|
|
54
|
+
else if (!ids.has(p)) errs.push(`节点 ${n.id} 的先修 ${p} 不存在`);
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
// 先修环检测(DAG 是路线图的前提)
|
|
58
|
+
const state = new Map();
|
|
59
|
+
const dfs = (id, stack) => {
|
|
60
|
+
if (state.get(id) === 2) return;
|
|
61
|
+
if (state.get(id) === 1) { errs.push(`先修关系成环:${[...stack, id].join(' → ')}`); return; }
|
|
62
|
+
state.set(id, 1);
|
|
63
|
+
const node = cur.nodes.find((x) => x.id === id);
|
|
64
|
+
for (const p of node ? node.prerequisites : []) dfs(p, [...stack, id]);
|
|
65
|
+
state.set(id, 2);
|
|
66
|
+
};
|
|
67
|
+
for (const n of cur.nodes) dfs(n.id, []);
|
|
68
|
+
|
|
69
|
+
if (errs.length) {
|
|
70
|
+
const e = new Error('课程计划语义校验失败:\n - ' + errs.join('\n - '));
|
|
71
|
+
e.code = 'CURRICULUM_INVALID';
|
|
72
|
+
e.errors = errs;
|
|
73
|
+
throw e;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
if (strictSources) {
|
|
77
|
+
const refs = [];
|
|
78
|
+
for (const n of cur.nodes) for (const r of n.source_refs) refs.push({ node: n.id, ref: r });
|
|
79
|
+
for (const { node, ref } of refs) {
|
|
80
|
+
let checked;
|
|
81
|
+
try {
|
|
82
|
+
checked = await checkSourceRef(ref);
|
|
83
|
+
} catch (e) {
|
|
84
|
+
const err = new Error(`节点 ${node} 的 source_ref 非法:${e.message}`);
|
|
85
|
+
err.code = e.code || 'CURRICULUM_INVALID';
|
|
86
|
+
throw err;
|
|
87
|
+
}
|
|
88
|
+
// 就地补全(missing/size/mtime),不编造 location
|
|
89
|
+
Object.assign(ref, checked);
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
return cur;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/* ---------- 写:草案 ---------- */
|
|
96
|
+
|
|
97
|
+
export function newNode(input) {
|
|
98
|
+
return {
|
|
99
|
+
id: assertNodeId(input.id),
|
|
100
|
+
title: String(input.title ?? '').trim(),
|
|
101
|
+
objective: String(input.objective ?? '').trim(),
|
|
102
|
+
prerequisites: [...new Set((input.prerequisites || []).map((x) => assertNodeId(x)))],
|
|
103
|
+
source_refs: (input.source_refs || []).map((r) => ({
|
|
104
|
+
path: String(r.path ?? '').replace(/\\/g, '/'),
|
|
105
|
+
location: String(r.location ?? '').trim(),
|
|
106
|
+
})),
|
|
107
|
+
kind: input.kind || 'concept',
|
|
108
|
+
estimated_minutes: Number(input.estimated_minutes || 20),
|
|
109
|
+
quiz_refs: [...new Set((input.quiz_refs || []).map(String))],
|
|
110
|
+
...(input.notes ? { notes: String(input.notes) } : {}),
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
// 新建或覆盖一份**草案**。覆盖已有 active 计划会被拒绝(必须先走 accept 流程)。
|
|
115
|
+
export async function saveDraft(subjectId, draft, { allowOverwriteActive = false } = {}) {
|
|
116
|
+
await ensureDataRoot();
|
|
117
|
+
const id = assertSafeId(subjectId, 'subject_id');
|
|
118
|
+
const prev = await loadCurriculum(id);
|
|
119
|
+
if (isActive(prev) && !allowOverwriteActive) {
|
|
120
|
+
const e = new Error(`科目 ${id} 已有生效计划(revision ${prev.revision})。草案不能直接覆盖生效计划,请用 proposeRevision 生成新版本待确认。`);
|
|
121
|
+
e.code = 'ACTIVE_EXISTS';
|
|
122
|
+
throw e;
|
|
123
|
+
}
|
|
124
|
+
const next = {
|
|
125
|
+
schema_version: 1,
|
|
126
|
+
subject: String(draft.subject || id).trim(),
|
|
127
|
+
subject_id: id,
|
|
128
|
+
title: String(draft.title || id).trim(),
|
|
129
|
+
goal: String(draft.goal || '').trim(),
|
|
130
|
+
revision: prev ? prev.revision : 1,
|
|
131
|
+
status: 'draft',
|
|
132
|
+
created_at: prev ? prev.created_at : nowIso(),
|
|
133
|
+
updated_at: nowIso(),
|
|
134
|
+
confirmed_at: null,
|
|
135
|
+
confirmed_by: null,
|
|
136
|
+
based_on: prev ? prev.revision : null,
|
|
137
|
+
change_note: String(draft.change_note || ''),
|
|
138
|
+
materials: (draft.materials || []).map((m) => ({
|
|
139
|
+
path: String(m.path ?? '').replace(/\\/g, '/'),
|
|
140
|
+
location: String(m.location ?? '').trim(),
|
|
141
|
+
})),
|
|
142
|
+
missing: (draft.missing || []).map(String),
|
|
143
|
+
open_questions: (draft.open_questions || []).map(String),
|
|
144
|
+
...(draft.notes ? { notes: String(draft.notes) } : {}),
|
|
145
|
+
...(draft.fixture ? { fixture: true } : {}),
|
|
146
|
+
nodes: (draft.nodes || []).map(newNode),
|
|
147
|
+
};
|
|
148
|
+
await validateCurriculum(next);
|
|
149
|
+
await writeJsonVersioned(subjectFile(id, CURRICULUM_FILE), next, 'curriculum');
|
|
150
|
+
return next;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/* ---------- 写:确认生效 ---------- */
|
|
154
|
+
|
|
155
|
+
// 用户确认后草案才生效;同时初始化 progress(已存在的进度不动,只补新节点)
|
|
156
|
+
export async function acceptCurriculum(subjectId, { by = 'user', revision = null, expectedRevision = null } = {}) {
|
|
157
|
+
const id = assertSafeId(subjectId, 'subject_id');
|
|
158
|
+
const cur = await loadCurriculum(id);
|
|
159
|
+
if (!cur) {
|
|
160
|
+
const e = new Error(`科目 ${id} 还没有计划草案`);
|
|
161
|
+
e.code = 'NO_CURRICULUM';
|
|
162
|
+
throw e;
|
|
163
|
+
}
|
|
164
|
+
if (revision !== null && cur.revision !== revision) {
|
|
165
|
+
const e = new Error(`确认的 revision(${revision}) 与当前文件(${cur.revision}) 不一致,请刷新后重试`);
|
|
166
|
+
e.code = 'REVISION_MISMATCH';
|
|
167
|
+
throw e;
|
|
168
|
+
}
|
|
169
|
+
// 乐观并发:网页提交时带上它看到的 revision,防止并发下把别人的改动顶掉
|
|
170
|
+
if (expectedRevision !== null && cur.revision !== expectedRevision) {
|
|
171
|
+
const e = new Error(`页面看到的 revision(${expectedRevision}) 已过期,当前为 ${cur.revision}。请刷新后再确认。`);
|
|
172
|
+
e.code = 'REVISION_STALE';
|
|
173
|
+
throw e;
|
|
174
|
+
}
|
|
175
|
+
if (isActive(cur) && cur.confirmed_at) {
|
|
176
|
+
const e = new Error(`科目 ${id} revision ${cur.revision} 已是生效计划,无需重复确认`);
|
|
177
|
+
e.code = 'ALREADY_ACTIVE';
|
|
178
|
+
throw e;
|
|
179
|
+
}
|
|
180
|
+
await validateCurriculum(cur);
|
|
181
|
+
const next = { ...cur, status: 'active', confirmed_at: nowIso(), confirmed_by: String(by), updated_at: nowIso() };
|
|
182
|
+
await writeJsonVersioned(subjectFile(id, CURRICULUM_FILE), next, 'curriculum');
|
|
183
|
+
await writeJsonVersioned(subjectFile(id, META_FILE), {
|
|
184
|
+
schema_version: 1,
|
|
185
|
+
subject_id: id,
|
|
186
|
+
title: next.title,
|
|
187
|
+
goal: next.goal,
|
|
188
|
+
active_revision: next.revision,
|
|
189
|
+
status: 'active',
|
|
190
|
+
updated_at: nowIso(),
|
|
191
|
+
...(next.fixture ? { fixture: true } : {}),
|
|
192
|
+
}, 'meta');
|
|
193
|
+
await initProgress(id, next);
|
|
194
|
+
return next;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/* ---------- 归档 ---------- */
|
|
198
|
+
|
|
199
|
+
export async function archiveCurriculum(subjectId, { reason = '' } = {}) {
|
|
200
|
+
const id = assertSafeId(subjectId, 'subject_id');
|
|
201
|
+
const cur = await loadCurriculum(id);
|
|
202
|
+
if (!cur) throw new Error(`科目 ${id} 没有计划`);
|
|
203
|
+
const next = { ...cur, status: 'archived', updated_at: nowIso(), change_note: reason || cur.change_note || '' };
|
|
204
|
+
await writeJsonVersioned(subjectFile(id, CURRICULUM_FILE), next, 'curriculum');
|
|
205
|
+
return next;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/* ---------- 重规划:差异草案 ---------- */
|
|
209
|
+
|
|
210
|
+
// 计算「受影响文件—受影响节点—原因—建议」,只提议不自动改(方案 §4-C)
|
|
211
|
+
export function diffCurriculums(base, next) {
|
|
212
|
+
const out = { added: [], removed: [], changed: [], unchanged: [], materials_changed: [] };
|
|
213
|
+
const bmap = new Map((base?.nodes || []).map((n) => [n.id, n]));
|
|
214
|
+
const nmap = new Map((next?.nodes || []).map((n) => [n.id, n]));
|
|
215
|
+
for (const [id, n] of nmap) if (!bmap.has(id)) out.added.push({ id, title: n.title });
|
|
216
|
+
for (const [id, n] of bmap) if (!nmap.has(id)) out.removed.push({ id, title: n.title });
|
|
217
|
+
for (const [id, n] of nmap) {
|
|
218
|
+
const b = bmap.get(id);
|
|
219
|
+
if (!b) continue;
|
|
220
|
+
const fields = [];
|
|
221
|
+
for (const f of ['title', 'objective', 'kind', 'estimated_minutes']) {
|
|
222
|
+
if (JSON.stringify(b[f]) !== JSON.stringify(n[f])) fields.push(f);
|
|
223
|
+
}
|
|
224
|
+
if (JSON.stringify(b.prerequisites) !== JSON.stringify(n.prerequisites)) fields.push('prerequisites');
|
|
225
|
+
if (JSON.stringify(b.source_refs) !== JSON.stringify(n.source_refs)) fields.push('source_refs');
|
|
226
|
+
if (JSON.stringify(b.quiz_refs) !== JSON.stringify(n.quiz_refs)) fields.push('quiz_refs');
|
|
227
|
+
if (fields.length) out.changed.push({ id, title: n.title, fields, from: b, to: n });
|
|
228
|
+
else out.unchanged.push(id);
|
|
229
|
+
}
|
|
230
|
+
const bm = new Map((base?.materials || []).map((m) => [m.path, m]));
|
|
231
|
+
const nm = new Map((next?.materials || []).map((m) => [m.path, m]));
|
|
232
|
+
for (const [p, m] of nm) if (!bm.has(p)) out.materials_changed.push({ path: p, kind: 'added', location: m.location });
|
|
233
|
+
for (const [p, m] of bm) {
|
|
234
|
+
if (!nm.has(p)) out.materials_changed.push({ path: p, kind: 'removed', location: m.location });
|
|
235
|
+
else if (JSON.stringify(bm.get(p)) !== JSON.stringify(nm.get(p))) out.materials_changed.push({ path: p, kind: 'changed', location: nm.get(p).location });
|
|
236
|
+
}
|
|
237
|
+
return out;
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
// 生成一份新的重规划草案:保留未受影响节点的 ID 与掌握状态,revision+1,不覆盖 active
|
|
241
|
+
export async function proposeRevision(subjectId, changes, { reason = '', by = 'model' } = {}) {
|
|
242
|
+
const id = assertSafeId(subjectId, 'subject_id');
|
|
243
|
+
const base = await loadCurriculum(id);
|
|
244
|
+
if (!base) throw new Error(`科目 ${id} 没有计划可重规划`);
|
|
245
|
+
const nodes = (changes.nodes || base.nodes).map(newNode);
|
|
246
|
+
const next = {
|
|
247
|
+
...base,
|
|
248
|
+
revision: base.revision + 1,
|
|
249
|
+
status: 'draft',
|
|
250
|
+
confirmed_at: null,
|
|
251
|
+
confirmed_by: null,
|
|
252
|
+
based_on: base.revision,
|
|
253
|
+
change_note: String(reason || changes.change_note || ''),
|
|
254
|
+
updated_at: nowIso(),
|
|
255
|
+
title: changes.title || base.title,
|
|
256
|
+
goal: changes.goal || base.goal,
|
|
257
|
+
materials: (changes.materials || base.materials).map((m) => ({
|
|
258
|
+
path: String(m.path ?? '').replace(/\\/g, '/'),
|
|
259
|
+
location: String(m.location ?? '').trim(),
|
|
260
|
+
})),
|
|
261
|
+
missing: changes.missing || base.missing || [],
|
|
262
|
+
open_questions: changes.open_questions || base.open_questions || [],
|
|
263
|
+
nodes,
|
|
264
|
+
proposed_by: by,
|
|
265
|
+
};
|
|
266
|
+
// 草案落盘在独立文件,绝不覆盖 active 的 curriculum.json
|
|
267
|
+
await validateCurriculum(next);
|
|
268
|
+
await writeJsonVersioned(subjectFile(id, 'curriculum.draft.json'), next, 'curriculum-draft');
|
|
269
|
+
return next;
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
export async function loadDraft(subjectId) {
|
|
273
|
+
return readJson(subjectFile(assertSafeId(subjectId, 'subject_id'), 'curriculum.draft.json'), null);
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
// 差异说明(给人看的文本,不自动应用)
|
|
277
|
+
export function describeDiff(diff) {
|
|
278
|
+
const lines = [];
|
|
279
|
+
if (diff.added.length) lines.push(`新增节点 ${diff.added.length} 个:` + diff.added.map((x) => `${x.id}(${x.title})`).join('、'));
|
|
280
|
+
if (diff.removed.length) lines.push(`移除节点 ${diff.removed.length} 个:` + diff.removed.map((x) => `${x.id}(${x.title})`).join('、'));
|
|
281
|
+
if (diff.changed.length) lines.push(`修改节点 ${diff.changed.length} 个:` + diff.changed.map((x) => `${x.id}[${x.fields.join(',')}]`).join('、'));
|
|
282
|
+
if (diff.materials_changed.length) lines.push(`材料变化 ${diff.materials_changed.length} 项:` + diff.materials_changed.map((x) => `${x.path}(${x.kind})`).join('、'));
|
|
283
|
+
if (!lines.length) lines.push('无实质变化。');
|
|
284
|
+
return lines.join('\n');
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
async function initProgress(id, cur) {
|
|
288
|
+
const { initProgressFor } = await import('./progress.mjs');
|
|
289
|
+
return initProgressFor(id, cur);
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
export { exists, path, safeId };
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
// 模块交接(handoff):短小、结构化,取代「聊天全文进入下一模块」。
|
|
2
|
+
//
|
|
3
|
+
// 方案 §4-D:模块结束保存 完成/未完成项、掌握依据、未解问题、当前错因、下一节点及资料引用。
|
|
4
|
+
// 硬规则:mastery_evidence 必须指向真实存在的答卷文件;没有证据不能声称掌握。
|
|
5
|
+
import path from 'node:path';
|
|
6
|
+
import { checkOrThrow } from './schemas.mjs';
|
|
7
|
+
import {
|
|
8
|
+
subjectDir, readJson, writeJsonVersioned, ensureDataRoot, assertSafeId, assertNodeId, nowIso,
|
|
9
|
+
WORKSPACE, exists, listDirSafe, checkSourceRef,
|
|
10
|
+
} from './store.mjs';
|
|
11
|
+
|
|
12
|
+
export const HANDOFF_DIR = 'handoffs';
|
|
13
|
+
|
|
14
|
+
export async function saveHandoff(subjectId, h) {
|
|
15
|
+
const id = assertSafeId(subjectId, 'subject_id');
|
|
16
|
+
const nid = assertNodeId(h.node_id);
|
|
17
|
+
const next = {
|
|
18
|
+
schema_version: 1,
|
|
19
|
+
subject_id: id,
|
|
20
|
+
node_id: nid,
|
|
21
|
+
created_at: h.created_at || nowIso(),
|
|
22
|
+
curriculum_revision: Number(h.curriculum_revision || 1),
|
|
23
|
+
completed: (h.completed || []).map(String),
|
|
24
|
+
unfinished: (h.unfinished || []).map(String),
|
|
25
|
+
mastery_evidence: (h.mastery_evidence || []).map(String),
|
|
26
|
+
open_questions: (h.open_questions || []).map(String),
|
|
27
|
+
misconceptions: (h.misconceptions || []).map(String),
|
|
28
|
+
next_node: h.next_node ? assertNodeId(h.next_node) : null,
|
|
29
|
+
material_refs: [],
|
|
30
|
+
session: {
|
|
31
|
+
isolation: h.session && h.session.isolation ? h.session.isolation : 'unknown',
|
|
32
|
+
...(h.session && h.session.note ? { note: String(h.session.note) } : {}),
|
|
33
|
+
...(h.session && h.session.dsn_session_id ? { dsn_session_id: String(h.session.dsn_session_id) } : {}),
|
|
34
|
+
},
|
|
35
|
+
};
|
|
36
|
+
// 证据必须真实存在,否则降级为「未验证」而不是静默接受
|
|
37
|
+
const missingEvidence = [];
|
|
38
|
+
for (const ev of next.mastery_evidence) {
|
|
39
|
+
const abs = path.resolve(WORKSPACE, ev);
|
|
40
|
+
if (!abs.startsWith(WORKSPACE + path.sep) || !(await exists(abs))) missingEvidence.push(ev);
|
|
41
|
+
}
|
|
42
|
+
if (missingEvidence.length) {
|
|
43
|
+
const e = new Error(`mastery_evidence 指向不存在的文件,不能作为掌握依据:\n - ` + missingEvidence.join('\n - '));
|
|
44
|
+
e.code = 'BAD_EVIDENCE';
|
|
45
|
+
e.errors = missingEvidence;
|
|
46
|
+
throw e;
|
|
47
|
+
}
|
|
48
|
+
for (const r of h.material_refs || []) {
|
|
49
|
+
next.material_refs.push(await checkSourceRef(r));
|
|
50
|
+
}
|
|
51
|
+
await checkOrThrow('handoff', next);
|
|
52
|
+
const file = path.join(subjectDir(id), HANDOFF_DIR, `${nid}__${next.created_at.replace(/[:.]/g, '-')}.json`);
|
|
53
|
+
await writeJsonVersioned(file, next, 'handoffs');
|
|
54
|
+
return next;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export async function listHandoffs(subjectId) {
|
|
58
|
+
const dir = path.join(subjectDir(assertSafeId(subjectId, 'subject_id')), HANDOFF_DIR);
|
|
59
|
+
const out = [];
|
|
60
|
+
for (const f of await listDirSafe(dir)) {
|
|
61
|
+
if (!f.isFile() || !f.name.endsWith('.json')) continue;
|
|
62
|
+
const h = await readJson(path.join(dir, f.name), null);
|
|
63
|
+
if (h) out.push({ file: f.name, ...h });
|
|
64
|
+
}
|
|
65
|
+
out.sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)));
|
|
66
|
+
return out;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
// 最近一次交接(新模块开场恢复用):只取约定字段
|
|
70
|
+
export async function latestHandoff(subjectId, nodeId = null) {
|
|
71
|
+
const all = await listHandoffs(subjectId);
|
|
72
|
+
return all.find((h) => !nodeId || h.node_id === nodeId) || null;
|
|
73
|
+
}
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
// 极简 JSON Schema (draft-07 子集) 校验器:零依赖,够学习助手的数据契约用。
|
|
2
|
+
//
|
|
3
|
+
// 支持的关键字:
|
|
4
|
+
// type(字符串或数组) / properties / required / additionalProperties(bool 或 schema)
|
|
5
|
+
// items(单个 schema) / enum / const / minimum / maximum
|
|
6
|
+
// minLength / maxLength / pattern / minItems / maxItems / uniqueItems
|
|
7
|
+
// oneOf / anyOf / allOf / not / $ref(仅本地 #/definitions、#/$defs)
|
|
8
|
+
//
|
|
9
|
+
// 明确**不支持**(遇到会静默忽略,不要依赖):
|
|
10
|
+
// if/then/else、format、patternProperties、dependentRequired、$ref 到外部文件
|
|
11
|
+
//
|
|
12
|
+
// 校验通过返回 [],否则返回错误字符串数组,每条形如 `$.nodes[0].id: 必须匹配 pattern ...`。
|
|
13
|
+
|
|
14
|
+
const typeOf = (v) => {
|
|
15
|
+
if (v === null) return 'null';
|
|
16
|
+
if (Array.isArray(v)) return 'array';
|
|
17
|
+
if (typeof v === 'number') return Number.isInteger(v) ? 'integer' : 'number';
|
|
18
|
+
return typeof v; // string | boolean | object | undefined
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
const matchesType = (v, t) => {
|
|
22
|
+
const a = typeOf(v);
|
|
23
|
+
if (t === 'number') return a === 'number' || a === 'integer';
|
|
24
|
+
if (t === 'integer') return a === 'integer';
|
|
25
|
+
if (t === 'boolean') return a === 'boolean';
|
|
26
|
+
if (t === 'null') return a === 'null';
|
|
27
|
+
return a === t;
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
const refParts = (ref) =>
|
|
31
|
+
ref
|
|
32
|
+
.slice(1)
|
|
33
|
+
.split('/')
|
|
34
|
+
.filter(Boolean)
|
|
35
|
+
.map((p) => p.replace(/~1/g, '/').replace(/~0/g, '~'));
|
|
36
|
+
|
|
37
|
+
const deref = (schema, root) => {
|
|
38
|
+
let s = schema;
|
|
39
|
+
let guard = 0;
|
|
40
|
+
while (s && typeof s.$ref === 'string') {
|
|
41
|
+
if (++guard > 20) throw new Error('$ref 循环:' + schema.$ref);
|
|
42
|
+
if (!s.$ref.startsWith('#')) throw new Error('只支持本地 $ref:' + s.$ref);
|
|
43
|
+
let cur = root;
|
|
44
|
+
for (const p of refParts(s.$ref)) cur = cur == null ? undefined : cur[p];
|
|
45
|
+
if (cur === undefined) throw new Error('$ref 解析不到:' + s.$ref);
|
|
46
|
+
s = cur;
|
|
47
|
+
}
|
|
48
|
+
return s;
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
const stable = (v) => {
|
|
52
|
+
try {
|
|
53
|
+
return JSON.stringify(v, (k, x) => {
|
|
54
|
+
if (x && typeof x === 'object' && !Array.isArray(x)) {
|
|
55
|
+
return Object.fromEntries(Object.keys(x).sort().map((kk) => [kk, x[kk]]));
|
|
56
|
+
}
|
|
57
|
+
return x;
|
|
58
|
+
});
|
|
59
|
+
} catch {
|
|
60
|
+
return String(v);
|
|
61
|
+
}
|
|
62
|
+
};
|
|
63
|
+
|
|
64
|
+
export function validate(schema, data, root = schema, at = '$', errs = []) {
|
|
65
|
+
let s;
|
|
66
|
+
try {
|
|
67
|
+
s = deref(schema, root);
|
|
68
|
+
} catch (e) {
|
|
69
|
+
errs.push(`${at}: schema 本身有问题(${e.message})`);
|
|
70
|
+
return errs;
|
|
71
|
+
}
|
|
72
|
+
if (!s || typeof s !== 'object') return errs;
|
|
73
|
+
|
|
74
|
+
const bad = (msg) => errs.push(`${at}: ${msg}`);
|
|
75
|
+
|
|
76
|
+
if (s.type !== undefined) {
|
|
77
|
+
const types = Array.isArray(s.type) ? s.type : [s.type];
|
|
78
|
+
if (!types.some((t) => matchesType(data, t))) {
|
|
79
|
+
bad(`类型应为 ${types.join('|')},实际是 ${typeOf(data)}`);
|
|
80
|
+
return errs; // 类型都不对,后面的检查没有意义
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
if (s.const !== undefined && stable(data) !== stable(s.const)) {
|
|
85
|
+
bad(`必须是 ${stable(s.const)}`);
|
|
86
|
+
}
|
|
87
|
+
if (Array.isArray(s.enum) && !s.enum.some((e) => stable(e) === stable(data))) {
|
|
88
|
+
bad(`取值必须是 [${s.enum.map((e) => stable(e)).join(', ')}] 之一,实际是 ${stable(data)}`);
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
if (typeof data === 'string') {
|
|
92
|
+
if (s.minLength !== undefined && data.length < s.minLength) bad(`长度至少 ${s.minLength}`);
|
|
93
|
+
if (s.maxLength !== undefined && data.length > s.maxLength) bad(`长度最多 ${s.maxLength}`);
|
|
94
|
+
if (s.pattern !== undefined && !new RegExp(s.pattern).test(data)) {
|
|
95
|
+
bad(`必须匹配 pattern ${s.pattern}(实际:${JSON.stringify(data)})`);
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
if (typeof data === 'number') {
|
|
100
|
+
if (s.minimum !== undefined && data < s.minimum) bad(`不能小于 ${s.minimum}`);
|
|
101
|
+
if (s.maximum !== undefined && data > s.maximum) bad(`不能大于 ${s.maximum}`);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
if (Array.isArray(data)) {
|
|
105
|
+
if (s.minItems !== undefined && data.length < s.minItems) bad(`至少 ${s.minItems} 项`);
|
|
106
|
+
if (s.maxItems !== undefined && data.length > s.maxItems) bad(`最多 ${s.maxItems} 项`);
|
|
107
|
+
if (s.uniqueItems === true) {
|
|
108
|
+
const seen = new Set();
|
|
109
|
+
data.forEach((x, i) => {
|
|
110
|
+
const k = stable(x);
|
|
111
|
+
if (seen.has(k)) bad(`第 ${i + 1} 项与前面重复:${k}`);
|
|
112
|
+
else seen.add(k);
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
if (s.items && typeof s.items === 'object') {
|
|
116
|
+
data.forEach((x, i) => validate(s.items, x, root, `${at}[${i}]`, errs));
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
if (data && typeof data === 'object' && !Array.isArray(data)) {
|
|
121
|
+
for (const r of s.required || []) {
|
|
122
|
+
if (data[r] === undefined) bad(`缺字段 ${r}`);
|
|
123
|
+
}
|
|
124
|
+
const props = s.properties || {};
|
|
125
|
+
for (const [k, v] of Object.entries(data)) {
|
|
126
|
+
if (props[k] !== undefined) {
|
|
127
|
+
validate(props[k], v, root, `${at}.${k}`, errs);
|
|
128
|
+
} else if (s.additionalProperties === false) {
|
|
129
|
+
bad(`不认识的字段 ${k}(schema 未声明,additionalProperties=false)`);
|
|
130
|
+
} else if (s.additionalProperties && typeof s.additionalProperties === 'object') {
|
|
131
|
+
validate(s.additionalProperties, v, root, `${at}.${k}`, errs);
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
const sub = (kw, fn) => {
|
|
137
|
+
if (s[kw] === undefined) return;
|
|
138
|
+
const list = Array.isArray(s[kw]) ? s[kw] : [s[kw]];
|
|
139
|
+
const hits = list.map((sub_schema) => {
|
|
140
|
+
const e = [];
|
|
141
|
+
validate(sub_schema, data, root, at, e);
|
|
142
|
+
return e;
|
|
143
|
+
});
|
|
144
|
+
fn(hits);
|
|
145
|
+
};
|
|
146
|
+
sub('allOf', (hits) => hits.forEach((h) => errs.push(...h)));
|
|
147
|
+
sub('anyOf', (hits) => {
|
|
148
|
+
if (!hits.some((h) => h.length === 0)) bad('anyOf:没有任何一个分支通过');
|
|
149
|
+
});
|
|
150
|
+
sub('oneOf', (hits) => {
|
|
151
|
+
const n = hits.filter((h) => h.length === 0).length;
|
|
152
|
+
if (n !== 1) bad(`oneOf:需要恰好命中 1 个分支,实际命中 ${n} 个`);
|
|
153
|
+
});
|
|
154
|
+
if (s.not !== undefined) {
|
|
155
|
+
const e = [];
|
|
156
|
+
validate(s.not, data, root, at, e);
|
|
157
|
+
if (e.length === 0) bad('not:命中了不该命中的分支');
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
return errs;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
export function validateOrThrow(schema, data, label = 'data') {
|
|
164
|
+
const errs = validate(schema, data);
|
|
165
|
+
if (errs.length) {
|
|
166
|
+
const e = new Error(`${label} 不符合 schema:\n - ` + errs.join('\n - '));
|
|
167
|
+
e.errors = errs;
|
|
168
|
+
throw e;
|
|
169
|
+
}
|
|
170
|
+
return true;
|
|
171
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
// 节点 ↔ 练习/答卷 映射(node-practice-map)。
|
|
2
|
+
//
|
|
3
|
+
// 为什么单独一份:题库 schema 不动(方案 §3 明确「不要擅改题库 schema」),
|
|
4
|
+
// 映射放在学习数据目录里,subject + stable_node_id + practice_id/attempt_ref 三元组显式登记。
|
|
5
|
+
import path from 'node:path';
|
|
6
|
+
import { checkOrThrow } from './schemas.mjs';
|
|
7
|
+
import {
|
|
8
|
+
subjectFile, readJson, writeJsonVersioned, ensureDataRoot, assertSafeId, assertNodeId, nowIso,
|
|
9
|
+
PRACTICE_DIR, resolveInside, listDirSafe,
|
|
10
|
+
} from './store.mjs';
|
|
11
|
+
|
|
12
|
+
export const MAPPING_FILE = 'mapping.json';
|
|
13
|
+
|
|
14
|
+
export async function loadMapping(subjectId) {
|
|
15
|
+
const id = assertSafeId(subjectId, 'subject_id');
|
|
16
|
+
return readJson(subjectFile(id, MAPPING_FILE), {
|
|
17
|
+
schema_version: 1, subject_id: id, curriculum_revision: 1, updated_at: nowIso(), links: [],
|
|
18
|
+
});
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
export async function saveMapping(subjectId, mapping) {
|
|
22
|
+
const id = assertSafeId(subjectId, 'subject_id');
|
|
23
|
+
const next = { ...mapping, schema_version: 1, subject_id: id, updated_at: nowIso() };
|
|
24
|
+
await checkOrThrow('node-practice-map', next);
|
|
25
|
+
await writeJsonVersioned(subjectFile(id, MAPPING_FILE), next, 'mapping');
|
|
26
|
+
return next;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
// 登记一条映射。practice_id 允许形如「复变函数/复数的乘幂与方根-03」,course 为科目名。
|
|
30
|
+
export async function link(subjectId, { node_id, practice_id, course, note = '' }) {
|
|
31
|
+
const id = assertSafeId(subjectId, 'subject_id');
|
|
32
|
+
const nid = assertNodeId(node_id);
|
|
33
|
+
const pid = String(practice_id || '').trim();
|
|
34
|
+
const c = String(course || '').trim();
|
|
35
|
+
if (!pid || !c) throw new Error('link 需要 practice_id 与 course');
|
|
36
|
+
const m = await loadMapping(id);
|
|
37
|
+
if (m.links.some((l) => l.node_id === nid && l.practice_id === pid && l.course === c)) return m;
|
|
38
|
+
const next = {
|
|
39
|
+
...m,
|
|
40
|
+
links: [...m.links, { node_id: nid, practice_id: pid, course: c, ...(note ? { note } : {}), created_at: nowIso() }],
|
|
41
|
+
};
|
|
42
|
+
return saveMapping(id, next);
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export async function unlink(subjectId, { node_id, practice_id, course }) {
|
|
46
|
+
const id = assertSafeId(subjectId, 'subject_id');
|
|
47
|
+
const m = await loadMapping(id);
|
|
48
|
+
const next = {
|
|
49
|
+
...m,
|
|
50
|
+
links: m.links.filter((l) => !(l.node_id === node_id && l.practice_id === practice_id && l.course === course)),
|
|
51
|
+
};
|
|
52
|
+
return saveMapping(id, next);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
export function linksForNode(mapping, nodeId) {
|
|
56
|
+
return (mapping.links || []).filter((l) => l.node_id === nodeId);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/* ---------- 从现有练习台数据读取答卷(只读) ---------- */
|
|
60
|
+
|
|
61
|
+
const RECORDS = path.join(PRACTICE_DIR, '_记录');
|
|
62
|
+
const safe = (s) => String(s || '').replace(/[\\/:*?"<>|]/g, '_').slice(0, 80);
|
|
63
|
+
|
|
64
|
+
// 列出某科目某练习的答卷(与 服务.mjs 的 recordsFor 同语义:文件名前缀 <id>__)
|
|
65
|
+
export async function recordsFor(course, practiceId) {
|
|
66
|
+
const dir = resolveInside(RECORDS, safe(course), 'course');
|
|
67
|
+
const out = [];
|
|
68
|
+
for (const f of await listDirSafe(dir)) {
|
|
69
|
+
if (!f.isFile() || !f.name.endsWith('.json')) continue;
|
|
70
|
+
if (!f.name.startsWith(safe(practiceId) + '__')) continue;
|
|
71
|
+
const rec = await readJson(path.join(dir, f.name), null);
|
|
72
|
+
if (!rec) continue;
|
|
73
|
+
out.push({ file: f.name, ref: `练习台/_记录/${safe(course)}/${f.name}`, ...rec });
|
|
74
|
+
}
|
|
75
|
+
out.sort((a, b) => String(b.at).localeCompare(String(a.at)));
|
|
76
|
+
return out;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// 某节点关联的全部答卷(跨练习),供批改与掌握判定取证据
|
|
80
|
+
export async function attemptsForNode(subjectId, nodeId) {
|
|
81
|
+
const m = await loadMapping(subjectId);
|
|
82
|
+
const out = [];
|
|
83
|
+
for (const l of linksForNode(m, nodeId)) {
|
|
84
|
+
for (const r of await recordsFor(l.course, l.practice_id)) {
|
|
85
|
+
out.push({ ...r, node_id: nodeId, practice_id: l.practice_id, course: l.course });
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
out.sort((a, b) => String(b.at).localeCompare(String(a.at)));
|
|
89
|
+
return out;
|
|
90
|
+
}
|