前言¶
在 DeepSeek Harness（DSH）里让模型用本地 Markdown 笔记库，常见流程是：读总览、翻 index、再 shell 跑检索脚本、打开页面、追来源——多步往返，上下文也容易被整页或长摘要撑满。维护者 xyzOvO 的 dsh-wiki-notes 把这一段收成 只读 工具 wiki_recall：一次调用返回命中小节的完整正文和页级引用，另带目录浏览、库健康检查与回写骨架（不写盘）。README 里对 73 页样例的对比是：旧流程单次约 18.7k 字符，新流程约 2.5k。
这是什么¶
Read-only Markdown knowledge-base retrieval for DeepSeek Harness——面向 DSH 的本地 Markdown 笔记库检索插件（当前 package 版本 1.1.3，MIT）。
设计思路来自 Karpathy 的 llm-wiki.md：持久 wiki 由 LLM 增量维护，本插件只加速其中的 Query 段。默认目录约定包括 原始资料-raw/、知识层-wiki/、根目录 AGENTS.md，以及 index.md、log.md；路径指到上一层（例如含 raw 与 wiki 的 LLM-Wiki/）时，插件会认 index.md 并自动下钻到知识层，返回里注明实际读取层级。
核心功能¶
wiki_recall 七种 mode¶
| mode | 作用 | 主要参数 |
|---|---|---|
search（默认） |
关键词 AND 检索 | query、limit（默认 5，≤12）、sectionChars（默认 900，≤3000） |
page |
按页名/别名取整页 | name、pageChars（6000） |
list |
按类型/标签/状态列目录 | type、tags、status、limit（40，≤200） |
overview |
总览、规模、最近日志、健康计数 | pageChars（4000）、logLimit（5，≤20） |
lint |
孤儿页、断链、缺字段、别名冲突等；与上次体检对比 | limit（8，≤40）、staleDays（120） |
draft |
生成新页落盘骨架（目录、frontmatter、index 行、log 条），不写文件 | title、type、tags、summary、sources |
help |
各 mode 与 status 说明 |
无 |
search 每条命中含 kind、sources（证据强度代理）、section（小节全文而非短片段）、citation（← [[页名]] §小节 → 路径）、brokenLinks、updated 距今天数（超过 180 天标可能过时）等。插件还会从库内标签注入一行主题提示（约 50 token），可在设置页关闭或自定义。
设置页与实时同步¶
DSH 设置 →「知识库」：填路径、测试、保存。浏览器侧走同源 HTTP /api/wiki-notes/*（state / check / save / rescan）。对库根目录 fs.watch 监听 .md 变更，400ms 防抖后作废缓存；监听失败则退回 30 秒 TTL。Linux 上递归监听需 Node ≥ 20.13.0（与 engines 一致）。
命令行（不装插件也可）¶
仓库提供 bin/cli.mjs 与 wiki-notes bin，便于本地验证检索。
安装与启用¶
DSH 生态里插件常以 bundle 形式安装，不要凭仓库名自行拼接未在文档出现的 dsh plugin add 命令。README 给出的两种方式如下。
在 DSH 里说明要安装的插件目录绝对路径，例如：「帮我装一个 DSH 插件，目录是 <绝对路径>」。
或自行调用：
plugin_manager { action: "install_bundle", target: "<绝对路径>" }
返回 application: applied 即生效，无需重启。修改 lib/*.js 后关开插件可热重载；改 lib/client.js（设置页）需重启 DSH。
安装前请自行查看 GitHub 仓库 源码与 MIT 许可证；插件以当前 DSH 进程权限读取你配置的路径，只读不写库。
配置知识库路径¶
四层优先级（高到低）：
| 优先级 | 来源 |
|---|---|
| 1 | 插件 config 的 root |
| 2 | 环境变量 DSH_WIKI_ROOT |
| 3 | wiki-notes.config.json（设置页写入） |
| 4 | lib/config.js 的 DEFAULT_WIKI_ROOT（默认空） |
未配置时工具会明确提示「还没配置知识库路径」，不会静默扫空目录。
典型用法¶
工具调用示例（JSON 参数）：
{ "mode": "search", "query": "上下文 预算", "limit": 5 }
本地 CLI（README 样例库）：
node bin/cli.mjs search 上下文 --root=examples/sample-wiki
更细的 frontmatter 七字段、index.md / log.md / 总览-overview.md 约定见仓库 docs/库结构.md；可跑样例在 examples/sample-wiki/。
适用场景与注意¶
适合：已按 wiki 结构维护本地 Markdown（含 Obsidian 双链习惯）、希望在 DSH 对话里少步数、小节级召回并带出处与健康信号的团队或个人。
局限（README 自述）：中文不分词，靠空格与 别名；页名即查询词时选节可能偏；每次调用全量扫描，70–100 页量级尚可，再大需增量索引；只读，不修红链、不改页。
可选上下游：网页剪藏进 raw 层可用 Obsidian Web Clipper；维护 wiki 语法可参考 kepano/obsidian-skills。
社区目录页：skillhub.cn 上的 dsh-wiki-notes（独立站点，与 DeepSeek / 幻方无官方从属）。源码与 issue：https://github.com/xyzOvO/dsh-wiki-notes。
结尾¶
dsh-wiki-notes 把「查本地 wiki」从多步读文件收成 wiki_recall 一次返回小节正文与 citation，并附带 overview、lint、draft 等辅助 mode。配好路径并在设置页测试通过后，模型在主题词命中时会更容易主动查库；需要写回页面仍要由你或别的工具完成，本插件 deliberately 保持只读。
