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,247 @@
|
|
|
1
|
+
// 学习助手数据层:路径解析、安全 ID、原子写入、版本历史、来源引用校验。
|
|
2
|
+
//
|
|
3
|
+
// 插件参数化版(相对学习区原版只有路径来源的改动):
|
|
4
|
+
// - 工作区根改读 LEARN_WORKSPACE(缺省退回旧推导链,传统布局零改动)
|
|
5
|
+
// - 练习台目录改读 LEARN_PRACTICE_DIR(缺省 = <工作区>/练习台)
|
|
6
|
+
// - 数据根优先级:LEARN_DATA_ROOT(自检/测试)> LEARN_DATA_SUBDIR(相对工作区)> 默认 学习助手数据
|
|
7
|
+
// 其余行为与原版一致:只写数据根、不写台账、原子写 + _history 版本备份。
|
|
8
|
+
import fs from 'node:fs';
|
|
9
|
+
import fsp from 'node:fs/promises';
|
|
10
|
+
import path from 'node:path';
|
|
11
|
+
import { fileURLToPath } from 'node:url';
|
|
12
|
+
|
|
13
|
+
const HERE = path.dirname(fileURLToPath(import.meta.url)); // src/practice/learn
|
|
14
|
+
|
|
15
|
+
function resolveWorkspace() {
|
|
16
|
+
if (process.env.LEARN_WORKSPACE && path.isAbsolute(process.env.LEARN_WORKSPACE)) {
|
|
17
|
+
return path.resolve(process.env.LEARN_WORKSPACE);
|
|
18
|
+
}
|
|
19
|
+
// 旧推导链:learn/ 直接住在 <工作区>/练习台/learn 下时成立(传统布局);
|
|
20
|
+
// 插件布局(src/practice/learn)下必须显式提供 LEARN_WORKSPACE。
|
|
21
|
+
return path.resolve(HERE, '../../../');
|
|
22
|
+
}
|
|
23
|
+
export const WORKSPACE = resolveWorkspace();
|
|
24
|
+
|
|
25
|
+
export const PRACTICE_DIR = process.env.LEARN_PRACTICE_DIR && path.isAbsolute(process.env.LEARN_PRACTICE_DIR)
|
|
26
|
+
? path.resolve(process.env.LEARN_PRACTICE_DIR)
|
|
27
|
+
: path.join(WORKSPACE, '练习台');
|
|
28
|
+
|
|
29
|
+
export const DATA_ROOT = path.resolve(
|
|
30
|
+
process.env.LEARN_DATA_ROOT
|
|
31
|
+
|| path.join(WORKSPACE, process.env.LEARN_DATA_SUBDIR || '学习助手数据'),
|
|
32
|
+
);
|
|
33
|
+
|
|
34
|
+
export const SUBJECTS_DIR = path.join(DATA_ROOT, 'subjects');
|
|
35
|
+
export const PREFS_FILE = path.join(DATA_ROOT, '_prefs.json');
|
|
36
|
+
|
|
37
|
+
// 允许被 source_refs 引用的根(白名单)。其余路径一律拒绝,避免把任意文件读进上下文。
|
|
38
|
+
// 与原版同姿态:只放行「知识整理」与练习台的数据子目录 + 数据根本身。
|
|
39
|
+
export const ALLOWED_SOURCE_ROOTS = [
|
|
40
|
+
path.join(WORKSPACE, '知识整理'),
|
|
41
|
+
path.join(PRACTICE_DIR, '_题库'),
|
|
42
|
+
path.join(PRACTICE_DIR, '_记录'),
|
|
43
|
+
path.join(PRACTICE_DIR, '_笔迹'),
|
|
44
|
+
path.join(PRACTICE_DIR, '_收件箱'),
|
|
45
|
+
DATA_ROOT,
|
|
46
|
+
];
|
|
47
|
+
|
|
48
|
+
/* ---------- 安全 ID ---------- */
|
|
49
|
+
|
|
50
|
+
// 科目 ID:禁止路径分隔符与 Windows 保留字符,避免目录穿越
|
|
51
|
+
export function safeId(s, max = 40) {
|
|
52
|
+
const cleaned = String(s ?? '').trim().replace(/[\\/:*?"<>|\x00-\x1f]/g, '_');
|
|
53
|
+
return cleaned.slice(0, max);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
export function assertSafeId(s, label = 'id') {
|
|
57
|
+
const id = safeId(s);
|
|
58
|
+
if (!id || id !== String(s ?? '').trim()) {
|
|
59
|
+
const e = new Error(`${label} 非法:${JSON.stringify(s)}(不允许空、路径分隔符、保留字符或首尾空格)`);
|
|
60
|
+
e.code = 'BAD_ID';
|
|
61
|
+
throw e;
|
|
62
|
+
}
|
|
63
|
+
return id;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
// 节点 ID:只允许 [A-Za-z0-9._-],与 schema 的 pattern 一致
|
|
67
|
+
export function assertNodeId(s) {
|
|
68
|
+
const id = String(s ?? '').trim();
|
|
69
|
+
if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(id)) {
|
|
70
|
+
const e = new Error(`节点 ID 非法:${JSON.stringify(s)}(需匹配 ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$)`);
|
|
71
|
+
e.code = 'BAD_NODE_ID';
|
|
72
|
+
throw e;
|
|
73
|
+
}
|
|
74
|
+
return id;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// 把一个相对/绝对路径解析到受控根内;越界抛错
|
|
78
|
+
export function resolveInside(root, rel, label = 'path') {
|
|
79
|
+
const abs = path.resolve(root, rel);
|
|
80
|
+
const r = path.resolve(root);
|
|
81
|
+
if (abs !== r && !abs.startsWith(r + path.sep)) {
|
|
82
|
+
const e = new Error(`${label} 越界:${rel} 解析为 ${abs},不在 ${r} 内`);
|
|
83
|
+
e.code = 'PATH_ESCAPE';
|
|
84
|
+
throw e;
|
|
85
|
+
}
|
|
86
|
+
return abs;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/* ---------- 来源引用 ---------- */
|
|
90
|
+
|
|
91
|
+
// source_refs 的 path 一律相对工作区根书写(如 知识整理/复变函数/xx.md)
|
|
92
|
+
export function resolveSourceRef(refPath) {
|
|
93
|
+
const raw = String(refPath ?? '').trim();
|
|
94
|
+
if (!raw) {
|
|
95
|
+
const e = new Error('source_refs.path 为空');
|
|
96
|
+
e.code = 'BAD_SOURCE_REF';
|
|
97
|
+
throw e;
|
|
98
|
+
}
|
|
99
|
+
if (path.isAbsolute(raw)) {
|
|
100
|
+
const e = new Error(`source_refs.path 必须是工作区相对路径,不接受绝对路径:${raw}`);
|
|
101
|
+
e.code = 'BAD_SOURCE_REF';
|
|
102
|
+
throw e;
|
|
103
|
+
}
|
|
104
|
+
const abs = path.resolve(WORKSPACE, raw);
|
|
105
|
+
if (!abs.startsWith(WORKSPACE + path.sep)) {
|
|
106
|
+
const e = new Error(`source_refs.path 越界:${raw}`);
|
|
107
|
+
e.code = 'PATH_ESCAPE';
|
|
108
|
+
throw e;
|
|
109
|
+
}
|
|
110
|
+
const allowed = ALLOWED_SOURCE_ROOTS.some((r) => abs === r || abs.startsWith(r + path.sep));
|
|
111
|
+
if (!allowed) {
|
|
112
|
+
const e = new Error(`source_refs.path 不在允许的资料来源根内:${raw}`);
|
|
113
|
+
e.code = 'PATH_NOT_ALLOWED';
|
|
114
|
+
throw e;
|
|
115
|
+
}
|
|
116
|
+
return abs;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
// 全局极短偏好(/api/learn/prefs 提供)
|
|
120
|
+
export async function loadPrefs() {
|
|
121
|
+
return readJson(PREFS_FILE, {
|
|
122
|
+
schema_version: 1, language: 'zh-CN',
|
|
123
|
+
explanation_style: '先直观例子再完整例题,逐步说明每步理由。',
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
// 校验并补全一条 source_ref:真实存在则带 size/mtime,不存在标 missing(不编造)
|
|
128
|
+
export async function checkSourceRef(ref) {
|
|
129
|
+
const abs = resolveSourceRef(ref.path);
|
|
130
|
+
const out = { path: String(ref.path).replace(/\\/g, '/'), location: String(ref.location ?? '').trim() };
|
|
131
|
+
if (!out.location) {
|
|
132
|
+
const e = new Error(`source_refs.location 为空(必须有标题/页码/章节等可核对位置):${out.path}`);
|
|
133
|
+
e.code = 'BAD_SOURCE_REF';
|
|
134
|
+
throw e;
|
|
135
|
+
}
|
|
136
|
+
try {
|
|
137
|
+
const st = await fsp.stat(abs);
|
|
138
|
+
if (!st.isFile()) throw new Error('不是文件');
|
|
139
|
+
out.missing = false;
|
|
140
|
+
out.size = st.size;
|
|
141
|
+
out.mtime_ms = Math.round(st.mtimeMs);
|
|
142
|
+
} catch {
|
|
143
|
+
out.missing = true;
|
|
144
|
+
out.size = null;
|
|
145
|
+
out.mtime_ms = null;
|
|
146
|
+
}
|
|
147
|
+
return out;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/* ---------- 原子写入 + 版本历史 ---------- */
|
|
151
|
+
|
|
152
|
+
const stamp = (d = new Date()) => {
|
|
153
|
+
const p = (n) => String(n).padStart(2, '0');
|
|
154
|
+
return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}${String(d.getMilliseconds()).padStart(3, '0')}`;
|
|
155
|
+
};
|
|
156
|
+
|
|
157
|
+
export async function readJson(file, fallback = null) {
|
|
158
|
+
try {
|
|
159
|
+
return JSON.parse(await fsp.readFile(file, 'utf8'));
|
|
160
|
+
} catch (e) {
|
|
161
|
+
if (e && e.code === 'ENOENT') return fallback;
|
|
162
|
+
if (fallback !== null && e instanceof SyntaxError) return fallback;
|
|
163
|
+
throw e;
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
export async function exists(p) {
|
|
168
|
+
try { await fsp.stat(p); return true; } catch { return false; }
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
// 原子写:先写同目录临时文件再 rename(同分区 rename 是原子的),失败不留半截文件
|
|
172
|
+
export async function atomicWrite(file, text) {
|
|
173
|
+
await fsp.mkdir(path.dirname(file), { recursive: true });
|
|
174
|
+
const tmp = path.join(path.dirname(file), `.${path.basename(file)}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
|
|
175
|
+
try {
|
|
176
|
+
await fsp.writeFile(tmp, text, 'utf8');
|
|
177
|
+
await fsp.rename(tmp, file);
|
|
178
|
+
} catch (e) {
|
|
179
|
+
try { await fsp.unlink(tmp); } catch { /* 清理失败不掩盖原错误 */ }
|
|
180
|
+
throw e;
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
export async function writeJson(file, obj) {
|
|
185
|
+
await atomicWrite(file, JSON.stringify(obj, null, 2) + '\n');
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
// 覆盖前把旧版本存进 <DATA_ROOT>/_history/<kind>/,保留最近 keep 份;
|
|
189
|
+
// 这是「旧版本与成绩不被抹除」的兜底,也是没有 git 时的回滚手段。
|
|
190
|
+
export async function backupBeforeWrite(file, kind, keep = 60) {
|
|
191
|
+
if (!(await exists(file))) return null;
|
|
192
|
+
const dir = path.join(DATA_ROOT, '_history', kind);
|
|
193
|
+
await fsp.mkdir(dir, { recursive: true });
|
|
194
|
+
const dest = path.join(dir, `${stamp()}-${path.basename(file)}`);
|
|
195
|
+
await fsp.copyFile(file, dest);
|
|
196
|
+
const all = (await fsp.readdir(dir)).filter((f) => f.endsWith('.json')).sort();
|
|
197
|
+
for (const f of all.slice(0, Math.max(0, all.length - keep))) {
|
|
198
|
+
try { await fsp.unlink(path.join(dir, f)); } catch { /* 清理失败无妨 */ }
|
|
199
|
+
}
|
|
200
|
+
return dest;
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
// 带备份的写:所有课程数据的唯一写入口
|
|
204
|
+
export async function writeJsonVersioned(file, obj, kind) {
|
|
205
|
+
await backupBeforeWrite(file, kind);
|
|
206
|
+
await writeJson(file, obj);
|
|
207
|
+
return obj;
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/* ---------- 科目目录布局 ---------- */
|
|
211
|
+
|
|
212
|
+
export const subjectDir = (subjectId) => resolveInside(SUBJECTS_DIR, assertSafeId(subjectId, 'subject_id'), 'subject_id');
|
|
213
|
+
export const subjectFile = (subjectId, name) => resolveInside(subjectDir(subjectId), name, name);
|
|
214
|
+
|
|
215
|
+
export async function listSubjects() {
|
|
216
|
+
let ents = [];
|
|
217
|
+
try { ents = await fsp.readdir(SUBJECTS_DIR, { withFileTypes: true }); } catch { return []; }
|
|
218
|
+
const out = [];
|
|
219
|
+
for (const e of ents) {
|
|
220
|
+
if (!e.isDirectory() || e.name.startsWith('_')) continue;
|
|
221
|
+
const dir = path.join(SUBJECTS_DIR, e.name);
|
|
222
|
+
const meta = await readJson(path.join(dir, 'meta.json'), null);
|
|
223
|
+
const curriculum = await readJson(path.join(dir, 'curriculum.json'), null);
|
|
224
|
+
const progress = await readJson(path.join(dir, 'progress.json'), null);
|
|
225
|
+
out.push({ subject_id: e.name, dir, meta, curriculum, progress });
|
|
226
|
+
}
|
|
227
|
+
out.sort((a, b) => a.subject_id.localeCompare(b.subject_id));
|
|
228
|
+
return out;
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
export async function ensureDataRoot() {
|
|
232
|
+
await fsp.mkdir(SUBJECTS_DIR, { recursive: true });
|
|
233
|
+
if (!(await exists(PREFS_FILE))) {
|
|
234
|
+
await writeJson(PREFS_FILE, {
|
|
235
|
+
schema_version: 1,
|
|
236
|
+
language: 'zh-CN',
|
|
237
|
+
explanation_style: '先直观例子再完整例题,逐步说明每步理由;公式用 $…$。',
|
|
238
|
+
note: '全局极短偏好(方案 §4-D 第 1 类数据)。不含任何课程进度。',
|
|
239
|
+
});
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
export const nowIso = () => new Date().toISOString();
|
|
244
|
+
export { stamp };
|
|
245
|
+
export const readText = (f) => fsp.readFile(f, 'utf8');
|
|
246
|
+
export const listDirSafe = async (p) => { try { return await fsp.readdir(p, { withFileTypes: true }); } catch { return []; } };
|
|
247
|
+
export { fs };
|