cc-viewer 1.6.182 → 1.6.183

package/concepts/zh/Tool-EnterPlanMode.md

@@ -1,128 +1,35 @@
 # EnterPlanMode
 
-## 定义
+将会话切换到计划模式——一个只读探索阶段，助手在其中调研代码库并起草具体的实施方案，交由用户审批后再修改任何文件。
 
-将 Claude Code 切换到规划模式，用于在实施前探索代码库并设计方案。
+## 何时使用
+
+- 用户请求的是跨多个文件或子系统的非平凡改动。
+- 需求存在歧义，助手需要先阅读代码再决定方案。
+- 提出重构、迁移或依赖升级，而影响范围尚不明确。
+- 用户明确说「先做计划」「先规划一下」或请求设计评审。
+- 风险较高，直接动手可能浪费工作或破坏状态。
 
 ## 参数
 
-无参数。
+无。`EnterPlanMode` 不接受任何参数——调用时传入空参数对象即可。
 
-## 使用场景
+## 示例
 
-**适合使用：**
-- 新功能实现——需要架构决策
-- 存在多种可行方案——需要用户选择
-- 代码修改影响现有行为或结构
-- 多文件变更——可能涉及 2-3 个以上文件
-- 需求不明确——需要先探索再理解范围
-- 用户偏好很重要——实现可以有多种合理方向
+### 示例 1：大型功能请求
 
-**不适合使用：**
-- 单行或少量行的修复（拼写错误、明显 bug）
-- 用户已给出非常具体的指令
-- 纯研究/探索任务——应使用 Task（Explore 类型）
+用户说：「给管理后台加上通过 Okta 的 SSO。」助手调用 `EnterPlanMode`，接着花费若干轮阅读认证中间件、会话存储、路由守卫和现有登录 UI。它写出一份计划，描述所需改动、迁移步骤和测试覆盖，然后通过 `ExitPlanMode` 提交审批。
 
-## 规划模式中的行为
+### 示例 2：高风险重构
 
-进入规划模式后，Claude Code 会：
-1. 使用 Glob、Grep、Read 工具深入探索代码库
-2. 理解现有模式和架构
-3. 设计实施方案
-4. 将方案提交给用户审批
-5. 如需澄清可使用 AskUserQuestion
-6. 方案就绪后通过 ExitPlanMode 退出
+用户说：「把 REST 控制器换成 tRPC。」助手进入计划模式，审视每个控制器，盘点公开契约，列出发布阶段（shim、双读、切换），并在修改任何文件之前提出排序计划。
 
 ## 注意事项
 
-- 此工具需要用户同意才能进入规划模式
-- 如果不确定是否需要规划，倾向于规划——提前对齐比返工好
-
-## 原文
-
-<textarea readonly>Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.
-
-## When to Use This Tool
-
-**Prefer using EnterPlanMode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply:
-
-1. **New Feature Implementation**: Adding meaningful new functionality
-   - Example: "Add a logout button" - where should it go? What should happen on click?
-   - Example: "Add form validation" - what rules? What error messages?
-
-2. **Multiple Valid Approaches**: The task can be solved in several different ways
-   - Example: "Add caching to the API" - could use Redis, in-memory, file-based, etc.
-   - Example: "Improve performance" - many optimization strategies possible
-
-3. **Code Modifications**: Changes that affect existing behavior or structure
-   - Example: "Update the login flow" - what exactly should change?
-   - Example: "Refactor this component" - what's the target architecture?
-
-4. **Architectural Decisions**: The task requires choosing between patterns or technologies
-   - Example: "Add real-time updates" - WebSockets vs SSE vs polling
-   - Example: "Implement state management" - Redux vs Context vs custom solution
-
-5. **Multi-File Changes**: The task will likely touch more than 2-3 files
-   - Example: "Refactor the authentication system"
-   - Example: "Add a new API endpoint with tests"
-
-6. **Unclear Requirements**: You need to explore before understanding the full scope
-   - Example: "Make the app faster" - need to profile and identify bottlenecks
-   - Example: "Fix the bug in checkout" - need to investigate root cause
-
-7. **User Preferences Matter**: The implementation could reasonably go multiple ways
-   - If you would use AskUserQuestion to clarify the approach, use EnterPlanMode instead
-   - Plan mode lets you explore first, then present options with context
-
-## When NOT to Use This Tool
-
-Only skip EnterPlanMode for simple tasks:
-- Single-line or few-line fixes (typos, obvious bugs, small tweaks)
-- Adding a single function with clear requirements
-- Tasks where the user has given very specific, detailed instructions
-- Pure research/exploration tasks (use the Agent tool with explore agent instead)
-
-## What Happens in Plan Mode
-
-In plan mode, you'll:
-1. Thoroughly explore the codebase using Glob, Grep, and Read tools
-2. Understand existing patterns and architecture
-3. Design an implementation approach
-4. Present your plan to the user for approval
-5. Use AskUserQuestion if you need to clarify approaches
-6. Exit plan mode with ExitPlanMode when ready to implement
-
-## Examples
-
-### GOOD - Use EnterPlanMode:
-User: "Add user authentication to the app"
-- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)
-
-User: "Optimize the database queries"
-- Multiple approaches possible, need to profile first, significant impact
-
-User: "Implement dark mode"
-- Architectural decision on theme system, affects many components
-
-User: "Add a delete button to the user profile"
-- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates
-
-User: "Update the error handling in the API"
-- Affects multiple files, user should approve the approach
-
-### BAD - Don't use EnterPlanMode:
-User: "Fix the typo in the README"
-- Straightforward, no planning needed
-
-User: "Add a console.log to debug this function"
-- Simple, obvious implementation
-
-User: "What files handle routing?"
-- Research task, not implementation planning
-
-## Important Notes
-
-- This tool REQUIRES user approval - they must consent to entering plan mode
-- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work
-- Users appreciate being consulted before significant changes are made to their codebase
-</textarea>
+- 计划模式在契约上是只读的。处于其中时，助手不得运行 `Edit`、`Write`、`NotebookEdit` 或任何会改变状态的 shell 命令。仅使用 `Read`、`Grep`、`Glob` 以及非破坏性的 `Bash` 命令。
+- 不要对简单的单行编辑、纯粹的研究性问题，或用户已详细指定的任务进入计划模式。开销得不偿失。
+- 在 Auto 模式下，除非用户明确要求，否则不建议进入计划模式——Auto 模式倾向于先行动而非事先规划。
+- 通过计划模式降低高成本工作的反复修改。五分钟的计划往往能省下一小时的无用编辑。
+- 进入计划模式后，将调研聚焦在真正会改动的部分。避免对与当前任务无关的仓库区域做详尽巡视。
+- 计划本身应写入运行时约定的路径，以便 `ExitPlanMode` 提交。计划应包含具体的文件路径、函数名和验证步骤，而不是笼统的意图。
+- 用户可能驳回计划并要求修改。请在计划模式内迭代，直到计划被接受；然后再退出。

package/concepts/zh/Tool-EnterWorktree.md

@@ -1,56 +1,44 @@
 # EnterWorktree
 
-## 定义
+在新分支上创建一个隔离的 Git worktree，或将会话切换到当前仓库的已有 worktree，以便并行或试验性工作可在不影响主检出的情况下进行。
 
-创建隔离的 git worktree 并将当前会话切换到其中。仅在用户明确要求使用 worktree 时使用。
+## 何时使用
 
-## 参数
-
-| 参数名 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| name | string | 否 | `name`（可选）：worktree 的名称。未提供时自动生成随机名称。 |
-
-## 使用场景
+- 用户明确说「worktree」——例如「开启一个 worktree」「创建一个 worktree」或「在 worktree 中工作」。
+- `CLAUDE.md` 或持久内存中的项目指令要求你为当前任务使用 worktree。
+- 你想继续之前以 worktree 形式建立的任务（传入 `path` 重新进入）。
+- 多个试验性分支需要同时存在于磁盘上，而不必频繁切换检出。
+- 长时间运行的任务需要与主工作树中的无关编辑隔离。
 
-**适合使用：**
-- 用户明确说 "worktree"（如 "创建一个 worktree"、"在 worktree 中工作"）
-
-**不适合使用：**
-- 用户要求创建分支、切换分支——使用 git 命令
-- 用户要求修复 bug 或开发功能——除非明确提到 worktree，否则使用正常 git 工作流
-
-## 注意事项
-
-- 必须在 git 仓库中，或已配置 WorktreeCreate/WorktreeRemove hooks
-- 不能已经在 worktree 中
-
-## 原文
-
-<textarea readonly>Use this tool ONLY when the user explicitly asks to work in a worktree. This tool creates an isolated git worktree and switches the current session into it.
+## 参数
 
-## When to Use
+- `name` (string, 可选)：新 worktree 目录的名称。每个以 `/` 分隔的段只能包含字母、数字、点、下划线和短横线；完整字符串上限 64 个字符。若 `name` 与 `path` 都省略，则自动生成随机名称。与 `path` 互斥。
+- `path` (string, 可选)：要切换进入的当前仓库现有 worktree 的文件系统路径。必须出现在本仓库的 `git worktree list` 中；不属于当前仓库已注册 worktree 的路径会被拒绝。与 `name` 互斥。
 
-- The user explicitly says "worktree" (e.g., "start a worktree", "work in a worktree", "create a worktree", "use a worktree")
+## 示例
 
-## When NOT to Use
+### 示例 1：使用描述性名称创建新 worktree
 
-- The user asks to create a branch, switch branches, or work on a different branch — use git commands instead
-- The user asks to fix a bug or work on a feature — use normal git workflow unless they specifically mention worktrees
-- Never use this tool unless the user explicitly mentions "worktree"
+```
+EnterWorktree(name="feat/okta-sso")
+```
 
-## Requirements
+基于 `HEAD` 在新分支上创建 `.claude/worktrees/feat/okta-sso`，然后将会话的工作目录切换到其中。此后所有文件编辑和 shell 命令都在该 worktree 中执行，直到退出。
 
-- Must be in a git repository, OR have WorktreeCreate/WorktreeRemove hooks configured in settings.json
-- Must not already be in a worktree
+### 示例 2：重新进入已有的 worktree
 
-## Behavior
+```
+EnterWorktree(path="/Users/me/repo/.claude/worktrees/feat/okta-sso")
+```
 
-- In a git repository: creates a new git worktree inside `.claude/worktrees/` with a new branch based on HEAD
-- Outside a git repository: delegates to WorktreeCreate/WorktreeRemove hooks for VCS-agnostic isolation
-- Switches the session's working directory to the new worktree
-- On session exit, the user will be prompted to keep or remove the worktree
+恢复此前创建的 worktree 的工作。由于通过 `path` 进入，`ExitWorktree` 不会自动删除它——以 `action: "keep"` 离开只是返回原目录。
 
-## Parameters
+## 注意事项
 
-- `name` (optional): A name for the worktree. If not provided, a random name is generated.
-</textarea>
+- 除非用户明确要求或项目指令规定，否则不要调用 `EnterWorktree`。普通的分支切换或 bug 修复请求应使用标准 Git 命令，而不是 worktree。
+- 在 Git 仓库内调用时，工具会在 `.claude/worktrees/` 下创建 worktree，并基于 `HEAD` 注册新分支。在 Git 仓库之外，它会委派给 `settings.json` 中配置的 `WorktreeCreate` / `WorktreeRemove` hook，以实现与 VCS 无关的隔离。
+- 同一时间只允许一个 worktree 会话活跃。如果你已经在 worktree 会话中，本工具会拒绝运行；请先用 `ExitWorktree` 退出。
+- 使用 `ExitWorktree` 在会话中途离开。若会话结束时仍处于新建的 worktree 内，系统会提示用户保留还是移除。
+- 通过 `path` 进入的 worktree 被视为外部 worktree——带 `action: "remove"` 的 `ExitWorktree` 不会删除它们。这是保护用户手动管理的 worktree 的安全屏障。
+- 新建的 worktree 继承当前分支的内容，但拥有独立的工作目录和索引。主检出中已暂存或未暂存的改动在 worktree 中不可见。
+- 命名建议：以工作类型作前缀（`feat/`、`fix/`、`spike/`），让多个并发 worktree 在 `git worktree list` 中易于区分。

package/concepts/zh/Tool-ExitPlanMode.md

@@ -1,62 +1,42 @@
 # ExitPlanMode
 
-## 定义
+将计划模式期间起草的实施方案提交给用户审批，并——若获批准——让会话退出计划模式，以便开始编辑。
 
-退出规划模式并将方案提交给用户审批。方案内容从之前写入的计划文件中读取。
+## 何时使用
 
-## 参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `allowedPrompts` | array | 否 | 实施方案所需的权限描述列表 |
-
-`allowedPrompts` 数组中每个元素：
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `tool` | enum | 是 | 适用的工具，目前仅支持 `Bash` |
-| `prompt` | string | 是 | 操作的语义描述（如 "run tests"、"install dependencies"） |
-
-## 使用场景
+- 在 `EnterPlanMode` 中撰写的计划已完成并准备接受审阅。
+- 任务以实施为核心（代码或配置改动），而非纯粹的调研，因此需要明确的计划。
+- 所有前置阅读与分析已完成；在用户决定前无需进一步调研。
+- 助手已列出具体的文件路径、函数和步骤——而不只是目标。
+- 用户要求查看计划，或计划模式流程即将交接给编辑工具。
 
-**适合使用：**
-- 规划模式中方案已完成，准备提交用户审批
-- 仅用于需要编写代码的实施任务
-
-**不适合使用：**
-- 纯研究/探索任务——不需要退出规划模式
-- 想问用户"方案可以吗？"——这正是此工具的功能，不要用 AskUserQuestion 来问
-
-## 注意事项
+## 参数
 
-- 此工具不接受方案内容作为参数——它从之前写入的计划文件中读取
-- 用户会看到计划文件的内容来审批
-- 不要在调用此工具前用 AskUserQuestion 问"方案是否可以"，这是重复的
-- 不要在问题中提及"计划"，因为用户在 ExitPlanMode 之前看不到计划内容
+- `allowedPrompts` (array, 可选)：用户可在审批界面上输入的提示，用于自动批准或调整计划。每个元素指定一个带作用域的权限（例如操作名与适用的工具）。留空使用默认审批流。
 
-## 原文
+## 示例
 
-<textarea readonly>Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.
+### 示例 1：标准提交
 
-## How This Tool Works
-- You should have already written your plan to the plan file specified in the plan mode system message
-- This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote
-- This tool simply signals that you're done planning and ready for the user to review and approve
-- The user will see the contents of your plan file when they review it
+在计划模式中调研完认证重构并将计划文件写入磁盘后，助手无参数调用 `ExitPlanMode`。运行时从约定路径读取计划，展示给用户，等待审批或驳回。
 
-## When to Use This Tool
-IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.
+### 示例 2：预先批准的快速操作
 
-## Before Using This Tool
-Ensure your plan is complete and unambiguous:
-- If you have unresolved questions about requirements or approach, use AskUserQuestion first (in earlier phases)
-- Once your plan is finalized, use THIS tool to request approval
+```
+ExitPlanMode(allowedPrompts=[
+  {"tool": "Bash", "prompt": "run tests"},
+  {"tool": "Bash", "prompt": "install dependencies"}
+])
+```
 
-**Important:** Do NOT use AskUserQuestion to ask "Is this plan okay?" or "Should I proceed?" - that's exactly what THIS tool does. ExitPlanMode inherently requests user approval of your plan.
+让用户提前为例行后续命令授权，这样助手在实施期间就不必因每次权限弹窗而中断。
 
-## Examples
+## 注意事项
 
-1. Initial task: "Search for and understand the implementation of vim mode in the codebase" - Do not use the exit plan mode tool because you are not planning the implementation steps of a task.
-2. Initial task: "Help me implement yank mode for vim" - Use the exit plan mode tool after you have finished planning the implementation steps of the task.
-3. Initial task: "Add a new feature to handle user authentication" - If unsure about auth method (OAuth, JWT, etc.), use AskUserQuestion first, then use exit plan mode tool after clarifying the approach.
-</textarea>
+- `ExitPlanMode` 只适用于实施型工作。若用户请求的是调研或解释类任务，没有文件改动，请直接作答——不要仅仅为了退出而先走计划模式。
+- 计划必须已写入磁盘后再调用本工具。`ExitPlanMode` 不接受计划正文作为参数；它从运行时约定的路径读取。
+- 若用户驳回计划，你将回到计划模式。请根据反馈修订并再次提交；在计划获批之前不要开始编辑文件。
+- 审批授予你退出计划模式并使用变更类工具（`Edit`、`Write`、`Bash` 等）的权限，范围就是计划中描述的。事后扩大范围需要新的计划或用户明确同意。
+- 在调用本工具前，不要用 `AskUserQuestion` 询问「这个计划看起来如何？」——请求计划审批正是 `ExitPlanMode` 的职责，并且在提交之前用户看不到计划。
+- 计划要简短且可执行。审阅者应能在一分钟内扫完并完全理解将要发生什么改动。
+- 若在实施中途发现计划有误，请停下并向用户汇报，而不是默默偏离。重新进入计划模式是合理的下一步。

package/concepts/zh/Tool-ExitWorktree.md

@@ -0,0 +1,41 @@
+# ExitWorktree
+
+退出由 `EnterWorktree` 创建的 worktree 会话，并将会话返回到原始工作目录。此工具仅对当前会话中由 `EnterWorktree` 创建的 worktree 生效；如果没有活跃的此类会话，调用将为空操作。
+
+## 何时使用
+
+- 已完成隔离 worktree 中的工作，希望返回主工作目录。
+- 在功能分支 worktree 中完成任务并合并后，需要清理该分支和目录。
+- 希望保留 worktree 以便稍后继续使用，只需返回原始目录而不删除任何内容。
+- 希望放弃实验性或临时性分支，不在磁盘上保留任何产物。
+- 需要开启新的 `EnterWorktree` 会话，必须先退出当前会话。
+
+## 参数
+
+- `action`（字符串，必填）：`"keep"` 保留 worktree 目录和分支，以便之后返回；`"remove"` 删除 worktree 目录及其分支，执行干净退出。
+- `discard_changes`（布尔值，可选，默认 `false`）：仅在 `action` 为 `"remove"` 时有意义。若 worktree 存在未提交的文件或不在原始分支上的提交，工具将拒绝删除，除非将 `discard_changes` 设置为 `true`。错误响应会列出具体变更，以便在重新调用前与用户确认。
+
+## 示例
+
+### 示例 1：合并变更后的干净退出
+
+在 worktree 中完成工作并将分支合并到主分支后，使用 `action: "remove"` 调用 `ExitWorktree`，删除 worktree 目录和分支，并返回原始工作目录。
+
+```
+ExitWorktree(action: "remove")
+```
+
+### 示例 2：丢弃含有未提交实验代码的临时 worktree
+
+若 worktree 包含需要完全丢弃的实验性未提交变更，先尝试 `action: "remove"`。工具将拒绝并列出未提交的变更。在与用户确认可以丢弃后，再次调用并传入 `discard_changes: true`。
+
+```
+ExitWorktree(action: "remove", discard_changes: true)
+```
+
+## 注意事项
+
+- 此工具仅对当前会话中由 `EnterWorktree` 创建的 worktree 生效。它不会影响通过 `git worktree add` 创建的 worktree、之前会话的 worktree，或从未调用过 `EnterWorktree` 时的普通工作目录——这些情况下调用为空操作。
+- 若 worktree 存在未提交的变更或未合入原始分支的提交，`action: "remove"` 将拒绝执行，除非明确提供 `discard_changes: true`。设置此参数前务必与用户确认，因为数据一旦删除无法恢复。
+- 若 worktree 附有 tmux 会话：`remove` 时该会话会被终止；`keep` 时会话继续运行，并返回其名称以便用户之后重新连接。
+- `ExitWorktree` 完成后，可再次调用 `EnterWorktree` 开始新的 worktree 会话。

package/concepts/zh/Tool-Glob.md

@@ -1,39 +1,35 @@
 # Glob
 
-## 定义
+按 glob 模式匹配文件名，并按最近修改时间倒序返回路径。它针对任意规模的代码库都能快速定位文件，无需退化到 `find`。
 
-快速的文件名模式匹配工具，支持任意规模的代码库。返回按修改时间排序的匹配文件路径。
+## 何时使用
 
-## 参数
+- 枚举某个扩展名的所有文件（例如 `src` 下所有 `*.ts`）
+- 按命名约定发现配置或夹具文件（`**/jest.config.*`、`**/*.test.tsx`）
+- 在执行有针对性的 `Grep` 前收窄搜索面
+- 在调用 `Write` 前检查是否已存在符合模式的文件
+- 依赖修改时间排序，查找最近改动过的文件
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `pattern` | string | 是 | glob 模式（如 `**/*.js`、`src/**/*.ts`） |
-| `path` | string | 否 | 搜索目录，默认为当前工作目录。不要传 "undefined" 或 "null" |
+## 参数
 
-## 使用场景
+- `pattern` (string, 必填)：要匹配的 glob 表达式。支持 `*` 单段通配、`**` 递归匹配、`{a,b}` 多选，例如 `src/**/*.{ts,tsx}`。
+- `path` (string, 可选)：执行搜索的目录。提供时必须是有效目录路径。完全省略该字段即在当前工作目录搜索。不要传入字符串 `"undefined"` 或 `"null"`。
 
-**适合使用：**
-- 按文件名模式查找文件
-- 查找特定类型的所有文件（如所有 `.tsx` 文件）
-- 查找特定类定义（如 `class Foo`）时先定位文件
-- 可以在单条消息中并行发起多个 Glob 调用
+## 示例
 
-**不适合使用：**
-- 搜索文件内容——应使用 Grep
-- 需要多轮搜索的开放式探索——应使用 Task（Explore 类型）
+### 示例 1：每一个 TypeScript 源文件
+以 `pattern: "src/**/*.ts"` 调用 `Glob`。结果按修改时间排序，最近编辑过的文件排在前面，便于聚焦热点。
 
-## 注意事项
+### 示例 2：定位类定义候选
+当你怀疑某个类位于某个不确定名字的文件中时，使用 `pattern: "**/*UserService*"` 缩小候选范围，再用 `Read` 或 `Grep` 跟进。
 
-- 支持标准 glob 语法：`*` 匹配单层，`**` 匹配多层，`{}` 匹配多选
-- 结果按修改时间排序
-- 比 Bash 的 `find` 命令更推荐使用
+### 示例 3：更大任务前的并行发现
+在同一条消息中发起多个 `Glob` 调用（例如一个搜 `**/*.test.ts`、一个搜 `**/fixtures/**`），让它们并行执行，再将结果关联。
 
-## 原文
+## 注意事项
 
-<textarea readonly>- Fast file pattern matching tool that works with any codebase size
-- Supports glob patterns like "**/*.js" or "src/**/*.ts"
-- Returns matching file paths sorted by modification time
-- Use this tool when you need to find files by name patterns
-- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead
-- You can call multiple tools in a single response. It is always better to speculatively perform multiple searches in parallel if they are potentially useful.</textarea>
+- 结果按文件修改时间排序（最新优先），而非字母顺序。如需稳定排序，请在后续步骤中自行排序。
+- 模式由工具解析，而非 shell；你无需像在命令行那样加引号或转义。
+- 对于需要多轮搜索和推理的开放式探索，请委派给 `Agent` 并使用 Explore 代理类型，而不是串起很多次 `Glob`。
+- 在文件名发现上，优先使用 `Glob` 而非通过 `Bash` 调 `find` 或 `ls`；它处理权限更一致，返回结构化输出。
+- 若要查找文件内部的内容而非文件名，请改用 `Grep`。

package/concepts/zh/Tool-Grep.md

@@ -1,57 +1,46 @@
 # Grep
 
-## 定义
+基于 ripgrep 引擎搜索文件内容。提供完整的正则表达式支持、按文件类型过滤，以及三种输出模式，可在精确性与紧凑性之间权衡。
 
-基于 ripgrep 的强大内容搜索工具。支持正则表达式、文件类型过滤和多种输出模式。
+## 何时使用
+
+- 定位某函数的每一处调用点或某标识符的每一处引用
+- 检查字符串或错误消息是否出现在代码库的任何地方
+- 统计某模式出现次数，以在重构前评估影响
+- 将搜索缩小到某种文件类型（`type: "ts"`）或 glob（`glob: "**/*.tsx"`）
+- 使用 `multiline: true` 拉取跨行匹配，例如多行的结构定义或 JSX 块
 
 ## 参数
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `pattern` | string | 是 | 正则表达式搜索模式 |
-| `path` | string | 否 | 搜索路径（文件或目录），默认当前工作目录 |
-| `glob` | string | 否 | 文件名过滤（如 `*.js`、`*.{ts,tsx}`） |
-| `type` | string | 否 | 文件类型过滤（如 `js`、`py`、`rust`），比 glob 更高效 |
-| `output_mode` | enum | 否 | 输出模式：`files_with_matches`（默认）、`content`、`count` |
-| `-i` | boolean | 否 | 大小写不敏感搜索 |
-| `-n` | boolean | 否 | 显示行号（仅 content 模式），默认 true |
-| `-A` | number | 否 | 匹配后显示的行数 |
-| `-B` | number | 否 | 匹配前显示的行数 |
-| `-C` / `context` | number | 否 | 匹配前后显示的行数 |
-| `head_limit` | number | 否 | 限制输出条目数，默认 0（无限） |
-| `offset` | number | 否 | 跳过前 N 条结果 |
-| `multiline` | boolean | 否 | 启用多行匹配模式，默认 false |
-
-## 使用场景
-
-**适合使用：**
-- 在代码库中搜索特定字符串或模式
-- 查找函数/变量的使用位置
-- 按文件类型过滤搜索结果
-- 统计匹配数量
-
-**不适合使用：**
-- 按文件名查找文件——应使用 Glob
-- 需要多轮搜索的开放式探索——应使用 Task（Explore 类型）
+- `pattern` (string, 必填)：要搜索的正则表达式。使用 ripgrep 语法，因此字面花括号需转义（例如用 `interface\{\}` 查找 `interface{}`）。
+- `path` (string, 可选)：要搜索的文件或目录。默认为当前工作目录。
+- `glob` (string, 可选)：文件名过滤，例如 `*.js` 或 `*.{ts,tsx}`。
+- `type` (string, 可选)：文件类型快捷方式，如 `js`、`py`、`rust`、`go`。对标准语言比 `glob` 更高效。
+- `output_mode` (enum, 可选)：`files_with_matches`（默认，只返回路径）、`content`（返回匹配行）或 `count`（返回计数）。
+- `-i` (boolean, 可选)：不区分大小写匹配。
+- `-n` (boolean, 可选)：在 `content` 模式下包含行号。默认为 `true`。
+- `-A` (number, 可选)：每个匹配之后显示的上下文行数（需 `content` 模式）。
+- `-B` (number, 可选)：每个匹配之前的上下文行数（需 `content` 模式）。
+- `-C` / `context` (number, 可选)：匹配两侧的上下文行数。
+- `multiline` (boolean, 可选)：允许模式跨换行（`.` 匹配 `\n`）。默认为 `false`。
+- `head_limit` (number, 可选)：限制返回的行数、文件路径或计数条目。默认 250；传 `0` 为不限制（谨慎使用）。
+- `offset` (number, 可选)：在应用 `head_limit` 之前跳过前 N 条结果。默认 `0`。
+
+## 示例
+
+### 示例 1：找到某函数的所有调用点
+设 `pattern: "registerHandler\\("`、`output_mode: "content"`、`-C: 2`，查看每次调用周围的上下文。
+
+### 示例 2：按类型统计匹配数
+设 `pattern: "TODO"`、`type: "py"`、`output_mode: "count"`，查看所有 Python 源码的每文件 TODO 汇总。
+
+### 示例 3：多行结构匹配
+使用 `pattern: "struct Config \\{[\\s\\S]*?version"` 搭配 `multiline: true`，捕获 Go 结构体中声明在数行之后的字段。
 
 ## 注意事项
 
-- 使用 ripgrep 语法（非 grep），花括号等特殊字符需要转义
-- `files_with_matches` 模式只返回文件路径，最高效
-- `content` 模式返回匹配行内容，支持上下文行
-- 多行匹配需要设置 `multiline: true`
-- 始终优先使用 Grep 工具而非 Bash 中的 `grep` 或 `rg` 命令
-
-## 原文
-
-<textarea readonly>A powerful search tool built on ripgrep
-
-  Usage:
-  - ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.
-  - Supports full regex syntax (e.g., "log.*Error", "function\s+\w+")
-  - Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
-  - Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts
-  - Use Agent tool for open-ended searches requiring multiple rounds
-  - Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\{\}` to find `interface{}` in Go code)
-  - Multiline matching: By default patterns match within single lines only. For cross-line patterns like `struct \{[\s\S]*?field`, use `multiline: true`
-</textarea>
+- 始终优先使用 `Grep` 而不是通过 `Bash` 调 `grep` 或 `rg`；本工具已针对权限处理和结构化输出做了优化。
+- 默认输出模式 `files_with_matches` 最节省。仅当你需要看到具体行时才切到 `content`。
+- 上下文标志（`-A`、`-B`、`-C`）仅在 `output_mode` 为 `content` 时生效，否则会被忽略。
+- 大结果集会消耗上下文 token。使用 `head_limit`、`offset` 或更紧的 `glob`/`type` 过滤保持聚焦。
+- 对于文件名发现，请使用 `Glob`；对于需要多轮的开放式调查，请派发 `Agent` 并使用 Explore 代理。

package/concepts/zh/Tool-Monitor.md

@@ -0,0 +1,50 @@
+# Monitor
+
+启动一个后台监视器，从长时间运行的脚本中实时推送事件。每一行标准输出都会成为一条通知——继续工作，事件会实时出现在对话中。
+
+## 何时使用
+
+- 在部署运行期间，持续追踪日志文件中的错误、警告或崩溃特征
+- 每隔 30 秒轮询远程 API、PR 或 CI 流水线，获取最新状态事件
+- 实时监视文件系统目录或构建输出的变化
+- 在多次迭代中等待特定条件（例如训练步骤里程碑或队列清空）
+- **不适用于**简单的"等待完成"场景——请改用带 `run_in_background` 的 `Bash`，它会在进程退出时发送一次完成通知
+
+## 参数
+
+- `command`（字符串，必填）：要运行的 shell 命令或脚本。写入标准输出的每一行都会成为独立的通知事件。进程退出后监视器结束。
+- `description`（字符串，必填）：在每条通知中显示的简短可读标签。请尽量具体——"deploy.log 中的错误"比"监视日志"更清晰。此标签用于识别触发通知的监视器。
+- `timeout_ms`（数字，默认 `300000`，最大 `3600000`）：终止时限（毫秒）。超过此时长后进程将被强制终止。当 `persistent: true` 时此参数无效。
+- `persistent`（布尔值，默认 `false`）：设为 `true` 时，监视器在整个会话期间持续运行，不受超时限制。可通过 `TaskStop` 显式停止。
+
+## 示例
+
+### 示例 1：追踪日志文件中的错误和崩溃
+
+此示例覆盖所有终止状态：成功标记、回溯信息、常见错误关键词、OOM 终止以及意外进程退出。
+
+```bash
+tail -F /var/log/deploy.log | grep -E --line-buffered \
+  "deployed|Traceback|Error|FAILED|assert|Killed|OOM"
+```
+
+每个管道中都必须使用 `grep --line-buffered`。若不使用，操作系统会以 4 KB 块为单位缓冲输出，事件可能延迟数分钟。交替匹配模式同时覆盖成功路径（`deployed`）和失败路径（`Traceback`、`Error`、`FAILED`、`Killed`、`OOM`）。只监视成功标记的监视器在崩溃时会保持静默——静默与"仍在运行"无法区分。
+
+### 示例 2：每 30 秒轮询一次远程 API
+
+```bash
+while true; do
+  curl -sf "https://api.example.com/status" || true
+  sleep 30
+done | grep --line-buffered -E "completed|failed|error"
+```
+
+`|| true` 防止偶发的网络故障中断循环。远程 API 建议采用 30 秒以上的轮询间隔，以避免触发频率限制。调整 grep 模式，同时捕获成功和失败响应，避免 API 侧错误被静默掩盖。
+
+## 注意事项
+
+- **管道中必须始终使用 `grep --line-buffered`。** 若不使用，管道缓冲会将事件延迟数分钟，因为操作系统会累积输出直到填满 4 KB 块。`--line-buffered` 强制在每行后刷新缓冲。
+- **过滤器必须同时覆盖成功和失败特征。** 只监视成功标记的监视器在崩溃、挂起或意外退出时会保持静默。扩大匹配范围：在成功关键词之外，还应包含 `Error`、`Traceback`、`FAILED`、`Killed`、`OOM` 等终止状态标记。
+- **远程 API 的轮询间隔不少于 30 秒。** 对外部服务进行高频轮询可能触发频率限制或封禁。对于本地文件系统或进程检查，0.5–1 秒的间隔是合适的。
+- **对于会话级长期监视，使用 `persistent: true`。** 默认 `timeout_ms` 为 300 000 毫秒（5 分钟），超时后进程会被终止。若希望监视器持续运行直至手动停止，请设置 `persistent: true`，并在完成后调用 `TaskStop`。
+- **事件过多时自动停止。** 每行标准输出都是一条对话消息。如果过滤器太宽泛、产生过多事件，监视器会被自动停止。请使用更精确的 `grep` 模式重新启动。200 毫秒内到达的多行会合并为一条通知。