SiriLee/dsh-edit-approval

dsh-edit-approval

为 DeepSeek Harness 提供先询问后执行的审批：每次 write / edit / str_replace_editor 调用都在文件真正落盘前先询问——弹出红绿行级 diff，同意一次 / 拒绝——每次 bash 命令执行前也先询问，两者在 Settings → General 各有独立总开关。

npm version
npm license

刻意保持聚焦，只做一件事：两扇镜像对称的审批门——编辑与命令——让 agent 未经你同意就无法改动文件或执行命令。

| 审批门 | 拦截目标 | 默认 | 面板 |
| --- | --- | --- | --- |
| 编辑审批 | write / edit / str_replace_editor | 开 | 红绿行级 diff——同意一次 / 拒绝 |
| 命令审批 | bash | 关 | 描述 headline + 原生命令行 |

两扇门共用 harness 自带的 serviceAsk seam：插件在 tools/pre-execute 返回 { kind: 'ask', reason }，harness 将其路由进 Web 审批面板——host 端零 UI 改动——allowed-once 继续执行、rejected 拒绝调用；在 never 策略下插件直接委托，全权会话照常工作。

效果预览

安装后 Settings → General 出现两行开关——编辑审批 / 命令审批。所有写类调用先弹出红绿 diff 面板；开启命令审批后，每条命令先弹出面板：白色 headline 是 agent 的描述，灰色行是命令原文。

Settings → General 总开关
编辑审批面板——红绿行级 diff

命令审批面板——描述 + 命令
/approval-edit 与 /approval-bash 命令

安装

dsh plugin --profile web add dsh-edit-approval

装完重启 dsh web（--profile web）生效。

给贡献者：可从本地 checkout、pin 的 commit 或离线 tarball 安装——dsh plugin --profile web add /path/to/dsh-edit-approval、dsh plugin --profile web add github:SiriLee/dsh-edit-approval# 或 npm pack 后 dsh plugin --profile web add ./dsh-edit-approval-.tgz。git 安装首次会失败：pnpm 默认禁止 git 依赖执行构建脚本，需先在 profile 的 pnpm-workspace.yaml 加 allowBuilds；之后 pnpm 会执行插件的 prepare 并装入 profile。npm pack 同样运行 prepare，tarball 内始终包含预构建 lib/（含 .d.ts）与 LICENSE。

使用

1. 编辑审批默认开启。 任何 write / edit / str_replace_editor 调用都在文件被触碰前先询问。面板只显示改动行——删除红色、新增绿色——带右对齐 NN| 行号 gutter，被跳过的上下文与 hunk 间隔以 … 省略号标记。
2. 同意一次 / 拒绝。 allowed-once 放行该调用；rejected 拒绝并反馈给模型。
3. 命令审批默认关闭——在 Settings → General 或通过下面的命令开启。面板白色 headline 是描述（如 bash · push to remote）；下方灰色行是命令原文，由 harness 原生渲染。
4. 命令行入口： /approval-edit on|off|status 与 /approval-bash on|off|status——与设置行同源。
5. 白名单（仅配置文件）： bash-approval 设置命名空间下，allow 存放始终放行的命令前缀。匹配做了空白归一化（git  push 命中 git push），无法用多余空格绕过。暂不提供 UI。

原理

插件监听 tools/pre-execute 瀑布（harness 在工具执行前的 seam），按工具名分派到两扇门之一——名称重叠时编辑门优先。

1. 编辑审批

对每个被拦截的写类调用：

1. 解析目标文件：经 ctx.fs 解析路径，沿用 fs 工具的会话 cwd 规则（相对路径含 .. 时对 cwd 做规范化）。
2. 读取当前内容并按工具参数重建拟写入内容，镜像各工具语义：write — 全文；edit — 唯一替换（或 replace_all）；str_replace_editor — str_replace 唯一替换、insert 按行插入、create 用 file_text。
3. 计算行级 diff：用 jsdiff 的 structuredPatch（Myers）——与 harness 的 write/edit 结果卡同一参考实现、同一 3 行上下文窗口——因此审批预览与执行后的结果卡同源同形，大文件里改 1 行仍是 1 行 diff。
4. 返回 { kind: 'ask', reason }：头部一行（工具名 · 文件 (操作): N insertions, M deletions）加 diff 文本。harness 的 serviceAsk 经 ctx.approval 路由进 Web 审批面板。

2. 命令审批

纯决策，不碰 fs——不读不写任何东西：

- 门关闭、工具不在 tools 列表、命令为空，或属于沙箱升级调用（带 sandbox_permissions + justification——它们自带审批，不能二次弹窗）时直接放行。
- 白名单优先：空白归一化后的前缀命中即免询问放行。
- 否则返回 { kind: 'ask', reason }，headline 单行——bash · （描述为空时退化为 bash）。命令文本不嵌入 reason：harness 会在面板命令行原生渲染，避免内容重复。

3. 共享策略处理

会话审批策略（ask / never）持续生效。在 never（如 danger-full-access）下，插件发出的每个 ask 都会被审批服务确定性转为拒绝，导致全权会话里所有编辑与命令被静默打断——因此两扇门都通过 next() 委托、交由沙箱约束。插件绝不扩大权限，也不改变沙箱模式。

4. 审批面板

浏览器端（dsh.client）按动画帧合并的 MutationObserver 发现并增强面板，所有副作用收敛在单个 ctx.effect（卸载 / HMR 时完整清理）：

- 编辑面板：把纯文本 headline 重建为仅改动行——删除红色、新增绿色、右对齐 NN| 行号——并注入 white-space: pre-wrap 补偿样式、为多行 diff 安装折叠按钮。
- 命令面板：保持 harness 原生——只打 dsh-ea-kind-command 标记，不重写、不重排——白色描述 headline 与灰色命令行就是 harness 原样渲染的结果。

配置

运行时配置位于两个设置命名空间——edit-approval 与 bash-approval——层级为*schema 默认值 =24.0.0。
- DeepSeek Harness web 配置档（dsh --profile web）；@deepseek-ai/ peer 包由 harness 运行时提供。
- 声明对准已实测的 DSH 范围：每个受支持的版本元组一个 || 项——^0.1.0-rc.6 || ^0.1.1-rc.2 || ^0.1.2-rc.1 || ^0.1.5-rc.1（@deepseek-ai/dsh-settings 保留自身的 ^0.1.0-rc.8 地板），并由 dsh.engines.dsh 声明运行时下限 >=0.1.0-rc.6。npm 预发布匹配要求候选与比较器处于同一 [major, minor, patch] 元组，且没有任何简写能表达「0.1.x 全系列预发布」，因此每新增一个元组系列就要追加一个 || 项；同一元组内的 rc 滚动（rc.2 → rc.3）无需更新。node scripts/check-dsh-version.mjs 守护这份声明（各 peer 元组序列一致、engines 下限同步、没有发布超出上限）。0.1.2 的 alpha 线以及未经实测的 0.1.3-alpha.2 不在声明窗口内：客户端仍按能力存在探测而非解析版本号，alpha 线的兼容分支保留，但不再作为声明目标。
- 客户端按能力存在探测版本（ctx.get('uiConversation') 是否解析、会话快照是否仍携带 chat/pending），绝不解析版本字符串。会话/聊天读取走双通道适配器：rc.2 读会话面快照的 chat/pending，alpha.1+ 读 uiConversation 服务的命名 "chat" 视图；两代都缺则退化为 undefined（不崩）。注册工具名是 str_replace_editor（下划线），与 npm 包名 @deepseek-ai/dsh-tool-str-replace-editor 不同。

[!WARNING]
本项目与 DSH 均处于 developer preview。可复现环境请固定精确版本，并留意上文的行为说明。

安全

插件仅在 tools/pre-execute 拦截点读取目标文件以计算编辑预览；命令门完全不碰文件。它从不自行写入文件——只有在你批准后，工具本体才执行写入。无网络请求，不访问任何凭据。

开发

npm install            # devDeps 来自 npm registry
npm run typecheck      # tsc 双编译面（host + client）
npm test               # vitest：diff / guard / command-guard / display-parity / 集成 / client 套件
npm run build          # 全量构建：tsc → lib/（含 .d.ts）+ lib/client.js bundle
npm run build:portable # 可选：轻量 esbuild 构建，不做类型检查
node scripts/verify-host.mjs   # 对 BUILT host 产物做端到端验证（两个命名空间 + 全部命令路径）

prepare 生命周期运行全量构建，因此 git 安装与 npm pack / npm publish 始终得到完整的 lib/（含 .d.ts）与 LICENSE。

发布

发版走 GitHub Actions Trusted Publishing（OIDC，无需存储 NPM_TOKEN）。详见 docs/npm-trusted-publishing-guide.md。

npm version patch && git push origin main --tags   # 触发 .github/workflows/publish.yml

workflow 会校验 tag 与 package.json 版本一致，执行 typecheck + 测试 + 全量构建 + 产物验证，以 Sigstore provenance 发布并创建 GitHub Release。CI（.github/workflows/ci.yml）在每次 push / PR 上运行同样的检查。发布步骤幂等——版本已在 npm 则跳过。

许可

MIT