dsh

dsh-wiki — DSH 插件（llm-wiki 知识库）

为 DeepSeek Harness (DSH) 提供的 llm-wiki 通用知识库插件：内嵌 vendor-core，与 pi 扩展 / MCP 服务端 / skill CLI 同一实现（packages/dsh/scripts/sync-vendor.mjs 从 packages/core 同步）， 读写同一份 OKF v0.2 bundle（默认 ~/.agents/wiki）。

安装

# 从 npm（发布后）
dsh plugin --profile web add @sidleo3/dsh-wiki

# 本地开发（源码目录）
dsh plugin --profile web add link:/path/to/packages/dsh

修改 profile 组合后需重启 dsh web 生效。

兼容性（DSH 版本）

已核对版本：0.1.7-rc.2（开发基线）、0.2.0-rc.1 与 0.2.1-rc.2（复核，桌面版实测加载：14 个 wiki_* 工具可用、system prompt 注入可见、/api/dsh-wiki/state 与 /health 返回 200）。

客户端契约（0.1.7-rc.2 / 0.2.0-rc.1 / 0.2.1-rc.2 一致）：

• 产物是经典脚本 + CJS 工厂 window.__ModuleLoader__.load({ id, factory })；第一行必须是 load 调用（多一个 "use strict" 前缀该行就认不出来），factory 内 require 走 loader 模块表。
• 模块表基线种子 0.2.1 为 11 项：react、react/jsx-runtime、react-dom、react-dom/client、@deepseek-ai/cordis、zod、@tanstack/react-virtual、@deepseek-ai/dsh-client-store、@deepseek-ai/dsh-client-ui-slots、@deepseek-ai/dsh-client-ui-primitives、@deepseek-ai/dsh-client-ui-dockkit；0.2.0 及更早为 9 项（无 zod、@tanstack/react-virtual，旧 9 项是子集）。本插件只 require react，故不需要 dsh.client.external。
• 非基线模块必须写进 dsh.client.external：漏了不是单插件静默失效，而是 factory 物化时抛错、整个 web boot 失败（web boot: N entries did not activate）。
• slot 的声明方与 key 语义：settings.section（list，声明方 dsh-client-ui-settings-general，id 即导航项）与 plugins.bundle.config（keyed，声明方 dsh-client-ui-plugin-manager，key = 包名）。

版本门：

• 0.2.1 起强制执行顶层 engines.dsh（与 engines.node 并列）：声明了它就只按它判定，peerDependencies 被忽略。本插件顶层声明 >=0.1.7-rc.2，覆盖 0.1.7-rc.2 到 0.2.x。
• 0.1.7-rc.2 与 0.2.0-rc.1 没有任何代码读取 engines.dsh，门是 peerDependencies 里的 @deepseek-ai/dsh* 加 semver.satisfies(runtime, range, { includePrerelease: true })（dsh-app-boot）；本插件不声明这类 peer（peer 只有 react）→ 缺省不设限。
• 永远不要写 ^0.1.7-rc.2 这类下界精确到 prerelease 的写法：^ 的上界卡在 0.2.0 之前，对 0.2.x 判 false，会让整个 bundle 被静默 skip。

复核方法：tests/dsh-client-bundle-test.mjs 是离线契约闸门（外壳格式 + 两个 slot + jsdom 渲染）；tests/dsh-020-contract-test.mjs 钉 0.2.0 的基线表与 slot 契约，并校验当前 package.json 的顶层 engines.dsh；真机复核看 Settings 的「llm-wiki 知识库」与侧栏 Plugins 的 bundle 页。

能力

• 注入分两层（可选宿主优化；system-prompt/assemble 瀑布，apply 同步注册，异步读盘不外抛）：
  • 恒定层：工具用法 + 【硬要求】第一步先 wiki_list，作为 system prompt section （sectionOrder: 62）注入。文本是模块级常量——任何会话 / 任何 bundle 分支 / 任何用户 逐字节相同，所以注入内容永远不会打断提供方的前缀缓存。
  • 会话层：当前 bundle（名 + 路径）+ 目录清单 + 各目录 APPEND_SYSTEM_PROMPT.md 规则， 走 runtime context 快照（宿主追加在会话尾部，内容未变则不产生新消息；切换分支 / 改规则才更新一条）。注入对象带 interpolate: false：APPEND 正文里的 {{...}} 保持字面量， 不会被宿主当作提示词变量解析。放进 system prompt 的代价是一字节变化就得重发整份 prompt， 在目标续跑等请求序列边界上更是整段前缀作废——故不放。
  • 概念计数不参与注入（每次写入都变的高频源），目录树与分支清单按需用 wiki_list / wiki_dirs 获取。
• 14 个工具：wiki_list / wiki_search / wiki_get（附 backlinks）/ wiki_create / wiki_update / wiki_validate / wiki_lint / wiki_ingest / wiki_deprecate / wiki_rules / wiki_help（机制文档自助查）/ wiki_dirs / wiki_use / wiki_sync。
• 两种在线后端（同一 wiki_sync 入口按 kind 分派）：
  • 本地目录 bundle → Git 远端（git.mjs：status/sync/init/clone，绝不 force push）；
  • 飞书云盘库 bundle（kind:'feishu'，云盘文件夹里存原生 .md）→ lark-cli（feishu.mjs： status/sync/pull/push/init，三方状态增量、只推改动文件、永不删两端、冲突停下报清单）。 身份自动选择：动作前读一次 auth status 的身份态（不做试探性读写）后挑 user/bot—— auto（默认：user ready 用 user，否则回退 bot）或锁定身份（不可用即报错、不回退）。 真删除：wiki_sync 的 delete 动作（v1 不同步删除，只删一侧必复活，故两侧一起删 + 清账本）； 只删显式 paths、另一侧有未同步改动即拒删、默认预演（apply:false）。
• 定时自动同步（默认关闭）：插件内在宿主进程里跑定时器，对飞书 bundle 按间隔自动 推拉（默认 5 分钟，最小 1、最大 1440）。只驱动飞书后端——Git 远端同步涉及合并，保持手动。 设置按机器存 ~/.agents/wiki-autosync.json（core autosync.mjs）；同一 bundle 不并发， 失败只记录不停表，冲突照旧停下报清单、绝不覆盖。
• 图形化配置（DSH 0.1.7-rc.2 起；0.2.1-rc.2 已复核）：浏览器半 lib/client.js 把同一个配置页注册进两个 slot—— settings.section（设置 → llm-wiki 知识库，一等区块）与 plugins.bundle.config （侧栏「插件」→ @sidleo3/dsh-wiki 页面，key = 包名）。四区：命名目录管理 / 在线同步（按后端显示 Git 或飞书状态）/ 定时自动同步（开关·间隔·身份·立即同步）/ 体检与索引；命名目录新增时可选「本地目录 / 飞书云盘库」， 并支持一键在飞书新建文件夹并注册。运行参数不提供界面编辑（部署级配置，改 profile 的 cordis.patch.yml）。 宿主半另注册 /api/dsh-wiki/* RPC（页面只走这些端点）。 0.1.7 起官方移除了「设置 → 插件 → 插件配置」Tab（settings.plugin.item 与设置命名空间钥匙一并作废）， 故 0.7.0 起要求 dsh >= 0.1.7-rc.2。
• 多目录（命名 bundle）：注册多个 wiki 目录并切换。wiki_dirs 查看分支； wiki_use <name> 会话级切换（按对话隔离，仅当前对话生效），global: true 持久化为全局默认（写注册表 ~/.agents/wiki-registry.json，新会话与 CLI/pi 生效）。
• 门控：写入前读目标目录 AGENTS.md 规则（wiki_rules），需 human 确认的类型经 agent 交互确认后带 verified（无代码强制弹窗；格式仍是纯 OKF）。

配置

数据目录默认 ~/.agents/wiki；用 id 定向补丁覆盖：

# cordis.patch.yml（profile 层）
- id: wiki-registry
  config:
    dataDir: /absolute/path/to/bundle
    sectionName: wiki-registry
    sectionOrder: 62
    maxSectionChars: 6000
    contextOrder: 130
    maxContextChars: 12000
    maxGetChars: 40000
    cacheTtlMs: 30000

多目录：config.dataDirs 声明命名 bundle（与注册表 ~/.agents/wiki-registry.json 合并，同名配置优先）：

  config:
    dataDirs:
      工作: /absolute/path/to/bundle-a
      个人: ~/notes/wiki

切换：wiki_use <name> [global:true]（会话级/持久化全局默认），wiki_dirs 查看。 也可以直接编辑注册表 ~/.agents/wiki-registry.json：

{ "bundles": { "工作": "/abs/path/a", "个人": "~/notes/wiki" }, "active": "工作" }

开发与测试

node --check wiki.mjs
node tests/dsh-mock-test.mjs        # 宿主无关 mock：14 工具注册 + 注入分层 + 门控 + 多目录 + 同步诊断（35 项）
node --test tests/dsh-config-test.mjs       # 配置页宿主半：/api/dsh-wiki/* + 飞书分派 + 定时同步 RPC（14 项）
node --test tests/feishu-backend.test.mjs   # 飞书云盘后端（假 lark-cli，25 项，含 user/bot 身份选择）
node --test tests/autosync.test.mjs         # 定时自动同步（配置持久化 + 调度器 + 冲突安全，17 项）
node --test tests/feishu-delete.test.mjs    # 真删除（只删点名路径 / 拒删未同步 / 预演默认 / 不复活，11 项）
node --test tests/dsh-client-bundle-test.mjs # 配置页产物契约（两个 slot）+ jsdom 渲染（8 项）

# 浏览器半构建（改 src/client/ 后必须重跑）
npm install && npm run build        # 产出 lib/client.js（tsdown，banner = __ModuleLoader__.load）
npm run typecheck                   # tsc --noEmit

# 本地迭代：profile 用仓库目录替换 registry 版本（改 host 半需重启 dsh web）
dsh plugin --profile web add link:/path/to/packages/dsh

依赖

宿主半运行时自包含（vendor-core 内嵌，npm run sync-vendor 从仓库 packages/core 同步）；独立引用 core 可用 @sidleo3/llm-wiki-core。浏览器半只依赖 React（平台基线模块，构建期 external，运行时由 loader 提供）；页面经 DSH 的 slots 服务注册，服务缺席时静默跳过。

许可

MIT