dsh-shared-kb 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,242 @@
-# Temporary Holding Version
+# dsh-shared-kb
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DeepSeek Harness 知识库中枢：**指定一个物理地址，每个库一个独立子文件夹**，原始资料与派生分块都落在库里；自带 **SQLite FTS5 全文索引 + 向量语义检索**，用租约与 revision CAS 支持**多人多机同时读、写入与索引重建**。
+
+- 包名：`dsh-shared-kb`
+- 插件 id：`shared-kb`
+- 工作台：`/shared-kb/`
+- 工具前缀：`kb_*`
+
+---
+
+## 一、它解决什么
+
+`dsh-knowledge-wiki` 这类知识库插件把「资料 → 分块 → 索引」放在**单机、单进程**的假设下：
+
+- 索引和资料在同一个目录，两台机器同时用会互相破坏索引；
+- 清单靠一把本机文件锁串行化，跨机器形同虚设；
+- 「后写覆盖先写」没有任何检测，两个人同时改一个库会**静默丢数据**。
+
+本插件把这些假设逐条拆掉：
+
+| 单机假设 | 本插件的做法 |
+|---|---|
+| 索引与资料同目录 | **资料在共享盘，索引在每台机器本地**（原因见第四节） |
+| 本机文件锁足够 | **目录原子创建租约** + 心跳，跨机器可见、可回收 |
+| 后写覆盖先写 | **revision 单调递增 + CAS**，冲突返回 `REV_CONFLICT` 而不是静默覆盖 |
+| 一套向量模型 | provider 身份写进索引 meta，换模型自动整体重建，绝不混用 |
+| 索引坏了要重建全库 | 每篇文档记 version，**增量补**，别人加的资料第一次检索就到 |
+
+---
+
+## 二、目录布局
+
+`kbRoot` 指向任意物理地址（本地盘、已挂载盘符、UNC 共享、NAS 挂载点）：
+
+```
+<kbRoot>/
+  .hub/
+    hub.json                    根标记 + schema 版本 + 归属信息
+    machines/<machineId>.json   每台机器一条心跳（诊断「现在谁在用」）
+  <库名>/
+    kb.json                     库元数据（描述/只读/写入策略/默认检索参数）
+    manifest.json               文档清单：唯一真相，rev 单调递增，CAS 写入
+    events.jsonl                操作审计（只增不改，谁在何时改了什么）
+    schema.md                   本库维护规范（人写，插件永不覆盖）
+    index.md                    自动生成的目录
+    log.md                      自动生成的操作日志
+    sources/                    原始资料（只读，导入后不再修改）
+    markdown/<docId>/
+      meta.json                 单篇元数据
+      <docId>.md                合并版全文
+      part-0001.md …            分块（精读/喂模型用）
+      history/                  历史正文版本（覆盖前自动留）
+    notes/                      笔记 / 编译页（带 YAML frontmatter）
+    exports/                    导出产物
+    snapshots/                  库级快照
+    .locks/                     跨机器租约（<scope>.lease/owner.json）
+```
+
+索引**不在**库里：
+
+```
+~/.dsh/shared-kb/indexes/<根目录哈希>/kb-<库名>.sqlite
+```
+
+同一个物理根目录在每个使用者机器上各有一份索引，互不干扰。
+
+---
+
+## 三、多人同时用同一个库：三道防线
+
+### 3.1 租约（lease）—— 让并发写有序
+
+`mkdir` 在所有主流文件系统（含 SMB/NFS）上是**原子**的：恰好一个调用方成功，其余 `EEXIST`。租约就是基于这个原语：
+
+1. `mkdir <库>/.locks/<scope>.lease` 成功者获得锁；
+2. 锁内写 `owner.json`（machine / pid / token / heartbeatAt）；
+3. 持有者每 5 秒刷新 `heartbeatAt`；
+4. 释放时先比对 token 再删，防止「删掉别人刚抢到的锁」。
+
+**回收判据分两类，不能混用**：
+
+| 同机 | 异机 |
+|---|---|
+| PID 是硬证据：进程不在了，立刻可回收（需越过 300ms 建锁保护期） | 只能靠心跳：超过 `staleMs` 未刷新才认为失联 |
+
+为什么不用文件锁（flock / LockFileEx）：SMB 上各实现语义不一，有的静默降级成无锁，出问题时表现为「两个进程都以为自己拿到了锁」——数据损坏且无迹可查。
+
+### 3.2 revision CAS —— 让「后写覆盖先写」不可能发生
+
+清单带 `rev`（整数单调递增，不用时间戳：多机时钟偏移会让时间戳倒退，无法比较先后）。
+
+每次写入可以声明「我基于哪一版」：
+
+```
+expectedRev = 12 → 提交时清单 rev 若已变成 13，立刻返回 REV_CONFLICT
+                         并回传当前 rev 与冲突文档，让上层重读后再提交
+```
+
+不传 `expectedRev` 时，读-改-写在**同一把租约内**完成，等价于「自动取最新」。两条路都不允许后写静默覆盖先写。
+
+### 3.3 原子写重试 —— 让共享盘上的写入真的落地
+
+这是 Windows + 共享盘的必备件，不是可选项：
+
+- POSIX 上 `rename(tmp, target)` 是覆盖式原子替换，基本不会失败；
+- **Windows 上**目标文件若正被另一进程打开（杀毒扫描、预览、另一个进程在 read/stat），`rename` 返回 `EPERM` / `EACCES` / `EBUSY`。
+
+多进程同时写清单时这个窗口必然出现。裸 `rename` 的表现是「随机丢条目」——测试里真实复现过（8 个并发进程偶发只写入 6–7 篇）。因此所有覆盖式写入都走 `lib/core/atomic.js`：指数退避 + 抖动的有限重试，最终失败给出可诊断错误。
+
+---
+
+## 四、为什么索引不进共享盘
+
+在 SMB / UNC / NAS 上放一个多进程同时写的 SQLite 文件是灾难：
+
+- SQLite 的 WAL 依赖共享内存映射与 `fcntl` 锁，SMB 实现普遍不支持或语义不一致；
+- 典型后果：索引静默损坏、打不开、或被标记 malformed 后每次打开都要重建；
+- 更糟的是**损坏是静默的**，表现为「检索结果变少」，而不是报错。
+
+所以：**资料在共享盘（唯一真相），索引在每台机器本地（可再生）**。
+
+好处不止是避免损坏：
+
+- 索引坏了删掉重建，不影响任何人；
+- 每台机器可以按自己的 CPU/内存决定要不要建向量索引；
+- 别人在另一台机器导的资料，我这边第一次检索时按 `version` 增量补齐，不重建全库。
+
+---
+
+## 五、检索
+
+### 5.1 混合检索（默认）
+
+| 通道 | 强项 | 弱项 |
+|---|---|---|
+| 全文 BM25 | 标准号、型号、条款号、专有名词的**精确**命中 | 同义改写抓不到 |
+| 向量语义 | 同义改写、自然语言提问 | 编号/型号不敏感 |
+
+融合用 **RRF（Reciprocal Rank Fusion）**：只看排名不看分数，不需要把 BM25 的「越小越好」与余弦的「越大越好」凑到同一量纲，也不会因为某一路分数尺度不同而让另一路失效（k=60）。
+
+额外一层「字面加分」：命中查询里罕见 token 时给极小固定加分，用于处理 RRF 后的并列。
+
+`mode` 可选 `hybrid`（默认）/ `fulltext` / `semantic`。
+
+### 5.2 中文分词
+
+FTS5 的 `unicode61` 不认识中文（整段连续汉字算一个 token，搜「知识库」命中不了）。本插件的做法是**预分词后存进普通列**，而不是用 trigram：
+
+- `Intl.Segmenter` 词级切分（Node 内置，无第三方词典）
+- 汉字连续段额外产出**二元组**（解决「识库」这类子串查询）
+- 英文词 + 去分隔符压紧形式（`GB/T` → `gbt`）
+- 数字串数字面量（`19963.2` 可查）
+
+索引与查询复用同一函数，不会「索引里有、查不到」。
+
+### 5.3 语义 provider
+
+| 模式 | 说明 |
+|---|---|
+| `auto`（默认） | 优先 onnx，不可用回退 builtin |
+| `onnx` | `onnxruntime-node` + `@huggingface/tokenizers` 加载 BGE 类中文模型（可选 peer） |
+| `remote` | OpenAI 兼容 `/v1/embeddings`（自备 key） |
+| `builtin` | 零依赖哈希嵌入（character n-gram + feature hashing），无模型文件时的兜底 |
+
+provider 名与维度写进索引 meta；换了模型或维度变化 → 索引**整体重建**，绝不把两套向量混在一个索引里。
+
+---
+
+## 六、工具
+
+| 工具 | 用途 |
+|---|---|
+| `skb_status` | 根目录、索引位置、provider、机器心跳、各库索引是否落后、租约占用 |
+| `skb_list` | 列库 / 列某库文档（过滤、分页、含回收站） |
+| `skb_create` | 建库（自动生成目录骨架与 `schema.md` 模板） |
+| `skb_import` | 导入文件或目录（pdf/docx/xlsx/pptx/epub/md/txt/csv/html），幂等 |
+| `skb_query` | 混合检索，返回命中块（标题/章节/页码/片段）与按文档聚合视图 |
+| `skb_read` | 精读：`outline` / 数字块 / `all`（直接读磁盘，不依赖索引） |
+| `skb_note` | 写/更新笔记（同标题=更新，不另起「续」） |
+| `skb_notes` | 列笔记 |
+| `skb_doc` | 改元数据 / 软删 / 恢复 / 彻底删 / 历史版本 / 恢复版本 |
+| `skb_kb` | 改库元数据 / 重命名 / 删库 / 快照 / 审计 / 刷新目录 / 租约管理 |
+| `skb_reindex` | 增量同步或强制重建索引 |
+| `skb_page` | PDF 按页渲染成 PNG（核对公式、图纸、版式） |
+
+---
+
+## 七、工作台
+
+`/shared-kb/` 提供：库列表（含索引落后标记）、检索（可切模式）、文档列表（含回收站）、导入（服务器路径 / 上传）、笔记编辑、审计与租约查看、重建索引与快照。
+
+安全：所有请求过**信任围栏**（`webRuntime.trustedHosts`；拿不到列表时只放行回环），响应带 `nosniff` / `no-referrer` / `SAMEORIGIN`；静态文件路径做目录穿越校验。
+
+---
+
+## 八、配置
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `kbRoot` | `~/.dsh/shared-kb` | 知识库物理根目录（可指向共享盘） |
+| `defaultKb` | `default` | 未指定 kb 时的默认库 |
+| `semanticProvider` | `auto` | `auto` / `onnx` / `remote` / `builtin` |
+| `semanticModelDir` | 空 | ONNX 模型目录 |
+| `remoteBaseUrl` / `remoteApiKey` / `remoteModel` / `remoteDim` | 空 / 1024 | 远端 embedding |
+| `builtinDim` | 512 | 兜底嵌入维度 |
+| `partChars` / `overlapChars` | 1200 / 150 | 分块大小与重叠 |
+| `indexCacheRoot` | 空 | 本机索引缓存根（默认 `~/.dsh/shared-kb/indexes/<hash>`） |
+| `historyKeep` | 10 | 每篇保留多少历史版本 |
+| `maxImportBytes` | 512 MiB | 单文件上限 |
+| `autoIndex` | true | 导入后与检索前自动增量同步 |
+| `webEnabled` | true | 是否挂载 `/shared-kb` |
+
+---
+
+## 九、测试
+
+```bash
+node test/all.mjs          # 全部套件
+node test/smoke.mjs        # 核心链路（建库/导入/幂等/检索/精读/笔记/CAS/租约/布局）
+node test/tools.mjs        # 工具层（12 个工具的真实接线与错误路径）
+node test/concurrency.mjs  # 多进程并发（真 fork 子进程，含 SIGKILL 回收租约）
+node test/web.mjs          # Web 层（真 http server，含信任围栏与目录穿越）
+node test/syntax.mjs       # 全量语法检查
+```
+
+多进程并发测试覆盖：8 进程同时导入、同文件并发导入幂等、同一 `expectedRev` 竞争、被杀进程的租约回收、跨进程检索可见性、两套独立索引共存。
+
+---
+
+## 十、已知边界
+
+- **彻底正确性依赖 CAS，不依赖锁**：共享盘上不存在绝对正确的分布式锁，本插件的锁是「失败可见、可自愈、竞争窗口极小」，真正的写入正确性由 revision CAS 兜底。
+- **向量检索是全表扫描**：知识库规模（几千到几万块）下毫秒级；超过约 20 万块建议分库，而不是硬扛。
+- **OCR 不在本插件内**：PDF 只取文字层，扫描页会给出警告并可用 `skb_page` 查看原图；需要 OCR 请先用 `dsh-knowledge-wiki` 或外部工具把扫描件转成文字版。
+- **`builtin` 嵌入不是真语义模型**：它是让检索链路在无模型时仍可用的兜底，语义能力有限；要真语义请配 onnx 或 remote。
+
+---
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# dsh-shared-kb bundle patch。
+#
+# 只插入自己这一行，不覆盖任何官方或第三方插件。用户可在 profile 的
+# cordis.patch.yml 里覆盖任意 config 键，但不要再加一个 id 为
+# shared-kb 的 insert（loader id 重复会导致启动失败）。
+- insert:
+    - id: shared-kb
+      name: dsh-shared-kb
+      config:
+        kbRoot: ~/.dsh/shared-kb
+        defaultKb: default

package/lib/client.js

@@ -0,0 +1,61 @@
+/**
+ * 客户端注入半：在会话侧栏/输入区挂一个「打开知识库中枢」入口。
+ *
+ * 说明：DSH 的 client 插件要由宿主 ModuleLoader 加载（window.__ModuleLoader__）。
+ * 这里只做最小可用：注册一个命令式入口，点击后新开 /shared-kb/ 页面。
+ * 不依赖 React，避免不同宿主版本的 react 版本冲突。
+ */
+(() => {
+  "use strict";
+  const boot = typeof window !== "undefined" ? window.__DSH_BOOT__ : undefined;
+  const rows = boot && Array.isArray(boot.entries) ? boot.entries : [];
+  const known = new Set(rows.map((row) => row && row.id));
+  const CANDIDATES = ["shared-kb", "dsh-shared-kb"];
+  const id = CANDIDATES.find((candidate) => known.has(candidate)) || CANDIDATES[0];
+
+  if (typeof window === "undefined" || !window.__ModuleLoader__) return;
+
+  window.__ModuleLoader__.load({
+    id,
+    factory: () => {
+      const open = () => {
+        try {
+          window.open("/shared-kb/", "_blank", "noopener");
+        } catch {
+          /* 弹窗被拦时静默 */
+        }
+      };
+
+      /**
+       * 注册入口。宿主不同版本提供的注册方式不同，这里按能力探测，
+       * 全部失败也不抛错（工作台可以直接输 URL 访问）。
+       */
+      const register = (api) => {
+        if (!api) return;
+        if (typeof api.command === "function") {
+          api.command({
+            id: "shared-kb.open",
+            title: "打开知识库中枢",
+            run: open,
+          });
+        }
+        if (typeof api.slashCommand === "function") {
+          api.slashCommand({
+            name: "kb",
+            description: "打开知识库中枢（/shared-kb/）",
+            run: open,
+          });
+        }
+      };
+
+      return {
+        apply(ctx) {
+          register(ctx);
+          register(ctx?.commands);
+          register(ctx?.ui);
+        },
+        open,
+      };
+    },
+  });
+})();

package/lib/core/atomic.js

@@ -0,0 +1,87 @@
+/**
+ * 原子写 + 跨平台重试。
+ *
+ * 为什么单独抽一个模块：
+ *
+ *   POSIX 上 rename(tmp, target) 是"覆盖式原子替换"，基本不会失败（除了 EXDEV）。
+ *   Windows 上不是：目标文件如果正被另一个进程以不带 FILE_SHARE_DELETE 的
+ *   方式打开（杀毒扫描、资源管理器预览、我们自己的另一个进程在 read/stat），
+ *   rename 会返回 EPERM / EACCES / EBUSY。
+ *
+ *   知识库放在共享盘、多进程同时写清单时，这个窗口是必然存在的，
+ *   不是"偶发故障"。因此所有覆盖式写入都必须带有限重试 + 随机抖动，
+ *   并在最终失败时给出可诊断的错误（哪个文件、试了几次、最后一次什么错）。
+ *
+ * 重试策略：指数退避 + 抖动，总时长约 1–2 秒 —— 太短撑不过一次杀毒扫描，
+ * 太长会在真的死锁时让用户干等。
+ */
+import { randomBytes } from "node:crypto";
+import { rename, rm, writeFile } from "node:fs/promises";
+
+/** Windows 上 rename 覆盖会被拒的错误码；POSIX 上这些基本不出现。 */
+const TRANSIENT = new Set(["EPERM", "EACCES", "EBUSY", "ENOTEMPTY", "EEXIST"]);
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function backoff(i) {
+  return Math.min(300, 8 * 2 ** Math.min(i, 6)) + Math.floor(Math.random() * 40);
+}
+
+/**
+ * 覆盖式原子写：先写同目录临时文件，再 rename 到目标。
+ *
+ * @param {string} target 目标路径
+ * @param {string|Buffer} data 内容
+ * @param {{attempts?: number, tmpSuffix?: string, encoding?: BufferEncoding}} [options]
+ */
+export async function writeFileAtomic(target, data, options = {}) {
+  const attempts = Math.max(1, Number(options.attempts) || 12);
+  const suffix = options.tmpSuffix ?? `${process.pid}.${randomBytes(4).toString("hex")}`;
+  const tmp = `${target}.${suffix}.tmp`;
+  const writeOptions = typeof data === "string" ? { encoding: options.encoding ?? "utf8" } : undefined;
+
+  await writeFile(tmp, data, writeOptions);
+  let lastError = null;
+  for (let i = 0; i < attempts; i += 1) {
+    try {
+      await rename(tmp, target);
+      return { path: target, attempts: i + 1 };
+    } catch (error) {
+      lastError = error;
+      if (!TRANSIENT.has(error?.code)) break;
+      await sleep(backoff(i));
+    }
+  }
+
+  await rm(tmp, { force: true }).catch(() => {});
+  const wrapped = new Error(
+    `原子写覆盖失败（${attempts} 次重试后）：${String(lastError?.code ?? "unknown")} ${target}` +
+      `；最后一次错误：${String(lastError?.message ?? lastError)}`
+  );
+  wrapped.code = lastError?.code ?? "ATOMIC_WRITE_FAILED";
+  wrapped.path = target;
+  wrapped.attempts = attempts;
+  throw wrapped;
+}
+
+/** 只做 rename 的覆盖（调用方已写好 tmp），带同样的重试。 */
+export async function renameWithRetry(from, to, options = {}) {
+  const attempts = Math.max(1, Number(options.attempts) || 12);
+  let lastError = null;
+  for (let i = 0; i < attempts; i += 1) {
+    try {
+      await rename(from, to);
+      return { attempts: i + 1 };
+    } catch (error) {
+      lastError = error;
+      if (!TRANSIENT.has(error?.code)) break;
+      await sleep(backoff(i));
+    }
+  }
+  await rm(from, { force: true }).catch(() => {});
+  const wrapped = new Error(
+    `重命名失败（${attempts} 次重试后）：${String(lastError?.code ?? "unknown")} ${from} -> ${to}`
+  );
+  wrapped.code = lastError?.code ?? "RENAME_FAILED";
+  throw wrapped;
+}

package/lib/core/errors.js

@@ -0,0 +1,39 @@
+/**
+ * 错误类型：所有对外抛出的错误都带机器码，方便工具层与 HTTP 层统一映射。
+ * 不用 throw new Error("...") 混着抛，否则调用方只能靠字符串匹配。
+ */
+export class HubError extends Error {
+  /**
+   * @param {string} code 机器码，例如 KB_NOT_FOUND / REV_CONFLICT / LEASE_HELD
+   * @param {string} message 给人看的中文说明
+   * @param {{ status?: number, details?: unknown, retryAfterMs?: number }} [options]
+   */
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = "HubError";
+    this.code = code;
+    this.status = options.status ?? 400;
+    this.details = options.details;
+    this.retryAfterMs = options.retryAfterMs;
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      ...(this.details === undefined ? {} : { details: this.details }),
+      ...(this.retryAfterMs === undefined ? {} : { retryAfterMs: this.retryAfterMs }),
+    };
+  }
+}
+
+export const notFound = (what) => new HubError("NOT_FOUND", `${what}不存在`, { status: 404 });
+export const badRequest = (message, details) => new HubError("BAD_REQUEST", message, { status: 400, details });
+export const conflict = (message, details) => new HubError("REV_CONFLICT", message, { status: 409, details });
+
+/** 把任意异常压成 { code, message } —— 日志与工具输出都用这个口径。 */
+export function describeError(error) {
+  if (error instanceof HubError) return error.toJSON();
+  const code = typeof error?.code === "string" && /^[A-Z_]+$/.test(error.code) ? error.code : "INTERNAL";
+  return { code, message: String(error?.message ?? error) };
+}

package/lib/core/hubconfig.js

@@ -0,0 +1,151 @@
+/**
+ * 中枢级配置与机器身份。
+ *
+ * 为什么需要「机器身份」：知识库可能放在网络共享盘上（SMB/UNC/NAS），
+ * 多台机器同时挂载同一个库。要知道「现在是谁在写」「这把锁是不是我一个
+ * 已经死掉的进程留下的」，必须能区分机器。PID 只在单机内唯一。
+ *
+ * hub.json 放在 <root>/.hub/ 下，是整个知识库根目录的元数据：
+ *   - schemaVersion：布局版本，用于将来迁移
+ *   - machines：机器注册表，每台机器一条心跳，用于诊断「谁在用这个库」
+ *   - 同时也是「这是一个知识库根目录」的标记文件
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { hostname, platform, arch, release } from "node:os";
+import { mkdir, readFile, readdir, unlink } from "node:fs/promises";
+import { writeFileAtomic } from "./atomic.js";
+import { join } from "node:path";
+import { hubDir } from "./paths.js";
+
+export const HUB_SCHEMA = 1;
+
+/** 稳定的机器 id：hostname + platform + arch 派生，同一台机器恒定。 */
+export function machineId() {
+  const seed = `${hostname()}|${platform()}|${arch()}`;
+  return createHash("sha256").update(seed).digest("hex").slice(0, 12);
+}
+
+export function machineLabel() {
+  let who = "unknown";
+  try {
+    who = String(process.env.USERNAME ?? process.env.USER ?? "user");
+  } catch {
+    /* ignore */
+  }
+  return `${hostname()} / ${platform()} ${release()} / ${who}`;
+}
+
+function hubFilePath(root) {
+  return join(hubDir(root), "hub.json");
+}
+
+function machinesDir(root) {
+  return join(hubDir(root), "machines");
+}
+
+/**
+ * 原子写 JSON。底层走 writeFileAtomic（带 Windows EPERM 重试）：
+ * 共享盘上多进程同时刷新心跳/清单时 rename 覆盖会被占用打回，
+ * 这里不能自己实现一遍裸 rename。
+ */
+export async function writeJsonAtomic(path, value) {
+  await writeFileAtomic(path, JSON.stringify(value, null, 2), { encoding: "utf8" });
+}
+
+async function readJsonSafe(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 确保知识库根目录存在并带上 .hub 标记。
+ * 返回 { root, created, hub }。
+ */
+export async function ensureHub(root) {
+  const dir = hubDir(root);
+  await mkdir(dir, { recursive: true });
+  await mkdir(machinesDir(root), { recursive: true });
+  const path = hubFilePath(root);
+  const existing = await readJsonSafe(path);
+  if (existing && typeof existing === "object") {
+    if (!existing.schemaVersion || existing.schemaVersion < HUB_SCHEMA) {
+      const upgraded = { ...existing, schemaVersion: HUB_SCHEMA, upgradedAt: new Date().toISOString() };
+      await writeJsonAtomic(path, upgraded);
+      return { root, created: false, hub: upgraded };
+    }
+    return { root, created: false, hub: existing };
+  }
+  const hub = {
+    schemaVersion: HUB_SCHEMA,
+    createdAt: new Date().toISOString(),
+    // 放置根目录的「归属信息」只是展示用，不参与鉴权。
+    createdBy: { machine: machineId(), label: machineLabel() },
+    // 索引默认策略：本机缓存（不改的话索引永远不进共享盘）
+    indexLocation: "local",
+  };
+  await writeJsonAtomic(path, hub);
+  return { root, created: true, hub };
+}
+
+export async function readHub(root) {
+  return (await readJsonSafe(hubFilePath(root))) ?? null;
+}
+
+/** 心跳：写本机一条记录，供 skb_status 展示「现在有谁在用」。 */
+export async function heartbeat(root, extra = {}) {
+  const dir = machinesDir(root);
+  await mkdir(dir, { recursive: true });
+  const id = machineId();
+  const path = join(dir, `${id}.json`);
+  const prev = (await readJsonSafe(path)) ?? {};
+  const seen = Number(prev.seenCount) || 0;
+  const record = {
+    machine: id,
+    label: machineLabel(),
+    hostname: hostname(),
+    platform: `${platform()} ${release()}`,
+    pid: process.pid,
+    firstSeenAt: prev.firstSeenAt ?? new Date().toISOString(),
+    lastSeenAt: new Date().toISOString(),
+    seenCount: seen + 1,
+    ...extra,
+  };
+  await writeJsonAtomic(path, record);
+  return record;
+}
+
+/** 列出已知机器；超过 staleMs 未心跳的标记为 stale（不删，保留历史）。 */
+export async function listMachines(root, { staleMs = 10 * 60 * 1000 } = {}) {
+  const dir = machinesDir(root);
+  let names = [];
+  try {
+    names = await readdir(dir);
+  } catch {
+    return [];
+  }
+  const now = Date.now();
+  const out = [];
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    const record = await readJsonSafe(join(dir, name));
+    if (!record) continue;
+    const age = now - Date.parse(record.lastSeenAt ?? 0);
+    out.push({ ...record, ageMs: Number.isFinite(age) ? age : null, stale: !Number.isFinite(age) || age > staleMs });
+  }
+  out.sort((a, b) => String(b.lastSeenAt).localeCompare(String(a.lastSeenAt)));
+  return out;
+}
+
+/** 清理本机自己的历史记录（仅用于测试与重置）。 */
+export async function dropMachine(root, id = machineId()) {
+  await unlink(join(machinesDir(root), `${id}.json`)).catch(() => {});
+}
+
+/** 本机索引缓存根：与知识库根目录一一对应，用 root 路径的哈希隔离。 */
+export function localIndexCacheRoot(home, root) {
+  const key = createHash("sha256").update(root, "utf8").digest("hex").slice(0, 16);
+  return join(home, "indexes", key);
+}