cx-viewer 1.0.0

package/concepts/zh-TW/GlobalSettings.md

@@ -0,0 +1,232 @@
+# CX-Viewer 全局配置参考
+
+## 一、全局设置面板（UI）
+
+通过左上角菜单 → "全局设置" 打开。
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| 过滤无关请求 | 开关 | 开 | 隐藏心跳、count_tokens、子代理等非主代理请求 |
+| 默认展开 Body Diff JSON | 开关 | 关 | 请求详情面板中的 Body Diff 区域默认展开 |
+| 日志目录设置 | 文本输入 | `~/.codex/cx-viewer` | 项目日志的读写根目录，支持 `~/` 展开。修改后回车或失焦保存，立即生效 |
+
+## 二、显示设置面板（UI）
+
+通过左上角菜单 → "显示设置" 打开。
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| 折叠工具结果 | 开关 | 开 | 聊天视图中折叠工具调用结果块 |
+| 展开思考过程 | 开关 | 开 | 默认展开 Claude 的思考/推理过程块 |
+| 完整展示所有内容 | 开关 | 关 | 显示完整的工具调用内容，不截断 |
+| 自动恢复会话 | 开关 + 选项 | 关 | 遇到会话恢复提示时自动选择：`继续` 或 `新建` |
+
+## 三、偏好设置文件
+
+所有 UI 设置持久化到 `<日志目录>/preferences.json`，通过 `/api/preferences` 接口读写。
+
+```json
+{
+  "lang": "zh",
+  "filterIrrelevant": true,
+  "expandDiff": false,
+  "collapseToolResults": true,
+  "expandThinking": true,
+  "showFullToolContent": false,
+  "logDir": "~/.codex/cx-viewer",
+  "resumeAutoChoice": null,
+  "disabledPlugins": [],
+  "presetShortcuts": []
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `lang` | string | 界面语言（zh/en/zh-TW/ko/ja/de/es/fr/it/da/pl/ru/ar/no/pt-BR/th/tr/uk） |
+| `filterIrrelevant` | boolean | 过滤无关请求 |
+| `expandDiff` | boolean | 默认展开 Body Diff JSON |
+| `collapseToolResults` | boolean | 折叠工具结果 |
+| `expandThinking` | boolean | 展开思考过程 |
+| `showFullToolContent` | boolean | 完整展示内容 |
+| `logDir` | string | 日志目录路径 |
+| `resumeAutoChoice` | null / "continue" / "new" | 自动恢复会话选择 |
+| `disabledPlugins` | string[] | 已禁用的插件文件名列表 |
+| `presetShortcuts` | array | Agent Team 快捷指令预设 |
+
+## 四、环境变量
+
+### CX-Viewer 专有
+
+| 变量名 | 默认值 | 说明 |
+|--------|--------|------|
+| `CXV_LOG_DIR` | `~/.codex/cx-viewer` | 日志存储根目录。特殊值：`tmp`/`temp` 使用系统临时目录 |
+| `CXV_CLI_MODE` | 未设置 | `=1` 启用 CLI 模式（PTY 终端） |
+| `CXV_SDK_MODE` | 未设置 | `=1` 启用 Agent SDK 模式（无终端） |
+| `CXV_WORKSPACE_MODE` | 未设置 | `=1` 启用工作空间选择模式 |
+| `CXV_PROJECT_DIR` | `process.cwd()` | 项目工作目录，用于文件操作和 Git 命令 |
+| `CXV_PROXY_PORT` | 未设置 | 本地 MITM 代理端口 |
+| `CXV_BYPASS_PERMISSIONS` | 未设置 | `=1` 跳过工具权限审批（配合 `--dangerously-skip-permissions`） |
+| `CXV_DISABLE_DELTA` | 未设置 | `=1` 禁用增量日志存储，每次写入完整消息 |
+| `CXV_DEBUG` | 未设置 | `=1` 启用 HTTP 代理调试日志 |
+| `CXV_DEBUG_PLUGINS` | 未设置 | `=1` 启用插件加载调试日志 |
+
+### 内部 IPC
+
+| 变量名 | 说明 |
+|--------|------|
+| `CXVIEWER_PORT` | 服务端口，供 ask-bridge/perm-bridge 通信 |
+| `CXV_EDITOR_PORT` | 服务端口，供 ccv-editor 文件编辑桥接 |
+
+### 外部变量（读取）
+
+| 变量名 | 说明 |
+|--------|------|
+| `OPENAI_BASE_URL` | 自定义 Anthropic API 地址 |
+| `SHELL` | 用户 Shell（PTY 启动和 Shell 配置检测） |
+| `http_proxy` / `HTTPS_PROXY` 等 | HTTP 代理配置（通过 undici EnvHttpProxyAgent） |
+
+## 五、CLI 命令参数
+
+```
+ccv [选项] [claude 参数...]
+```
+
+### CX-Viewer 专有选项
+
+| 参数 | 说明 |
+|------|------|
+| `-logger` | 安装/修复 Codex hooks |
+| `--uninstall` / `-uninstall` | 卸载所有 CX-Viewer 集成 |
+| `--help` / `-h` / `help` | 显示帮助信息 |
+| `--version` / `-v` | 显示版本号 |
+| `-SDK` / `--sdk` | 使用 Agent SDK 模式 |
+| `--d` | `--dangerously-skip-permissions` 简写 |
+| `--ad` | `--allow-dangerously-skip-permissions` 简写 |
+| `run` | 通过代理运行命令（`ccv run -- claude ...`） |
+
+### Claude 透传参数（常用）
+
+| 参数 | 说明 |
+|------|------|
+| `-c` / `--continue` | 继续上一次会话 |
+| `-r` / `--resume` | 恢复指定会话 |
+| `-p` / `--print` | 非交互式输出 |
+| `--model` | 指定模型 |
+| `--permission-mode` | 权限模式 |
+| `--system-prompt` | 自定义系统提示词 |
+| `--max-budget-usd` | 最大预算 |
+
+## 六、Hook 配置
+
+CX-Viewer 自动注册到 `~/.claude/settings.json` 的 `hooks.PreToolUse` 中：
+
+### 1. AskUserQuestion 桥接
+- **匹配器**: `"AskUserQuestion"`
+- **命令**: `node <安装目录>/lib/ask-bridge.js`
+- **作用**: 将 Claude 的问题转发到 Web UI，等待用户回答
+
+### 2. 权限审批桥接
+- **匹配器**: `""` (空 = 匹配所有工具)
+- **命令**: `node <安装目录>/lib/perm-bridge.js`
+- **作用**: 仅 `Bash`/`Edit`/`Write`/`NotebookEdit` 需要 Web UI 审批，其余自动放行
+
+## 七、Shell 集成
+
+CX-Viewer 在 `~/.zshrc`（或 `.bashrc`）中注入 `claude()` 函数：
+
+```bash
+# >>> CX-Viewer Auto-Inject >>>
+claude() { ... }
+# <<< CX-Viewer Auto-Inject <<<
+```
+
+所有 `claude` 命令自动通过 CX-Viewer 代理，实现日志捕获和 Web UI 功能。
+
+卸载：`ccv --uninstall` 或手动删除标记之间的内容。
+
+## 八、代理配置（Proxy Profile）
+
+存储在 `<日志目录>/profile.json`，通过 UI 的"代理切换"面板管理。
+
+```json
+{
+  "active": "max",
+  "profiles": [
+    { "id": "max", "name": "Default" },
+    { "id": "my-proxy", "name": "自定义", "baseURL": "https://...", "apiKey": "sk-..." }
+  ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `active` | 当前激活的配置 ID（`"max"` = 直连，无代理） |
+| `id` | 唯一标识 |
+| `name` | 显示名称 |
+| `baseURL` | 代理 API 地址（替换请求 origin） |
+| `apiKey` | 代理 API 密钥（替换认证头） |
+| `models` | 可用模型列表 |
+| `activeModel` | 当前选中的模型 |
+
+## 九、插件系统
+
+插件目录：`<日志目录>/plugins/`
+
+### 支持的 Hook 类型
+
+| Hook | 类型 | 说明 |
+|------|------|------|
+| `httpsOptions` | 瀑布 | 提供 HTTPS 证书（返回 `{ cert, key }` 或 `{ pfx }`） |
+| `localUrl` | 瀑布 | 修改本地访问 URL |
+| `serverStarted` | 并行 | 服务器启动通知 |
+| `serverStopping` | 并行 | 服务器停止通知 |
+| `onNewEntry` | 并行 | 新日志条目写入通知 |
+
+插件启用/禁用通过 `preferences.json` 的 `disabledPlugins` 数组管理。
+
+## 十、目录结构
+
+```
+~/.codex/cx-viewer/               # 日志根目录
+├── preferences.json               # 用户偏好设置
+├── workspaces.json                # 工作空间注册表
+├── profile.json                   # 代理配置
+├── plugins/                       # 插件目录
+│   └── my-plugin.js
+├── <项目名>/                       # 每个项目的日志目录
+│   ├── <项目名>_20260404_123456.jsonl  # JSONL 日志文件
+│   ├── <项目名>.json              # 统计数据（后台生成）
+│   └── images/                    # 上传图片的持久副本
+└── ...
+
+/tmp/cx-viewer-uploads/            # 临时上传文件目录
+```
+
+## 十一、服务器配置
+
+| 配置 | 值 | 说明 |
+|------|-----|------|
+| 端口范围 | 7008-7099 | 自动扫描可用端口 |
+| 绑定地址 | 0.0.0.0 | 所有网络接口 |
+| 访问令牌 | 随机 16 字节 hex | 局域网访问需要 `?token=xxx`，本机免认证 |
+| HTTPS | 仅通过插件 | 需要插件提供 `httpsOptions` hook |
+| CORS | `*` | 允许所有来源 |
+| 上传限制 | 50MB | 单文件最大上传大小 |
+
+## 十二、URL 参数
+
+| 参数 | 说明 |
+|------|------|
+| `?token=xxx` | 局域网访问认证令牌 |
+| `?logfile=path` | 打开指定历史日志文件（只读模式） |
+
+## 十三、localStorage 配置
+
+| 键 | 说明 |
+|-----|------|
+| `cxv_cacheExpireAt` | 缓存倒计时到期时间 |
+| `cxv_cacheType` | 缓存类型标签 |
+| `ccv_sseSlim` | 启用 SSE 增量裁剪（桌面端性能优化） |
+| `ccv_calibrationModel` | KV-Cache 上下文窗口校准模型 |
+| `ccv_fileExplorerOpen` | 文件浏览器面板开关 |
+| `cx-viewer-terminal-width` | 终端面板宽度（像素） |

package/concepts/zh-TW/KVCacheContent.md

@@ -0,0 +1,49 @@
+# KV-Cache 快取內容
+
+## 什麼是 Prompt Caching？
+
+當你與 Claude 對話時，每次 API 請求都會發送完整的對話上下文（system prompt + 工具定義 + 歷史訊息）。Anthropic 的 prompt caching 機制會將已經計算過的前綴內容快取在伺服端，後續請求如果前綴一致，則直接複用快取結果，跳過重複計算，大幅降低延遲和費用。
+
+cx-viewer 中將這一機制稱為「KV-Cache」，對應的是 Anthropic API 層面的 prompt caching，而非 LLM 內部 transformer 注意力層的 key-value cache。
+
+## 快取的工作原理
+
+Anthropic 的 prompt caching 按照固定順序拼接快取鍵：
+
+```
+Tools → System Prompt → Messages（到 cache breakpoint）
+```
+
+只要這個前綴與 TTL 視窗內的任意一次請求完全一致，API 就會命中快取（返回 `cache_read_input_tokens`），而非重新計算（`cache_creation_input_tokens`）。
+
+> **Codex 對 `cache_control` 屬性並不強依賴，伺服端會配合剔除部分這些屬性，但依然能夠很好的建立快取，所以沒有看到 `cache_control` 屬性並不代表沒有被快取**
+>
+> 對於 Codex 這類特殊用戶端，Anthropic 伺服端並不完全依賴請求中的 `cache_control` 屬性來決定快取行為。伺服端會對特定欄位（如 system prompt、tools 定義）自動執行快取策略，即使請求中未顯式攜帶 `cache_control` 標記。因此，當你在請求體中沒有看到該屬性時不必疑惑——伺服端已在幕後完成了快取操作，只是未將此資訊暴露給用戶端。這是 Codex 與 Anthropic API 之間的一種默契。
+
+## 「當前 KV-Cache 快取內容」是什麼？
+
+cx-viewer 中顯示的「當前 KV-Cache 快取內容」，是從最近一次 MainAgent 請求中提取的、位於快取邊界（cache breakpoint）之前的內容。具體包括：
+
+- **System Prompt**：Codex 的系統指令，包含核心 agent 指令、工具使用規範、CLAUDE.md 專案指令、環境資訊等
+- **Tools**：當前可用的工具定義列表（如 Read、Write、Bash、Agent、MCP 工具等）
+- **Messages**：對話歷史中被快取的部分（通常是較早的訊息，直到最後一個 `cache_control` 標記處）
+
+## 為什麼要查看快取內容？
+
+1. **理解上下文**：了解 Claude 當前「記住」了哪些內容，幫助你判斷它的行為是否符合預期
+2. **費用優化**：快取命中時費用遠低於重新計算。查看快取內容可以幫助你理解為什麼某些請求觸發了快取重建（cache rebuild）
+3. **除錯對話**：當 Claude 的回答不符合預期時，檢查快取內容可以確認 system prompt 和歷史訊息是否正確
+4. **上下文品質監控**：在除錯、修改設定或調整 prompt 的過程中，KV-Cache-Text 提供了一個集中的視角，幫助你快速確認核心上下文是否出現劣化或被意外內容污染——無需逐條翻閱原始報文
+
+## 多級快取策略
+
+Codex 對應的 KV-Cache 並非只有一份。伺服端會為 Tools 和 System Prompt 單獨生成不同的快取，與 Messages 部分的快取相互獨立。這樣設計的好處是：當 messages 堆疊出現錯亂（如上下文截斷、訊息修改等）需要重建時，不會連帶 Tools 和 System Prompt 的快取一起失效，避免全部重新計算。
+
+這是現階段伺服端的一個優化策略——因為 Tools 定義和 System Prompt 在正常使用過程中都相對穩定，很少變化，單獨快取它們可以最大限度地減少不必要的重建開銷。所以你在觀察 Cache 的時候會發現，除了 Tools 重建需要全部重新刷新快取以外，System Prompt 和 Messages 的破壞都仍然有可以繼承的快取可用。
+
+## 快取的生命週期
+
+- **建立**：首次請求或快取失效後，API 會建立新快取（`cache_creation_input_tokens`）
+- **命中**：後續請求前綴一致時複用快取（`cache_read_input_tokens`）
+- **過期**：快取有 5 分鐘的 TTL（存活時間），超時後自動失效
+- **重建**：當 system prompt、工具列表、模型或訊息內容發生變化時，快取鍵不匹配，觸發對應級別的快取重建

package/concepts/zh-TW/MainAgent.md

@@ -0,0 +1,23 @@
+# MainAgent
+
+## 定義
+
+MainAgent 是 Codex 在非 agent team 狀態下的主幹請求鏈路。每一次使用者與 Codex 的互動，都會產生一系列 API 請求，其中 MainAgent 請求構成了核心對話鏈路——它們攜帶完整的 system prompt、工具定義和訊息歷史。
+
+## 識別方式
+
+在 cx-viewer 中，MainAgent 透過 `req.mainAgent === true` 標識，由 `interceptor.js` 在請求擷取時自動標記。
+
+判定條件（滿足全部）：
+- 請求體包含 `system` 欄位（system prompt）
+- 請求體包含 `tools` 陣列（工具定義）
+- system prompt 中包含 "Codex" 特徵文字
+
+## 與 SubAgent 的區別
+
+| 特徵 | MainAgent | SubAgent |
+|------|-----------|----------|
+| system prompt | 完整的 Codex 主 prompt | 精簡的任務專用 prompt |
+| tools 陣列 | 包含全部可用工具 | 通常只包含任務所需的少量工具 |
+| 訊息歷史 | 累積完整對話上下文 | 僅包含子任務相關訊息 |
+| 快取行為 | 有 prompt caching（5 分鐘 TTL） | 通常無快取或快取較小 |

package/concepts/zh-TW/ProxySwitch.md

@@ -0,0 +1,50 @@
+# Hot-Switch Proxy
+
+## Overview
+
+Hot-Switch Proxy lets you dynamically redirect API requests to a different endpoint without restarting Codex. This is useful when using third-party API proxy services.
+
+> ⚠️ Do not use this feature if you are a Claude Max subscriber.
+
+## Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| **Name** | ✅ | Display name for this proxy, used to identify it |
+| **Base URL** | ✅ | Base URL of the API service (e.g. `https://api.example.com`). The original request origin will be replaced |
+| **API Key** | ✅ | API key for the proxy service, replaces the original authentication |
+| **Models** | ❌ | Comma-separated list of models supported by this proxy (e.g. `model-a, model-b`) |
+| **Active Model** | ❌ | Select the active model from the list. The `model` field in requests will be replaced |
+
+## How It Works
+
+When a proxy is active, `interceptor.js` performs the following before each API request:
+
+1. **URL Rewrite** — Replaces the request origin with the proxy's Base URL
+2. **Auth Replace** — Replaces `x-api-key` or `Authorization` header with the proxy's API Key
+3. **Model Replace** — If an active model is set, replaces the `model` field in the request body
+
+## Config File
+
+Configuration is stored at `~/.codex/cx-viewer/profile.json`. Click the folder icon in the title to open the directory:
+
+```json
+{
+  "active": "my-proxy",
+  "profiles": [
+    { "id": "max", "name": "Max" },
+    {
+      "id": "my-proxy",
+      "name": "My Proxy",
+      "baseURL": "https://api.example.com",
+      "apiKey": "sk-xxx",
+      "models": ["model-a", "model-b"],
+      "activeModel": "model-a"
+    }
+  ]
+}
+```
+
+- `active` — ID of the current profile. Set to `"max"` for direct connection (no proxy)
+- `profiles` — Profile list. `id: "max"` is built-in and cannot be deleted
+- Changes take effect within ~1.5 seconds (monitored via `fs.watchFile`), no restart needed

package/concepts/zh-TW/QRCode.md

@@ -0,0 +1,25 @@
+# 手機掃碼程式設計
+
+## 工作原理
+
+CX Viewer 在本機啟動 HTTP 服務後，會生成一個**區域網路位址**（如 `http://192.168.1.100:7008`）。手機掃描 QR Code 後，透過同一 WiFi 網路存取該位址，即可在手機上操作 Codex。
+
+## 為什麼掃碼後無法連線？
+
+1. **不在同一區域網路** — 手機和電腦必須連接到同一個 WiFi（同路由器/同網路名稱）
+2. **防火牆攔截** — macOS/Windows 防火牆可能阻擋了入站連線
+3. **企業/學校網路隔離** — 部分企業網路會隔離裝置間的直接通訊（AP 隔離）
+4. **VPN 干擾** — 電腦或手機開啟 VPN 可能導致網路不通
+
+## 網路安全提示
+
+> ⚠️ CX Viewer 的區域網路服務預設對同一網路內的所有裝置開放。
+
+- 在**公共 WiFi** 下使用時請注意安全
+- CX Viewer 使用 **Token 驗證**保護存取（URL 自動附帶 token）
+- 建議在可信的家庭或辦公網路中使用
+
+## 突破區域網路限制
+
+- **內網穿透工具** — 如 frp、ngrok、Tailscale 等
+- **CX Viewer 外掛** — 透過外掛機制配置中間代理，實現跨網路存取

package/concepts/zh-TW/ResponseFields.md

@@ -0,0 +1,50 @@
+# Response Body 欄位說明
+
+Claude API `/v1/messages` 回應主體的欄位說明。
+
+## 頂層欄位
+
+| 欄位 | 型別 | 說明 |
+|------|------|------|
+| **model** | string | 實際使用的模型名稱，如 `claude-opus-4-6` |
+| **id** | string | 本次回應的唯一識別碼，如 `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **type** | string | 固定為 `"message"` |
+| **role** | string | 固定為 `"assistant"` |
+| **content** | array | 模型輸出的內容區塊陣列，包含文字、工具呼叫、思考過程等 |
+| **stop_reason** | string | 停止原因：`"end_turn"`（正常結束）、`"tool_use"`（需要執行工具）、`"max_tokens"`（達到 token 上限） |
+| **stop_sequence** | string/null | 觸發停止的序列，通常為 `null` |
+| **usage** | object | Token 用量統計（詳見下方） |
+
+## content 區塊型別
+
+| 型別 | 說明 |
+|------|------|
+| **text** | 模型的文字回覆，含 `text` 欄位 |
+| **tool_use** | 工具呼叫請求，含 `name`（工具名稱）、`input`（參數）、`id`（呼叫 ID，用於匹配 tool_result） |
+| **thinking** | 擴展思考內容（僅在開啟 thinking 模式時出現），含 `thinking` 欄位 |
+
+## usage 欄位詳解
+
+| 欄位 | 說明 |
+|------|------|
+| **input_tokens** | 未命中快取的輸入 token 數（需要全價計費） |
+| **cache_creation_input_tokens** | 本次新建立快取的 token 數（快取寫入，計費高於一般輸入） |
+| **cache_read_input_tokens** | 命中快取的 token 數（快取讀取，計費遠低於一般輸入） |
+| **output_tokens** | 模型輸出的 token 數 |
+| **service_tier** | 服務等級，如 `"standard"` |
+| **inference_geo** | 推論地域，如 `"not_available"` 表示未提供地域資訊 |
+
+## cache_creation 子欄位
+
+| 欄位 | 說明 |
+|------|------|
+| **ephemeral_5m_input_tokens** | 5 分鐘 TTL 的短期快取建立 token 數 |
+| **ephemeral_1h_input_tokens** | 1 小時 TTL 的長期快取建立 token 數 |
+
+> **關於快取計費**：`cache_read_input_tokens` 的單價遠低於 `input_tokens`，而 `cache_creation_input_tokens` 的單價略高於一般輸入。因此，在持續對話中保持高快取命中率可以顯著降低費用。透過 cx-viewer 的「命中率」指標可以直觀監控這一比例。
+
+## stop_reason 含義
+
+- **end_turn**：模型正常完成回覆
+- **tool_use**：模型需要呼叫工具，content 中會包含 `tool_use` 區塊。下一輪請求需要在 messages 中追加 `tool_result` 才能繼續對話
+- **max_tokens**：達到 `max_tokens` 限制被截斷，回覆可能不完整

package/concepts/zh-TW/SubAgent-Search.md

@@ -0,0 +1,20 @@
+# SubAgent: Search
+
+## 定義
+
+Search 是由 Codex 主 agent 生成的子 agent 類型，用於執行程式碼庫搜尋。它使用 Glob、Grep 和 Read 等工具執行有針對性的檔案和內容搜尋，然後將結果返回給父 agent。
+
+## 行為
+
+- 當主 agent 需要搜尋或探索程式碼庫時自動生成
+- 在具有唯讀存取權限的隔離上下文中執行
+- 使用 Glob 進行檔案模式比對，使用 Grep 進行內容搜尋，使用 Read 進行檔案檢查
+- 將搜尋結果返回給父 agent 以供進一步處理
+
+## 出現時機
+
+Search 子 agent 通常在以下情況出現：
+
+1. 主 agent 需要尋找特定檔案、函式或程式碼模式時
+2. 使用者請求進行廣泛的程式碼庫探索時
+3. agent 正在調查依賴關係、參照或使用模式時

package/concepts/zh-TW/Teammate.md

@@ -0,0 +1,26 @@
+# Teammate
+
+## 定義
+
+Teammate 是 Codex Agent Team 模式下的協作 agent。當主 agent 透過 `TeamCreate` 建立團隊並使用 `Agent` 工具生成 teammate 時，每個 teammate 作為獨立的 agent 程序運行，擁有自己的上下文視窗和工具集，透過 `SendMessage` 與團隊成員通訊。
+
+## 與 SubAgent 的區別
+
+| 特徵 | Teammate | SubAgent |
+|------|----------|----------|
+| 生命週期 | 持續存在，可接收多次訊息 | 一次性任務，完成即銷毀 |
+| 通訊方式 | SendMessage 雙向訊息 | 父→子單向呼叫，回傳結果 |
+| 上下文 | 獨立完整上下文，跨輪次保留 | 隔離的任務上下文 |
+| 協作模式 | 團隊協作，可相互通訊 | 層級結構，只與父 agent 互動 |
+| 任務類型 | 複雜的多步驟任務 | 搜尋、探索等單一任務 |
+
+## 行為
+
+- 由主 agent（team lead）透過 `Agent` 工具建立並分配 `team_name`
+- 透過 `TaskList` / `TaskGet` / `TaskUpdate` 共享任務列表
+- 每輪執行完畢後進入 idle 狀態，等待新訊息喚醒
+- 可透過 `shutdown_request` 優雅終止
+
+## 統計面板說明
+
+Teammate 統計面板顯示每個 teammate 的 API 呼叫次數。`Name` 欄為 teammate 名稱（如 `reviewer-security`、`reviewer-pipeline`），`次數` 欄為該 teammate 產生的 API 請求總數。

package/concepts/zh-TW/Tool-Agent.md

@@ -0,0 +1,125 @@
+# Agent
+
+## 定義
+
+啟動一個子 agent（SubAgent）來自主處理複雜的多步驟任務。子 agent 是獨立的子程序，擁有各自專用的工具集和上下文。Agent 是新版 Codex 中 Task 工具的重新命名版本。
+
+## 參數
+
+| 參數 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `prompt` | string | 是 | 子 agent 要執行的任務描述 |
+| `description` | string | 是 | 3-5 個詞的簡短摘要 |
+| `subagent_type` | string | 是 | 子 agent 類型，決定可用工具集 |
+| `model` | enum | 否 | 指定模型（sonnet / opus / haiku），預設繼承父級 |
+| `max_turns` | integer | 否 | 最大 agentic 輪次數 |
+| `run_in_background` | boolean | 否 | 是否背景執行，背景任務回傳 output_file 路徑 |
+| `resume` | string | 否 | 要恢復的 agent ID，從上次執行繼續。適用於在不遺失上下文的情況下接續之前的子 agent |
+| `isolation` | enum | 否 | 隔離模式，`worktree` 建立臨時 git worktree |
+
+## 子 agent 類型
+
+| 類型 | 用途 | 可用工具 |
+|------|------|----------|
+| `Bash` | 命令執行，git 操作 | Bash |
+| `general-purpose` | 通用多步驟任務 | 全部工具 |
+| `Explore` | 快速探索程式碼庫 | 除 Agent/Edit/Write/NotebookEdit/ExitPlanMode 外的所有工具 |
+| `Plan` | 設計實施方案 | 除 Agent/Edit/Write/NotebookEdit/ExitPlanMode 外的所有工具 |
+| `claude-code-guide` | Codex 使用指南問答 | Glob, Grep, Read, WebFetch, WebSearch |
+| `statusline-setup` | 設定狀態列 | Read, Edit |
+
+## 使用場景
+
+**適合使用：**
+- 需要多步驟自主完成的複雜任務
+- 程式碼庫探索和深度研究（使用 Explore 類型）
+- 需要隔離環境的並行工作
+- 需要背景執行的長時間任務
+
+**不適合使用：**
+- 讀取特定檔案路徑——直接用 Read 或 Glob
+- 在 2-3 個已知檔案中搜尋——直接用 Read
+- 搜尋特定類別定義——直接用 Glob
+
+## 注意事項
+
+- 子 agent 完成後回傳單條訊息，其結果對使用者不可見，需要主 agent 轉述
+- 可以在單條訊息中發起多個並行 Agent 呼叫以提高效率
+- 背景任務透過 TaskOutput 工具檢查進度
+- Explore 類型比直接呼叫 Glob/Grep 慢，僅在簡單搜尋不夠時使用
+- 長時間執行且不需要立即結果的任務建議使用 `run_in_background: true`；需要結果後才能繼續時使用前台模式（預設）
+- `resume` 參數允許繼續之前啟動的子 agent 會話，保留其累積的上下文
+
+## 原文
+
+<textarea readonly>Launch a new agent to handle complex, multi-step tasks autonomously.
+
+The Agent tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+
+Available agent types and the tools they have access to:
+- general-purpose: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. (Tools: *)
+- statusline-setup: Use this agent to configure the user's Codex status line setting. (Tools: Read, Edit)
+- Explore: Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
+- Plan: Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
+- claude-code-guide: Use this agent when the user asks questions ("Can Claude...", "Does Claude...", "How do I...") about: (1) Codex (the CLI tool) - features, hooks, slash commands, MCP servers, settings, IDE integrations, keyboard shortcuts; (2) Claude Agent SDK - building custom agents; (3) Claude API (formerly Anthropic API) - API usage, tool use, Anthropic SDK usage. **IMPORTANT:** Before spawning a new agent, check if there is already a running or recently completed claude-code-guide agent that you can resume using the "resume" parameter. (Tools: Glob, Grep, Read, WebFetch, WebSearch)
+
+When using the Agent tool, you must specify a subagent_type parameter to select which agent type to use.
+
+When NOT to use the Agent tool:
+- If you want to read a specific file path, use the Read or Glob tool instead of the Agent tool, to find the match more quickly
+- If you are searching for a specific class definition like "class Foo", use the Glob tool instead, to find the match more quickly
+- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Agent tool, to find the match more quickly
+- Other tasks that are not related to the agent descriptions above
+
+Usage notes:
+- Always include a short description (3-5 words) summarizing what the agent will do
+- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+- You can optionally run agents in the background using the run_in_background parameter. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead.
+- **Foreground vs background**: Use foreground (default) when you need the agent's results before you can proceed — e.g., research agents whose findings inform your next steps. Use background when you have genuinely independent work to do in parallel.
+- Agents can be resumed using the `resume` parameter by passing the agent ID from a previous invocation. When resumed, the agent continues with its full previous context preserved. When NOT resuming, each invocation starts fresh and you should provide a detailed task description with all necessary context.
+- When the agent is done, it will return a single message back to you along with its agent ID. You can use this ID to resume the agent later if needed for follow-up work.
+- Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.
+- Agents with "access to current context" can see the full conversation history before the tool call. When using these agents, you can write concise prompts that reference earlier context (e.g., "investigate the error discussed above") instead of repeating information. The agent will receive all prior messages and understand the context.
+- The agent's outputs should generally be trusted
+- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
+- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
+- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple Agent tool use content blocks. For example, if you need to launch both a build-validator agent and a test-runner agent in parallel, send a single message with both tool calls.
+- You can optionally set `isolation: "worktree"` to run the agent in a temporary git worktree, giving it an isolated copy of the repository. The worktree is automatically cleaned up if the agent makes no changes; if changes are made, the worktree path and branch are returned in the result.
+
+Example usage:
+
+<example_agent_descriptions>
+"test-runner": use this agent after you are done writing code to run tests
+"greeting-responder": use this agent to respond to user greetings with a friendly joke
+</example_agent_descriptions>
+
+<example>
+user: "Please write a function that checks if a number is prime"
+assistant: Sure let me write a function that checks if a number is prime
+assistant: First let me use the Write tool to write a function that checks if a number is prime
+assistant: I'm going to use the Write tool to write the following code:
+<code>
+function isPrime(n) {
+  if (n <= 1) return false
+  for (let i = 2; i * i <= n; i++) {
+    if (n % i === 0) return false
+  }
+  return true
+}
+</code>
+<commentary>
+Since a significant piece of code was written and the task was completed, now use the test-runner agent to run the tests
+</commentary>
+assistant: Now let me use the test-runner agent to run the tests
+assistant: Uses the Agent tool to launch the test-runner agent
+</example>
+
+<example>
+user: "Hello"
+<commentary>
+Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
+</commentary>
+assistant: "I'm going to use the Agent tool to launch the greeting-responder agent"
+</example>
+</textarea>