dsh-ref-lib · 只读参考库

给 DeepSeek Harness 的每个会话挂一个「只读参考库」：把本地目录（比如你的项目源码、内部文档）登记为参考库后，agent 回答前会先去这些目录里查证，查不到才允许走外部途径——而不是凭空猜或者直接上网搜。

dsh plugin --profile web add @hpyperry/dsh-ref-lib@0.17.0

它解决什么问题

• 答案有依据：agent 查的是你指定的真实目录，涉及你的代码、接口、配置时，回答会更贴合实际。
• 每个会话独立：这个会话配了参考库，不影响其他会话；分支会话（fork）会自动继承父会话的参考库。
• 只读、安全：参考库目录对 agent 只读——能查、能引用，但不能创建或修改库里的文件。

安装

# 安装
dsh plugin --profile web add @hpyperry/dsh-ref-lib@0.17.0

# 卸载
dsh plugin --profile web remove @hpyperry/dsh-ref-lib

@0.17.0 是指定版本号：安装其他版本把 @0.17.0 换成对应版本即可（如 @hpyperry/dsh-ref-lib@0.16.0）；不带版本号则默认装最新版。

安装完成后重启 dsh web 生效。本地开发期想改动即时生效，也可以直接指向仓库本地路径：dsh plugin --profile web add /path/to/ref-lib。

快速上手

1. 重启后，输入框正上方会出现一个「参考库」胶囊，点开即见管理面板。
2. 添加目录，三种方式任选：
   • 应用内目录浏览器：在面板里点开浏览选择（界面随语言本地化）；
   • 系统原生选择器：走操作系统自带的目录对话框（界面语言跟随系统；启动时自动探测你的环境支持哪种，想手动切换可在 profile 的 cordis.patch.yml 里改 directory-picker 配置）；
   • 手动输入路径：直接粘贴路径，支持 ~ 和相对路径（相对路径基于当前会话工作区解析）。
3. 可选：给每个库写一句用途说明（比如「xx 项目 API 文档」），不写也没关系——插件会自动从目录 README 的首个标题提取，实在没有就留空。
4. 开始对话。配置了参考库的会话，agent 会收到一份"查证规则"：涉及你的项目时必须先查参考库，查不到再走外部来源并说明；同时被要求不修改库内文件。

想验证效果，在对话里输入 /ref-lib list，应能看到你刚添加的库。

常用命令

UI 面板和命令操作的是同一份数据，按习惯用哪个都行。

| 命令 | 作用 | | --- | --- | | /ref-lib add <path> | 添加一个目录作为参考库 | | /ref-lib add <path> --note <用途> | 添加时附上用途说明 | | /ref-lib list | 列出当前会话的参考库（含失效标记） | | /ref-lib remove <id> | 删除某个参考库 | | /ref-lib import [会话] [路径...] | 从其他会话导入参考库（详见下文） |

命令结果以专属卡片展示，完整文本直接可见，并带一键复制。

跨会话导入

想把别的会话里配好的参考库搬过来，用面板里的「从会话导入」或 /ref-lib import。流程分三步：

1. 选会话：只列出配过参考库的会话，按工作区分组显示（组头可折叠，默认收起；未归属工作区的归入「未分组」）。会话多也不卡——列表默认只显示概览，展开某组时才加载该组的会话。
2. 勾条目：勾选要搬的条目，可全选（默认反选起步）。
3. 处理冲突：当前会话里已有相同路径时，会并排对比两边差异（用途说明、可用状态的不同会按侧高亮），逐条决定「保留现有」还是「采用导入」。

几个要点：

• 导入是快照副本，不回流——导入后源会话的改动不会同步过来，两边从此各自独立。
• 已归档的会话不会出现在导入来源里；空白会话（从未开始过对话）和对话中分发的子代理会话同样不列出——和宿主侧边栏的展示口径一致。
• 命令模式 /ref-lib import 语义相同，只是遇到冲突会直接跳过该条目。

它是怎么工作的

| 你想知道的 | 答案 | | --- | --- | | 数据存在哪 | <dshHome>/plugin-data/ref-lib/<sessionId>.json，每个会话一个文件，随 dsh home 一起持久化，重启不丢 | | 怎么注入给 agent | 只给配了参考库的会话注入（走 systemPrompt.context）；参考库为空时不注入，零 token 开销。注入内容为定稿英文规则：库清单（含用途说明作为路由元数据）+ 强制查证流程 + 权威性/冲突处理 + 只读约束 | | 用途说明 | 添加时可选填写；自动提取目录 README 首标题兜底。它帮助 agent 判断"这个库和当前问题相不相关"，之后可在面板条目详情里随时改 | | 分支会话 | fork 出的新会话在创建那一刻复制父会话的参考库快照，条目独立成新身份；两边之后各改各的 | | 失效检测 | 每次读取都实时探测目录是否还在（被删除或换成了普通文件即判失效）。失效库不再注入上下文，并在面板状态行、胶囊角标、/ref-lib list 里红色标出；失效条目只能移除，不能编辑或重新打开 | | UI 刷新 | 面板数据由交互驱动：执行 /ref-lib 命令、发消息、面板操作后即时刷新，没有后台轮询；外部改动了文件，下次界面交互时同步 |

安全

• 所有读写走插件自注册的 /api/ref-lib/* 路由，带 loopback 护栏（校验源地址、Host、Origin 等），恶意网页和局域网访问都会被拒。
• 插件唯一会写入的文件是它自己的 sidecar（固定目录、会话隔离、原子写）；「添加」只是把"已存在的目录路径"记进列表，不会创建或修改目标目录里的任何文件。
• 只读保证有两层：参考库目录在 workspace 之外时，沙箱从进程层面强制只读；上下文注入再补一层软约束（要求 agent 禁止修改库内文件）。

已知限制

• 系统原生目录选择器可能卡顿，界面语言跟随操作系统：嫌它难用就手动输路径，或在 profile 的 cordis.patch.yml 里把 directory-picker 切到 @deepseek-ai/dsh-host-directory-picker-browse（应用内浏览器）。
• settings 配置客户端白名单（DSH 框架限制）：第三方插件的 namespace 默认不能被浏览器端读写，官方标注为 deferred work。
• 相对路径的基准：/ref-lib add 的相对路径基于当前会话工作区解析，不是 dsh 进程的启动目录。
• 导入是单向的：导入后源会话的改动不会回流；同路径再次导入仍走冲突处理，不会自动合并。
• 部分会话不在导入来源里：归档会话、空白会话、子代理会话都不列出（见上文），需要时先在 GUI 里取消归档。

开发

pnpm typecheck   # 类型检查（tsc --noEmit）
pnpm lint        # eslint + prettier
pnpm test        # vitest：L0 纯函数 / L1 装载 / L2 harness 边界回归
pnpm build       # 构建 node half（tsc）+ client bundle（tsdown）→ lib/

• 代码结构：src/ 是 node half（服务、/api/ref-lib/* 路由、/ref-lib 命令、上下文注入），src/client/ 是 web half（dock 胶囊、管理面板、目录浏览器、本地化），tests/ 是测试。
• 隔离开发环境：scripts/dev-isolate.sh 用独立的 DSH_HOME（默认 ~/.dsh-dev）启动插件，真实 ~/.dsh 零接触，rm -rf 即可重置。启动、安装、热更新、重置的完整用法见仓库 AGENTS.md。
• 指定 dsh 版本测试（不依赖 npm 全局安装）：DSH_BIN="$(DSH_VERSION=0.1.2-rc.1 ./scripts/dsh-local.sh)" DEV_HOME="$HOME/.dsh-dev-rc1" ./scripts/dev-isolate.sh——dsh-local.sh 把目标版本幂等装到 ~/.dsh-tools/<版本>/（非全局），dev-isolate 经 DSH_BIN 调用它；详见两个脚本头注释与 docs/upgrade-dsh-0.1.2-rc.1.md §5.3。
• 热更新：改 src/client/* 后跑 pnpm build:client，浏览器约 0.5 秒内自动生效；改 node half 需要重启 dsh web。

License

MIT，与 DeepSeek Harness 一致。

更多

• 开发规范 / 测试标准 / 开发环境约定：见仓库 AGENTS.md
• 仓库：https://github.com/hpyperry/dsh-ref-lib