dsh-knj-obsidian

dsh plugin --profile web add dsh-knj-obsidian

dsh-knj-obsidian

DSH（DeepSeek Harness）内简化版 Obsidian：为 AI agent 提供项目级知识库（wiki）的构建能力。agent 通过工具把对话、文档、网页等源材料蒸馏为结构化知识页，落盘到项目根目录的 .wiki/，形成可复用、可维护的知识资产。

当前版本为 v1 构建核心 + v2 检索 + v3 图谱导出 + v4 UI + v5 笔记编辑：写入侧（ingest / capture / lint）已完整；检索侧提供 wiki_query 工具与 wiki-query skill 双通道（见下文「v2：检索」）；图谱侧提供 wiki_export 工具导出交互图谱与结构化图数据（见下文「v3：图谱导出」）；UI 侧提供右侧边栏"知识库"标签 + 笔记/图谱工作台（见下文「v4：UI」）；v5 起笔记工作台支持富渲染、双链原地跳转、源码视图与全文编辑（见下文「v5：笔记编辑」）。

安装方式

需要 Node.js ≥ 20，且已安装 DSH 宿主（提供 dsh CLI 与 web profile）。

# 1. 在插件目录内打包
npm pack

# 2. 在插件目录内执行：安装到 DSH 的 web profile
dsh plugin --profile web add ./dsh-knj-obsidian-2026.8.257.tgz

# 3. 重启 DSH，确认宿主日志无 dsh-knj-obsidian 相关报错

安装后插件在 DSH 启动时自动向 agent 暴露工具（wiki_ingest / wiki_capture / wiki_normalize_tags / wiki_lint / wiki_query / wiki_drill / wiki_read / wiki_export / wiki_mine / wiki_init / wiki_checkpoint / wiki_checkpoints / wiki_search_semantic），并随包分发 5 个 wiki-* skill，无需额外配置。

宿主兼容（重要）

从 2026.11.12 起，本包不再声明 @deepseek-ai/dsh-llm / @deepseek-ai/dsh-tools 的 peerDependencies。

原因：DSH 至今没有任何正式版，latest 一直是 0.2.1-rc.5 这类预发布版；而 semver 规定预发布版只能被同一 x.y.z 上的预发布比较符命中，因此 >=0.1.2-rc.1 <0.3.0-0 这种写法永远放行不了 0.2.1-rc.5——npm 安装期必然报：

npm error code ERESOLVE
npm error peerOptional @deepseek-ai/dsh-llm@">=0.1.2-rc.1 <0.3.0-0" from dsh-knj-obsidian@2026.11.11

（这两条即使标了 optional 也照样拦。）而这两个包本来就由宿主在运行时提供，peerDependencies 只影响安装期解析、对运行时没有任何作用，所以移除它们不改变任何行为，只是不再把「宿主升级到新 rc」变成「插件装不上」。

兼容性改由两处承载：

• engines.dsh：>=0.1.2-rc.1（只写下界；npm 默认不强制 engines，--engine-strict 时才拦）
• 启动日志：DSH 启动时会打印一行

[dsh-knj-obsidian] v<版本> loaded (node <node版本>, cwd <目录>)

这行没出现，就说明插件包根本没被加载（例如 Cordis 因 package.json 带 UTF-8 BOM 而静默跳过整个 bundle）。

已测宿主范围：0.1.2-rc.1 ~ 0.2.1-rc.5。

老版本（≤ 2026.11.11）在 0.2.1-rc.x 宿主上安装会 ERESOLVE，临时绕过：

npm i dsh-knj-obsidian@2026.11.11 --legacy-peer-deps，或改用 pnpm（autoInstallPeers: false，对未满足的 optional peer 只 warning）。

v1 能力

工具 · 作用

wiki_ingest · 把 agent 提取好的知识页批量写入 wiki。入参 pages（id / title / category / tags / confidence / body）+ source（源材料标识）。同 id 页面自动合并正文（保留 created、更新 updated）；传入 contentHash（源内容 SHA-256）且与 manifest 记录一致时整体跳过，实现增量 ingest。

wiki_capture · 把当前讨论快速沉淀为一条知识页（quick 模式，默认写入 references/，confidence=inferred），适合把对话结论即时落盘。

wiki_lint · 健康度检查：孤儿页（入链或出链缺失的页面）、断链（[[wikilink]] 指向不存在页面）、缺 frontmatter。返回报告供 agent 自查或人工查看。

.wiki 结构

知识库位于项目根目录的 .wiki/（由 process.cwd() 决定）：

.wiki/
├── index.md          # 维护的索引页
├── .manifest.json    # 源材料增量追踪（contentHash → 跳过重复 ingest）
├── _system/          # 会话归档、处理器与进度等内部运行数据（不参与知识检索）
├── concepts/         # 概念页
├── entities/         # 实体页
├── references/       # 参考资料
├── synthesis/        # 综合/跨主题结论
└── projects/         # 项目知识

每页为 Markdown + YAML frontmatter：

---
id: kebab-case-stable-id
title: 页面标题
category: concepts
tags: [tag-a, tag-b]
source: 源材料标识
confidence: extracted|inferred|ambiguous
created: 2026-08-25T00:00:00.000Z
updated: 2026-08-25T00:00:00.000Z
---

markdown 正文（不含 frontmatter）

v2：检索

v2 检索基于同一 .wiki/ 知识库，提供双通道能力，均只读（不创建/修改任何页面）：

通道 · 触发方式 · 说明

wiki_query 工具 · agent 自动调用 · 内置于插件，DSH 启动即暴露。agent 被问到「我之前关于 X 踩过什么坑」「我了解 Y 吗」这类既有知识问题时自动调用它检索 .wiki/，再基于候选合成带引用的回答。

wiki-query skill · 独立 skill（fallback） · 随包分发的 skill（wiki-query/SKILL.md + references/retrieval-guide.md）。在工具不可用/受限的环境里，agent 按该 skill 用 grep / glob / read 完成同等分层检索（通道对齐关系见下）。

分层检索策略

wiki_query 与 wiki-query skill 共用同一套从便宜到贵的分层层级（L1–L4），两者对 L1 的语义对齐如下：

1. L1 — index 快速层：读 .wiki/index.md，匹配查询词所在行。工具 mode=index-only 只做这一步；skill 在 auto 模式下把 L1 当作预热扫描，命中后仍继续 L2 核对更强者（工具 auto 模式不查 index，直接从 L2 开始）。

2. L2 — 标题 + 标签层：grep 标题与 frontmatter 标签，读命中文件的 title / tags / confidence（命中即停，不升 L3）。

3. L3 — 正文层：L2 无果时打开正文定位查询词，截取上下文 ≤200 字符作为 snippet。

4. L4 — 图谱邻居：解析命中页的 [[wikilink]] 出链，取一跳邻居作为关联候选。

通道对应关系：工具 auto 模式 = L2→L3→L4；工具 mode=index-only = skill 的 L1 快速层；skill 完整流程 = 工具 auto 模式 + L1 预热扫描。两通道在相同 vault 上对同一查询给出的候选集一致（skill 按上述语义执行时，L1 在 auto 下不产生候选，与工具一致）。

答案由 agent 基于候选页合成，必须带引用（页面路径 + confidence 标记：extracted / inferred / ambiguous）。无匹配时返回「wiki 无匹配」，并建议把相关内容吸收进 wiki。

wiki_query 工具

• 入参：query（检索词，必填）、mode（auto 分层 / index-only 只查 index）、maxCandidates（默认 10）。
• 返回：candidates[]（page / id / category / title / confidence / snippet / matchedBy）+ strategy + totalPages。

wiki_drill（语义种子 + 一跳双链下钻）与 wiki_read（读整页）

词面分层（L1–L4）对改写式提问天然无力：句子与库内页没有共享字面词，整串/分词匹配都会 0 命中。

wiki_drill 专治这一类，并为「检索到了却没人读原文」补上最后一环：

工具 · 入参 · 返回

wiki_drill · query（模式 A）或 page（模式 B）、limit（种子数，默认 5 / 上限 10）、neighbors（每种子邻居数，默认 8 / 上限 20）、direction（模式 B：out/in/both） · seeds[]：模式 A 把语义（QMD 本地双通道）与词面两路按名次 RRF 融合，每条带 matchedBy 与 sources（哪些通道贡献）；每个种子附一跳邻居 neighbors[]（direction / broken / degree / via / matchedBy: 'graph-neighbor'）。另有 strategy、truncated、message、semantic.status

wiki_read · id（必填）、category（同 id 跨分类歧义时用） · body 整页正文 + frontmatter 摘要/tier/confidence + outLinks / inLinks / brokenLinks 清单

推荐流程：wiki_drill({query}) 拿种子 → wiki_read 读最像的那页 → 不满意就 wiki_drill({page: '<该页链到的 id>'}) 继续一跳。

• 只给一跳：实测本库两跳即覆盖全库 40%–60%，一次性多跳等于把半个库倒进上下文；更深由调用方逐跳迭代（模式 B 毫秒级、不跑嵌入）。
• 邻居不是命中：邻居的 matchedBy 恒为 graph-neighbor（与 L4 的 graph 区分），属「顺链到达」，证据强度低于直接命中。
• 降级如实回报：索引陈旧/模型缺失时结果照给，但 message 与 semantic.status 会说明「基于旧索引」「本次仅词面通道」；KNJ_OBSIDIAN_DRILL=off 可整体关闭这两个工具（wiki_query 不受影响），KNJ_OBSIDIAN_SEMANTIC_FALLBACK=off 会一并关掉下钻的语义通道（用户关它的意图就是别加载 300M 模型）。

wiki-query skill（无工具 fallback）

无 dsh 工具的环境里，agent 按 wiki-query/SKILL.md 的流程用 grep / glob / read 完成同等检索，降级路径（无 grep、无 index.md、结果过多）见 `references/retri

…(truncated)