dsh-llm-wiki

DeepSeek Harness 插件：让 agent 直接管理 LLM-Wiki 个人知识库——检索、阅读、统计、校验、修复、错误本、入库，共 7 个工具。

@detpecca/dsh-llm-wiki 是一个薄适配层，不重复实现任何检索/编译逻辑：

DSH agent ──调用工具──▶ 本插件（ToolDefinition × 7）
                          │ ctx.subprocess.spawn
                          ▼
                python -m llm_wiki --wiki <路径> <子命令> --json
                          │
                          ▼
              LLM-Wiki 引擎（检索打分 / 算法 1 编译 / 校验修复的唯一权威）
                          │
                          ▼
                     你的 Wiki 目录

• 每个工具通过 DSH 的 subprocess 服务调用 LLM-Wiki 引擎 CLI 的 --json 通道；
• Wiki 自己的结构化信号检索（页名/别名/标签/摘要加权打分）和论文算法 1 编译流程保持唯一权威；
• 插件本体零运行时依赖（纯 ESM，无构建步骤），Node ≥ 18。

前置要求

1. 已安装 DeepSeek Harness（dsh 命令可用，或有其仓库 checkout）；
2. Python ≥ 3.10（供引擎使用）；
3. （可选）一个 OpenAI 兼容的 LLM API key——只有 wiki_ingest 和 wiki_fix {finalize:true} 需要。

🚀 快速开始

两条命令，不需要克隆任何仓库。

1. 安装 Python 引擎（LLM-Wiki）

pip install git+https://github.com/detpecca/LLM-Wiki.git
# 唯一运行时依赖是 pyyaml

2. 安装本插件

dsh plugin --profile web add @detpecca/dsh-llm-wiki

还没发布 npm 时，直接从 GitHub 装（本插件无构建步骤，git 安装即可用）：
dsh plugin --profile web add github:detpecca/dsh-llm-wiki

3. 配置知识库路径

安装默认指向 ./wiki。把实际路径写进 profile 的 cordis.patch.yml
（$DSH_HOME/profiles/<name>/cordis.patch.yml，$DSH_HOME 默认为 ~/.dsh），
按 id 覆盖并重述全部键（patch 是整行替换，不是深合并）：

- id: llm-wiki
  config:
    wikiPath: D:/path/to/your/wiki   # 你的知识库根目录
    pythonPath: python               # python 可执行文件（引擎已装进它的 site-packages）
    cwd: ''                          # 留空用宿主 cwd；llm_wiki 需可从 cwd 导入（pip 装过即可）
    # —— 以下三项可选：wiki_ingest / wiki_fix finalize 的 LLM 配置，显式配置优先于环境变量 ——
    llmWikiBaseUrl: https://api.moonshot.cn/v1
    llmWikiApiKey: sk-xxx            # 或改用环境变量 LLM_WIKI_API_KEY
    llmWikiModel: kimi-k2-0711-preview

重启 DSH 后，agent 即可调用全部 7 个工具。

Windows：一键安装脚本

在插件仓库里直接跑（本地无引擎 checkout 时自动从 GitHub 装）：

.\scripts\install.ps1 -WikiPath D:\你的知识库 -ApiKey sk-xxx

脚本自动完成：uv 建 venv → 装引擎 → dsh plugin add → 把配置（含 key）写进
profile 的 cordis.patch.yml。详情 Get-Help .\scripts\install.ps1。

知识库初始化

知识库为空时，可以让 agent 直接 wiki_ingest 你的第一份笔记，或先用引擎 CLI 编译：

python -m llm_wiki --wiki ./wiki ingest my_notes.txt

（--wiki 必须放在子命令之前。更多 CLI 用法见
LLM-Wiki README。）

卸载

dsh plugin --profile web remove @detpecca/dsh-llm-wiki

工具参考

工具	作用	需要 LLM key？
wiki_search	结构化信号打分检索（CJK 分词）	否
wiki_read	批量读页 / 目录索引，跟随 [[wikilink]]	否
wiki_stats	页面/分类/digest/错误本统计	否
wiki_validate	4 类确定性结构校验	否
wiki_fix	确定性修复；finalize:true 追加 LLM 修复轮	否（finalize 需 key）
wiki_errorbook	查看 Error Book（自我纠错记录）	否
wiki_ingest	把源文本编译入库（算法 1 全流程）	是

wiki_search — 检索（第一跳）

• 参数：query（必填；实体名/别名匹配最好）、limit（默认 10）
• 返回：{ hits: [{ path, score, aliases, tags, summary }] }，score 是整数权重
  累加（页名 8 > 别名 6 > 标签 4 > 摘要 2 > 正文 1），越高越强，非相似度

wiki_read — 批量读页

• 参数：paths（必填，数组）：wiki 相对路径、不带 .md，如 concepts/retrieval、
  目录索引 concepts/_index、根索引 index、digest sources/digests/s-001
• 返回：{ pages: { path: content } }；缺失页值为 (page not found)，
  不安全路径值为 (invalid or unreadable path)
• 页面正文含 [[wikilink]]，多跳问题让 agent 跟随链接继续读

wiki_stats — 统计

• 返回：{ pages, categories: {分类: 数量}, digests, errorBookEntries }

wiki_validate — 结构校验（只读）

• 返回：{ ok, errors: [{ type, page, detail }] }
• 4 类确定性检查：悬空链接 / 不完整页面 / 畸形来源引用 / 索引不一致
• 第 5 类 unseen_overwrite 是编译期检查，只在 wiki_ingest 内部触发，不在本工具
• 有错误时引擎 exit 1，插件已按"结果而非失败"处理，放心调用

wiki_fix — 修复（wiki_validate 的搭档）

• 参数：finalize（默认 false）
  • false：只跑确定性修复——重建目录/全局索引、补双向 [[wikilink]] 回链，
    无需 LLM key；
  • true：追加论文 §3.3 定稿流程（3 轮 代码↔LLM 修复 + 跨页一致性扫描 +
    Error Book Verify & Close），较慢且需 LLM key
• 返回：{ codeFixes, finalized, repaired, closedErrorEntries, openErrorEntries }
• 典型闭环：wiki_validate 发现问题 → wiki_fix → 再 wiki_validate 确认

wiki_errorbook — 错误记录本（只读）

• 返回：{ entries: [...] }，条目含 id / status / type / page / occurrences /
  constraint_rule 等

wiki_ingest — 编译入库

• 参数：file（必填）：源文本文件路径，相对 DSH 宿主 cwd 解析
• 返回：{ source, passages, written, pages, openErrorEntries, skipped }
• 需要 LLM 配置（见下）；建议跑完后接 wiki_validate 确认健康

配置项

键	默认	说明
wikiPath	./wiki	wiki 根目录（含 index.md）
pythonPath	python	python 可执行文件
cwd	''（宿主 cwd）	子进程工作目录；llm_wiki 包需可导入
llmWikiBaseUrl	''（回落环境变量）	ingest/finalize 的 OpenAI 兼容端点
llmWikiApiKey	''（回落环境变量）	ingest/finalize 的 API key
llmWikiModel	''（回落环境变量）	ingest/finalize 的模型名

LLM 配置的优先级：每个键独立判断——cordis.patch.yml 里的显式值 >
环境变量 LLM_WIKI_BASE_URL / LLM_WIKI_API_KEY / LLM_WIKI_MODEL > 不设置
（此时 wiki_ingest / finalize 会以清晰错误失败）。查询类工具不需要第二套
LLM key——遍历推理由 DSH 宿主的 agent 模型自己完成。

使用示例（对 agent 说）

• 「把 D:\notes\transformer.md 收录进我的知识库，然后校验一下」
• 「我知识库里关于注意力机制都讲了什么？给出依据页面」
• 「检查一下知识库结构有没有问题，有就修好」
• 「错误本里最近记录了什么？为什么会反复出现？」

故障排查

症状	原因与处理
No module named 'llm_wiki'	引擎没装进 pythonPath 指向的解释器。按快速开始第 1 步安装；插件报错信息里也自带此提示
wiki_ingest 报缺 API key	配 llmWikiApiKey 或环境变量 LLM_WIKI_API_KEY；查询类工具不受影响
改动了 wiki 但搜索/统计没变化	重启 DSH 使配置生效；若是手动编辑了 wiki 文件，跑 wiki_fix 重建索引（建议始终通过工具修改 wiki）
wiki_validate 报错但 wiki_fix 修不掉	结构性问题之外的错误（如坏链接改写）需要 wiki_fix {finalize:true}（需 LLM key）
子进程输出被截断	stdout 上限 2MB、stderr 200KB，正常检索/入库不会触及

开发与测试

# 真实驱动 Python CLI 的端到端测试（10 个用例）
LLM_WIKI_PYTHON="path/to/python.exe" LLM_WIKI_ROOT="path/to/LLM-Wiki" node --test test/run.test.js

• LLM_WIKI_PYTHON：装了 pyyaml 的 python（默认 python）
• LLM_WIKI_ROOT：LLM-Wiki 引擎 checkout 根目录（默认 ../LLM-Wiki）

相关仓库

• LLM-Wiki — 本插件调用的 Python 引擎，
  也是论文《Retrieval as Reasoning: Self-Evolving Agent-Native Retrieval via LLM-Wiki》
  的原始实现（CLI 参考、wiki 目录结构、论文映射见其 README）；
• deepseek-harness — 宿主；
• DSH-Wiki — ⚠️ 已废弃的引擎 fork，功能已并回
  LLM-Wiki，请勿再使用。

许可证

MIT（见 LICENSE）。