dsh-shared-kb 0.0.0-stage → 1.0.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.
@@ -0,0 +1,906 @@
1
+ /**
2
+ * 知识库 CRUD 与文档写入。
3
+ *
4
+ * 目录布局(每个库一个独立子文件夹,用户可以直接在资源管理器里看/拷):
5
+ *
6
+ * <kbRoot>/
7
+ * .hub/
8
+ * hub.json 根标记 + schema 版本
9
+ * machines/<machineId>.json 机器心跳(诊断「谁在用」)
10
+ * <kbName>/
11
+ * kb.json 库元数据(描述、创建者、默认检索配置)
12
+ * manifest.json 文档清单(rev 单调递增,CAS 写入)
13
+ * events.jsonl 操作审计(只增)
14
+ * schema.md 本库维护规范(人写,给模型看的入库约定)
15
+ * index.md 自动生成的目录
16
+ * log.md 自动生成的操作日志
17
+ * sources/ 原始资料(只读,导入后不修改)
18
+ * markdown/<docId>/
19
+ * meta.json 单篇元数据
20
+ * <docId>.md 合并版全文
21
+ * part-0001.md … 分块(大模型精读用)
22
+ * history/ 历史正文版本
23
+ * notes/ 笔记 / 编译页
24
+ * exports/ 导出产物
25
+ * snapshots/ 库级快照
26
+ * .locks/ 跨机器租约
27
+ *
28
+ * 索引不在这里(见 indexer/sqlite-index.js 顶部说明)。
29
+ */
30
+ import { createHash, randomBytes } from "node:crypto";
31
+ import { mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
32
+ import { writeFileAtomic } from "../core/atomic.js";
33
+ import { basename, join } from "node:path";
34
+ import { HubError, badRequest, notFound } from "../core/errors.js";
35
+ import { machineId } from "../core/hubconfig.js";
36
+ import { packBlocks } from "../parse/chunk.js";
37
+ import {
38
+ docDir,
39
+ docIdFor,
40
+ docMergedPath,
41
+ docMetaPath,
42
+ exportsDir,
43
+ kbMetaPath,
44
+ kbRootDir,
45
+ normalizeRelKey,
46
+ noteIdFor,
47
+ notesDir,
48
+ safeFileName,
49
+ sanitizeKbName,
50
+ snapshotsDir,
51
+ sourcesDir,
52
+ } from "../core/paths.js";
53
+ import {
54
+ appendEvent,
55
+ DEFAULT_HISTORY_KEEP,
56
+ readKbMeta,
57
+ readManifest,
58
+ withManifest,
59
+ writeKbMeta,
60
+ } from "./manifest.js";
61
+
62
+ /** 笔记正文会切成几块(与写入时同一套规则,保证 meta 与磁盘一致)。 */
63
+ function countPartsOfBody(body) {
64
+ const blocks = String(body)
65
+ .split(/\n{2,}/)
66
+ .map((text) => ({ text: text.trim(), heading: "", level: 0 }))
67
+ .filter((block) => block.text !== "");
68
+ return Math.max(
69
+ 1,
70
+ packBlocks(blocks.length > 0 ? blocks : [{ text: body, heading: "", level: 0 }], {
71
+ partChars: 1200,
72
+ overlapChars: 0,
73
+ }).length
74
+ );
75
+ }
76
+
77
+ const INDEX_MD = "index.md";
78
+ const LOG_MD = "log.md";
79
+ const SCHEMA_MD = "schema.md";
80
+
81
+ /** 建库:目录骨架 + kb.json + 空清单 + schema.md 模板。 */
82
+ export async function createKb(root, name, options = {}) {
83
+ const kb = sanitizeKbName(name);
84
+ const dir = kbRootDir(root, kb);
85
+ const existing = await readKbMeta(dir).catch(() => null);
86
+ if (existing) {
87
+ if (options.existOk !== false) return { name: kb, dir, created: false, meta: existing };
88
+ throw new HubError("KB_EXISTS", `知识库 ${kb} 已存在`, { status: 409 });
89
+ }
90
+ await mkdir(dir, { recursive: true });
91
+ await mkdir(sourcesDir(dir), { recursive: true });
92
+ await mkdir(join(dir, "markdown"), { recursive: true });
93
+ await mkdir(notesDir(dir), { recursive: true });
94
+ await mkdir(exportsDir(dir), { recursive: true });
95
+ await mkdir(snapshotsDir(dir), { recursive: true });
96
+
97
+ const meta = {
98
+ name: kb,
99
+ description: String(options.description ?? ""),
100
+ createdAt: new Date().toISOString(),
101
+ createdBy: { machine: machineId(), pid: process.pid },
102
+ owner: options.owner ?? null,
103
+ // 多人协作:写入策略默认「乐观并发」(CAS),可选 strict(写前必须拿到 rev)
104
+ writePolicy: options.writePolicy === "strict" ? "strict" : "cas",
105
+ // 检索默认值(可被单次调用覆盖)
106
+ retrieval: {
107
+ mode: "hybrid",
108
+ partChars: 1200,
109
+ overlapChars: 150,
110
+ },
111
+ // 只读库:除了管理员,任何人只能读
112
+ readOnly: options.readOnly === true,
113
+ };
114
+ await writeKbMeta(dir, meta);
115
+ await withManifest(dir, kb, (manifest) => {
116
+ manifest.name = kb;
117
+ manifest.createdAt = meta.createdAt;
118
+ return null;
119
+ });
120
+ await ensureSchemaDoc(dir, kb);
121
+ await refreshCatalog(dir, kb);
122
+ await appendEvent(dir, { action: "kb.create", kb, by: meta.createdBy });
123
+ return { name: kb, dir, created: true, meta };
124
+ }
125
+
126
+ /** schema.md:入库规范。缺失时补一份模板;已存在绝不覆盖(人写的)。 */
127
+ export async function ensureSchemaDoc(dir, kb) {
128
+ const path = join(dir, SCHEMA_MD);
129
+ try {
130
+ await stat(path);
131
+ return { created: false };
132
+ } catch {
133
+ /* 不存在,创建 */
134
+ }
135
+ const template = `# ${kb} · 维护规范
136
+
137
+ > 这份文件由插件在首次建库时生成,之后由**人**维护。任何导入/修订动作都不会覆盖它。
138
+
139
+ ## 收什么
140
+
141
+ - 收:有明确出处、会被反复引用的资料(标准、手册、规范、合同、教材)
142
+ - 不收:一次性草稿、纯聊天记录、无法追溯来源的二手转述
143
+
144
+ ## 怎么命名
145
+
146
+ - 标准类:\`标准号 名称\`(编号由插件自动识别,不要手工加括号年份)
147
+ - 手册类:\`产品名 型号 文档类型\`
148
+ - 笔记:用主题命名,同一主题再次写入=更新,不要另起「续」
149
+
150
+ ## 可信度口径
151
+
152
+ | 等级 | 含义 |
153
+ |---|---|
154
+ | high | 已发布现行版标准、正式出版教材 |
155
+ | medium | 企业文件、培训资料、报批稿 |
156
+ | low | 草案、征求意见稿、已废止版本 |
157
+
158
+ ## 引用格式
159
+
160
+ 结论后写(《标题》编号 第 N 条,第 N 页);多处用分号分隔。
161
+ `;
162
+ await writeFile(path, template, "utf8");
163
+ return { created: true };
164
+ }
165
+
166
+ export async function readSchemaDoc(dir) {
167
+ try {
168
+ return await readFile(join(dir, SCHEMA_MD), "utf8");
169
+ } catch {
170
+ return "";
171
+ }
172
+ }
173
+
174
+ /** 列出根目录下所有知识库(含文档数、字符量、最近更新)。 */
175
+ export async function listKbs(root) {
176
+ let names = [];
177
+ try {
178
+ names = await readdir(root, { withFileTypes: true });
179
+ } catch {
180
+ return [];
181
+ }
182
+ const out = [];
183
+ for (const entry of names) {
184
+ if (!entry.isDirectory()) continue;
185
+ if (entry.name.startsWith(".")) continue;
186
+ const dir = join(root, entry.name);
187
+ const meta = await readKbMeta(dir);
188
+ if (!meta) continue;
189
+ let manifest = null;
190
+ try {
191
+ manifest = await readManifest(dir, entry.name);
192
+ } catch (error) {
193
+ // 清单坏了也要能列出来(否则用户连「哪个库坏了」都不知道)
194
+ out.push({
195
+ name: entry.name,
196
+ dir,
197
+ broken: true,
198
+ error: String(error?.message ?? error),
199
+ description: meta.description ?? "",
200
+ });
201
+ continue;
202
+ }
203
+ out.push({
204
+ name: entry.name,
205
+ dir,
206
+ description: meta.description ?? "",
207
+ readOnly: meta.readOnly === true,
208
+ rev: manifest.rev,
209
+ docs: manifest.stats?.docs ?? 0,
210
+ allDocs: manifest.stats?.all ?? 0,
211
+ chars: manifest.stats?.chars ?? 0,
212
+ updatedAt: manifest.updatedAt,
213
+ updatedBy: manifest.updatedBy ?? null,
214
+ createdAt: meta.createdAt ?? manifest.createdAt,
215
+ });
216
+ }
217
+ out.sort((a, b) => String(a.name).localeCompare(String(b.name), "zh-Hans-CN"));
218
+ return out;
219
+ }
220
+
221
+ export async function requireKb(root, name) {
222
+ const kb = sanitizeKbName(name);
223
+ const dir = kbRootDir(root, kb);
224
+ const meta = await readKbMeta(dir);
225
+ if (!meta) throw notFound(`知识库 ${kb}`);
226
+ return { name: kb, dir, meta };
227
+ }
228
+
229
+ export async function updateKbMeta(root, name, patch) {
230
+ const { dir, meta } = await requireKb(root, name);
231
+ const next = { ...meta };
232
+ if (patch.description !== undefined) next.description = String(patch.description);
233
+ if (patch.readOnly !== undefined) next.readOnly = patch.readOnly === true;
234
+ if (patch.writePolicy !== undefined) next.writePolicy = patch.writePolicy === "strict" ? "strict" : "cas";
235
+ if (patch.retrieval !== undefined && patch.retrieval && typeof patch.retrieval === "object") {
236
+ next.retrieval = { ...(meta.retrieval ?? {}), ...patch.retrieval };
237
+ }
238
+ await writeKbMeta(dir, next);
239
+ await appendEvent(dir, { action: "kb.update", kb: name, patch });
240
+ return next;
241
+ }
242
+
243
+ export async function removeKb(root, name, { confirm } = {}) {
244
+ const { dir } = await requireKb(root, name);
245
+ if (confirm !== name) {
246
+ throw badRequest(`删除知识库需要 confirm 精确等于库名(${name})`, { expected: name });
247
+ }
248
+ await rm(dir, { recursive: true, force: true });
249
+ return { removed: true, name };
250
+ }
251
+
252
+ export async function renameKb(root, name, newName) {
253
+ const { dir, meta } = await requireKb(root, name);
254
+ const target = sanitizeKbName(newName);
255
+ const targetDir = kbRootDir(root, target);
256
+ try {
257
+ await stat(targetDir);
258
+ throw new HubError("KB_EXISTS", `目标库 ${target} 已存在`, { status: 409 });
259
+ } catch (error) {
260
+ if (error?.code !== "ENOENT") throw error;
261
+ }
262
+ await rename(dir, targetDir);
263
+ await writeKbMeta(targetDir, { ...meta, name: target, renamedFrom: name });
264
+ // 清单里的 name 也要跟着改,否则二次校验会不一致
265
+ await withManifest(targetDir, target, (manifest) => {
266
+ manifest.name = target;
267
+ return null;
268
+ });
269
+ return { from: name, to: target, dir: targetDir };
270
+ }
271
+
272
+ // ---------------------------------------------------------------------------
273
+ // 文档写入
274
+ // ---------------------------------------------------------------------------
275
+
276
+ function hashOf(value) {
277
+ return createHash("sha256").update(value).digest("hex");
278
+ }
279
+
280
+ /**
281
+ * 写入一篇已解析好的文档。
282
+ *
283
+ * 幂等语义:同一 relKey + 同一内容哈希 → 直接返回 unchanged,不动版本号。
284
+ * 这条对多人协作很关键:两个人各自导入同一份文件时,第二次不会产生
285
+ * 「rev 变了、索引重建了、却什么都没变」的噪音。
286
+ *
287
+ * @param {object} params
288
+ * @param {string} params.dir 库目录
289
+ * @param {string} params.kb 库名
290
+ * @param {string} params.relKey 相对键(通常是源文件相对路径或标题)
291
+ * @param {object} params.parsed {blocks, pages, type, warnings, outline}
292
+ * @param {object} params.parts packBlocks 的产物
293
+ * @param {object} [params.meta] 额外元数据(title/standardNo/tags/summary/trust)
294
+ * @param {boolean} [params.replace] 已存在时是否覆盖(默认 true,但内容相同则跳过)
295
+ * @param {number} [params.expectedRev] 调用方预期的清单版本(多人并发保护)
296
+ * @param {string} [params.sourcePath] 原始文件路径(sources/ 下会留副本)
297
+ */
298
+ export async function writeDoc(params) {
299
+ const {
300
+ dir,
301
+ kb,
302
+ relKey,
303
+ parsed,
304
+ parts,
305
+ meta = {},
306
+ replace = true,
307
+ expectedRev,
308
+ sourcePath = null,
309
+ historyKeep = DEFAULT_HISTORY_KEEP,
310
+ by = null,
311
+ } = params;
312
+
313
+ const docId = docIdFor(relKey);
314
+ const mergedText = composeMerged(parts, meta.title ?? relKey);
315
+ const contentHash = hashOf(mergedText);
316
+ const now = new Date().toISOString();
317
+
318
+ const existing = await findDoc(dir, kb, docId);
319
+
320
+ if (existing && existing.contentHash === contentHash && !params.force) {
321
+ return {
322
+ docId,
323
+ status: "unchanged",
324
+ rev: null,
325
+ version: existing.version,
326
+ title: existing.title,
327
+ parts: parts.length,
328
+ chars: mergedText.length,
329
+ };
330
+ }
331
+ if (existing && !replace) {
332
+ throw new HubError("DOC_EXISTS", `文档已存在:${existing.title}(${docId})`, {
333
+ status: 409,
334
+ details: { docId, title: existing.title, version: existing.version },
335
+ });
336
+ }
337
+
338
+ // 先落正文(磁盘),再更新清单。顺序不能反:清单是索引/读者看到的东西,
339
+ // 如果先更新清单而正文没写成功,读者会看到一篇「存在但读不出」的文档。
340
+ const targetDir = docDir(dir, docId);
341
+ await mkdir(targetDir, { recursive: true });
342
+ if (existing) await snapshotHistory(dir, docId, existing, historyKeep);
343
+
344
+ await writePartsToDisk(targetDir, docId, parts);
345
+ await writeFile(docMergedPath(dir, docId), mergedText, "utf8");
346
+
347
+ const entry = {
348
+ id: docId,
349
+ relKey: normalizeRelKey(relKey),
350
+ title: String(meta.title ?? existing?.title ?? relKey),
351
+ type: parsed.type ?? "text",
352
+ standardNo: meta.standardNo ?? existing?.standardNo ?? "",
353
+ tags: Array.isArray(meta.tags) ? meta.tags : existing?.tags ?? [],
354
+ summary: meta.summary ?? existing?.summary ?? "",
355
+ trust: meta.trust ?? existing?.trust ?? "unknown",
356
+ stage: meta.stage ?? existing?.stage ?? "published",
357
+ kind: meta.kind ?? existing?.kind ?? "source",
358
+ chars: mergedText.length,
359
+ parts: parts.length,
360
+ pages: parsed.pages ?? null,
361
+ scannedPages: Array.isArray(parsed.scannedPages) ? parsed.scannedPages.length : 0,
362
+ warnings: Array.isArray(parsed.warnings) ? parsed.warnings : [],
363
+ outline: Array.isArray(parsed.outline) ? parsed.outline.slice(0, 300) : [],
364
+ sourceName: sourcePath ? safeFileName(sourcePath) : existing?.sourceName ?? "",
365
+ parserVersion: parsed.parserVersion ?? null,
366
+ version: existing ? existing.version + 1 : 1,
367
+ status: "ready",
368
+ contentHash,
369
+ createdAt: existing?.createdAt ?? now,
370
+ updatedAt: now,
371
+ updatedBy: by ?? { machine: machineId(), pid: process.pid },
372
+ deletedAt: null,
373
+ };
374
+
375
+ await writeFileAtomic(docMetaPath(dir, docId), JSON.stringify(entry, null, 2), { encoding: "utf8" });
376
+
377
+ // 清单 CAS 写入:rev 对不上会把上面写好的正文留在磁盘上(幂等,下次重跑会覆盖),
378
+ // 但绝不更新清单,读者看不到半成品。
379
+ const result = await withManifest(
380
+ dir,
381
+ kb,
382
+ (manifest) => {
383
+ const list = manifest.docs ?? (manifest.docs = []);
384
+ const at = list.findIndex((doc) => doc.id === docId);
385
+ if (at >= 0) list[at] = entry;
386
+ else list.push(entry);
387
+ return entry;
388
+ },
389
+ { expectedRev }
390
+ );
391
+
392
+ await appendEvent(dir, {
393
+ action: existing ? "doc.update" : "doc.create",
394
+ kb,
395
+ docId,
396
+ title: entry.title,
397
+ version: entry.version,
398
+ rev: result.rev,
399
+ parts: entry.parts,
400
+ chars: entry.chars,
401
+ });
402
+
403
+ return {
404
+ docId,
405
+ status: existing ? "updated" : "created",
406
+ rev: result.rev,
407
+ version: entry.version,
408
+ title: entry.title,
409
+ parts: entry.parts,
410
+ chars: entry.chars,
411
+ warnings: entry.warnings,
412
+ };
413
+ }
414
+
415
+ async function findDoc(dir, kb, docId) {
416
+ const manifest = await readManifest(dir, kb);
417
+ return (manifest.docs ?? []).find((doc) => doc.id === docId) ?? null;
418
+ }
419
+
420
+ /** 合并版正文:标题 + 按 part 顺序拼接(part 之间留一个空行)。 */
421
+ export function composeMerged(parts, title) {
422
+ const head = `# ${String(title ?? "").trim() || "未命名文档"}\n\n`;
423
+ const body = parts
424
+ .map((part) => {
425
+ const heading = String(part.heading ?? "").trim();
426
+ // 只在 heading 变化处插小标题,避免每块都重复同一标题
427
+ const label = heading && part.level > 0 && part.level <= 3 ? `## ${heading}\n\n` : "";
428
+ return label + String(part.text ?? "").trim();
429
+ })
430
+ .join("\n\n");
431
+ return head + body + "\n";
432
+ }
433
+
434
+ async function writePartsToDisk(targetDir, docId, parts) {
435
+ // 清掉旧分块,避免「上一次 20 块、这次 12 块」留下 8 个幽灵块
436
+ let names = [];
437
+ try {
438
+ names = await readdir(targetDir);
439
+ } catch {
440
+ names = [];
441
+ }
442
+ for (const name of names) {
443
+ if (/^part-\d+\.md$/.test(name)) await unlink(join(targetDir, name)).catch(() => {});
444
+ }
445
+ for (const part of parts) {
446
+ const name = `part-${String(part.index).padStart(4, "0")}.md`;
447
+ const header = [
448
+ `# ${docId} · 第 ${part.index} 块`,
449
+ part.heading ? `> 位置:${part.heading}${part.page ? ` · 第 ${part.page} 页` : ""}` : part.page ? `> 第 ${part.page} 页` : "",
450
+ "",
451
+ ]
452
+ .filter((line) => line !== undefined)
453
+ .join("\n");
454
+ await writeFile(join(targetDir, name), `${header}\n${part.text}\n`, "utf8");
455
+ }
456
+ }
457
+
458
+ /** 覆盖前留历史版本(正文 + meta),最多保留 historyKeep 份。 */
459
+ async function snapshotHistory(dir, docId, previous, keep) {
460
+ const historyRoot = join(docDir(dir, docId), "history");
461
+ await mkdir(historyRoot, { recursive: true });
462
+ const stamp = new Date().toISOString().replace(/[:.]/g, "-");
463
+ const target = join(historyRoot, `v${previous.version}-${stamp}`);
464
+ await mkdir(target, { recursive: true });
465
+ const merged = docMergedPath(dir, docId);
466
+ const meta = docMetaPath(dir, docId);
467
+ for (const [from, name] of [
468
+ [merged, `${docId}.md`],
469
+ [meta, "meta.json"],
470
+ ]) {
471
+ try {
472
+ await writeFile(join(target, name), await readFile(from));
473
+ } catch {
474
+ /* 首次写入时正文可能还不存在 */
475
+ }
476
+ }
477
+ // 修剪
478
+ let dirs = [];
479
+ try {
480
+ dirs = (await readdir(historyRoot, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
481
+ } catch {
482
+ return;
483
+ }
484
+ dirs.sort();
485
+ while (dirs.length > Math.max(0, keep)) {
486
+ const victim = dirs.shift();
487
+ await rm(join(historyRoot, victim), { recursive: true, force: true }).catch(() => {});
488
+ }
489
+ }
490
+
491
+ /** 列历史版本。 */
492
+ export async function listDocHistory(dir, docId) {
493
+ const historyRoot = join(docDir(dir, docId), "history");
494
+ try {
495
+ const entries = await readdir(historyRoot, { withFileTypes: true });
496
+ const out = [];
497
+ for (const entry of entries) {
498
+ if (!entry.isDirectory()) continue;
499
+ const m = entry.name.match(/^v(\d+)-/);
500
+ out.push({ name: entry.name, version: m ? Number(m[1]) : null, at: entry.name });
501
+ }
502
+ out.sort((a, b) => String(b.name).localeCompare(String(a.name)));
503
+ return out;
504
+ } catch {
505
+ return [];
506
+ }
507
+ }
508
+
509
+ /** 恢复某个历史版本正文(当前版本会先被存成历史,不会丢)。 */
510
+ export async function restoreDocVersion(dir, kb, docId, historyName) {
511
+ const target = join(docDir(dir, docId), "history", historyName, `${docId}.md`);
512
+ const content = await readFile(target, "utf8").catch(() => null);
513
+ if (content === null) throw notFound(`历史版本 ${historyName}`);
514
+ const current = await findDoc(dir, kb, docId);
515
+ if (!current) throw notFound(`文档 ${docId}`);
516
+ await snapshotHistory(dir, docId, current, DEFAULT_HISTORY_KEEP);
517
+ await writeFile(docMergedPath(dir, docId), content, "utf8");
518
+ const next = {
519
+ ...current,
520
+ version: current.version + 1,
521
+ contentHash: hashOf(content),
522
+ chars: content.length,
523
+ updatedAt: new Date().toISOString(),
524
+ restoredFrom: historyName,
525
+ };
526
+ await writeFileAtomic(docMetaPath(dir, docId), JSON.stringify(next, null, 2), { encoding: "utf8" });
527
+ const result = await withManifest(dir, kb, (manifest) => {
528
+ const list = manifest.docs ?? (manifest.docs = []);
529
+ const at = list.findIndex((doc) => doc.id === docId);
530
+ if (at >= 0) list[at] = next;
531
+ return next;
532
+ });
533
+ await appendEvent(dir, { action: "doc.restore", kb, docId, from: historyName, rev: result.rev });
534
+ return { docId, version: next.version, rev: result.rev, chars: next.chars };
535
+ }
536
+
537
+ /** 软删除(可恢复):从检索里消失,但磁盘与历史都在。 */
538
+ export async function softDeleteDoc(root, kb, docId, { expectedRev } = {}) {
539
+ const { dir } = await requireKb(root, kb);
540
+ const result = await withManifest(
541
+ dir,
542
+ kb,
543
+ (manifest) => {
544
+ const list = manifest.docs ?? [];
545
+ const at = list.findIndex((doc) => doc.id === docId);
546
+ if (at < 0) throw notFound(`文档 ${docId}`);
547
+ list[at] = { ...list[at], deletedAt: new Date().toISOString(), status: "deleted" };
548
+ return list[at];
549
+ },
550
+ { expectedRev }
551
+ );
552
+ await appendEvent(dir, { action: "doc.delete", kb, docId, rev: result.rev });
553
+ return { docId, deleted: true, rev: result.rev };
554
+ }
555
+
556
+ export async function restoreDeletedDoc(root, kb, docId, { expectedRev } = {}) {
557
+ const { dir } = await requireKb(root, kb);
558
+ const result = await withManifest(
559
+ dir,
560
+ kb,
561
+ (manifest) => {
562
+ const list = manifest.docs ?? [];
563
+ const at = list.findIndex((doc) => doc.id === docId);
564
+ if (at < 0) throw notFound(`文档 ${docId}`);
565
+ list[at] = { ...list[at], deletedAt: null, status: "ready" };
566
+ return list[at];
567
+ },
568
+ { expectedRev }
569
+ );
570
+ await appendEvent(dir, { action: "doc.undelete", kb, docId, rev: result.rev });
571
+ return { docId, restored: true, rev: result.rev };
572
+ }
573
+
574
+ /** 彻底删除(正文 + 历史 + 清单条目 + 原始副本)。 */
575
+ export async function purgeDoc(root, kb, docId, { expectedRev, removeSource = true } = {}) {
576
+ const { dir } = await requireKb(root, kb);
577
+ const manifest = await readManifest(dir, kb);
578
+ const doc = (manifest.docs ?? []).find((item) => item.id === docId);
579
+ if (!doc) throw notFound(`文档 ${docId}`);
580
+ if (!doc.deletedAt && doc.status !== "deleted") {
581
+ throw new HubError("DOC_NOT_DELETED", "彻底删除前请先软删除(避免误删不可恢复)", { status: 409 });
582
+ }
583
+ await rm(docDir(dir, docId), { recursive: true, force: true }).catch(() => {});
584
+ if (removeSource && doc.relKey) {
585
+ const candidate = join(sourcesDir(dir), doc.relKey);
586
+ await rm(candidate, { force: true }).catch(() => {});
587
+ }
588
+ const result = await withManifest(
589
+ dir,
590
+ kb,
591
+ (m) => {
592
+ m.docs = (m.docs ?? []).filter((item) => item.id !== docId);
593
+ return docId;
594
+ },
595
+ { expectedRev }
596
+ );
597
+ await appendEvent(dir, { action: "doc.purge", kb, docId, rev: result.rev });
598
+ return { docId, purged: true, rev: result.rev };
599
+ }
600
+
601
+ /** 更新单篇元数据(标题/标签/摘要/可信度),不动正文。 */
602
+ export async function updateDocMeta(root, kb, docId, patch, { expectedRev } = {}) {
603
+ const { dir } = await requireKb(root, kb);
604
+ const allow = ["title", "tags", "summary", "trust", "standardNo", "stage", "kind"];
605
+ const result = await withManifest(
606
+ dir,
607
+ kb,
608
+ (manifest) => {
609
+ const list = manifest.docs ?? [];
610
+ const at = list.findIndex((doc) => doc.id === docId);
611
+ if (at < 0) throw notFound(`文档 ${docId}`);
612
+ const next = { ...list[at] };
613
+ for (const key of allow) {
614
+ if (patch[key] !== undefined) next[key] = patch[key];
615
+ }
616
+ next.updatedAt = new Date().toISOString();
617
+ next.updatedBy = { machine: machineId(), pid: process.pid };
618
+ list[at] = next;
619
+ return next;
620
+ },
621
+ { expectedRev }
622
+ );
623
+ // 正文文件里的 meta.json 也要同步,否则「读 meta.json」与「读 manifest」两个来源打架
624
+ const metaPath = docMetaPath(dir, docId);
625
+ try {
626
+ const current = JSON.parse(await readFile(metaPath, "utf8"));
627
+ await writeFileAtomic(metaPath, JSON.stringify({ ...current, ...result.result }, null, 2), { encoding: "utf8" });
628
+ } catch {
629
+ /* 没有独立 meta 时只改清单 */
630
+ }
631
+ await appendEvent(dir, { action: "doc.meta", kb, docId, patch, rev: result.rev });
632
+ return result.result;
633
+ }
634
+
635
+ /** 保留原始文件副本到 sources/(同名覆盖,保留相对目录)。 */
636
+ export async function keepSourceCopy(dir, sourcePath, relKey) {
637
+ const rel = normalizeRelKey(relKey);
638
+ const target = join(sourcesDir(dir), rel);
639
+ await mkdir(join(target, ".."), { recursive: true });
640
+ const data = await readFile(sourcePath);
641
+ await writeFile(target, data);
642
+ return { target, bytes: data.length, sha256: createHash("sha256").update(data).digest("hex") };
643
+ }
644
+
645
+ // ---------------------------------------------------------------------------
646
+ // 笔记(编译页)
647
+ // ---------------------------------------------------------------------------
648
+
649
+ export async function writeNote(dir, kb, { title, content, kind = "note", tags = [], sources = [] }) {
650
+ const clean = String(title ?? "").trim();
651
+ if (clean === "") throw badRequest("笔记标题不能为空");
652
+ const noteId = noteIdFor(clean);
653
+ const target = join(notesDir(dir), `${noteId}.md`);
654
+ const now = new Date().toISOString();
655
+
656
+ let previous = null;
657
+ try {
658
+ const raw = await readFile(target, "utf8");
659
+ const m = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
660
+ if (m) {
661
+ previous = { front: m[1], body: m[2] };
662
+ }
663
+ } catch {
664
+ /* 新笔记 */
665
+ }
666
+
667
+ const front = [
668
+ "---",
669
+ `title: ${JSON.stringify(clean)}`,
670
+ `kind: ${kind}`,
671
+ `created: ${previous ? (previous.front.match(/^created: (.*)$/m)?.[1] ?? now) : now}`,
672
+ `updated: ${now}`,
673
+ `tags: ${JSON.stringify(tags)}`,
674
+ `sources: ${JSON.stringify(sources)}`,
675
+ "---",
676
+ "",
677
+ ].join("\n");
678
+
679
+ await mkdir(notesDir(dir), { recursive: true });
680
+ await writeFileAtomic(target, front + String(content ?? ""), { encoding: "utf8" });
681
+
682
+ // 笔记必须同时落一份到 markdown/<noteId>/,否则它只在清单里、不在索引里,
683
+ // 检索永远搜不到自己写的笔记 —— 这是最容易漏的一处。
684
+ {
685
+ const body = String(content ?? "");
686
+ const blocks = body
687
+ .split(/\n{2,}/)
688
+ .map((text) => ({ text: text.trim(), heading: clean, level: 1 }))
689
+ .filter((block) => block.text !== "");
690
+ const noteParts = packBlocks(blocks.length > 0 ? blocks : [{ text: body, heading: clean, level: 1 }], {
691
+ partChars: 1200,
692
+ overlapChars: 0,
693
+ });
694
+ const noteDir = docDir(dir, noteId);
695
+ await mkdir(noteDir, { recursive: true });
696
+ for (const part of noteParts) {
697
+ const name = `part-${String(part.index).padStart(4, "0")}.md`;
698
+ await writeFile(
699
+ join(noteDir, name),
700
+ `# ${noteId} · 第 ${part.index} 块\n> 位置:${clean}\n\n${part.text}\n`,
701
+ "utf8"
702
+ );
703
+ }
704
+ await writeFile(docMergedPath(dir, noteId), `# ${clean}\n\n${body}\n`, "utf8");
705
+ }
706
+
707
+ const entry = {
708
+ id: noteId,
709
+ relKey: `notes/${noteId}.md`,
710
+ title: clean,
711
+ type: "note",
712
+ kind,
713
+ tags,
714
+ sources,
715
+ summary: String(content ?? "").replace(/\s+/g, " ").slice(0, 160),
716
+ chars: String(content ?? "").length,
717
+ parts: countPartsOfBody(String(content ?? "")),
718
+ version: previous ? 2 : 1,
719
+ status: "ready",
720
+ contentHash: hashOf(String(content ?? "")),
721
+ createdAt: previous ? (previous.front.match(/^created: (.*)$/m)?.[1] ?? now) : now,
722
+ updatedAt: now,
723
+ deletedAt: null,
724
+ updatedBy: { machine: machineId(), pid: process.pid },
725
+ };
726
+ await writeFile(docMetaPath(dir, noteId).replace(/meta\.json$/, "meta.json"), JSON.stringify(entry, null, 2), "utf8").catch(() => {});
727
+
728
+ const result = await withManifest(dir, kb, (manifest) => {
729
+ const list = manifest.docs ?? (manifest.docs = []);
730
+ const at = list.findIndex((doc) => doc.id === noteId);
731
+ if (at >= 0) list[at] = entry;
732
+ else list.push(entry);
733
+ return entry;
734
+ });
735
+ await appendEvent(dir, { action: "note.write", kb, docId: noteId, title: clean, rev: result.rev });
736
+ return { noteId, title: clean, rev: result.rev, version: entry.version };
737
+ }
738
+
739
+ export async function readNote(dir, noteId) {
740
+ const path = join(notesDir(dir), `${noteId}.md`);
741
+ try {
742
+ return await readFile(path, "utf8");
743
+ } catch {
744
+ return null;
745
+ }
746
+ }
747
+
748
+ export async function listNotes(dir) {
749
+ try {
750
+ const names = (await readdir(notesDir(dir))).filter((n) => n.endsWith(".md"));
751
+ const out = [];
752
+ for (const name of names) {
753
+ const raw = await readFile(join(notesDir(dir), name), "utf8");
754
+ const title = raw.match(/^title: (.*)$/m)?.[1];
755
+ out.push({
756
+ id: name.replace(/\.md$/, ""),
757
+ title: title ? JSON.parse(title) : name.replace(/\.md$/, ""),
758
+ updated: raw.match(/^updated: (.*)$/m)?.[1] ?? "",
759
+ });
760
+ }
761
+ return out;
762
+ } catch {
763
+ return [];
764
+ }
765
+ }
766
+
767
+ // ---------------------------------------------------------------------------
768
+ // 目录文件(index.md / log.md 自动生成,不给手改)
769
+ // ---------------------------------------------------------------------------
770
+
771
+ export async function refreshCatalog(dir, kb) {
772
+ const manifest = await readManifest(dir, kb);
773
+ const live = (manifest.docs ?? []).filter((doc) => !doc.deletedAt && doc.status === "ready");
774
+ const byKind = new Map();
775
+ for (const doc of live) {
776
+ const kind = doc.type === "note" ? `笔记 / ${doc.kind ?? "note"}` : doc.type;
777
+ if (!byKind.has(kind)) byKind.set(kind, []);
778
+ byKind.get(kind).push(doc);
779
+ }
780
+ const lines = [
781
+ `# ${kb} · 内容索引`,
782
+ "",
783
+ `> 自动生成,勿手改。清单 rev ${manifest.rev},最近更新 ${manifest.updatedAt}`,
784
+ `> 共 ${live.length} 条(另有 ${(manifest.docs ?? []).length - live.length} 条在回收站)`,
785
+ "",
786
+ ];
787
+ for (const [kind, docs] of [...byKind.entries()].sort((a, b) => String(a[0]).localeCompare(String(b[0])))) {
788
+ lines.push(`## ${kind}(${docs.length})`, "");
789
+ for (const doc of docs.sort((a, b) => String(a.title).localeCompare(String(b.title), "zh-Hans-CN"))) {
790
+ const bits = [
791
+ doc.standardNo || "",
792
+ doc.trust && doc.trust !== "unknown" ? `[${doc.trust}]` : "",
793
+ doc.parts ? `${doc.parts} 块` : "",
794
+ ].filter(Boolean);
795
+ lines.push(`- ${doc.title}${bits.length > 0 ? ` — ${bits.join(" · ")}` : ""} \`${doc.id}\``);
796
+ }
797
+ lines.push("");
798
+ }
799
+ await writeFile(join(dir, INDEX_MD), lines.join("\n"), "utf8");
800
+
801
+ const events = await readRecentEvents(dir, 40);
802
+ const logLines = [
803
+ `# ${kb} · 操作日志`,
804
+ "",
805
+ "> 自动生成,勿手改。完整审计在 events.jsonl。",
806
+ "",
807
+ "| 时间 | 操作 | 对象 | 机器 |",
808
+ "|---|---|---|---|",
809
+ ...events.map(
810
+ (e) => `| ${e.at} | ${e.action} | ${e.title ?? e.docId ?? e.kb ?? ""} | ${e.machine ?? ""} |`
811
+ ),
812
+ "",
813
+ ];
814
+ await writeFile(join(dir, LOG_MD), logLines.join("\n"), "utf8");
815
+ return { index: join(dir, INDEX_MD), log: join(dir, LOG_MD), docs: live.length };
816
+ }
817
+
818
+ async function readRecentEvents(dir, limit) {
819
+ const { readEvents } = await import("./manifest.js");
820
+ return readEvents(dir, { limit });
821
+ }
822
+
823
+ // ---------------------------------------------------------------------------
824
+ // 快照(库级)
825
+ // ---------------------------------------------------------------------------
826
+
827
+ export async function createSnapshot(dir, kb, { label = "", includeSources = false } = {}) {
828
+ const stamp = new Date().toISOString().replace(/[:.]/g, "-");
829
+ const name = `${stamp}${label ? `-${safeFileName(label)}` : ""}`;
830
+ const target = join(snapshotsDir(dir), name);
831
+ await mkdir(target, { recursive: true });
832
+ const manifest = await readManifest(dir, kb);
833
+ await writeFileAtomic(join(target, "manifest.json"), JSON.stringify(manifest, null, 2), { encoding: "utf8" });
834
+ for (const file of [SCHEMA_MD, INDEX_MD, LOG_MD, "kb.json"]) {
835
+ try {
836
+ await writeFile(join(target, file), await readFile(join(dir, file)));
837
+ } catch {
838
+ /* 可选文件 */
839
+ }
840
+ }
841
+ // markdown 与 notes 直接整棵复制(体积可控,且是派生数据)
842
+ const { cp } = await import("node:fs/promises");
843
+ await cp(join(dir, "markdown"), join(target, "markdown"), { recursive: true }).catch(() => {});
844
+ await cp(notesDir(dir), join(target, "notes"), { recursive: true }).catch(() => {});
845
+ if (includeSources) {
846
+ await cp(sourcesDir(dir), join(target, "sources"), { recursive: true }).catch(() => {});
847
+ }
848
+ await writeFile(
849
+ join(target, "meta.json"),
850
+ JSON.stringify({ kb, createdAt: new Date().toISOString(), rev: manifest.rev, includeSources, label }, null, 2),
851
+ "utf8"
852
+ );
853
+ await appendEvent(dir, { action: "kb.snapshot", kb, snapshot: name, rev: manifest.rev });
854
+ return { snapshot: name, path: target, rev: manifest.rev };
855
+ }
856
+
857
+ export async function listSnapshots(dir) {
858
+ try {
859
+ const entries = await readdir(snapshotsDir(dir), { withFileTypes: true });
860
+ const out = [];
861
+ for (const entry of entries) {
862
+ if (!entry.isDirectory()) continue;
863
+ const meta = await readFile(join(snapshotsDir(dir), entry.name, "meta.json"), "utf8")
864
+ .then((raw) => JSON.parse(raw))
865
+ .catch(() => null);
866
+ out.push({ name: entry.name, ...(meta ?? {}) });
867
+ }
868
+ return out.sort((a, b) => String(b.name).localeCompare(String(a.name)));
869
+ } catch {
870
+ return [];
871
+ }
872
+ }
873
+
874
+ export async function readDocMerged(dir, docId) {
875
+ try {
876
+ return await readFile(docMergedPath(dir, docId), "utf8");
877
+ } catch {
878
+ return null;
879
+ }
880
+ }
881
+
882
+ /** 从磁盘读一份分块(不依赖索引,索引坏掉也能精读)。 */
883
+ export async function readPartFromDisk(dir, docId, index) {
884
+ const path = join(docDir(dir, docId), `part-${String(index).padStart(4, "0")}.md`);
885
+ try {
886
+ const raw = await readFile(path, "utf8");
887
+ // 去掉写入时加的 3 行头(标题 / 位置 / 空行)
888
+ const lines = raw.split("\n");
889
+ return lines.slice(3).join("\n").trim();
890
+ } catch {
891
+ return null;
892
+ }
893
+ }
894
+
895
+ export async function listPartFiles(dir, docId) {
896
+ try {
897
+ return (await readdir(docDir(dir, docId)))
898
+ .filter((n) => /^part-\d+\.md$/.test(n))
899
+ .sort()
900
+ .map((n) => Number(n.match(/part-(\d+)/)[1]));
901
+ } catch {
902
+ return [];
903
+ }
904
+ }
905
+
906
+ export { basename, kbMetaPath, sourcesDir };