dsh-openwiki

dsh plugin --profile web add dsh-openwiki

<p align="center">

<strong>简体中文</strong> | <a href="README.en.md">English</a>

</p>

dsh-openwiki

DSH 插件：把 openwiki 的代码库知识库能力搬进 DeepSeek Harness —— 一键生成 / 阅读 / 更新仓库 Wiki 与 Grounded Claims（溯源知识卡片），直接复用 DSH 已配置的模型，无需二次填 Key。

dsh-openwiki 是 DeepSeek Harness（Cordis 全插件架构）的 Web profile 包插件：Host 半部托管 openwiki CLI 运行时并驱动生成任务，Client 半部在 DSH 主界面提供知识库入口、浮动窗口、目录树、文档阅读等交互。核心思路是把 openwiki 当作增量生成引擎（命令行 + 磁盘产物契约），DSH 侧负责 UI、任务编排、模型桥接与触发器。

---

📑 目录

• [🚀 安装](#-安装)

• [🛠️ 开发与维护](#-开发与维护)

• [✨ 功能一览](#-功能一览)

• [🧱 架构设计](#-架构设计)

• [🖼️ 特性巡礼](#-特性巡礼)

• [🧠 关键逻辑](#-关键逻辑)

• [📡 RPC API](#-rpc-api)

• [⚠️ 已知限制](#-已知限制)

• [🧪 验证脚本](#-验证脚本)

---

🚀 安装

前置依赖：Node ≥ 20、openwiki CLI（插件可自动安装）、DSH 已配置模型与凭证。

方式一：npm 包（推荐）

dsh plugin --profile web add dsh-openwiki

方式二：本地源码

# 1. 获取源码到本地任意目录（下文以 <源码目录> 指代）
git clone <仓库地址> <源码目录>

# 2. 构建产物（lib/ 与 client/）
cd <源码目录>
npm run build

# 3. 以本地目录方式安装到 DSH web profile
dsh plugin --profile web add <源码目录>

安装后配置（两种方式相同）

# 编辑 <你的 DSH 用户目录>\profiles\web\cordis.patch.yml，追加：
# - id: dsh-openwiki
#   name: 'dsh-openwiki'
# 重启 dsh web

说明：

* 本地目录方式安装时，dsh plugin add 会在 profile 的 node_modules 下建立指向 <源码目录> 的链接（pnpm 目录安装默认行为），改源码 + npm run build 后重启 dsh web 即生效

* dsh.profile.bundles 需含 dsh-openwiki（dsh.client manifest：platform web，peerDependency schemastery）

---

🛠️ 开发与维护

目录结构

<源码目录>/
├── src/host/index.js        # Host 权威源码（动态/包共用）
├── src/client/index.js      # Client 权威源码
├── scripts/build-host.mjs   # → lib/index.js（ESM 入口）
├── scripts/build-client.mjs # → client/client.js（ModuleLoader bundle）
├── lib/  client/            # 构建产物
├── tests/                   # Playwright / 离线验证脚本 + screenshots/
└── package.json             # dsh.client manifest（platform web）

<br />

面向 AI 的注意事项

• 构建脚本改写：build-host 把 harness.handle 换成 rpc.handle 并注入 webServer/settings；build-client 把 host.call 换成 rpc.call。新增 Host handler 用 harness.handle(...)，新增 Client 交互用 host.call(...)，构建自动适配

• readBytes 限制：fs.readBytes 超限会抛错（不是截断）——读文件头用 readText + slice

• manifest 缺失是常态：所有 wiki 读取都要走 disk-scan fallback（readWikiTree/readWikiOverview/readWikiClaims）

• shim EPERM：Windows 下不要 spawn .cmd，解析 shim 内脚本路径直接 spawn node

• not found 静默：可选状态文件缺失（.page-manifest.json/.run.json/.last-update.json）不要 console.error，否则轮询刷屏

• settings 命名空间：settings.register('openwiki', schema) 依赖 @deepseek-ai/schemastery，从 profile 动态 import 可能失败（settings namespace skipped）——不依赖它，用内存态 + localStorage

• client 服务注册表每次刷新重建：better-sidebar 注册必须自动重注册（autoRegisterSidebar），不能依赖用户点击

• openwiki 无 git 触发器：自动更新靠插件轮询 git rev-parse HEAD

• 非 git 仓库无法生成：startJob 前置校验已拦截并报明确错误

• Markdown 渲染：fence 检测必须 startsWith('`')（见「🧠 关键逻辑」死循环教训）

• 性能：空闲轮询只刷 jobs + overview（轻量），有运行任务才全量 refreshWorkspace；避免每 3s 全量磁盘扫描

---

✨ 功能一览

• 📚 知识库入口：DSH 主界面左下角「设置」上方「openwiki知识库」入口（可关闭，localStorage 持久化），点击打开可拖拽/可缩放的浮动窗口；另有「conversation.view」会话视图 Tab 与 better-sidebar 侧边页面两种嵌入形态。工作区列表每次打开知识库/点击「刷新」都实时重新拉取（新增工作区无需刷新页面）

• 🗂️ 三模式视图：Open Wiki（仓库 Wiki 文档树）、知识卡片（Grounded Claims 溯源抽点）与 知识库（personal 模式个人知识库）三个常驻 Tab，选中高亮；另有「忽略文件」「刷新」按钮；左栏宽度可拖动调整

• 🧠 知识库（personal 模式）：第三个 Tab「知识库」——上传本地文件（文本格式，含文件类型提示；新增/删除文件的行为说明见「生成知识库」按钮下方）生成个人知识库，输出到 <项目>/openwiki-kb/wiki（OPENWIKI_CONFIG_DIR 注入），树形阅读复用文档视图；模型凭据单点化：从 ~/.openwiki/.env 注入子进程，项目内不重复配置，openwiki-kb/ 一条 gitignore 排除全部 personal 产物

• 📄 文档阅读：预览 / 代码双视图 + 目录分栏（点击「目录」在工具栏下方分出左侧目录面板，独立竖滚动条、sticky 不随正文滚动；点条目平滑滚动到对应标题）

• 🗂️ 知识卡片：Grounded Claims 溯源抽点（statement + evidence），点「知识卡片」Tab 查看

• 🔗 应用内链接导航：md 内链（含 /openwiki/... 绝对路径）点击后在应用内跳转，绝不把浏览器带走到 file://；目录链接（尾 /）进入文件夹浏览

• ⚡ 生成任务：生成 / 重新生成（增量更新）/ 取消，实时进度（已完成 X/Y (Z%)，处理中: N，失败: M），断点续跑依赖 openwiki 的 .run.json；非 git 仓库明确报错

• 📊 生成状态卡：右侧展示文件数 / 成功 / 失败 / 更新时间 / 文档位置（openwiki/）与「重新生成」按钮

• 🔌 模型复用：读取 DSH 默认模型（agentDefaultModel）与凭证，映射为 openwiki 的 provider 配置写入 ~/.openwiki/.env（openai-compatible / anthropic / gemini / openrouter）

• 🖥️ 运行时托管：自动检测 openwiki CLI（解析 npm shim）、版本检查（registry）、安装 / 升级 / 自检（--help）

• 🔔 自动更新：轮询各工作区 git HEAD，检测到新提交自动跑增量更新（openwiki 无原生 git 触发器，由插件补上）；安装后默认对所有工作区开启——开关在知识库面板左栏「刷新」旁（仅 Open Wiki Tab 显示，知识卡片/知识库不涉及），按工作区独立，手动关闭某个工作区后不会自动重开

• 🧩 better-sidebar 集成：检测到 dsh-better-sidebar 服务即自动注册一个侧边页面（刷新后自动重注册，等效持久化）；未安装时设置页给出安装指引

• 🛡️ 忽略文件：.openwikiignore（gitignore 语法）图形化编辑保存

• ⚙️ 设置页：运行时 / 模型 / better-sidebar 注册 / 入口显隐（自动更新开关已移至知识库面板，按工作区独立）

🔌 核心理念：openwiki 是 CLI 引擎，DSH 是宿主。一切状态（openwiki/ 目录下的 .page-manifest.json / .run.json / .last-update.json / .claims/）都是磁盘契约，插件只做读取 + 展示 + 触发，不干预生成算法本身。

---

🧱 架构设计

双半结构（Host / Client）

Cordis 插件分两半，各自有权威源码，构建脚本生成包产物：

半部 · 权威源码 · 构建产物 · 职责

Host · src/host/index.js · lib/index.js（ESM 入口） · openwiki 运行时托管、模型桥接、生成任务、wiki/claims 磁盘读取、忽略文件、自动更新、RPC 服务端

Client · src/client/index.js · client/client.js（Web ModuleLoader bundle） · 全部 UI：入口、浮动窗口、目录树、文档渲染、设置页、better-sidebar 注册

构建脚本（scripts/build-host.mjs / build-client.mjs）把源码中的自由标识符改写为包形态：

• Host：harness.handle( → rpc.handle(；lib/index.js 注入 webServer/settings 硬依赖并注册 /dsh-openwiki/rpc 同源 JSON-RPC

…(truncated)