dsh-cajita · DSH 小工具箱插件

DeepSeek Harness（DSH）插件：一个插件包、多个小工具。当前包含：

• 任务 1 · 编辑消息——在用户消息的复制按钮旁新增「编辑」按钮，把误发送的未完成消息 在原消息位置覆盖一条与官方输入框同款的内联编辑卡继续编辑，编辑后作为一条新消息正常发送；
• 任务 2 · web_fetch 内网放行（web-fetch-policy）——给官方 web_fetch 换一个带 「内网放行开关」的 fetch provider：默认与官方完全一致（只允许公网目标），在 设置 → 插件配置 打开开关后放行解析到私网/回环等内网地址的目标（TUN / 代理用户 的 DNS 常回 fake-ip/内网地址，不开会全部被拒）；
• 任务 3 · 提醒通知（turn-notify）——agent 回合完成、弹出提问或需要审批时， 页面不在前台则弹浏览器系统通知（标题带场景前缀，需先授权一次）；开关在 cajita 设置卡里。

npm：@hpyperry/dsh-cajita · 仓库：https://github.com/hpyperry/dsh-cajita

安装（推荐锁版本）：dsh plugin --profile web add @hpyperry/dsh-cajita@0.1.5

✨ 工具清单

📦 安装

插件已发布到 npm（@hpyperry/dsh-cajita），直接按包名安装即可：

包名 @hpyperry/dsh-cajita 是 npm 安装/卸载身份；插件注册进 dsh 的 layer id 为 cajita（不带 dsh- 前缀，与 ref-lib 同模式： @hpyperry/dsh-ref-lib ↔ layer id ref-lib）。

# 从 npm 安装（推荐锁版本）
dsh plugin --profile web add @hpyperry/dsh-cajita@0.1.5
# 或装最新标签
dsh plugin --profile web add @hpyperry/dsh-cajita@latest

npm 包自带构建产物（lib/），无需源码构建/授权；想要最新开发版或未发布改动时， 可用本地 link 形态安装源码目录（见下）。

升级插件的小坑：pnpm 在“已装版本仍满足当前声明范围”（如声明 ^0.1.4、新出 0.1.5）时，add <包>@latest 会被判定为无需改动（no-op）。要真正升级请显式指定 新版本（…add @hpyperry/dsh-cajita@0.1.5），或在 profile 里跑 pnpm update @hpyperry/dsh-cajita --latest。

安装后重启生效：dsh --profile web。

• 本地开发期（改动即时生效，link 形态）：dsh plugin --profile web add /path/to/dsh-cajita
• 卸载：dsh plugin --profile web remove @hpyperry/dsh-cajita

发布（维护者）

cd /path/to/dsh-cajita
# 升版本（npm version patch 等）→ 构建并发布
npm publish        # prepare 自动跑 tsc + tsdown 产出 lib/

scoped 公开包所需配置（publishConfig.access: public）已在 package.json 内； 发布前请确认 npm whoami 已登录（账号需与 @hpyperry scope 一致）。

📝 编辑消息（任务 1）

行为

1. 每条用户消息（含运行中插入的 steering 消息）的气泡下方，复制按钮旁出现「编辑」按钮；
2. 点击后原消息位置覆盖一条与官方输入框同宽、同款视觉的内联编辑卡（ChatGPT 式）， 文本域带出原消息文本（已发送的序列化文本），可直接继续编写；
3. 点「发送」或按 Enter（Shift+Enter 换行、Esc 取消）即发送一条新消息——内容为 编辑后的文本，与输入框正常发送无任何差别（同一 input machine → 同一 adjudication → 同一 sink）。

编辑框为简单文本编辑（与 ChatGPT 一致，不含 / 命令与 @ 引用补全——官方 未提供第三方输入框的可插拔补全 API；需要完整 / @ 能力时，可把编辑文本 setDraft 进主输入框继续编辑，见下「边界」）。

边界与异常处理

⚙️ 插件设置（设置 → 插件配置 → cajita 工具箱）

插件级设置收成一张与官方插件配置同风格的可展开卡片，三个即写开关 （写 $DSH_HOME/settings.yaml 的 cajita: 节，改完即时生效，无需重启）：

1. 编辑消息（默认开）：开启 = 用户消息气泡提供「编辑」按钮；关闭 = 立即恢复官方 气泡显示，随时可再开；
2. web_fetch 内网放行（默认关）：关闭 = 与官方完全一致（只允许公网目标）；开启 = 放行解析到私网/回环/内网（如 TUN fake-ip）的目标——TUN/代理用户需要开启。 web_fetch 不设单独的"子功能启停"：这个放行开关本身就是该功能；
3. 提醒通知（默认开）：agent 回合完成、弹出提问或需要审批时，页面不在前台则弹 浏览器系统通知，标题带场景前缀（完成 / 提问 / 待审批 / 出错）；首次使用先点 「授权系统通知」。自己正盯着页时不打扰。

🌐 web_fetch 内网放行（任务 2 / web-fetch-policy）

为什么需要它

官方 web_fetch 只允许访问公网目标：解析结果里出现私网/回环/fake-ip（如 TUN 代理常见的 198.18.0.0/15 或内网 DNS 回包）会整组拒绝。TUN / 代理模式下 DNS 常被 劫持成非公网地址，导致 web_fetch 全部失败。官方没有关闭这项检查的开关。

行为

• 默认关 = 与官方行为一致（只允许公网目标，安全不缩水）；
• 打开开关 = 放行内网：可抓取解析到私网/回环/内网地址的目标；
• 开关即点即生效，无需重启；模型侧 web_fetch 用法完全不变。

边界与异常处理

🧑‍💻 开发

pnpm typecheck   # tsc --noEmit
pnpm lint        # eslint（typescript-eslint recommended）+ prettier
pnpm test        # vitest（L0 纯函数 / L1 装载）
pnpm build       # tsc（node half）+ tsdown（client bundle）→ lib/

• 结构：src/（node half：插件身份 + web-fetch-policy 行）+ src/client/ （web half：index.ts 编排「绑定设置 → TOOLS 动态注册 → 注册设置卡片」+ locales.ts 汇总；每个功能独立目录 src/client/<tool>/，自带 register/组件/ 纯逻辑/字典片段/样式标签；插件级设置表面在 src/client/settings/）+ tests/ （按功能子目录）；
• 单插件多工具：所有小工具共用一个插件包与 cajita 文案/设置命名空间；新功能 = 新目录 + 在 src/client/index.ts 的 TOOLS 注册表登记（见 AGENTS.md §6.2）；
• 热更新：src/client/* 改动 pnpm build:client 后浏览器 ≤0.5s 自动热更新； node half 改动需重启 dsh web。

隔离开发环境（scripts/dev-isolate.sh）

所有开发/联调一律在独立 DSH_HOME（默认 ~/.dsh-dev）进行，真实 ~/.dsh 零接触（2026-08-17 事故教训：直接在真实 profile 联调可能污染真实会话日志）； rm -rf ~/.dsh-dev 即完全重置。

用指定版本的 dsh 测试（多版本兼容矩阵）

插件的依赖基线需要与宿主 dsh 版本族配对。默认 dev-isolate.sh 用 PATH 上的全局 dsh；要验证「本插件实现在 dsh 0.1.2-rc.1（当前 latest/next）上是否兼容」， 用 scripts/dsh-local.sh 取一个版本化本地安装（装进 ~/.dsh-tools/<版本>/， 与 npm 全局安装完全无关），再经 DSH_BIN 指给隔离环境：

# 例：在隔离环境用 dsh 0.1.2-rc.1 验证本插件（首次自动安装该版本 CLI）
DSH_BIN="$(DSH_VERSION=0.1.2-rc.1 ./scripts/dsh-local.sh)" \
  DEV_HOME="$HOME/.dsh-dev-rc1" \
  ./scripts/dev-isolate.sh --port 3091

• 宿主 @deepseek-ai/dsh 的 npm dist-tag latest/next 均已是 0.1.2-rc.1： 任何无 pin 的全局安装都会升级生产宿主，安装脚本/验证一律显式 pin 版本；

• 不同版本用独立 DEV_HOME（如 ~/.dsh-dev-rc1）与 profile，互不干扰； 依赖基线升级的破坏面/迁移结论记录在 docs/upgrade-dsh-*.md。

• 提示：若全局 npm 缓存目录（~/.npm）存在 root 属主文件导致 npm install 报 EPERM，可先 npm cache verify 修复，或为 dsh-local.sh 指定可写的 npm_config_cache 环境变量。

• 常用端口：--port 3090，浏览器访问 http://127.0.0.1:3090；

• 验证加载：启动日志（stdout）会列出装载的插件与 client bundle；也可 curl -s http://127.0.0.1:3090/ | head 确认 web 在服务；client 注册是否生效 以浏览器 UI 为准（编辑按钮出现在用户消息复制按钮旁）；

⚠️ 已知限制

• 接管式渲染：为在用户消息复制按钮旁加按钮，本插件 shadow 官方 user/steering 气泡渲染器（priority -1，数值最低者渲染）。官方气泡视觉升级时需手动同步（快照结构变化由 typecheck 兜底）；同 key 的第三方接管者按 shadow 链数值低者渲染；接管条目随「编辑消息」 开关运行时增删——关闭即 dispose、官方气泡即时恢复；
• 运行时"关闭 ≠ 卸载"（web_fetch）：关闭放行 = provider 锁定限制模式（行为与 官方逐字节等价，官方行仍被组合禁用）；真回滚官方行需 dsh plugin remove 并重启；
• 设置节迁移：v0.1.2 的 cajita-web-fetch: 设置节已并入 cajita: 节； 旧节残留无害，可手工从 settings.yaml 删除；
• 系统通知受浏览器限制：需用户授权一次（设置卡内按钮）；标签页需保持打开 （可后台/最小化）；http://127.0.0.1 这类本地地址是安全上下文可用，局域网 IP / 0.0.0.0 / 非 https 部署不可用；同 origin 多标签页会各自弹通知（官方无跨 标签协调）。
• 简单文本编辑：内联编辑框不含 / 命令与 @ 引用补全（官方未提供第三方输入框 的可插拔补全 API；官方输入框的补全落地硬接线到 composer 机器）。需要完整 / @ 能力时，可把编辑文本 setDraft 进主输入框继续编辑后发送；
• 不编辑图片消息的图片：编辑框只编辑文本部分（图片随原消息保留在气泡中，编辑后 的新消息仅含文本）；
• 不重写已发送消息：发送的是一条新消息（与需求一致），历史消息不变。

📄 License

MIT，与 DeepSeek Harness 一致。

📚 更多

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