cx-viewer 1.0.2 → 1.0.4

package/concepts/zh/Tool-TaskUpdate.md

@@ -1,123 +0,0 @@
-# TaskUpdate
-
-## 定义
-
-更新任务列表中某个任务的状态、内容或依赖关系。
-
-## 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `taskId` | string | 是 | 要更新的任务 ID |
-| `status` | enum | 否 | 新状态：`pending` / `in_progress` / `completed` / `deleted` |
-| `subject` | string | 否 | 新标题 |
-| `description` | string | 否 | 新描述 |
-| `activeForm` | string | 否 | 进行中时显示的现在进行时文本 |
-| `owner` | string | 否 | 新的任务负责人（agent 名称） |
-| `metadata` | object | 否 | 要合并的元数据（设为 null 可删除键） |
-| `addBlocks` | string[] | 否 | 被此任务阻塞的任务 ID 列表 |
-| `addBlockedBy` | string[] | 否 | 阻塞此任务的前置任务 ID 列表 |
-
-## 状态流转
-
-```
-pending → in_progress → completed
-```
-
-`deleted` 可从任何状态转入，永久移除任务。
-
-## 使用场景
-
-**适合使用：**
-- 开始工作时标记任务为 `in_progress`
-- 完成工作后标记任务为 `completed`
-- 设置任务间的依赖关系
-- 需求变更时更新任务内容
-
-**重要规则：**
-- 只有在完全完成任务时才标记为 `completed`
-- 遇到错误或阻塞时保持 `in_progress`
-- 测试失败、实现不完整、遇到未解决错误时不得标记为 `completed`
-
-## 注意事项
-
-- 更新前应先通过 TaskGet 获取任务最新状态，避免过期数据
-- 完成任务后调用 TaskList 查找下一个可用任务
-
-## 原文
-
-<textarea readonly>Use this tool to update a task in the task list.
-
-## When to Use This Tool
-
-**Mark tasks as resolved:**
-- When you have completed the work described in a task
-- When a task is no longer needed or has been superseded
-- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
-- After resolving, call TaskList to find your next task
-
-- ONLY mark a task as completed when you have FULLY accomplished it
-- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
-- When blocked, create a new task describing what needs to be resolved
-- Never mark a task as completed if:
-  - Tests are failing
-  - Implementation is partial
-  - You encountered unresolved errors
-  - You couldn't find necessary files or dependencies
-
-**Delete tasks:**
-- When a task is no longer relevant or was created in error
-- Setting status to `deleted` permanently removes the task
-
-**Update task details:**
-- When requirements change or become clearer
-- When establishing dependencies between tasks
-
-## Fields You Can Update
-
-- **status**: The task status (see Status Workflow below)
-- **subject**: Change the task title (imperative form, e.g., "Run tests")
-- **description**: Change the task description
-- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
-- **owner**: Change the task owner (agent name)
-- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
-- **addBlocks**: Mark tasks that cannot start until this one completes
-- **addBlockedBy**: Mark tasks that must complete before this one can start
-
-## Status Workflow
-
-Status progresses: `pending` → `in_progress` → `completed`
-
-Use `deleted` to permanently remove a task.
-
-## Staleness
-
-Make sure to read a task's latest state using `TaskGet` before updating it.
-
-## Examples
-
-Mark task as in progress when starting work:
-```json
-{"taskId": "1", "status": "in_progress"}
-```
-
-Mark task as completed after finishing work:
-```json
-{"taskId": "1", "status": "completed"}
-```
-
-Delete a task:
-```json
-{"taskId": "1", "status": "deleted"}
-```
-
-Claim a task by setting owner:
-```json
-{"taskId": "1", "owner": "my-name"}
-```
-
-Set up task dependencies:
-```json
-{"taskId": "2", "addBlockedBy": ["1"]}
-```
-</textarea>

package/concepts/zh/Tool-TeamCreate.md

@@ -1,38 +0,0 @@
-# TeamCreate
-
-## 定义
-
-创建一个新的团队来协调多个 agent 协同工作。团队通过共享任务列表和 agent 间消息传递实现并行任务执行。
-
-## 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `team_name` | string | 是 | 新团队的名称 |
-| `description` | string | 否 | 团队描述/用途 |
-| `agent_type` | string | 否 | 团队负责人的类型/角色 |
-
-## 创建内容
-
-- **团队配置文件**：`~/.claude/teams/{team-name}/config.json` — 存储成员列表和元数据
-- **任务列表目录**：`~/.claude/tasks/{team-name}/` — 所有队友共享的任务列表
-
-团队与任务列表一一对应。
-
-## 团队工作流程
-
-1. **TeamCreate** — 创建团队及其任务列表
-2. **TaskCreate** — 为团队定义任务
-3. **Agent**（带 `team_name` + `name`）— 生成加入团队的队友
-4. **TaskUpdate** — 通过 `owner` 将任务分配给队友
-5. 队友处理任务，通过 **SendMessage** 进行通信
-6. 完成后关闭队友，然后用 **TeamDelete** 清理资源
-
-## 相关工具
-
-| 工具 | 用途 |
-|------|------|
-| `TeamDelete` | 删除团队和任务目录 |
-| `SendMessage` | 团队内 agent 间的通信 |
-| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | 管理共享任务列表 |
-| `Agent` | 生成加入团队的队友 |

package/concepts/zh/Tool-TeamDelete.md

@@ -1,30 +0,0 @@
-# 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

@@ -1,55 +0,0 @@
-# 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

@@ -1,58 +0,0 @@
-# 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

@@ -1,39 +0,0 @@
-# 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

@@ -1,41 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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-TW/CacheRebuild.md

@@ -1,36 +0,0 @@
-# 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-TW/KVCacheContent.md

@@ -1,49 +0,0 @@
-# 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/Tool-Agent.md

@@ -1,125 +0,0 @@
-# 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>