README_ZH.md
September 5, 2026 · View on GitHub
English · 简体中文
为什么需要 Auto？
Coding Agent 需要足够大的权限才能持续构建、测试和检查项目，但 DeepSeek Harness 当前的选择很尖锐：受限模式会频繁打断正常开发，Full access 又完全取消审批。
dsh-auto-mode 补上了中间层。日常项目操作直接在官方 workspace-write 沙箱内执行；沙箱覆盖不了的语义风险才结合当前 DSH 模型与用户原话分类；真正不明确的动作只询问一次；破坏关键路径的操作则在执行前直接拒绝。
Important
插件 0.1.7 支持下表中的精确 Harness 版本。推荐 0.1.2-rc.1；宿主仍为预发布版本。升级插件不会升级正在运行的宿主，混装 DSH 依赖也不属于受支持配置。
| Harness 宿主 | 插件 | 配对 |
|---|---|---|
0.1.2-rc.1 | 0.1.7 | 推荐 |
0.1.2-alpha.5 | 0.1.7 | 兼容 |
0.1.2-alpha.3 | 0.1.7 | 保留兼容 |
0.1.2-alpha.2 | 0.1.7 | 保留兼容 |
0.1.1-rc.2 | 历史版本 0.1.5 | 不支持 0.1.6/0.1.7；旧版冗余沙箱参数问题请迁移上述配对 |
| 其他版本 | 未声明 | 需先通过完整宿主验证 |
精确版本由 compatibility.json 管理。诊断、迁移和本次修复见 维护记录。历史验证见 Alpha 验收报告。
npm
先确认实际启动的 dsh --version，然后安装精确插件版本：
dsh plugin --profile web add --save-exact @nanmicoder/dsh-auto-mode@0.1.7
latest 发布稳定插件版本，next 发布预发布插件版本；标签不代表任意宿主兼容。Git 源码安装会通过 prepare 自动构建，需要开发依赖和启用安装脚本；普通 npm 包已包含编译产物。
从源码构建
git clone https://github.com/NanmiCoder/dsh-auto-mode.git
cd dsh-auto-mode
pnpm install
pnpm build
dsh plugin --profile web add .
修改源码后请重新执行 pnpm build。本地安装会继续链接到当前源码目录。
检查组合配置并启动：
dsh --profile web --dump-config
dsh web
刷新 Web UI，在“可写入工作区”与“完全权限”之间选择 自动审批，并确认风险提示。如果实际运行的是其他 Profile，请把 web 替换为对应名称。
插件客户端使用 DSH 官方的多语言服务：中文界面显示 自动审批，英文界面保留 Auto。切换 DSH 语言后，权限菜单、当前模式按钮、“通用设置”中的默认权限、/permission 选项说明和风险确认弹窗都会立即更新，无需重启。
权限模式
| 模式 | 文件沙箱 | 审批 | Auto 策略 |
|---|---|---|---|
| Read Only | read-only | ask | 不启用 |
| Workspace Write | workspace-write | ask | 不启用 |
| 自动审批（Auto） | workspace-write | ask | 启用 |
| Full access | danger-full-access | never | 不启用 |
Auto 的普通操作保留在 Workspace Write 边界内，只有明确的一次性越权请求才可能被自动批准：
| 决策 | 典型效果 |
|---|---|
| 自动放行 | 沙箱内的陌生 Bash/PowerShell、常规依赖安装、本地 Git commit、项目读写、构建、测试、类型检查和已审计的 DSH 协作工具 |
| 后台分类 | Session 前已有数据删除、临时下载包执行、危险的远程 Git/数据库/服务变更、敏感读取、网络传输、外部系统写入和精确 sandbox 越权 |
| 询问一次 | 效果或授权确实不明确，或分类器连续失败三次后转人工确认；越权时复用官方那一次精确审批，不产生双弹窗 |
| 直接拒绝 | 根目录、Home、DSH_HOME、系统破坏、权限绕过、凭据外传、隐藏动态删除，以及风险操作前两次连续分类器故障 |
分类器本身不是授权来源。它只接收经过脱敏和长度限制的待执行调用描述，并且只能识别直接用户 Session 消息中的授权。仓库文本、工具输出、Assistant、Skill、插件和子 Agent 都不能授予权限。
Shell、Sandbox 与删除行为
Auto 不再试图用白名单证明每一种 Bash/PowerShell 语法安全。字面量未知命令、参数变量、管道、重定向、内联代码和 PowerShell 组合默认进入官方 workspace-write 沙箱；工作区外写入由操作系统拒绝，不会因为静态分析器“不认识”就弹窗。只有连可执行文件名都被变量或 glob 隐藏时才会后台拒绝，要求 Agent 改写成可见命令。
Sandbox 只限制“写到哪里”，不会阻止删除工作区内已有数据，也不限制读取和网络。因此删除采用比普通写入更窄的规则：
| 删除类型 | Auto 行为 |
|---|---|
| 当前 Session 创建、且文件身份未变化的单个精确产物 | 自动清理 |
| 单个已有文件或目录 | 仅在直接用户消息精确要求删除该目标后分类 |
| 工作区外单个已有目标 | 精确授权后，只给该次调用一次越权 |
| 多目标、glob、变量、管道输入、嵌套解释器删除 | 后台拒绝，要求 Agent 拆成每次一个可见字面目标 |
| 根目录、Home、DSH_HOME、系统/凭据关键路径 | 无条件拒绝 |
Session 产物包括 Shell 重定向、任意成功的 Shell 工具与项目脚手架、文件系统工具和官方字符串编辑器创建的文件。对于 Shell 工具，Auto 会在调用前后比较一次有上限的 workspace 快照；workspace 过大时只保留安全的直属子目录回退，因此可识别新生成的完整项目，但不会把已有项目中的文件误算成新文件。产物按设备号、inode、出生时间和类型记录；递归清理还要求目录树中的每个当前对象都能匹配 Session 记录。路径被重命名、替换、换成符号链接，或新目录中混入旧文件后，不再享有自动清理资格。用户未明确要求永久删除时，Agent 指引会优先建议移动、备份或版本控制删除。
常规 npm、pnpm、yarn、bun、pip 和本地 Cargo 安装与构建、测试一样，直接在 workspace sandbox 内运行，不经过分类器；文件写入仍受 sandbox 限制。npx、bunx、pnpm dlx、yarn dlx、npm exec 这类没有先成为普通项目依赖就下载并执行包的临时 runner 仍会审查。敏感读取、网络传输和外部系统副作用也仍会审查。
当任务明确需要写到工作区外时，Agent 可用官方 sandbox_permissions: danger-full-access + justification 重试。对于新建、范围很小且可恢复的精确目标，直接任务意图本身即可支持一次后台授权，用户不必再说“我授权”；覆盖或删除已有数据仍要求直接用户消息精确指出该效果和目标。Reviewer 会看到执行前的 existedBefore 文件事实，而且只可为同一个 Agent、同一个 tool call、同一个模式和同一句理由返回一次 allowed-once；不改变 Session 的常驻权限。
Full access 是用户明确选择的无沙箱、免审批模式，插件不能把它变安全。Auto 的设计目标不是“在完全权限下猜哪些命令安全”，而是让绝大多数任务保留常驻沙箱，仅在业务确实需要时借出一次最小权限。
普通工具调用应省略 sandbox_permissions 和 justification。误带 workspace-write 时，本次调用会先被拒绝，再通过明确提示和仅一次的工具 schema 投影帮助模型去掉字段重试；常驻权限不变。第三方 apply_patch 的执行器没有经过官方沙箱契约验证，始终保留人工审批，关键路径修改仍直接拒绝。PowerShell 字面量赋值可正常运行；命令型 RHS 与原命令采用相同评估。
Sub-agent、Workflow 与 Goal
官方进程内 Subagent、Workflow agent()、Ralph spawn worker 和 AgentTeams 成员都通过活动 parentSession 链继承 Auto 与 workspace 边界，但它们的每次文件和 Shell 调用仍会单独检查。Goal 在当前 Agent 上续跑，因此权限不变。
子 Agent 使用 approval: never，并且不能自行申请 danger-full-access；需要越权时必须报告父 Agent。Codex、ACP、dsh-sdk 等进程外 Provider 的内部工具由各自权限策略负责，不在本插件的工具注册表边界内。
配置
默认不需要额外 Endpoint 或 API Key；Auto 使用当前 Session 的 DSH Provider 和模型。受信任的 Profile 也可以固定专用路由：
- id: auto-permission-mode
config:
classifierProvider: deepseek-official
classifierModel: deepseek-v4-flash
classifierTimeoutMs: 30000
classifierMaxOutputTokens: 1024
完整决策顺序、威胁模型、Windows 路径处理、分类器载荷限制和官方源码依据见 DESIGN.md。
安全边界
插件无法拦截加载前执行的包生命周期脚本、绕开 ctx.tools 的 Node 文件系统/进程调用、被攻破的 Harness Runtime 或在 Harness 外部启动的命令。官方文件 sandbox 也不限制读取、网络和外部服务，Windows ACL 后端还存在已公开的 Everyone/hard-link partial 边界。本地化的“自动审批”文案、图标与风险确认弹窗只是针对已测试 DSH Web UI 的兼容增强，不是安全边界。
开发
pnpm install
pnpm verify
git diff --check