mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-15 12:55:51 +00:00
docs: 重写 Auto Mode，从源码解剖改为分类器设计分析
移除 TypeScript 代码、源码路径索引和 prompt 模板细节， 聚焦两阶段分类流水线的速度/准确性权衡、 危险权限剥离的设计哲学和降级到更安全行为的策略。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
claude-code-best
@@ -1,263 +1,102 @@
|
||||
---
|
||||
title: "Auto Mode - AI 分类器驱动的自主执行模式"
|
||||
description: "详解 Claude Code 的 auto mode：基于 transcript classifier 的自动权限决策、两阶段分类流水线、危险权限剥离机制、模式切换状态管理、以及与 plan mode 的协作方式。"
|
||||
keywords: ["auto mode", "yoloClassifier", "transcript classifier", "权限分类", "自动执行", "两阶段分类"]
|
||||
title: "Auto Mode"
|
||||
description: "AI 分类器驱动的自主执行模式。理解两阶段分类流水线、危险权限剥离和分类器不可用时的降级策略。"
|
||||
keywords: ["auto mode", "自动执行", "AI 分类器", "权限分类"]
|
||||
---
|
||||
|
||||
## 概述
|
||||
## 核心问题
|
||||
|
||||
Auto mode 是 Claude Code 的一种权限模式，让 AI 进入**连续自主执行**状态。与传统模式（每个敏感操作都弹出权限对话框等待用户审批）不同，auto mode 使用 AI 分类器（transcript classifier）自动判断每个工具调用是否安全，从而实现无中断的执行体验。
|
||||
默认模式下，AI 执行每个敏感操作都需要用户确认。这在处理复杂任务时产生大量打断——一次重构可能需要确认 20 次文件编辑和 10 次命令执行。
|
||||
|
||||
Auto mode 的目标：**让 AI 连续自主执行，只在真正危险时才停下来。**
|
||||
|
||||
## 权限模式的层级
|
||||
|
||||
```
|
||||
权限模式层级：
|
||||
|
||||
default → auto → bypassPermissions
|
||||
default → auto → bypass
|
||||
（逐项确认） （AI 分类器审批） （全部放行）
|
||||
```
|
||||
|
||||
## 核心架构
|
||||
Auto mode 不是 bypass——它不是"什么都允许"，而是"让 AI 判断什么安全、什么危险"。
|
||||
|
||||
### 1. AI 分类器（yoloClassifier）
|
||||
## 核心架构：AI 分类器
|
||||
|
||||
分类器是 auto mode 的核心，位于 `src/utils/permissions/yoloClassifier.ts`。
|
||||
Auto mode 的核心是一个 AI 分类器。每个工具调用经过分类器评估，返回三种裁决：
|
||||
|
||||
每个工具调用经过分类器评估，返回三种裁决之一：
|
||||
| 裁决 | 含义 | 处理 |
|
||||
|------|------|------|
|
||||
| **allow** | 操作安全 | 直接执行 |
|
||||
| **deny** | 操作危险 | 拒绝并告知 AI |
|
||||
| **ask** | 无法确定 | 回退到用户确认 |
|
||||
|
||||
| 裁决 | 含义 | 处理方式 |
|
||||
|------|------|---------|
|
||||
| **allow** | 操作安全 | 直接执行，用户无感知 |
|
||||
| **deny** | 操作危险 | 拒绝执行，向 AI 返回拒绝消息 |
|
||||
| **ask** | 无法确定 | 回退到传统权限对话框 |
|
||||
**设计洞察**：分类器基于完整的对话上下文判断，而非只看单条命令。它能理解操作的意图——同样是 `rm` 命令，删除构建产物是安全的，删除源代码是危险的。
|
||||
|
||||
分类器的判断基于完整的对话上下文（transcript），而不仅仅看单条命令——它能理解操作的意图和上下文。
|
||||
## 两阶段分类流水线
|
||||
|
||||
### 2. 两阶段分类流水线
|
||||
分类器采用两阶段设计：
|
||||
|
||||
分类器支持两阶段 XML 分类（`classifyYoloActionXml`）：
|
||||
### Stage 1：快速判断
|
||||
|
||||
```
|
||||
Stage 1 — "fast"（快速判断）
|
||||
├── max_tokens=64，stop_sequences 触发即时 yes/no
|
||||
├── 如果 allow → 直接放行（最快路径）
|
||||
└── 如果 block → 进入 Stage 2
|
||||
使用短输出（最多 64 token）快速给出 allow/block 判断。大多数安全操作在这一阶段就被放行，延迟极低。
|
||||
|
||||
Stage 2 — "thinking"（深度思考）
|
||||
├── chain-of-thought 推理
|
||||
├── 减少误报（false positives）
|
||||
└── 最终决定 allow / deny / ask
|
||||
```
|
||||
### Stage 2：深度思考
|
||||
|
||||
两个阶段共享相同的 system prompt 和 user content，利用 API 的 prompt caching（1 小时 TTL）优化性能。
|
||||
Stage 1 判断为 block 的操作进入深度推理阶段，通过 chain-of-thought 减少误报。
|
||||
|
||||
可通过配置选择模式：
|
||||
- `'both'`（默认）— 两阶段都跑
|
||||
- `'fast'` — 只跑 Stage 1
|
||||
- `'thinking'` — 只跑 Stage 2
|
||||
|
||||
### 3. 分类器结果类型
|
||||
|
||||
```typescript
|
||||
// src/types/permissions.ts
|
||||
type YoloClassifierResult = {
|
||||
thinking?: string // 分类器的推理过程
|
||||
shouldBlock: boolean // 是否阻止
|
||||
reason: string // 决策原因
|
||||
unavailable?: boolean // 分类器是否不可用
|
||||
transcriptTooLong?: boolean // 对话是否超出上下文窗口
|
||||
model: string // 使用的分类器模型
|
||||
stage?: 'fast' | 'thinking' // 哪个阶段做出的决定
|
||||
// ... token 使用量、耗时等监控字段
|
||||
}
|
||||
```
|
||||
**设计考量**：两阶段设计在速度和准确性之间取得平衡。99% 的操作在 Stage 1 就能正确判断，只有少数模糊操作需要 Stage 2 的深度分析。这避免了每个操作都跑完整推理的性能开销。
|
||||
|
||||
## 安全机制
|
||||
|
||||
### 危险权限剥离
|
||||
|
||||
进入 auto mode 时，系统调用 `stripDangerousPermissionsForAutoMode()`（`permissionSetup.ts:510`），移除所有可能绕过分类器的 allow 规则。
|
||||
进入 auto mode 时，系统自动剥离所有可能绕过分类器的 allow 规则：
|
||||
|
||||
被剥离的规则类型（`dangerousPatterns.ts`）：
|
||||
| 被剥离的规则类型 | 原因 |
|
||||
|----------------|------|
|
||||
| Bash 解释器规则（python/node/bash） | 可执行任意代码 |
|
||||
| Agent allow 规则 | 会绕过分类器审批子 Agent |
|
||||
| 权限提升规则（sudo/eval） | 可执行任意命令 |
|
||||
|
||||
| 规则类型 | 示例 | 剥离原因 |
|
||||
|---------|------|---------|
|
||||
| **Bash 代码执行** | `Bash(python:*)`, `Bash(node:*)` | 解释器可执行任意代码，绕过分类器审查 |
|
||||
| **Shell 入口** | `Bash(bash:*)`, `Bash(sh:*)` | 直接 shell 访问等同无限制 |
|
||||
| **Agent 规则** | `Agent(*)` | 任何 Agent allow 规则会绕过分类器审批子代理 |
|
||||
| **PowerShell 代码执行** | `PowerShell(node:*)` | 同 Bash 逻辑 |
|
||||
| **权限提升** | `Bash(sudo:*)`, `Bash(eval:*)` | 可执行任意命令 |
|
||||
剥离的规则在退出 auto mode 时恢复。
|
||||
|
||||
剥离的规则被暂存在 `strippedDangerousRules` 中，退出 auto mode 时通过 `restoreDangerousPermissions()` 恢复。
|
||||
**设计哲学**：auto mode 的安全性依赖于分类器的判断。如果用户之前设置了"Bash: always allow"，分类器就被绕过了。剥离这些规则确保分类器是唯一的安全决策者。
|
||||
|
||||
### Circuit Breaker
|
||||
|
||||
远程配置可以在紧急情况下全局禁用 auto mode。这为 Anthropic 提供了远程紧急关停能力——如果发现分类器存在系统性漏洞，可以在不发布新版本的情况下立即禁用。
|
||||
|
||||
### 模型支持检测
|
||||
|
||||
不是所有模型都支持 auto mode。`modelSupportsAutoMode()`（`src/utils/betas.ts`）检查当前模型是否具备安全分类能力。不支持的模型无法进入 auto mode。
|
||||
|
||||
### Circuit Breaker 机制
|
||||
|
||||
`autoModeState.ts` 维护一个 circuit breaker 标志：
|
||||
|
||||
```typescript
|
||||
let autoModeCircuitBroken = false // 由远程配置控制
|
||||
```
|
||||
|
||||
当远程配置（GrowthBook `tengu_auto_mode_config.enabled`）设为 `'disabled'` 时，circuit breaker 触发，阻止 auto mode 的进入和继续使用。这为 Anthropic 提供了远程紧急关停能力。
|
||||
|
||||
## 模式切换状态管理
|
||||
|
||||
### 进入 Auto Mode
|
||||
|
||||
`transitionPermissionMode()`（`permissionSetup.ts:597`）处理所有模式切换：
|
||||
|
||||
```
|
||||
1. 检查 auto mode gate 是否开启（isAutoModeGateEnabled）
|
||||
2. 设置 autoModeActive = true
|
||||
3. 调用 stripDangerousPermissionsForAutoMode() 剥离危险规则
|
||||
4. 向对话注入 Auto Mode 系统提示
|
||||
```
|
||||
|
||||
### 退出 Auto Mode
|
||||
|
||||
```
|
||||
1. 设置 autoModeActive = false
|
||||
2. 设置 needsAutoModeExitAttachment = true（触发退出通知）
|
||||
3. 调用 restoreDangerousPermissions() 恢复被剥离的规则
|
||||
4. 向对话注入 "Exited Auto Mode" 提示
|
||||
```
|
||||
|
||||
### 触发路径
|
||||
|
||||
Auto mode 可通过以下方式激活：
|
||||
- CLI 参数 `--enable-auto-mode`
|
||||
- settings.json 中的 `autoMode` 配置
|
||||
- Plan mode 默认使用 auto mode 语义（`useAutoModeDuringPlan`，默认 true）
|
||||
- SDK 控制消息
|
||||
- REPL 中 Shift+Tab 切换
|
||||
不是所有模型都支持 auto mode。分类器需要特定的能力（如理解安全语义），不支持该能力的模型无法进入 auto mode。
|
||||
|
||||
## 系统提示词
|
||||
|
||||
### 进入时（Full Instructions）
|
||||
### 进入时
|
||||
|
||||
注入到对话中的指令（`messages.ts:3481`）：
|
||||
注入到对话中的指令要求 AI：
|
||||
1. **直接执行** — 做合理假设，减少提问
|
||||
2. **偏好行动** — 默认直接编码，不进 plan mode
|
||||
3. **避免破坏性操作** — 删除数据、修改生产系统仍需确认
|
||||
|
||||
> Auto mode is active. The user chose continuous, autonomous execution. You should:
|
||||
>
|
||||
> 1. **Execute immediately** — 直接实现，做合理假设
|
||||
> 2. **Minimize interruptions** — 常规决策自行判断，减少提问
|
||||
> 3. **Prefer action over planning** — 默认直接编码，不进 plan mode
|
||||
> 4. **Expect course corrections** — 用户可随时纠正
|
||||
> 5. **Do not take overly destructive actions** — 删除数据/修改生产系统仍需确认
|
||||
> 6. **Avoid data exfiltration** — 不主动分享密钥/内部文档
|
||||
### 退出时
|
||||
|
||||
### 持续运行时（Sparse Instructions）
|
||||
注入"退出 auto mode"提示，要求 AI 回到谨慎模式——方案不明确时提问而非假设。
|
||||
|
||||
后续轮次注入简短提醒：
|
||||
## 降级策略
|
||||
|
||||
> Auto mode still active. Execute autonomously, minimize interruptions, prefer action over planning.
|
||||
当分类器 API 不可用时：
|
||||
- **不直接 allow** — 回退到传统权限对话框
|
||||
- 告知 AI 分类器暂时不可用
|
||||
- 确定性错误（如对话过长）不重试
|
||||
|
||||
### 退出时（Exit Instructions）
|
||||
|
||||
> You have exited auto mode. Ask clarifying questions when the approach is ambiguous rather than making assumptions.
|
||||
**设计哲学**：降级到更安全的行为。宁可多确认一次，也不要在没有分类器保护的情况下自动放行。
|
||||
|
||||
## 与 Plan Mode 的协作
|
||||
|
||||
Plan mode 默认使用 auto mode 语义（`getUseAutoModeDuringPlan()`，默认 true）。这意味着：
|
||||
Plan mode 默认使用 auto mode 语义——在只读探索阶段，分类器自动判断哪些只读操作是安全的，进一步减少打断。
|
||||
|
||||
- Plan mode 进入时，如果 auto mode 可用，也会激活分类器
|
||||
- `isAutoModeActive()` 是权威信号（`prePlanMode`/`strippedDangerousRules` 不可靠）
|
||||
- 退出 plan mode 时会同时退出 auto mode
|
||||
## 接下来
|
||||
|
||||
## 分类器不可用的降级策略
|
||||
|
||||
当分类器 API 不可用时（`unavailable: true` 或 `transcriptTooLong: true`）：
|
||||
|
||||
- 不会直接 allow — 回退到传统的权限对话框（ask）
|
||||
- 向 AI 发送消息："{model} is temporarily unavailable, so auto mode cannot determine the safety of {toolName} right now."
|
||||
- 确定性错误（如对话过长）不重试，直接降级
|
||||
|
||||
## 分类器 Prompt 模板
|
||||
|
||||
分类器的行为由三个 prompt 文件控制，位于 `src/utils/permissions/yolo-classifier-prompts/`。这些文件在构建时通过 `require()` 内联为字符串常量，运行时不可修改。
|
||||
|
||||
### auto_mode_system_prompt.txt
|
||||
|
||||
主系统提示词，定义分类器的角色、分类流程和决策类别。包含：
|
||||
|
||||
- **分类流程**：理解操作 → 检查用户意图 → 评估风险
|
||||
- **BLOCK 始终阻止**：外部代码执行、不可逆删除、未授权持久化、安全削弱、提权、网络服务
|
||||
- **BLOCK 除非明确意图**：CWD 外写入、系统包管理、git push、大规模变更
|
||||
- **ALLOW 安全操作**：读文件、搜索、git 只读命令、测试/lint/构建、CWD 内编辑
|
||||
- `<permissions_template>` 占位符 — 运行时替换为具体权限模板（external 或 anthropic）
|
||||
- 末尾 `Use the classify_result tool to report your classification.` — XML 模式下被替换为 `<block>` 标签格式说明
|
||||
|
||||
### permissions_external.txt
|
||||
|
||||
外部用户版本的权限模板。三个 `<user_*_to_replace>` 标签内包裹默认规则（bullet 格式），用户自定义规则**整体替换**默认值：
|
||||
|
||||
```
|
||||
<user_allow_rules_to_replace>
|
||||
- 默认 allow 规则 1
|
||||
- 默认 allow 规则 2
|
||||
</user_allow_rules_to_replace>
|
||||
```
|
||||
|
||||
- **allow**：9 条默认规则（只读命令、版本检查、git 只读、测试/lint/构建、包安装、CWD 内文件操作等）
|
||||
- **soft_deny**：10 条默认规则（外部代码执行、递归删除、shell 配置修改、提权、网络服务等）
|
||||
- **environment**：4 条环境描述（终端环境、auto mode 上下文、开发工具可用、语言/框架不限）
|
||||
|
||||
`getDefaultExternalAutoModeRules()` 从此文件提取 bullet 项，供 `claude auto-mode defaults` 命令输出。
|
||||
|
||||
### permissions_anthropic.txt
|
||||
|
||||
Anthropic 内部版本的权限模板。默认规则在标签**外部**，标签内为空，用户自定义规则以**追加**方式叠加：
|
||||
|
||||
```
|
||||
- 默认规则（在标签外，始终生效）
|
||||
<user_allow_rules_to_replace>
|
||||
</user_allow_rules_to_replace>
|
||||
```
|
||||
|
||||
相比 external 版本，额外包含：
|
||||
- 云 CLI 只读命令（aws describe, gcloud describe, kubectl get 等）
|
||||
- 基础设施即代码 plan 命令（terraform plan, pulumi preview 等）
|
||||
- 对应的 deny 规则（云资源创建/修改/删除、IaC apply、生产环境访问等）
|
||||
|
||||
### 模板替换流程
|
||||
|
||||
```
|
||||
buildYoloSystemPrompt()
|
||||
├── BASE_PROMPT.replace('<permissions_template>', EXTERNAL/ANTHROPIC_TEMPLATE)
|
||||
├── .replace(<user_allow_rules_to_replace>, userAllow ?? defaults)
|
||||
├── .replace(<user_deny_rules_to_replace>, userDeny ?? defaults)
|
||||
└── .replace(<user_environment_to_replace>, userEnvironment ?? defaults)
|
||||
```
|
||||
|
||||
- 外部模板：用户设置非空时**替换**对应标签内容，否则保留默认值
|
||||
- 内部模板：用户设置**追加**到默认值之后（标签在末尾为空）
|
||||
|
||||
## 当前状态说明
|
||||
|
||||
> **注意**：auto mode 的完整代码逻辑已存在于代码库中，但依赖 `feature('TRANSCRIPT_CLASSIFIER')` feature flag。
|
||||
> 在当前反编译版本中，`feature()` 始终返回 `false`，因此 auto mode 不可用。
|
||||
> 要启用需将 `feature('TRANSCRIPT_CLASSIFIER')` 改为 `true`，并确保 GrowthBook 配置源有合理的 fallback 默认值。
|
||||
|
||||
Prompt 模板文件为**重建产物**——原始文件在反编译过程中丢失，已根据代码逻辑和 `yoloClassifier.ts` 中的替换模式重新编写。
|
||||
|
||||
## 相关源码索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/utils/permissions/yoloClassifier.ts` | 分类器核心实现 |
|
||||
| `src/utils/permissions/autoModeState.ts` | Auto mode 状态管理 |
|
||||
| `src/utils/permissions/permissionSetup.ts` | 模式切换、危险权限剥离 |
|
||||
| `src/utils/permissions/dangerousPatterns.ts` | 危险命令模式列表 |
|
||||
| `src/utils/permissions/classifierDecision.ts` | 分类器决策处理 |
|
||||
| `src/utils/permissions/classifierShared.ts` | 分类器共享逻辑 |
|
||||
| `src/utils/permissions/bashClassifier.ts` | Bash 命令分类规则 |
|
||||
| `src/utils/permissions/bypassPermissionsKillswitch.ts` | bypass 权限熔断器 |
|
||||
| `src/utils/permissions/yolo-classifier-prompts/auto_mode_system_prompt.txt` | 分类器主系统提示词 |
|
||||
| `src/utils/permissions/yolo-classifier-prompts/permissions_external.txt` | 外部权限模板 |
|
||||
| `src/utils/permissions/yolo-classifier-prompts/permissions_anthropic.txt` | 内部权限模板 |
|
||||
| `src/cli/handlers/autoMode.ts` | CLI `auto-mode` 子命令处理 |
|
||||
| `src/utils/messages.ts` | Auto mode 系统提示词注入 |
|
||||
| `src/types/permissions.ts` | 权限类型定义 |
|
||||
| `src/utils/betas.ts` | 模型 auto mode 支持检测 |
|
||||
- **权限模型** — 理解 auto mode 在权限体系中的位置
|
||||
- **Plan Mode** — 理解"先规划再执行"的安全工作流
|
||||
- **为什么安全很重要** — 理解安全体系的设计动机
|
||||
|
||||
Reference in New Issue
Block a user