@llangtop/dsh-approval-ai

English | 中文

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

配置

- 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：

/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 测试

在本仓库目录执行：

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

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

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，公开 npm 包名是 @llangtop/dsh-approval-ai；当前 0.1.0-rc.6 是预发布版本，建议使用 next dist-tag。

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

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

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

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，再安装这个文件：

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 表示；独立的人类应答器仍负责交互处理。