前言¶
DeepSeek Harness (DSH) 的理念是“一切皆插件”。DSH 内置版 Obsidian（dsh-knj-obsidian）为 AI agent 提供项目级知识库（wiki）的构建能力。Agent 可以通过工具将对话、文档、网页等源材料蒸馏为结构化知识页，落盘到项目根目录的 .wiki/，形成可复用、可维护的知识资产。
该插件由 yangdongzhen590 维护，当前版本包含 v1 构建、v2 检索、v3 图谱导出、v4 UI 和 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 启动时向 agent 暴露工具，并随包分发 wiki-query skill，无需额外配置。
v1 构建：写入侧¶
插件提供三个核心工具用于知识库的构建与维护。
wiki_ingest¶
将 Agent 提取好的知识页批量写入 wiki。支持 contentHash 增量合并，当源内容 SHA-256 与 manifest 记录一致时整体跳过，实现增量写入。
wiki_capture¶
快速沉淀。采用 quick 模式，默认写入 references/ 目录，confidence 标记为 inferred。适合将对话结论即时落盘。
wiki_lint¶
健康度检查。检查孤儿页（无入链或出链）、断链（[[wikilink]] 指向不存在的页面）以及缺 frontmatter 的情况，并返回报告。
知识库结构位于项目根目录的 .wiki/，包含 index.md、_system/、concepts/、entities/、references/、synthesis/、projects/ 等目录。
v2 检索：双通道¶
检索能力基于同一 .wiki/ 知识库，提供双通道机制，均为只读操作。
wiki_query 工具¶
内置工具，DSH 启动即暴露。Agent 在被问到“之前关于 X 踩过什么坑”等既有知识问题时自动调用。
wiki-query skill¶
随包分发的独立 skill，作为工具的 fallback。在工具不可用时，Agent 可通过该 skill 使用 grep / glob / read 完成同等分层检索。
分层检索策略¶
两者共用 L1–L4 分层层级：
1. L1 — index 快速层：读取 .wiki/index.md。
2. L2 — 标题 + 标签层：grep 标题与标签，命中即停。
3. L3 — 正文层：打开正文定位，截取上下文。
4. L4 — 图谱邻居：解析 [[wikilink]] 出链，取一跳邻居。
v3 图谱导出¶
wiki_export 工具¶
Agent 被问到“导出图谱”时自动调用。提供两种格式：
- html：生成
graph.html，单文件交互可视化，内联 SVG + 原生 JS，零外部依赖。 - json：生成
graph.json，包含节点、边、孤儿、统计信息，供外部工具使用。
产物写入 <vault>/wiki-export/。
v4 UI：侧边栏¶
安装后，DSH 右侧边栏会出现“知识库”标签，提供笔记/图谱工作台入口。
v5 笔记编辑¶
笔记编辑器支持富渲染、双链原地跳转、源码视图与全文编辑。
本地语义检索¶
除关键词分层检索外，插件提供 wiki_search_semantic 工具，支持本地语义检索。此功能依赖 QMD 库，默认不安装。
启用步骤¶
需手动安装 QMD 及下载模型：
# 1. 安装 QMD
dsh plugin --profile web add @tobilu/qmd@2.8.3
# 2. 手动下载模型（约 320 MB）
# 放置到：%USERPROFILE%\.dsh\qmd\models\embeddinggemma-300M-Q8_0.gguf
离线约束¶
语义检索严格离线。QMD 的云端模型路径会被禁用，索引与查询全程零网络。索引状态可通过 API 轮询。
注意事项¶
- 依赖安装：
@tobilu/qmd为 optional peerDependency，DSH 默认不会自动安装。需显式执行上述安装命令。 - 模型下载：需手动下载模型文件并放置到指定路径，插件不会自动下载。
- 环境要求：需 Node.js >= 20 和已安装的 DSH 宿主。
