docs: mintlify 文档撰写

docs/tools/file-operations.mdx

@@ -0,0 +1,54 @@
+---
+title: "文件操作"
+description: "AI 如何安全、高效地读写你的代码"
+---
+
+{/* 本章目标：介绍文件类工具的设计理念 */}
+
+## 读、写、改——三种操作模式
+
+Claude Code 把文件操作拆分为三个独立工具，而不是一个万能的"文件工具"：
+
+| 工具 | 功能 | 设计考量 |
+|------|------|---------|
+| **Read** | 读取文件内容 | 只读操作，权限最低，AI 可以随意使用 |
+| **Write** | 创建新文件或完全重写 | 高风险操作，需要确认 |
+| **Edit** | 精确替换文件中的特定片段 | 中等风险，但比 Write 安全——只改你指定的部分 |
+
+<Tip>
+为什么 Edit 和 Write 要分开？因为"编辑一行"和"重写整个文件"的风险完全不同。分离后，权限系统可以对它们施加不同的控制策略。
+</Tip>
+
+## 文件读取的智慧
+
+Read 工具不是简单的 `cat` 命令，它有很多精细的设计：
+
+- **分页读取**：超大文件不会一次性全部读入，支持 offset + limit 指定范围
+- **多格式支持**：除了文本文件，还能读取图片（多模态展示）、PDF、Jupyter Notebook
+- **文件状态缓存**：记住已读过的文件内容，避免重复读取浪费 token
+- **Token 感知**：文件内容计入 token 预算，系统会自动评估是否"读得起"
+
+## 精确编辑 vs 全量重写
+
+Edit 工具的核心设计是**精确字符串替换**：
+
+- AI 指定 `old_string`（要被替换的原文）和 `new_string`（替换后的新文）
+- 系统确保 `old_string` 在文件中**唯一匹配**——如果匹配到多处或零处，操作失败
+- 这个设计确保 AI 不会"改错地方"
+
+## 搜索与导航
+
+在动手修改之前，AI 通常需要先"找到目标"。两个搜索工具分工明确：
+
+- **Glob**：按文件名模式搜索（"找到所有 `.ts` 文件"），替代 `find` 命令
+- **Grep**：按文件内容搜索（"找到所有包含 `TODO` 的行"），替代 `grep/rg` 命令
+
+两者都经过优化，能在大型项目中快速返回结果，并自动截断过长的输出。
+
+## 文件历史快照
+
+每当 AI 准备修改文件时，系统会自动保存一份快照。这意味着：
+
+- 用户可以随时回滚到 AI 修改前的状态
+- 即使 AI 做了错误的编辑，原始内容不会丢失
+- 快照与 git 互补——git 追踪已提交的变更，快照保护未提交的工作

docs/tools/search-and-navigation.mdx

@@ -0,0 +1,43 @@
+---
+title: "搜索与导航"
+description: "AI 如何在百万行代码中精准定位目标"
+---
+
+{/* 本章目标：介绍搜索类工具和工具搜索机制 */}
+
+## 两种搜索维度
+
+| 维度 | 工具 | 适用场景 |
+|------|------|---------|
+| **按名称找文件** | Glob | "找到所有测试文件"、"找 config 开头的文件" |
+| **按内容找代码** | Grep | "哪里定义了这个函数"、"谁在调用这个 API" |
+
+两者组合使用，AI 就拥有了在大型项目中"导航"的能力。
+
+## 搜索结果的智能处理
+
+大型项目的搜索结果可能有成千上万条，直接全部返回不现实：
+
+- **结果数量限制**：默认最多返回 250 条匹配
+- **上下文行**：Grep 支持显示匹配行前后的上下文（类似 `grep -C`）
+- **按修改时间排序**：Glob 默认把最近修改的文件排在前面
+- **文件类型过滤**：按语言类型过滤（只搜 `.ts` 文件、只搜 `.py` 文件）
+
+## 工具发现机制
+
+当可用工具超过 50 个时，AI 可能不知道该用哪个。系统提供了 **ToolSearch** 机制：
+
+- AI 可以用自然语言描述需求（"我需要连接数据库"）
+- 系统在所有已注册工具（包括 MCP 提供的）中搜索匹配
+- 返回最相关的工具列表及使用说明
+
+这让 AI 在面对庞大的工具库时不会迷路。
+
+## Web 搜索与抓取
+
+AI 的信息获取不局限于本地代码：
+
+- **WebSearch**：搜索互联网获取最新信息
+- **WebFetch**：抓取特定网页内容，转换为 Markdown 供 AI 阅读
+
+这让 AI 可以查阅文档、搜索 Stack Overflow、阅读 GitHub issue——和人类开发者的工作方式一致。

docs/tools/shell-execution.mdx

@@ -0,0 +1,53 @@
+---
+title: "命令执行"
+description: "让 AI 在你的终端里运行命令——安全地"
+---
+
+{/* 本章目标：介绍 Bash 工具的能力与安全设计 */}
+
+## AI 能执行命令意味着什么
+
+这是 Claude Code 最强大也最敏感的能力。AI 可以：
+
+- 运行构建命令（`npm run build`、`cargo build`）
+- 执行测试（`pytest`、`jest`）
+- 使用 git（`git status`、`git commit`）
+- 调用系统工具（`curl`、`docker`、`kubectl`）
+
+几乎你在终端里能做的事，AI 都能做。
+
+## 安全设计
+
+强大的能力需要严格的控制：
+
+<AccordionGroup>
+  <Accordion title="权限确认">
+    默认情况下，每条命令执行前都需要用户手动确认。用户可以设置白名单规则，让特定命令自动放行。
+  </Accordion>
+  <Accordion title="沙箱隔离">
+    在支持的平台上，命令可以运行在沙箱环境中——限制文件系统访问范围、禁止网络请求、阻止危险操作。
+  </Accordion>
+  <Accordion title="超时控制">
+    每条命令都有超时限制（默认 2 分钟，最长 10 分钟），防止 AI 启动一个永远不会结束的进程。
+  </Accordion>
+  <Accordion title="输出截断">
+    命令输出过长时自动截断，避免把海量日志全部塞进 AI 的上下文。
+  </Accordion>
+</AccordionGroup>
+
+## 前台与后台
+
+有些命令需要等待结果（比如 `git status`），有些适合在后台运行（比如 `npm install`）：
+
+- **前台执行**：AI 等待命令完成，拿到输出后继续思考
+- **后台执行**：命令在后台运行，AI 可以继续做其他事，稍后再检查结果
+
+## 为什么用专用工具而不是直接调 shell
+
+<Note>
+Claude Code 为文件读写、代码搜索等操作提供了专用工具（Read、Grep、Glob），而不是让 AI 用 `cat`、`grep` 等 shell 命令。原因有三：
+</Note>
+
+1. **权限粒度更细**：`Read` 是只读操作可以自动放行，但 `Bash: cat file` 需要审批整条命令
+2. **输出结构化**：专用工具的返回值是结构化的，方便 UI 渲染（高亮、diff 视图等）
+3. **性能优化**：专用工具可以做缓存、分页、token 预算控制，shell 命令做不到

docs/tools/task-management.mdx

@@ -0,0 +1,50 @@
+---
+title: "任务管理"
+description: "让 AI 的工作有条理、可追踪"
+---
+
+{/* 本章目标：介绍任务系统如何帮助 AI 和用户保持同步 */}
+
+## 为什么需要任务管理
+
+当你给 AI 一个复杂需求（比如"重构整个认证模块"），它可能需要执行几十个步骤。没有任务管理，用户只能被动等待，不知道 AI 做到哪了、还要做什么。
+
+## 任务系统的运作方式
+
+AI 可以自主创建和管理任务列表：
+
+<Steps>
+  <Step title="分解任务">
+    AI 把大需求拆解为多个小任务，创建到任务列表
+  </Step>
+  <Step title="标记进度">
+    开始某个任务时标记为"进行中"，完成后标记为"已完成"
+  </Step>
+  <Step title="依赖管理">
+    任务之间可以设定依赖关系——"任务 B 必须等任务 A 完成后才能开始"
+  </Step>
+  <Step title="用户可见">
+    用户随时可以查看任务列表，了解整体进度
+  </Step>
+</Steps>
+
+## 任务与 Plan Mode 的配合
+
+面对复杂任务，AI 可以先进入**计划模式**：
+
+1. AI 进入计划模式 → 只允许使用搜索和阅读类工具（不能修改文件）
+2. AI 探索代码库、理解现有架构
+3. AI 制定实施计划，创建任务列表
+4. 用户审批计划
+5. AI 退出计划模式，按计划逐项执行
+
+这种"先规划、后执行"的方式避免了 AI 盲目行动造成的返工。
+
+## 状态展示
+
+终端 UI 中，任务列表会实时更新：
+
+- 待办任务灰色显示
+- 进行中的任务有旋转动画
+- 已完成的任务打勾标记
+- 被阻塞的任务标注依赖项

docs/tools/what-are-tools.mdx

@@ -0,0 +1,74 @@
+---
+title: "工具：AI 的双手"
+description: "理解 Tool 这个核心抽象——AI 是怎么从'说'变成'做'的"
+---
+
+{/* 本章目标：让读者理解 Tool 抽象的设计思想 */}
+
+## AI 为什么需要工具
+
+大语言模型本质上只能做一件事：**根据输入文本，生成输出文本**。
+
+它不能读文件、不能执行命令、不能搜索代码。要让 AI 真正"动手"，需要一个桥梁——这就是 **Tool**（工具）。
+
+工具是 AI 的双手。AI 说"我想读这个文件"，工具系统替它真正去读；AI 说"我想执行这条命令"，工具系统替它真正去跑。
+
+## 一个工具长什么样
+
+每个工具都是一个标准化的"能力单元"，包含四个要素：
+
+| 要素 | 说明 | 示例（FileRead 工具） |
+|------|------|----------------------|
+| **名称** | 工具的唯一标识 | `Read` |
+| **描述** | 告诉 AI 这个工具能做什么（AI 据此决定是否使用） | "读取本地文件系统中的文件" |
+| **参数定义** | 工具接受什么输入 | `file_path`（必填）、`offset`、`limit` |
+| **执行逻辑** | 工具被调用时实际做什么 | 读取文件内容并返回 |
+
+## AI 如何选择工具
+
+AI 不是从下拉菜单里选工具——它是根据**工具描述**和**当前任务**自主决策的：
+
+1. 系统把所有可用工具的名称、描述、参数告诉 AI
+2. AI 在思考过程中决定"我需要用某个工具"
+3. AI 生成一个结构化的工具调用请求（工具名 + 参数）
+4. 系统执行工具，将结果返回给 AI
+
+<Note>
+工具描述的质量直接影响 AI 的决策准确性。一段好的描述不仅说明"能做什么"，还说明"什么时候该用、什么时候不该用"。
+</Note>
+
+## 50+ 内置工具
+
+Claude Code 内置了覆盖软件开发全流程的工具集：
+
+<CardGroup cols={3}>
+  <Card title="文件操作" icon="file">
+    Read / Write / Edit / Glob / Grep / NotebookEdit
+  </Card>
+  <Card title="命令执行" icon="terminal">
+    Bash / PowerShell
+  </Card>
+  <Card title="对话管理" icon="comments">
+    Agent / SendMessage / AskUserQuestion
+  </Card>
+  <Card title="任务追踪" icon="list-check">
+    TaskCreate / TaskUpdate / TaskList / TaskGet
+  </Card>
+  <Card title="Web 能力" icon="globe">
+    WebFetch / WebSearch
+  </Card>
+  <Card title="规划与版本" icon="map">
+    EnterPlanMode / Worktree / TodoWrite
+  </Card>
+</CardGroup>
+
+## 工具的可视化渲染
+
+工具不仅能"做事"，还能"展示"。每个工具可以定义自己的 UI 渲染方式：
+
+- **FileEdit** → 在终端里展示语法高亮的 diff 视图
+- **Bash** → 实时显示命令输出，带进度指示
+- **Grep** → 高亮匹配结果，显示文件路径和行号链接
+- **Agent** → 显示子 Agent 的进度条和状态
+
+这让用户能直观地看到"AI 在做什么、做到哪了"。