# @duke-dsh-plugins/dsh-agent-approval 中文文档 规范地址：https://npmcn.com/package/%40duke-dsh-plugins/dsh-agent-approval/ 版本：1\.12\.2 npm 元数据更新时间：2026-11-04T15:18:37.446Z 中文译文更新时间：2026-11-13T00:46:22.072Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40duke-dsh-plugins/dsh-agent-approval 原文对照：https://npmcn.com/package/%40duke-dsh-plugins/dsh-agent-approval/?lang=original 项目主页：https://github.com/MoonlitDropOfBlood/dsh-agent-approval 源码仓库：https://github.com/MoonlitDropOfBlood/dsh-agent-approval ## 关键信息（来自 npm 元数据） - 包体积（解压后）：346 kB，10 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：1 个 - peer 依赖：@deepseek-ai/dsh ^0\.1\.5-rc\.3 \|\| ^0\.2\.0-rc\.1 \|\| ^0\.2\.1-rc\.0，@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-typert-protocol ^0\.1\.0-rc\.7 \|\| ^0\.1\.7-rc\.1 \|\| ^0\.2\.0-rc\.1 \|\| ^0\.2\.1-rc\.0 - 首次发布：2026-08-22T23:08:32.190Z - 最新版本发布：2026-11-04T15:18:36.812Z - 近 30 天下载量：2655（2026-10-13 至 2026-11-11，npm 官方下载统计） - 已发布版本数：28（近 12 个月 28 个） ## 中文简介 DeepSeek Harness的代理决定批准:一个QQ许可模式,每个沙盒升级都由一个LLM(默认法官:一个没有子代理会话的直接LLM呼叫;可选的孤立法官子代理)加一个独立的QQ ## 安装 ```sh npm install @duke-dsh-plugins/dsh-agent-approval ``` 也可以使用：`pnpm add @duke-dsh-plugins/dsh-agent-approval`、`yarn add @duke-dsh-plugins/dsh-agent-approval`、`bun add @duke-dsh-plugins/dsh-agent-approval` ## README ### DeepSeek Harness 自动审批权限插件 ![DSH plugin](https://img.shields.io/badge/DSH-Plugin-4D6BFE?style=flat) [![MIT License](https://img.shields.io/badge/license-MIT-2EA44F?style=flat)](https://npmcn.com/package/%40duke-dsh-plugins/dsh-agent-approval/LICENSE) ![Web UI](https://img.shields.io/badge/Web%20UI-Yes-22C55E?style=flat) 中文 * * * 为 [DeepSeek Harness（DSH）](https://github.com/deepseek-ai/deepseek-harness) Web UI 打造的 **自动审批**权限插件：当内置的权限选项（`workspace-write + ask` / `danger-full-access + never`）不能满足需求时，为会话开启第三种模式——**以 workspace-write 为基线，提权请求交由独立审批 Agent 裁决，有风险就拒绝**。 ## 功能 | 功能 | 说明 | | --- | --- | | 🛡 **权限菜单第四项** | `/permission` 菜单新增 **自动审批** 预设；选中即开启，切到其他预设自动关闭，跨重启保持 | | ⚙️ 原生设置导航图标 | DSH 0.2.2-rc.1 起通过官方 `settings.section.icon`、按 section id 注册 shield-check；旧宿主保留兼容 fallback，核心齿轮与自定义图标不会同时显示 | | 🤖 新权限模式 | 开启后：沙箱基线固定 `workspace-write`，审批策略切到 `ask`（内部接管），**不再弹人工审批** | | 🤖 自动裁决（默认 LLM 直连） | 每次提权请求由**一次 LLM 直连调用**裁决（v1.8.0 起默认）：与子代理同一套审批人格 / 提示词 / 结构化裁决 `{decision, riskLevel, rationale}`，但**不创建审批子会话**（零上下文污染）；设置页可切回「隔离子代理」（一次性 `spawn` 子代理：独立会话、零工具、只读材料） | | 🕵️ 自动审查（逐调用，实验） | 与自动审批**完全独立**的第二种模式（需先在设置页配置 Jev，配置即启用）：**Full access 基线**，每个工具调用（含 PTC 内层）执行前经 Jev 判定一次，风险调用**直接拒绝、body 不执行、不转人工**（fail-closed）；规则表与会话内信任先行短路降噪；`/agent-review on|off` 或菜单「自动审查」开启。v1.9.0 起**有效代码展开**：命令引用的解释器脚本（node / python / bash / ps1）内容会被读出并放进裁决 state，agent 临时写的脚本按**实际代码**受审而不是只看命令行（仅读 workspace 内文件，越界只标注、永不读取）。v1.12.0 起**沿委派链覆盖子代理**：宿主把满权限传给了子会话，子会话（含孙会话）的机器改动同样受审（自动审批不传播，仍不递归审批）；v1.12.1 修复宿主初始化时自动补齐 Full-access 预设被误判为显式退出、导致继承未生效的问题 | | ⛔ 风险即拒绝 | 破坏性 / 不可逆 / 越界（含修改操作系统或其他应用数据）/ 理由与实际命令不符 → 直接 `reject`；仅"安全、可逆、与任务相符、理由诚实"才 `approve`——项目自身的安装/部署脚本写其文档指定路径属任务所需 | | 🔒 Fail-closed | 审批 Agent 启动失败、超时（可配 30s–600s）、结果不合法 → 一律按拒绝处理，绝不静默放行 | | ⚙️ 审批模型可配置 | 设置页选择 Provider + Model（**只能是 LLM 路由**），不选则固定用 **Harness 默认模型**（不跟随请求会话，口径稳定）；选择与超时**持久保存**，重启不丢 | | ⚡ TypeSafe Jev 决策模型（仅自动审查） | Jev（System One 结构化决策模型）是**自动审查模式专属**的判定后端：设置页「自动审查」卡片独立配置（API Key / Endpoint / 模型 / 置信度阈值），直连其 API 用类型化问题（Choice/Noul）毫秒级返回带校准概率的裁决；置信度低于阈值按 fail-closed 处理，审计理由由概率合成（也可设 `TYPESAFE_API_KEY`）。**v1.10.0 起不再是自动审批的判定选项**——Jev 的风险判断弱于 LLM，而提权正是人工审批原本要守住的路径 | | 📋 审计记录（随会话） | 会话窗口顶部的\*\*「审批」标签页\*\*（轨迹旁）查看本会话全部审批：结论 / 风险等级 / 模型 / 耗时 / 理由；悬停看完整理由与**精确工具参数**；审批 Agent 的会话 id 可回溯完整推理；已批准行可一键\*\*「加白」**存为放行规则。记录存在**会话存储目录内的独立文件\*\*——随会话恢复，删除会话即随之删除；大量记录按页加载、后台增量同步，避免反复整文件读取与整表重渲染。宿主半尚未重启（升级了包但没重启 DSH）时，标签页会自动回退到旧的全量读取方式，记录照常可见 | | 🔁 可逆开关 | 权限菜单「自动审批」预设、`/agent-approval on|off` 命令两条等价路径；关闭时**恢复开启前的权限旋钮** | ## 工作原理 ``` 开启（菜单 / 命令） └─ 记住旧旋钮 → sandbox/mode=workspace-write + approval/policy=ask（规范写路径，可恢复） │ 工具请求提权（sandbox_permissions / 人工 ask） └─ ctx.approval.request() → approval/request 瀑布 └─ 本插件 prepend 抢占（先于人工弹窗 answerer） ├─ （默认）LLM 直连裁决（一次 stream 调用 · 同套人格/提示词/裁决格式 · 零子会话） ├─ （可选）spawn 审批 Agent（独立会话 · 零工具 · 结构化裁决 · 不会递归审批） │ ├─ approve → allowed-once（该次放行） │ ├─ reject → rejected（风险操作，最终拒绝） │ └─ 超时/故障/低置信/取消 → fail-closed（按拒绝处理） └─ 记入审计（会话目录内的独立文件，「审批」标签页可见） ``` - 审批 Agent 只能看到：workspace 路径、**最近的用户消息**（任务上下文）、工具名、提权理由、**精确的工具参数 JSON**（按 `callId` 从会话日志回查）。裁决看"操作 vs 用户任务"的客观对齐，不依赖理由措辞。 - 子代理审批策略被 DSH 委派机制钉死为 `never`，不存在递归审批；全局工具全部空白，审批员只能"判"不能"做"。 - 未开启的会话完全不受影响（监听器原样 `next()`，人工审批行为不变）。 ## 安装 ### 标准安装（推荐） 本插件是**标准 DSH bundle**：`package.json` 声明 `dsh.bundle.patch`，包内 `cordis.patch.yml` 同时完成两件事——`- insert:` 挂载插件本身，`- id: permission` 把 **自动审批** 预设注册进 `/permission` 菜单。用官方 `dsh plugin` 命令安装： ```bash # 本地开发：pnpm 软链到本仓库，改代码即生效（无需重新复制） dsh plugin --profile web add /path/to/dsh-agent-approval # 正式发布：从 GitHub Release tarball 安装（资产名为 npm pack 的 scope 形式） dsh plugin --profile web add https://github.com/MoonlitDropOfBlood/dsh-agent-approval/releases/download/v1.8.0/duke-dsh-plugins-dsh-agent-approval-1.8.0.tgz ``` 重启 DSH 后：设置面板出现 **自动审批** 页；`/permission` 菜单出现第四项 **自动审批**。 > **可选：权限菜单图标**。菜单图标硬编码在官方 `dsh-client-ui-conversation` 的 `permissionGlyphs` 映射里（无公开注册口），标准安装不会补它——不跑下面的命令只是**菜单项没有图标**，预设与功能不受影响。想让菜单项带盾牌图标，装完再跑一次（幂等；DSH 升级重装原版 bundle 后重跑即可）： > > ```bash > npm run patch:glyph > ``` > `dsh plugin add` 把插件装成 profile 的 npm 依赖并追加到 `dsh.profile.bundles`，启动时自动应用包内 patch。卸载：`dsh plugin --profile web remove dsh-agent-approval`。 ## 使用 1. **开启**：在 `/permission` 菜单选 **自动审批**，或输入 `/agent-approval on`。 2. **自动裁决**：之后该会话里的提权请求（例如命令被沙箱拒绝后带 `sandbox_permissions` 的重试）不再弹窗，由审批 Agent 在后台裁决并放行/拒绝。 3. **审计**：会话窗口顶部的\*\*「审批」标签页\*\*（轨迹旁）查看本会话的审批记录；悬停"审批理由"看完整理由与工具参数；已批准行可「加白」存为放行规则。记录存在会话存储目录内的独立文件，删除会话即随之删除；v1.4 的旧全局记录用 `node scripts/migrate-records.mjs` 一次性迁移（`--dry-run` 预览）。 4. **配置自动审批**：设置 → **自动审批** 设置审批模型（Harness 默认模型或指定 Provider/Model——**只能是 LLM 路由**）、**裁决方式**（LLM 直连 / 隔离子代理）、审批超时与放行/拒绝规则。 5. **配置自动审查（独立）**：设置页「自动审查」卡片填 Jev 的 API Key（可调 Endpoint / 模型版本 / 置信度阈值）——保存后**自动审查变为可选**（`/permission` 菜单出现 **自动审查** 预设），**不会改动任何已有会话**。要进入该模式，在目标会话里选 **自动审查** 预设或执行 `/agent-review on`：该会话切到 Full access 基线，**每个工具调用**执行前经 Jev 判定，风险调用直接拒绝（不转人工）；该会话派生的子代理沿委派链**同样受审**（子代理继承了满权限，就必须有人判定）；关闭恢复原旋钮。 6. **关闭**：菜单切回其他预设，或 `/agent-approval off`，恢复开启前的沙箱模式与审批策略。 ## 目录结构 ``` dsh-agent-approval/ ├── index.js # Host 半：AgentApprovalService（审批瀑布抢占 + LLM 直连/子代理裁决 + Jev 逐调用审查 + 审计） ├── judge-context.js # 审批上下文增量投影与旧 Host 的 seq 校验缓存 ├── audit-store.js # 审计 JSONL 增量索引与稳定分页游标 ├── client.js # Client 半：设置页「自动审批」+ 会话「审批」审计标签页 bundle ├── typert.host.js # Typert Host manifest（agentApproval 12 个 Remote 方法的描述） ├── cordis.patch.yml # dsh bundle patch（挂载行 + permission 预设表覆盖） ├── scripts/patch-glyph.mjs # 可选：权限菜单图标补丁（标准安装不自动执行） ├── scripts/check-typert-manifest.mjs # npm run check 用：双代 Typert codec 契约冒烟 ├── .github/workflows/ # GitHub Actions 发布 ├── AGENTS.md # 面向 AI agent 的开发指南（含踩坑） └── LICENSE # MIT ``` ## 开发 ```bash npm run check # 语法 + Typert + 模式/审批上下文/审计分页完整回归 npm run bench:performance # 可选：五万事件、两千审计记录的本地性能基准 dsh plugin --profile web add /path/to/dsh-agent-approval # 安装/重装到本机 DSH profile npm run patch:glyph # 可选：权限菜单图标 ``` **兼容性**：支持 DSH 0.1.5-rc.3 ~ 0.1.7-rc.1。v1.7.0 起 Typert manifest / Client Remote 描述符的每个 codec 同时携带 `schema`（≤0.1.5 的 zod 契约）与 `create()` 工厂（0.1.7 的新契约），任一宿主代际都能注册；旧版本（≤1.6.0）在 0.1.7 上会被 typert-loader 以 "has no create() factory" 拒绝，Remote 全部失效。 详见 [AGENTS.md](https://npmcn.com/package/%40duke-dsh-plugins/dsh-agent-approval/AGENTS.md)——记录了 DSH 正式插件（Host/Client/Typert 三件套）的完整机制、审批瀑布 prepend 抢占与结构化子代理裁决的踩坑。 ## License 本项目遵循 [MIT License](https://npmcn.com/package/%40duke-dsh-plugins/dsh-agent-approval/LICENSE)。 > 本项目是基于 DeepSeek Harness 构建的社区插件，并非 DeepSeek 官方产品。 ## 常见问题 ### @duke-dsh-plugins/dsh-agent-approval 是什么？ DeepSeek Harness的代理决定批准:一个QQ许可模式,每个沙盒升级都由一个LLM\(默认法官:一个没有子代理会话的直接LLM呼叫;可选的孤立法官子代理\)加一个独立的QQ ### 如何安装 @duke-dsh-plugins/dsh-agent-approval？ 在项目目录运行 npm install @duke-dsh-plugins/dsh-agent-approval，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）、@deepseek-ai/dsh-typert-protocol（^0\.1\.0-rc\.7 \|\| ^0\.1\.7-rc\.1 \|\| ^0\.2\.0-rc\.1 \|\| ^0\.2\.1-rc\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @duke-dsh-plugins/dsh-agent-approval 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/duke-dsh-plugins\_\_dsh-agent-approval 是否存在。 ### @duke-dsh-plugins/dsh-agent-approval 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @duke-dsh-plugins/dsh-agent-approval 可以商用吗？ @duke-dsh-plugins/dsh-agent-approval 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @duke-dsh-plugins/dsh-agent-approval 的下载量有多少？ 根据 npm 官方下载统计，@duke-dsh-plugins/dsh-agent-approval 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,655 次，日均约 89 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @duke-dsh-plugins/dsh-agent-approval 还在维护吗？ 最新版本 1\.12\.2 发布于 2026/11/04（8 天前）；至今共发布 28 个版本，其中过去 12 个月发布了 28 个；首次发布于 2026/08/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。