# https://github.com/anthropics/claude-code 项目说明书

生成时间：2026-05-31 03:34:00 UTC

## 目录

- [项目概览](#overview)
- [安装指南](#installation)
- [快速上手](#quickstart)
- [斜杠命令系统](#slash-commands)
- [Agent 代理系统](#agents-system)
- [Hooks 钩子系统](#hooks-events)
- [插件系统架构](#plugin-system)
- [官方插件详解](#official-plugins)
- [设置与配置管理](#settings-management)
- [企业托管设置](#managed-settings)

<a id='overview'></a>

## 项目概览

### 相关页面

相关主题：[安装指南](#installation), [快速上手](#quickstart)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/anthropics/claude-code/blob/main/README.md)
- [CHANGELOG.md](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
- [plugins/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)
- [plugins/feature-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/feature-dev/README.md)
- [plugins/plugin-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)
- [plugins/hookify/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/README.md)
- [plugins/code-review/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/code-review/README.md)
</details>

# 项目概览

Claude Code 是 Anthropic 公司开发的命令行工具，为开发者提供 AI 辅助编程能力。通过自然语言交互，开发者可以在终端中完成代码编写、调试、代码审查、功能开发等任务。

## 核心定位

Claude Code 定位为**开发者的智能编程伙伴**，而非简单的代码补全工具。它具备以下核心能力：

| 能力类别 | 具体功能 |
|---------|---------|
| 代码理解 | 深度理解代码库结构、架构和模式 |
| 任务执行 | 读取文件、编写代码、执行命令、创建项目 |
| 代码审查 | 自动检查代码质量、错误处理、测试覆盖 |
| 工作流程 | 支持 7 阶段结构化开发流程 |
| 插件扩展 | 通过插件系统自定义功能和工作流 |

最新版本为 **v2.1.158**，已在 Bedrock、Vertex 和 Foundry 平台为 Opus 4.7 和 Opus 4.8 提供 Auto mode 支持。

## 插件架构

Claude Code 采用模块化插件架构，允许开发者扩展核心功能。插件系统包含以下组件类型：

### 组件类型概览

| 组件类型 | 用途 | 文件位置 |
|---------|------|---------|
| Skills（技能） | 提供专业知识和工作流指导 | `skills/*.md` |
| Commands（命令） | 用户可调用的斜杠命令 | `commands/*.md` |
| Agents（代理） | 自主执行复杂任务的子 AI | `agents/*.md` |
| Hooks（钩子） | 事件驱动的自动化触发 | `hooks/hooks.json` |
| MCP | 外部服务集成 | `*.mcp.json` |
| Settings | 用户配置管理 | `README.md` |

### 插件结构示例

```mermaid
graph TD
    A[插件根目录] --> B[commands/]
    A --> C[skills/]
    A --> D[agents/]
    A --> E[hooks/]
    A --> F[MCP配置]
    A --> G[README.md]
    
    B --> B1[.md 命令文件]
    C --> C1[SKILL.md]
    C --> C2[references/]
    C --> C3[examples/]
    D --> D1[agent markdown]
```

## 内置插件

Claude Code 仓库包含多个官方插件，位于 `plugins/` 目录下：

| 插件名称 | 功能描述 | 主要命令/组件 |
|---------|---------|--------------|
| `feature-dev` | 结构化功能开发工作流 | `/feature-dev` - 7 阶段开发流程 |
| `plugin-dev` | 插件开发框架 | 多个技能和命令 |
| `code-review` | 自动化代码审查 | `/code-review` |
| `hookify` | 自定义钩子创建 | `/hookify` |
| `pr-review-toolkit` | PR 审查工具集 | 6 个专业审查代理 |
| `ralph-wiggum` | 迭代开发循环 | `/ralph-loop` |
| `security-guidance` | 安全问题提醒 | PreToolUse 钩子 |

## 功能开发工作流

`feature-dev` 插件实现了标准化的 7 阶段开发流程：

```mermaid
graph LR
    A[Phase 1: Discovery<br/>理解需求] --> B[Phase 2: Exploration<br/>代码库探索]
    B --> C[Phase 3: Questions<br/>澄清问题]
    C --> D[Phase 4: Design<br/>架构设计]
    D --> E[Phase 5: Implementation<br/>实现]
    E --> F[Phase 6: Validation<br/>验证检查]
    F --> G[Phase 7: Documentation<br/>文档完善]
```

每个阶段都有明确的目标和交付物，确保功能开发的完整性和质量。

## 插件开发框架

`plugin-dev` 是官方提供的插件开发框架，包含以下开发技能：

| 技能名称 | 触发关键词 | 用途 |
|---------|-----------|------|
| `plugin-structure` | "插件目录结构"、"plugin structure" | 指导插件组织方式 |
| `hook-development` | "创建钩子"、"hook development" | 事件钩子开发 |
| `mcp-integration` | "MCP 集成"、"MCP server" | 外部服务集成 |
| `command-development` | "创建斜杠命令"、"command development" | 命令开发 |
| `agent-development` | "创建代理"、"agent development" | 子代理开发 |
| `skill-development` | "创建技能"、"skill development" | 技能开发 |
| `plugin-settings` | "插件设置"、"settings management" | 配置管理 |

## 钩子系统

Claude Code 支持事件驱动的钩子机制，主要类型包括：

| 钩子类型 | 触发时机 | 常见用途 |
|---------|---------|---------|
| `PreToolUse` | 工具执行前 | 验证、安全检查 |
| `Stop` | 退出尝试时 | 阻止意外关闭 |
| `PostToolUse` | 工具执行后 | 通知、日志 |

钩子配置通过 `hooks/hooks.json` 管理，支持提示词模式和脚本模式。

## 代码审查功能

内置的代码审查功能包括：

- **CLAUDE.md 合规检查**：验证代码是否符合项目规范
- **测试覆盖分析**：检查测试用例完整性
- **静默失败检测**：识别 catch 块中的问题
- **类型设计审查**：评估 TypeScript 类型使用
- **代码简化建议**：识别可优化代码

## 安装与使用

### 全局安装

```bash
npm install -g @anthropic-ai/claude-code
```

### 项目级使用

在项目中安装后，通过以下方式使用：

```bash
# 进入项目目录
cd your-project

# 启动 Claude Code
claude
```

### 插件安装

```bash
/plugin install <plugin-name>@<source>
```

支持的插件来源包括官方 marketplace 和 GitHub 仓库。

## 社区热点问题

根据社区反馈，以下问题值得关注：

| 问题类型 | 描述 | 相关链接 |
|---------|------|---------|
| 功能请求 | AGENTS.md 支持（#6235，304 条评论） | 社区希望统一多 AI 代理的配置格式 |
| 模型问题 | 复杂工程任务可用性问题（#42796，583 条评论） | 用户反馈二月更新后的稳定性 |
| 社区怀念 | /buddy 命令移除（#45596，254 条评论） | v2.1.97 版本移除了 companion 功能 |
| 终端问题 | Windows Terminal 渲染重叠（#58579） | TUI 显示问题 |
| 权限问题 | auto 模式不可继承 | 权限配置相关 |

## 相关资源

- 官方文档：查看仓库中的 `docs/` 目录
- 社区插件：awesome-claude-code 仓库收集第三方插件
- 问题反馈：通过 GitHub Issues 提交 bug 或功能请求

---

本页面概述了 Claude Code 的整体架构、核心功能和扩展机制。详细的技术文档请参考各模块对应的专门页面。

---

<a id='installation'></a>

## 安装指南

### 相关页面

相关主题：[项目概览](#overview), [快速上手](#quickstart)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/anthropics/claude-code/blob/main/README.md)
- [plugins/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)
- [.devcontainer/Dockerfile](https://github.com/anthropics/claude-code/blob/main/.devcontainer/Dockerfile)
- [Script/run_devcontainer_claude_code.ps1](https://github.com/anthropics/claude-code/blob/main/Script/run_devcontainer_claude_code.ps1)
- [plugins/code-review/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/code-review/README.md)
- [plugins/commit-commands/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/commit-commands/README.md)
</details>

# 安装指南

本页面详细介绍 Claude Code 的完整安装流程、插件系统配置以及开发环境搭建方案。

## 系统要求

Claude Code 对运行环境有以下基本要求：

| 组件 | 最低版本要求 | 推荐版本 |
|------|-------------|---------|
| Node.js | v18.0.0 | v20.x LTS |
| npm | v9.0.0 | v10.x |
| Git | v2.0 | v2.40+ |
| 操作系统 | macOS 12+, Ubuntu 20.04+, Windows 10+ | 最新稳定版 |

**额外依赖：**
- GitHub CLI (`gh`) - 用于某些插件功能（如 PR 审查）
- Docker - 仅在使用 Dev Container 场景下需要

资料来源：[README.md:1-50](https://github.com/anthropics/claude-code/blob/main/README.md)

## 全局安装

### 通过 npm 安装

Claude Code 提供全局 npm 包，可通过以下命令安装：

```bash
npm install -g @anthropic-ai/claude-code
```

安装完成后，在任意项目目录中运行以下命令启动 Claude Code：

```bash
claude
```

资料来源：[README.md:1-30](https://github.com/anthropics/claude-code/blob/main/README.md)

### 验证安装

安装完成后，可通过以下命令验证版本：

```bash
npx @anthropic-ai/claude-code --version
```

确保使用最新版本以获得最新功能和安全修复。

## 插件系统安装

### 内置插件

Claude Code 仓库自带多个内置插件，这些插件位于 `plugins/` 目录下。要使用这些插件：

1. 安装 Claude Code 全局包
2. 在项目中运行 `claude`
3. 使用 `/plugin` 命令安装所需插件

### 插件安装命令

```bash
/plugin install <plugin-name>
```

例如，安装代码审查插件：

```bash
/plugin install code-review
```

资料来源：[plugins/README.md:1-50](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)

### 可用插件列表

| 插件名称 | 功能描述 | 主要命令 |
|---------|---------|---------|
| code-review | 自动 PR 代码审查 | `/code-review` |
| commit-commands | Git 工作流自动化 | `/commit`, `/commit-push-pr` |
| feature-dev | 功能开发工作流 | `/feature-dev` |
| pr-review-toolkit | PR 审查工具集 | `/pr-review-toolkit:review-pr` |
| plugin-dev | 插件开发框架 | `/create-plugin` |
| agent-sdk-dev | Agent SDK 开发 | `/new-sdk-app` |
| hookify | 自定义钩子创建 | `/hookify` |

资料来源：[plugins/README.md:50-150](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)

## 开发环境配置

### Dev Container 方式

Claude Code 支持通过 Docker Dev Container 运行，提供一致的开发环境。

#### 前置条件

1. 安装 Docker Desktop
2. 安装 VS Code Remote - Containers 扩展
3. 克隆 Claude Code 仓库

#### 启动 Dev Container

**Windows (PowerShell)：**

```powershell
.\Script\run_devcontainer_claude_code.ps1
```

资料来源：[Script/run_devcontainer_claude_code.ps1:1-50](https://github.com/anthropics/claude-code/blob/main/Script/run_devcontainer_claude_code.ps1)

#### Dockerfile 配置

Dev Container 使用以下基础镜像配置：

```dockerfile
FROM node:20-slim

# 安装必要工具
RUN apt-get update && apt-get install -y \
    git \
    curl \
    gh

# 设置工作目录
WORKDIR /workspace
```

资料来源：[.devcontainer/Dockerfile:1-30](https://github.com/anthropics/claude-code/blob/main/.devcontainer/Dockerfile)

### 工作流程图

```mermaid
graph TD
    A[开始安装] --> B{选择安装方式}
    B -->|npm 全局安装| C[npm install]
    B -->|Dev Container| D[克隆仓库]
    C --> E[运行 claude 命令]
    D --> F[运行 Dev Container 脚本]
    F --> G[VS Code 连接容器]
    E --> H[配置插件和设置]
    G --> H
    H --> I[开始使用 Claude Code]
```

## 项目级配置

### 初始化新项目

首次在项目中使用 Claude Code 时，会自动创建 `.claude/` 配置目录：

```
project/
├── .claude/
│   └── settings.json      # 项目级设置
├── CLAUDE.md              # 项目指南 (可选)
└── ...
```

### settings.json 配置

项目级设置文件示例：

```json
{
  "permissions": {
    "defaultMode": "auto"
  },
  "plugins": []
}
```

### CLAUDE.md 项目指南

在项目根目录创建 `CLAUDE.md` 文件，可定义项目特定的行为规范和约定。资料来源：[plugins/README.md:1-20](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)

## 身份验证配置

### Anthropic API 密钥

Claude Code 需要有效的 Anthropic API 密钥才能运行。有两种配置方式：

1. **环境变量：**
   ```bash
   export ANTHROPIC_API_KEY=your-api-key
   ```

2. **交互式输入：**
   首次运行时，Claude Code 会提示输入 API 密钥

### GitHub CLI 身份验证

某些功能（如 PR 审查）需要 GitHub CLI：

```bash
gh auth login
```

资料来源：[plugins/code-review/README.md:1-30](https://github.com/anthropics/claude-code/blob/main/plugins/code-review/README.md)

## 常见安装问题

### 问题：命令未找到

**症状：** 安装后运行 `claude` 提示命令不存在

**解决方案：**

```bash
# 确认安装位置
npm list -g @anthropic-ai/claude-code

# 检查 PATH
npm bin -g
```

### 问题：权限错误

**症状：** 写入配置目录时权限被拒绝

**解决方案：**
- Linux/macOS：确保配置目录存在且有写入权限
- Windows：以管理员身份运行或使用 PowerShell

### 问题：插件安装失败

**症状：** `/plugin install` 命令执行失败

**解决方案：**
1. 检查网络连接
2. 确认 npm 源配置正确
3. 尝试清除缓存：`npm cache clean --force`

资料来源：[plugins/commit-commands/README.md:1-30](https://github.com/anthropics/claude-code/blob/main/plugins/commit-commands/README.md)

## 环境变量

### 可用环境变量

| 变量名 | 用途 | 默认值 |
|--------|------|--------|
| `ANTHROPIC_API_KEY` | API 密钥认证 | - |
| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 启用 Auto 模式 | 0 |
| `CLAUDE_PLUGIN_ROOT` | 插件根目录路径 | - |
| `HTTP_PROXY` | HTTP 代理设置 | - |
| `HTTPS_PROXY` | HTTPS 代理设置 | - |

资料来源：[README.md:50-100](https://github.com/anthropics/claude-code/blob/main/README.md)

### Auto 模式启用

Auto 模式现已支持 Bedrock、Vertex 和 Foundry 平台。要启用：

```bash
export CLAUDE_CODE_ENABLE_AUTO_MODE=1
```

适用于 Opus 4.7 和 Opus 4.8 模型。

## 升级与维护

### 升级 Claude Code

```bash
npm update -g @anthropic-ai/claude-code
```

### 查看当前版本

```bash
claude --version
```

### 卸载

```bash
npm uninstall -g @anthropic-ai/claude-code
```

## 快速开始流程

```mermaid
graph LR
    A[安装 Node.js] --> B[npm 全局安装]
    B --> C[运行 claude 命令]
    C --> D{首次运行}
    D -->|未配置| E[输入 API 密钥]
    D -->|已配置| F[开始使用]
    E --> F
    F --> G[可选: 安装插件]
    G --> H[可选: 创建 CLAUDE.md]
```

## 相关资源

- 官方文档：[Anthropic Claude Code](https://docs.anthropic.com/claude-code)
- GitHub 仓库：[anthropics/claude-code](https://github.com/anthropics/claude-code)
- 插件市场：社区开发的插件可在 [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) 找到
- Claude Code 安全审查工具：[claude-code-security-review](https://github.com/anthropics/claude-code-security-review)

---

<a id='quickstart'></a>

## 快速上手

### 相关页面

相关主题：[项目概览](#overview), [斜杠命令系统](#slash-commands), [设置与配置管理](#settings-management)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/anthropics/claude-code/blob/main/README.md)
- [plugins/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)
- [plugins/feature-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/feature-dev/README.md)
- [plugins/plugin-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)
- [plugins/hookify/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/README.md)
- [plugins/code-review/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/code-review/README.md)
- [plugins/feature-dev/commands/feature-dev.md](https://github.com/anthropics/claude-code/blob/main/plugins/feature-dev/commands/feature-dev.md)
</details>

# 快速上手

## 概述

Claude Code 是 Anthropic 官方推出的命令行工具，旨在帮助开发者通过 AI 辅助完成编码任务。作为一款终端集成开发环境，Claude Code 能够理解代码库结构、执行文件操作、运行命令，并与各种开发工具链无缝协作。

本快速上手指南将帮助新用户：
- 完成 Claude Code 的初始配置
- 理解基本工作流程
- 掌握核心命令和功能
- 使用插件扩展功能
- 了解常见问题的解决方案

## 环境要求与安装

### 系统要求

Claude Code 支持主流操作系统，包括 macOS、Linux 和 Windows。

| 平台 | 最低版本要求 | 推荐终端 |
|------|-------------|----------|
| macOS | macOS 12+ | iTerm2, Terminal.app |
| Linux | Ubuntu 20.04+ / Debian 11+ | GNOME Terminal, Konsole |
| Windows | Windows 10+ | Windows Terminal, PowerShell |

### 安装方式

Claude Code 通过 npm 全局安装：

```bash
npm install -g @anthropic-ai/claude-code
```

安装完成后，运行 `claude` 命令启动：

```bash
claude
```

资料来源：[README.md:1-10]()

## 首次启动配置

### 身份验证

首次启动时，Claude Code 会引导完成 Anthropic API 密钥配置：

1. 系统会提示输入 `ANTHROPIC_API_KEY`
2. 可从 [Anthropic Console](https://console.anthropic.com/) 获取密钥
3. 密钥会自动保存到配置文件

### 权限模式配置

Claude Code 提供三种权限模式控制工具使用范围：

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `auto` | 自动批准安全操作，拒绝危险操作 | 日常开发 |
| `review` | 每次操作需用户确认 | 谨慎操作 |
| `bypass` | 允许所有操作 | 自动化脚本 |

可通过 `~/.claude/settings.json` 配置默认模式：

```json
{
  "defaultMode": "auto"
}
```

> ⚠️ **已知问题**：`auto` 权限模式不会在新会话中继承，且无法在会话中途设置。详情参见 [GitHub Issue #55558](https://github.com/anthropics/claude-code/issues/55558)。

资料来源：[plugins/README.md:50-80]()

## 基本工作流程

### 会话生命周期

```mermaid
graph TD
    A[启动 Claude Code] --> B[创建新会话]
    B --> C[发送请求/任务]
    C --> D{Claude 分析请求}
    D -->|需要更多信息| E[提问澄清]
    E --> C
    D -->|执行工具| F[读写文件/运行命令]
    F --> G{操作完成?}
    G -->|否| C
    G -->|是| H[返回结果]
    H --> I[结束会话]
```

### 核心交互模式

Claude Code 支持多种交互方式：

**直接对话模式**
```
claude
> 帮我创建一个用户登录功能
```

**文件参考模式**
```
> 审查这个文件的代码质量
@src/auth/login.ts
```

**命令模式**
```
/help
/model
/agent
```

### 工具使用

Claude Code 可调用多种工具完成任务：

| 工具类别 | 功能 | 示例 |
|---------|------|------|
| **Bash** | 执行 Shell 命令 | `git status`, `npm install` |
| **Read** | 读取文件内容 | 查看源码、配置文件 |
| **Write/Edit** | 修改文件 | 添加功能、修复 Bug |
| **WebFetch** | 获取网页内容 | 查阅文档、API 参考 |
| **Grep** | 搜索代码 | 查找函数调用、变量定义 |
| **Glob** | 文件模式匹配 | 查找特定类型文件 |

资料来源：[plugins/feature-dev/commands/feature-dev.md:1-30]()

## 项目级配置

### CLAUDE.md 文件

在项目根目录创建 `CLAUDE.md` 文件，可以为 Claude Code 提供项目特定的指令和上下文：

```markdown
# 项目指南

## 技术栈
- 前端框架：React 18
- 后端：Node.js + Express
- 数据库：PostgreSQL

## 代码规范
- 使用 TypeScript strict 模式
- 组件文件首字母大写
- 优先使用函数式组件

## 常用命令
- 开发服务器：`npm run dev`
- 运行测试：`npm test`
- 构建生产版本：`npm run build`
```

### 配置文件位置

Claude Code 按以下优先级读取配置：

1. `./.claude/` - 项目级配置
2. `~/.claude/` - 用户级配置
3. 系统默认配置

> ⚠️ **已知问题**：CLAUDE.md 规则不会传递给 Agent 子代理，且在上下文压缩后会弱化。详情参见 [GitHub Issue #59309](https://github.com/anthropics/claude-code/issues/59309)。

## 插件系统

### 插件架构

Claude Code 采用插件化架构，允许用户扩展核心功能：

```mermaid
graph TD
    A[Claude Code Core] --> B[Commands 命令]
    A --> C[Skills 技能]
    A --> D[Agents 代理]
    A --> E[Hooks 钩子]
    A --> F[MCP 服务器]
    
    B --> B1[/slash commands]
    C --> C1[Auto-triggered guidance]
    D --> D1[Specialized subagents]
    E --> E1[Event-driven automation]
    F --> F1[External integrations]
```

### 官方插件列表

| 插件名称 | 功能描述 | 核心组件 |
|---------|---------|---------|
| **feature-dev** | 结构化功能开发工作流 | 命令：`/feature-dev`，代理：`code-explorer`、`code-architect` |
| **code-review** | 自动化 PR 代码审查 | 命令：`/code-review`，5 个并行 Sonnet 代理 |
| **hookify** | 创建自定义钩子 | 命令：`/hookify`、`/hookify:list` |
| **commit-commands** | Git 工作流自动化 | 命令：`/commit`、`/commit-push-pr` |
| **pr-review-toolkit** | PR 审查工具集 | 6 个专业代理 |
| **security-guidance** | 安全提醒钩子 | 钩子：PreToolUse |

资料来源：[plugins/README.md:1-50]()

### 安装和使用插件

**方式一：使用 /plugin 命令**

```bash
/plugin
# 选择 marketplace 中的插件进行安装
```

**方式二：手动配置**

在项目的 `.claude/settings.json` 中添加：

```json
{
  "plugins": [
    "feature-dev",
    "code-review",
    "hookify"
  ]
}
```

### 功能开发工作流

使用 `feature-dev` 插件可以遵循系统化的 7 阶段开发流程：

| 阶段 | 名称 | 目标 |
|------|------|------|
| 1 | 发现 (Discovery) | 理解需要构建的内容 |
| 2 | 代码库探索 | 理解现有代码和模式 |
| 3 | 澄清问题 | 填补空白，解决歧义 |
| 4 | 架构设计 | 设计优雅的解决方案 |
| 5 | 实现 | 编写高质量代码 |
| 6 | 验证 | 质量检查 |
| 7 | 文档 | 更新文档 |

```bash
# 启动功能开发工作流
/feature-dev 添加用户认证功能
```

资料来源：[plugins/feature-dev/README.md:1-80]()

## 常见工作场景

### 代码审查

使用 `code-review` 插件进行自动化 PR 审查：

```bash
# 本地审查，输出到终端
/code-review

# 发布为 PR 评论
/code-review --comment
```

该插件会并行启动多个代理分析：
- CLAUDE.md 合规性
- Bug 检测
- 历史上下文分析
- PR 历史分析
- 代码注释分析

### Git 工作流

Claude Code 内置 Git 命令简化常见操作：

| 命令 | 功能 |
|------|------|
| `/commit` | 提交更改 |
| `/commit-push-pr` | 提交、推送并创建 PR |
| `/clean_gone` | 清理已合并分支 |

### 问题分类

使用 `/triage-issue` 命令自动分类 GitHub Issue：

```bash
/triage-issue
# 输入 Issue 链接或内容
# 自动分类：bug/feature/docs 等
```

## 故障排除

### 常见问题

#### 1. 模型加载超时

**症状**：`/model` 命令显示 "Loading models..." 无响应。

**解决方案**：
- 检查网络连接
- 验证 API 密钥有效性
- 尝试重启 Claude Code

详情参见 [GitHub Issue #59646](https://github.com/anthropics/claude-code/issues/59646)

#### 2. 终端渲染异常 (Windows)

**症状**：TUI 视图线条重叠或堆叠。

**解决方案**：
- 使用最新版本 Windows Terminal
- 尝试切换到 PowerShell 7.6+
- 更新 Claude Code 到最新版本

详情参见 [GitHub Issue #58579](https://github.com/anthropics/claude-code/issues/58579)

#### 3. 速率限制问题

**症状**：操作被限制，提示达到使用上限。

**解决方案**：
- 检查 API 使用量
- 等待限制重置（注意：实际周期约 24 小时，而非文档所述 7 天）

详情参见 [GitHub Issue #52921](https://github.com/anthropics/claude-code/issues/52921)

#### 4. MCP 服务器崩溃

**症状**：插件市场列表操作崩溃，显示 "Illegal instruction"。

**解决方案**：
- Bun 构建版本问题，需要更新
- 切换到 Node.js 运行时

详情参见 [GitHub Issue #59645](https://github.com/anthropics/claude-code/issues/59645)

### 日志和调试

Claude Code 运行时可添加调试标志：

```bash
CLAUDE_DEBUG=1 claude
```

日志文件位置：
- macOS/Linux：`~/.claude/logs/`
- Windows：`%USERPROFILE%\.claude\logs\`

## 最佳实践

### 提高响应质量

1. **提供清晰的任务描述**
   - 明确说明期望结果
   - 提供相关文件路径
   - 说明约束条件

2. **使用文件引用**
   - 使用 `@` 引用相关文件
   - 提供代码片段作为上下文

3. **分步骤执行复杂任务**
   - 将大任务分解为小步骤
   - 每步完成后确认结果

### 安全注意事项

1. **敏感信息处理**
   - 不要在对话中分享 API 密钥
   - 使用环境变量存储敏感配置
   - 利用 `security-guidance` 插件监控危险操作

2. **权限控制**
   - 生产环境使用 `review` 模式
   - 定期审查已批准的权限请求

### 性能优化

1. **上下文管理**
   - 大型代码库使用 `/compact` 命令压缩上下文
   - 定期清理不必要的对话历史

2. **插件管理**
   - 按需启用插件，避免加载过多未使用的组件
   - 使用 `hookify` 插件防止不必要的重复操作

## 下一步

熟悉基础操作后，建议深入学习：

1. **插件开发** - 使用 `plugin-dev` 插件创建自定义功能
   ```bash
   /plugin-dev
   ```

2. **Agent 开发** - 创建专门的子代理处理特定任务
   ```bash
   # 参考 plugins/agent-sdk-dev 文档
   ```

3. **MCP 集成** - 连接外部服务和数据库
   ```bash
   # 创建 .mcp.json 配置
   ```

4. **自动化工作流** - 结合 GitHub Actions 实现 CI/CD 集成

## 版本信息

当前最新版本：**v2.1.158**

**最新特性**：
- Auto mode 现已支持 Bedrock、Vertex 和 Foundry 平台的 Opus 4.7 及 Opus 4.8
- 通过设置 `CLAUDE_CODE_ENABLE_AUTO_MODE=1` 启用

---

如需更多帮助，请参考：
- 官方文档：[docs.anthropic.com](https://docs.anthropic.com)
- GitHub Issues：[github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)
- 社区插件：[awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code)

---

<a id='slash-commands'></a>

## 斜杠命令系统

### 相关页面

相关主题：[Agent 代理系统](#agents-system), [Hooks 钩子系统](#hooks-events), [插件系统架构](#plugin-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [plugins/plugin-dev/skills/command-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/SKILL.md)
- [plugins/plugin-dev/skills/command-development/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/README.md)
- [plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md)
- [plugins/plugin-dev/skills/command-development/examples/simple-commands.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/examples/simple-commands.md)
- [plugins/plugin-dev/skills/command-development/examples/plugin-commands.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/examples/plugin-commands.md)
- [plugins/plugin-dev/commands/create-plugin.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/commands/create-plugin.md)
</details>

# 斜杠命令系统

## 概述

斜杠命令（Slash Commands）是 Claude Code 中用于触发特定工作流程的用户命令。以 `/` 开头，用户可以通过斜杠命令快速调用预设的功能、工作流或自动化任务。斜杠命令系统是 Claude Code 插件体系的核心组件之一，与技能（Skills）、代理（Agents）、钩子（Hooks）和 MCP 服务器共同构成了完整的插件扩展生态。

斜杠命令采用 Markdown 格式定义，结合 YAML frontmatter 元数据配置，使得命令的开发、维护和分发变得简单直观。开发者无需编写复杂的代码，只需按照约定的格式创建 Markdown 文件即可定义新的命令。资料来源：[plugins/plugin-dev/skills/command-development/README.md:1-15]()

## 架构设计

### 核心组件

斜杠命令系统的架构包含以下核心组件：

| 组件 | 说明 | 位置 |
|------|------|------|
| 命令文件 | Markdown 格式的命令定义文件 | `commands/` 目录 |
| Frontmatter | YAML 元数据配置 | 命令文件顶部 |
| 命令主体 | 命令执行时的提示词 | Markdown 正文内容 |
| 环境变量 | 命令运行时可用的变量 | `${CLAUDE_PLUGIN_ROOT}` 等 |

资料来源：[plugins/plugin-dev/skills/command-development/SKILL.md:1-30]()

### 命令执行流程

```mermaid
graph TD
    A[用户输入 /command-name] --> B[解析命令名称]
    B --> C{查找命令定义}
    C -->|找到| D[加载命令文件]
    C -->|未找到| E[返回 Unknown skill 错误]
    D --> F[解析 Frontmatter]
    F --> G[替换变量占位符]
    G --> H[执行命令逻辑]
    H --> I[返回执行结果]
```

## 命令文件结构

### 基本格式

每个斜杠命令由一个 Markdown 文件定义，文件结构如下：

```markdown
---
description: 命令描述
argument-hint: [参数1] [参数2]
allowed-tools: Bash, Read
---

命令执行时使用的提示词内容...
```

资料来源：[plugins/plugin-dev/skills/command-development/README.md:60-80]()

### Frontmatter 字段说明

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `description` | string | 是 | 命令的简短描述，显示在命令列表中 |
| `argument-hint` | string | 否 | 参数提示，定义命令接受的参数格式 |
| `allowed-tools` | string | 否 | 允许使用的工具列表 |
| `disable-model-invocation` | boolean | 否 | 设为 `true` 时为手动模式命令 |

资料来源：[plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md:1-50]()

## 命令开发指南

### 开发工作流

斜杠命令的开发遵循以下标准化流程：

```mermaid
graph LR
    A[设计命令] --> B[创建文件]
    B --> C[添加 Frontmatter]
    C --> D[编写命令主体]
    D --> E[测试命令]
    E --> F{验证通过?}
    F -->|否| D
    F -->|是| G[完成]
```

### 设计阶段

在创建命令之前，需要明确以下要素：

- **命令目的**：命令要解决什么问题
- **参数设计**：需要哪些输入参数
- **工具依赖**：需要哪些 Claude Code 内置工具
- **输出格式**：命令执行后的预期结果

资料来源：[plugins/plugin-dev/skills/command-development/SKILL.md:100-120]()

### 实现示例

#### 简单代码审查命令

```markdown
---
description: Review code for issues
---

Review this code for quality and potential bugs.
```

#### 带参数的环境部署命令

```markdown
---
description: Deploy to environment
argument-hint: [environment] [version]
---

Deploy to $1 environment using version $2
```

#### 集成 Bash 执行的命令

```markdown
---
description: Show Git status
allowed-tools: Bash(git:*)
---

Current status: !`git status`
Recent commits: !`git log --oneline -5`
```

资料来源：[plugins/plugin-dev/skills/command-development/README.md:80-120]()

## 变量与动态内容

### 参数占位符

在命令主体中使用 `$1`、`$2` 等占位符引用用户提供的参数：

```markdown
---
description: Create file
argument-hint: [filename]
---

Create a new file named $1 in the current directory
```

### Bash 执行语法

使用 `` !`command` `` 语法在命令执行时动态获取 Bash 命令输出：

```markdown
---
description: Show project info
---

Project: !`basename $(pwd)`
Git branch: !`git branch --show-current`
```

资料来源：[plugins/plugin-dev/skills/command-development/examples/simple-commands.md:1-50]()

### 文件引用

使用 `@` 符号引用文件内容作为命令上下文：

```markdown
---
description: Document file
argument-hint: [file-path]
---

Generate documentation for @$1
```

### 环境变量

| 变量 | 说明 |
|------|------|
| `${CLAUDE_PLUGIN_ROOT}` | 插件根目录路径 |
| `${CLAUDE_PROJECT_ROOT}` | 项目根目录路径 |

这些变量确保命令在不同环境下具有可移植性。资料来源：[plugins/plugin-dev/skills/command-development/SKILL.md:50-70]()

## 插件命令系统

### 命名空间

插件中的命令通过 `plugin-name:command-name` 格式命名。例如 `plugin-dev:create-plugin` 表示 plugin-dev 插件中的 create-plugin 命令。这种命名空间机制避免了不同插件之间的命令冲突。

资料来源：[plugins/plugin-dev/commands/create-plugin.md:1-30]()

### 插件命令特性

插件命令相比普通命令具有以下额外特性：

| 特性 | 说明 |
|------|------|
| 多脚本编排 | 支持按顺序执行多个脚本 |
| 模板生成 | 支持基于模板创建文件 |
| 配置驱动 | 支持从配置文件读取参数 |
| 组件集成 | 可调用同一插件中的 Agents 和 Skills |

资料来源：[plugins/plugin-dev/skills/command-development/examples/plugin-commands.md:1-30]()

### 多脚本工作流示例

```markdown
---
description: Create and configure project
argument-hint: [project-name]
allowed-tools: Bash, Write, Read
---

# Step 1: Initialize project
!`mkdir -p $1 && cd $1 && npm init -y`

# Step 2: Create structure
Create the following files:
- src/index.ts
- package.json
- tsconfig.json

# Step 3: Configure
Update package.json with proper scripts
```

## 命令与技能的协作

### 技能加载机制

在 Phase 5（实现阶段），创建命令时可能需要加载相关技能：

```markdown
---
description: Create new feature
argument-hint: [feature-name]
---

Follow the feature development workflow:
1. Load skill: plugin-structure
2. Create component plan
3. Implement feature
```

资料来源：[plugins/plugin-dev/skills/command-development/SKILL.md:150-170]()

### 技能触发短语

命令中可包含触发技能加载的短语：

- "create a slash command" → 触发 command-development 技能
- "create a hook" → 触发 hook-development 技能
- "create a skill" → 触发 skill-development 技能

资料来源：[plugins/plugin-dev/skills/command-development/README.md:150-180]()

## 最佳实践

### 设计原则

1. **单一职责**：每个命令应专注于一个特定任务
2. **清晰描述**：description 应简洁明了，说明命令用途
3. **参数验证**：使用 argument-hint 提供参数格式提示
4. **错误处理**：考虑边界情况和错误场景

### 编写规范

| 规范 | 说明 |
|------|------|
| 使用祈使语气 | 命令主体使用动词开头，如 "Create"、"Review"、"Deploy" |
| 保持简洁 | 避免过长的命令描述 |
| 提供示例 | 在命令中添加使用示例 |
| 文档化参数 | 为每个参数提供清晰的说明 |

资料来源：[plugins/plugin-dev/skills/command-development/SKILL.md:180-200]()

### 安全注意事项

- 避免在命令中硬编码敏感信息
- 使用 `${CLAUDE_PLUGIN_ROOT}` 确保路径可移植性
- 命令中的 Bash 执行应进行输入验证
- 遵循最小权限原则，仅启用必要的工具

## 验证与测试

### 本地测试

创建命令后，按以下步骤测试：

1. 重启 Claude Code 或重新加载插件
2. 输入 `/command-name` 触发命令
3. 验证参数解析是否正确
4. 检查工具调用是否按预期执行
5. 确认输出格式符合预期

### 常用问题排查

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| Unknown skill | 命令文件位置错误 | 确保文件在 `commands/` 目录下 |
| 参数未解析 | 占位符格式错误 | 使用 `$1`, `$2` 格式 |
| 工具不可用 | allowed-tools 配置错误 | 检查工具名称拼写 |
| 路径错误 | 未使用环境变量 | 使用 `${CLAUDE_PLUGIN_ROOT}` |

资料来源：[plugins/plugin-dev/skills/command-development/SKILL.md:200-230]()

## 内置斜杠命令参考

Claude Code 提供以下内置斜杠命令：

| 命令 | 功能 |
|------|------|
| `/model` | 切换使用的 AI 模型 |
| `/claude` | 调用另一个 Claude 实例 |
| `/bug` | 报告 bug |
| `/review` | 代码审查 |
| `/agent` | 创建子代理 |
| `/compose` | 组合多个工具调用 |
| `/mcp` | 管理 MCP 服务器 |
| `/help` | 显示帮助信息 |
| `/cmd` | 列出所有可用命令 |
| `/compact` | 压缩上下文 |
| `/exit` | 退出对话 |

## 社区相关讨论

根据社区反馈，以下是与斜杠命令系统相关的热门议题：

- **#45596 "Bring Back Buddy"**：用户对 `/buddy` 命令被移除表示强烈不满，反映了社区对斜杠命令的依赖程度
- **技能与命令集成**：社区创建了多个技能集合（如 awesome-claude-code），其中包含大量自定义斜杠命令
- **AGENTS.md 标准化请求 (#6235)**：用户建议支持 AGENTS.md 作为跨平台命令配置文件

这些讨论表明斜杠命令系统是 Claude Code 生态中用户高度关注的核心功能。

## 扩展阅读

- [命令开发技能](../plugin-dev/skills/command-development/) - 完整的命令开发指南
- [Frontmatter 参考](../plugin-dev/skills/command-development/references/frontmatter-reference.md) - 详细的字段配置说明
- [简单命令示例](../plugin-dev/skills/command-development/examples/simple-commands.md) - 10 个实际命令示例
- [插件命令示例](../plugin-dev/skills/command-development/examples/plugin-commands.md) - 插件专用命令模式

---

<a id='agents-system'></a>

## Agent 代理系统

### 相关页面

相关主题：[斜杠命令系统](#slash-commands), [Hooks 钩子系统](#hooks-events), [插件系统架构](#plugin-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [plugins/plugin-dev/skills/agent-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/agent-development/SKILL.md)
- [plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md)
- [plugins/plugin-dev/skills/agent-development/references/triggering-examples.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/agent-development/references/triggering-examples.md)
- [plugins/plugin-dev/skills/agent-development/references/agent-creation-system-prompt.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/agent-development/references/agent-creation-system-prompt.md)
- [plugins/plugin-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)
- [plugins/feature-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/feature-dev/README.md)
- [plugins/pr-review-toolkit/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/pr-review-toolkit/README.md)
</details>

# Agent 代理系统

## 概述

Agent（代理）是 Claude Code 中用于执行特定任务的自主子程序。通过 Agent 系统，Claude Code 能够将复杂任务分解为多个专门化的子任务，每个子任务由专门的代理处理。这种设计模式使得系统能够处理多维度、高复杂度的开发工作流程，同时保持代码质量和一致性。

Agent 系统是 Claude Code 插件架构的核心组件之一，与 Commands（命令）、Hooks（钩子）、Skills（技能）和 MCP（模型上下文协议）共同构成完整的插件生态系统。 资料来源：[plugins/plugin-dev/README.md:1-20]()

## 核心概念

### Agent 与 Subagent 的区别

在 Claude Code 中，"Agent" 通常指用户级别的代理配置，而 "Subagent" 则指在父代理内部创建的子代理实例。根据社区反馈，**CLAUDE.md 规则不会自动传播到 Subagent**，这是一个已知的限制问题。 资料来源：[社区 Issue #59309]()

### Agent 的生命周期

Agent 的完整生命周期包含以下阶段：

```mermaid
graph TD
    A[用户触发 Agent] --> B{检查触发条件}
    B -->|匹配| C[加载 Agent 配置]
    B -->|不匹配| D[返回主会话]
    C --> E[初始化 System Prompt]
    E --> F[分配工具和资源]
    F --> G[执行任务]
    G --> H{任务完成?}
    H -->|是| I[返回结果]
    H -->|否| J[继续执行]
    J --> G
    I --> K[结果整合]
```

## Agent 文件结构

Agent 通过 Markdown 文件定义，采用 YAML 前置元数据（frontmatter）加 Markdown 正文的结构。

### 文件格式

```markdown
---
name: agent-name
description: 代理描述
model: claude-sonnet-4-20250514
color: blue
tools:
  - Bash
  - Read
  - Write
  - Edit
  - NotebookEdit
---

# System Prompt 内容
具体指令和任务描述...
```

### Frontmatter 字段说明

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `name` | string | 是 | Agent 唯一标识符 |
| `description` | string | 是 | Agent 功能描述，用于触发匹配 |
| `model` | string | 否 | 指定使用的模型，默认使用当前会话模型 |
| `color` | string | 否 | Agent 在 UI 中的显示颜色 |
| `tools` | array | 否 | 允许 Agent 使用的工具列表 |

资料来源：[plugins/plugin-dev/skills/agent-development/SKILL.md:45-80]()

## Description 设计规范

### 触发机制

Agent 的 `description` 字段采用渐进式披露（Progressive Disclosure）设计，包含元数据层级、核心功能和示例块三部分：

```markdown
description: |
  分析代码注释的准确性和维护性
  <example>
  用户: "检查这个文件的注释是否准确"
  触发: 检查代码注释质量
  </example>
  <example>
  用户: "Review comment accuracy"
  触发: 分析文档完整性
  </example>
```

### 触发短语要求

有效的触发短语应具备以下特征：

- **具体性**：避免过于宽泛的表述
- **行动导向**：使用动词明确表达预期行为
- **上下文关联**：与实际使用场景紧密结合
- **多样性**：提供多种触发变体以提高匹配率

资料来源：[plugins/plugin-dev/skills/agent-development/references/triggering-examples.md:1-50]()

## System Prompt 设计

### 设计原则

System Prompt 是 Agent 的核心指令集，决定了代理的行为模式和质量标准。主要设计原则包括：

1. **角色定义清晰**：明确代理的专业领域和能力边界
2. **输出格式规范**：定义标准化的响应格式
3. **决策路径明确**：为常见场景提供决策指引
4. **错误处理指导**：指定异常情况的处理方式

### 模式分类

根据功能类型，Agent 可分为以下几种设计模式：

| 模式类型 | 适用场景 | 特征 |
|----------|----------|------|
| 分析型 (Analysis) | 代码审查、数据检查 | 强调观察细节、结构化输出 |
| 生成型 (Generation) | 代码生成、文档创建 | 强调规范遵循、示例参考 |
| 验证型 (Validation) | 测试验证、配置检查 | 强调准确性、全面性覆盖 |
| 编排型 (Orchestration) | 任务协调、多组件集成 | 强调流程控制、状态管理 |

资料来源：[plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md:1-80]()

## Agent 开发工作流

### 创建流程概览

```mermaid
graph LR
    A[定义需求] --> B[设计 Description]
    B --> C[编写 System Prompt]
    C --> D[配置 Frontmatter]
    D --> E[创建文件]
    E --> F[验证格式]
    F --> G[测试执行]
    G --> H{通过?}
    H -->|是| I[部署使用]
    H -->|否| J[迭代优化]
    J --> C
```

### 详细步骤

#### 1. 需求分析

明确 Agent 需要解决的核心问题：
- 任务类型（分析、生成、验证、编排）
- 输入输出格式
- 依赖的工具和资源
- 与其他组件的交互方式

#### 2. 使用 agent-creator Agent

Claude Code 提供了专门的 `agent-creator` Agent 用于辅助创建代理：

```
提供描述 → Agent-creator 生成 identifier、whenToUse、systemPrompt
```

资料来源：[plugins/plugin-dev/README.md:45-65]()

#### 3. 文件创建规范

Agent 文件应放置在插件目录的 `agents/` 子目录下，文件命名使用 kebab-case 风格：

```
plugins/
  └── your-plugin/
      └── agents/
          ├── code-architect.md
          ├── test-analyzer.md
          └── validation-agent.md
```

#### 4. 格式验证

创建 Agent 后，使用 `validate-agent.sh` 脚本进行格式验证：

```bash
./validate-agent.sh agents/your-agent.md
```

资料来源：[plugins/plugin-dev/skills/agent-development/SKILL.md:120-150]()

## 插件内置 Agent 示例

### Feature Dev Plugin

Feature Dev 插件包含多个专门化的 Agent，用于特征开发的各个阶段：

| Agent 名称 | 功能 | 使用场景 |
|------------|------|----------|
| `code-explorer` | 代码库探索 | 理解现有代码结构 |
| `code-architect` | 架构设计 | 设计新功能的实现方案 |
| `pr-reviewer` | 代码审查 | PR 质量把控 |

资料来源：[plugins/feature-dev/README.md:30-80]()

### PR Review Toolkit

PR Review Toolkit 提供了 6 个专业化的审查 Agent：

| Agent | 专注领域 | 主要功能 |
|-------|----------|----------|
| `comment-analyzer` | 注释分析 | 检查注释准确性和技术债务 |
| `pr-test-analyzer` | 测试分析 | 验证测试覆盖率和质量 |
| `silent-failure-hunter` | 错误处理 | 排查静默失败和异常处理 |
| `type-design-analyzer` | 类型设计 | 评估类型设计的合理性 |
| `code-reviewer` | 代码审查 | 综合代码质量评估 |
| `code-simplifier` | 代码简化 | 优化代码结构和可读性 |

资料来源：[plugins/pr-review-toolkit/README.md:15-60]()

## Agent 与上下文的继承问题

### 已知的限制

根据社区反馈，Agent 存在以下已知问题：

1. **CLAUDE.md 规则传播问题**：Subagent 不会继承父代理的 CLAUDE.md 规则
2. **上下文压缩后规则弱化**：经过上下文压缩后，规则遵守度显著下降

这些问题影响了 Agent 执行任务时的规范一致性。 资料来源：[社区 Issue #59309]()

### 临时解决方案

在使用 Agent 时，建议采取以下措施：

- 在 Agent 的 System Prompt 中直接嵌入必要的规则
- 避免依赖 CLAUDE.md 的自动传播机制
- 在关键任务前显式提醒 Agent 遵守特定规则

## 最佳实践

### 触发条件优化

- 使用具体的行动短语而非抽象描述
- 提供 2-3 个触发示例以覆盖不同表达方式
- 避免与高频词汇过度重叠导致误触发

### System Prompt 编写

- 保持指令简洁明了，避免冗长
- 使用结构化格式提高可读性
- 为输出指定明确的格式要求
- 包含边界情况和异常处理指引

### 文件组织

```
plugins/
  └── your-plugin/
      ├── agents/
      │   ├── primary-agent.md
      │   └── secondary-agent.md
      ├── skills/
      ├── commands/
      └── hooks/
```

### 安全考虑

- 避免在 System Prompt 中硬编码敏感信息
- 使用环境变量引用外部配置
- 对文件操作和命令执行设置明确的权限边界

## 相关资源

- [Agent 开发技能文档](plugins/plugin-dev/skills/agent-development/SKILL.md)
- [System Prompt 设计指南](plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md)
- [触发条件设计示例](plugins/plugin-dev/skills/agent-development/references/triggering-examples.md)
- [Claude Code 插件开发指南](plugins/plugin-dev/README.md)

---

<a id='hooks-events'></a>

## Hooks 钩子系统

### 相关页面

相关主题：[斜杠命令系统](#slash-commands), [Agent 代理系统](#agents-system), [插件系统架构](#plugin-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [plugins/plugin-dev/skills/hook-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/hook-development/SKILL.md)
- [plugins/plugin-dev/skills/hook-development/references/patterns.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/hook-development/references/patterns.md)
- [plugins/hookify/hooks/pretooluse.py](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/hooks/pretooluse.py)
- [plugins/hookify/hooks/posttooluse.py](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/hooks/posttooluse.py)
- [plugins/security-guidance/hooks/security_reminder_hook.py](https://github.com/anthropics/claude-code/blob/main/plugins/security-guidance/hooks/security_reminder_hook.py)
</details>

# Hooks 钩子系统

## 概述

Hooks 是 Claude Code 中的事件驱动自动化机制，允许开发者在特定操作执行前或执行后插入自定义逻辑。通过 Hooks，系统可以在关键时间点拦截、验证或修改行为，实现安全控制、行为提醒、自动化工作流等功能。

```mermaid
graph TD
    A[用户操作] --> B{Hook 触发点}
    B -->|工具执行前| C[PreToolUse Hook]
    B -->|工具执行后| D[PostToolUse Hook]
    B -->|会话停止| E[Stop Hook]
    B -->|上下文压缩| F[Compact Hook]
    
    C -->|允许| G[执行工具]
    C -->|阻止| H[显示警告]
    C -->|修改| I[工具参数]
    
    G --> D
    D --> J[结果处理]
    
    style C fill:#e1f5fe
    style D fill:#e8f5e8
```

**核心能力**：
- 在工具执行前进行验证和拦截
- 记录操作历史并分析行为模式
- 提供交互式确认提示
- 修改工具执行参数
- 自动化重复性检查任务

资料来源：[plugins/plugin-dev/skills/hook-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/hook-development/SKILL.md)

## 钩子类型

Claude Code 支持多种类型的 Hook，每种类型对应不同的触发时机和用途。

| 钩子类型 | 触发时机 | 典型用途 | 返回值 |
|---------|---------|---------|--------|
| `PreToolUse` | 工具执行前 | 验证参数、阻止危险操作、提醒用户 | `accept` / `reject` / `ask` |
| `PostToolUse` | 工具执行后 | 分析结果、记录日志、后续处理 | `continue` |
| `Stop` | 会话停止时 | 清理资源、保存状态 | `continue` |
| `Compact` | 上下文压缩前 | 提取关键信息、准备压缩 | `continue` |

资料来源：[plugins/plugin-dev/skills/hook-development/references/patterns.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/hook-development/references/patterns.md)

### PreToolUse 钩子

`PreToolUse` 是最常用的钩子类型，在任何工具调用之前触发。它可以：

- **验证工具参数**：检查文件路径、命令安全性
- **阻止危险操作**：如 `rm -rf` 等高风险命令
- **要求确认**：向用户展示操作详情并请求确认
- **修改参数**：在执行前调整工具参数

```python
# pretooluse.py 示例 - Hookify 插件
def hook_pre_tool_use(tool_name, tool_input):
    """
    预工具使用钩子 - 在工具执行前检查
    """
    # 检查危险命令
    if tool_name == "Bash" or tool_name == "bash__":
        command = tool_input.get("command", "")
        
        # 检测 rm -rf 命令
        if "rm -rf" in command or "rm -fr" in command:
            return {
                "action": "ask",
                "message": f"⚠️ 检测到危险删除命令: {command}\n是否继续?"
            }
    
    # 检测其他危险操作
    dangerous_patterns = [
        (r"chmod\s+777", "过于宽松的文件权限"),
        (r":\(\)\{\s*:\|\:&\s*;\s*:\;\s*\}", "Fork 炸弹"),
        (r"curl.*\|.*sh", "管道执行远程脚本"),
    ]
    
    for pattern, description in dangerous_patterns:
        import re
        if re.search(pattern, command):
            return {
                "action": "reject",
                "message": f"❌ 检测到危险操作: {description}"
            }
    
    return {"action": "accept"}
```

资料来源：[plugins/hookify/hooks/pretooluse.py](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/hooks/pretooluse.py)

### PostToolUse 钩子

`PostToolUse` 在工具执行完成后触发，适用于：

- **结果分析**：检查命令输出中的潜在问题
- **日志记录**：记录操作历史用于审计
- **后续处理**：基于执行结果执行额外操作

```python
# posttooluse.py 示例 - Hookify 插件
def hook_post_tool_use(tool_name, tool_input, tool_output):
    """
    后工具使用钩子 - 在工具执行后分析结果
    """
    # 分析 Bash 命令输出
    if tool_name == "Bash" or tool_name == "bash__":
        output = tool_output.get("content", "")
        
        # 检测潜在的敏感信息泄露
        sensitive_patterns = [
            (r"password\s*=", "密码硬编码"),
            (r"api[_-]?key\s*=", "API Key 暴露"),
            (r"-----BEGIN.*PRIVATE KEY-----", "私钥泄露"),
            (r"ghp_[a-zA-Z0-9]{36}", "GitHub Token"),
        ]
        
        warnings = []
        for pattern, description in sensitive_patterns:
            import re
            if re.search(pattern, output, re.IGNORECASE):
                warnings.append(description)
        
        if warnings:
            return {
                "action": "warn",
                "messages": [f"⚠️ 检测到: {w}" for w in warnings]
            }
    
    return {"action": "continue"}
```

资料来源：[plugins/hookify/hooks/posttooluse.py](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/hooks/posttooluse.py)

### 安全提醒钩子

`security-guidance` 插件提供了专业的安全检查钩子：

```python
# security_reminder_hook.py - 安全提醒钩子
SECURITY_PATTERNS = [
    ("Command Injection", [
        r"\$\([^)]+\)",           # $(command)
        r"`[^`]+`",               # `command`
        r"\|\s*sh\b",             # | sh
    ]),
    ("XSS", [
        r"innerHTML\s*=",         # innerHTML赋值
        r"document\.write",        # document.write
        r"eval\s*\(",             # eval()
    ]),
    ("Dangerous Deserialization", [
        r"pickle\.loads?",        # pickle.load/loads
        r"unpickle",              # unpickle
    ]),
    ("OS Command Injection", [
        r"os\.system\s*\(",        # os.system()
        r"os\.popen\s*\(",         # os.popen()
        r"subprocess\.call\s*\(",  # subprocess.call()
    ]),
]
```

资料来源：[plugins/security-guidance/hooks/security_reminder_hook.py](https://github.com/anthropics/claude-code/blob/main/plugins/security-guidance/hooks/security_reminder_hook.py)

## 钩子配置

### hooks.json 配置结构

每个插件通过 `hooks/hooks.json` 文件定义钩子配置：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "name": "security-reminder",
        "description": "提醒潜在的安全问题",
        "path": "hooks/security_reminder_hook.py"
      }
    ],
    "PostToolUse": [
      {
        "name": "operation-logger",
        "description": "记录操作历史",
        "path": "hooks/post_tool_logger.py"
      }
    ]
  }
}
```

**配置字段说明**：

| 字段 | 类型 | 必需 | 说明 |
|-----|------|-----|------|
| `name` | string | 是 | 钩子唯一标识名称 |
| `description` | string | 否 | 钩子功能描述 |
| `path` | string | 是 | 钩子脚本相对路径 |
| `enableByDefault` | boolean | 否 | 是否默认启用（默认 true）|

资料来源：[plugins/plugin-dev/skills/hook-development/references/patterns.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/hook-development/references/patterns.md)

### 钩子脚本位置规范

```
plugin-name/
├── hooks/
│   ├── hooks.json           # 钩子配置
│   ├── pretooluse.py        # PreToolUse 钩子实现
│   ├── posttooluse.py       # PostToolUse 钩子实现
│   └── examples/            # 示例脚本（非执行代码）
│       └── sample_check.py
```

**重要规范**：
- 钩子脚本应放置在 `hooks/` 目录或子目录中
- 示例代码放置在 `examples/` 目录
- 使用 `${CLAUDE_PLUGIN_ROOT}` 确保路径可移植性

资料来源：[plugins/plugin-dev/skills/hook-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/hook-development/SKILL.md)

## 钩子返回值

### PreToolUse 返回值

```mermaid
graph TD
    A[PreToolUse 执行] --> B{返回 action}
    B -->|accept| C[✅ 允许工具执行]
    B -->|reject| D[❌ 阻止执行]
    B -->|ask| E[❓ 请求用户确认]
    B -->|modify| F[✏️ 修改参数后执行]
    
    E -->|用户同意| C
    E -->|用户拒绝| D
    
    style accept fill:#c8e6c9
    style reject fill:#ffcdd2
    style ask fill:#fff9c4
```

| action 值 | 说明 | 使用场景 |
|-----------|------|----------|
| `accept` | 允许工具正常执行 | 验证通过，继续执行 |
| `reject` | 阻止工具执行，显示拒绝消息 | 危险操作、权限不足 |
| `ask` | 显示提示信息，等待用户确认 | 需要用户知情的高风险操作 |
| `modify` | 修改参数后执行 | 自动修复参数问题 |

### PostToolUse 返回值

| action 值 | 说明 |
|-----------|------|
| `continue` | 正常继续，正常结束会话 |
| `stop` | 停止当前会话 |

## 钩子开发工作流

```mermaid
graph LR
    A[1. 加载 hook-development 技能] --> B[2. 创建 hooks/hooks.json]
    B --> C[3. 编写钩子脚本]
    C --> D[4. 放置到 hooks/ 目录]
    D --> E[5. 使用验证脚本测试]
    E --> F{验证结果}
    F -->|通过| G[✅ 钩子就绪]
    F -->|失败| H[🔧 修复问题]
    H --> C
```

### 开发步骤详解

**步骤 1：加载技能**
```
使用 Skill 工具加载 hook-development 技能
```

**步骤 2：创建配置**
在 `hooks/hooks.json` 中定义钩子元数据

**步骤 3：实现钩子逻辑**

钩子函数签名：
```python
def hook_pre_tool_use(tool_name, tool_input):
    """
    Args:
        tool_name: 被调用的工具名称 (如 "Bash", "Read", "Write")
        tool_input: 工具输入参数字典
    Returns:
        dict: 包含 action 和可选 message 的字典
    """
    # 编写检查逻辑
    return {"action": "accept"}

def hook_post_tool_use(tool_name, tool_input, tool_output):
    """
    Args:
        tool_name: 被调用的工具名称
        tool_input: 工具输入参数
        tool_output: 工具执行结果
    Returns:
        dict: 包含 action 的字典
    """
    # 编写后续处理逻辑
    return {"action": "continue"}
```

**步骤 4：验证钩子**

```bash
# 验证 hooks.json 语法
./scripts/validate-hook-schema.sh

# 测试钩子脚本
./scripts/test-hook.sh <hook-type> <test-input>
```

资料来源：[plugins/plugin-dev/skills/hook-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/hook-development/SKILL.md)

## 实际应用示例

### Hookify 插件

`hookify` 插件展示了钩子的高级用法——通过对话分析自动创建规则：

```bash
# 从用户反馈中学习
/hookify 不要使用 console.log

# 分析最近对话自动创建规则
/hookify
```

**工作流程**：
1. 分析用户最近的纠正行为
2. 创建对应的钩子规则文件
3. 规则立即生效，无需重启

**规则文件格式** (`.claude/hookify.*.local.md`)：

```markdown
---
trigger: console\.log
message: "检测到 console.log，建议使用结构化日志"
severity: warn
---
```

### 安全提醒插件

`sedurity-guidance` 插件在工具执行前检查多种安全模式：

| 类别 | 检测模式 | 严重程度 |
|------|---------|---------|
| 命令注入 | `$(...)`, `\`...\``, `\| sh` | 高 |
| XSS | `innerHTML =`, `document.write` | 高 |
| 危险反序列化 | `pickle.load`, `unpickle` | 高 |
| OS 命令执行 | `os.system`, `os.popen` | 中 |

## 最佳实践

### 命名规范

| 规范 | 示例 |
|-----|------|
| 脚本命名 | `security_check.py`, `operation_logger.py` |
| 函数命名 | `hook_pre_tool_use`, `hook_post_tool_use` |
| 配置文件 | `hooks.json` |

### 安全考虑

1. **HTTPS 优先**：网络请求必须使用 HTTPS
2. **无硬编码凭证**：不使用明文密码或 API Key
3. **输入验证**：始终验证和清理外部输入
4. **最小权限**：钩子只请求必要的系统权限

### 性能优化

- 避免在钩子中执行耗时操作
- 使用正则表达式时注意贪婪匹配
- 对高频触发的钩子进行优化

## 社区相关问题

根据社区反馈，钩子系统在以下场景中有重要应用：

1. **CLAUDE.md 规则强化**：用户反馈钩子有助于确保子代理遵守项目规范（#59309）
2. **安全验证**：社区开发者重视钩子在防止危险操作中的作用
3. **自动化工作流**：通过 Hookify 等插件实现智能行为学习

## 相关资源

| 资源 | 位置 | 说明 |
|-----|------|------|
| hook-development 技能 | `plugins/plugin-dev/skills/hook-development/` | 核心开发指南 |
| 钩子模式参考 | `plugins/plugin-dev/skills/hook-development/references/patterns.md` | 高级模式 |
| Hookify 插件 | `plugins/hookify/` | 钩子创建示例 |
| 安全提醒插件 | `plugins/security-guidance/` | 安全钩子示例 |

---

<a id='plugin-system'></a>

## 插件系统架构

### 相关页面

相关主题：[官方插件详解](#official-plugins), [斜杠命令系统](#slash-commands), [Agent 代理系统](#agents-system), [Hooks 钩子系统](#hooks-events)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [plugins/plugin-dev/skills/plugin-structure/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/SKILL.md)
- [plugins/plugin-dev/skills/plugin-structure/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/README.md)
- [plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md)
- [plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md)
- [plugins/plugin-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)
- [plugins/plugin-dev/skills/command-development/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/README.md)
- [plugins/pr-review-toolkit/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/pr-review-toolkit/README.md)
- [plugins/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)
</details>

# 插件系统架构

Claude Code 的插件系统是一个模块化的扩展框架，允许开发者通过创建包含多种组件（Skills、Commands、Agents、Hooks、MCP）的插件来增强 Claude Code 的功能。本页详细介绍插件的架构设计、组件类型、开发工作流和最佳实践。

## 1. 系统概述

### 1.1 插件系统的设计理念

Claude Code 插件系统遵循以下核心设计原则：

- **渐进式披露**：插件文档分为元数据层、核心文档层和资源层，用户按需获取信息
- **组件化架构**：每个插件由多个独立但可协作的组件构成
- **声明式配置**：使用 YAML frontmatter 和 Markdown 格式声明组件行为
- **可移植性**：通过 `${CLAUDE_PLUGIN_ROOT}` 环境变量实现路径可移植
- **安全优先**：默认启用 HTTPS 验证，无硬编码凭证

### 1.2 插件与项目的集成关系

插件在 Claude Code 中的加载和执行层级如下：

```mermaid
graph TD
    A[Claude Code 核心] --> B[已安装插件]
    B --> C[项目级配置: .claude/settings.json]
    B --> D[用户级配置: ~/.claude/settings.json]
    C --> E[CLAUDE.md / CLAUDE.local.md]
    D --> F[插件组件]
    F --> G[Skills]
    F --> H[Commands]
    F --> I[Agents]
    F --> J[Hooks]
    F --> K[MCP Servers]
```

资料来源：[plugins/plugin-dev/skills/plugin-structure/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/README.md)

## 2. 插件目录结构

### 2.1 标准目录布局

每个插件遵循统一的目录结构，便于 Claude Code 自动发现和加载组件：

```
plugin-name/
├── manifest.json          # 插件清单（必需）
├── README.md              # 插件文档
├── SKILL.md               # 插件级技能（可选）
├── commands/              # 斜杠命令目录
│   ├── command-name.md
│   └── namespace/
│       └── command-name.md
├── skills/                # 技能目录
│   ├── skill-name/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── detail.md
│   └── another-skill/
├── agents/                # 子代理目录
│   └── agent-name.md
├── hooks/                 # 钩子配置
│   ├── hooks.json
│   └── hook-scripts/
│       └── hook-script.sh
├── mcp/                   # MCP 服务器配置
│   └── .mcp.json
└── examples/              # 示例文件（不会被加载）
```

资料来源：[plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md)

### 2.2 清单文件 (manifest.json)

每个插件必须包含 `manifest.json` 作为入口点，定义插件的基本信息和组件位置：

```json
{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "插件功能描述",
  "author": "作者信息",
  "homepage": "https://github.com/..."
}
```

资料来源：[plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md)

## 3. 组件类型详解

### 3.1 组件类型总览

| 组件类型 | 目录 | 用途 | 加载方式 |
|---------|------|------|---------|
| Skills | `skills/` | 领域知识库和行为指导 | 自动加载到上下文 |
| Commands | `commands/` | 用户可调用的斜杠命令 | `/command-name` 触发 |
| Agents | `agents/` | 自主执行复杂任务的子代理 | 按需启动 |
| Hooks | `hooks/` | 事件驱动的自动化逻辑 | 事件触发 |
| MCP | `mcp/` | 外部服务集成 | 独立进程通信 |

资料来源：[plugins/plugin-dev/skills/plugin-structure/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/SKILL.md)

### 3.2 Skills（技能）

Skills 是插件的核心知识单元，包含特定领域的专业知识和行为指导。

**结构规范：**

```
skills/skill-name/
├── SKILL.md           # 必需：包含 YAML frontmatter 和核心指令
└── references/        # 可选：详细参考文档
    ├── reference-1.md
    └── reference-2.md
```

**SKILL.md 格式：**

```yaml
---
description: 技能触发描述（用第三人称描述技能能力）
trigger: "create a skill", "write a new skill"
---
# Skill Title

核心技能内容...

## 关键要点
- 重要行为准则
- 实现模式
```

**设计原则：**
- 使用第三人称描述（如 "This skill provides..."）
- 行为描述使用祈使句或不定式
- 关键信息放在 SKILL.md 中，详细文档放在 references/

资料来源：[plugins/plugin-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)

### 3.3 Commands（命令）

Commands 是用户通过斜杠触发的可执行操作。

**命令文件格式：**

```markdown
---
description: 命令简短描述
argument-hint: [参数1] [参数2]     # 可选：参数提示
disable-model-invocation: true      # 可选：禁用模型调用
allowed-tools:                     # 可选：限制可用工具
  - Bash(git:*)
  - Read
---

命令主体内容...
使用 $1, $2 引用参数
使用 @file.md 引用文件
使用 !`bash command` 执行 bash
```

**命名空间组织：**

```
commands/
├── deploy.md              # /deploy
├── help.md                # /help
├── utils/
│   ├── lint.md            # /utils:lint
│   └── format.md          # /utils:format
```

资料来源：[plugins/plugin-dev/skills/command-development/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/README.md)

### 3.4 Agents（子代理）

Agents 是能够自主执行复杂任务的子代理，具有独立的目标和工具集。

**Agent 文件格式：**

```yaml
---
description: 代理描述（第一人称说明代理职责）
whenToUse: |
  - 示例场景1
  - 示例场景2
model: sonnet                 # 可选：指定模型
color: blue                   # 可选：UI 颜色
tools:                        # 可选：可用工具
  - Bash
  - Read
---
# Agent System Prompt

代理系统提示词内容...
```

**使用场景示例：**

| Agent | 用途 | 触发场景 |
|-------|------|---------|
| code-explorer | 代码探索和分析 | "探索这段代码的实现" |
| agent-creator | 生成新代理 | "创建一个代码审查代理" |
| plugin-validator | 验证插件质量 | "检查插件是否正确" |

资料来源：[plugins/pr-review-toolkit/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/pr-review-toolkit/README.md)

### 3.5 Hooks（钩子）

Hooks 是在特定事件发生时自动执行的脚本或提示。

**支持的事件类型：**

| 事件 | 触发时机 | 常见用途 |
|------|---------|---------|
| PreToolUse | 工具调用前 | 验证、阻止危险操作 |
| PostToolUse | 工具调用后 | 记录、通知 |
| Stop | 会话结束前 | 确认保存、清理 |
| SubagentStop | 子代理结束前 | 汇总结果 |
| SessionStart | 会话启动时 | 初始化状态 |
| SessionEnd | 会话结束时 | 清理资源 |
| UserPromptSubmit | 用户提交输入时 | 内容过滤 |
| PreCompact | 上下文压缩前 | 保存状态 |
| Notification | 显示通知时 | 自定义通知处理 |

**hooks.json 配置格式：**

```json
{
  "hooks": [
    {
      "event": "PreToolUse",
      "name": "validate-write",
      "prompt": "验证写入操作是否安全..."
    }
  ]
}
```

资料来源：[plugins/plugin-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)

### 3.6 MCP（模型上下文协议）

MCP 允许插件集成外部服务，如数据库、API 等。

**.mcp.json 配置格式：**

```json
{
  "mcpServers": {
    "server-name": {
      "type": "stdio|sse",
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/path/to/server.js"],
      "env": {
        "API_KEY": "${MCP_API_KEY}"
      },
      "extensionToLanguage": {
        ".ts": "typescript",
        ".js": "javascript"
      }
    }
  }
}
```

资料来源：[plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md)

## 4. 插件开发工作流

### 4.1 七阶段开发流程

使用 `/plugin-dev:create-plugin` 命令启动结构化开发流程：

```mermaid
graph TD
    A[Phase 1: 发现] --> B[Phase 2: 组件规划]
    B --> C[Phase 3: 架构设计]
    C --> D[Phase 4: 结构创建]
    D --> E[Phase 5: 组件实现]
    E --> F[Phase 6: 验证]
    F --> G{验证通过?}
    G -->|是| H[Phase 7: 文档]
    G -->|否| E
    H --> I[发布/使用]
```

**各阶段说明：**

| 阶段 | 目标 | 关键输出 |
|------|------|---------|
| 1. 发现 | 理解插件目的 | 插件用途声明 |
| 2. 组件规划 | 确定所需组件 | 组件类型和数量 |
| 3. 架构设计 | 设计组件交互 | 架构文档 |
| 4. 结构创建 | 初始化目录 | 目录结构 |
| 5. 组件实现 | 创建各组件 | 完整代码 |
| 6. 验证 | 质量检查 | 验证报告 |
| 7. 文档 | 编写文档 | README |

资料来源：[plugins/plugin-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)

### 4.2 关键决策点

在以下阶段需要用户确认后继续：

1. **Phase 1 后**：确认插件目的
2. **Phase 2 后**：批准组件计划
3. **Phase 3 后**：进入实现
4. **Phase 6 后**：修复问题或继续
5. **Phase 7 后**：继续到文档

## 5. 插件安装与配置

### 5.1 安装方式

```bash
# 从市场安装
/plugin install plugin-name@claude-code-marketplace

# 指定路径加载（开发用）
cc --plugin-dir /path/to/plugin-dir
```

### 5.2 项目级配置

在项目 `.claude/settings.json` 中配置插件：

```json
{
  "plugins": [
    "plugin-name",
    "another-plugin@1.0.0"
  ]
}
```

### 5.3 用户级配置

在 `~/.claude/settings.json` 中全局启用插件：

```json
{
  "defaultPlugins": [
    "always-enabled-plugin"
  ]
}
```

资料来源：[plugins/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)

## 6. 内置插件示例

Claude Code 仓库内置了多个插件供参考：

| 插件名称 | 功能描述 | 主要组件 |
|---------|---------|---------|
| plugin-dev | 插件开发框架 | 全套组件类型 |
| pr-review-toolkit | PR 审查工具集 | 6 个专业 Agents |
| code-review | 代码审查命令 | Commands + Agents |
| commit-commands | Git 提交辅助 | Commands |
| feature-dev | 功能开发工作流 | 7 阶段流程 |
| hookify | 自定义钩子创建 | Hooks |
| ralph-wiggum | 迭代开发循环 | Commands + Hooks |
| security-guidance | 安全提醒 | PreToolUse Hook |

资料来源：[plugins/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)

## 7. 最佳实践

### 7.1 安全原则

- **HTTPS 优先**：所有外部请求使用 HTTPS
- **无硬编码凭证**：使用环境变量存储敏感信息
- **输入验证**：验证所有用户输入
- **最小权限**：仅请求必要的工具和权限

### 7.2 可移植性

- 使用 `${CLAUDE_PLUGIN_ROOT}` 代替绝对路径
- 相对路径基于插件根目录
- 环境变量支持跨平台运行

### 7.3 文档质量

- SKILL.md 保持简洁，详细信息放在 references/
- 为每个命令提供 argument-hint
- 使用示例代码说明用法
- 包含故障排除指南

### 7.4 代码组织

```mermaid
graph LR
    A[用户输入] --> B[触发短语识别]
    B --> C{组件类型}
    C -->|Skill| D[加载到上下文]
    C -->|Command| E[直接执行]
    C -->|Agent| F[启动子代理]
    C -->|Hook| G[事件监听]
    C -->|MCP| H[外部通信]
```

## 8. 相关资源

- **官方文档**：plugins/README.md
- **开发指南**：plugins/plugin-dev/README.md
- **组件参考**：plugins/plugin-dev/skills/plugin-structure/references/
- **社区插件列表**：awesome-claude-code

## 9. 社区反馈与已知问题

根据社区反馈，以下问题可能影响插件使用：

| 问题 | 影响 | 状态 |
|------|------|------|
| MCP 服务器在 AVX-only CPU 上崩溃 | Windows 用户无法使用部分插件 | 待修复 |
| 插件市场列表加载问题 | 部分用户无法浏览插件 | 待修复 |
| CLAUDE.md 规则未传递给子代理 | 插件中的规则可能被忽略 | 待改进 |

资料来源：[GitHub Issues - Plugin 相关](https://github.com/anthropics/claude-code/issues?q=label%3Aplugin)

---

<a id='official-plugins'></a>

## 官方插件详解

### 相关页面

相关主题：[插件系统架构](#plugin-system), [斜杠命令系统](#slash-commands), [快速上手](#quickstart)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [plugins/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)
- [plugins/plugin-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)
- [plugins/code-review/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/code-review/README.md)
- [plugins/commit-commands/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/commit-commands/README.md)
- [plugins/feature-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/feature-dev/README.md)
- [plugins/hookify/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/README.md)
- [plugins/ralph-wiggum/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/ralph-wiggum/README.md)
- [plugins/security-guidance/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/security-guidance/README.md)
- [plugins/plugin-dev/skills/command-development/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/README.md)
</details>

# 官方插件详解

Claude Code 的官方插件系统提供了可扩展的功能模块，用于增强开发工作流程的各个方面。这些插件涵盖从代码审查、提交管理到安全审计和功能开发的完整工具链。

## 插件系统概述

Claude Code 的插件系统采用模块化架构，每个插件可以包含以下组件类型：

| 组件类型 | 说明 |
|---------|------|
| **Commands** | 斜杠命令（slash commands），用户通过 `/command-name` 触发 |
| **Agents** | 子代理（subagents），专门处理特定任务的 AI 助手 |
| **Hooks** | 钩子函数，在特定事件发生时自动执行 |
| **Skills** | 技能定义，包含专业知识和工作流程指南 |
| **MCP** | 模型上下文协议（Model Context Protocol）集成 |
| **Settings** | 配置管理，支持项目级本地设置 |

资料来源：[plugins/README.md:1-15](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)

## 核心开发插件

### plugin-dev：插件开发框架

plugin-dev 是官方提供的插件开发框架，提供结构化的 7 阶段工作流程，引导开发者从概念到完整插件实现。

```mermaid
graph TD
    A[Phase 1: Discovery<br>理解需求] --> B[Phase 2: Planning<br>组件规划]
    B --> C[Phase 3: Architecture<br>架构设计]
    C --> D[Phase 4: Structure<br>结构创建]
    D --> E[Phase 5: Implementation<br>组件实现]
    E --> F[Phase 6: Validation<br>质量验证]
    F --> G[Phase 7: Testing<br>测试验证]
    G --> H[Phase 8: Documentation<br>文档完善]
```

**关键功能：**

- **自动技能加载**：每个阶段自动加载相关技能（skill），如 `plugin-structure`、`command-development`、`agent-development`
- **AI 辅助生成**：使用 `agent-creator` agent 自动生成子代理代码
- **验证工具**：提供 `validate-agent.sh`、`validate-hook-schema.sh` 等验证脚本
- **渐进式披露**：详细文档存储在 `references/` 和 `examples/` 目录，按需加载

**使用方式：**

```bash
/plugin-dev:create-plugin [可选描述]

# 示例：
/plugin-dev:create-plugin
/plugin-dev:create-plugin 数据库迁移管理插件
```

资料来源：[plugins/plugin-dev/README.md:1-80](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)

### feature-dev：功能开发工作流

feature-dev 专注于结构化的功能开发流程，强调在编写代码之前深入理解代码库。

**7 阶段流程：**

| 阶段 | 目标 | 关键动作 |
|-----|------|---------|
| Discovery | 理解需求 | 澄清问题、识别约束 |
| Codebase Exploration | 理解现有代码 | 并行启动 2-3 个 code-explorer agent |
| Clarifying Questions | 消除歧义 | 识别所有未明确的行为 |
| Architecture Design | 架构设计 | 设计优雅的解决方案 |
| Implementation | 实现 | 遵循最佳实践编写代码 |
| Review | 质量审查 | 代码审查和测试验证 |
| Completion | 完成 | 更新文档、清理 todo |

**核心原则：**

- 在理解代码库后再开始编写代码
- 提出具体、明确的问题，而非假设
- 优先考虑可读性和可维护性
- 使用 TodoWrite 跟踪所有进度

资料来源：[plugins/feature-dev/README.md:1-60](https://github.com/anthropics/claude-code/blob/main/plugins/feature-dev/README.md)

## 代码质量插件

### code-review：代码审查工具

code-review 插件通过 GitHub CLI 自动执行 PR 审查，检查 CLAUDE.md 合规性、代码质量和潜在 bug。

**工作流程：**

```mermaid
graph LR
    A[创建 PR] --> B[/code-review]
    B --> C[启动审查 agents]
    C --> D[分析代码质量]
    C --> E[检查 CLAUDE.md 合规]
    C --> F[识别 bug 和问题]
    D --> G[输出审查报告]
    E --> G
    F --> G
    G --> H[可选：发布为 PR 评论]
```

**使用方法：**

```bash
# 本地审查（输出到终端）
/code-review

# 发布为 PR 评论
/code-review --comment
```

**前置条件：**

- Git 仓库
- GitHub CLI (`gh`) 已安装并认证
- 可选：项目包含 CLAUDE.md 文件

资料来源：[plugins/code-review/README.md:1-80](https://github.com/anthropics/claude-code/blob/main/plugins/code-review/README.md)

### pr-review-toolkit：PR 审查代理套件

pr-review-toolkit 是一套 6 个专业化审查 agent，每个专注于代码质量的特定方面。

| Agent | 职责 | 使用场景 |
|-------|------|---------|
| `comment-analyzer` | 代码注释准确性 | 检查文档是否与代码一致 |
| `pr-test-analyzer` | 测试覆盖质量 | 验证测试完整性和边界情况 |
| `silent-failure-hunter` | 静默失败检测 | 审查错误处理和异常捕获 |
| `type-design-analyzer` | 类型设计分析 | 检查 TypeScript/JavaScript 类型 |
| `code-reviewer` | 综合代码审查 | 遵循 CLAUDE.md 规范 |
| `code-simplifier` | 代码简化重构 | 降低代码复杂度 |

**使用方式：**
直接提出相关问题，Claude 会自动触发对应的 agent：
```
"检查测试是否覆盖所有边界情况" → 触发 pr-test-analyzer
"审查 API 客户端的错误处理" → 触发 silent-failure-hunter
```

资料来源：[plugins/pr-review-toolkit/README.md:1-80](https://github.com/anthropics/claude-code/blob/main/plugins/pr-review-toolkit/README.md)

### security-guidance：安全提醒钩子

security-guidance 提供 PreToolUse 钩子，在执行潜在危险操作前发出安全警告。

**监控的安全模式（9 种）：**

| 类别 | 危险模式 | 说明 |
|------|---------|------|
| 命令注入 | Shell 注入风险 | 未经过滤的用户输入 |
| 跨站脚本 | XSS 漏洞 | 直接插入未转义的用户内容 |
| 代码执行 | eval() 使用 | 动态代码执行风险 |
| HTML 安全 | 危险 HTML 操作 | innerHTML 等不安全 API |
| 序列化安全 | pickle 反序列化 | Python 不安全反序列化 |
| 系统调用 | os.system 调用 | 直接系统命令执行 |

资料来源：[plugins/security-guidance/README.md:1-20](https://github.com/anthropics/claude-code/blob/main/plugins/security-guidance/README.md)

## Git 工作流插件

### commit-commands：提交命令集

commit-commands 提供三个命令，简化 Git 提交和 PR 创建流程。

| 命令 | 用途 | 使用场景 |
|------|------|---------|
| `/commit` | 智能提交 | 常规开发中的快速提交 |
| `/commit-push-pr` | 提交并创建 PR | 完整的功能分支工作流 |
| `/clean_gone` | 清理已删除的远程分支 | 定期维护 |

**工作流集成示例：**

```mermaid
graph TD
    A[编写代码] --> B[/commit]
    B --> C[更多更改]
    C --> D[/commit]
    D --> E[准备创建 PR]
    E --> F[/commit-push-pr]
    F --> G[审查 PR 描述]
    G --> H[合并后]
    H --> I[/clean_gone]
    I --> J[清理完成]
```

**前置条件：**

- Git 已安装并配置
- 对于 `/commit-push-pr`：GitHub CLI (`gh`) 已安装并认证
- 仓库必须是一个 git 仓库并有 remote

资料来源：[plugins/commit-commands/README.md:1-60](https://github.com/anthropics/claude-code/blob/main/plugins/commit-commands/README.md)

## 自动化工作流插件

### ralph-wiggum：迭代循环开发

ralph-wiggum 插件实现自引用 AI 循环，Claude 在同一任务上重复工作直到完成。

**核心功能：**

- **自主迭代**：Claude 持续处理任务，无需每次手动触发
- **中断拦截**：Stop 钩子阻止意外退出，询问是否继续
- **状态保持**：维护迭代状态直到任务完成或手动取消

**使用方式：**

```bash
/ralph-loop  开始自主迭代
/cancel-ralph  取消迭代循环
```

资料来源：[plugins/ralph-wiggum/README.md:1-40](https://github.com/anthropics/claude-code/blob/main/plugins/ralph-wiggum/README.md)

### hookify：自定义钩子创建

hookify 简化了自定义钩子的创建过程，无需编辑复杂的 `hooks.json` 文件。

**核心特性：**

- **对话分析**：自动分析对话模式识别不良行为
- **Markdown 配置**：使用 YAML frontmatter 定义规则
- **正则匹配**：支持强大的正则表达式模式
- **即时生效**：无需重启，下次工具使用即生效

**快速开始：**

```bash
# 基于指令创建规则
/hookify 警告我使用 rm -rf 命令

# 分析对话自动创建规则
/hookify

# 列出所有规则
/hookify:list

# 交互式配置
/hookify:configure
```

**创建的规则文件：**
规则存储在 `.claude/hookify.warn-*.local.md` 文件中

资料来源：[plugins/hookify/README.md:1-60](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/README.md)

## 插件安装与配置

### 安装方式

**从 marketplace 安装：**

```bash
/plugin install plugin-name@claude-code-marketplace
```

**开发模式使用：**

```bash
cc --plugin-dir /path/to/plugin-dev
```

**全局安装后使用：**

```bash
# 全局安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 进入项目目录
cd my-project
claude

# 使用 /plugin 命令安装插件
/plugin install pr-review-toolkit
```

资料来源：[plugins/README.md:40-55](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)

### 项目级配置

插件配置通常存储在项目根目录的 `.claude/settings.json` 中：

```json
{
  "plugins": ["code-review", "commit-commands", "pr-review-toolkit"]
}
```

本地设置可使用 `.claude/plugin-name.local.md` 文件模式

## 社区关注与已知问题

### 相关社区讨论

根据社区反馈，以下问题与插件使用相关：

| Issue | 问题描述 | 状态 |
|-------|---------|------|
| #59309 | CLAUDE.md 规则未传递给 Agent 子代理 | 开放 |
| #59645 | 插件 marketplace 在 AVX-only CPU 上崩溃 | 开放 |
| #59634 | 速率限制感知的延迟提示调度功能请求 | 开放 |

### 使用建议

1. **CLAUDE.md 规则传递**：在复杂的多 agent 工作流中，确保 CLAUDE.md 规则在每个 agent 上下文中明确传递
2. **插件兼容性**：在 Windows AVX-only CPU 环境下注意插件 marketplace 可能的兼容性问题
3. **速率限制**：对于长时间运行的自动化任务，考虑使用 hookify 创建提醒机制

## 插件开发技能体系

plugin-dev 提供了完整的技能开发指南：

| 技能 | 触发短语 | 用途 |
|------|---------|------|
| Hook Development | "create a hook", "PreToolUse hook" | 创建事件钩子 |
| Agent Development | "create an agent", "add an agent" | 开发子代理 |
| Command Development | "create a slash command" | 开发斜杠命令 |
| Skill Development | "create a skill", "add a skill" | 开发新技能 |
| MCP Integration | "add MCP server", "integrate MCP" | 集成外部服务 |
| Plugin Settings | "per-project settings" | 配置管理 |

每个技能包含：
- **核心 SKILL.md**：基本概念和用法
- **References/**：详细规范文档
- **Examples/**：实际工作示例

资料来源：[plugins/plugin-dev/README.md:80-140](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)

## 最佳实践

### 组件设计原则

| 原则 | 说明 |
|------|------|
| 渐进式披露 | 元数据 → SKILL.md → resources |
| 强触发描述 | 使用具体短语而非泛泛描述 |
| 命令式语气 | Skills 使用祈使句编写 |
| 安全性优先 | HTTPS、无硬编码凭证 |
| 可移植性 | 使用 `${CLAUDE_PLUGIN_ROOT}` 变量 |

### 开发流程

1. **规划阶段**：明确插件目标和所需组件类型
2. **结构创建**：使用 plugin-structure skill 建立目录
3. **组件实现**：按技能指南实现每个组件
4. **验证测试**：运行验证脚本确保质量
5. **文档完善**：编写清晰的 README 和使用说明

资料来源：[plugins/plugin-dev/skills/command-development/README.md:80-120](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/README.md)

---

<a id='settings-management'></a>

## 设置与配置管理

### 相关页面

相关主题：[企业托管设置](#managed-settings), [项目概览](#overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [examples/settings/README.md](https://github.com/anthropics/claude-code/blob/main/examples/settings/README.md)
- [examples/settings/settings-strict.json](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-strict.json)
- [examples/settings/settings-lax.json](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-lax.json)
- [examples/settings/settings-bash-sandbox.json](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-bash-sandbox.json)
- [plugins/plugin-dev/skills/plugin-settings/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-settings/SKILL.md)
</details>

# 设置与配置管理

Claude Code 提供了灵活的配置系统，允许用户在全局、项目和插件级别管理设置。本文档介绍 Claude Code 的配置管理架构、配置方法以及常见配置场景。

## 配置架构概述

Claude Code 采用分层配置架构，支持从全局默认值到项目特定设置的渐进式覆盖。

```mermaid
graph TD
    A[用户主目录 ~/.claude/settings.json] --> B[项目级 .claude/settings.json]
    B --> C[环境变量配置]
    C --> D[运行时配置]
    E[插件级设置 .claude/plugin-name.local.md] --> D
```

配置优先级从高到低依次为：
1. 环境变量
2. 项目级配置文件
3. 用户主目录全局配置
4. Claude Code 默认值

## 全局设置管理

### 配置文件位置

Claude Code 全局配置存储在用户主目录的 `~/.claude/settings.json` 文件中。

### 核心配置选项

Claude Code 支持多种配置选项来定制行为：

| 配置项 | 类型 | 说明 | 常见值 |
|--------|------|------|--------|
| `defaultMode` | string | 默认权限模式 | `"auto"`, `"plan"`, `"browse"` |
| `maxTokens` | number | 单次响应最大令牌数 | 2000-8000 |
| `Temperature` | number | 生成温度参数 | 0.0-1.0 |
| `permissionMode` | string | 权限控制模式 | `"auto"`, `"skip"` |

### 权限模式配置

根据社区反馈，`defaultMode` 设置在某些场景下可能不会正确继承到新会话中。 资料来源：[社区 Issue #55558](https://github.com/anthropics/claude-code/issues/55558)

```json
{
  "defaultMode": "auto",
  "permissionMode": "auto"
}
```

**注意**：当 `defaultMode` 设置为 `"auto"` 时，该配置不会自动继承到新打开的会话中，这是已知的限制。 资料来源：[社区 Issue #55558](https://github.com/anthropics/claude-code/issues/55558)

## 环境变量配置

Claude Code 通过环境变量支持高级配置选项：

| 环境变量 | 说明 | 示例值 |
|----------|------|--------|
| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 启用 Auto 模式 | `1` |
| `ANTHROPIC_API_KEY` | API 密钥配置 | `sk-...` |
| `CLAUDE_CODE_BASE_URL` | 自定义 API 端点 | `https://api.anthropic.com` |

### Auto 模式配置

最新版本 v2.1.158 在 Bedrock、Vertex 和 Foundry 平台上为 Opus 4.7 和 Opus 4.8 模型启用了 Auto 模式。 资料来源：[最新发布说明](https://github.com/anthropics/claude-code/releases/tag/v2.1.158)

启用方式：
```bash
export CLAUDE_CODE_ENABLE_AUTO_MODE=1
```

## 插件设置管理

### 设置文件结构

插件使用 `.claude/plugin-name.local.md` 模式存储项目特定配置。 资料来源：[plugins/plugin-dev/skills/plugin-settings/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-settings/SKILL.md)

```
.claude/
├── plugin-name.local.md    # 插件本地配置
└── settings.json           # 通用设置
```

### 配置格式

插件设置文件采用 YAML frontmatter + Markdown 内容的结构：

```markdown
---
api-key: "your-api-key"
endpoint: "https://api.example.com"
timeout: 30
---

# 插件配置说明

此插件需要以上配置才能正常工作。
```

### 解析配置技术

在 Bash 脚本中解析 frontmatter 配置的常用方法： 资料来源：[plugins/plugin-dev/skills/plugin-settings/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-settings/SKILL.md)

```bash
# 使用 sed 提取配置值
API_KEY=$(sed -n '/^---$/,/^---$/{/api-key:/p}' "$CONFIG_FILE" | sed 's/.*api-key: *//')

# 使用 awk 解析 YAML
API_KEY=$(awk '/^api-key:/ {print $2}' "$CONFIG_FILE")
```

## 预设配置示例

### 严格模式配置

适用于需要高安全性和最小化风险的项目： 资料来源：[examples/settings/settings-strict.json](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-strict.json)

```json
{
  "permissionMode": "skip",
  "maxTokens": 2000,
  "temperature": 0.0,
  "dangerouslySkipVa": false
}
```

### 宽松模式配置

适用于可信环境和快速迭代： 资料来源：[examples/settings/settings-lax.json](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-lax.json)

```json
{
  "permissionMode": "auto",
  "maxTokens": 8000,
  "temperature": 0.7
}
```

### Bash 沙箱配置

适用于受限执行环境： 资料来源：[examples/settings/settings-bash-sandbox.json](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-bash-sandbox.json)

```json
{
  "bashTimeout": 30000,
  "maxConcurrentBash": 2,
  "sandboxMode": "restricted"
}
```

## 常见配置场景

### 场景一：速率限制与配额管理

用户报告每周限制计数器在实际运行中约每 24 小时重置一次，而非文档所述的 7 天周期。 资料来源：[社区 Issue #52921](https://github.com/anthropics/claude-code/issues/52921)

```mermaid
graph LR
    A[请求发送] --> B{检查配额}
    B -->|有余额| C[执行请求]
    B -->|配额耗尽| D[等待重置]
    C --> E[扣减配额]
    D --> F[24小时周期检查]
    F -->|到达重置时间| E
```

### 场景二：延迟提示调度

社区请求在遇到速率限制时实现智能延迟调度功能。 资料来源：[社区 Issue #59634](https://github.com/anthropics/claude-code/issues/59634)

### 场景三：多项目配置隔离

为不同项目维护独立的配置文件：

```bash
# 项目 A 配置
/project-a/.claude/settings.json

# 项目 B 配置  
/project-b/.claude/settings.json
```

## 配置验证

### 验证工具

Claude Code 提供配置验证脚本来检查设置有效性：

```bash
# 验证 JSON 格式
cat ~/.claude/settings.json | jq .

# 验证插件设置
./scripts/validate-settings.sh
```

### 常见配置错误

| 错误类型 | 症状 | 解决方案 |
|----------|------|----------|
| JSON 格式错误 | 配置不生效 | 使用 `jq .` 验证语法 |
| 权限不足 | 操作被拒绝 | 检查文件权限 |
| 模式不匹配 | 意外行为 | 参考示例配置文件 |

## 最佳实践

1. **使用版本控制**：将项目级配置纳入版本控制
2. **敏感信息分离**：将 API 密钥等敏感信息放在本地忽略的文件中
3. **渐进式配置**：从宽松配置开始，逐步收紧
4. **定期检查**：使用 `/model` 命令验证当前配置
5. **文档化配置**：为团队成员记录配置变更原因

```bash
# .gitignore 中排除本地配置
echo ".claude/*.local.md" >> .gitignore
```

## 故障排除

### 配置不生效

如果设置更改后未生效：
1. 确认配置文件路径正确
2. 验证 JSON 语法
3. 重启 Claude Code 会话
4. 检查环境变量是否覆盖了配置文件

### 权限模式问题

当 `auto` 模式不按预期工作时，可以尝试：
- 显式设置 `permissionMode` 而非依赖 `defaultMode`
- 在每个新会话开始时手动设置模式

### 模型加载卡顿

社区报告 `/model` 命令在 VSCode 扩展中可能无限期卡在 "Loading models..." 状态。 资料来源：[社区 Issue #59646](https://github.com/anthropics/claude-code/issues/59646)

如遇此问题，请尝试：
- 手动指定模型而非使用自动选择
- 检查网络连接状态

## 相关资源

- [Claude Code 官方文档](https://docs.anthropic.com/claude-code)
- [插件开发指南](./plugins/plugin-dev/)
- [命令行参考](./reference/cli.md)

---

<a id='managed-settings'></a>

## 企业托管设置

### 相关页面

相关主题：[设置与配置管理](#settings-management), [项目概览](#overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [examples/mdm/README.md](https://github.com/anthropics/claude-code/blob/main/examples/mdm/README.md)
- [examples/mdm/macos/com.anthropic.claudecode.mobileconfig](https://github.com/anthropics/claude-code/blob/main/examples/mdm/macos/com.anthropic.claudecode.mobileconfig)
- [examples/mdm/macos/com.anthropic.claudecode.plist](https://github.com/anthropics/claude-code/blob/main/examples/mdm/macos/com.anthropic.claudecode.plist)
- [examples/mdm/windows/ClaudeCode.admx](https://github.com/anthropics/claude-code/blob/main/examples/mdm/windows/ClaudeCode.admx)
- [examples/mdm/windows/Set-ClaudeCodePolicy.ps1](https://github.com/anthropics/claude-code/blob/main/examples/mdm/windows/Set-ClaudeCodePolicy.ps1)
</details>

# 企业托管设置

## 概述

Claude Code 支持企业级托管部署，通过移动设备管理（MDM）解决方案实现跨平台策略管理。管理员可以使用标准化的企业配置工具在 macOS 和 Windows 设备上统一部署和配置 Claude Code，覆盖权限管理、使用限制、安全策略等多个方面。

该功能使组织能够在保护敏感数据的同时，保持对开发工具的集中控制，确保所有团队成员使用一致的配置运行 Claude Code。

## 平台支持

Claude Code 的企业托管设置覆盖两大主流桌面操作系统：

| 平台 | 配置格式 | 配置文件 | 管理工具 |
|------|----------|----------|----------|
| macOS | mobileconfig / plist | `com.anthropic.claudecode.mobileconfig`<br>`com.anthropic.claudecode.plist` | Apple Configurator、JAMF、 Kandji、Jamf Pro |
| Windows | ADMX / PowerShell | `ClaudeCode.admx`<br>`Set-ClaudeCodePolicy.ps1` | Microsoft Intune、Group Policy、SCCM |

## 目录结构

MDM 配置示例的完整目录结构如下：

```
examples/mdm/
├── README.md
├── macos/
│   ├── com.anthropic.claudecode.mobileconfig
│   └── com.anthropic.claudecode.plist
└── windows/
    ├── ClaudeCode.admx
    └── Set-ClaudeCodePolicy.ps1
```

## macOS 配置

### MobileConfig 配置文件

macOS 平台使用 Apple 的 mobileconfig 格式，这是一种 XML 格式的配置文件，用于描述配置概要（Configuration Profile）。`com.anthropic.claudecode.mobileconfig` 文件定义了 Claude Code 在 macOS 设备上的企业策略。

mobileconfig 文件的核心结构包括：

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "...">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <!-- 配置项定义 -->
    </array>
</dict>
</plist>
```

### Property List 配置

`com.anthropic.claudecode.plist` 是标准的 macOS 属性列表文件，定义了 Claude Code 的具体配置参数。Property List 通常用于存储应用程序的偏好设置，可以通过以下方式部署：

1. **通过 MDM 推送**：由 MDM 解决方案自动部署到托管设备
2. **手动安装**：用户双击配置文件进行安装
3. **命令行工具**：使用 `defaults` 命令读取和写入配置

### 配置 Payload 结构

macOS 配置文件中的关键 Payload 包括：

| Payload 键 | 类型 | 说明 |
|------------|------|------|
| `PayloadIdentifier` | String | 配置文件的唯一标识符 |
| `PayloadUUID` | String | Payload 的全局唯一标识符 |
| `PayloadType` | String | Payload 类型（通常为 `com.apple.ManagedClient`） |
| `PayloadVersion` | Integer | Payload 版本号 |

## Windows 配置

### ADMX 策略定义

Windows 平台使用 ADMX（Administrative Template XML）格式定义组策略。`ClaudeCode.admx` 文件是组策略管理模板，允许管理员通过 Active Directory 或本地组策略编辑器配置 Claude Code。

ADMX 文件的主要组成部分：

```xml
<policyDefinitions>
    <policyNamespaces>
        <target prefix="claudecode" namespace="..." />
    </policyNamespaces>
    <supersededAdmFileName />
    <categories>
        <category name="..." />
    </categories>
    <policies>
        <policy ...>
            <elements>...</elements>
        </policy>
    </policies>
</policyDefinitions>
```

### PowerShell 部署脚本

`Set-ClaudeCodePolicy.ps1` 是 Windows 平台的 PowerShell 部署脚本，用于自动化应用配置策略。该脚本支持：

- **静默部署**：无需用户交互即可应用配置
- **批量操作**：通过网络策略服务器批量应用到多台设备
- **配置验证**：部署后验证策略是否正确应用

### ADMX 策略类别

Windows 策略通常按功能分类组织，便于管理员在组策略编辑器中查找和配置：

| 策略类别 | 说明 | 典型配置项 |
|----------|------|------------|
| **常规设置** | 基本运行参数 | 启动行为、日志级别 |
| **安全策略** | 权限和访问控制 | 权限模式、API 密钥管理 |
| **网络设置** | 代理和连接配置 | 代理服务器、超时设置 |
| **更新策略** | 自动更新控制 | 禁用自动更新、版本锁定 |

## 托管策略详解

### 权限管理模式

企业托管设置支持配置 Claude Code 的权限模式，这是社区中用户关注的一个配置项。根据社区反馈，默认权限模式设置为 `"auto"` 时不会在新会话中继承，且无法在会话中途更改。

托管策略可以预先配置以下权限模式：

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `manual` | 每次操作前请求用户确认 | 高安全要求环境 |
| `auto` | 自动批准已知安全操作 | 标准开发环境 |
| `bypass` | 完全禁用权限检查 | 受信任的自动化场景 |

**注意**：根据社区 Issue #55558，当 `defaultMode` 设置为 `"auto"` 时，该设置不会自动继承到新会话。建议通过 MDM 统一配置以确保所有会话使用一致的权限策略。

### 使用限制配置

企业托管设置允许管理员配置使用限制策略，包括：

- **每周使用上限**：限制每个用户的每周请求配额
- **会话超时**：设置空闲会话自动断开时间
- **并发会话数**：限制同一用户的并发会话数量

**已知问题**：根据社区 Issue #52921，每周限制计数器约每 24 小时重置一次，而非文档所述的 7 天周期。管理员在配置使用限制时应考虑这一行为差异。

## 部署工作流

```mermaid
graph TD
    A[准备配置文件] --> B{选择目标平台}
    B -->|macOS| C[生成 mobileconfig 或 plist]
    B -->|Windows| D[准备 ADMX 或 PowerShell 脚本]
    C --> E[上传到 MDM 服务器]
    D --> E
    E --> F{MDM 服务器类型}
    F -->|Jamf Pro| G[创建配置文件并分配]
    F -->|Intune| H[创建应用配置策略]
    F -->|其他| I[使用通用部署方法]
    G --> J[分配目标设备/用户]
    H --> J
    I --> J
    J --> K{验证部署}
    K -->|成功| L[配置生效]
    K -->|失败| M[排查问题]
    M --> E
```

## 常见配置项

### API 密钥管理

托管环境通常需要集中管理 API 密钥：

| 配置项 | 说明 | 推荐值 |
|--------|------|--------|
| `apiKey` | Anthropic API 密钥 | 通过密钥管理服务注入 |
| `apiEndpoint` | 自定义 API 端点 | 企业内部端点（如适用） |

### 网络和代理设置

| 配置项 | 说明 |
|--------|------|
| `httpProxy` | HTTP 代理服务器地址 |
| `httpsProxy` | HTTPS 代理服务器地址 |
| `noProxy` | 跳过代理的地址列表 |
| `timeout` | 请求超时时间（秒） |

### 日志和诊断

| 配置项 | 说明 |
|--------|------|
| `logLevel` | 日志详细程度（debug/info/warn/error） |
| `logPath` | 自定义日志存储路径 |
| `telemetryEnabled` | 遥测数据收集开关 |

## 故障排除

### macOS 部署问题

| 问题 | 解决方案 |
|------|----------|
| 配置文件未安装 | 检查设备是否已注册到 MDM，确认用户有安装权限 |
| 配置不生效 | 重启 Claude Code 或重新登录用户会话 |
| 权限模式未继承 | 通过 MDM 强制部署 `defaultMode` 设置 |

### Windows 部署问题

| 问题 | 解决方案 |
|------|----------|
| 策略未应用 | 运行 `gpupdate /force` 强制刷新组策略 |
| PowerShell 脚本被阻止 | 使用 `Set-ExecutionPolicy` 调整脚本执行策略 |
| ADMX 模板未加载 | 将 ADMX 文件复制到正确的策略定义存储位置 |

## 安全考虑

### 数据保护

企业托管设置应遵循以下安全最佳实践：

1. **密钥管理**：使用企业密钥管理解决方案存储敏感配置
2. **传输安全**：确保配置文件通过加密通道传输
3. **访问控制**：限制 MDM 控制台访问权限
4. **审计日志**：启用配置变更审计以便追踪

### 合规性

根据组织合规要求，可能需要配置以下设置：

- **数据驻留**：配置使用区域性 API 端点
- **遥测控制**：在受监管行业中可能需要禁用遥测
- **日志保留**：配置合规的日志保留策略

## 参考资料

- [MDM 配置示例目录](https://github.com/anthropics/claude-code/tree/main/examples/mdm)
- [macOS mobileconfig 配置](https://github.com/anthropics/claude-code/blob/main/examples/mdm/macos/com.anthropic.claudecode.mobileconfig)
- [macOS plist 配置](https://github.com/anthropics/claude-code/blob/main/examples/mdm/macos/com.anthropic.claudecode.plist)
- [Windows ADMX 策略定义](https://github.com/anthropics/claude-code/blob/main/examples/mdm/windows/ClaudeCode.admx)
- [Windows PowerShell 部署脚本](https://github.com/anthropics/claude-code/blob/main/examples/mdm/windows/Set-ClaudeCodePolicy.ps1)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：anthropics/claude-code

摘要：发现 39 个潜在踩坑项，其中 16 个为 high/blocking；最高优先级：安装坑 - 来源证据：Extended thinking: signed thinking block 'cannot be modified' (400) permanently wedges session。

## 1. 安装坑 · 来源证据：Extended thinking: signed thinking block 'cannot be modified' (400) permanently wedges session

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Extended thinking: signed thinking block 'cannot be modified' (400) permanently wedges session
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6fd2423d8dd840ad898450c124291027 | https://github.com/anthropics/claude-code/issues/63335 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：[BUG] Old sessions do not open, also cannot start new sessions

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Old sessions do not open, also cannot start new sessions
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_abbd745212d743c6b17ef3e919d49b0d | https://github.com/anthropics/claude-code/issues/64109 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 3. 配置坑 · 来源证据：Feature Request: Cross-device session sync between desktop and mobile

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Feature Request: Cross-device session sync between desktop and mobile
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_cd5af4117b394f29bd45302db852a9e9 | https://github.com/anthropics/claude-code/issues/61298 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 配置坑 · 来源证据：Session titles generated in English despite locale set to ko-KR

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Session titles generated in English despite locale set to ko-KR
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e75af4578a6c41e8820a88e1e8b8d617 | https://github.com/anthropics/claude-code/issues/64111 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 5. 配置坑 · 来源证据：Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellat…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellation)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_262f6cbca571401884333f86087e0ddd | https://github.com/anthropics/claude-code/issues/64095 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 6. 配置坑 · 来源证据：[Bug] Anthropic API Error: Cannot modify thinking blocks in assistant messages

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] Anthropic API Error: Cannot modify thinking blocks in assistant messages
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9c64894658eb475f9ad68245eed8d2f5 | https://github.com/anthropics/claude-code/issues/64094 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

## 7. 能力坑 · 来源证据：Shift+Enter to Control+J in Terminal

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：Shift+Enter to Control+J in Terminal
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e0c0e16324d045f38cb9237f7f4dfff6 | https://github.com/anthropics/claude-code/issues/64115 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 8. 运行坑 · 来源证据：[FEATURE] Continue when the session limit reached

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[FEATURE] Continue when the session limit reached
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a1a5923e7779438ca2f53dafbaf38d00 | https://github.com/anthropics/claude-code/issues/13354 | 来源类型 github_issue 暴露的待验证使用条件。

## 9. 安全/权限坑 · 失败模式：security_permissions: Remote Control (/remote-control) disconnects frequently

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: Remote Control (/remote-control) disconnects frequently
- 对用户的影响：Developers may expose sensitive permissions or credentials: Remote Control (/remote-control) disconnects frequently
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Remote Control (/remote-control) disconnects frequently. Context: Observed when using windows, macos, linux
- 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/anthropics/claude-code/issues/33041
- 证据：failure_mode_cluster:github_issue | fmev_9c4c7261c368bad5ca3425e0acae9cca | https://github.com/anthropics/claude-code/issues/33041 | Remote Control (/remote-control) disconnects frequently

## 10. 安全/权限坑 · 失败模式：security_permissions: [BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating...

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: [BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linux)
- 对用户的影响：Developers may expose sensitive permissions or credentials: [BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linux)
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linux). Context: Observed when using node, linux
- 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/anthropics/claude-code/issues/50423
- 证据：failure_mode_cluster:github_issue | fmev_8458acfcfab9d6641fe4696ba1202131 | https://github.com/anthropics/claude-code/issues/50423 | [BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linux)

## 11. 安全/权限坑 · 来源证据：Model fabricates tool output (and even a user instruction) when a parallel batch is partially cancelled / appears empty

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Model fabricates tool output (and even a user instruction) when a parallel batch is partially cancelled / appears empty
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1448fd32254e42c7a13bb07c4d4b376e | https://github.com/anthropics/claude-code/issues/63538 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 12. 安全/权限坑 · 来源证据：Remote Control (/remote-control) disconnects frequently

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Remote Control (/remote-control) disconnects frequently
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_88549375cbdc40f5b59125e4fbda8e11 | https://github.com/anthropics/claude-code/issues/33041 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 13. 安全/权限坑 · 来源证据：[BUG] API Error: Usage credits required for 1M context

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] API Error: Usage credits required for 1M context
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_87e11d1be1a941db9b9a16f57f0303ef | https://github.com/anthropics/claude-code/issues/64117 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 14. 安全/权限坑 · 来源证据：[BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session — commands silently dropped

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session — commands silently dropped
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_79e2cfaaa0d840d0ad2301e7fdee0458 | https://github.com/anthropics/claude-code/issues/64112 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 15. 安全/权限坑 · 来源证据：[BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linu…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linux)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ff2e3e5c8d8544f49fb33923239ce9ae | https://github.com/anthropics/claude-code/issues/50423 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 16. 安全/权限坑 · 来源证据：[MODEL] Opus 4.8 starts hallucinating results before parallel tasks finish

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MODEL] Opus 4.8 starts hallucinating results before parallel tasks finish
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_72142433607342c683efa2dfd91727e1 | https://github.com/anthropics/claude-code/issues/63884 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 17. 安装坑 · 失败模式：installation: [BUG] Old sessions do not open, also cannot start new sessions

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [BUG] Old sessions do not open, also cannot start new sessions
- 对用户的影响：Developers may fail before the first successful local run: [BUG] Old sessions do not open, also cannot start new sessions
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Old sessions do not open, also cannot start new sessions. Context: Observed when using windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_369baf02a3bc53ab601dee041b939afe | https://github.com/anthropics/claude-code/issues/64109 | [BUG] Old sessions do not open, also cannot start new sessions

## 18. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:937253475 | https://github.com/anthropics/claude-code | host_targets=claude, claude_code

## 19. 配置坑 · 失败模式：configuration: Feature Request: Cross-device session sync between desktop and mobile

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Feature Request: Cross-device session sync between desktop and mobile
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Feature Request: Cross-device session sync between desktop and mobile
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Feature Request: Cross-device session sync between desktop and mobile. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_283825ec99bcea39a11f0a6e6c298804 | https://github.com/anthropics/claude-code/issues/61298 | Feature Request: Cross-device session sync between desktop and mobile

## 20. 配置坑 · 失败模式：configuration: Harness silently executes duplicated parallel tool_use blocks: subagent fan-out runs N× the i...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Harness silently executes duplicated parallel tool_use blocks: subagent fan-out runs N× the intended count (6 → 24)
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Harness silently executes duplicated parallel tool_use blocks: subagent fan-out runs N× the intended count (6 → 24)
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Harness silently executes duplicated parallel tool_use blocks: subagent fan-out runs N× the intended count (6 → 24). Context: Observed during installation or first-run setup.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_a856115bae11a139a2c97e4617737eed | https://github.com/anthropics/claude-code/issues/64080 | Harness silently executes duplicated parallel tool_use blocks: subagent fan-out runs N× the intended count (6 → 24)

## 21. 配置坑 · 失败模式：configuration: Session titles generated in English despite locale set to ko-KR

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Session titles generated in English despite locale set to ko-KR
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Session titles generated in English despite locale set to ko-KR
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Session titles generated in English despite locale set to ko-KR. Context: Observed when using windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_0388434519fd0a36700613913cb137e0 | https://github.com/anthropics/claude-code/issues/64111 | Session titles generated in English despite locale set to ko-KR

## 22. 配置坑 · 失败模式：configuration: [FEATURE] Multi-account switching in Claude Mobile app without shared email

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: [FEATURE] Multi-account switching in Claude Mobile app without shared email
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [FEATURE] Multi-account switching in Claude Mobile app without shared email
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [FEATURE] Multi-account switching in Claude Mobile app without shared email. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_13a40dd6b5f966f8cf8d81e22aa64f3e | https://github.com/anthropics/claude-code/issues/36151 | [FEATURE] Multi-account switching in Claude Mobile app without shared email

## 23. 配置坑 · 来源证据：Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on-screen evidence the port…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on-screen evidence the port was the host resolver
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d98a409f57c74c26a5ba696527e6c1b0 | https://github.com/anthropics/claude-code/issues/64110 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 24. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:937253475 | https://github.com/anthropics/claude-code | README/documentation is current enough for a first validation pass.

## 25. 运行坑 · 失败模式：runtime: [FEATURE] Continue when the session limit reached

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: [FEATURE] Continue when the session limit reached
- 对用户的影响：Developers may hit a documented source-backed failure mode: [FEATURE] Continue when the session limit reached
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [FEATURE] Continue when the session limit reached. Context: Source discussion did not expose a precise runtime context.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_0940bbcf61d4a9404571f32848072c7d | https://github.com/anthropics/claude-code/issues/13354 | [FEATURE] Continue when the session limit reached

## 26. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:937253475 | https://github.com/anthropics/claude-code | last_activity_observed missing

## 27. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:937253475 | https://github.com/anthropics/claude-code | no_demo; severity=medium

## 28. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:937253475 | https://github.com/anthropics/claude-code | no_demo; severity=medium

## 29. 安全/权限坑 · 来源证据：Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2cc9f1b9f9da461b8ec530dcb1cdf6fa | https://github.com/anthropics/claude-code/issues/64106 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 30. 能力坑 · 失败模式：capability: Tool calls intermittently emitted as literal text (stray 'court' + raw <invoke>) instead of e...

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Tool calls intermittently emitted as literal text (stray 'court' + raw <invoke>) instead of executing — mostly Edit/Read (Opus, CLI)
- 对用户的影响：Developers may hit a documented source-backed failure mode: Tool calls intermittently emitted as literal text (stray 'court' + raw <invoke>) instead of executing — mostly Edit/Read (Opus, CLI)
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Tool calls intermittently emitted as literal text (stray 'court' + raw <invoke>) instead of executing — mostly Edit/Read (Opus, CLI). Context: Observed when using macos
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_2933d9f47cbf4f5f4fb221bac31ceb7d | https://github.com/anthropics/claude-code/issues/64108 | Tool calls intermittently emitted as literal text (stray 'court' + raw <invoke>) instead of executing — mostly Edit/Read (Opus, CLI)

## 31. 能力坑 · 失败模式：capability: Tool-result envelope injected into tool-call input channel during parallel tool batches (corr...

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellation)
- 对用户的影响：Developers may hit a documented source-backed failure mode: Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellation)
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellation). Context: Observed when using macos
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_c36dedf952efb0b87258d9add70eb890 | https://github.com/anthropics/claude-code/issues/64095 | Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellation)

## 32. 能力坑 · 失败模式：capability: [BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: [BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited
- 对用户的影响：Developers may hit a documented source-backed failure mode: [BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited. Context: Observed when using windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_f149428db4eaf50a33b3d1a869e10e0a | https://github.com/anthropics/claude-code/issues/53915 | [BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited

## 33. 能力坑 · 失败模式：capability: [BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session —...

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: [BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session — commands silently dropped
- 对用户的影响：Developers may hit a documented source-backed failure mode: [BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session — commands silently dropped
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session — commands silently dropped. Context: Observed when using macos
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_90aaa75e00b64d60d6925606deeeac09 | https://github.com/anthropics/claude-code/issues/64112 | [BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session — commands silently dropped

## 34. 能力坑 · 失败模式：capability: [Bug] Anthropic API Error: Server Rate Limiting on Recurring Requests

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: [Bug] Anthropic API Error: Server Rate Limiting on Recurring Requests
- 对用户的影响：Developers may hit a documented source-backed failure mode: [Bug] Anthropic API Error: Server Rate Limiting on Recurring Requests
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug] Anthropic API Error: Server Rate Limiting on Recurring Requests. Context: Observed when using macos
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_74b4a063bf7b78b902bf847b1e15998c | https://github.com/anthropics/claude-code/issues/64101 | [Bug] Anthropic API Error: Server Rate Limiting on Recurring Requests

## 35. 能力坑 · 失败模式：conceptual: Cancelling a parallel tool-call batch corrupts thinking blocks -> 400 "thinking blocks cannot...

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: Cancelling a parallel tool-call batch corrupts thinking blocks -> 400 "thinking blocks cannot be modified" permanently wedges the session
- 对用户的影响：Developers may hit a documented source-backed failure mode: Cancelling a parallel tool-call batch corrupts thinking blocks -> 400 "thinking blocks cannot be modified" permanently wedges the session
- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_c47900c3ee637585906fc588a2c5cca4 | https://github.com/anthropics/claude-code/issues/63192 | Cancelling a parallel tool-call batch corrupts thinking blocks -> 400 "thinking blocks cannot be modified" permanently wedges the session

## 36. 能力坑 · 失败模式：conceptual: Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on...

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on-screen evidence the port was the host resolver
- 对用户的影响：Developers may hit a documented source-backed failure mode: Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on-screen evidence the port was the host resolver
- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_412c2e9812e680366a198d368bc09d58 | https://github.com/anthropics/claude-code/issues/64110 | Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on-screen evidence the port was the host resolver

## 37. 能力坑 · 失败模式：conceptual: Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8
- 对用户的影响：Developers may hit a documented source-backed failure mode: Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8
- 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_fae94d46beb702ecb9e71f49ebeb7268 | https://github.com/anthropics/claude-code/issues/64106 | Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8

## 38. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:937253475 | https://github.com/anthropics/claude-code | issue_or_pr_quality=unknown

## 39. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:937253475 | https://github.com/anthropics/claude-code | release_recency=unknown

<!-- canonical_name: anthropics/claude-code; human_manual_source: deepwiki_human_wiki -->