dsh-llm-wiki

English

一个按工作区隔离、本地优先的 DeepSeek Harness LLM Wiki 插件。它从当前 Harness 工作区导入文本，构建可随时重建的本地索引，并向主 agent 提供显式工具，用于检索和维护有来源依据的 Wiki 页面。

核心能力

• 使用 exec.agent.session.header.cwd 的 canonical realpath 隔离不同工作区的数据。
• 以 Markdown 和文本文件为事实源；PGlite 索引可删除并重新构建。
• 使用确定性的 384 维 feature-hashing embedding、PostgreSQL 全文检索、CJK 子串回退及 [[wikilink]] 图信号，并通过 RRF 融合排序。
• 根据 Wiki 链接和同页实体共现确定性生成关系图。
• 由 Harness 主 agent 维护 Wiki，不发起隐藏的嵌套模型调用，因此模型输入与输出保留在正常 session log 中。
• 通过 read-before-write SHA-256 检查防止意外覆盖。

环境要求

• Node.js ^22.19.0 或 >=24.0.0
• DeepSeek Harness 0.1.0-rc.6 或兼容版本
• pnpm 11

从 GitHub 安装

安装到一个 Harness profile：

dsh plugin --profile headless add github:wangning19940904/dsh-llm-wiki

仓库包含 TypeScript 源码，GitHub 安装时通过 prepare 生成 dist/。pnpm 会阻止未经审核的依赖构建脚本；如果安装提示插件构建被忽略，请先审核，然后在该 profile 的 pnpm-workspace.yaml 中加入以下配置并重新安装：

allowBuilds:
  dsh-llm-wiki: true

随包提供的 bundle patch 会挂载 dsh-llm-wiki，并将 dataRoot 默认设置为 dshHomePath('llm-wiki')。

工具工作流

1. llm_wiki_search 在 agent 回答前检索已有知识。 2. llm_wiki_import 将当前工作区内的相对路径 .md、.markdown 和 .txt 文件复制到 raw/docs。 3. llm_wiki_ingest 增量更新派生索引。发现新增或变化的来源后，会向 agent 附加一条已记录的维护提醒。 4. agent 使用 llm_wiki_read 阅读来源，并通过 llm_wiki_write 在 wiki/sources、wiki/entities 或 wiki/concepts 下维护有来源依据的页面。 5. llm_wiki_graph 浏览实体、提及页面、关系以及最多三跳的图路径。

搜索结果包含插件内相对路径、来源行号、摘要、融合总分和各路信号分数。写入成功后会立即更新索引。

数据目录

每个 canonical workspace 使用独立目录：

<dataRoot>/workspaces/<workspace-id>/
├── workspace.json
├── purpose.md
├── schema.md
├── raw/docs/
├── wiki/
│   ├── index.md
│   ├── log.md
│   ├── sources/
│   ├── entities/
│   └── concepts/
└── .index/

raw/docs 与 wiki 是持久知识；.index 只保存 PGlite 派生数据，可以安全删除。下一次不带 paths 的 llm_wiki_ingest 会重建索引。

配置

内置 patch 提供以下默认值：

- insert:
    - id: llm-wiki
      name: dsh-llm-wiki
      config:
        dataRoot: !!js dshHomePath('llm-wiki')
        chunkSizeChars: 1600
        chunkOverlapChars: 200
        embeddingDimensions: 384
        importMaxFiles: 50
        importMaxBytesPerFile: 2000000
        readMaxBytes: 100000
        searchDefaultLimit: 8
        searchMaxLimit: 20
        rrfK: 60
        vectorWeight: 1
        keywordWeight: 1
        graphWeight: 0.6
        maintenanceBatchSize: 5

正整数约束、非负有限权重、overlap 小于 chunk size、默认 limit 不超过最大 limit 都会在加载时校验；错误配置会阻止插件激活。

安全限制

• 所有工具都要求 agent session 提供 cwd，否则返回 WIKI_WORKSPACE_REQUIRED。
• 导入会拒绝绝对路径、目录穿越、目录、通过符号链接解析到工作区外的文件、不支持的扩展名、无效 UTF-8、含 NUL 的二进制内容及超过配置限制的文件数量或大小。
• 读取仅允许 raw/docs 和 wiki，并受 readMaxBytes 限制。
• 写入仅允许 wiki 下的 Markdown 文件。新建页面无需 digest；替换页面必须提供最近一次 llm_wiki_read 返回的 digest。未观察和过期写入分别返回 WIKI_NOT_OBSERVED 与 WIKI_STALE。
• Cordis 插件卸载时会关闭所有数据库句柄。

MVP 范围

本版本不包含 Web UI、MCP server、trace、后台模型任务、PDF/图片转换、独立 CLI 或 npm 发布，仅支持本地 UTF-8 Markdown 与文本文件。Feature-hashing embedding 优先保证离线和确定性，其语义质量不等同于神经网络 embedding 模型。

开发与验证

pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm pack
pnpm verify:package

verify:package 会打包项目、将 tarball 安装到临时 Harness profile，并确认 --dump-config 已挂载插件。

License

MIT