@hpyperry/dsh-ref-lib

Readme

# dsh-ref-lib · 只读参考库

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

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

## 它解决什么问题

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

## 安装

```bash
# 安装
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 里取消归档。

## 开发

```bash
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](LICENSE)，与 DeepSeek Harness 一致。

## 更多

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