DSH Plugin Overview: dsh-plugin-fact-vault (Cross-Session Fact Sticky Note Library)

前言¶

在 DeepSeek Harness (DSH) 的智能体开发场景中，上下文窗口是核心约束。传统的 Transcript 插件记录了“发生了什么”，但往往缺乏对“结论是什么”的持久化存储，导致在后续会话中需要重复解释既定的决策或口径。dsh-plugin-fact-vault 旨在解决这一问题，提供一个跨会话的事实便签库。

插件介绍¶

这是一个由 121212165 维护的 MIT 许可插件。它的核心价值在于将“决策”与“过程”分离：用户或模型可以通过工具记录带标签的决策，并在任何后续会话中按需召回。相比于 Pinboard 等无条件注入系统提示的插件，本插件采用按需召回机制，不占用系统提示预算。

核心功能¶

插件提供了以下核心能力：

• 记录决策：通过 /fact save 命令记录带标签的决策。
• 关键词召回：通过 /fact find 或 fact_find 工具按关键词检索。
• 列表查看：通过 /fact list 查看最近记录。
• 删除功能：通过 /fact rm 删除指定记录。
• 模型工具：fact_find 工具供模型在回答“之前说过/定过什么”时自动调用。
• 容错机制：读取数据时跳过损坏的行，且永不改写源文件中的损坏行。

安装与启用¶

安装过程需要将插件包安装到指定 Profile，并合并配置文件。

1. 安装插件包：

    dsh plugin --profile web add github:121212165/dsh-plugin-fact-vault

此命令会通过 `pnpm` 自动运行构建。

2. 合并配置文件：
   打开 $DSH_HOME/profiles/web/cordis.patch.yml。将插件仓库根目录下的 cordis.patch.yml 内容并进该文件中。

   • 注意：不要直接追加。追加会形成两个 YAML 文档，导致启动时报错 failed to parse overlay ... end of the stream or a document separator is expected。

3. 重启 DSH：
   配置层与客户端均需重启才能生效（客户端按启动时算出的内容下发，硬刷新浏览器无效）。

基本用法¶

1. 记录决策¶

使用 /fact save 记录一条决策，支持添加标签。标签以 # 开头，可带多个。

/fact save 这里的预算上限是 500 #budget #money

2. 检索决策¶

使用 /fact find 检索记录。系统会对关键词进行空格分词，并按权重排序：
* 标签命中：记 3 分
* 正文命中：记 1 分
* 同分按时间倒序（新记录优先）。

/fact find budget

3. 查看列表¶

查看最近 20 条记录。

/fact list

4. 删除记录¶

使用 ID 删除指定记录。

/fact rm 3

5. 模型调用¶

模型在回答问题时，可以调用 fact_find 工具来自动检索历史决策。例如，当被问到“上周定过的口径是什么”时，模型会自动调用该工具获取答案。

配置与数据结构¶

• 默认库路径：~/.dsh/fact-vault/facts.jsonl
• 数据格式：JSONL，每行包含 {v:1, id, text, tags, at}。
• ID 规则：ID 是自增数字字符串（max(已存 id)+1），不是哈希，便于手动删除。
• 配置项：
  • enabled：是否启用，默认 true。
  • libraryPath：库文件路径。
  • limit：find 和 fact_find 最多返回的条数，默认 10。

注意事项¶

• 写库与读库逻辑：写库是插件自己的逻辑；读时容错（坏行跳过并计数），但永不改写源文件中损坏的行。
• Web UI 体验：未验证 /fact 命令在 web UI 里的手动输入体验（Headless 会话无输入通道）。
• 环境要求：Node.js 版本需 >= 22.18。

适用场景¶

该插件适合回答“上周我在这个 harness 里定过的口径是什么”这类问题，将临时的对话结论转化为可检索的知识库。