企业官网建设流程全解析

dcode 如何配置 Manual、Auto 与 YOLO 审批模式控制代理副作用？

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents

在运行deepagents-code（命令名dcode）会话时，代理会请求执行execute（shell）、写/改/删文件、Web 工具、task、异步子代理控制以及非只读 MCP 工具等带副作用的调用。审批模式（Approval Mode）就是用来控制这些调用是逐个人工批准、交给分类器自动审查、还是直接放行的按会话策略。本文介绍如何在 dcode 中通过快捷键、斜杠命令和启动参数在 Manual、Auto、YOLO 三种模式间切换，以及如何在无人值守场景下配合 shell 白名单限定代理能执行的命令。适用对象是本地 TUI、ACP 模式和 headless 模式的使用者；所有模式行为来自仓库中 Permissions and Human Approval 概念文档与 dcode 会话工作流。

三种模式分别控制什么

dcode 的ApprovalMode是一个每会话策略，取值manual、auto、yolo，三者对"被审批门控的工具调用"（即上面列出的副作用工具）的处理方式不同：

两个关键的默认与边界：

• 失败关闭（fail closed）：无效、非字符串的持久化值一律强制回退为manual；审批模式记录存于每线程的 LangGraph Store 记录（命名空间("deepagents_code", "approval_mode")，键为线程 ID 的 SHA-256 哈希）。Store 缺失、记录损坏、键错误或读取异常都会返回None，调用方按 Manual 处理——控制状态丢失时宁可多问人，也不会静默变成自主执行。
• Auto 不是无差别放行清单：它先跑确定性策略，再做分类器审查；其确定性 shell 放行范围刻意收窄，只允许固定仓库命令或已配置的命令条目，且要先拒绝 shell 控制语法和宽泛的可执行文件/通配条目。
• 沙箱会话不支持 Auto：基于远程 sandbox 的会话中 Auto 不可用，模式循环中会跳过它。

在会话中切换模式：Shift+Tab 与斜杠命令

在交互 TUI 中最直接的切换方式是Shift+Tab，循环顺序为 Manual → Auto → YOLO → Manual，规则如下：

• 只有当 Auto 可用时才包含 Auto（沙箱会话中会被省略）；
• 只有当 YOLO 切换器启用时才包含 YOLO（由startup.yolo_switcher配置控制，见下文）；
• 退出 YOLO 时固定回到 Manual，而不是循环回 YOLO 之前的模式。

首次通过 Shift+Tab 进入 YOLO 时，会弹出与--yolo相同的本地确认框（acknowledgement），需要确认当前策略版本的无审查模式风险警告后，YOLO 才会真正生效；确认持久化在安装私有的approval.json状态文件中，按策略版本（当前版本2026-07-14）一次性记录。如果确认写入 Store 失败，会话停留在原模式并提示YOLO could not be persisted; remaining in the previous mode.。

除快捷键外，dcode 提供对应的斜杠命令，效果与 Shift+Tab 切换器一致：

沙箱会话中输入/auto会被拒绝；/yolo同样受startup.yolo_switcher策略约束并触发首次确认。命令一览可参见 COMMANDS.md。

用启动参数指定初始模式

两种模式也可以通过命令行参数在启动时就确定，参数定义见 main.py：

# 启动本地 TUI 或 ACP 服务器并启用分类器辅助的 Auto 模式； # headless 模式下该参数被忽略并给出警告 dcode -y # 在一次性本地风险确认后，以 YOLO（无审查）运行门控动作； # 适用于交互 TUI 或 ACP 模式；headless 模式下被忽略并警告 dcode --yolo

两点注意：

• -y/--auto-approve与--yolo属于同一个互斥参数组，一次只能给其一；
• 两个参数在 headless 模式（dcode -n "..."）下都会被忽略并警告，headless 的审批控制走下面一条路径——shell 白名单。

禁用 YOLO 切换器：startup.yolo_switcher

如果组织不希望交互式会话能进入无审查模式，可以关闭 YOLO 切换器条目。该开关的解析见 config.py 的is_yolo_switcher_enabled()：

• 配置项为startup.yolo_switcher，默认启用；
• 在config.toml中设为假值即可让团队分发关闭策略；
• 也可用环境变量DEEPAGENTS_CODE_YOLO_SWITCHER设为0、false、no等假值（说明见 _env_vars.py）。

关闭后的效果：Shift+Tab 循环只剩 Manual（或 Manual/Auto）；但已经通过--yolo启动进入 YOLO 的会话仍可用 Shift+Tab 退出，退出后回到 Manual。

Headless 场景：用 shell 白名单约束副作用

headless 模式（例如dcode -n "run the focused tests" --max-turns 8 --timeout 600）每次进程都会创建新的 UUID7 线程，不进入交互审批。此时控制副作用的主要手段是-S/--shell-allow-list：

# 仅允许逗号分隔的指定命令自动执行 dcode -n "run the focused tests" -S "uv run,git status" # 使用内置的安全默认命令列表 dcode -n "run the focused tests" -S recommended # 允许任意命令（等价于不受限 shell，需谨慎） dcode -n "run the focused tests" -S all

行为规则（见 permissions-hitl.md 与 run-dcode-session.md）：

• 未提供白名单时，headless 下 shell 访问直接禁用；
• 提供限制性列表后，ShellAllowListMiddleware在执行前检查execute调用，白名单外的命令直接返回错误ToolMessage，而不是走中断/恢复流程；
• 白名单为空是非法输入；all（SHELL_ALLOW_ALL哨兵值）不能与具体命令混用，且非交互场景若使用不受限 shell，应改用auto_approve=True，它会禁用所有 HITL 中断。

验证当前处于哪种模式

• 状态栏：YOLO 激活期间状态栏有持久的YOLO指示器；同时会弹出YOLO is active: gated actions run without review.提示。该提示可通过/notifications或把"yolo"加入[warnings].suppress静音，但静音只是外观性的——进入 YOLO 仍需显式确认，状态栏指示器会一直存在，这是老用户静音提示后唯一的会话内信号。
• 行为验证：让代理触发一个门控调用（例如执行一条 shell 命令）。Manual 下会弹出审批面板等待 approve/reject；Auto 下分类器允许的调用直接继续、被拒绝的变成错误消息、require_human的调用升级为人工提示；YOLO 下无暂停直接执行。
• 追踪元数据：YOLO 激活时，运行会在 trace 元数据中记录dcode_auto_approve=True，可在追踪系统中筛出"未经 HITL 审批就执行了工具"的运行（见 config.py 的流配置说明）。
• 失败关闭验证：如果 Store 中该线程的审批模式记录丢失或损坏，下一次读取会按 Manual 处理并记录告警日志，而不是回到 Auto/YOLO——这是设计行为，不属于故障。

限制与边界

• 审批模式只门控"模型请求的工具调用"，不门控启动时对项目文件的读取；工作目录本身是信任边界，不要在宿主机上直接跑不受信任的 checkout，需要主机隔离时应使用远程 sandbox。
• Auto 与 YOLO 都不可用于 sandbox-backed 会话（Auto 被明确排除；沙箱中 YOLO 循环条目也会被省略的说明只涉及 Auto 的资格判断，YOLO 条目由startup.yolo_switcher单独控制）。
• ask_user工具只用于提问，不是审批门控，不能拿它当审批替代。
• 模式状态是每线程的：切换影响当前会话线程，其他线程各自维持自己的记录。

进一步阅读：Permissions and Human Approval、Run a dcode Session、config.py 中的is_yolo_switcher_enabled()与 approval_mode.py 中的模式持久化实现。

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents