# @llangtop/dsh-approval-ai

[English](README.md) | 中文

面向 `approval/request` 的 AI 审批应答器。DSH 负责创建和路由审批请求；本插件只对已经产生的请求调用 `ctx.llm` 判断。插件不新增路径、工作区、Shell、沙箱或风险触发条件。默认路由为 provider `deepseek-official`、model `deepseek-v4-flash`；凭据和供应商协议由 LLM Adapter 管理。

## 配置

```yaml
- id: approval-ai
  name: '@llangtop/dsh-approval-ai'
  config:
    provider: deepseek-official
    model: deepseek-v4-flash
    mode: ai-only
    timeoutMs: 3000
    failClosed: true
```

`mode` 支持 `ai-only`、`ai-then-human` 和 `human-only`。插件接收进入其 listener 的每个审批请求，但不决定是否创建审批请求；`human-only` 始终委托。`ai-only` 将合法的 `allow` 映射为 `allowed-once`；拒绝、高/严重风险、review、非法输出、路由缺失、取消、超时和 Provider 错误均故障关闭。`ai-then-human` 按 `reviewOutcome` 处理 review，不依赖 listener 顺序表达优先级。

## 页面操作

在 Web 组合中，客户端 bundle 会贡献原生设置页卡片，宿主也会注册 `approval-ai` settings namespace。当 DSH Web settings API 暴露这个 namespace 时，可以打开“设置 → 插件 → 插件配置 → AI 审批”编辑 provider、model、mode 和 failClosed；“保存”会写入 namespace，“放弃”只丢弃当前页面修改，“重置”会清除用户覆盖。旧版本 `0.1.0-rc.5` 没有客户端卡片，安装 `0.1.0-rc.6` 或更新版本后需要重新启动 Web。

当前 DSH Web 宿主会在 `/api/settings.describe` 返回前，通过固定的 settings namespace 白名单过滤可暴露的设置。`approval-ai` 虽然已经由插件注册，但当前不在宿主白名单中，因此可能出现“插件已经安装、客户端 bundle 已加载，但设置卡片仍然没有”的结果。这是宿主 settings API 暴露限制，不是 slot 顺序、npm scope 或客户端导出问题。第三方插件自身不能把 namespace 加入宿主固定白名单；在宿主提供可扩展 settings 注册机制之前，请使用下面的 `/approval-ai` 命令。

插件注册 DSH 原生 `/approval-ai` 斜杠命令。Web 页面打开输入框的 `/` 命令菜单后即可选择或直接输入这些命令；修改会写入 `approval-ai` settings namespace，并即时作用于当前进程，不需要手改 `cordis.patch.yml`：

```text
/approval-ai                 查看当前 provider、model、mode 和 failClosed
/approval-ai enable          开启 AI 自动审批（ai-only）
/approval-ai disable         关闭 AI 审批并交给人工（human-only）
/approval-ai mode ai-only
/approval-ai mode ai-then-human
/approval-ai mode human-only
/approval-ai provider <id>   切换已注册的 LLM provider 路由
/approval-ai model <id>      切换该路由上的模型 ID
/approval-ai reset           清除本插件的用户覆盖，恢复组合配置
```

`provider` 必须是 DSH 当前已经注册的路由 ID，`model` 必须是该路由提供的模型 ID。`disable` 不会卸载插件，只会将它切换为 `human-only`，让 DSH 原有的人类审批页面接管请求。命令本身的结果会作为直接命令结果显示在会话中，不会发送给模型。

模型只接收 DSH 审批请求字段，以及显式配置的审批背景：当前路径、项目架构摘要、实施架构摘要、挂载的 `AGENTS.md` 指导和安全审批提示词。这些是配置值，不是插件读取的文件。插件不会读取项目、会话历史、工具 schema、凭据或主 system prompt，也不会将模型请求或响应写入 Agent 会话。参数和响应原因均有字节限制，模型输出会在运行时校验为 JSON。

## 本地开发与 DSH 测试

在本仓库目录执行：

```sh
pnpm install --frozen-lockfile
pnpm run typecheck
pnpm run build
npm pack --dry-run
```

要把 checkout 挂载到本地 DSH profile，请从 DSH 自己的仓库运行 CLI，并使用绝对路径：

```sh
cd /path/to/deepseek-harness
pnpm dsh plugin --profile approval-ai-local add /mnt/data/demo/dsh插件/approval-ai
pnpm dsh --profile approval-ai-local --dump-config
pnpm dsh --profile approval-ai-local
```

profile 的配置 dump 中应看到插入到现有审批服务旁边的 `approval-ai` 条目。默认 patch 使用 provider `deepseek-official`，因此 profile 需要可用的 DSH LLM 配置和凭据，审批请求才能得到 AI 应答。`pnpm dsh plugin --profile <profile> why @llangtop/dsh-approval-ai` 只能证明依赖已经进入 profile，不能证明 patch 已应用，也不能证明当前 Web 进程加载了新包。修改 profile 后需要停止并重新启动 `pnpm dsh web`。移除本地安装：`pnpm dsh plugin --profile approval-ai-local remove @llangtop/dsh-approval-ai`。

要验证尚未发布的真实 npm 包内容，先构建并打包本仓库，再把生成的 `.tgz` 绝对路径交给 `dsh plugin --profile <name> add /absolute/path/to/package.tgz`。

## 发布与安装

源码仓库是 [github.com/ang-XWBWZ/dsh-approval-ai](https://github.com/ang-XWBWZ/dsh-approval-ai)，公开 npm 包名是 `@llangtop/dsh-approval-ai`；当前 `0.1.0-rc.6` 是预发布版本，建议使用 `next` dist-tag。

在本仓库中使用具有 `@llangtop` scope 发布权限的 npm 账号登录并发布：

```sh
npm login
npm whoami
npm publish --access public --tag next
```

将已经发布的组合包安装到 DSH profile：

```sh
cd /path/to/deepseek-harness
pnpm dsh plugin --profile approval-ai add @llangtop/dsh-approval-ai@next
pnpm dsh --profile approval-ai --dump-config
```

`dsh plugin` 会读取包里的 `dsh.bundle.patch`，把包加入 profile，并在组合时应用 `cordis.patch.yml`。这个 patch 会把 `approval-ai` 行插入 DSH 现有审批服务旁边，不需要修改 DSH 源码。当前包的 peer 版本目标是 DSH `0.1.0-rc.6`、Cordis `4.0.1` 和 Schemastery `3.18.1`。

如果版本还没有发布到 npm，可以先生成 tarball，再安装这个文件：

```sh
pnpm pack
pnpm dsh plugin --profile approval-ai add /absolute/path/to/llangtop-dsh-approval-ai-0.1.0-rc.6.tgz
```

GitHub 仓库承担源码和发布工作区；npm 包和本地 tarball 是支持的运行时分发方式，因为 `prepack` 会构建发布所需的 `lib/` 产物。

## Model Experience

### 审批评估

#### 模型看到的内容

辅助模型看到固定的分类指令和包含最小审批字段的 JSON 用户载荷，必须返回 `decision`、`risk` 和 `reason`，且不能调用工具。

#### Token effect

每个审批请求产生一个有界的辅助请求。该请求独立于主对话，不加入主 transcript。

#### KV Cache effect

辅助请求不改变主对话缓存；传输缓存由 Provider Adapter 自行决定。

## 已知限制与延后工作

- 不提供审批结果缓存、永久授权或多模型仲裁；Web settings API 暴露卡片时，它只编辑本插件的四个运行时设置，不替代 DSH 的审批交互页面。宿主白名单隐藏卡片时，`/approval-ai` 命令仍是可用的配置入口。
- 当前 `ApprovalRequest` 携带工具参数，但不负责解析供应商特定的工作区上下文；有上下文时由调用方提供。
- 人工 review 通过 `reviewOutcome` 表示；独立的人类应答器仍负责交互处理。