cx-viewer 1.0.3 → 1.0.4

package/concepts/zh/TranslateContextPollution.md

@@ -1,46 +1,18 @@
-# 翻译接口 Context 污染问题
+# 辅助请求隔离
 
 ## 背景
 
-CX-Viewer 内置了翻译功能（`POST /api/translate`），通过调用 Anthropic Messages API 实现文本翻译。在早期实现中，翻译请求会复用 Codex 会话中缓存的认证凭据——包括 `x-api-key` 和 `authorization` header。这导致了一个隐蔽但严重的问题：翻译结果频繁"答非所问"。
+部分请求详情会展示 `authorization`、`x-api-key` 等敏感认证头。CX Viewer 会在这些 header 旁显示这篇说明，是为了提醒：辅助功能不能随意复用正在运行的 Codex 会话凭据。
 
-## 问题根因
+## 原则
 
-### 两种认证方式的本质区别
+内部辅助请求应当与 Codex 主对话隔离：
 
-Anthropic API 支持两种认证方式：
+1. 如果辅助功能必须调用模型服务，应使用独立 endpoint 和独立凭据。
+2. 不要把主会话的 `authorization` header 转发给无关服务。
+3. prompt、文件片段和工具上下文都应视为用户数据，启用代理 profile 后可能经过对应服务。
+4. UI 级功能能本地处理时优先本地处理。
 
-| 方式 | Header | 典型来源 | 特点 |
-|------|--------|----------|------|
-| API Key | `x-api-key: sk-ant-...` | 环境变量 / Console 生成 | 无状态，每次请求独立 |
-| OAuth Token | `authorization: Bearer sessionToken` | Codex 订阅登录 | 绑定会话，服务端维护上下文关联 |
+## 为什么重要
 
-关键差异在于：**API Key 是无状态的**，每个请求完全独立；而 **OAuth session token 是有状态的**，Anthropic 服务端会将同一 token 的请求关联到同一会话上下文中。
-
-### 污染链路
-
-当 Codex 使用订阅 OAuth 登录时，认证流程如下：
-
-```
-Codex 主对话 ──(authorization: Bearer sessionToken)──→ Anthropic API
-                                                              ↑
-CX-Viewer 翻译请求 ──(authorization: Bearer sessionToken)──→ Anthropic API
-```
-
-由于翻译请求复用了同一个 session token，Anthropic 服务端可能将翻译请求与 Codex 的主对话关联到同一上下文。这会导致：
-
-1. **翻译结果受主对话上下文影响**：翻译请求的 system prompt 是"你是一个翻译器"，但服务端上下文中还残留着 Codex 的对话历史，模型可能受到干扰
-2. **主对话受翻译请求干扰**：翻译请求的内容（用户界面文本片段）可能被注入到主对话的上下文中，导致 Codex 的回复出现偏差
-3. **不可预测的行为**：由于上下文污染是服务端行为，客户端无法感知也无法控制
-
-## 经验总结
-
-- **OAuth session token 不是"另一种 API Key"**——它携带服务端状态，复用它等于共享上下文
-- **内部服务间调用应使用独立的、无状态的认证方式**，避免与用户会话产生关联
-
-## 参考资料
-
-- [Anthropic API 认证文档](https://docs.anthropic.com/en/api/getting-started) — `x-api-key` 与 `authorization` header 的官方说明
-- [Codex 认证方式](https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code) — API Key 环境变量管理
-- [Anthropic 禁止第三方应用使用订阅 OAuth](https://winbuzzer.com/2026/02/19/anthropic-bans-claude-subscription-oauth-in-third-party-apps-xcxwbn/) — Anthropic 对 OAuth token 使用范围的限制
-- [Codex Authentication: API Keys, Subscriptions, and SSO](https://developertoolkit.ai/en/claude-code/quick-start/authentication/) — 认证方式对比
+复用会话凭据可能让无关辅助流量绑定到用户的主 agent 会话，也可能把请求上下文泄露给非预期服务。将辅助调用隔离后，代理行为更容易审计，也能避免 UI 功能与 Codex turn 之间发生意外串扰。

package/concepts/zh/UltraPlan.md

@@ -2,12 +2,12 @@
 
 ## 什么是 UltraPlan
 
-UltraPlan 是 cx-viewer 对 Codex 原生 `/ultraplan` 命令的**本地化实现**。它让你无需启动 Claude 官方的远程服务，即可在本地环境中使用 `/ultraplan` 的完整能力，引导 Codex 以**多代理协作**的方式完成复杂的规划和实现任务。
+UltraPlan 是 CX Viewer 面向 Codex 的**本地化规划工作流**。它会引导 Codex 以**多代理协作**的方式完成复杂的规划和实现任务。
 
 与普通的 Plan 模式或 Agent Team 相比，UltraPlan 能够：
 - 自动评估任务复杂度并选择最优规划策略
 - 派遣多个并行代理从不同维度探索代码库
-- 引入外部搜索（webSearch）调研业界最佳实践
+- 引入外部搜索（`web_search`）调研业界最佳实践
 - 在计划执行完成后自动组建 Code Review Team 进行代码审查
 - 形成**规划 → 执行 → 审查 → 修复**的完整闭环
 
@@ -23,12 +23,12 @@ UltraPlan 的模板和流程目前针对编程项目进行了深度优化。其
 
 ### 3. 执行时间和上下文窗口要求
 - 如果 UltraPlan 命中成功，单次执行通常需要 **30 分钟以上**
-- 需要 MainAgent 拥有更大的上下文窗口（推荐 1M context 的 Opus 模型）
-- 如果你只有 200K 的大模型，**务必在执行前先 `/clear` 上下文**
-- Codex 在窗口不足时执行 `/compact` 的效果非常差，要避免窗口爆满
+- 需要 MainAgent 拥有足够大的上下文窗口，用来容纳多代理发现和审查输出
+- 如果当前模型上下文窗口较小，**务必在执行前先 `/clear` 上下文**
+- 当上下文窗口已经接近满载时，压缩效果会变得不稳定，要避免窗口爆满
 - 保持充足的上下文空间是 UltraPlan 成功执行的关键前提
 
-如果对本地化的 UltraPlan 有任何疑问或建议，欢迎在 [GitHub](https://github.com/anthropics/claude-code/issues) 上提 Issues，一起探讨交流。
+如果对本地化的 UltraPlan 工作流有任何疑问或建议，欢迎在 CX Viewer 项目中提 Issue，一起探讨交流。
 
 ---
 
@@ -48,7 +48,7 @@ UltraPlan 提供两种运行模式：
 ### 强制模式（Forced）
 直接启用 Route C 的完整多代理流程：
 1. 派遣最多 5 个并行代理同时探索代码库（架构理解、文件定位、风险识别等）
-2. 可选派遣预研代理通过 webSearch 调研业界方案
+2. 可选派遣预研代理通过 `web_search` 调研业界方案
 3. 综合所有代理发现，生成详细的实施计划
 4. 派遣审查代理从多角度审查计划的完整性
 5. 计划获批后执行实施

package/concepts/zh-TW/BodyFields.md

@@ -1,42 +1,39 @@
-# Request Body 欄位說明
+# Request Body 字段说明
 
-Claude API `/v1/messages` 請求體的頂層欄位說明。
+CX-Viewer 归一化后的 Codex 请求体字段说明。原始来源可能是 OpenAI Responses API、Codex app-server 通知或 Codex SDK 事件，CX-Viewer 会映射为统一的 viewer 结构。
 
-## 欄位列表
+## 字段列表
 
-| 欄位 | 類型 | 說明 |
+| 字段 | 类型 | 说明 |
 |------|------|------|
-| **model** | string | 使用的模型名稱，如 `claude-opus-4-6`、`claude-sonnet-4-6` |
-| **messages** | array | 對話訊息歷史。每條訊息包含 `role`（user/assistant）和 `content`（文字、圖片、tool_use、tool_result 等 block 陣列） |
-| **system** | array | System prompt。包含 Codex 的核心指令、工具使用說明、環境資訊、CLAUDE.md 內容等。帶 `cache_control` 的區塊會被 prompt caching |
-| **tools** | array | 可用工具定義列表。每個工具包含 `name`、`description` 和 `input_schema`（JSON Schema）。MainAgent 通常有 20+ 工具，SubAgent 只有少量 |
-| **metadata** | object | 請求中繼資料，通常包含 `user_id` 用於識別使用者 |
-| **max_tokens** | number | 模型單次回覆的最大 token 數，如 `16000`、`64000` |
-| **thinking** | object | 擴展思考配置。`type: "enabled"` 開啟思考模式，`budget_tokens` 控制思考 token 上限 |
-| **context_management** | object | 上下文管理配置。`truncation: "auto"` 允許 Codex 自動截斷過長的訊息歷史 |
-| **output_config** | object | 輸出配置，如 `format` 設定 |
-| **stream** | boolean | 是否啟用串流回應。Codex 始終使用 `true` |
+| **model** | string | Codex 选择的模型名称，例如 `gpt-*` 模型 |
+| **input** | string/array | OpenAI Responses API 的输入内容。Codex 通常使用数组形式，携带用户输入、助手历史、工具结果等上下文项 |
+| **instructions** | string/array | OpenAI Responses API 的指令内容。可能包含 Codex 核心指令、工具使用说明、环境信息和 `AGENTS.md` 项目指令 |
+| **tools** | array | 可用工具定义或精简工具描述。MainAgent 通常比 SubAgent 拥有更完整的工具集合 |
+| **metadata** | object | 请求元数据，例如 `thread_id`、`turn_id`、`cwd`、SDK/app-server 来源，以及 subAgent 的父线程信息 |
+| **max_tokens** | number | 模型单次回复的最大 token 数，如 `16000`、`64000` |
+| **reasoning_effort** | string | Codex 上报的推理强度 |
+| **reasoning_summary** | string | Codex 上报的推理摘要模式 |
+| **approval_policy** | string | 本轮 Codex 审批策略 |
+| **sandbox_policy** | object/string | 本轮沙箱策略（如果来源协议提供） |
+| **stream** | boolean | OpenAI Responses API 请求是否流式；app-server/SDK 条目会按流式 turn 归一化 |
 
-## messages 結構
+## input 结构
 
-每條訊息的 `content` 是一個 block 陣列，常見類型：
+`input` 为数组时，每个输入项通常包含 `role` 和 `content`。`content` 可以是 block 数组，常见类型：
 
-- **text**: 普通文字內容
-- **tool_use**: 模型呼叫工具（含 `name`、`input`）
-- **tool_result**: 工具執行結果（含 `tool_use_id`、`content`）
-- **image**: 圖片內容（base64 或 URL）
-- **thinking**: 模型的思考過程（擴展思考模式）
+- **text**: 普通文本内容
+- **tool_use**: 模型调用工具（含 `name`、`input`）
+- **tool_result**: 工具执行结果（含 `tool_use_id`、`content`）
+- **image/input_image/local_image**: 图片内容或本地图片引用
+- **thinking**: 模型的思考过程（扩展思考模式）
 
-## system 結構
+## instructions 结构
 
-system prompt 陣列中通常包含：
+`instructions` 通常包含：
 
 1. **核心 agent 指令**（"You are Codex..."）
-2. **工具使用規範**
-3. **CLAUDE.md 內容**（專案級指令）
+2. **工具使用规范**
+3. **AGENTS.md 内容**（项目级指令）
 4. **技能提示**（skills reminder）
-5. **環境資訊**（OS、shell、git 狀態等）— 事實上 Codex 非常依賴 git。如果專案存在 git 儲存庫，Codex 能展現出對專案更好的理解能力，包括可以拉取遠端的變更和 commit 記錄來輔助分析
-
-帶 `cache_control: { type: "ephemeral" }` 標記的區塊會被 Anthropic API 快取 5 分鐘，命中快取時以 `cache_read_input_tokens` 計費（遠低於 `input_tokens`）。
-
-> **注意**：對於 Codex 這類特殊用戶端，Anthropic 伺服端實際上並不完全依賴請求中的 `cache_control` 屬性來決定快取行為。伺服端會對特定欄位（如 system prompt、tools 定義）自動執行快取策略，即使請求中未顯式攜帶 `cache_control` 標記。因此，當你在請求體中沒有看到該屬性時不必疑惑——伺服端已在幕後完成了快取操作，只是未將此資訊暴露給用戶端。這是 Codex 與 Anthropic API 之間的一種默契。
+5. **环境信息**（OS、shell、git 状态等）— 事实上 Codex 非常依赖 git。如果项目存在 git 仓库，Codex 能展现出对项目更好的理解能力，包括可以拉取远端的变更和 commit 记录来辅助分析

package/concepts/zh-TW/GlobalSettings.md

@@ -17,7 +17,7 @@
 | 配置项 | 类型 | 默认值 | 说明 |
 |--------|------|--------|------|
 | 折叠工具结果 | 开关 | 开 | 聊天视图中折叠工具调用结果块 |
-| 展开思考过程 | 开关 | 开 | 默认展开 Claude 的思考/推理过程块 |
+| 展开思考过程 | 开关 | 开 | 默认展开 Codex 的 reasoning/thinking 块 |
 | 完整展示所有内容 | 开关 | 关 | 显示完整的工具调用内容，不截断 |
 | 自动恢复会话 | 开关 + 选项 | 关 | 遇到会话恢复提示时自动选择：`继续` 或 `新建` |
 
@@ -75,20 +75,20 @@
 | 变量名 | 说明 |
 |--------|------|
 | `CXVIEWER_PORT` | 服务端口，供 ask-bridge/perm-bridge 通信 |
-| `CXV_EDITOR_PORT` | 服务端口，供 ccv-editor 文件编辑桥接 |
+| `CXV_EDITOR_PORT` | 服务端口，供 cxv-editor 文件编辑桥接 |
 
 ### 外部变量（读取）
 
 | 变量名 | 说明 |
 |--------|------|
-| `OPENAI_BASE_URL` | 自定义 Anthropic API 地址 |
+| `OPENAI_BASE_URL` | 自定义 OpenAI 兼容 API 地址 |
 | `SHELL` | 用户 Shell（PTY 启动和 Shell 配置检测） |
 | `http_proxy` / `HTTPS_PROXY` 等 | HTTP 代理配置（通过 undici EnvHttpProxyAgent） |
 
 ## 五、CLI 命令参数
 
 ```
-ccv [选项] [claude 参数...]
+cxv [选项] [codex 参数...]
 ```
 
 ### CX-Viewer 专有选项
@@ -100,49 +100,50 @@ ccv [选项] [claude 参数...]
 | `--help` / `-h` / `help` | 显示帮助信息 |
 | `--version` / `-v` | 显示版本号 |
 | `-SDK` / `--sdk` | 使用 Agent SDK 模式 |
-| `--d` | `--dangerously-skip-permissions` 简写 |
-| `--ad` | `--allow-dangerously-skip-permissions` 简写 |
-| `run` | 通过代理运行命令（`ccv run -- claude ...`） |
+| `--d` | `--dangerously-bypass-approvals-and-sandbox` 简写 |
+| `--ad` | 兼容旧配置的 CXV 侧 bypass 开关 |
+| `run` | 通过 CXV 包装运行命令（`cxv run -- codex ...`） |
 
-### Claude 透传参数（常用）
+### Codex 透传参数（常用）
 
 | 参数 | 说明 |
 |------|------|
-| `-c` / `--continue` | 继续上一次会话 |
-| `-r` / `--resume` | 恢复指定会话 |
-| `-p` / `--print` | 非交互式输出 |
+| `continue` | 恢复上一次会话（`codex resume --last`） |
+| `resume [session-id]` | 恢复指定会话 |
+| `exec [prompt]` | 非交互式 Codex 执行 |
 | `--model` | 指定模型 |
-| `--permission-mode` | 权限模式 |
-| `--system-prompt` | 自定义系统提示词 |
-| `--max-budget-usd` | 最大预算 |
+| `--search` | 启用实时搜索模式 |
+| `-C` / `--cd` | 指定工作目录 |
+| `--sandbox` | 指定沙箱模式 |
+| `--ask-for-approval` | 指定审批策略 |
 
 ## 六、Hook 配置
 
-CX-Viewer 自动注册到 `~/.claude/settings.json` 的 `hooks.PreToolUse` 中：
+CX-Viewer 的 Codex 集成主要走本地 wrapper/proxy 路径。Hook bridge 只使用当前 Codex 工具名。
 
-### 1. AskUserQuestion 桥接
-- **匹配器**: `"AskUserQuestion"`
+### 1. request_user_input 桥接
+- **匹配器**: `"request_user_input"`
 - **命令**: `node <安装目录>/lib/ask-bridge.js`
-- **作用**: 将 Claude 的问题转发到 Web UI，等待用户回答
+- **作用**: 在 bridge 路径启用时，将工具/用户审批转发到 Web UI
 
 ### 2. 权限审批桥接
 - **匹配器**: `""` (空 = 匹配所有工具)
 - **命令**: `node <安装目录>/lib/perm-bridge.js`
-- **作用**: 仅 `Bash`/`Edit`/`Write`/`NotebookEdit` 需要 Web UI 审批，其余自动放行
+- **作用**: `shell_command`、`apply_patch`、`web_search`、`image_generation` 等会变更文件或访问外部资源的工具需要 Web UI 审批，其余自动放行
 
 ## 七、Shell 集成
 
-CX-Viewer 在 `~/.zshrc`（或 `.bashrc`）中注入 `claude()` 函数：
+CX-Viewer 在 logger 模式下可向 `~/.zshrc`（或 `.bashrc`）注入 `codex()` 包装函数：
 
 ```bash
 # >>> CX-Viewer Auto-Inject >>>
-claude() { ... }
+codex() { ... }
 # <<< CX-Viewer Auto-Inject <<<
 ```
 
-所有 `claude` 命令自动通过 CX-Viewer 代理，实现日志捕获和 Web UI 功能。
+交互式 `codex` 命令会通过 CX-Viewer 实现日志捕获和 Web UI 功能；`codex --help`、`codex auth` 等 passthrough 命令仍直接执行。
 
-卸载：`ccv --uninstall` 或手动删除标记之间的内容。
+卸载：`cxv --uninstall` 或手动删除标记之间的内容。
 
 ## 八、代理配置（Proxy Profile）
 
@@ -224,9 +225,6 @@ claude() { ... }
 
 | 键 | 说明 |
 |-----|------|
-| `cxv_cacheExpireAt` | 缓存倒计时到期时间 |
-| `cxv_cacheType` | 缓存类型标签 |
-| `ccv_sseSlim` | 启用 SSE 增量裁剪（桌面端性能优化） |
-| `ccv_calibrationModel` | KV-Cache 上下文窗口校准模型 |
-| `ccv_fileExplorerOpen` | 文件浏览器面板开关 |
+| `cxv_viewMode` | 当前响应式视图模式覆盖 |
+| `cxv_fileExplorerOpen` | 文件浏览器面板开关 |
 | `cx-viewer-terminal-width` | 终端面板宽度（像素） |

package/concepts/zh-TW/MainAgent.md

@@ -20,4 +20,3 @@ MainAgent 是 Codex 在非 agent team 狀態下的主幹請求鏈路。每一次
 | system prompt | 完整的 Codex 主 prompt | 精簡的任務專用 prompt |
 | tools 陣列 | 包含全部可用工具 | 通常只包含任務所需的少量工具 |
 | 訊息歷史 | 累積完整對話上下文 | 僅包含子任務相關訊息 |
-| 快取行為 | 有 prompt caching（5 分鐘 TTL） | 通常無快取或快取較小 |

package/concepts/zh-TW/ProxySwitch.md

@@ -1,32 +1,32 @@
-# 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.
+代理热切换允许你在不重启 Codex 的情况下，动态切换 API 请求的目标地址和认证信息。适用于使用第三方 API 代理服务的场景。
 
-> ⚠️ Do not use this feature if you are a Claude Max subscriber.
+> 仅在你有权使用的 endpoint 和 API Key 上开启该功能。启用 profile 后，请求认证会被替换，prompt、文件片段和工具上下文可能会经过配置的服务。
 
-## 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 |
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| **名称** | ✅ | 代理的显示名称，方便区分不同代理 |
+| **地址 (Base URL)** | ✅ | API 服务的基础地址（如 `https://api.example.com`），原始请求的 origin 会被替换为此地址 |
+| **API Key** | ✅ | 代理服务的 API 密钥，会替换原始请求中的认证信息 |
+| **模型** | ❌ | 代理支持的模型列表，用逗号分隔（如 `model-a, model-b`） |
+| **当前模型** | ❌ | 从模型列表中选择当前使用的模型，请求中的 `model` 字段会被替换 |
 
-## How It Works
+## 工作原理
 
-When a proxy is active, `interceptor.js` performs the following before each API request:
+切换代理后，`interceptor.js` 会在每次 API 请求发出前执行以下操作：
 
-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
+1. **URL 重写** — 将请求的 origin 替换为代理的 Base URL
+2. **认证替换** — 将请求头中的 `x-api-key` 或 `Authorization` 替换为代理的 API Key
+3. **模型替换** — 如果指定了当前模型，将请求体中的 `model` 字段替换
 
-## Config File
+## 配置文件
 
-Configuration is stored at `~/.codex/cx-viewer/profile.json`. Click the folder icon in the title to open the directory:
+配置存储在 `~/.codex/cx-viewer/profile.json`，你可以点击标题旁的文件夹图标直接打开目录编辑：
 
 ```json
 {
@@ -45,6 +45,6 @@ Configuration is stored at `~/.codex/cx-viewer/profile.json`. Click the folder i
 }
 ```
 
-- `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
+- `active` — 当前使用的 profile ID，设为 `"max"` 表示直连（不走代理）
+- `profiles` — profile 列表，`id: "max"` 为内置直连模式，不可删除
+- 修改文件后约 1.5 秒自动生效（通过 `fs.watchFile` 监听），无需重启

package/concepts/zh-TW/ResponseFields.md

@@ -1,50 +1,39 @@
-# Response Body 欄位說明
+# Response Body 字段说明
 
-Claude API `/v1/messages` 回應主體的欄位說明。
+CX-Viewer 归一化后的 Codex 响应体字段说明。
 
-## 頂層欄位
+## 顶层字段
 
-| 欄位 | 型別 | 說明 |
+| 字段 | 类型 | 说明 |
 |------|------|------|
-| **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 區塊型別
-
-| 型別 | 說明 |
+| **model** | string | 实际使用的模型名称 |
+| **id** | string | 响应或流式 item 的唯一标识符（如果来源协议提供） |
+| **type** | string | 固定为 `"message"` |
+| **role** | string | 固定为 `"assistant"` |
+| **content** | array | 模型输出的内容块数组，包含文本、工具调用、思考过程等 |
+| **stop_reason** | string | 归一化后的停止原因/状态，例如 `"end_turn"`、`"completed"`、`"failed"`、`"max_tokens"` |
+| **stop_sequence** | string/null | 触发停止的序列，通常为 `null` |
+| **usage** | object | Token 用量统计（详见下方） |
+
+## content 块类型
+
+| 类型 | 说明 |
 |------|------|
-| **text** | 模型的文字回覆，含 `text` 欄位 |
-| **tool_use** | 工具呼叫請求，含 `name`（工具名稱）、`input`（參數）、`id`（呼叫 ID，用於匹配 tool_result） |
-| **thinking** | 擴展思考內容（僅在開啟 thinking 模式時出現），含 `thinking` 欄位 |
+| **text** | 模型的文本回复，含 `text` 字段 |
+| **tool_use** | 工具调用请求，含 `name`（工具名）、`input`（参数）、`id`（调用 ID，用于匹配 tool_result） |
+| **thinking** | 扩展思考内容（仅在开启 thinking 模式时出现），含 `thinking` 字段 |
 
-## usage 欄位詳解
+## usage 字段详解
 
-| 欄位 | 說明 |
+| 字段 | 说明 |
 |------|------|
-| **input_tokens** | 未命中快取的輸入 token 數（需要全價計費） |
-| **cache_creation_input_tokens** | 本次新建立快取的 token 數（快取寫入，計費高於一般輸入） |
-| **cache_read_input_tokens** | 命中快取的 token 數（快取讀取，計費遠低於一般輸入） |
-| **output_tokens** | 模型輸出的 token 數 |
-| **service_tier** | 服務等級，如 `"standard"` |
-| **inference_geo** | 推論地域，如 `"not_available"` 表示未提供地域資訊 |
+| **input_tokens** | 未命中缓存的输入 token 数（需要全价计费） |
+| **output_tokens** | 模型输出的 token 数 |
+| **reasoning_output_tokens** | 来源协议上报的推理 token 数 |
+| **total_tokens** | 来源协议上报的总 token 数 |
 
-## cache_creation 子欄位
+## stop_reason 含义
 
-| 欄位 | 說明 |
-|------|------|
-| **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` 限制被截斷，回覆可能不完整
+- **end_turn**：模型正常完成回复
+- **tool_use**：模型需要调用工具；当来源协议提供结果时，CX-Viewer 会展示匹配的工具返回
+- **max_tokens**：达到 `max_tokens` 限制被截断，回复可能不完整

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

@@ -1,20 +1,20 @@
 # SubAgent: Search
 
-## 定義
+## 定义
 
-Search 是由 Codex 主 agent 生成的子 agent 類型，用於執行程式碼庫搜尋。它使用 Glob、Grep 和 Read 等工具執行有針對性的檔案和內容搜尋，然後將結果返回給父 agent。
+Search 是由 Codex 主 agent 生成的子 agent 类型，用于执行代码库搜索。它通过 `tool_search` 发现当前可用的搜索和读取能力，然后将结果返回给父 agent。
 
-## 行為
+## 行为
 
-- 當主 agent 需要搜尋或探索程式碼庫時自動生成
-- 在具有唯讀存取權限的隔離上下文中執行
-- 使用 Glob 進行檔案模式比對，使用 Grep 進行內容搜尋，使用 Read 進行檔案檢查
-- 將搜尋結果返回給父 agent 以供進一步處理
+- 当主 agent 需要搜索或探索代码库时自动生成
+- 在具有只读访问权限的隔离上下文中运行
+- 使用当前 Codex/deferred 工具进行文件模式匹配、内容搜索和文件检查
+- 将搜索结果返回给父 agent 以供进一步处理
 
-## 出現時機
+## 出现时机
 
-Search 子 agent 通常在以下情況出現：
+Search 子 agent 通常在以下情况出现：
 
-1. 主 agent 需要尋找特定檔案、函式或程式碼模式時
-2. 使用者請求進行廣泛的程式碼庫探索時
-3. agent 正在調查依賴關係、參照或使用模式時
+1. 主 agent 需要查找特定文件、函数或代码模式时
+2. 用户请求进行广泛的代码库探索时
+3. agent 正在调查依赖关系、引用或使用模式时

package/concepts/zh-TW/Teammate.md

@@ -1,26 +1,26 @@
 # Teammate
 
-## 定義
+## 定义
 
-Teammate 是 Codex Agent Team 模式下的協作 agent。當主 agent 透過 `TeamCreate` 建立團隊並使用 `Agent` 工具生成 teammate 時，每個 teammate 作為獨立的 agent 程序運行，擁有自己的上下文視窗和工具集，透過 `SendMessage` 與團隊成員通訊。
+Teammate 是 Codex Agent Team 模式下的协作 agent。主 agent 会通过 `tool_search` 发现当前可用的 multi-agent 工具；当这些工具可用时，每个 teammate 作为独立的 agent 进程运行，拥有自己的上下文窗口和工具集。
 
-## 與 SubAgent 的區別
+## 与 SubAgent 的区别
 
-| 特徵 | Teammate | SubAgent |
+| 特征 | Teammate | SubAgent |
 |------|----------|----------|
-| 生命週期 | 持續存在，可接收多次訊息 | 一次性任務，完成即銷毀 |
-| 通訊方式 | SendMessage 雙向訊息 | 父→子單向呼叫，回傳結果 |
-| 上下文 | 獨立完整上下文，跨輪次保留 | 隔離的任務上下文 |
-| 協作模式 | 團隊協作，可相互通訊 | 層級結構，只與父 agent 互動 |
-| 任務類型 | 複雜的多步驟任務 | 搜尋、探索等單一任務 |
+| 生命周期 | 持续存在，可接收多次消息 | 一次性任务，完成即销毁 |
+| 通信方式 | 通过可用 multi-agent 工具集进行团队通信 | 父→子单向调用，返回结果 |
+| 上下文 | 独立完整上下文，跨轮次保留 | 隔离的任务上下文 |
+| 协作模式 | 团队协作，可相互通信 | 层级结构，只与父 agent 交互 |
+| 任务类型 | 复杂的多步骤任务 | 搜索、探索等单一任务 |
 
-## 行為
+## 行为
 
-- 由主 agent（team lead）透過 `Agent` 工具建立並分配 `team_name`
-- 透過 `TaskList` / `TaskGet` / `TaskUpdate` 共享任務列表
-- 每輪執行完畢後進入 idle 狀態，等待新訊息喚醒
-- 可透過 `shutdown_request` 優雅終止
+- 由主 agent（team lead）通过可用 multi-agent 工具创建并分配团队身份
+- 通过可用 multi-agent 任务/状态工具共享任务状态
+- 每轮执行完毕后进入 idle 状态，等待新消息唤醒
+- 可通过 `shutdown_request` 优雅终止
 
-## 統計面板說明
+## 统计面板说明
 
-Teammate 統計面板顯示每個 teammate 的 API 呼叫次數。`Name` 欄為 teammate 名稱（如 `reviewer-security`、`reviewer-pipeline`），`次數` 欄為該 teammate 產生的 API 請求總數。
+Teammate 统计面板显示每个 teammate 的 API 调用次数。`Name` 列为 teammate 名称（如 `reviewer-security`、`reviewer-pipeline`），`次数` 列为该 teammate 产生的 API 请求总数。