docs: mintlify 文档撰写

2026-06-18 06:15:51 +00:00 · 2026-04-01 09:16:41 +08:00
parent 722d59b6d5
commit f6fe94463e
27 changed files with 1542 additions and 0 deletions
--- a/docs/extensibility/custom-agents.mdx
+++ b/docs/extensibility/custom-agents.mdx
@@ -0,0 +1,56 @@
+---
+title: "自定义 Agent"
+description: "定义你自己的 AI 角色——不同的人格、能力和边界"
+---
+
+{/* 本章目标：解释自定义 Agent 定义的设计 */}
+
+## 为什么需要自定义 Agent
+
+默认的 Claude Code 是一个"全能型"助手。但有些场景需要更专门化的角色：
+
+- 一个只负责代码审查、不会修改代码的 Agent
+- 一个专门处理 DevOps 任务的 Agent
+- 一个面向初学者、回答更详细的 Agent
+
+## Agent 定义
+
+自定义 Agent 通过 Markdown 文件定义，放在 `.claude/agents/` 目录：
+
+| 配置项 | 说明 |
+|--------|------|
+| **名称** | Agent 的标识和显示名 |
+| **描述** | 这个 Agent 的职责说明 |
+| **System Prompt** | 自定义的角色指令——替换或追加到默认 System Prompt |
+| **允许的工具** | 这个 Agent 可以使用哪些工具 |
+| **模型** | 使用哪个 AI 模型 |
+
+## 与子 Agent 的关系
+
+自定义 Agent 可以作为子 Agent 被启动：
+
+- 主 Agent 说"这个任务需要安全审查"
+- 系统启动一个自定义的"安全审查 Agent"
+- 该 Agent 只有阅读权限，使用专门的安全审查 Prompt
+
+这实现了**角色分离**——不同的任务由不同"人格"的 Agent 处理。
+
+## 复用与共享
+
+<CardGroup cols={2}>
+  <Card title="项目级" icon="folder">
+    放在项目的 `.claude/agents/` 目录，团队所有人可用
+  </Card>
+  <Card title="用户级" icon="user">
+    放在 `~/.claude/agents/` 目录，跨项目可用
+  </Card>
+</CardGroup>
+
+## 实际应用
+
+| Agent | 角色 | 工具限制 |
+|-------|------|---------|
+| `reviewer` | 代码审查员 | 只允许 Read、Glob、Grep |
+| `devops` | DevOps 工程师 | 允许 Bash，限制在 infra/ 目录 |
+| `tutor` | 编程导师 | 全部工具，但 Prompt 强调教学 |
+| `security` | 安全审计员 | 只允许搜索和阅读，输出安全报告 |
--- a/docs/extensibility/hooks.mdx
+++ b/docs/extensibility/hooks.mdx
@@ -0,0 +1,72 @@
+---
+title: "Hooks：生命周期钩子"
+description: "在 AI 的关键行为节点插入你自己的逻辑"
+---
+
+{/* 本章目标：解释 Hooks 系统的设计和应用场景 */}
+
+## 什么是 Hooks
+
+Hooks 是用户定义的 shell 命令，在 Claude Code 生命周期的特定时刻自动执行。
+
+类比：React 的 `useEffect` 让你在组件渲染后执行自定义逻辑。Claude Code 的 Hooks 让你在 AI 的关键行为前后执行自定义脚本。
+
+## 可用的 Hook 事件
+
+| 事件 | 触发时机 | 典型用途 |
+|------|---------|---------|
+| **PreToolUse** | 工具调用前 | 拦截危险操作、自定义审批逻辑 |
+| **PostToolUse** | 工具调用后 | 记录日志、触发通知、自动格式化 |
+| **PreCompact** | 上下文压缩前 | 标记不可丢失的信息 |
+| **PostCompact** | 上下文压缩后 | 验证关键信息是否保留 |
+| **Notification** | AI 发出通知时 | 自定义通知渠道（Slack、邮件等） |
+| **StopFailure** | AI 循环异常停止时 | 自定义错误处理 |
+
+## Hook 的能力
+
+Hook 脚本不仅能"观察"，还能"干预"：
+
+<CardGroup cols={2}>
+  <Card title="拦截操作" icon="hand">
+    返回特定信号可以阻止工具调用执行
+  </Card>
+  <Card title="修改行为" icon="pen">
+    返回结构化的 JSON 输出，影响 Claude Code 的后续行为
+  </Card>
+  <Card title="注入上下文" icon="syringe">
+    向 AI 的对话中注入额外信息
+  </Card>
+  <Card title="触发外部流程" icon="bolt">
+    调用 CI/CD、发送通知、更新 Issue tracker
+  </Card>
+</CardGroup>
+
+## 配置方式
+
+Hooks 在 `settings.json` 中配置：
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": { "tool_name": "Write" },
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx prettier --write $CLAUDE_FILE_PATH"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+这个例子：每当 AI 写入一个文件后，自动用 Prettier 格式化。
+
+## 安全控制
+
+- 托管设置（企业管理员）的 Hooks 优先级最高，用户不能覆盖
+- Hook 执行有超时限制
+- Hook 的输出会被解析和验证，防止注入攻击
--- a/docs/extensibility/mcp-protocol.mdx
+++ b/docs/extensibility/mcp-protocol.mdx
@@ -0,0 +1,75 @@
+---
+title: "MCP：开放的工具生态"
+description: "通过标准协议对接任何外部能力——数据库、API、自定义服务"
+---
+
+{/* 本章目标：解释 MCP 协议如何扩展 AI 的能力边界 */}
+
+## 内置工具的局限
+
+Claude Code 内置了 50+ 工具，覆盖了通用的软件开发需求。但每个团队都有特殊需求：
+
+- 连接内部数据库查询数据
+- 调用公司内部 API
+- 操作特定的 DevOps 工具
+- 访问私有的知识库
+
+不可能把所有人的需求都内置进去。
+
+## MCP：一个标准的"插头"
+
+**Model Context Protocol**（模型上下文协议）是 Anthropic 提出的开放标准，定义了 AI 与外部工具之间的通信方式。
+
+类比：USB 是电脑连接外设的标准接口。MCP 是 AI 连接外部能力的标准接口。
+
+## 工作原理
+
+<Steps>
+  <Step title="启动 MCP Server">
+    开发者编写一个 MCP Server，暴露自定义工具（比如"查询数据库"、"发送 Slack 消息"）
+  </Step>
+  <Step title="Claude Code 连接">
+    在配置文件中声明要连接的 MCP Server
+  </Step>
+  <Step title="工具自动发现">
+    连接后，MCP Server 提供的工具自动出现在 AI 的可用工具列表中
+  </Step>
+  <Step title="透明调用">
+    AI 像使用内置工具一样使用 MCP 工具——无需知道底层实现
+  </Step>
+</Steps>
+
+## 三种连接方式
+
+| 方式 | 适用场景 |
+|------|---------|
+| **stdio** | MCP Server 作为子进程运行，通过标准输入/输出通信。最简单 |
+| **SSE** | 通过 HTTP Server-Sent Events 通信。适合远程服务 |
+| **StreamableHTTP** | 基于 HTTP 流的双向通信。适合复杂的交互场景 |
+
+## 权限一视同仁
+
+MCP 提供的工具和内置工具一样受权限系统管控：
+
+- 需要用户确认才能调用
+- 可以设置 allow/deny 规则
+- 支持沙箱限制
+
+这确保了第三方工具不会绕过安全边界。
+
+## 实际例子
+
+```json
+// settings.json 中的 MCP 配置
+{
+  "mcpServers": {
+    "my-database": {
+      "command": "npx",
+      "args": ["@my-org/db-mcp-server"],
+      "env": { "DB_URL": "postgres://..." }
+    }
+  }
+}
+```
+
+配置后，AI 就多了"查询数据库"这个能力——用自然语言描述需求，AI 自动生成查询并执行。
--- a/docs/extensibility/skills.mdx
+++ b/docs/extensibility/skills.mdx
@@ -0,0 +1,60 @@
+---
+title: "Skills：预制的能力包"
+description: "把常用的工作流封装成可复用的技能"
+---
+
+{/* 本章目标：解释 Skills 系统的设计思想 */}
+
+## Tool vs Skill
+
+| | Tool | Skill |
+|---|---|---|
+| 粒度 | 单个原子操作（读文件、执行命令） | 一套完整的工作流（代码审查、创建 PR） |
+| 触发方式 | AI 自主选择 | 用户主动调用（`/skill-name`）或 AI 根据场景推荐 |
+| 本质 | 执行逻辑 | 预制的 Prompt + 工具权限配置 |
+
+## Skill 的三个来源
+
+<CardGroup cols={3}>
+  <Card title="内置 Skill" icon="box">
+    编译进 CLI 的技能包。如 `/commit`、`/review`、`/debug`
+  </Card>
+  <Card title="项目 Skill" icon="folder-open">
+    项目 `.claude/skills/` 目录中的 Markdown 文件。团队共享
+  </Card>
+  <Card title="MCP Skill" icon="plug">
+    通过 MCP Server 提供的技能。动态发现
+  </Card>
+</CardGroup>
+
+## 一个 Skill 包含什么
+
+每个 Skill 本质上是一个"AI 行为的预设"：
+
+| 组成部分 | 作用 |
+|----------|------|
+| **名称和描述** | 告诉 AI 和用户这个技能做什么 |
+| **whenToUse** | 什么场景下应该使用这个技能（AI 据此自动推荐） |
+| **Prompt 模板** | 注入给 AI 的详细指令——相当于"操作手册" |
+| **allowedTools** | 这个技能允许使用哪些工具（能力边界） |
+| **model** | 可选指定使用的模型 |
+
+## 设计精妙之处
+
+Skill 的核心洞见是：**很多复杂任务的关键不在于代码逻辑，而在于 Prompt 的质量**。
+
+一个好的代码审查，不是写了什么代码来审查，而是：
+- 告诉 AI 审查的标准是什么
+- 告诉 AI 按什么顺序审查
+- 告诉 AI 输出什么格式的报告
+- 限制 AI 只能用读取类工具（不要边审查边改代码）
+
+Skill 把这些"经验"封装起来，任何人都能一键调用。
+
+## 技能发现
+
+当可用技能很多时，AI 可以通过 **SkillTool** 搜索匹配的技能：
+
+- 用户说"帮我做代码审查"
+- AI 搜索已注册的技能，发现 `code-review` 匹配
+- AI 调用该技能，按预设的流程执行