dsh-kb-sync

LIMITATIONS

Known limitations

- **应用内只有一个设置分节**：`lib/client.js` 在 **设置 → dsh-kb-sync** 注册一节（状态几行 + 「抓取新对话 / 更新知识库 / 刷新」），手写、无构建步骤；完整的控制页仍是独立 URL（那里才有检索、全文展开、分步表格）。**装配契约已逐条对宿主实现核对**（`__ModuleLoader__.load` 的 id 必须等于包名、`exports["./client"]` 的合法形式、`settings.section` 的注册字段、`immediately` 只是预取提示）——见 [`docs/CLIENT-HALF.md`](docs/CLIENT-HALF.md)；整条安装链路（`insert` 行 → loader 说明符 → 包目录 → 两侧代码）见 [`docs/INSTALL-PATH.md`](docs/INSTALL-PATH.md)。 - 客户端分节**不做配置编辑**（配置读的是插件启动时解析的那一份，改配置要重启；页面上能改反而会骗人）。 - **控制页与应用内分节都支持中英**：控制页默认中文、`?lang=en` 或浏览器 `Accept-Language` 切换；设置分节跟随宿主界面语言。**服务端的诊断文案（`/status` 的 message、更新知识库各步输出、流水线脚本自身的输出）仍是中文**——它们是排错信息，翻译收益低、改动面大，暂不翻。 - 需要宿主提供 `subprocess` 服务；缺失时 `/run`、`/doctor` 会明确报错，而不是静默失败。 - 状态是轮询（运行中 3 秒一次），不是推送。 - 已在 Windows + DSH 0.2.0-rc.2 上实测：控制页、`/status`、`/doctor`、越界与跨站拒绝；POSIX 执行分支已写但未实测。 - **2026-10-12 晚：页面那几条路也在真机跑过了**（读数取自 `/status`）—— 一键更新知识库 **21:21:04→21:21:09**（5 步全 `ok`）、`/process` **21:21:39**（自动选中 `deepseek-official` / `deepseek-flash`）、**全量回填 21:23:04→21:25:23 跑完**（真实导出包 25.6 MB / 2549 条会话，0 新增、0 更新、2549 skipped、`errors: []`）、`/run` 的成功路径跑通（`trigger.log` 有 `rc=0`；页面按钮与双击走的是同一条 `trigger.cmd`）。 > 读法：这几轮上游**没有新内容**（`fetch` 报"没有需要更新的内容 ✔"、整理 报"本轮条目 0"），所以它们证明的是**管道通 + 幂等 + 跳过路径**，而不是"一次产出新内容的运行"；真正写盘的那几轮看 `data\kb\catalog.json`（2556 条）与 `data\import\knowledge\*.backup-*` 的轮转。 - **拉取有两条路**：日常用**增量**（列表接口 `chat_session/fetch_page` 实测：`count` 上限 **100**，超过报 `ILLEGAL_COUNT`；`page`/`offset`/`page_num`/`seq_id`/`cursor` 全被忽略、`POST` 405 —— **这条路翻不了页**，2026-10-12 实测，所以增量只保证「往后每天长」）；要**完整历史**用**全量回填**（官方导出包）。回填的解析器已对着真实导出包实测：2446 条会话全部解析，最后一条是助手回复的占 **2442/2446**（若按时间戳找叶子，会有几百条停在提问上、丢掉最后一条回答——这正是导出包的已知坑）。 - `userToken` 会过期（数小时~数天）：过期后拉取报错，重新粘一次即可；它是你的账号凭据，不要外传。 - **默认不共用知识库目录**：插件的库在它自己的 `data/kb`。只有你显式把 `outDir` 指到与别的脚本同一个目录，才会出现两边互相重写 `catalog.json` / `conversations.jsonl` 的情况（各自读-改-写）。 - 检索是**直接扫 JSONL、不建索引**（几千会话够快）；会话量再涨一个量级要换方案。