# 附录 V：工作区扩展与运行模式
> 工具的边界即思维的边界——扩展工作区，就是扩展可能性本身。
---
## 附录 V-A：Plan Mode V2（结构化规划）
### 功能描述
Plan Mode V2 是对基础计划模式的重大升级，引入了**多 Agent 并行探索**与**需求面试阶段**。当用户进入计划模式时，系统可以派出多个子 Agent 同时探索不同的实现路径，然后综合各路结果生成更高质量的执行计划。
### 核心文件
| 文件 | 说明 |
|------|------|
| `src/utils/planModeV2.ts` | 核心逻辑：Agent 数量决策、面试阶段开关 |
| `src/tools/EnterPlanModeTool/` | 进入计划模式的工具入口 |
| `src/tools/ExitPlanModeTool/` | 退出计划模式的工具入口 |
### 工作机制
**Agent 并发数决策**（`getPlanModeV2AgentCount()`）：
- `max` 套餐 + `20x` 速率限制，或 `enterprise` / `team` 计划 → **3 个 Agent**
- 其余套餐 → **1 个 Agent**（退化为经典单路计划）
- 环境变量 `CLAUDE_CODE_PLAN_V2_AGENT_COUNT` 可覆盖，上限 10
**探索阶段 Agent 数**（`getPlanModeV2ExploreAgentCount()`）：固定返回 3，与用户套餐无关。
**需求面试阶段**（`isPlanModeInterviewPhaseEnabled()`）：
- Anthropic 内部用户（`USER_TYPE=ant`）：始终开启
- 外部用户：由 `tengu_plan_mode_interview_phase` 功能 gate 控制
- 开启后，系统先与用户往返几轮确认需求，再触发多 Agent 并行探索
### 关键常量/配置
```typescript
// 环境变量覆盖 Agent 数（最大 10）
process.env.CLAUDE_CODE_PLAN_V2_AGENT_COUNT
// Gate 名称（GrowthBook 功能开关）
'tengu_plan_mode_interview_phase'
```
---
## 附录 V-B：Sandbox 沙箱隔离
### 功能描述
Sandbox 为 Agent 的文件系统操作和网络访问提供运行时隔离层。它不依赖操作系统级沙箱，而是在 Claude Code 层面通过白名单/黑名单规则过滤工具调用，并记录违规行为供后续审计。
### 核心文件
| 文件 | 说明 |
|------|------|
| `src/utils/sandbox/sandbox-adapter.ts` | FS 白名单/黑名单、网络 Pattern 匹配、违规拦截 |
| `src/utils/sandbox/sandbox-ui-utils.ts` | 违规记录的 UI 展示辅助函数 |
### 工作机制
1. **文件系统规则**：区分"允许读取路径"、"允许写入路径"、"明确禁止路径"三层规则，使用 Glob 模式匹配。
2. **网络主机过滤**：通过 Glob 匹配目标主机名，阻止 Agent 连接未授权外部服务。
3. **`SandboxViolationStore`**：收集运行时违规记录（工具名称、被拒绝的路径/主机），可通过 `/doctor` 命令汇总展示。
4. **运行时切换**：`/sandbox-toggle` 命令支持在不重启会话的情况下启用/禁用沙箱。
### 关键常量/配置
```typescript
// 触发违规日志的环境变量（通常由配置文件中的 sandbox 字段控制）
// 在 CLAUDE.md 或 .claude/settings.json 中配置 allowedPaths / deniedPaths
```
---
## 附录 V-C：Rewind（会话回溯）
### 功能描述
Rewind 是一个极简的"时光倒流"命令，允许用户将对话历史截断到某个历史节点，从而非破坏性地撤销 Agent 的后续操作。它的实现出人意料地简洁。
### 核心文件
| 文件 | 说明 |
|------|------|
| `src/commands/rewind/rewind.ts` | 核心实现，不足 20 行有效代码 |
### 工作机制
整个 Rewind 命令的 `call()` 方法只做两件事：
```typescript
async call(context) {
context.openMessageSelector() // 打开消息选择 UI
return { type: 'skip' } // 告知引擎跳过本次响应
}
```
`openMessageSelector()` 由 context 层负责：渲染一个时间线 UI，用户选中某条历史消息后，框架将内存中的消息数组截断到该节点之前。截断是内存操作，**不修改磁盘上的会话历史文件**，因此是非破坏性的。
### 关键常量/配置
无特殊配置，Rewind 是通用功能，不受功能 gate 限制。
---
## 附录 V-D：ultraplan 关键词触发
### 功能描述
ultraplan 是一个"魔法词"机制：当用户输入中出现特定触发词时，系统自动将其替换为 `plan`，并进入增强的计划模式。触发词识别算法包含复杂的边界检测逻辑，防止误触发。
### 核心文件
| 文件 | 说明 |
|------|------|
| `src/utils/ultraplan/keyword.ts` | 关键词位置检测，`findKeywordTriggerPositions()` |
| `src/utils/ultraplan/ccrSession.ts` | CCR（Cloud Code Runner）会话集成 |
### 工作机制
`findKeywordTriggerPositions()` 扫描用户输入，执行以下过滤：
| 不触发条件 | 说明 |
|-----------|------|
| 位于 `` ` ``、`'`、`"` 引号内 | 避免干扰代码/字符串 |
| 位于 `()`、`[]`、`{}` 括号内 | 避免干扰表达式 |
| 紧跟 `?` 字符 | `ultraplan?` 被视为提问，而非触发 |
| 以 `/` 前缀开头 | `/ultraplan` 作为 slash 命令单独处理 |
| 出现在路径中 | 防止误替换文件路径里的关键词 |
通过检测后，关键词被替换为 `plan`，输入转发给 LLM，后续走标准计划模式流程。
### 关键常量/配置
```typescript
// 触发词列表（硬编码在 keyword.ts 中）
// 具体关键词内容为内部实现细节
```
---
## 附录 V-E：Teleport（代码库传送到云端）
### 功能描述
Teleport 允许用户将本地代码库"传送"到 Anthropic 云端环境中运行 Agent，适用于无法在本地运行的复杂任务。它通过 Git Bundle 打包本地仓库（包含未提交的 WIP），上传后在云端 Session 中重建工作环境。
### 核心文件
| 文件 | 说明 |
|------|------|
| `src/utils/teleport/environments.ts` | 云端环境枚举与获取 |
| `src/utils/teleport/gitBundle.ts` | Git bundle 打包与上传逻辑 |
| `src/utils/teleport/api.ts` | Teleport API 调用层 |
### 工作机制
**环境类型**（`EnvironmentKind`）：
```typescript
type EnvironmentKind = 'anthropic_cloud' | 'byoc' | 'bridge'
// anthropic_cloud: Anthropic 托管云
// byoc: 用户自带云（Bring Your Own Cloud）
// bridge: 通过 Bridge 协议连接的 IDE 环境
```
**打包流程**（`gitBundle.ts`）：
1. `git stash create` → `update-ref refs/seed/stash`（使 WIP 可达）
2. `git bundle create --all`（打包 refs/seed/stash 及其所有对象）
3. 支持三级降级策略：`all`（完整历史）→ `head`（仅当前分支）→ `squashed`（单提交快照）
4. 上传到 `/v1/files` API，返回 `fileId`
5. 清理临时 ref `refs/seed/stash`
**默认 Bundle 大小上限**：100 MB（可通过 `tengu_ccr_bundle_max_bytes` 调整）。
**获取环境**（`fetchEnvironments()`）：需要有效的 OAuth token + 组织 UUID。
### 关键常量/配置
```typescript
// Bundle 大小上限（默认 100MB）
const DEFAULT_BUNDLE_MAX_BYTES = 100 * 1024 * 1024
// GrowthBook gate
'tengu_ccr_bundle_max_bytes'
```
---
## 附录 V-F：Asciicast 会话录制
### 功能描述
Asciicast 以 `.cast` 格式录制终端会话，用于回放、调试和分享。该功能仅对 Anthropic 内部用户开放，且需要主动设置环境变量启用。
### 核心文件
| 文件 | 说明 |
|------|------|
| `src/utils/asciicast.ts` | 录制文件路径生成、缓冲写入器 |
### 工作机制
**启用条件**（`getRecordFilePath()`）：
```typescript
// 必须同时满足两个条件，否则返回 undefined
USER_TYPE === 'ant' // 仅 Anthropic 内部用户
CLAUDE_CODE_TERMINAL_RECORDING === '1' // 显式启用
```
**文件路径格式**：
```
~/.claude/projects/<projectHash>/<sessionId>-<timestamp>.cast
```
**Resume 兼容**：使用 `--resume` 续接会话时，系统自动将旧录制文件重命名以匹配新 Session ID，保持录制连续性。
**写入性能**：`createBufferedWriter()` 提供缓冲写入，避免频繁 I/O 影响终端响应。
### 关键常量/配置
```bash
# 启用录制（仅对 USER_TYPE=ant 有效）
export CLAUDE_CODE_TERMINAL_RECORDING=1
```
---
## 附录 V-G：终端截图与对话导出
### 功能描述
Claude Code 支持将当前终端画面渲染为 PNG/SVG 图片并复制到系统剪贴板，也支持将整条对话导出为纯文本或 Markdown 文件。截图功能完全在进程内完成，零外部依赖。
### 核心文件
| 文件 | 说明 |
|------|------|
| `src/utils/ansiToPng.ts` | ANSI 转 PNG，内置位图字体渲染器 |
| `src/utils/ansiToSvg.ts` | ANSI 解析层（供 PNG 渲染器复用） |
| `src/utils/screenshotClipboard.ts` | 将渲染结果写入系统剪贴板 |
### 工作机制
**ANSI → PNG 渲染**（`ansiToPng.ts`）：
- 跳过 SVG 中间格式，直接位图渲染
- 内置 Fira Code Regular 24×48 位图字体（Base64 编码打包在源码中）
- 字体覆盖 ASCII 可打印字符 + `/stats` 输出使用的 Unicode 字符
- 渲染速度：**5–15 ms**（对比旧 resvg-wasm 方案的 224 ms）
- 零外部依赖（仅使用 Node.js 内置 `zlib`）
**字体许可**：Fira Code Regular（SIL OFL 1.1），Copyright © 2014–2021 The Fira Code Project Authors。
**`/export` 命令**：
- 将整条对话历史序列化为纯文本或 Markdown 格式
- 输出到文件或标准输出
- 支持 `--format text|markdown` 参数
### 关键常量/配置
```typescript
// 字形尺寸（位图字体渲染分辨率）
const GLYPH_W = 24 // 字形宽度（像素）
const GLYPH_H = 48 // 字形高度（像素）
```
---
## 下一附录
→ [appendix-VI-ux.md](appendix-VI-ux)（用户体验与彩蛋：Buddy 虚拟伴侣、Effort 模式、Chrome 集成、诊断工具）