cx-viewer 1.0.0

package/concepts/zh/Tool-TeamDelete.md

@@ -0,0 +1,30 @@
+# TeamDelete
+
+## 定义
+
+在多 agent 协作工作完成后，删除团队及其关联的任务目录。是 TeamCreate 的清理对应操作。
+
+## 行为
+
+- 删除团队目录：`~/.claude/teams/{team-name}/`
+- 删除任务目录：`~/.claude/tasks/{team-name}/`
+- 清除当前会话中的团队上下文
+
+**重要**：如果团队中仍有活跃成员，TeamDelete 将会失败。必须先通过 SendMessage 发送关闭请求，优雅地关闭所有队友。
+
+## 典型用法
+
+TeamDelete 在团队工作流程结束时调用：
+
+1. 所有任务已完成
+2. 通过 `SendMessage` 发送 `shutdown_request` 关闭队友
+3. **TeamDelete** 删除团队和任务目录
+
+## 相关工具
+
+| 工具 | 用途 |
+|------|------|
+| `TeamCreate` | 创建新团队及其任务列表 |
+| `SendMessage` | 与队友通信 / 发送关闭请求 |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | 管理共享任务列表 |
+| `Agent` | 生成加入团队的队友 |

package/concepts/zh/Tool-WebFetch.md

@@ -0,0 +1,55 @@
+# WebFetch
+
+## 定义
+
+抓取指定 URL 的网页内容，将 HTML 转换为 markdown，并使用 AI 模型根据 prompt 处理内容。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `url` | string (URI) | 是 | 要抓取的完整 URL |
+| `prompt` | string | 是 | 描述要从页面中提取什么信息 |
+
+## 使用场景
+
+**适合使用：**
+- 获取公开网页的内容
+- 查阅在线文档
+- 提取网页中的特定信息
+
+**不适合使用：**
+- 需要认证的 URL（Google Docs、Confluence、Jira、GitHub 等）——应先查找专用的 MCP 工具
+- GitHub URL——优先使用 `gh` CLI
+
+## 注意事项
+
+- URL 必须是完整的有效 URL
+- HTTP 会自动升级为 HTTPS
+- 内容过大时结果可能被摘要
+- 包含 15 分钟自清理缓存
+- 当 URL 重定向到不同主机时，工具会返回重定向 URL，需要用新 URL 重新请求
+- 如果有 MCP 提供的 web fetch 工具可用，优先使用那个
+
+## 原文
+
+<textarea readonly>IMPORTANT: WebFetch WILL FAIL for authenticated or private URLs. Before using this tool, check if the URL points to an authenticated service (e.g. Google Docs, Confluence, Jira, GitHub). If so, you MUST use ToolSearch first to find a specialized tool that provides authenticated access.
+
+- Fetches content from a specified URL and processes it using an AI model
+- Takes a URL and a prompt as input
+- Fetches the URL content, converts HTML to markdown
+- Processes the content with the prompt using a small, fast model
+- Returns the model's response about the content
+- Use this tool when you need to retrieve and analyze web content
+
+Usage notes:
+  - IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead of this one, as it may have fewer restrictions.
+  - The URL must be a fully-formed valid URL
+  - HTTP URLs will be automatically upgraded to HTTPS
+  - The prompt should describe what information you want to extract from the page
+  - This tool is read-only and does not modify any files
+  - Results may be summarized if the content is very large
+  - Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL
+  - When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL to fetch the content.
+  - For GitHub URLs, prefer using the gh CLI via Bash instead (e.g., gh pr view, gh issue view, gh api).
+</textarea>

package/concepts/zh/Tool-WebSearch.md

@@ -0,0 +1,58 @@
+# WebSearch
+
+## 定义
+
+执行搜索引擎查询，返回搜索结果用于获取最新信息。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `query` | string | 是 | 搜索查询（最少 2 个字符） |
+| `allowed_domains` | string[] | 否 | 仅包含这些域名的结果 |
+| `blocked_domains` | string[] | 否 | 排除这些域名的结果 |
+
+## 使用场景
+
+**适合使用：**
+- 获取超出模型知识截止日期的最新信息
+- 查找当前事件和最新数据
+- 搜索最新的技术文档
+
+## 注意事项
+
+- 搜索结果以 markdown 超链接格式返回
+- 使用后必须在响应末尾附上 "Sources:" 部分，列出相关 URL
+- 支持域名过滤（包含/排除）
+- 搜索查询中应使用当前年份
+- 仅在美国可用
+
+## 原文
+
+<textarea readonly>
+- Allows Claude to search the web and use the results to inform responses
+- Provides up-to-date information for current events and recent data
+- Returns search result information formatted as search result blocks, including links as markdown hyperlinks
+- Use this tool for accessing information beyond Claude's knowledge cutoff
+- Searches are performed automatically within a single API call
+
+CRITICAL REQUIREMENT - You MUST follow this:
+  - After answering the user's question, you MUST include a "Sources:" section at the end of your response
+  - In the Sources section, list all relevant URLs from the search results as markdown hyperlinks: [Title](URL)
+  - This is MANDATORY - never skip including sources in your response
+  - Example format:
+
+    [Your answer here]
+
+    Sources:
+    - [Source Title 1](https://example.com/1)
+    - [Source Title 2](https://example.com/2)
+
+Usage notes:
+  - Domain filtering is supported to include or block specific websites
+  - Web search is only available in the US
+
+IMPORTANT - Use the correct year in search queries:
+  - The current month is March 2026. You MUST use this year when searching for recent information, documentation, or current events.
+  - Example: If the user asks for "latest React docs", search for "React documentation" with the current year, NOT last year
+</textarea>

package/concepts/zh/Tool-Write.md

@@ -0,0 +1,39 @@
+# Write
+
+## 定义
+
+将内容写入本地文件系统。如果文件已存在则覆盖。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_path` | string | 是 | 文件的绝对路径（必须是绝对路径） |
+| `content` | string | 是 | 要写入的内容 |
+
+## 使用场景
+
+**适合使用：**
+- 创建新文件
+- 需要完全重写文件内容时
+
+**不适合使用：**
+- 修改文件中的局部内容——应使用 Edit
+- 不应主动创建文档文件（*.md）或 README，除非用户明确要求
+
+## 注意事项
+
+- 如果目标文件已存在，必须先通过 Read 读取，否则会失败
+- 会覆盖已有文件的全部内容
+- 优先使用 Edit 编辑现有文件，Write 仅用于创建新文件或完全重写
+
+## 原文
+
+<textarea readonly>Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- Prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
+- NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.</textarea>

package/concepts/zh/Tool-executeCode.md

@@ -0,0 +1,41 @@
+# executeCode (mcp__ide__executeCode)
+
+## 定义
+
+在当前 notebook 文件的 Jupyter kernel 中执行 Python 代码。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `code` | string | 是 | 要执行的 Python 代码 |
+
+## 使用场景
+
+**适合使用：**
+- 在 Jupyter notebook 环境中执行代码
+- 测试代码片段
+- 数据分析和计算
+
+**不适合使用：**
+- 非 Jupyter 环境的代码执行——应使用 Bash
+- 修改文件——应使用 Edit 或 Write
+
+## 注意事项
+
+- 这是一个 MCP（Model Context Protocol）工具，由 IDE 集成提供
+- 代码在当前 Jupyter kernel 中执行，状态在调用间持久化
+- 除非用户明确要求，应避免声明变量或修改 kernel 状态
+- kernel 重启后状态会丢失
+
+## 原文
+
+<textarea readonly>Execute python code in the Jupyter kernel for the current notebook file.
+    
+    All code will be executed in the current Jupyter kernel.
+    
+    Avoid declaring variables or modifying the state of the kernel unless the user
+    explicitly asks for it.
+    
+    Any code executed will persist across calls to this tool, unless the kernel
+    has been restarted.</textarea>

package/concepts/zh/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## 定义
+
+从 VS Code 获取语言诊断信息，包括语法错误、类型错误、lint 警告等。
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `uri` | string | 否 | 文件 URI。不提供则获取所有文件的诊断信息 |
+
+## 使用场景
+
+**适合使用：**
+- 检查代码的语法、类型、lint 等语义问题
+- 编辑代码后验证是否引入了新错误
+- 替代 Bash 命令来检查代码质量
+
+**不适合使用：**
+- 运行测试——应使用 Bash
+- 检查运行时错误——应使用 Bash 执行代码
+
+## 注意事项
+
+- 这是一个 MCP（Model Context Protocol）工具，由 IDE 集成提供
+- 仅在 VS Code / IDE 环境中可用
+- 优先使用此工具而非 Bash 命令来检查代码问题
+
+## 原文
+
+<textarea readonly>Get language diagnostics from VS Code</textarea>

package/concepts/zh/Tools.md

@@ -0,0 +1,67 @@
+# Codex 工具一览
+
+Codex 通过 Anthropic API 的 tool_use 机制向模型提供一组内置工具。每次 MainAgent 请求的 `tools` 数组中包含这些工具的完整 JSON Schema 定义，模型在响应中通过 `tool_use` content block 调用它们。
+
+以下是全部工具的分类索引。
+
+## Agent 系统
+
+| 工具 | 用途 |
+|------|------|
+| [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) | 列出所有任务 |
+
+## 文件操作
+
+| 工具 | 用途 |
+|------|------|
+| [Read](Tool-Read.md) | 读取文件内容（支持文本、图片、PDF、Jupyter notebook） |
+| [Edit](Tool-Edit.md) | 通过精确字符串替换编辑文件 |
+| [Write](Tool-Write.md) | 写入或覆盖文件 |
+| [NotebookEdit](Tool-NotebookEdit.md) | 编辑 Jupyter notebook 单元格 |
+
+## 搜索
+
+| 工具 | 用途 |
+|------|------|
+| [Glob](Tool-Glob.md) | 按文件名模式匹配搜索文件 |
+| [Grep](Tool-Grep.md) | 基于 ripgrep 的文件内容搜索 |
+
+## 终端
+
+| 工具 | 用途 |
+|------|------|
+| [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 中执行代码 |

package/concepts/zh/ToolsFirst.md

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

package/concepts/zh/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# 翻译接口 Context 污染问题
+
+## 背景
+
+CX-Viewer 内置了翻译功能（`POST /api/translate`），通过调用 Anthropic Messages API 实现文本翻译。在早期实现中，翻译请求会复用 Codex 会话中缓存的认证凭据——包括 `x-api-key` 和 `authorization` header。这导致了一个隐蔽但严重的问题：翻译结果频繁"答非所问"。
+
+## 问题根因
+
+### 两种认证方式的本质区别
+
+Anthropic API 支持两种认证方式：
+
+| 方式 | 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/) — 认证方式对比

package/concepts/zh/UltraPlan.md

@@ -0,0 +1,55 @@
+# UltraPlan — 至尊许愿机
+
+## 什么是 UltraPlan
+
+UltraPlan 是 cx-viewer 对 Codex 原生 `/ultraplan` 命令的**本地化实现**。它让你无需启动 Claude 官方的远程服务，即可在本地环境中使用 `/ultraplan` 的完整能力，引导 Codex 以**多代理协作**的方式完成复杂的规划和实现任务。
+
+与普通的 Plan 模式或 Agent Team 相比，UltraPlan 能够：
+- 自动评估任务复杂度并选择最优规划策略
+- 派遣多个并行代理从不同维度探索代码库
+- 引入外部搜索（webSearch）调研业界最佳实践
+- 在计划执行完成后自动组建 Code Review Team 进行代码审查
+- 形成**规划 → 执行 → 审查 → 修复**的完整闭环
+
+---
+
+## 使用须知
+
+### 1. UltraPlan 不是万能的
+UltraPlan 是一个更强大的许愿机，但不代表什么愿望都可以实现。它比 Plan 和 Agent Team 更强大，但不代表能够直接帮你"赚钱"。你需要考虑任务的合理步长——将大目标拆解为可执行的中等粒度任务，而不是试图一步到位。
+
+### 2. 目前主要针对编程项目有奇效
+UltraPlan 的模板和流程目前针对编程项目进行了深度优化。其他场景（文档撰写、数据分析等）可以尝试使用，也可以等待后续版本的适配优化。
+
+### 3. 执行时间和上下文窗口要求
+- 如果 UltraPlan 命中成功，单次执行通常需要 **30 分钟以上**
+- 需要 MainAgent 拥有更大的上下文窗口（推荐 1M context 的 Opus 模型）
+- 如果你只有 200K 的大模型，**务必在执行前先 `/clear` 上下文**
+- Codex 在窗口不足时执行 `/compact` 的效果非常差，要避免窗口爆满
+- 保持充足的上下文空间是 UltraPlan 成功执行的关键前提
+
+如果对本地化的 UltraPlan 有任何疑问或建议，欢迎在 [GitHub](https://github.com/anthropics/claude-code/issues) 上提 Issues，一起探讨交流。
+
+---
+
+## 运行原理
+
+UltraPlan 提供两种运行模式：
+
+### 自适应模式（Auto）
+自动分析任务复杂度（4-12 分），根据评分路由到不同策略：
+
+| 路由 | 评分 | 策略 |
+|------|------|------|
+| Route A | 4-6 分 | 轻量规划，直接探索代码 |
+| Route B | 7-9 分 | 带结构图表的规划（Mermaid / ASCII） |
+| Route C | 10-12 分 | 多代理探索 + 审查闭环 |
+
+### 强制模式（Forced）
+直接启用 Route C 的完整多代理流程：
+1. 派遣最多 5 个并行代理同时探索代码库（架构理解、文件定位、风险识别等）
+2. 可选派遣预研代理通过 webSearch 调研业界方案
+3. 综合所有代理发现，生成详细的实施计划
+4. 派遣审查代理从多角度审查计划的完整性
+5. 计划获批后执行实施
+6. 实施完成后自动组建 Code Review Team 验证代码质量

package/concepts/zh-TW/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON（請求體增量對比）
+
+## 背景
+
+Codex 的 MainAgent 採用全量上下文發送機制——每次請求都會攜帶完整的對話歷史、system prompt、工具定義等內容。這意味著隨著對話推進，請求體會越來越龐大，直接查看原始 Body 很難快速定位「這一輪到底新增了什麼」。
+
+Body Diff JSON 正是為了解決這個問題：它自動對比前後兩個 MainAgent 請求的 body，提煉出增量部分，讓你一眼看清本次請求實際新增的內容。
+
+## 工作原理
+
+1. **識別連續的 MainAgent 請求**：當前請求必須是 MainAgent 類型，且存在上一個 MainAgent 請求
+2. **逐欄位對比**：遍歷請求體的所有頂層欄位，跳過 `_` 前綴的內部屬性
+3. **智慧差異提取**：
+   - 新增的欄位：直接展示
+   - 刪除的欄位：不顯示（通常不影響理解）
+   - 變更的欄位：展示當前值
+   - `messages` 陣列特殊處理：只展示新增的訊息（因為正常對話是追加模式，前綴訊息不變）
+4. **請求體縮小偵測**：如果當前請求體比上一個更小，說明發生了上下文截斷或會話重置，此時會顯示提示訊息而非 diff
+
+## 典型場景
+
+在一輪正常對話中，Body Diff JSON 通常只包含：
+- `messages`：新增的 1~2 條訊息（使用者的輸入 + 上一輪助手的回覆）
+
+如果你看到 diff 中出現了 `system`、`tools`、`model` 等欄位的變更，說明本輪請求發生了配置變化，這往往也是快取重建的原因。
+
+## 使用方式
+
+- Body Diff JSON 顯示在 MainAgent 請求的詳情面板中
+- 點擊標題可展開/收起
+- 支援 JSON 和 Text 兩種查看模式，以及一鍵複製
+- 在左上角 **CX-Viewer → 全域設定** 中，可以設定「預設展開 Body Diff JSON」

package/concepts/zh-TW/BodyFields.md

@@ -0,0 +1,42 @@
+# Request Body 欄位說明
+
+Claude API `/v1/messages` 請求體的頂層欄位說明。
+
+## 欄位列表
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| **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` |
+
+## messages 結構
+
+每條訊息的 `content` 是一個 block 陣列，常見類型：
+
+- **text**: 普通文字內容
+- **tool_use**: 模型呼叫工具（含 `name`、`input`）
+- **tool_result**: 工具執行結果（含 `tool_use_id`、`content`）
+- **image**: 圖片內容（base64 或 URL）
+- **thinking**: 模型的思考過程（擴展思考模式）
+
+## system 結構
+
+system prompt 陣列中通常包含：
+
+1. **核心 agent 指令**（"You are Codex..."）
+2. **工具使用規範**
+3. **CLAUDE.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 之間的一種默契。

package/concepts/zh-TW/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` 壓縮摘要替換原始訊息）