dsh-approval-comment

Readme

# dsh-approval-comment

![dsh-approval-comment](docs/images/banner.png)

DSH（DeepSeek Harness）Web 审批增强插件：**无感替代内置审批窗口**，支持「拒绝并附言」，并在拒绝后**终止当前回合**、让模型**重新结合附言思考**。

- 纯 host + client 双半区插件，零第三方依赖、零构建步骤（纯 JS）。
- 不修改任何 `@deepseek-ai/dsh*` 核心包；核心升级不会覆盖本插件。
- 安装进 web profile 即生效（下次 `dsh web` 启动自动加载）。

## 解决的问题

默认审批流程有两个不符合真实工作场景的行为：

1. 点「拒绝」后，模型不会停下，而是继续下一轮思考、**猜测你拒绝的原因并换其他方案**：

   ![点「拒绝」后模型继续下一轮思考的演示](docs/images/problem-reject-continues.png)

2. 手动停止后，拒绝这件事**不进模型上下文**，下一次请求就"丢了上下文"。

本插件改为：

- 审批窗保持原样（警示条 + 工具名 + 允许一次/拒绝），并**新增一个附言（say some）输入框**。
- 四种组合行为：

| | 允许一次 | 拒绝 |
|---|---|---|
| **无附言** | 继续执行 | 中断任务（停止，等待下一条指令） |
| **有附言** | 附言一并生效，继续执行 | 据附言**调整并自动继续**（不停止） |

- 附言通过「插话（steer）」注入当前回合，模型在下一步立即读到并据此行动；拒绝与附言都留在 transcript 中，手动停止后也不丢上下文。

  ![审批窗口：附言框 + 允许一次 / 拒绝](docs/images/screenshot-approval-panel.png)

  ![拒绝并附言后，模型据附言调整（改写到工作目录）](docs/images/screenshot-reject-with-comment.png)

## 安装与卸载

### 方式一：GitHub Release（远程，推荐）

1. 在仓库 [Releases](https://github.com/MaYiFei1995/dsh-approval-comment/releases) 发布 `dsh-approval-comment-0.1.0.tgz`（`npm pack` 产物）后，目标设备执行：

```powershell
dsh plugin --profile web add https://github.com/MaYiFei1995/dsh-approval-comment/releases/download/v0.1.0/dsh-approval-comment-0.1.0.tgz
```

### 方式二：tgz 本地文件

先从 GitHub Release 下载 `.tgz`（或本机 `npm pack` 生成），再用本地路径安装：

```powershell
# 绝对路径
dsh plugin --profile web add C:\path\to\dsh-approval-comment-0.1.0.tgz

# 相对路径（锚定到执行命令的目录）
dsh plugin --profile web add ./dsh-approval-comment-0.1.0.tgz
```

### 方式三：git 源

```powershell
dsh plugin --profile web add git+https://github.com/MaYiFei1995/dsh-approval-comment.git
```

> git 源会运行 prepare 脚本，pnpm 默认拦截；需按 pnpm 提示把包名加入 profile 的
> `pnpm-workspace.yaml` 的 `allowBuilds`。Release tarball 是预构建产物，无需此步。

安装后重启 `dsh web`（`Ctrl+C` 后重新 `dsh web`）即可生效。验证：

```powershell
dsh --profile web --dump-config   # 应能看到 approval-comment 行
```

### 卸载

```powershell
dsh plugin --profile web remove dsh-approval-comment
```

卸载后重启 `dsh web` 生效；可用 `dsh --profile web --dump-config` 确认 `approval-comment` 行已移除。若曾从 GitHub Release / tgz 安装，删除 profile 里 `package.json` 对应的依赖条目即可（`dsh plugin remove` 会一并清理）。

## 工作原理

| 半区 | 文件 | 作用 |
|---|---|---|
| host | `lib/index.js` | `approval/request` 前置监听：观察拒绝结果 + **grant-next 一次性放行**（附言后模型据附言调整的越权调用不再弹窗）；`agent/pre-step` 守卫：纯拒绝 → `{ kind: 'reject' }` 终止回合，拒绝+附言 → 放行 |
| client | `lib/client.js` | 以 `conversation.composer` 链 `priority: 0` 顶替内置审批面板，新增附言框；允许/拒绝时若有附言，先经 `session.prompt(…, 'steer')` 注入附言再应答 |

时序（拒绝并附言）：

```
模型调用需越权的工具
  → 审批面板（本插件版）弹出，附言框可用
  → 用户填写说明并点「拒绝」
      a) 附言经 session.prompt(…, 'steer') 注入当前回合（插话）
      b) 应答 rejected → 工具结果 = the user rejected tool "X"（核心文本，不可改）
  → agent/pre-step 守卫：检测到刚被拒绝，且本步消息里有附言 → 放行（不终止）
  → 模型读到「拒绝 + 附言」→ 据附言调整并自动继续
  → 调整的越权调用命中 grant-next → 自动放行，不再弹第二次审批窗
```

允许并附言：附言同样以 steer 注入，工具照常执行，模型在下一步读到附言并据此调整；调整调用由 grant-next 自动放行，**全程只弹一次审批窗**。

无附言的纯「拒绝」：守卫返回 `{ kind: 'reject' }` 终止当前回合；模型停止并等待你的下一条指令。

`approval/policy = 'never'` 的自动拒绝（无人值守/CI）在应答链之前短路，**不受**停止守卫影响。

## 构建与分发

```powershell
npm run check   # 契约校验（host/client 半区、package.json、cordis.patch.yml 的挂载契约）
npm run build   # 别名：同 check（本插件纯 JS，无需转译）
npm pack        # 产出 dsh-approval-comment-<version>.tgz（上传到 GitHub Release 即可）
```

> 仓库自带 GitHub Actions：`push` 时跑语法+契约校验并产出 tarball；推 `v*` tag 时自动把
> tarball 作为 Release 资产发布。

## 目录结构

```
├── lib/index.js          # host 插件（ESM，零依赖）
├── lib/client.js         # client 插件（__ModuleLoader__ bundle，零依赖）
├── cordis.patch.yml      # bundle 层：insert 挂载 host 半区
├── package.json          # dsh.bundle.patch + dsh.client 声明
├── scripts/check.mjs     # 契约校验脚本
├── .github/workflows/ci.yml
└── docs/DESIGN.md        # 设计文档
```

## 已知边界

- 审批面板以 `reason`（或"工具 X 请求越权执行"）为标题；内置面板额外显示的命令原文未复刻（需复用会话内部 helper，属于非必要）。
- **grant-next 是一次性授权，回合作用域**：只放行附言后紧接着的那一次越权调用；`turn/end` 或离开附言调整步即作废，不跨回合残留。源于用户主动附言，风险可控。
- **允许+附言时原命令先执行**：审批语义是"批准本次调用"，附言无法改写已定参数，故旧参数命令先执行，模型再据附言自动修正（grant-next 放行）。要完全跳过旧参数需上游支持改参执行。
- 若目标设备无可用审批 UI（非 web 场景），应答链回退为 `unavailable`，行为与现状一致。
- 客户端半区改动后需浏览器硬刷新（非 dev 模式无热更新）。

## 声明

本项目代码及文档由 deepseek-v4-pro 模型生成。

## License

[MIT](./LICENSE)