前言¶
在 DeepSeek Harness（DSH）里做长线任务时，结论往往散落在对话里：隔几周再问「当时检索方案怎么定的」，只能靠翻聊天记录，或者自己另存笔记文件，和 Agent 用的上下文并不贯通。常见做法包括手工维护 Obsidian / 纯 Markdown 目录、让模型每次从头总结会话，或接入向量库——前者和 Harness 工具面脱节，后者要网络和模型调用，部署也更重。
下面介绍社区插件 dsh-km（GitHub：calmzealA/dsh-km，分类：记忆）：把知识落在工作区 .dsh-km/ 下的普通 Markdown 上，由四个 km_* 工具读写，侧边栏提供 Web 面板做审阅；检索用本地 BM25（含 CJK bigram），无嵌入、无额外依赖、无出站网络。
这是什么¶
dsh-km 是面向 DeepSeek Harness 的 local-first 知识库插件。维护者为 calmzealA（npm 包名 dsh-km，当前版本 0.1.0，许可证 MIT）。它解决的是：在同一工作区内，让人和 Agent 共用一套可 diff、可提交、可审阅的笔记，并按「何时该想起来」和关键词检索，而不是只堆对话历史。
要点如下：
- Markdown 为唯一事实来源；内存索引在启动和写入后重建。
- 每条笔记有单行
when字段，用于「情境匹配」，不仅靠关键词。 sources（session、URL、file、manual）与审阅状态draft/verified/stale/archived是一等公民；模型写入默认为draft。- 删除进入
.trash/，工具不会直接 unlink 笔记文件。
核心功能¶
四个 km_* 工具¶
| 工具 | 主要参数 | 返回 |
|---|---|---|
km_search |
query（空则列最近）、tags?、status?、topK?、workspace? |
id、标题、状态、when、片段、来源、得分 |
km_read |
id、maxChars?、workspace? |
Frontmatter、正文、来源、链接、反向链接 |
km_write |
title、body、tags?、when?、status?、sources?、id? |
稳定 id、路径、状态、时间戳 |
km_link |
from、to |
两笔记双向链接 |
笔记 id 形如 km-xxxxxxxx；工具不接受文件路径。新笔记默认 draft；/km add 与面板保存默认 verified。
目录与笔记格式¶
默认库路径为 <workspace>/.dsh-km/：
<workspace>/.dsh-km/
├── .gitignore
├── notes/
│ └── 检索方案选型-km-8060879c.md
└── .trash/
笔记为带 YAML frontmatter 的 Markdown，例如：
---
id: km-8060879c
title: 检索方案选型
tags: [检索, 架构]
when: 当需要决定检索方案时
links: [km-9f8e7d6c]
status: verified
created: 2026-11-11T09:00:00.000Z
updated: 2026-11-11T09:30:00.000Z
sources:
- {type: session, ref: sess_ab12, locator: "seq:41-47", capturedAt: "2026-11-11T09:00:00.000Z"}
- {type: url, ref: https://example.com/spec}
---
正文 Markdown……
手写在磁盘上的笔记会在下次 reload 时被索引；格式错误的单条会在面板中报错，不阻塞其余库。
检索¶
- 中文按字符 bigram，拉丁文与数字按小写词切分；混合查询可用。
- 加权 BM25：
title(3)、when(2)、tags(2)、body(1)，k1=1.2，b=0.75。 verified优先于draft；stale降权；默认排除archived（可按需指定）。- 结果受
maxResultChars预算约束，片段约 180 字符，命中项带sources。
Web 面板与命令面¶
知识库面板在侧边栏底部，紧邻 Settings；界面支持英文与简体中文，随 DSH 当前 locale。Host 侧变更需重启 DSH；仅面板相关变更刷新页面即可。
对话中也可用命令：
/km status, counts, recent notes
/km add <text> save a human-authored note (verified)
/km search <text> compact hits
/km open status + hint to open the panel
面板通过同源前缀 /dsh-km/api 与 Host 通信（列举工作区、搜笔记、读写、进回收站、重建索引、设置与统计等）；vault 须为已注册工作区路径，id 须匹配 ^km-[0-9a-f]{8}$。
安装与启用¶
插件面向 DSH >=0.2.2-rc.1 <0.3.0 与 Node.js 20+，无运行时 npm 依赖。
推荐从 npm 安装（需 web profile）：
dsh plugin --profile web add dsh-km
本地目录安装：
dsh plugin --profile web add ./dsh-km
在 DSH Desktop 中：打开 Plugins → Install third-party plugin，粘贴插件包的绝对路径；启用 bundle 后刷新页面一次以加载 Web 面板。
可在 Plugins → Discover → Add index source 添加市场索引（示例 URL，与 README 一致）：
https://cdn.jsdelivr.net/npm/dsh-km@0.1.0/market/index.json
可选配置¶
cordis.patch.yml 中插件行支持：
| Key | 默认 | 含义 |
|---|---|---|
vaultDir |
'' |
空为 <workspace>/.dsh-km |
maxNoteBytes |
1048576 |
单条正文最大字节 |
searchTopK |
8 |
默认命中条数 |
maxResultChars |
6000 |
工具结果字符预算 |
autoCreate |
true |
首次写入时创建库 |
watch |
true |
磁盘变更时重载索引 |
优先级：cordis.patch.yml 高于 Settings 页；Settings 写入 $DSH_HOME/dsh-km/settings.json，高于内置默认。面板不修改 profile patch。
典型用法¶
对话里让 Agent 写入与引用¶
在会话中：
> 把这次关于检索方案的结论存进知识库，标注一下来源
Agent 调用 km_write，返回稳定 id（如 km-8060879c）。之后：
> 之前关于检索方案是怎么定的？用 [km-id] 标注引用
Agent 依次 km_search、km_read，并在回答里标注 id。
人工快速录入¶
/km add 本次选型：工作区检索先用 BM25，verified 状态由人工确认
可与 Git 对工作区 .dsh-km/notes/ 做版本管理，与插件的审阅状态互补。
适用场景与注意¶
适合谁：需要在 DSH 工作区内沉淀架构决策、调研结论、可复现约定，并希望 Agent 能按 id 检索、带来源与 when 字段的团队或个人；不打算为笔记单独跑向量服务或外网 API 的环境。
运行与安全（安装前请自行核对）：
- 插件以当前 dsh 进程权限读写工作区；所有文件操作限制在该工作区的 vault 内，id 不含路径分隔符，并在
path.resolve后做包含性检查。 - 写入按 vault 串行化，临时文件加 rename；删除仅进
.trash/。插件本身不发网络请求、不调用模型。 - 安装第三方插件前，建议阅读 GitHub 源码 与 MIT 许可证，确认与自身合规要求一致。
当前里程碑未包含（README 路线图）：会话事件自动采集与审阅队列、相关度注入、km_check 引文校验、嵌入、PDF/Office 摄取、长文分块与图谱画布等；数据模型已为 sources 与 status 预留扩展。
DSH 生态理念是「一切皆插件」；SkillHub 目录页 等社区站点独立运营，与 DeepSeek / 幻方无官方从属关系，本文介绍的是社区维护的 dsh-km，非官方应用商店内置能力。
结尾¶
dsh-km 把工作区里的 Markdown 变成 Agent 可读写的知识库：本地 BM25、来源与审阅状态、四个 km_* 工具与侧边审阅面板，适合想在 Harness 内闭环「记结论—再召回」的开发者。进一步细节见目录页与仓库 README。
- 目录页：https://www.skillhub.cn/plugins/calmzealA/dsh-km
- GitHub：https://github.com/calmzealA/dsh-km
