dsh-ref-lib · 只读参考库

DeepSeek Harness（DSH）插件：给任意会话挂上只读参考库，agent 需要查证时
先在参考库里检索——而不是凭空猜测或直接搜网。

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

✨ 特性

📦 安装

# 使用npm
dsh plugin --profile web add @hpyperry/dsh-ref-lib

# 本地开发期（改动即时生效）：指向仓库本地路径
# dsh plugin --profile web add /path/to/ref-lib

# 重启生效
dsh --profile web

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

🚀 快速开始

1. 重启后在输入卡正上方看到「参考库」胶囊（新会话与具体对话均可见）；
2. 点开面板 → 添加目录（应用内浏览器 / 系统选择器 / 手动路径三选一）→ 列表出现 → 行尾垃圾桶移除；
3. 或对话内命令：/ref-lib add <path> [--note <用途>]、/ref-lib list、/ref-lib remove <id>、/ref-lib import [会话] [路径...]；
4. 想把别的会话里配好的参考库搬过来：面板「从会话导入」或 /ref-lib import——三步挑选，重复项逐条决定保留现有还是采用导入；
5. 配置了参考库的会话，agent 会收到定稿英文的"参考库规则"上下文指令——查证规范/API/项目事实时必须先查参考库（未覆盖才允许外部途径并自报），且禁止修改库内文件。

⚙️ 行为与配置

开箱即用，无配置文件。几个可说明的行为：

🛡️ 安全

• /api/ref-lib/* 走宿主 ctx.webServer 同源路由，loopback 护栏（源地址 + Host + Origin + Sec-Fetch-Site），恶意网页 CSRF 与 LAN 访问均被拒；
• 端点唯一的文件写入是自己的 sidecar（固定目录、session 隔离、原子写）；add 只把"已存在的目录路径"记入列表，不创建/修改目标路径文件；
• 只读保证分层：库放在 workspace 之外 → 沙箱进程级强制只读（read-only/workspace-write 模式均只读）；上下文再注入软约束（"禁止创建、修改或删除库内文件"）。

⚠️ 已知限制

• 系统原生目录选择器可能卡顿且界面语言跟随 OS：可用「手动输入路径」绕开；或在 profile 把 directory-picker 切换为 @deepseek-ai/dsh-host-directory-picker-browse（应用内浏览器，快速且 zh/en 本地化）；
• settings 配置客户端白名单（DSH rc.6 框架限制）：第三方插件 namespace 默认不可被浏览器端读写，官方标注为 deferred work；
• /ref-lib add <path> 的相对路径基于当前会话工作区解析，而非 dsh 进程启动目录；
• 导入只做单向快照：导入后源会话的变化不会回流；同路径再次导入仍是重复项处理（保留现有 / 采用导入），不会自动合并。

🧑‍💻 开发

pnpm typecheck   # tsc --noEmit
pnpm lint        # eslint（typescript-eslint recommended）+ prettier
pnpm test        # vitest（L0–L2：纯函数 / 装载 / harness 边界回归）
pnpm build       # tsc（node half）+ tsdown（client bundle）→ 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；
• 热更新：src/client/* 改动 pnpm build:client 后浏览器 ≤0.5s 自动热更新；node half 改动需重启 dsh web。

📄 License

MIT，与 DeepSeek Harness 一致。

📚 更多

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