cx-viewer 1.0.2 → 1.0.4

package/concepts/zh/ProxySwitch.md

@@ -4,7 +4,7 @@
 
 代理热切换允许你在不重启 Codex 的情况下，动态切换 API 请求的目标地址和认证信息。适用于使用第三方 API 代理服务的场景。
 
-> ⚠️ 如果你是 Claude 官方 Max 订阅用户，请勿使用该功能。
+> 仅在你有权使用的 endpoint 和 API Key 上开启该功能。启用 profile 后，请求认证会被替换，prompt、文件片段和工具上下文可能会经过配置的服务。
 
 ## 字段说明
 

package/concepts/zh/ResponseFields.md

@@ -1,17 +1,17 @@
 # Response Body 字段说明
 
-Claude API `/v1/messages` 响应体的字段说明。
+CX-Viewer 归一化后的 Codex 响应体字段说明。
 
 ## 顶层字段
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| **model** | string | 实际使用的模型名称，如 `claude-opus-4-6` |
-| **id** | string | 本次响应的唯一标识符，如 `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **model** | string | 实际使用的模型名称 |
+| **id** | string | 响应或流式 item 的唯一标识符（如果来源协议提供） |
 | **type** | string | 固定为 `"message"` |
 | **role** | string | 固定为 `"assistant"` |
 | **content** | array | 模型输出的内容块数组，包含文本、工具调用、思考过程等 |
-| **stop_reason** | string | 停止原因：`"end_turn"`（正常结束）、`"tool_use"`（需要执行工具）、`"max_tokens"`（达到 token 上限） |
+| **stop_reason** | string | 归一化后的停止原因/状态，例如 `"end_turn"`、`"completed"`、`"failed"`、`"max_tokens"` |
 | **stop_sequence** | string/null | 触发停止的序列，通常为 `null` |
 | **usage** | object | Token 用量统计（详见下方） |
 
@@ -28,23 +28,12 @@ Claude API `/v1/messages` 响应体的字段说明。
 | 字段 | 说明 |
 |------|------|
 | **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 的"命中率"指标可以直观监控这一比例。
+| **reasoning_output_tokens** | 来源协议上报的推理 token 数 |
+| **total_tokens** | 来源协议上报的总 token 数 |
 
 ## stop_reason 含义
 
 - **end_turn**：模型正常完成回复
-- **tool_use**：模型需要调用工具，content 中会包含 `tool_use` 块。下一轮请求需要在 messages 中追加 `tool_result` 才能继续对话
+- **tool_use**：模型需要调用工具；当来源协议提供结果时，CX-Viewer 会展示匹配的工具返回
 - **max_tokens**：达到 `max_tokens` 限制被截断，回复可能不完整

package/concepts/zh/SubAgent-Search.md

@@ -2,13 +2,13 @@
 
 ## 定义
 
-Search 是由 Codex 主 agent 生成的子 agent 类型，用于执行代码库搜索。它使用 Glob、Grep 和 Read 等工具执行有针对性的文件和内容搜索，然后将结果返回给父 agent。
+Search 是由 Codex 主 agent 生成的子 agent 类型，用于执行代码库搜索。它通过 `tool_search` 发现当前可用的搜索和读取能力，然后将结果返回给父 agent。
 
 ## 行为
 
 - 当主 agent 需要搜索或探索代码库时自动生成
 - 在具有只读访问权限的隔离上下文中运行
-- 使用 Glob 进行文件模式匹配，使用 Grep 进行内容搜索，使用 Read 进行文件检查
+- 使用当前 Codex/deferred 工具进行文件模式匹配、内容搜索和文件检查
 - 将搜索结果返回给父 agent 以供进一步处理
 
 ## 出现时机

package/concepts/zh/Teammate.md

@@ -2,22 +2,22 @@
 
 ## 定义
 
-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 的区别
 
 | 特征 | Teammate | SubAgent |
 |------|----------|----------|
 | 生命周期 | 持续存在，可接收多次消息 | 一次性任务，完成即销毁 |
-| 通信方式 | SendMessage 双向消息 | 父→子单向调用，返回结果 |
+| 通信方式 | 通过可用 multi-agent 工具集进行团队通信 | 父→子单向调用，返回结果 |
 | 上下文 | 独立完整上下文，跨轮次保留 | 隔离的任务上下文 |
 | 协作模式 | 团队协作，可相互通信 | 层级结构，只与父 agent 交互 |
 | 任务类型 | 复杂的多步骤任务 | 搜索、探索等单一任务 |
 
 ## 行为
 
-- 由主 agent（team lead）通过 `Agent` 工具创建并分配 `team_name`
-- 通过 `TaskList` / `TaskGet` / `TaskUpdate` 共享任务列表
+- 由主 agent（team lead）通过可用 multi-agent 工具创建并分配团队身份
+- 通过可用 multi-agent 任务/状态工具共享任务状态
 - 每轮执行完毕后进入 idle 状态，等待新消息唤醒
 - 可通过 `shutdown_request` 优雅终止
 

package/concepts/zh/Tool-apply_patch.md

@@ -0,0 +1,11 @@
+# apply_patch
+
+`apply_patch` 是 Codex 修改文件的结构化 patch 工具。它接收 freeform patch，而不是 JSON。
+
+适用场景：
+
+- 新增、删除或更新仓库文件。
+- 保持变更可审阅，避免用 shell 重定向直接写文件。
+- 精确表达局部修改。
+
+旧日志中的 `FileChange` 或 `fileChange` 是文件变更事件名，会兼容跳转到本工具。

package/concepts/zh/Tool-create_goal.md

@@ -0,0 +1,8 @@
+# create_goal
+
+`create_goal` 只在用户或系统明确要求创建 goal 时使用。它会启动一个新的活跃目标；如果已有未完成目标，调用会失败。
+
+字段：
+
+- `objective`：具体目标，必填。
+- `token_budget`：可选；只有用户明确要求 token 预算时才设置。

package/concepts/zh/Tool-exec.md

@@ -0,0 +1,88 @@
+# exec
+
+`exec` 是 Code Mode 的核心工具编排套件。它在全新的 V8 isolate 中运行一个异步 JavaScript module，并把当前轮次已装载的工具转换为可调用的 JavaScript 方法。因此它不只是“执行 JavaScript”，而是 shell、文件、计划、goal、MCP、网络、图片、插件及其他动态能力的统一组合层。
+
+## 套件提供的能力
+
+- **统一的 JavaScript 调用面。** 所有已启用的嵌套工具都挂载在全局 `tools` 对象上。
+- **串行组合。** 可以检查前一个工具的结果，并在同一脚本中把它传给下一个工具。
+- **并行编排。** 相互独立的调用可以通过 `Promise.all` 并行执行，减少往返等待。
+- **动态发现。** `ALL_TOOLS` 提供已启用工具的元数据，也包含未写入生成式参考文本的 deferred tools。
+- **类型提示。** 运行时会根据嵌套工具的输入、输出 schema 生成类似 TypeScript 的声明。
+- **增量和多模态输出。** 脚本可以输出文本、普通图片、生成图片以及即时进度通知。
+- **跨调用状态。** 可序列化数据可以保存，并由同一会话后续的 `exec` 调用读取。
+- **长任务 cell。** 超过初始 yield 窗口的任务会返回 cell id，并通过 `wait` 继续运行。
+
+嵌套工具仍保留各自的 schema、沙箱边界和审批要求。通过 `exec` 调用不会绕过原有权限策略。
+
+## 调用嵌套工具
+
+工具名会被规范化为合法 JavaScript 标识符。普通工具 `shell_command` 通过 `tools.shell_command(...)` 调用；带 namespace 的 `web.run` 则会暴露为类似 `tools.web__run(...)` 的名称。
+
+- Function tool 接收对象参数。
+- `apply_patch` 这类 freeform tool 接收字符串参数。
+- 嵌套调用根据各自契约返回对象或字符串。
+- deferred tool 即使没有出现在生成的参考正文中，也可以按 `name` 或 `description` 筛选 `ALL_TOOLS` 来发现。
+
+串行组合：
+
+```js
+const goal = await tools.get_goal({});
+text(goal);
+```
+
+并行组合：
+
+```js
+const [status, resources] = await Promise.all([
+  tools.shell_command({ command: "git status --short", workdir: "/workspace" }),
+  tools.list_mcp_resources({}),
+]);
+text(status);
+text(resources);
+```
+
+## 运行时 helper
+
+| Helper | 作用 |
+| --- | --- |
+| `text(value)` | 追加文本输出；对象需要时应显式序列化。 |
+| `image(value, detail?)` | 转发 base64 data URL、图片项或 MCP 图片内容块。 |
+| `generatedImage(result)` | 转发图片生成结果及可选的输出提示。 |
+| `notify(value)` | 在脚本继续运行的同时立刻发出一条附加输出。 |
+| `store(key, value)` | 保存可序列化数据，供本会话后续 `exec` 调用使用。 |
+| `load(key)` | 读取此前通过 `store` 保存的数据。 |
+| `exit()` | 在当前位置正常结束脚本。 |
+| `setTimeout` / `clearTimeout` | 在 isolate 内安排或取消回调。 |
+| `yield_control()` | 立即交出已累积的输出，同时保持脚本继续运行。 |
+| `ALL_TOOLS` | 查看已启用嵌套工具的 `{ name, description }` 元数据。 |
+
+仅存在待触发 timer 不会让 isolate 保持运行；需要完成延迟工作时，必须等待一个明确的 Promise。
+
+## 输入格式与执行生命周期
+
+输入必须是原始 JavaScript source，不能是 JSON、带引号字符串或 Markdown 代码块。脚本按异步 module 执行，因此可以直接使用顶层 `await`。
+
+首行可以使用可选 pragma，控制首次 yield 时间和直接输出预算：
+
+```js
+// @exec: {"yield_time_ms": 10000, "max_output_tokens": 2000}
+const result = await tools.shell_command({
+  command: "npm test",
+  workdir: "/workspace",
+  timeout_ms: 120000,
+});
+text(result);
+```
+
+- `yield_time_ms` 默认 10,000 毫秒。
+- `max_output_tokens` 默认 10,000 tokens。
+- 到达 yield 边界时任务仍在运行，`exec` 会返回 `Script running with cell ID ...`。
+- 将这个 id 传给 `wait`，可以反复等待直至完成；也可以用 `terminate: true` 终止。
+- JavaScript 执行完成后 isolate 会被销毁，未被 await 的 Promise 会被丢弃。只有通过 `store` 显式保存的数据可以跨调用保留。
+
+## 环境边界
+
+isolate 刻意不直接提供 Node.js API、文件系统、网络和 `console`。这些能力必须通过嵌套工具获得，结果则通过显式输出 helper 返回。HTTP 图片 URL 也不能直接传给 `generatedImage`，图片输出必须符合对应的 data/result 契约。
+
+这种设计让一次 `exec` 调用可以成为一个小型、遵守权限策略的 workflow：发现能力、调用多个工具、根据结果分支、保存状态，并只输出最终有用的组合结果。

package/concepts/zh/Tool-followup_task.md

@@ -0,0 +1,10 @@
+# followup_task
+
+`followup_task` 给现有的非根 Agent 分配后续任务，并在目标空闲时启动一轮。如果目标正在运行，任务会在安全的消息边界或当前工具调用结束后送达。
+
+字段：
+
+- `target`：Agent id 或规范任务名，必填。
+- `message`：后续任务说明，必填。
+
+它适合复用已有上下文与下一任务密切相关的 Agent。

package/concepts/zh/Tool-get_goal.md

@@ -0,0 +1,5 @@
+# get_goal
+
+`get_goal` 用来读取当前线程的 goal 状态，包括目标、状态、预算、token 用量、已耗时和剩余额度。
+
+它是只读工具，不创建或改变目标。

package/concepts/zh/Tool-image_generation.md

@@ -0,0 +1,5 @@
+# image_generation
+
+`image_generation` 用于生成 PNG 图片。它是当前请求体中装载的图片生成能力，不是旧的文件读写工具。
+
+适用场景包括生成位图视觉资产、插图、纹理、精灵、mockup 或透明背景素材。

package/concepts/zh/Tool-interrupt_agent.md

@@ -0,0 +1,9 @@
+# interrupt_agent
+
+`interrupt_agent` 会停止目标 Agent 当前正在运行的轮次，并返回此前状态。目标不会被删除，之后仍可接收消息或后续任务。
+
+字段：
+
+- `target`：Agent id 或规范任务名，必填。
+
+本工具用于终止或改向已经过时的工作，不应代替普通消息沟通。

package/concepts/zh/Tool-list_agents.md

@@ -0,0 +1,9 @@
+# list_agents
+
+`list_agents` 读取当前根线程中的活跃 Agent 树，并报告各任务的状态。
+
+字段：
+
+- `path_prefix`：可选的规范任务路径前缀，用来缩小结果范围；省略时列出全部活跃 Agent。
+
+这是只读检查工具，不会启动、中断或关闭任何 Agent。

package/concepts/zh/Tool-list_mcp_resource_templates.md

@@ -0,0 +1,8 @@
+# list_mcp_resource_templates
+
+`list_mcp_resource_templates` 用来列出 MCP server 暴露的参数化资源模板。模板适合按参数读取动态上下文，例如某个文件、记录或业务对象。
+
+字段：
+
+- `server`：可选，限定某个 MCP server。
+- `cursor`：可选，用于分页继续读取。

package/concepts/zh/Tool-list_mcp_resources.md

@@ -0,0 +1,8 @@
+# list_mcp_resources
+
+`list_mcp_resources` 用来列出 MCP server 提供的资源。资源可以是文件、数据库 schema 或应用上下文等，适合在可用时优先于网络搜索使用。
+
+字段：
+
+- `server`：可选，限定某个 MCP server。
+- `cursor`：可选，用于分页继续读取。

package/concepts/zh/Tool-read_mcp_resource.md

@@ -0,0 +1,10 @@
+# read_mcp_resource
+
+`read_mcp_resource` 用来读取指定 MCP server 上的具体资源。
+
+字段：
+
+- `server`：MCP server 名称，必填。
+- `uri`：资源 URI，必填，通常来自 `list_mcp_resources` 的返回值。
+
+旧日志中的通用 `MCPToolCall` 或 `mcpToolCall` 不是当前装载工具名；相关入口会兼容跳转到本工具。

package/concepts/zh/Tool-request_user_input.md

@@ -0,0 +1,9 @@
+# request_user_input
+
+`request_user_input` 用来在 Plan mode 下向用户提出 1 到 3 个结构化短问题。只有当用户输入确实能解除阻塞或明显提升计划质量时才应使用。
+
+字段要点：
+
+- `questions`：问题数组，必填。
+- 每个问题包含 `id`、`header`、`question` 和 `options`。
+- `autoResolutionMs`：可选，表示非阻塞问题的自动继续窗口。

package/concepts/zh/Tool-send_message.md

@@ -0,0 +1,10 @@
+# send_message
+
+`send_message` 向现有 Agent 的队列投递消息并尽快送达，但不会启动一个新轮次。
+
+字段：
+
+- `target`：`spawn_agent` 返回的相对或规范任务名，必填。
+- `message`：要投递的上下文、证据或指导，必填。
+
+如果需要让空闲目标主动开始另一个任务，应改用 `followup_task`。

package/concepts/zh/Tool-shell_command.md

@@ -0,0 +1,12 @@
+# shell_command
+
+`shell_command` 用来在用户的 shell 中运行命令。调用时必须设置 `workdir`，避免依赖隐式当前目录。
+
+常用字段：
+
+- `command`：要执行的命令，必填。
+- `workdir`：命令运行目录，必填。
+- `timeout_ms`：超时时间。
+- `sandbox_permissions`：使用默认沙箱，或在确实需要时请求 `require_escalated`。
+- `justification`：请求提权时展示给用户的问题。
+- `prefix_rule`：可选的、较窄范围的持久批准前缀。

package/concepts/zh/Tool-spawn_agent.md

@@ -0,0 +1,11 @@
+# spawn_agent
+
+`spawn_agent` 为一个具体、边界清晰且可以独立推进的任务创建子 Agent。新 Agent 会获得规范化任务名，并与根 Agent 共享工作区。
+
+字段：
+
+- `task_name`：小写任务标识，必填。
+- `message`：初始任务说明，必填。
+- `fork_turns`：复制最近多少轮会话上下文，可选。
+
+任务强依赖串行上下文或没有独立交付物时，不应使用本工具。

package/concepts/zh/Tool-tool_search.md

@@ -0,0 +1,12 @@
+# tool_search
+
+`tool_search` 在延迟装载的工具元数据中搜索匹配项，并让结果中的工具在下一轮可被调用。
+
+当前日志显示它用于发现多智能体工具、computer-use、node_repl、浏览器控制等插件或延迟工具。
+
+字段：
+
+- `query`：搜索词，必填。
+- `limit`：返回工具数量上限，可选。
+
+响应侧的 `tool_search_call` 会兼容跳转到本工具文档。

package/concepts/zh/Tool-update_goal.md

@@ -0,0 +1,9 @@
+# update_goal
+
+`update_goal` 用来把现有 goal 标记为 `complete` 或 `blocked`。
+
+使用边界：
+
+- 只有目标真实完成且没有剩余必要工作时，才能标记 `complete`。
+- 只有同一阻塞条件连续重复达到规则要求、且无法继续取得实质进展时，才能标记 `blocked`。
+- 不能把预算不足、任务较难或需要澄清本身当作完成或阻塞。

package/concepts/zh/Tool-update_plan.md

@@ -0,0 +1,9 @@
+# update_plan
+
+`update_plan` 用来维护当前任务计划，展示每一步的状态。每次最多只有一个步骤处于 `in_progress`。
+
+计划项状态：
+
+- `pending`：尚未开始。
+- `in_progress`：正在进行。
+- `completed`：已经完成。

package/concepts/zh/Tool-view_image.md

@@ -0,0 +1,10 @@
+# view_image
+
+`view_image` 用来查看本地文件系统中的图片，适合在视觉检查、截图验证、图片资产确认时使用。
+
+字段：
+
+- `path`：本地图片路径，必填。
+- `detail`：查看精度，可选 `high` 或 `original`。
+
+旧日志中的 `ImageView` 或 `imageView` 对应这个能力。

package/concepts/zh/Tool-wait.md

@@ -0,0 +1,12 @@
+# wait
+
+`wait` 用来恢复一个已 yield 的 `exec` cell，只返回本次新增输出或最终完成状态。
+
+字段：
+
+- `cell_id`：运行中的 exec cell 标识，必填。
+- `yield_time_ms`：再次 yield 前的等待时间。
+- `max_tokens`：本次 wait 返回内容的 token 上限。
+- `terminate`：为 true 时终止 cell，而不是继续等待。
+
+只有在 `exec` 明确报告脚本仍在运行并返回 cell id 后才使用本工具。

package/concepts/zh/Tool-wait_agent.md

@@ -0,0 +1,9 @@
+# wait_agent
+
+`wait_agent` 等待任意活跃 Agent 的 mailbox 更新。收到最终状态通知或新的用户输入改变当前轮次方向时，也会提前结束等待。
+
+字段：
+
+- `timeout_ms`：可选，必须处于运行时允许的等待范围内。
+
+返回值只汇总哪些 Agent 有更新，不包含消息正文；实际内容应从会话中送达的 Agent 消息查看。

package/concepts/zh/Tool-web_search.md

@@ -0,0 +1,11 @@
+# web_search
+
+`web_search` 用于访问网络搜索，支持文本和图片内容。Codex 官方手册说明，当 Codex 执行 web search 时，transcript 中会出现 `web_search` 项；该能力也可通过配置切换为缓存、实时或禁用。
+
+适用场景：
+
+- 用户明确要求联网、查询最新信息或验证当前事实。
+- 需要官方文档、直接链接或精确来源。
+- 信息有较高概率已经变化。
+
+响应侧的 `web_search_call` 会兼容跳转到本工具文档。

package/concepts/zh/Tools.md

@@ -1,67 +1,38 @@
-# Codex 工具一览
+# Codex 工具
 
-Codex 通过 Anthropic API 的 tool_use 机制向模型提供一组内置工具。每次 MainAgent 请求的 `tools` 数组中包含这些工具的完整 JSON Schema 定义，模型在响应中通过 `tool_use` content block 调用它们。
+“上下文消耗”弹窗里的 Codex 工具清单来自当前会话请求体中的已装载工具，而不是旧版工具集合。2026 年 7 月 11 日的本地请求日志包含 14 个嵌套/核心工具，以及两个新装载工具组中的 8 个可调用入口，共计 22 个已收录工具。
 
-以下是全部工具的分类索引。
+## Code Mode
 
-## Agent 系统
+- exec：Code Mode 的工具编排套件，在全新的 V8 isolate 中发现、组合、并行执行和续跑嵌套工具 workflow。
+- wait：继续等待或终止已 yield 的 exec cell，并返回最新输出。
 
-| 工具 | 用途 |
-|------|------|
-| [Task](Tool-Task.md) | 启动子 agent（SubAgent）处理复杂多步骤任务 |
-| [TaskOutput](Tool-TaskOutput.md) | 获取后台任务的输出 |
-| [TaskStop](Tool-TaskStop.md) | 停止正在运行的后台任务 |
-| [TaskCreate](Tool-TaskCreate.md) | 创建结构化任务列表条目 |
-| [TaskGet](Tool-TaskGet.md) | 获取任务详情 |
-| [TaskUpdate](Tool-TaskUpdate.md) | 更新任务状态、依赖关系等 |
-| [TaskList](Tool-TaskList.md) | 列出所有任务 |
+## 核心工具
 
-## 文件操作
+- shell_command：运行本地 shell 命令，并通过 sandbox/approval 字段表达权限边界。
+- apply_patch：用结构化 patch 修改工作区文件。
+- view_image：查看本地图片文件。
+- update_plan：维护任务计划。
+- request_user_input：在 Plan mode 下向用户提出结构化短问题。
+- get_goal：读取当前 goal 的状态、预算和用量。
+- create_goal：在明确要求时创建 goal。
+- update_goal：在目标真正完成或满足阻塞规则时更新 goal 状态。
+- tool_search：搜索延迟装载工具的元数据，并让匹配工具在下一轮可用。
+- list_mcp_resources：列出 MCP server 暴露的资源。
+- list_mcp_resource_templates：列出 MCP server 暴露的参数化资源模板。
+- read_mcp_resource：读取指定 MCP 资源。
+- web_search：访问网络搜索文本或图片内容。
+- image_generation：生成 PNG 图片。
 
-| 工具 | 用途 |
-|------|------|
-| [Read](Tool-Read.md) | 读取文件内容（支持文本、图片、PDF、Jupyter notebook） |
-| [Edit](Tool-Edit.md) | 通过精确字符串替换编辑文件 |
-| [Write](Tool-Write.md) | 写入或覆盖文件 |
-| [NotebookEdit](Tool-NotebookEdit.md) | 编辑 Jupyter notebook 单元格 |
+## Multi-Agent V2
 
-## 搜索
+- spawn_agent：创建一个边界清晰的子 Agent 任务。
+- send_message：向现有 Agent 投递上下文或指导，但不启动新一轮。
+- followup_task：分配后续任务，并在目标空闲时启动它。
+- wait_agent：等待 mailbox、完成通知或用户转向消息。
+- interrupt_agent：停止目标当前轮次，同时保留该 Agent 供后续复用。
+- list_agents：查看当前线程树中的活跃 Agent。
 
-| 工具 | 用途 |
-|------|------|
-| [Glob](Tool-Glob.md) | 按文件名模式匹配搜索文件 |
-| [Grep](Tool-Grep.md) | 基于 ripgrep 的文件内容搜索 |
+Code Mode 与 Multi-Agent V2 的工具名同时得到了本地请求体和 `openai/codex` 对应工具注册源码的确认。MCP、插件、App connector 等动态工具按会话发现和注入，因此不会硬编码进本目录。
 
-## 终端
-
-| 工具 | 用途 |
-|------|------|
-| [Bash](Tool-Bash.md) | 执行 shell 命令 |
-
-## Web
-
-| 工具 | 用途 |
-|------|------|
-| [WebFetch](Tool-WebFetch.md) | 抓取网页内容并用 AI 处理 |
-| [WebSearch](Tool-WebSearch.md) | 搜索引擎查询 |
-
-## 规划与交互
-
-| 工具 | 用途 |
-|------|------|
-| [EnterPlanMode](Tool-EnterPlanMode.md) | 进入规划模式，设计实施方案 |
-| [ExitPlanMode](Tool-ExitPlanMode.md) | 退出规划模式并提交方案供用户审批 |
-| [AskUserQuestion](Tool-AskUserQuestion.md) | 向用户提问以获取澄清或决策 |
-
-## 扩展
-
-| 工具 | 用途 |
-|------|------|
-| [Skill](Tool-Skill.md) | 执行技能（slash command） |
-
-## IDE 集成
-
-| 工具 | 用途 |
-|------|------|
-| [getDiagnostics](Tool-getDiagnostics.md) | 获取 VS Code 语言诊断信息 |
-| [executeCode](Tool-executeCode.md) | 在 Jupyter kernel 中执行代码 |
+旧版工具名不属于当前 Codex 工具清单，也不再作为概念文档别名保留。

package/concepts/zh/ToolsFirst.md

@@ -1,52 +1,48 @@
 # 为什么工具排在第一位？
 
-在 cx-viewer 的 Context 面板中，**工具（Tools）被放在 System Prompt 和 Messages 之前**。这不是随意排列，而是为了**精确反映 Anthropic API 的实际 KV-Cache 前缀顺序**。
+在 CX Viewer 的 Context 面板中，**工具（Tools）被放在 Instructions 和 Input 之前**。对 Codex 来说，这是一个诊断视图：工具定义是请求结构里体积大、影响强的一部分，因此先展示能力面，再展示约束它的指令和输入上下文。
 
-## KV-Cache 前缀序列
+## 请求上下文布局
 
-Anthropic API 在构建 KV-Cache 时，按以下**固定顺序**将上下文拼接为前缀序列：
+Codex 流量可能来自 OpenAI Responses API、Codex app-server 事件或 SDK 流事件。CX Viewer 会把这些来源归一化成一致的 Context 视图：
 
 ```
 ┌─────────────────────────────────────────────────┐
-│ 1. Tools (JSON Schema 定义)                      │  ← 缓存前缀的最前端
-│ 2. System Prompt                                 │
-│ 3. Messages (历史对话 + 当前 turn)               │  ← 缓存前缀的最后端
+│ 1. Tools (JSON Schema 定义)                      │  ← 能力面
+│ 2. Instructions                                  │
+│ 3. Input (历史对话 + 当前 turn)                  │
 └─────────────────────────────────────────────────┘
 ```
 
-这意味着 **Tools 比 System Prompt 更靠近缓存前缀的起始位置**。
+这个顺序不声称某个供应商一定按同样方式序列化请求，而是让你稳定地先检查可用能力，再阅读 instructions 和 input 历史。
 
-## 为什么 Tools 的缓存权重比 System 还高？
+## 为什么 Tools 往往最值得先看？
 
-在 KV-Cache 的前缀匹配机制中，**越靠前的内容越稳定**，对缓存命中的影响越大：
+工具定义通常是 agent 请求中最大的静态结构。一个 UI 开关、一个 MCP server 或一个动态工具变化，都可能让工具 schema 发生明显改变，进而影响模型行为和供应商报告的缓存用量。
 
-1. **前缀匹配是从头开始的**：KV-Cache 通过比较当前请求与上一次缓存的前缀序列来决定能复用多少。从第一个 token 开始逐一比较，一旦遇到不匹配就中断，后续全部失效。
+1. **能力变化就是语义变化**：增减工具会改变 agent 能做什么，不只是 token 数变化。
 
-2. **Tools 变化 = 全部缓存失效**：因为 Tools 在最前面，如果工具定义发生任何变化（哪怕只是增减一个 MCP tool），**整个缓存前缀从头开始就不匹配**，所有后续的 System Prompt 和 Messages 缓存全部作废。
+2. **工具 schema 可能占用大量上下文**：MCP 和动态工具通常包含详细 JSON Schema、描述、枚举和嵌套参数。
 
-3. **System 变化 = Messages 缓存失效**：System Prompt 在中间，它的变化只会导致后面的 Messages 缓存失效，但 Tools 部分的缓存仍然有效。
-
-4. **Messages 变化 = 只影响末尾**：Messages 在最后，新消息的追加只会让最后一小段缓存失效，前面的 Tools 和 System 缓存不受影响。
+4. **input 追加通常更容易判断**：正常对话多数只是新增用户输入、上一轮 assistant 回复和工具结果；工具和指令变化更少，但诊断价值更高。
 
 ## 实际影响
 
 | 变化类型 | 缓存影响 | 典型场景 |
 |----------|---------|---------|
-| 工具增减 | **全部失效** | MCP server 连接/断开、IDE 插件启停 |
-| System Prompt 变化 | Messages 缓存失效 | CLAUDE.md 修改、system reminder 注入 |
-| 新增消息 | 仅末尾增量 | 正常对话流（最常见，也最省钱） |
-
-这也是为什么 [CacheRebuild](CacheRebuild.md) 中 `tools_change` 导致的缓存重建成本往往最高 —— 它从最前面就打断了缓存前缀链。
+| 工具增减 | 供应商可能报告更低缓存复用 | MCP server 连接/断开、插件启停 |
+| Instructions 变化 | 指令和策略发生变化 | `AGENTS.md` 修改、developer instruction 更新 |
+| 新增 input | 仅末尾增量 | 正常对话流（最常见，也最省钱） |
 
 ## 为什么工具定义要排在思维之前？
 
-从缓存机制的角度，Tools 排在最前面是技术事实。但从认知设计的角度，这个顺序同样合理 —— **工具是手脚，System Prompt 是大脑**。
+从诊断角度看，把 Tools 放在前面很实用：工具定义先说明 agent 有哪些动作能力，然后再去看要求它行动的指令。
 
-一个人在行动之前，需要先感知自己有哪些肢体和工具可以使用。一个婴儿不是先理解世界的规则（System），再去学习如何伸手抓取；而是先感知到自己有手、有脚，然后在与环境的交互中逐渐理解规则。同样，LLM 在接收任务指令（System Prompt）之前，先知道自己能调用哪些工具（读文件、写代码、搜索、执行命令），才能在接收到指令时准确评估"我能做什么"和"我该怎么做"。
+一个人在行动之前，需要先感知自己有哪些肢体和工具可以使用。一个婴儿不是先理解世界的规则（Instructions），再去学习如何伸手抓取；而是先感知到自己有手、有脚，然后在与环境的交互中逐渐理解规则。同样，LLM 在接收任务指令（Instructions）之前，先知道自己能调用哪些工具（读文件、写代码、搜索、执行命令），才能在接收到指令时准确评估"我能做什么"和"我该怎么做"。
 
-如果反过来 —— 先告诉模型"你的任务是重构这个模块"，再告诉它"你有 Read、Edit、Bash 这些工具"—— 模型在理解任务时就缺少了关键的能力边界信息，可能产生不切实际的计划或遗漏可用的手段。
+如果反过来 —— 先告诉模型"你的任务是重构这个模块"，再告诉它"你有 shell_command、apply_patch、tool_search 这些工具"—— 模型在理解任务时就缺少了关键的能力边界信息，可能产生不切实际的计划或遗漏可用的手段。
 
-**先知道手里有什么牌，再决定怎么打。** 这就是 Tools 优先于 System 的认知逻辑。
+**先知道手里有什么牌，再决定怎么打。** 这就是 Tools 优先于 Instructions 的认知逻辑。
 
 ## MCP 工具为什么也在这个位置？
 
@@ -59,9 +55,7 @@ MCP（Model Context Protocol）工具与内置工具一样，被放在 Tools 区
 - **按需加载**：可以根据任务场景选择性连接/断开 MCP server，灵活组合工具集
 
 ### MCP 的代价
-
-- **缓存杀手**：每个 MCP tool 的 JSON Schema 定义都会被拼入 KV-Cache 前缀的最前端。增减一个 MCP tool = **整个缓存从头失效**。如果频繁连接/断开 MCP server，缓存命中率会大幅下降
-- **前缀膨胀**：MCP tool 的 Schema 通常比内置工具更大（包含详细的参数描述、枚举值等）。大量 MCP tool 会显著增加 Tools 区域的 token 数，挤压留给 Messages 的 context 空间
+- **前缀膨胀**：MCP tool 的 Schema 通常比内置工具更大（包含详细的参数描述、枚举值等）。大量 MCP tool 会显著增加 Tools 区域的 token 数，挤压留给 Input 的 context 空间
 - **延迟开销**：MCP tool 调用需要跨进程通信（JSON-RPC over stdio/SSE），比内置工具的函数调用慢一个数量级
 - **稳定性风险**：MCP server 是外部进程，可能崩溃、超时、返回异常格式，需要额外的错误处理
 
@@ -74,4 +68,4 @@ MCP（Model Context Protocol）工具与内置工具一样，被放在 Tools 区
 | MCP server 频繁增减 | 每次变动都会全量重建缓存，考虑固定 tool 集合 |
 | Tool Schema 过大 | 精简 description 和 enum，减少前缀 token 占用 |
 
-在 cx-viewer 的 Context 面板中，MCP 工具与内置工具并列显示在 Tools 区域，可以直观看到每个 tool 的 Schema 体积和对缓存前缀的贡献。
+在 CX Viewer 的 Context 面板中，MCP 工具会和内置工具、动态工具一起显示在 Tools 区域，可以直观看到每个 tool 的 Schema 体积以及它对请求结构的贡献。