置顶便签 121212165/dsh-plugin-pinboard

dsh-plugin-pinboard

🧩 dsh 插件家族（22 件）：总目录 dsh-plugin-family ｜ 明星插件：ide-hub 跨 IDE 统一管理 · task-forge 跨窗口无损交接 · quota 实时用量仪表

EN · 跨会话置顶便签：/pin 存一条便签，置顶的便签会进入每个会话的系统提示，并受硬预算约束（limit × maxChars，段落顺序 700，因此工具段落从 1000 之后开始）；pin_add 让模型自己置顶。从 v0.2 起，它还承载 fact-vault 的可检索库（/facts、fact_search）——存在同一个文件里，带标签，并且刻意永不注入。· 22 个 node --test 全绿 · 两个真实无头会话证明：会话 A 写入的便签会出现在会话 B 的提示词日志里 · 坏配置（limit: -1）在启动时失败并点名 pinboard，而不是把 harness 拖垮。

DeepSeek Harness (dsh) 插件：跨会话置顶便签。在任何会话里 /pin 一次，这条便签就会注入之后每一个会话的系统提示——不用重复交代，不用改 agent 配置文件。

适合回答："我怎么让 dsh 永远记住'回答用中文''别动 main 分支'这类长期约定？"

同系列：prompt-vault（提示词弹药库，手动发送）· session-insights。与 fact-vault 的关系（v0.2 起）：它的表面已并到这里——同一套动词、同一套 #标签 语法、同一套打分（标签 3 分 / 正文 1 分），只是存进同一个 pins.jsonl。分工本来就靠消费方式：便签"每次都直接告诉模型"，事实"模型自己去查"。审计指出 fact-vault 的病是"存了没有消费端"，所以这里把事实条目明确排除在注入预算之外，靠 /facts find 与 fact_search 取用；搬家用 /facts import（只读源文件）。

用法

- /pin <一句话> [#标签…]：置顶一条便签（多余空白压成单行；重复内容不重复入库）。标签是元数据，不进注入正文，只用于列表与检索。
- /facts save|find|list|rm|import：事实库（存下来供检索，不注入）。save 事实 #标签 / find 关键词 / rm <id>；import [--from <路径>] 一次性搬 ~/.dsh/fact-vault/facts.jsonl——只读源文件，重复跳过、坏行计数，源文件字节不动。
- /unpin <id>：取消置顶（# 前缀可带可不带）。
- /pins：列出全部便签，● 表示真的会注入、○ 表示因超出条数/字符上限被挤出去了。
- pin_add 工具：模型自己置顶——只在用户明确说"记住/以后都"时调用，返回值会告知是否进入了注入预算。

- fact_search 工具：模型自查事实库（标签命中 3 分、正文命中 1 分）。回答"我们之前定过/查过 X 吗"之前先调它，而不是凭记忆答——这条消费端正是 fact-vault 缺的。

配置

| 字段 | 默认 | 说明 |
| enabled | true | |
| dataPath | ~/.dsh/pinboard/pins.jsonl | 便签与事实共用的单文件库 |
| limit / maxChars | 12 / 1200 | 注入预算：只算便签，事实永远不占额度 |
| order | 700 | 注入段在系统提示里的位置 |
| factLimit | 10 | /facts find 与 fact_search 最多打印几条命中 |
| factsPath | ~/.dsh/fact-vault/facts.jsonl | /facts import 的默认源文件 |

order / factLimit / factsPath 走启动自检：填错即启动失败并点名 pinboard。

便签存为 ~/.dsh/pinboard/pins.jsonl（按月不切分，单文件）。注入通过 ctx.systemPrompt.section()，段落文本是每次组装时求值的 provider，所以中途新增的便签下一回合就生效，不需要重启 dsh。

注入预算（关键设计）

便签会长期占系统提示，所以预算是硬的：

| 字段 | 默认 | 说明 |
| enabled | true | 关掉则完全不注册命令与段落 |
| dataPath | ~/.dsh/pinboard/pins.jsonl | 便签文件 |
| limit | 12 | 最多注入几条 |
| maxChars | 1200 | 注入行的总字符上限（不含段落标题） |
| order | 700 | 系统提示段落顺序（官方工具段落从 1000 起，700 在策略段之后、工具段之前） |

选择规则：按 at 倒序（最新优先），逐条累加字符，装不下就停。唯一一条超长时截断而不是丢弃（末尾加 …），保证最新一条一定到达。

注入段落形态：

置顶便签（pinboard）用户置顶的持久指令，跨所有会话生效，优先于临时对话中的同类约定：
- 一律使用中文回答
- 代码注释也使用中文

安装

三步，实测于 @deepseek-ai/dsh@0.1.7-alpha.1（需 pnpm 在 PATH 上）：

① 装进 profile：dsh plugin 把参数原样转发给 pnpm，git 包会自动跑 prepare 构建 lib/
dsh plugin --profile web add github:121212165/dsh-plugin-pinboard

② 把本仓库根目录 cordis.patch.yml 的内容并进 $DSH_HOME/profiles/web/cordis.patch.yml。
该文件默认是 []，所以要么整份替换，要么把 insert 条目并进同一个数组；不要直接追加——追加会形成两个 YAML 文档，启动即报 failed to parse overlay ... end of the stream or a document separator is expected（本机实测踩过）。

③ 重启 dsh。配置层与 client 半都要重启才生效（客户端按 boot 时算出的内容 rev 下发，硬刷新浏览器没用）。

自检挂载：dsh --profile web --dump-config | grep dsh-plugin-pinboard，应看到该条目。

验证状态

- 22 个 node --test 全绿：纯函数（标签切分与去重、事实不占注入预算、检索打分与排序、导入的三类计数与时间戳保留、增删/去重/容错解析/预算裁剪/截断/列表标注）+ 装配层（真实 apply() 挂 mock ctx、真临时目录驱动 /pin /unpin /pins /facts 全部动词与 pin_add fact_search 两个工具、坏动词坏参数拒绝、导入两次不翻倍、--from 覆盖配置路径、源文件字节不变）。
- 本机 live 验证：两个真实 headless 会话——A 会话由模型调用 pin_add 写入便签，B 会话的 session.v4.jsonl.zstd 里系统提示确实包含该段落（跨会话注入成立）。
- 非法配置探针：limit: -1 时启动失败并点名 pinboard (dsh-plugin-pinboard): ValidationError，不会拖垮 harness。
- 未验证：/pin 在 web UI 命令面板里的手动输入体验（headless 无输入通道，验证走的是命令 handler 直接调用）。

测试

npm run check # typecheck + node --test + tsc build

22 个测试：纯函数 + 装配层，见上「验证状态」。装配层 harness 从 dsh-plugin-task-forge 复制，本仓是家族里第二个用它跑出全套覆盖的。

装配层测试 harness 借鉴 dsh-auto-review（222★，PerryLink）的 mountHarness 方法论，node:test 版实现来自 dsh-plugin-task-forge（本家族首个装配层覆盖的插件）。