cx-viewer 1.0.0

package/concepts/zh/CacheRebuild.md

@@ -0,0 +1,36 @@
+# Cache Rebuild（缓存重建）
+
+## 背景
+
+Anthropic 的 prompt caching 机制会将请求中的 system → tools → messages（到 cache breakpoint）按顺序拼接为缓存键。当缓存键与上一次请求完全一致时，API 返回 `cache_read_input_tokens`（缓存命中）；当缓存键发生变化，API 会重新创建缓存，返回大量 `cache_creation_input_tokens`，即缓存重建。
+
+缓存重建意味着额外的 token 计费（cache creation 的价格高于 cache read），因此识别重建原因对费用优化有直接价值。
+
+## 缓存重建原因分类
+
+cx-viewer 通过对比前后两个 MainAgent 请求的 body，精确判断缓存重建的原因：
+
+| reason | 含义 | 判断方式 |
+|--------|------|----------|
+| `ttl` | 缓存过期 | 距上一个 MainAgent 请求超过 5 分钟 |
+| `system_change` | system prompt 变更 | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | 工具定义变更 | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | 模型切换 | `prev.model !== curr.model` |
+| `msg_truncated` | 消息栈被截断 | 当前请求的 messages 数量少于上一个请求，通常因上下文窗口溢出触发截断 |
+| `msg_modified` | 历史消息修改 | 前缀消息内容不一致（正常追加时前缀应完全相同） |
+| `key_change` | 未知键变更 | 以上条件均不匹配时的 fallback |
+
+## 判断优先级
+
+1. 首先检查时间间隔——超过 5 分钟直接判定为 `ttl`，不再做 body 对比
+2. 然后依次检查 model、system、tools、messages
+3. 一个请求可能同时命中多个原因（如模型切换 + system prompt 变更），此时 `reasons` 数组包含所有匹配项，tooltip 换行显示
+
+## 常见场景
+
+- **`ttl`**：用户暂停操作超过 5 分钟后继续，缓存自然过期
+- **`system_change`**：Codex 更新了 system prompt（如加载新的 CLAUDE.md、project instructions 变化）
+- **`tools_change`**：MCP server 连接/断开导致可用工具列表变化
+- **`model_change`**：用户通过 `/model` 命令切换模型
+- **`msg_truncated`**：对话过长触发上下文窗口管理，Codex 截断早期消息
+- **`msg_modified`**：Codex 对历史消息做了编辑（如 `/compact` 压缩摘要替换原始消息）

package/concepts/zh/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/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/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/ProxySwitch.md

@@ -0,0 +1,50 @@
+# 代理热切换
+
+## 功能说明
+
+代理热切换允许你在不重启 Codex 的情况下，动态切换 API 请求的目标地址和认证信息。适用于使用第三方 API 代理服务的场景。
+
+> ⚠️ 如果你是 Claude 官方 Max 订阅用户，请勿使用该功能。
+
+## 字段说明
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| **名称** | ✅ | 代理的显示名称，方便区分不同代理 |
+| **地址 (Base URL)** | ✅ | API 服务的基础地址（如 `https://api.example.com`），原始请求的 origin 会被替换为此地址 |
+| **API Key** | ✅ | 代理服务的 API 密钥，会替换原始请求中的认证信息 |
+| **模型** | ❌ | 代理支持的模型列表，用逗号分隔（如 `model-a, model-b`） |
+| **当前模型** | ❌ | 从模型列表中选择当前使用的模型，请求中的 `model` 字段会被替换 |
+
+## 工作原理
+
+切换代理后，`interceptor.js` 会在每次 API 请求发出前执行以下操作：
+
+1. **URL 重写** — 将请求的 origin 替换为代理的 Base URL
+2. **认证替换** — 将请求头中的 `x-api-key` 或 `Authorization` 替换为代理的 API Key
+3. **模型替换** — 如果指定了当前模型，将请求体中的 `model` 字段替换
+
+## 配置文件
+
+配置存储在 `~/.codex/cx-viewer/profile.json`，你可以点击标题旁的文件夹图标直接打开目录编辑：
+
+```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` — 当前使用的 profile ID，设为 `"max"` 表示直连（不走代理）
+- `profiles` — profile 列表，`id: "max"` 为内置直连模式，不可删除
+- 修改文件后约 1.5 秒自动生效（通过 `fs.watchFile` 监听），无需重启

package/concepts/zh/QRCode.md

@@ -0,0 +1,29 @@
+# 手机扫码编程
+
+## 工作原理
+
+CX Viewer 在本机启动 HTTP 服务后，会生成一个**局域网地址**（如 `http://192.168.1.100:7008`）。手机扫描二维码后，通过同一 WiFi 网络访问该地址，即可在手机上操作 Codex。
+
+## 为什么扫码后无法连接？
+
+最常见的原因：
+
+1. **不在同一局域网** — 手机和电脑必须连接到同一个 WiFi 网络（同路由器/同网络名）
+2. **防火墙拦截** — macOS/Windows 防火墙可能阻止了入站连接，需要允许 CX Viewer 的端口通过
+3. **公司/学校网络隔离** — 部分企业网络会隔离设备间的直接通信（AP 隔离）
+4. **VPN 干扰** — 如果电脑或手机开启了 VPN，可能导致网络路径不通
+
+## 网络安全提示
+
+> ⚠️ CX Viewer 的局域网服务默认对同一网络内的所有设备可访问。
+
+- 在**公共 WiFi**（咖啡厅、机场等）下使用时请注意安全，同一网络的其他人理论上可以访问你的服务
+- CX Viewer 使用 **Token 验证**保护局域网访问（URL 中自动附带 token），未携带正确 token 的请求会被拒绝
+- 建议在可信的家庭或办公网络中使用
+
+## 突破局域网限制
+
+如果你需要在不同网络环境下（如外出时）远程访问电脑上的 Codex，可以通过以下方式：
+
+- **内网穿透工具** — 如 frp、ngrok、Tailscale 等，将本地服务暴露到公网
+- **CX Viewer 插件** — 支持通过插件机制配置中间代理，实现跨网络访问（详见插件文档）

package/concepts/zh/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/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/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/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>