Claude Code 学习手册

文档核心说明

本文档适用于 Claude Code 的入门到进阶用户，整合了从基础安装到高级配置的完整知识，覆盖：

• 基础安装与认证配置

• 层级架构与工作原理

• 核心使用方法与快捷键

• 扩展生态（Skills、MCP 服务器）

• 高级配置与性能优化

• 版本升级与问题修复

一、基础入门

1.1 什么是 Claude Code

Claude Code 是 Anthropic 推出的代理式编码系统，能够自主理解整个代码库、跨多个文件进行修改、运行命令、执行测试，并最终交付可提交的代码。

1.2 系统要求

• 操作系统：macOS 13.0+、Windows 10 1809+、Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+

• 硬件：4GB+ RAM，x64 或 ARM64 处理器

• 网络：互联网连接

• 账户：需要 Claude Pro、Max、Team、Enterprise 或 Console 账户（免费计划不包含 Claude Code）

1.3 下载安装

原生安装（自动更新，推荐）

macOS, Linux, WSL:

1

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

1

irm https://claude.ai/install.ps1 | iex

Windows CMD:

1

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

包管理器安装

Homebrew (macOS):

1
2
3
4
5

# 稳定版（约一周更新一次）
brew install --cask claude-code

# 最新版（实时更新）
brew install --cask claude-code@latest

WinGet (Windows):

1

winget install Anthropic.ClaudeCode

Linux 包管理器:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Debian/Ubuntu
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update && sudo apt install claude-code

# Fedora/RHEL
sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

npm 安装

1

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

1.4 验证安装

1
2
3
4
5

# 查看版本
claude --version

# 全面检查安装和配置
claude doctor

1.5 首次认证

安装完成后，在终端中运行：

1
2

cd your-project-directory
claude

系统会自动打开浏览器，引导您完成 OAuth 认证流程。

二、层级架构

2.1 三层功能架构（用户视角）

这是最常用的功能划分，将系统分为三个功能层：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

┌─────────────────────────────────────────────────────────┐
│                    EXTENSION LAYER                      │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  外部工具集成、确定性自动化、领域专业知识、打包扩展    │
├─────────────────────────────────────────────────────────┤
│                    DELEGATION LAYER                     │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Subagents (最多10个并行)            │    │
│  │   探索型 | 规划型 | 通用型 | 自定义              │    │
│  └─────────────────────────────────────────────────┘    │
│  隔离上下文专注工作，仅返回摘要给主代理                │
├─────────────────────────────────────────────────────────┤
│                      CORE LAYER                         │
│  ┌─────────────────────────────────────────────────┐    │
│  │              主代理循环 + 共享上下文             │    │
│  │   200K tokens(标准) | 1M tokens(Opus 4.6)       │    │
│  └─────────────────────────────────────────────────┘    │
│  主对话、任务协调、最终决策                            │
└─────────────────────────────────────────────────────────┘

核心层（Core Layer）

• 主代理循环和共享上下文窗口

• 8 个核心内置工具

• 上下文压缩管道

• 标准 200K tokens 上下文，Opus 4.6 支持 1M tokens

委托层（Delegation Layer）

• 子代理系统，最多支持 10 个并行子代理

• 每个子代理拥有独立的干净上下文窗口

• 完成任务后仅返回摘要给主代理，避免主上下文膨胀

扩展层（Extension Layer）

• Hooks：事件驱动的脚本

• Skills：封装可复用的专业知识

• Plugins：打包可分发的扩展包

• MCP 服务器：连接外部工具和数据源

2.2 五层系统架构（技术视角）

基于源代码分析的技术实现划分：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

┌─────────────────────────────────────────────────────────┐
│                    SURFACE LAYER                        │
│  交互式CLI | 无头CLI | Agent SDK | IDE集成 | 桌面应用  │
│  负责用户输入和结果展示                                │
├─────────────────────────────────────────────────────────┤
│                      CORE LAYER                         │
│  代理循环 | 五层上下文压缩管道 | 状态机                │
│  核心决策和迭代逻辑                                    │
├─────────────────────────────────────────────────────────┤
│                  SAFETY/ACTION LAYER                   │
│  权限系统 | Auto模式分类器 | Hook管道 | 工具池 | 沙箱  │
│  安全控制和行动执行                                    │
├─────────────────────────────────────────────────────────┤
│                     STATE LAYER                        │
│  上下文组装 | 运行时状态 | 会话持久化 | CLAUDE.md | 记忆│
│  数据管理和状态维护                                    │
├─────────────────────────────────────────────────────────┤
│                    BACKEND LAYER                       │
│  执行后端 | 外部资源访问 | API通信 | MCP客户端         │
│  底层基础设施和外部交互                                │
└─────────────────────────────────────────────────────────┘

表面层（Surface Layer）

• 交互式 CLI、无头 CLI、Agent SDK

• IDE 集成、桌面应用、浏览器扩展

• 负责用户交互和结果展示

核心层（Core Layer）

• 核心代理循环

• 五层上下文压缩管道

• 会话状态管理

安全与行动层（Safety/Action Layer）

• 权限系统、Auto 模式分类器

• Hook 管道、工具池

• Shell 沙箱、子代理生成器

状态层（State Layer）

• 上下文组装、运行时状态

• 会话持久化、CLAUDE.md 系统

• 自动记忆、Sidechain 转录

后端层（Backend Layer）

• 工具实现、Shell 执行器

• MCP 客户端、API 适配器

• 远程执行支持、LSP 集成

2.3 核心子系统

五层上下文压缩管道

每次模型调用前自动运行，解决上下文窗口有限的问题：

1. 预算减少：计算可用 token 预算，预留系统空间

2. 剪切：剪切过长的工具输出，保留开头结尾

3. 微压缩：删除冗余字符，压缩格式

4. 上下文折叠：合并相关消息为摘要

5. 自动压缩：使用 Claude 模型生成历史摘要

七层安全防御体系

深度防御策略，工具请求必须通过所有七层：

1. 工具预过滤

2. 拒绝优先规则评估

3. 权限模式约束

4. Auto 模式分类器

5. Shell 沙箱检查

6. 会话恢复检查

7. PreToolUse Hook 拦截

2.4 完整架构流程图

端到端执行流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

flowchart TD
    A[用户输入] --> B[表面层 Surface Layer]
    B --> C[状态层 State Layer]
    C --> D[核心层 Core Layer]
    D --> E{有工具调用吗?}
    E -->|否| F[返回结果给用户]
    E -->|是| G[安全与行动层 Safety/Action Layer]
    G --> H{安全检查通过?}
    H -->|否| I[返回拒绝原因]
    I --> D
    H -->|是| J[执行工具]
    J --> K{工具类型?}
    K -->|内置工具| L[直接执行]
    K -->|MCP工具| M[调用MCP服务器]
    K -->|Task工具| N[生成子代理]
    L --> O[工具执行结果]
    M --> O
    N --> O
    O --> P[状态层: 更新会话状态]
    P --> D```

## 三、核心使用

### 3.1 基本启动方式

​```bash
# 在当前项目目录启动
claude

# 直接执行任务
claude "修复auth.test.ts中失败的测试"

# 管道输入
tail -200 app.log | claude -p "分析这些日志中的错误"

3.2 内置工具集

3.3 常用斜杠命令

• /help - 查看帮助

• /init - 初始化项目，自动生成 CLAUDE.md 文件

• /model - 切换使用的模型（Opus, Sonnet, Haiku）

• /cost - 查看当前会话的费用

• /memory - 管理自动记忆

• /review - 发起代码审查

• /mcp - 管理 MCP 服务器连接

• /sandbox - 启用沙箱模式（Linux/WSL2）

• /loop - 定时重复执行任务

• /batch - 批量处理文件

3.4 快捷键

• Ctrl+C - 中断当前操作

• Ctrl+O - 查看 Claude 的详细思考过程

• Shift+Tab - 快速切换权限模式

• 双击Esc - 撤销上一次文件修改

• Shift+Enter - 多行输入

四、工作原理

4.1 核心：代理循环

Claude Code 的核心是一个极其简单的while循环：

1
2
3
4
5

while (claude_response.has_tool_call) {
    result = execute_tool(tool_call);
    claude_response = send_to_claude(result);
}
return claude_response.text;

循环分为三个阶段，不断迭代直到任务完成：

1. 收集上下文：扫描项目、读取文件、加载配置

2. 采取行动：分析上下文，规划执行路径，调用工具

3. 验证结果：检查行动效果，决定下一步操作

4.2 上下文管理

Claude Code 采用代理式搜索，不使用传统 RAG：

• 直接在本地机器上操作实时代码库

• 像人类工程师一样遍历文件系统、读取文件、搜索

• 不需要预先构建和维护代码库索引

• 始终使用最新的代码状态

4.3 安全机制

Claude Code 采用深度防御策略，多层安全机制相互配合：

1. 权限系统：分级控制工具执行权限

2. Auto 模式分类器：AI 驱动的风险评估

3. 输入层防护：扫描提示注入尝试

4. Shell 沙箱：隔离执行命令

5. 可逆性：所有文件修改都可以一键撤销

6. 审计日志：完整记录所有操作

五、扩展生态

5.1 常用 Skills 推荐

官方必备 Skills

通用开发 Skills

• planning-with-files：Manus 风格的持久化任务规划系统

• code-refactoring：结构化重构，遵循 SOLID 原则

• conventional-commits：自动生成符合规范的提交信息

• test-harness：自动生成全面的测试套件

• debugger-agent：专业的调试助手

前端开发 Skills

• react-best-practices：Vercel 官方推荐的 React 最佳实践

• vue3-guidelines：Vue 3 和 Composition API 指南

• tailwind-expert：Tailwind CSS 高级技巧

• web-quality-skills：Web 质量检查，覆盖性能、可访问性、SEO

后端与数据 Skills

• api-design：RESTful API 和 GraphQL 设计最佳实践

• sql-optimizer：SQL 查询优化专家

• pandas-pro：Pandas 高级数据处理

• dbt-transformation-patterns：官方 DBT 转换模式

DevOps 与基础设施 Skills

• hashicorp-agent-skills：Terraform、Vault 等官方技能

• docker-expert：Docker 容器化和镜像优化

• kubernetes-guide：Kubernetes 部署和管理

• github-actions：GitHub Actions 工作流创建

文档与协作 Skills

• readme-generator：自动生成完整的 README.md

• changelog-generator：从 Git 历史生成更新日志

• pr-description：自动生成 Pull Request 描述

• code-reviewer：结构化的代码审查

安全与质量 Skills

• security-scan：基于 OWASP 的漏洞扫描

• trail-of-bits-security：运行 CodeQL 和 Semgrep 分析

• secrets-detector：检测硬编码密钥

• dependency-audit：检查依赖漏洞

5.2 常用 MCP 服务器推荐

官方必备 MCP

开发工具类 MCP

• Semgrep：静态代码分析，漏洞检测

• Prisma：管理 Prisma 数据库模式和迁移

• Docker：管理 Docker 容器和镜像

• Figma Dev Mode：从 Figma 设计文件生成代码

• Magic MCP：生成高质量 UI 组件

数据库类 MCP

• MySQL/MariaDB：完整的 MySQL 支持

• SQLite：本地数据库操作

• MongoDB：NoSQL 数据库查询

• Redis：缓存和键值存储操作

• Supabase：完整的 Supabase 平台集成

云服务与 DevOps 类 MCP

• AWS：完整的 AWS 服务集成

• Azure：Microsoft Azure 服务

• Vercel：一键部署到 Vercel 平台

• Kubernetes：管理 Kubernetes 集群

• Terraform：基础设施即代码

• Sentry：错误跟踪和性能监控

生产力与协作类 MCP

• Slack：发送消息，读取频道

• Linear：问题跟踪和项目管理

• Notion：读取和写入 Notion 页面

• Jira：Atlassian Jira 问题跟踪

• Fireflies：会议转录和分析

知识与搜索类 MCP

• Context7：获取最新的库文档和代码示例

  1	claude mcp add --transport http context7 https://mcp.context7.com/mcp

• Playwright：浏览器自动化，测试，网页抓取

• Memory MCP：跨会话持久化记忆

5.3 常用 CLI 工具

官方核心 CLI 命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 项目管理
claude init              # 初始化项目，生成CLAUDE.md
claude config            # 查看和修改配置
claude status            # 查看当前会话状态
claude doctor            # 全面检查安装和配置
claude update            # 更新Claude Code到最新版本

# 代码操作
claude "任务描述"        # 直接执行任务
claude -p "提示词"       # 非交互式模式
claude review            # 代码审查
claude refactor          # 重构代码
claude test              # 运行测试

# MCP管理
claude mcp add           # 添加MCP服务器
claude mcp list          # 列出已安装的MCP服务器
claude mcp remove        # 移除MCP服务器
claude mcp restart       # 重启MCP服务器

# 会话管理
claude history           # 查看会话历史
claude resume            # 恢复上次会话
claude fork              # 分叉当前会话
claude export            # 导出会话历史

社区 CLI 工具

• claude-code-router：基于任务复杂度自动切换模型，优化成本

• claude-code-action：在 GitHub Actions 中运行 Claude Code

• mcptools：MCP 服务器管理工具

六、高级配置

6.1 配置文件优先级

• 项目级配置：./.claude/settings.json（优先级最高，仅当前项目生效）

• 全局根配置：~/.claude.json（所有项目生效）

6.2 全局配置文件（~/.claude.json）

极简必备配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "hasCompletedOnboarding": true,
  "autoUpdates": true,
  "autoUpdatesChannel": "stable",

  "env": {
        "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
        "CLAUDE_CODE_ENABLE_TELEMETRY": "0",
        "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },

  "permissions": {
    "defaultMode": "auto"
  }
}

完整版全能配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "hasCompletedOnboarding": true,
  "theme": "dark",
  "verbose": false,
  "autoUpdates": true,
  "autoUpdatesChannel": "stable",

  "cacheEnabled": true,
  "contextCompression": true,
  "parallelTasksCount": 3,

  "env": {
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "0",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },

  "permissions": {
    "defaultMode": "auto",
    "autoMode": {
      "enabled": true,
      "environment": "development"
    }
  }
}

6.3 核心配置项详解

跳过首次引导

1

"hasCompletedOnboarding": true

作用：永久跳过 Claude 启动引导教程，直接进入工作界面。

CCH 问题修复

CCH（Claude Code Attribution Header）：默认的随机归因头导致缓存失效，表现为卡顿、慢、费 token。

1

"CLAUDE_CODE_ATTRIBUTION_HEADER": "0"

注意：必须是字符串"0"，不能写数字0。

全局代理配置

1
2

"HTTP_PROXY": "http://127.0.0.1:7890",
"HTTPS_PROXY": "http://127.0.0.1:7890"

作用：永久设置全局代理，无需每次终端手动设置。

权限模式配置

其他优化配置

• autoUpdates: 自动更新 Claude

• theme: dark: 深色模式

• cacheEnabled: true: 开启本地缓存

• parallelTasksCount: 3: 最大并行子任务数

• CLAUDE_CODE_ENABLE_TELEMETRY": "0": 关闭遥测

6.4 版本升级指南

Windows CMD

1
2
3
4
5

:: 设置代理
set HTTPS_PROXY=http://127.0.0.1:7890
set HTTP_PROXY=http://127.0.0.1:7890
:: 升级
claude update

Windows PowerShell

1
2
3
4
5

# 设置代理
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY = "http://127.0.0.1:7890"
# 升级
claude update

macOS / Linux

1
2
3
4
5

# 设置代理
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
# 升级
claude update

强制升级

1

claude update --force

包管理器升级

1
2
3
4
5

# macOS Homebrew
brew upgrade --cask claude-code

# Windows Winget
winget upgrade Anthropic.ClaudeCode

6.5 生效方法

1. 修改配置文件后重启 Claude 终端会话

2. 验证配置加载：

1

claude config list

七、性能优化

1. 少而精：不要安装太多 Skills 和 MCP 服务器，建议保持 10 个以内核心扩展

2. 项目级配置：项目特定的配置放在项目目录，避免全局污染

3. 定期更新：定期更新 Claude 和扩展，获取最新优化

4. 缓存优化：开启 CCH 修复，提升缓存命中率到 95% 以上

5. 权限模式：使用auto模式，平衡安全与效率

核心知识点速览

• Claude Code 核心是代理循环，通过工具调用自主完成开发任务

• 配置"CLAUDE_CODE_ATTRIBUTION_HEADER": "0"可修复 CCH 缓存问题，大幅提升速度

• 权限模式推荐使用auto，平衡安全与效率

• 扩展生态包含 Skills、MCP 服务器，可大幅扩展 Claude 能力

• 项目级配置优先级高于全局配置，可实现项目隔离

• 全局配置可永久写入代理，无需每次终端手动设置

• 子代理系统可解决上下文有限问题，支持最多 10 个并行任务

• 七层安全防御体系保障工具执行安全

• 五层上下文压缩管道高效利用有限的上下文窗口

• 升级时可通过代理配置解决网络访问问题

飞书CLI技术文档

目录

1. 简介

2. 快速安装

3. 基础配置

4. 核心命令速查

5. 进阶使用技巧

6. AI Agent 集成

7. 故障排除

8. 相关资源

简介

飞书 CLI 是字节跳动飞书开放平台于 2026 年 3 月 28 日正式开源的官方命令行工具，采用 Go 语言开发，核心定位是 “Built for humans and AI Agents”。它既为人类提供终端高效办公体验，也专为 AI 智能体设计，让 AI 能够直接 “动手操作” 飞书全业务流程。

核心特性

• 官方出品，API 稳定可靠，持续更新迭代

• AI 原生设计，内置 24 个结构化 AI Agent Skills

• 支持 12 个核心业务域，200 + 精选高频命令

• 三层命令体系：快捷命令、API 命令、Raw API

• 凭证本地加密存储，支持 dry-run 预览模式

• 多身份支持，可切换个人用户和机器人身份

快速安装

推荐一键安装（包含 AI 技能）

1

npx @larksuite/cli@latest install

国内镜像安装

1
2
3
4
5

# 安装CLI
npm install -g @larksuite/cli --registry=https://registry.npmmirror.com

# 安装AI Agent技能
npx skills add larksuite/cli -y -g

版本管理

1
2
3
4
5

# 查看当前版本
lark-cli version

# 更新到最新版本
lark-cli update

基础配置

身份认证

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 扫码登录飞书账号
lark-cli auth login

# 查看当前登录状态
lark-cli auth status

# 查看所有已登录账号
lark-cli auth list

# 切换登录账号
lark-cli auth switch <account>

# 退出当前账号
lark-cli auth logout

通用参数

• --help: 查看任意命令帮助

• --dry-run: 预览操作不执行

• --json: 输出 JSON 格式（适合脚本调用）

• --verbose: 显示详细日志信息

核心命令速查

消息与群组

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 列出最近的聊天列表
lark-cli chat list

# 搜索聊天
lark-cli chat search "关键词"

# 发送文本消息
lark-cli message send --chat <chat_id> --text "消息内容"

# 发送文件
lark-cli message send --chat <chat_id> --file ./report.pdf

# 发送图片
lark-cli message send --chat <chat_id> --image ./screenshot.png

# 查看最近20条消息
lark-cli message list --chat <chat_id> --limit 20

# 回复指定消息
lark-cli message reply <message_id> --text "回复内容"

# 创建群聊
lark-cli group create --name "群名称" --members "user1@example.com,user2@example.com"

# 添加群成员
lark-cli group add-member --chat <chat_id> --members "user3@example.com"

云文档

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 创建空白文档
lark-cli doc create --title "文档标题"

# 导入本地Markdown为飞书文档
lark-cli doc import --input ./README.md --title "导入的文档"

# 导出飞书文档为Markdown
lark-cli doc export <doc_id> -o ./output.md

# 导出文档并下载图片到本地
lark-cli doc export <doc_id> -o ./output.md --download-images

# 获取文档内容
lark-cli doc get <doc_id>

# 更新文档内容
lark-cli doc update <doc_id> --content "# 新标题\n\n新内容"

# 在文档末尾追加内容
lark-cli doc append <doc_id> --content "\n\n追加的内容"

# 删除文档（移至回收站）
lark-cli doc delete <doc_id>

# 分享文档给用户（编辑权限）
lark-cli doc share <doc_id> --user "user@example.com" --permission "edit"

电子表格

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 创建空白电子表格
lark-cli sheet create --title "表格标题"

# 导入CSV到电子表格
lark-cli sheet import --input ./data.csv --sheet <spreadsheet_id>

# 导出工作表为CSV
lark-cli sheet export <spreadsheet_id> --sheet "Sheet1" -o ./data.csv

# 获取指定范围单元格数据
lark-cli sheet cell get <spreadsheet_id> --range "Sheet1!A1:C5"

# 设置单个单元格值
lark-cli sheet cell set <spreadsheet_id> --range "Sheet1!A1" --value "标题"

# 批量设置单元格值
lark-cli sheet cell batch-set <spreadsheet_id> --range "Sheet1!A2:B3" --values '[["a","b"],["c","d"]]'

多维表格

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 创建空白多维表格
lark-cli bitable create --title "多维表格标题"

# 列出多维表格中的所有数据表
lark-cli bitable table list <app_token>

# 列出数据表中的所有记录
lark-cli bitable record list <app_token> <table_id>

# 创建新记录
lark-cli bitable record create <app_token> <table_id> --fields '{"名称":"记录1","状态":"进行中"}'

# 更新记录
lark-cli bitable record update <app_token> <table_id> <record_id> --fields '{"状态":"已完成"}'

# 删除记录
lark-cli bitable record delete <app_token> <table_id> <record_id>

日历与会议

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 查看今日日程（快捷命令）
lark-cli calendar +agenda

# 查看今日到明天的日程
lark-cli calendar events list --start-time today --end-time tomorrow

# 创建会议
lark-cli calendar event create --title "会议标题" --start-time "2026-05-18T10:00:00+08:00" --end-time "2026-05-18T11:00:00+08:00" --attendees "user1@example.com,user2@example.com"

# 查看最近10个已结束的会议
lark-cli meeting list --status ended --limit 10

# 获取会议逐字稿
lark-cli meeting transcript <meeting_id>

# 获取会议纪要
lark-cli meeting minutes <meeting_id>

任务管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 列出所有未完成的任务
lark-cli task list --status incomplete

# 创建任务并分配给他人
lark-cli task create --title "任务标题" --assignee "user@example.com" --due-date "2026-05-20"

# 将任务标记为已完成
lark-cli task update <task_id> --status completed

# 给任务添加评论
lark-cli task comment <task_id> --text "任务评论"

# 删除任务
lark-cli task delete <task_id>

云空间

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 列出云空间根目录文件
lark-cli drive list

# 上传文件到指定文件夹
lark-cli drive upload --file ./document.pdf --folder <folder_id>

# 下载文件到本地
lark-cli drive download <file_token> -o ./downloaded.pdf

# 创建新文件夹
lark-cli drive mkdir --name "新文件夹" --parent <parent_folder_id>

# 删除文件（移至回收站）
lark-cli drive delete <file_token>

通讯录

1
2
3
4
5
6
7
8
9
10
11

# 搜索用户
lark-cli contact user search "张三"

# 获取用户详细信息
lark-cli contact user get <user_id>

# 列出所有部门
lark-cli contact department list

# 列出部门成员
lark-cli contact department members <department_id>

进阶使用技巧

脚本集成

所有命令都支持--json输出，方便在 Shell 脚本或 Python 中解析：

1
2
3
4
5

# 获取JSON格式的聊天列表
lark-cli chat list --json > chats.json

# 使用jq解析JSON
lark-cli chat list --json | jq '.[] | {name: .name, id: .chat_id}'

批量操作

结合 xargs 可以实现批量处理：

1
2
3
4
5

# 批量添加群成员
cat users.txt | xargs -I {} lark-cli group add-member --chat <chat_id> --members {}

# 批量导出文档
cat doc_ids.txt | xargs -I {} lark-cli doc export {} -o {}.md

定时任务

结合 crontab 可以实现自动化操作：

1
2
3
4
5

# 每天早上9点发送日报提醒
0 9 * * * lark-cli message send --chat <chat_id> --text "请大家提交昨日日报"

# 每周五晚上6点自动备份重要文档
0 18 * * 5 lark-cli doc export <doc_id> -o /backup/weekly/$(date +%Y%m%d).md

AI Agent 集成

飞书 CLI 原生支持 MCP 协议，可直接在所有主流 AI 编辑器中使用：

• Claude Code

• Cursor

• GitHub Copilot

• Windsurf

• Trae

AI 快捷命令

直接输入即可，无需复杂参数：

• +agenda: 查看今日日程

• +today: 查看今日所有待办和会议

• +tomorrow: 查看明日安排

• +meetings: 查看本周所有会议

• +tasks: 查看所有未完成任务

• +summary: 生成今日工作摘要

• +weekly: 生成本周工作周报

故障排除

常见问题

1. 登录失败

   • 确保网络连接正常

   • 尝试使用lark-cli auth logout清除缓存后重新登录

   • 检查是否有多个飞书账号冲突

2. 权限不足

   • 确认你在飞书中拥有对应资源的操作权限

   • 机器人身份需要管理员在开放平台配置相应权限

3. 资源 ID 错误

   • 资源 ID 可在飞书网页版 URL 中获取

   • 文档 ID 在/d/和/之间

   • 聊天 ID 在/im/chat/之后

相关资源

• GitHub 开源仓库

• 官方网站

• 官方文档

• NPM 包

claude-tap技术文档

目录

• 1. 概述

• 2. 技术架构

  • 2.1 整体架构

  • 2.2 工作原理

  • 2.3 代理模式

  • 2.4 流量处理机制

• 3. 核心技术实现

  • 3.1 安全脱敏机制

  • 3.2 低开销流式转发

  • 3.3 自包含查看器

  • 3.4 实时同步机制

• 4. 项目代码结构

• 5. 安装部署

  • 5.1 系统要求

  • 5.2 安装方式

  • 5.3 升级方法

• 6. 详细使用指南

  • 6.1 通用命令格式

  • 6.2 支持的客户端

• 7. 高级功能

• 8. CLI 完整参数参考

• 9. 技术特性对比

• 10. 常见问题

1. 概述

claude-tap 是一个开源的 AI 代理流量分析工具，专门用于拦截并查看各类终端 AI 助手的 API 流量，打破 AI 编程助手的 “黑箱” 状态。

核心价值

• 透明化：完整查看系统提示词、上下文管理、工具调用细节

• 可观测：精确追踪 Token 用量、缓存命中、API 调用时序

• 可调试：支持实时查看、历史回溯、流量导出

• 兼容性：支持 8+ 主流 AI 客户端，无需修改客户端代码

支持的客户端

2. 技术架构

2.1 整体架构

claude-tap 采用分层架构设计，从上到下分为：

1. 客户端层：各类 AI 终端助手（Claude Code、Codex 等）

2. 代理层：反向 / 正向代理服务器，负责流量拦截与转发

3. 记录层：流量记录、脱敏处理、Trace 存储

4. 查看层：HTML 查看器、实时 Dashboard、导出功能

5. 上游层：AI 服务提供商 API 端点

2.2 工作原理

claude-tap 采用 “中间人代理”（Man-in-the-Middle Proxy）技术，完整工作流程如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

1. 启动阶段
   ├── 启动代理服务器（反向/正向）
   ├── 生成临时 CA 证书（用于正向代理 HTTPS 拦截）
   └── 启动子进程运行目标 AI 客户端

2. 流量拦截
   ├── 客户端请求被重定向到本地代理
   ├── 代理解析请求内容，进行脱敏处理
   ├── 记录完整的请求元数据和 payload

3. 流量转发
   ├── 将请求转发到上游 API 服务器
   ├── 实时接收上游响应，流式转发回客户端
   ├── 同步记录响应内容和流数据

4. 数据存储
   ├── 将请求-响应对写入 JSONL Trace 文件
   ├── 实时推送到 Live Viewer（如果启用）

5. 后处理
   ├── 客户端退出后，生成自包含 HTML 查看器
   ├── 自动清理过期 Trace 文件
   └── 自动打开查看器（默认）

2.3 代理模式

claude-tap 支持两种代理模式，根据不同客户端的特性自动选择：

反向代理模式（Reverse Proxy）

适用场景：支持自定义 Base URL 的客户端
工作机制：

• 代理服务器监听本地端口

• 修改客户端的 Base URL 指向本地代理

• 客户端所有请求都发送到代理，代理转发到上游

• 无需证书，因为客户端主动信任代理

技术优势：

• 零证书配置

• 低 overhead，性能最优

• 完全透明，客户端无感知

支持客户端：Claude Code、Codex CLI、Kimi CLI

正向代理模式（Forward Proxy）

适用场景：不支持 Base URL 的多 Provider 客户端
工作机制：

• 代理服务器作为 HTTPS 正向代理

• 注入 HTTPS_PROXY 环境变量到客户端进程

• 生成临时 CA 证书，注入到客户端信任链

• 拦截所有 HTTPS 流量，无需修改客户端配置

技术优势：

• 支持任意上游域名

• 可捕获客户端所有 Provider 的流量

• 无需客户端支持自定义 Base URL

支持客户端：Gemini CLI、OpenCode、Pi、Hermes、Cursor CLI

2.4 流量处理机制

SSE 流式转发

针对 AI 服务常用的 Server-Sent Events 流式响应，claude-tap 实现了零拷贝的流式转发：

• 逐 chunk 转发，不等待完整响应

• 实时记录流数据，支持断点续传

• 保持原有的流控和背压机制

• 增加延迟 < 1ms，几乎无性能损耗

WebSocket 支持

对于部分客户端使用的 WebSocket 长连接：

• 完整支持 WebSocket 帧转发

• 支持双向流量记录

• 自动处理帧分片和重组

• 兼容 OAuth 认证的 WebSocket 连接

3. 核心技术实现

3.1 安全脱敏机制

为了保护用户隐私，claude-tap 实现了自动脱敏机制：

1
2
3
4
5
6
7
8
9

# 自动脱敏的 Header 列表
REDACTED_HEADERS = {
    "authorization",
    "proxy-authorization",
    "x-api-key",
    "x-auth-token",
    "cookie",
    "set-cookie",
}

脱敏规则：

• 所有敏感认证 Header 自动替换为 [REDACTED]

• 不会记录任何 API Key、Token、Cookie 等敏感信息

• 脱敏是在记录阶段进行，转发时使用原始值

• 支持自定义脱敏规则扩展

3.2 低开销流式转发

claude-tap 使用 Python AsyncIO 实现异步非阻塞 IO：

• 全异步架构，单线程可处理数千并发连接

• 流式处理，无需缓存完整请求 / 响应

• 内存占用极低，单 Trace 仅占用几 MB 内存

• 支持 GB 级大流量的处理

性能测试数据：

• 平均转发延迟：< 0.5ms

• CPU 占用：< 5%（正常负载）

• 内存占用：~20MB（基础运行）

• 并发连接：支持 1000+ 并发

3.3 自包含查看器

查看器是一个完全独立的 HTML 文件，零外部依赖：

• 所有功能内置，无需网络连接即可查看

• 包含完整的 CSS、JS、数据，单文件即可运行

• 支持暗色 / 亮色主题切换

• 响应式设计，支持移动端

前端技术栈：

• 原生 Vanilla JS，无框架依赖

• Tailwind CSS 内置编译

• 支持 i18n 国际化（8 种语言）

• 支持键盘导航、搜索、过滤

3.4 实时同步机制

Live 模式下，claude-tap 使用 SSE（Server-Sent Events）实现实时同步：

• 代理服务器作为 SSE 服务端

• 浏览器查看器作为客户端订阅更新

• 新的 Trace 数据实时推送到浏览器

• 支持断线重连和增量同步

• 无需 WebSocket，兼容性更好

4. 项目代码结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

claude-tap/
├── claude_tap/                 # 核心代码
│   ├── __init__.py
│   ├── __main__.py            # 入口点
│   ├── cli.py                 # CLI 解析
│   ├── proxy/
│   │   ├── __init__.py
│   │   ├── reverse_proxy.py   # 反向代理实现
│   │   ├── forward_proxy.py   # 正向代理实现
│   │   └── ca.py              # 临时 CA 证书生成
│   ├── clients/               # 客户端适配层
│   │   ├── __init__.py
│   │   ├── claude.py
│   │   ├── codex.py
│   │   ├── gemini.py
│   │   ├── kimi.py
│   │   ├── opencode.py
│   │   ├── pi.py
│   │   ├── hermes.py
│   │   └── cursor.py
│   ├── recorder/              # 记录层
│   │   ├── __init__.py
│   │   ├── trace.py           # Trace 管理
│   │   └── redaction.py       # 脱敏处理
│   ├── viewer/                # 查看器生成
│   │   ├── __init__.py
│   │   ├── generator.py       # HTML 生成
│   │   └── live.py            # Live 模式
│   └── utils/                 # 工具函数
├── viewer/                     # 查看器前端资源
│   └── index.html             # 查看器模板
├── tests/                      # 测试用例
├── docs/                       # 文档
├── pyproject.toml             # 项目配置
├── README.md                  # 英文 README
└── README_zh.md               # 中文 README

语言分布：

• Python: 76.7%（后端代理、CLI、记录层）

• HTML: 21.4%（前端查看器）

• Shell: 1.9%（脚本、安装工具）

5. 安装部署

5.1 系统要求

• Python 3.11 或更高版本

• 目标 AI 客户端已安装

• 操作系统：Linux /macOS/ Windows（WSL 推荐）

• 网络：可访问 AI 服务 API

5.2 安装方式

推荐：使用 uv（最快最可靠）

1
2
3
4
5

# 安装 uv 包管理器
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装 claude-tap
uv tool install claude-tap

使用 pip

1

pip install claude-tap

5.3 升级方法

1
2
3
4
5
6
7
8

# 使用 uv
uv tool upgrade claude-tap

# 使用 pip
pip install --upgrade claude-tap

# 内置升级命令
claude-tap update

6. 详细使用指南

6.1 通用命令格式

1

claude-tap [--tap-* 选项] -- [客户端参数]

所有非 --tap-* 开头的参数都会透传给所选的 AI 客户端。

6.2 支持的客户端

1. Claude Code（默认）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 基本使用
claude-tap

# 实时查看模式
claude-tap --tap-live

# 指定模型 + 自动批准工具调用
claude-tap --tap-live -- --model claude-sonnet-4-6 --dangerously-skip-permissions

# 搭配 DeepSeek API
export ANTHROPIC_AUTH_TOKEN="<你的 DeepSeek API key>"
claude-tap \
  --tap-proxy-mode reverse \
  --tap-target https://api.deepseek.com/anthropic \
  -- --permission-mode bypassPermissions

2. Codex CLI

1
2
3
4
5
6
7
8

# OAuth 用户（ChatGPT Plus/Pro/Team）
claude-tap --tap-client codex

# API Key 用户
claude-tap --tap-client codex

# 全自动模式 + 实时查看
claude-tap --tap-client codex --tap-live -- --full-auto

3. Kimi CLI

1
2
3
4
5
6
7
8

# 基本使用
claude-tap --tap-client kimi

# 开启思考过程
claude-tap --tap-client kimi -- --thinking

# 使用 Open Platform API
claude-tap --tap-client kimi --tap-target https://api.moonshot.ai/v1

4. Gemini CLI

1
2
3
4
5

# 基本使用
claude-tap --tap-client gemini -- -p "hello"

# 实时查看
claude-tap --tap-client gemini --tap-live -- -p "hello"

5. OpenCode

1
2
3
4
5

# 正向代理模式（捕获所有 Provider）
claude-tap --tap-client opencode

# 实时查看
claude-tap --tap-client opencode --tap-live

6. Pi

1
2
3
4
5

# 使用 OpenAI Codex OAuth
claude-tap --tap-client pi -- --model openai-codex/gpt-5.3-codex-spark -p "hello"

# 实时查看
claude-tap --tap-client pi --tap-live -- --model openai-codex/gpt-5.3-codex-spark -p "hello"

7. Hermes Agent

1
2
3
4
5

# 交互式 TUI 模式
claude-tap --tap-client hermes --tap-live

# Gateway 模式（捕获 Slack/Telegram 触发的调用）
claude-tap --tap-client hermes -- gateway start

8. Cursor CLI

1
2
3
4
5

# 基本使用
claude-tap --tap-client cursor -- -p --trust --model auto "hello"

# 继续上次对话
claude-tap --tap-client cursor -- -p --trust --model auto --continue "continue"

7. 高级功能

7.1 独立 Dashboard

浏览历史 Trace，不启动客户端：

1
2
3
4

claude-tap dashboard

# 自定义端口和目录
claude-tap dashboard --tap-output-dir ./my-traces --tap-live-port 3000

7.2 导出功能

从 JSONL Trace 生成 HTML 查看器：

1

claude-tap export trace.jsonl -o trace.html

7.3 纯代理模式

仅启动代理，手动连接：

1
2
3
4
5

# 启动代理
claude-tap --tap-no-launch --tap-port 8080

# 另一个终端连接
ANTHROPIC_BASE_URL=http://127.0.0.1:8080 claude

7.4 自定义配置

1
2
3
4
5
6
7
8
9
10
11

# 自定义 Trace 目录
claude-tap --tap-output-dir ./my-traces

# 限制最大 Trace 数量
claude-tap --tap-max-traces 10

# 禁用自动打开查看器
claude-tap --tap-no-open

# 固定代理端口
claude-tap --tap-port 8080

8. CLI 完整参数参考

9. 技术特性对比

10. 常见问题

Q: 我的 API Key 会被记录吗？

A: 不会。claude-tap 会自动脱敏所有认证 Header，不会在 Trace 文件中记录任何敏感的认证信息。

Q: 会影响客户端性能吗？

A: 影响极小。claude-tap 采用异步流式转发，平均增加延迟 <0.5ms，几乎无法感知。

Q: 支持 Windows 吗？

A: 推荐使用 WSL2。原生 Windows 部分功能可能有限制，正向代理的证书注入在 Windows 上需要额外配置。

Q: Trace 文件存在哪里？

A: 默认在当前目录的 ./.traces/ 下，按日期分组，每个会话一个独立的 Trace 文件。

Q: 可以在生产环境使用吗？

A: claude-tap 主要用于开发调试。生产环境使用请确保数据安全，不要泄露敏感信息。

最后更新: 2026-05-17

Everything Claude Code (ECC) 学习手册

文档核心说明

本文档适用于希望系统学习 Everything Claude Code (ECC) 技术的开发者，涵盖从入门到进阶的完整知识体系。

覆盖核心知识模块：

• 基础入门：项目概述、前提条件、三种官方安装方式、配置优化、常见问题

• 核心架构：代理、技能、规则、钩子、MCP 集成的完整定义与实现

• 基础使用：75+ 常用命令、快捷键、实用技巧、标准工作流示例

• 工作流编排：编排原语、执行引擎、高级特性、Hermes Operator v2.0

• 底层原理：Claude Code 扩展机制、代理委派、上下文管理

• 设计模式：架构模式、结构模式、行为模式、AI 原生设计模式

• 工具对比：与原生 Claude Code、Cursor、Codex、OpenCode、GitHub Copilot 的对比

• 自定义开发：代理开发、技能开发、工作流定义、测试调试

• 最佳实践：Token 优化、安全注意事项、适用场景、局限性

一、基础入门

1.1 项目概述

Everything Claude Code（简称 ECC）是由 Anthropic 黑客松冠军 Affaan Mustafa 创建的生产级 AI 代理性能优化系统，最初诞生于 2025 年 9 月的 Anthropic x Forum Ventures 黑客松，作者团队仅用 8 小时就使用这套配置完全构建了 zenith.chat 并夺冠。

它不是一个独立的 AI 编程工具，而是为 Claude Code、Cursor、Codex、OpenCode 等主流 AI 编程工具量身定制的 “高级改装套件”，将个人级的 AI 编程助手体验提升为团队级、可积累、可治理的 AI 开发基础设施。

截至 2026 年 5 月，ECC 已迭代至 v2.0.0-rc.1 版本，在 GitHub 上获得了超过 140k stars 和 21k forks，是目前最受欢迎的 AI 编程增强工具。

核心价值：

• 将通用 AI 助手转化为专业的开发专家

• 统一团队开发规范和最佳实践

• 自动化重复的开发流程，提升效率

• 可积累的技能库，持续提升团队能力

• 跨工具支持，一套配置适配所有主流 AI 编程环境

1.2 前提条件

在安装 ECC 之前，请确保你的环境满足以下要求：

• Claude Code CLI v2.1.0+ 或 Claude Code 桌面版

• Anthropic API Key（从 console.anthropic.com 获取）

• Node.js 18+

• Git

• 至少 1GB 可用磁盘空间（用于存储配置和缓存）

1.3 安装与配置

ECC 提供三种官方安装方式，严禁叠加使用多种安装方式，这是最常见的安装错误原因。

方式一：插件安装（官方推荐）

这是最稳定、最推荐的安装方式：

1
2
3
4
5
6
7

# 1. 添加 ECC 插件市场

/plugin marketplace add https://github.com/affaan-m/everything-claude-code

# 2. 安装 ECC 插件

/plugin install ecc@ecc

重要：插件无法自动分发规则，需要手动复制你需要的规则：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 克隆仓库

git clone https://github.com/affaan-m/everything-claude-code.git

cd everything-claude-code

# 复制通用规则和你使用的语言规则（不要复制所有规则）

mkdir -p ~/.claude/rules/ecc

cp -r rules/common ~/.claude/rules/ecc/

cp -r rules/typescript ~/.claude/rules/ecc/  # 根据你的技术栈选择

cp -r rules/python ~/.claude/rules/ecc/

验证安装：

1

/ecc:plan "测试安装是否成功"

方式二：脚本安装（手动控制）

适用于需要完全控制安装内容的用户：

1
2
3
4
5
6
7
8
9
10
11

# macOS/Linux

./install.sh --profile standard --target claude

# Windows PowerShell

.\install.ps1 --profile standard --target claude

# 或使用 npx

npx ecc-install --profile standard --target claude

可用配置文件：

• minimal：仅核心规则（适合低资源环境）

• standard：核心规则 + 基础技能 + 代理（推荐大多数用户）

• full：全量安装（包含所有实验性功能）

方式三：完全手动安装

适用于需要深度定制的用户：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# 1. 克隆仓库

git clone https://github.com/affaan-m/everything-claude-code.git

cd everything-claude-code

# 2. 安装依赖

npm install

# 3. 复制代理

cp agents/*.md ~/.claude/agents/

# 4. 复制规则

mkdir -p ~/.claude/rules/ecc

cp -r rules/common ~/.claude/rules/ecc/

cp -r rules/typescript ~/.claude/rules/ecc/

# 5. 复制技能

mkdir -p ~/.claude/skills/ecc

cp -r .agents/skills/* ~/.claude/skills/ecc/

# 6. 安装钩子运行时

./install.sh --target claude --modules hooks-runtime

配置优化（推荐）

在 ~/.claude/settings.json 中添加以下配置，优化 token 成本和自动行为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

{

  "autoCompact": true,

  "compactThreshold": 10000,

  "maxTokensPerRequest": 8192,

  "defaultModel": "claude-3-5-sonnet-20240620",

  "autoApprove": {

    "readFiles": true,

    "writeFiles": true,

    "runCommands": false,

    "installPackages": false

  },

  "env": {

    "MAX_THINKING_TOKENS": "10000",

    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"

  }

}

常见安装问题

问题 1：权限被拒绝

1
2
3

# 解决方案：修复目录权限

sudo chown -R $USER ~/.claude/

问题 2：Node.js 版本过低

1
2
3
4
5

# 解决方案：升级 Node.js

nvm install 18

nvm use 18

问题 3：Claude Code 版本不兼容

1
2
3

# 解决方案：升级 Claude Code

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

问题 4：网络连接失败

1
2
3
4
5

# 解决方案：使用代理

export https_proxy=http://127.0.0.1:7890

curl -fsSL https://raw.githubusercontent.com/affaan-m/everything-claude-code/main/scripts/install.sh | bash

问题 5：重复钩子错误

• 不要在 .claude-plugin/plugin.json 中添加 "hooks" 字段

• Claude Code v2.1+ 会自动加载插件的 hooks/hooks.json

• 手动删除 ~/.claude/settings.json 中重复的 hooks 配置

问题 6：卸载与重置

1
2
3
4
5
6
7
8
9
10
11

# 1. 卸载插件

/plugin uninstall ecc@ecc

# 2. 删除 ECC 规则

rm -rf ~/.claude/rules/ecc/

# 3. 完全卸载（脚本安装）

node scripts/uninstall.js

二、核心架构

ECC 采用分层模块化设计，包含 6 大核心组件，形成了完整的 AI 开发工作流闭环：

2.1 代理系统

代理是 ECC 的核心执行单元，每个代理本质上是一个带有角色定义、工具集和模型配置的提示模板。

核心代理列表：

• 架构师 (architect)：系统设计、可扩展性分析、技术选型决策

• 规划师 (planner)：任务分解、开发计划生成、风险评估

• TDD 导师 (tdd-guide)：测试驱动开发全流程指导

• 代码审查员 (code-reviewer)：多维度代码质量检查

• 安全审计员 (security-reviewer)：漏洞扫描与风险评估

• 构建错误解决器 (build-error-resolver)：自动定位和修复构建失败

• 数据库专家 (database-reviewer)：数据库设计、查询优化、迁移指导

• DevOps 专家 (devops-expert)：CI/CD 配置、容器化、部署指导

• 语言专家：TypeScript/Python/Go/Java/Rust/PHP 等 12 种语言的深度专项专家

代理定义格式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

---
name: code-reviewer
description: Reviews code for quality, security, and maintainability
tools: ["Read", "Grep", "Glob", "Bash"]
model: claude-3-5-sonnet-20240620
timeout: 300
---

你是一位资深代码审查员，必须从以下维度审查代码：
1. 代码可读性和命名规范
2. 代码可维护性和架构一致性
3. 性能优化和资源使用
4. 安全漏洞和错误处理
5. 测试覆盖率和测试质量
你必须为每个问题提供具体的修复建议，并给出严重程度评分。

2.2 技能系统

技能是 ECC 的 “知识库”，包含经过实战验证的工作流和最佳实践，是 ECC 的主要工作流表面。

技能分类：

• 开发工作流：TDD、敏捷开发、CI/CD 配置、Git 分支管理

• 技术栈知识：React/Vue/Angular、Django/FastAPI、Spring Boot、Node.js

• 工具使用：Docker/Kubernetes、AWS/GCP/Azure、数据库优化

• 项目管理：需求分析、任务分解、进度跟踪、文档生成

• 领域知识：机器学习、数据工程、移动开发、安全审计

技能定义格式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

---
name: tdd-workflow
description: Test-Driven Development workflow
agents: ["tdd-guide"]
phases:
  - name: write-tests
    description: Write failing tests
  - name: implement
    description: Implement minimal code to pass tests
  - name: refactor
    description: Refactor code while keeping tests passing
  - name: verify
    description: Verify test coverage
---

# TDD 工作流

当执行此技能时，你必须严格按照以下步骤进行：
1. 理解需求，明确功能边界
2. 编写第一个最简单的测试用例
3. 运行测试，确认测试失败（RED）
4. 编写最少的代码使测试通过（GREEN）
5. 重构代码，提高可读性和可维护性
6. 重复步骤 2-5 直到所有需求都被覆盖
7. 生成测试覆盖率报告，确保覆盖率≥80%

2.3 规则系统

规则是 ECC 的 “纪律系统”，通过系统提示注入强制 Claude 在所有任务中遵循最佳实践。

规则分类：

• 通用规则：代码注释规范、错误处理原则、命名约定、提交信息格式

• 语言专项规则：针对每种语言的编码风格、性能优化、安全最佳实践

• 项目规则：可自定义团队专属的开发规范和项目要求

规则执行机制：

• 规则在代码生成前注入，而不是生成后检查

• 强制规则必须严格遵守，违反的代码会被自动拒绝

• 推荐规则强烈建议遵守，除非有特殊理由

2.4 钩子系统

钩子是 ECC 的 “自动化引擎”，基于事件触发自动执行预定义的操作。

支持的事件类型：

• sessionStart：会话开始时

• sessionEnd：会话结束时

• beforeToolUse：调用工具前

• afterToolUse：调用工具后

• beforeFileWrite：写入文件前

• afterFileWrite：写入文件后

• beforeCommit：提交代码前

• afterCommit：提交代码后

常用钩子示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "hooks": {
    "afterFileWrite": [
      {
        "command": "prettier --write {{filePath}}",
        "description": "自动格式化代码",
        "include": ["*.ts", "*.tsx", "*.js", "*.jsx"]
      }
    ],
    "beforeCommit": [
      {
        "command": "npm run lint",
        "description": "运行代码检查",
        "failOnError": true
      }
    ]
  }
}

2.5 MCP 集成

ECC 预配置了 14+ 常用服务的 MCP（Model Context Protocol）服务器，允许 Claude 直接与这些服务交互。

预配置的 MCP 服务：

• GitHub：创建 Issue、PR、管理仓库

• Vercel：部署应用、查看部署状态

• Supabase：数据库操作、认证配置

• Exa：网络搜索、研究

• Playwright：端到端测试

• Context7：文档查询

MCP 配置格式：

1
2
3
4
5
6
7
8
9
10
11

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}

三、基础使用

3.1 基础使用流程

1. 进入项目目录：cd your-project

2. 启动 Claude Code：claude

3. 描述任务：/ecc:plan "为这个项目添加用户认证功能"

4. 审查计划：确认 Claude 生成的开发计划

5. 执行任务：Claude 会自动调用对应的代理和技能完成任务

6. 代码审查：/code-review 审查生成的代码

7. 测试验证：/test 运行测试用例

3.2 完整命令速查表

核心管理命令

项目开发命令

代码质量与安全命令

文档与协作命令

部署与运维命令

代理调用命令

工作流编排命令

插件管理命令

3.3 实用快捷键

3.4 实用技巧

1. Token 节省：使用 mgrep 替代系统 grep，可减少约 50% 的 token 消耗

1

alias grep="mgrep"

1. 快速执行：在命令后加 --auto 可自动批准所有安全操作

1

/tdd "实现登录功能" --auto

1. 指定模型：在任何命令后加 --model <model-name> 临时使用特定模型

1

/security-scan --model claude-3-opus-20240229

1. 仅生成计划：使用 --dry-run 参数只生成计划不执行

1

/refactor src/ --dry-run

1. 更新 ECC：定期更新到最新版本获取新功能

1

/plugin update ecc@ecc

3.5 常用工作流示例

新功能开发工作流

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 1. 生成开发计划
/ecc:plan "添加用户认证功能，支持邮箱密码和 OAuth2 登录"

# 2. 按照 TDD 模式实现功能
/tdd "实现邮箱密码登录功能"

# 3. 审查代码质量
/code-review

# 4. 安全审计
/security-scan

# 5. 运行测试
/test

# 6. 生成文档
/docs

Bug 修复工作流

1
2
3
4
5
6
7
8
9
10

# 1. 编写失败的测试用例
/tdd "修复用户登录时的空指针异常"

# 2. 实现修复代码
# 3. 验证测试通过
# 4. 代码审查
/code-review

# 5. 提交代码
/commit

代码重构工作流

1
2
3
4
5
6
7
8
9
10
11

# 1. 生成重构计划
/ecc:plan "将用户模块重构为微服务架构"

# 2. 执行重构
/refactor src/user/

# 3. 运行测试确保功能不变
/test

# 4. 代码审查
/code-review

生产部署准备工作流

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 1. 安全审计
/security-scan --full

# 2. 运行所有测试
/test

# 3. 生成测试覆盖率报告
/test-coverage

# 4. 生成变更日志
/changelog v1.2.0

# 5. 部署到生产环境
/deploy vercel

四、工作流编排

4.1 编排机制概述

ECC 的工作流编排不是基于传统的工作流引擎，而是一个纯提示工程驱动的编排层，完全构建在 Claude Code 官方提供的扩展机制之上。

它的核心技术哲学是：不重新发明轮子，而是将 Claude 本身的推理能力转化为一个可编程的工作流执行引擎。

4.2 核心编排原语

ECC 的工作流编排系统由 5 个核心原语构成：

1. 代理 (Agents)

工作流的基本执行单元，负责完成特定类型的任务。每个代理可以指定独立的模型、工具集和超时时间。

2. 技能 (Skills)

可重用的工作流模板，包含经过实战验证的分步工作流描述。技能可以被代理调用，也可以直接作为独立的工作流执行。

3. 命令 (Commands)

用户与 ECC 工作流系统交互的入口。每个命令对应一个工作流定义，用户通过输入斜杠命令来启动对应的工作流。

4. 状态 (State)

ECC 使用 SQLite 数据库 来存储工作流的状态信息，包括工作流实例 ID、当前执行阶段、已完成的步骤、代理间的交接文档等。

5. 钩子 (Hooks)

事件驱动的自动化引擎，允许在工作流执行的特定事件点自动执行预定义的操作。

4.3 工作流执行引擎

ECC 的工作流执行引擎完全运行在 Claude 的推理过程中，整个执行流程分为 6 个阶段：

1. 任务接收与分析：解析命令参数，确定工作流类型和任务描述

2. 工作流实例化：创建工作流实例，分配唯一 ID，初始化执行阶段

3. 代理调用与上下文传递：将当前工作流状态和交接文档注入到代理的上下文中

4. 工具调用与结果处理：验证工具调用权限，执行工具调用，将结果返回给代理

5. 阶段转换与质量门控：检查代理输出是否符合质量标准，生成交接文档，启动下一个代理

6. 结果整合与报告生成：整合所有代理的输出，生成结构化的最终报告

4.4 高级编排特性

1. 条件分支与循环

ECC 支持基于中间结果的条件分支和循环逻辑：

1
2
3
4
5
6
7
8
9
10
11

## 条件分支
如果测试覆盖率≥80%：
  → 进入代码审查阶段
否则：
  → 返回 TDD 阶段，补充测试用例

## 修复循环
当存在未解决的代码审查问题时：
1. 让开发者修复问题
2. 重新运行代码审查
3. 重复直到所有问题都解决

2. 嵌套工作流

一个工作流可以作为另一个工作流的一个阶段：

1
2
3
4
5

## 微服务开发工作流
1. 架构设计阶段：调用 `/orchestrate architect`
2. 服务实现阶段：为每个服务调用 `/orchestrate feature`
3. 集成测试阶段：调用 `/orchestrate integration-test`
4. 部署阶段：调用 `/orchestrate deploy`

3. 多模型协同编排

ECC 支持多模型协同开发，不同的任务可以分配给最适合的模型：

1
2
3
4
5
6

## 多模型协同工作流
1. **研究阶段**：Claude 3.5 Sonnet（通用推理）
2. **后端开发**：OpenAI Codex（后端代码生成）
3. **前端开发**：Google Gemini（UI/UX 设计）
4. **代码审查**：Claude 3 Opus（深度审查）
5. **安全审计**：Claude 3 Opus（安全分析）

4. 分布式并行执行

对于大型项目，ECC 支持基于 tmux 和 git worktree 的分布式并行执行：

• 为每个代理创建独立的 git 工作树

• 在独立的 tmux 窗格中启动代理会话

• 主编排器监控所有代理的执行状态

• 自动合并代理的修改并解决冲突

5. 人工介入点

ECC 支持在工作流的关键节点设置人工介入点：

1
2
3
4
5
6

## 人工介入点：架构设计审查
在开始实现之前，请用户审查架构设计方案：
- [ ] 批准架构设计
- [ ] 请求修改
- [ ] 取消工作流
用户批准后，工作流将继续执行。

4.5 状态管理与错误处理

SQLite 状态存储

ECC 使用 SQLite 数据库作为状态存储，包含以下表：

• workflows：工作流实例信息

• phases：工作流阶段信息

• agents：代理执行记录

• handoffs：代理间交接文档

• tool_calls：工具调用历史

• user_interactions：用户交互记录

会话持久化与恢复

ECC 会自动保存会话状态，当用户重新打开 Claude Code 时，会自动检测到未完成的工作流并恢复执行。

错误检测与自动重试

• 工具调用错误：自动重试最多 3 次，重试失败则暂停工作流

• 模型调用错误：自动切换到备用模型，或请求用户干预

• 超时错误：延长超时时间或终止任务

• 验证错误：要求代理重新生成输出

回滚机制

ECC 支持工作流的回滚操作，可以将项目恢复到任意之前的状态：

1

/rewind <workflow-id> <phase-id>

4.6 Hermes Operator（v2.0 新特性）

ECC v2.0.0-rc.1 引入了 Hermes Operator，这是一个全新的工作流编排控制平面，提供了以下高级功能：

1. 跨会话 / 跨工作树编排：管理多个 Claude Code 会话和 git 工作树，实现真正的分布式并行执行

2. 可视化仪表板：基于 Tkinter 的桌面应用，提供工作流状态监控、代理执行进度查看、token 消耗统计等功能

3. 持续学习与技能进化：自动从成功的工作流中提取可重用的模式，转化为新的技能

4. 状态快照：将本地状态存储导出为可移植的交接文档

5. Rust 控制平面：用 Rust 重写核心编排逻辑，提供更好的性能和可靠性

启动 Hermes 仪表板：

1
2
3

npm run dashboard
# 或
python3 ./ecc_dashboard.py

五、底层原理

5.1 ECC 的本质

ECC不是一个独立的 AI 编程工具，也不是 Claude Code 的 fork 版本，而是一个纯配置驱动的增强层。它完全基于 Claude Code 官方提供的扩展机制构建，没有修改 Claude Code 的任何二进制代码。

ECC 的安装过程本质上就是将它的配置文件复制到 Claude Code 的配置目录中。整个过程没有编译、没有二进制文件，完全是文本文件的复制。

5.2 Claude Code 原生扩展机制

ECC 的所有功能都构建在 Claude Code 提供的三个核心扩展点之上：

1. 系统提示注入

Claude Code 在启动时会自动读取 ~/.claude/rules/ 目录下的所有 .md 文件，并将它们的内容追加到系统提示的末尾。这是 ECC 最核心的注入点。

系统提示分层结构：

1. Claude Code 原生系统提示（不可修改）

2. ECC 基础规则层（通用行为规范）

3. 代理定义层（60+ 专业代理的角色描述）

4. 技能定义层（228+ 技能的工作流描述）

5. 命令定义层（75+ 斜杠命令的实现）

6. 语言专项规则层（12 种语言的编码规范）

7. 项目自定义规则层（项目级配置）

2. 自定义斜杠命令

Claude Code 允许用户在 ~/.claude/settings.json 中定义自定义斜杠命令。当用户输入一个斜杠命令时，Claude Code 会自动将其替换为预定义的提示文本。

3. 钩子系统

Claude Code 提供了基于事件的钩子机制，允许在特定事件发生时自动执行预定义的操作。

5.3 代理委派系统的实现原理

ECC 的代理委派完全在单个 Claude 会话内部完成，没有外部 API 调用，也没有多个模型实例。

代理委派流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

用户输入任务
    ↓
主代理分析任务类型
    ↓
匹配最适合的专业代理
    ↓
在当前上下文中注入该代理的角色提示
    ↓
告诉 Claude："现在你是 XX 代理，请按照 XX 规则执行任务"
    ↓
Claude 切换角色并执行任务
    ↓
任务完成后，主代理切换回原角色
    ↓
主代理整合结果并返回给用户

关键创新：上下文内角色切换技术，零延迟、低开销、保留完整上下文。

5.4 上下文管理与优化技术

智能上下文压缩

ECC 实现了一个基于语义的上下文压缩算法：

• 保留所有的系统规则和代理定义

• 保留最近的 10 轮对话

• 压缩较早的对话，只保留关键信息

• 完全删除无关的信息（如调试输出、错误信息）

Token 优化策略

• 使用 mgrep 替代系统 grep，只返回最相关的上下文

• 自动截断长文件，只读取与当前任务相关的部分

• 使用缩写和简洁的表达方式

• 避免重复信息

MCP 上下文管理

• 每个 MCP 工具描述都会消耗 token，过多的 MCP 会将 200k 上下文减少到～70k

• 建议保持不超过 10 个 MCP 服务器和 80 个工具处于激活状态

• 使用 /mcp 命令禁用不需要的 MCP 服务器

六、ECC 设计模式

6.1 核心设计哲学

1. 纯配置驱动：不修改 Claude Code 的任何二进制代码

2. LLM 作为执行引擎：将 Claude 本身的推理能力转化为可编程的工作流执行器

3. 质量内置而非事后检查：通过前置约束和自动化流程确保输出质量

6.2 架构模式

1. 四层扩展架构

• Hooks 层：安全验证、自动化、事件响应

• Skills 层：可重用知识、工作流模板

• Agents 层：角色专业化、任务执行

• Commands 层：用户交互入口、工作流触发器

2. 纯配置驱动架构

所有功能都通过文本文件定义，没有编译步骤，没有二进制文件。

3. 控制平面 / 数据平面分离架构（v2.0）

• 控制平面：Hermes Operator（Rust 编写），负责工作流编排、状态管理、资源调度

• 数据平面：多个 Claude Code 会话，负责实际的代码生成和任务执行

4. 插件化架构

允许用户将一组相关的代理、技能、命令和钩子打包成一个插件，方便分发和安装。

6.3 结构模式

1. 代理模式

每个专业代理都是 Claude 通用能力的一个 “代理”，专注于特定类型的任务。

2. 组合模式

简单的技能和代理可以组合成更复杂的工作流。

3. 装饰器模式

通过规则和钩子来 “装饰”Claude Code 的基础功能，在不修改核心代码的情况下增强其能力。

4. 外观模式

提供统一的斜杠命令接口，隐藏了内部复杂的编排逻辑。

5. 享元模式

共享系统提示和技能定义，优化 token 消耗。

6.4 行为模式

1. 策略模式

根据任务类型动态选择最适合的代理、模型和技能。

2. 观察者模式

钩子系统是观察者模式的典型实现，当特定事件发生时，所有注册的钩子都会被通知。

3. 状态模式

工作流执行引擎是一个有限状态机，工作流在不同的状态之间转换。

4. 命令模式

斜杠命令系统将用户的请求封装为一个命令对象，包含执行该请求所需的所有信息。

5. 模板方法模式

技能系统定义了工作流的骨架，将具体步骤的实现延迟到代理。

6. 责任链模式

规则系统是责任链模式的实现，多个规则依次检查代码，只有通过所有规则的代码才会被接受。

7. 中介者模式

主代理作为中介者，协调多个子代理之间的交互，子代理之间不直接通信。

6.5 AI 原生设计模式

这些是 ECC 针对 LLM 的特性设计的独特模式：

1. 上下文内角色切换模式

在单个 Claude 会话内部实现多代理协作，不需要创建新的会话或 API 调用。

2. 纯提示工程编排模式

工作流编排完全通过提示工程实现，没有传统的控制流代码。

3. 交接文档协议模式

定义标准化的交接文档格式，确保代理之间能够清晰、准确地传递上下文信息。

4. 质量门控模式

在工作流的每个阶段都设置质量门控，只有满足质量标准的输出才能进入下一阶段。

5. 增量验证循环模式

每完成一个小步骤就进行验证，而不是等到整个任务完成后再验证。

6. Trinity 模式

复杂任务处理分为三个阶段：探索→规划→执行。

7. Git Worktree 隔离模式

使用 git worktree 为每个任务创建独立的工作环境，避免不同任务之间的代码干扰。

8. 持续学习模式

通过钩子系统观察用户的操作，自动学习用户的偏好和编码风格，并转化为新的技能。

七、工具对比与选型

7.1 ECC 增强 Claude Code vs 原生 Claude Code

7.2 ECC 增强 Claude Code vs Cursor

7.3 ECC 与其他 AI 代理框架的对比

7.4 跨工具支持对比

ECC 是目前唯一支持所有主流 AI 编程工具的增强框架：

八、自定义开发

8.1 ECC 文件结构

1
2
3
4
5
6
7
8
9
10
11

everything-claude-code/
├── agents/           # 60 个专业代理定义
├── skills/           # 228 个工作流技能
├── commands/         # 75 个斜杠命令
├── rules/            # 34 个编码规则
├── hooks/            # 钩子配置和脚本
├── mcp-configs/      # MCP 服务器配置
├── scripts/          # 安装和工具脚本
├── tests/            # 测试套件
├── .claude-plugin/   # 插件元数据
└── ecc_dashboard.py  # Hermes 仪表板

8.2 自定义代理开发

1. 在 agents/ 目录下创建一个新的 Markdown 文件

2. 添加 YAML 前端元数据，定义代理的名称、描述、工具集和模型

3. 编写代理的角色描述和行为规范

4. 保存文件，Claude Code 会自动加载

示例：自定义代理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

---
name: my-custom-agent
description: My custom agent for specific tasks
tools: ["Read", "Write", "Bash"]
model: claude-3-5-sonnet-20240620
---

你是我的自定义代理，专门处理以下任务：
1. 任务一
2. 任务二
3. 任务三

你必须遵循以下规则：
- 规则一
- 规则二
- 规则三

8.3 自定义技能开发

1. 在 skills/ 目录下创建一个新的目录

2. 在该目录下创建 SKILL.md 文件

3. 添加 YAML 前端元数据，定义技能的名称、描述和使用的代理

4. 编写技能的工作流步骤

5. 保存文件，Claude Code 会自动加载

示例：自定义技能

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

---
name: my-custom-skill
description: My custom workflow skill
agents: ["my-custom-agent"]
phases:
  - name: phase1
    description: Phase 1 description
  - name: phase2
    description: Phase 2 description
---

# 我的自定义技能
当执行此技能时，你必须严格按照以下步骤进行：
1. 步骤一
2. 步骤二
3. 步骤三

8.4 自定义命令开发

1. 在 commands/ 目录下创建一个新的 Markdown 文件

2. 添加 YAML 前端元数据，定义命令的名称、描述和参数

3. 编写命令被触发时发送给 Claude 的提示文本

4. 保存文件，Claude Code 会自动加载

示例：自定义命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

---
name: /my-command
description: My custom command
arguments:
  - name: arg1
    type: string
    required: true
    description: Argument 1 description
---

# 我的自定义命令
请执行以下任务：{{arg1}}
你必须遵循以下规则：
- 规则一
- 规则二

8.5 测试与调试

1. 测试单个代理：

1

/invoke-agent my-custom-agent "测试任务"

1. 测试工作流：

1

/orchestrate custom "测试任务" --dry-run

1. 查看工作流日志：

1

/workflow-log <workflow-id>

1. 运行测试套件：

1

node tests/run-all.js

九、最佳实践

9.1 适用场景

ECC 最适合以下场景：

• 中大型项目开发：需要多人协作、代码质量要求高的项目

• 复杂多文件任务：系统重构、微服务开发、CI/CD 配置

• 自动化流程：测试自动化、部署自动化、文档生成

• 团队开发：需要统一代码规范和开发流程的团队

• 技术学习：通过观察专业代理的工作方式学习最佳实践

9.2 不适用场景

ECC 不适合以下场景：

• 简单的单行代码修改：使用原生 Claude Code 或 Cursor 更高效

• 需要深度 IDE 集成的任务：如调试、断点设置

• 离线环境：需要连接 Anthropic API

• 预算非常有限的项目：ECC 会增加 API 调用次数

9.3 Token 优化最佳实践

1. 模型选择：

• 默认使用 Claude 3.5 Sonnet，处理 80%+ 的任务

• 仅在复杂架构、深度推理时使用 Claude 3 Opus

• 简单任务可以使用 Claude 3 Haiku

1. 上下文管理：

• 使用 /clear 在不相关任务之间重置上下文

• 使用 /compact 在逻辑断点处压缩上下文

• 禁用不需要的 MCP 服务器

1. 配置优化：

1
2
3
4
5
6
7

{
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  }
}

9.4 安全最佳实践

1. 权限管理：

• 谨慎开启 autoApprove 中的 runCommands 和 installPackages 选项

• 永远不要在生产环境中开启完全自动批准

• 使用钩子拦截危险操作

1. 安全审计：

• 定期运行 /security-scan 检查代码漏洞

• 使用 AgentShield 扫描 ECC 配置本身的漏洞

• 审查所有自动生成的代码

1. 密钥管理：

• 永远不要将 API 密钥提交到代码仓库

• 使用环境变量存储敏感信息

• 定期轮换 API 密钥

9.5 局限性

1. 提示工程的天花板：所有功能都基于提示工程，存在固有的不稳定性

2. 可观测性不足：缺乏完善的监控和调试工具

3. token 开销较大：大量的规则和代理定义会增加每次请求的 token 消耗

4. 大规模团队协作支持有限：目前主要面向个人开发者和小团队

5. 依赖 Claude Code 的能力：ECC 无法实现 Claude Code 本身不支持的功能