@sidleo3/dsh-kb

v0.1.0

Published

a month ago

通用知识库（渐进式披露）插件：目录即分类（多级，可启用/停用），每个知识点一个 markdown 文件（front-matter + 正文），多标签 + 关键词检索。适用于 DeepSeek Harness (DSH)，任意 preset 模式可用。Install via `dsh plugin --profile <name> add @sidleo3/dsh-kb`.

0High
0Medium
0Low

sidleo3

deepseek-harness dsh plugin knowledge-base progressive-disclosure markdown tags

dsh-kb — 通用知识库插件（渐进式披露）

为 DeepSeek Harness（DSH）设计的通用知识库插件，与 dsh-sqlkb 同构但不绑定任何业务：分类由用户自由定义（目录树、多级、可启用/停用），每个知识点一个 markdown 文件，多标签 + 关键词检索。

适用场景示例：企业知识库（业务口径/组织架构/踩坑日志）、个人知识库（读书笔记/灵感/技能）、项目资料库（规范/FAQ/复盘）…… 分类、标签、内容全部由你决定。

核心思路（与 skill 的渐进式披露同构，但由插件代码确定性控制）：

| 时机 | 行为 | 由谁控制 | |------|------|---------| | 会话每一轮 prompt 组装 | 注入紧凑「描述层」section：数据源路径 + 分类树索引（title(path)：description ｜条目数）+ 工具用法（不铺开条目明细），每轮开销恒定、不随知识量增长 | 插件代码（确定性） | | 做知识工作、需要知道有哪些资源时 | 第一步必须先 kb_categories list / kb_list 得到分类树与条目索引 → kb_search（含正文匹配、子树/标签过滤）缩小范围 → kb_get 读取单个条目明细 | 插件代码（硬要求先 list，精确、有界、按需） | | 未命中时 | kb_search/kb_get 未命中会自动留痕到进程内存待补池（按会话隔离、不写文件、重启即清空）；kb_search 未命中还自动附分类树索引；任务收尾经用户同意后 kb_create 补录 | 插件代码（自动留痕）→ 经用户同意（补录） | | 新增/修改知识后 | kb_validate 校验规范 | 插件代码 | | 知识过期/换工作 | 生效开关：在 categories.yml 中将某分类 enabled: false，该分类（含整棵子树）即停用，默认不参与检索/列表/描述层；恢复 enabled: true 后自动生效，数据零删除 | 用户或插件代码（kb_categories update enabled） |

安装于宿主层（web profile）：挂在 profile bundle 层，任意 preset / 任意模式 / 任意会话共享。

安装

dsh plugin --profile web add @sidleo3/dsh-kb

本地开发安装（源码目录）：

dsh plugin --profile web add link:/path/to/dsh-kb

修改 profile 组合后需重启 dsh web 生效。

配置（数据目录与生效白名单）

默认数据目录：~/.agents/kb（首次使用自动创建骨架 README；不包含任何业务内容，知识文件由你维护）
自动记录白名单：autoApproveCategories（逗号分隔分类路径，支持前缀匹配）内的分类，kb_create/kb_update 免确认自动记录（继承旧「主动知识记录/踩坑必记」习惯）；白名单外的分类写入必须 user_approved: true

在 profile 的 cordis.patch.yml 中 id 定向覆盖（后写者胜，需写全 config 键）：

- id: kb-registry
  config:
    dataDir: /absolute/path/to/kb
    sectionName: kb-registry
    sectionOrder: 61
    maxSectionChars: 6000
    maxGetChars: 40000
    cacheTtlMs: 30000
    autoApproveCategories: logs/knowledge-log, 我的分类

工具

| 工具 | 用途 | |------|------| | kb_categories { action, path?, … } | 分类管理：list 免确认；add（目录即分类，父级自动创建）、update（改 title/description/order/enabled 生效开关，或 new_path 重命名/移动整棵子树）、remove（仅空分类）——增删改需 user_approved: true | | kb_list { category?, include_disabled? } | 无 category：分类树（title(path)：description ｜条目数，含子树聚合，空目录标注）；有：该分类子树全部条目。【硬要求】知识相关工作第一步先调用它/kb_categories list | | kb_search { query, category?, tag?, include_disabled? } | 关键词检索：匹配 name/summary/tags/related/所属分类（含分类标题与描述）+ 正文；词元拆分 + 量词后缀兜底；强匹配标 ★ 排前；支持子树/标签过滤；命中自动附 related；未命中自动留痕 + 附分类树索引 | | kb_get { name } | 读取单个条目完整正文，自动附 related 摘要；未找到自动留痕 | | kb_validate { } | 校验知识目录：分类树与 categories.yml 一致性（残影/未登记）、条目 front-matter 完整性、命名一致、全库唯一、空正文、未分类根条目 | | kb_pending { action?, keyword?, note?, id? } | 管理待补池（进程内存、按会话隔离、重启即清空）：list / add / remove；补录走 kb_create | | kb_create { name, category, summary, tags, body?, … } | 新增知识条目（写入 <分类>/<条目名>.md 并自动校验）。默认需 user_approved: true；白名单分类免确认；停用分类拒绝写入；from_pending 成功后自动删待补条目 | | kb_update { name, category?, summary?, tags?, body?, … } | 更新已有条目：只更新传入字段；category 变更=移动文件到目标分类；门控同上；删缺必填字段被拦 |

~/.agents/kb/
├── README.md              # 种子说明（自动生成，含规范）
├── categories.yml         # 可选元数据叠加层：分类路径 → {title, description, order, enabled}
└── <分类路径>/            # 多级目录树，每个目录即分类
    └── <条目名>.md        # 每个知识点一个文件

目录树是分类的唯一事实来源：路径即分类 id，可多级嵌套。你可以直接在文件管理器里建文件夹=建分类、拖拽文件=改分类、删空目录=删分类，agent 工具（kb_categories）与目录操作一致，二者永远同步；categories.yml 只做展示与生效设置的叠加（缺失时 title 直接用目录名）。

条目文件 front-matter（必填 3 项）

---
name: 商行=小商行firm_s      # 与文件名一致，全库唯一
summary: 常用维度简称「商行」默认指小商行
tags: 口径, 商行, 维度        # 多标签，逗号分隔
related: 调改店经营SKU数     # 可选：相关条目名，检索/读取时自动附带
status: 已审核              # 可选
updated: 2026-08-12        # 可选
---
正文

条目分类 = 文件所在目录，front-matter 不存 category：人工移动文件即自动改分类，无需改任何字段。

categories.yml 元数据叠加层（可选）

categories:
  data/biz-caliber:
    title: 业务口径
    description: 指标定义、计算口径、数据来源
    order: 11
  data/org:
    title: 组织架构
    description: 品类架构、区域架构、门店维度
    order: 12

分类生效开关（启用/停用）

在 categories.yml 中给某分类加 enabled: false（或用 kb_categories update enabled: false）→ 该分类及其整棵子树停用。
停用后：描述层、kb_list、kb_search、kb_get 默认完全忽略（相关条目视作不存在）。
kb_categories list 始终显示全部分类并标注「⛔已停用」；kb_list/kb_search 传 include_disabled: true 可强制查看。
停用分类拒绝写入新条目；恢复 enabled: true（或删掉该行）后自动生效，数据零删除。
典型用法：离职后把旧公司相关分类停用，相关知识整体失效、不影响日常检索；未来再启用即可。

维护

新增条目：在任意分类目录下建 <条目名>.md（front-matter 三要素 + 正文），下个缓存窗口自动收录；或会话内 kb_create
新增分类：直接建目录（多级随意），title/description 可选在 categories.yml 补登记
修改：直接编辑文件，或 kb_update；kb_validate 校验合规
迁移旧资料：仓库自带 scripts/migrate-legacy.mjs（把旧的 AGENTS.md / 业务资料目录整理为种子知识）；冒烟测试 scripts/smoke-test.mjs 无需 DSH 运行时即可验证 8 个工具

测试

node --check kb.mjs
node scripts/smoke-test.mjs                          # 合成 fixtures
node scripts/smoke-test.mjs --dataDir=~/.agents/kb-test   # 迁移库实测

设计说明

描述层注入走 system-prompt/assemble 瀑布（同步注册、异常不外抛，绝不影响 prompt 组装），与 DSH 官方 tool-bootstrap 同机制
插件不 publish 任何 service，纯消费 systemPrompt/tools，可安全挂载于宿主层
知识数据是纯 markdown + 目录树，工具无关：任何编码代理（pi/Claude Code 等）可直接按文件路径读取
目录即分类：人按文件夹管理资料的习惯与 agent 工具操作天然一致；tags 承担跨域标注（如「熟食/报表/涉密」），分类树只管归属，二者互补
生效开关：知识会随人生阶段/岗位变化而失效，停用而非删除，快速可恢复

许可

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme