dsh-wiki-notes

dsh plugin --profile web add dsh-wiki-notes

dsh-wiki-notes


给你那堆 Markdown 笔记，接上四个能用的工具：查得到、读得出、核得住、看得见。

为 DeepSeek Harness 做的只读检索插件。旧的流程是五步：读总览 → 读索引 → 敲命令搜 → 打开那页 → 追它的来源。现在一次调用就把命中小节的完整正文 + 出处返回，模型自己接着答。

中文文档从下面开始。实测：73 页的库，旧流程单次 ≈ 18.7k 字符，新流程 ≈ 2.5k。

---

目录

你想知道 · 直接跳

这插件到底能干什么 · [四个工具](#四个工具)

我要先装上试试 · [装](#装) · [配](#配)

我自己的笔记该怎么写 · [库该长什么样](#库该长什么样)

检索为什么这么打分 · [检索质量](#检索质量)

它有没有偷看我的东西 · [只读，且不往外发](#只读且不往外发)

旧版本有没有遗留 · [发布物与残余风险](#发布物与残余风险)

已知毛病 · [已知局限](#已知局限)

要改代码 · [目录 / 开发](#目录--开发)

---

四个工具

插件注册四个工具，用途不重叠，按顺序读就明白了：

工具 · 一句话 · 什么时候用

wiki_recall · 检索库，拿到命中小节的正文与出处 · 「我的笔记里怎么写的？」

wiki_context · 检索 + 抽证据 + 标缺口 + 给回答约束，一次做完 · 要引用笔记原文回答，或想知道「依据够不够」

wiki_verify · 拿已有的 context 核验一段回答，不重新检索 · 答案写完了自查，特别是有数字的时候

wiki_observe · 查观察日志统计（调用次数、支持状态分布、违规类型） · 诊断，不参与回答

设置页里只有一个「知识库」入口，进去分两个页签：概览（路径、体检、提示词）和调用记录（谁在什么时候查了什么、查到没有）。后者不是工具，是那本账的界面。

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 · 库健康检查：孤儿页、断链名字、缺字段、别名冲突、久未更新、无出链、草稿、index 与磁盘不一致；并和上次体检对比，报出新增与已修 · limit（8，≤40）、staleDays（120）

draft · 把好答案回写成新页的落盘骨架（目录、frontmatter、index 行、log 条），不写文件 · title、type、tags、summary、sources

help · 用法与状态说明：七个 mode 各返回什么、status 各取值怎么读、参数默认值 · 无

{ "mode": "search", "query": "上下文 预算", "limit": 5 }

每条命中带 kind（note / raw-summary / source）、sources（来源数，证据强度的唯一可靠代理）、status、gist、section（命中小节正文，不是 90 字片段）、citation（← [[页名]] §小节 → 路径）、brokenLinks（指向不存在页的双链 = 「库里没依据」的硬信号），以及 updated 后面的距今天数（超过 180 天标「可能已过时」——三年前的结论和上周的长得一样，模型需要这个信号）。overview 额外给三项健康信号：index 有磁盘无、磁盘有 index 无、跨目录重名。

wiki_context —— 带证据的上下文

要引用笔记原文回答、或需要知道「有没有依据 / 依据够不够 / 哪里是缺口」时用它，而不是自己连续调 wiki_recall。

参数：query（必填）、limit（1–12，默认 5）、engine（both / search / wiki_recall，默认 both）、ttl_seconds（默认 1800）。

返回里最重要的一条：status.support 和 status.degraded 是两件事，必须分开看。

• support 说的是知识够不够（sufficient / partial / insufficient）。
• degraded 说的是引擎有没有坏。它是布尔值，为真时说明某个检索通道挂了 —— 这时候不能把 support 当结论，那是拿不完整的检索结果下的判断。

同时返回 evidence（证据页，含分级、支撑了哪个槽位）、missing（缺什么、为什么缺）、conflicts（冲突候选，未裁决，别当成已确认的结论）、answer.contract_text（给回答的约束：必须披露缺口、不得超出证据、引文须原文），以及一个 context_id。

wiki_verify —— 核验回答

写完答案后自查（尤其含数字、范围、年份、题量分值这类主张时）用它。参数：context_id + answer（可选 observe_id，一般不用传，插件会自动带上）。

它不重新检索 —— 拿当初那份快照来比，所以快，也不受库里后来改动的影响。

返回 status 与 violations：violations 非空说明回答越过了证据允许的边界，每条都带类型、主张和原因。另有 notices 单独放「说不清」的提示 —— 「说不清」不等于「说错了」，模型若只读 violations 会漏掉这一块。

context_expired / context_missing 是快照问题，不等于回答错了：重新取一份 context 再核验就行。

每次核验都会往观察日志追加一条记录，并用 parent_observe_id 指回当初那份 context —— 这样「哪次核验修好了哪次回答」在日志里追得回。

wiki_observe —— 诊断

参数：days（1–365，默认 7）、limit（1–50，默认 10）。

报观察窗口内的调用次数、支持状态分布、检索状态分布、违规类型分布，还有修正情况（核验过的 context 里已改正 / 仍未改正的比例）—— 这一项比违规总数更能反映核验到底有没有用。只读诊断，不参与回答，也不改检索行为。

⚠️ 它只看网关那三次调用（wiki_context / wiki_verify）。wiki_recall 不走 Python，也就不写观察日志 —— 要看全部调用，去「知识库」页的「调用记录」页签。

调用审计 —— 「知识库」页的「调用记录」页签

在设置页的「知识库」里切到第二个页签。模型和面板每一次查库都会记一行，回答的是「我这句问话，它到底查了没有、查到没有」。

三格数字（今日调用 / 命中率 / 零命中）+ 一张表（时间 · 来源 · 工具 · 问题 · 命中 · 耗时）+ 筛选（全部 / 模型 / 面板、只看零命中）。页面每 2 秒自己刷新。

账本落在插件目录旁的 calls.jsonl（已在 .gitignore 里），只记 8 个字段：

ts · source · tool · mode · query · hits · ms · ok

页面路径、正文、答案一律不进账本。 query 截到 120 字。

几条口径值得写清楚：

• 命中率的分母不含 wiki_verify / wiki_observe，也不算 page / list 这类非检索模式 —— 它们没有「命中几页」这回事，记成 0 会把命中率系统性压低，所以记 null，不进统计。
• 它只能看见「发生了的调用」。模型压根没想起来查库，这里也不会有记录 —— 那是一种缺席，账本记不了缺席。要统计「哪类问题从来不查库」，得去读会话转录（本插件不读）。
• 记满 5000 行轮转一次，只留最近 2500 行；读取只扫文件尾部 256 KB。
• 记账是旁路：写不进去只打一行警告，工具的返回值一个字都不改。calls.enabled 可以整个关掉。

---

设计从哪来

库结构来自 Karpathy 的 llm-wiki.md：与其每次提问都从原始文档重新检索（知识不累积），不如让 LLM 增量维护一个持久的 wiki。本插件只加速其中的 Query 一段。

gist 里的概念 · 本插件默认位置

Raw sources（不可变） · 原始资料-raw/

The wiki（LLM 维护） · 知识层-wiki/

The schema · 库根 AGENTS.md

index.md + log.md · 同名同格式

---

库该长什么样

一个目录 + 一堆 .md 就能用。 更细的约定见 [docs/库结构.md](docs/库结构.md)：frontmatter 七字段（英文写法 title/type/tags/aliases/status/created/updated/sources 也认）、index.md 摘要目录、log.md 时间线、总览-overview.md，满足得越多检索越准。可跑的样例在 [examples/sample-wiki/](examples/sample-wiki/)。

路径指到上一层（比如 LLM-Wiki/，里面还有 原始资料-raw/ 和 知识层-wiki/）也没关系：插件会认 index.md，自动下钻到知识层，并在返回里注明它实际读的是哪一层。

---

装

在 DSH 里说一句即可：「帮我装一个 DSH 插件，目录是 <绝对路径>」。或自己发：

plugin_manager { action: "install_bundle", target: "<绝对路径>" }

返回 application: applied 就生效，不用重启。但改插件自己的代码要重启 DSH：lib/*.js（宿主半）和 lib/client.js（设置页）都一样，已载入的模块不会因为关开插件而重新求值。

---

配

设置 →「知识库」，填路径 → 测试 → 保存。四层优先级：

优先级 · 来源

1 · 插件 config 的 root

2 · 环境变量 DSH_WIKI_ROOT

3 · wiki-notes.config.json（设置页写这里）

4 · lib/config.js 的 DEFAULT_WIKI_ROOT（默认空）

没配时工具会直接告诉你「还没配置知识库路径」，不会静默扫空目录。

wiki_context / wiki_verify / wiki_observe 还需要一条 Python 通路（bridge.python + bridge.toolsRoot，后者是含 wiki_bridge.py 的目录）。没配的话这三个工具会明确报 E_PYTHON_UNAVAILABLE —— 不会假装成「知识库里没有」。配置形状见 [docs/契约-stage0/阶段4-插件接入.md](docs/契约-stage0/阶段4-插件接入.md)。

---

模型怎么知道该查库

插件会从你库里现有的 标签 算出主题词，注入一行（约 50 token，例如「本地知识库主题：上下文工程、ai、agent…」）。不带页数 —— 页数一变就会打掉提示词的前缀缓存，而它对「该不该查」没有帮助。换库自动变，所以问题沾这些主题时它自己会去查，不用你提醒。设置页里可以关掉（不占上下文）、换成自己的整段、或在末尾追加一句，改完下一回合生效。

主题词怎么挑：跳过 总览/index 这类结构页，跳过 数据/工具/meta 这类空泛标签，默认只留出现 ≥2 次的标签（设置页可改回 ≥1）。全被滤掉时退回不过滤的前五 —— 小库不至于一条提示都没有。

---

设置页

设置 →「知识库」。状

…(truncated)