新手上路（六）：Claude code装上ECC全家桶：38 个子代理、156 个技能、生产级 Hooks 与 Rules 体系

Windows 10 · Node.js 18+ · Git · Claude Code CLI + ECC v1.10.0 · 2026-05-01

一、这篇教程解决什么问题

一句话定位：在国内 Windows 环境下，Claude code配置 Everything Claude Code（ECC）插件系统，获得 38 个专业子代理、156 个技能、72 个命令、生产级 Hooks、MCP 集成，以及三条开箱即用的作业流水线。

阅读前提：

• 已安装 Node.js 18+（终端执行 node --version 能输出版本号）
• 已安装 Git（终端执行 git --version 能输出版本号）
• 能打开 PowerShell 并以管理员身份运行

读完能得到什么：

• Claude Code CLI 完整安装并成功认证
• ECC 插件安装完毕，包含 agents、skills、hooks、rules 四大组件
• 掌握三条最实用的作业流水线（新功能开发、会话管理、安全审查）
• 了解 Hooks 运行机制并能自定义
• 掌握 MCP 服务器配置方法
• 遇到常见报错时能快速定位并修复

---

二、环境准备

2.1 依赖清单

组件	最低版本	说明
Node.js	18.0+	Claude Code CLI 运行时；推荐 LTS（当前 22.x）
npm	9.0+	随 Node.js 附带，用于全局安装 CLI 和 ECC 依赖
Git	2.30+	克隆 ECC 仓库、管理 worktree
FFmpeg	6.0+	可选，仅视频翻译项目需要
PowerShell	5.1+	Windows 自带；ECC 的 install.ps1 依赖

2.2 逐条验证

node --version          # 应输出 v18.x.x 或更高
npm --version           # 应输出 9.x.x 或更高
git --version           # 应输出 git version 2.30.x 或更高
$PSVersionTable.PSVersion   # 应输出 Major >= 5

如果缺少某个组件：

• Node.js：推荐使用 fnm（Fast Node Manager）安装，避免权限问题：

  winget install Schniz.fnm
  fnm install --lts
  fnm default lts
  

  安装后重新打开终端，再验证 node --version。

• Git：

  winget install Git.Git
  

  安装后重新打开终端。

---

三、安装步骤

3.1 通过插件市场安装（由于Claude自带plan，推荐使用插件安装方式）

如果你希望在 Claude Code 内部管理 ECC 组件，可以通过插件市场安装：

# 启动 Claude Code
claude

# 在 Claude Code 内部执行
/plugin marketplace add https://github.com/affaan-m/everything-claude-code
/plugin install everything-claude-code@everything-claude-code

存在以下选项，按需选择

为你安装(用户范围)
为本仓库的所有合作者安装(项目范围)
仅为你安装，在此仓库中(本地范围)
打开主页
返回插件列表

插件方式无法自动分发 rules，rules 仍需通过 3.5 的安装脚本手动安装。

3.2 克隆 Everything Claude Code 仓库（以下为手动安装）

cd C:\Workspace
git clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code
git checkout v1.10.0

国内用户如果 git clone 速度极慢或超时，可以使用 GitHub 镜像加速（参见 Debug #2）。

3.3 安装 ECC 依赖

npm install

预期输出：

added XXX packages in Xs

3.4 运行 ECC 安装脚本

ECC 提供了 Windows 原生的 PowerShell 安装脚本。根据你的技术栈选择：

# 安装全部组件（推荐首次使用）
.\install.ps1 --profile full

# 或只安装特定语言的规则
.\install.ps1 typescript          # 仅 TypeScript/JavaScript
.\install.ps1 python              # 仅 Python
.\install.ps1 typescript python   # 多语言同时安装

预期输出：

[ECC] Installing dependencies...
[ECC] Installing rules...
[ECC] Copying common rules to C:\Users\<用户名>\.claude\rules\common
[ECC] Copying typescript rules to C:\Users\<用户名>\.claude\rules\typescript
[ECC] Done!

验证安装结果：

# 检查 rules 是否就位
ls "$env:USERPROFILE\.claude\rules"
# 应看到 common/ 和你选择的语言目录（如 typescript/）

# 检查 agents 是否就位
ls "$env:USERPROFILE\.claude\agents"
# 应看到 planner.md、architect.md 等文件

# 检查 skills 是否就位
ls "$env:USERPROFILE\.claude\skills"
# 应看到 tdd-workflow、security-review 等目录

3.5 启动与验证

# 启动 Claude Code
claude

在 Claude Code 中验证 ECC 功能：

# 测试 ECC 命令（手动安装方式）
/plan "创建一个简单的 Express API"

# 测试 ECC 命令（插件安装方式）
/everything-claude-code:plan "创建一个简单的 Express API"

如果 Claude 开始输出实现计划（包含文件结构、测试策略等），说明 ECC 安装成功。

四、配置详解

4.1 CLAUDE.md 项目配置

CLAUDE.md 是 Claude Code 的核心配置文件，告诉 Claude 你的项目是什么、遵循什么规则。

放置位置：

位置	路径	作用范围
项目级	项目根目录\CLAUDE.md	仅当前项目
用户级	C:\Users\<用户名>\.claude\CLAUDE.md	所有项目的默认行为

示例项目配置（ECC 仓库中 examples/CLAUDE.md 的精简版）：

# CLAUDE.md

## 项目概述
[项目描述、技术栈]

## 关键规则
- 不可变优先，不修改对象或数组
- 不在生产代码中使用 console.log
- 所有用户输入必须校验
- 不硬编码密钥，使用环境变量

## 文件结构
src/
  app/            # 应用路由
  components/     # UI 组件
  lib/            # 工具函数
  types/          # 类型定义

## Git 提交规范
- feat: 新功能
- fix: 修复
- refactor: 重构
- docs: 文档
- test: 测试

4.2 Hooks 配置

Hooks 是 ECC 的核心能力之一，能在 Claude Code 执行工具前后自动触发检查。

Hooks 运行机制：

用户请求 → Claude 选择工具 → PreToolUse Hook 运行 → 工具执行 → PostToolUse Hook 运行

ECC 默认 Hooks 一览：

Hook	触发事件	匹配器	行为	退出码
开发服务器拦截	PreToolUse	Bash	在非 tmux 环境阻止 npm run dev 等命令	2（阻断）
Tmux 提醒	PreToolUse	Bash	建议长时间运行的命令使用 tmux	0（警告）
Git Push 提醒	PreToolUse	Bash	push 前提醒检查改动	0（警告）
提交质量检查	PreToolUse	Bash	commit 前检查 lint、提交格式、console.log	2/0
文档文件警告	PreToolUse	Write	警告非标准 .md 文件	0（警告）
战略性压缩	PreToolUse	Edit|Write	每 ~50 次工具调用建议 /compact	0（警告）
PR 记录	PostToolUse	Bash	记录 PR URL	0
构建分析	PostToolUse	Bash	后台分析构建输出	0
质量门禁	PostToolUse	Edit|Write	编辑后快速质量检查	0
Prettier 格式化	PostToolUse	Edit	自动格式化 JS/TS 文件	0
TypeScript 检查	PostToolUse	Edit	编辑 .ts/.tsx 后运行 tsc	0

Hook 运行时控制（无需修改 hooks.json）：

# Hook 严格度（默认: standard）
$env:ECC_HOOK_PROFILE = "standard"    # minimal | standard | strict

# 临时禁用特定 Hook
$env:ECC_DISABLED_HOOKS = "pre:bash:tmux-reminder,post:edit:typecheck"

自定义 Hook 示例——拦截超大文件创建：

{
  "matcher": "Write",
  "hooks": [{
    "type": "command",
    "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const c=i.tool_input?.content||'';const lines=c.split('\\n').length;if(lines>800){console.error('[Hook] BLOCKED: 文件超过 800 行');process.exit(2)}console.log(d)})\""
  }],
  "description": "阻止创建超过 800 行的文件"
}

Hook 输入的 JSON 结构：

interface HookInput {
  tool_name: string;        // "Bash", "Edit", "Write", "Read" 等
  tool_input: {
    command?: string;       // Bash: 要执行的命令
    file_path?: string;     // Edit/Write/Read: 目标文件
    old_string?: string;    // Edit: 被替换的文本
    new_string?: string;    // Edit: 替换后的文本
    content?: string;       // Write: 文件内容
  };
  tool_output?: {           // 仅 PostToolUse 有
    output?: string;        // 命令/工具输出
  };
}

4.3 MCP 服务器配置

MCP（Model Context Protocol）让 Claude Code 能调用外部工具（GitHub、数据库、浏览器等）。

添加 MCP 服务器：

# 在 Claude Code 内部执行
claude mcp add github -- npx -y @modelcontextprotocol/server-github
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem C:\Workspace

ECC 提供的 MCP 配置文件（mcp-configs/mcp-servers.json）包含常用服务的预设配置：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx你的Token"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Workspace"]
    }
  }
}

配置文件位置：

范围	路径
项目级	项目目录\.claude\settings.json
用户级	C:\Users\<用户名>\.claude\settings.json

MCP 服务器使用 stdio 管道通信。在 Windows 上，如果 Claude Code 通过 cmd.exe 启动，管道可能被截断。解决方案：始终从 PowerShell 或 Git Bash 启动 Claude Code，不要通过 cmd.exe 的 start 命令间接启动。

4.4 Rules 配置

Rules 是 Claude Code 的"始终遵循"规则，类似 ESLint 但针对 AI 行为。

ECC 的 Rules 分为两层：

C:\Users\<用户名>\.claude\rules\
  common\              # 通用规则（语言无关）
    coding-style.md    # 代码风格：不可变、文件组织
    git-workflow.md    # Git 工作流：提交格式、PR 流程
    testing.md         # 测试：TDD、80% 覆盖率
    performance.md     # 性能：模型选择、上下文管理
    patterns.md        # 设计模式
    hooks.md           # Hook 架构
    agents.md          # 子代理委托规则
    security.md        # 安全检查
  typescript\          # TypeScript/JavaScript 专用
    coding-style.md
    testing.md
    ...
  python\              # Python 专用
  golang\              # Go 专用

语言专用规则会自动覆盖通用规则中的同名部分（类似 CSS 优先级）。复制 rules 时必须复制整个目录，不能把文件摊平到一个目录里，否则同名文件会互相覆盖。

---

五、ECC 命令体系：先搞懂"技能"和"命令"

装完 ECC 后，你会在 Claude Code 中看到 180+ 个技能和 59+ 个斜杠命令。别慌——你日常只会用到其中不到 10 个。

5.1 Skills vs Commands 的区别

概念	是什么	怎么触发	举例
Skill（技能）	一个完整的工作流模板，包含多步骤指令	输入 /技能名 或 Claude 自动调用	/plan、/tdd、/code-review
Command（命令）	ECC 的旧版入口，大部分已指向对应 Skill	输入 /everything-claude-code:技能名	/everything-claude-code:plan
Agent（子代理）	一个专业领域的"虚拟专家"，由 Skill 自动派遣	无需手动调用，Claude 根据任务自动选择	planner、code-reviewer、tdd-guide

新手直觉：你只需要记住斜杠命令（如 /plan），Skill 会自动编排 Agent 工作。你不需要知道背后是哪个 Agent 在干活。

5.2 新手必记的 8 个命令

命令	一句话说明	什么时候用
/plan	让 Claude 先出方案再动手	每次开始新功能前
/tdd	测试驱动开发全流程	写功能代码时
/code-review	代码质量 + 安全审查	写完代码后
/build-fix	自动修复编译/构建错误	构建失败时
/checkpoint	在当前会话打个"存档点"	上下文变重之前
/save-session	完整保存会话状态	下班前、切换项目前
/resume-session	恢复上次保存的会话	第二天开工
/security-review	安全专项审查	涉及认证、支付、API 前

---

六、作业流水线一：新功能开发（最常用的作业流）

这是 ECC 最核心的流水线，适用于 90% 的日常开发场景。我们用一个具体例子走完全程：用 Express 创建一个待办事项（Todo）API。

6.1 流水线全景图

/plan（规划）→ Claude 出方案 → 你确认
    ↓
/tdd（测试驱动开发）→ 写测试 → 写实现 → 重构
    ↓
/code-review（代码审查）→ 修复问题
    ↓
/build-fix（如有构建错误）→ 自动修复
    ↓
/checkpoint（存档）→ 完成

6.2 第一步：/plan —— 让 Claude 先想再做

# 在你的项目目录中启动 Claude Code
cd C:\Workspace\my-todo-api
claude

在 Claude Code 中输入：

/plan 创建一个 Express Todo API，支持 CRUD 操作，使用内存存储，包含输入验证

Claude 会输出一份完整的实现方案，包括：

## 实现方案

### 文件结构
src/
  app.js              # Express 应用入口
  routes/
    todos.js          # Todo 路由
  middleware/
    validate.js       # 输入验证中间件
  __tests__/
    todos.test.js     # 测试文件

### API 设计
| 方法 | 路径 | 说明 |
|------|------|------|
| GET    | /todos       | 获取所有待办 |
| POST   | /todos       | 创建待办 |
| PUT    | /todos/:id   | 更新待办 |
| DELETE | /todos/:id   | 删除待办 |

### 实现步骤
1. 初始化项目 + 安装依赖
2. 编写路由和验证中间件
3. 编写测试用例
4. 运行测试确认全部通过

是否按此方案执行？

关键：/plan 不会直接写代码——它只输出方案，等你确认后才动手。这是 ECC 最重要的安全机制：先规划，再执行。

输入 yes 或 确认 让 Claude 开始执行。

6.3 第二步：/tdd —— 测试驱动开发

如果方案中包含复杂逻辑，你可以在 Claude 开始写代码后，用 /tdd 切换到测试驱动模式：

/tdd 给 Todo API 补充完整的测试用例

/tdd 会自动执行以下循环：

RED   → 写一个会失败的测试（证明测试真的在测）
GREEN → 写最少的代码让测试通过
REFACTOR → 清理代码，保持测试绿色

每次阶段完成后，Claude 会自动提交 checkpoint：

test: add Todo CRUD test cases          # RED 阶段
fix: implement Todo API endpoints        # GREEN 阶段
refactor: extract validation middleware  # REFACTOR 阶段

/tdd 要求测试覆盖率不低于 80%。对新手来说这可能偏高，但 ECC 会帮你逐步达到——不需要你一次写完所有测试。

6.4 第三步：/code-review —— 代码质量审查

代码写完后，运行审查：

/code-review

ECC 的 code-reviewer Agent 会自动扫描你改动过的文件，输出类似：

## Code Review Report

### CRITICAL (必须修复)
- routes/todos.js:23 — DELETE 路由缺少鉴权中间件，任何人可删除任意 todo

### HIGH (强烈建议修复)
- middleware/validate.js:8 — 未对 title 做 XSS 过滤
- routes/todos.js:45 — 错误信息泄露了内部堆栈

### MEDIUM (建议修复)
- app.js:12 — 未设置 CORS 白名单，当前允许所有来源

Claude 会自动修复 CRITICAL 和 HIGH 级别的问题。你也可以选择跳过某些 MEDIUM 项。

6.5 第四步：/build-fix —— 修复构建错误（如有）

如果过程中出现构建或运行错误：

/build-fix

ECC 会自动检测项目语言，派遣对应的构建修复 Agent（如 typescript-reviewer、python-reviewer 等），定位错误并修复。

6.6 第五步：/checkpoint —— 打存档点

一切就绪后：

/checkpoint

这会在当前会话中标记一个里程碑。如果后续出问题，你可以回退到这个点。

---

七、作业流水线二：会话管理（上下文不爆炸的秘密）

Claude Code 的上下文窗口有限（约 200K tokens）。随着对话变长，旧内容会被压缩甚至丢失。ECC 的会话管理流水线帮你解决这个问题。

7.1 什么时候需要管理会话？

信号	应对
Claude 回答开始"忘记"之前说过的话	运行 /context-budget 查看消耗
一个功能开发到一半，要下班了	运行 /save-session 保存
第二天回来继续昨天的工作	运行 /resume-session 恢复
想问一个和当前任务无关的问题	运行 /aside 开临时旁路

7.2 日常会话流水线

开工流程（每天早上）：

claude                          # 启动
/resume-session                 # 如果昨天有未完成的工作

工作中途存档（上下文变重时）：

/context-budget                 # 查看当前上下文使用情况
# 如果报告显示使用超过 70%，执行：
/checkpoint                     # 轻量存档（只标记里程碑）
# 或
/save-session                   # 完整保存（保存全部状态到磁盘）

下班收工：

/save-session                   # 保存当前会话状态
# 明天用 /resume-session 恢复

7.3 /context-budget 输出解读

Context Budget Report
=====================
Total window:  200,000 tokens
Used:          142,300 tokens (71.2%)
Remaining:     57,700 tokens

Breakdown:
  System prompt:    12,000  (6.0%)
  CLAUDE.md:         3,200  (1.6%)
  Rules:             8,100  (4.1%)
  Conversation:    119,000  (59.5%)  ← 主要消耗
  Tools available:      0   (auto-managed)

Recommendation: Consider /checkpoint or /compact

经验值：对话超过 70% 时，Claude 的回答质量会开始下降。此时运行 /checkpoint 或让系统自动压缩（/compact）是最佳实践。

---

八、作业流水线三：发布前安全审查

在代码提交或发布前，运行这条流水线确保没有安全问题。

8.1 发布前流水线

/security-review（安全审查）→ 修复问题 → /code-review（最终确认）→ 提交

8.2 /security-review 审查清单

输入 /security-review 后，ECC 的 security-reviewer Agent 会逐项检查：

检查项	说明	常见问题
密钥管理	硬编码的 API Key、密码	sk-xxxx 出现在源码中
输入验证	用户输入是否经过校验	缺少 Zod/Joi schema
SQL 注入	是否使用参数化查询	字符串拼接 SQL
XSS 防护	输出是否转义	未使用 DOMPurify
CSRF 保护	表单是否有 CSRF Token	缺失中间件
敏感数据泄露	错误信息是否暴露内部细节	堆栈返回给前端

8.3 实战演示

/security-review 审查 src/routes/auth.js 的登录接口

输出示例：

## Security Review — src/routes/auth.js

### CRITICAL 🔴
1. Line 34: 密码明文比较 (==), 应使用 bcrypt.compare()
2. Line 42: JWT secret 硬编码为 "my-secret-key"

### HIGH 🟠
3. Line 28: 未做登录频率限制，存在暴力破解风险
4. Line 55: 错误响应泄露 "User not found" vs "Wrong password"

### 修复建议已应用 ✅
- [x] 替换为 bcrypt.compare()
- [x] JWT secret 改为环境变量
- [x] 添加 express-rate-limit
- [x] 统一错误消息为 "Invalid credentials"

Claude 会自动修复标记为 CRITICAL 和 HIGH 的问题，然后运行验证确认修复有效。

---

九、进阶玩法：多模型协作（了解即可，新手可跳过）

当你的项目变复杂后，ECC 支持调用多个 AI 模型协作开发。这对新手来说不是必须掌握的，但了解它的存在有助于你规划进阶路径。

9.1 多模型协作是什么？

ECC 的 multi-* 系列命令让 Claude（主控）、Codex（后端专精）、Gemini（前端专精）三个模型并行工作：

命令	说明	适用场景
/everything-claude-code:multi-plan	三个模型各自出方案，Claude 综合	复杂架构决策
/everything-claude-code:multi-execute	按计划分工执行，Claude 做最终审查	全栈功能开发
/everything-claude-code:multi-frontend	Gemini 主导前端，Claude 审查	纯前端任务
/everything-claude-code:multi-backend	Codex 主导后端，Claude 审查	纯后端任务

9.2 工作原理

你 → Claude（主控调度）
        ├── Codex（后端 Agent）→ 返回 diff
        ├── Gemini（前端 Agent）→ 返回 diff
        └── Claude 合并 + 质量审查 → 写入文件

核心原则：外部模型只生产"草稿"（diff），Claude 是唯一有文件写入权限的模型。这保证了代码质量的一致性。

9.3 新手什么时候该碰这个？

• 你已经熟练使用 /plan → /tdd → /code-review 流水线
• 你的项目是真正的全栈项目（前后端分离）
• 你愿意为多模型调用支付额外的 API 费用

在那之前，单模型的流水线（第六~八章）已经足够覆盖日常开发的 90% 场景。

---

十、Debug #1 — npm 全局安装权限错误 (EACCES / EPERM)

报错日志

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path C:\Program Files\nodejs\node_modules\@anthropic-ai
npm ERR! errno -4092
npm ERR!
npm ERR! Your cache folder contains root-owned files to due to a previous
npm ERR! npm run with administrator privileges.

npm ERR! File C:\Users\<用户名>\AppData\Roaming\npm-cache\_cacache\tmp exists

或者：

Error: EPERM: operation not permitted, mkdir 'C:\Program Files\nodejs\node_modules\@anthropic-ai'

根因

Windows 上 Node.js 默认安装在 C:\Program Files\nodejs\，npm 全局包也装在这个目录下。普通用户没有对该目录的写权限。如果用管理员 PowerShell 安装，包会装到管理员上下文，后续普通终端找不到 claude 命令。根本解决方案是把 npm 全局目录迁到用户空间（如 C:\Users\<用户名>\npm-global），彻底避免权限冲突。

一览对比表

对比维度	修复前	修复后
npm 全局目录	C:\Program Files\nodejs\node_modules\	C:\Users\<用户名>\npm-global\
写权限	需要管理员权限	当前用户即可
PATH 优先级	可能冲突	用户 PATH 优先于系统 PATH
多终端一致性	管理员终端 vs 普通终端不一致	所有终端行为一致

代码修复

修复前（直接安装，会失败）：

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

修复后（先迁移全局目录再安装）：

# 第 1 步：创建用户级全局目录
mkdir "$env:USERPROFILE\npm-global"

# 第 2 步：告诉 npm 使用新目录
npm config set prefix "$env:USERPROFILE\npm-global"

# 第 3 步：将新目录加入用户 PATH（永久生效）
$currentPath = [System.Environment]::GetEnvironmentVariable("Path", "User")
$newPath = "$env:USERPROFILE\npm-global;" + $currentPath
[System.Environment]::SetEnvironmentVariable("Path", $newPath, "User")

# 第 4 步：重新打开终端后，安装 Claude Code
npm install -g @anthropic-ai/claude-code

第 3 步修改的是用户级 PATH（不是系统级），不需要管理员权限，也不会影响其他用户。

验证

# 重新打开终端后执行
claude --version

预期输出：

@anthropic-ai/claude-code x.x.x

---

十一、Debug #2 — git clone 超时 / 速度极慢

报错日志

Cloning into 'everything-claude-code'...
fatal: unable to access 'https://github.com/affaan-m/everything-claude-code.git/':
Failed to connect to github.com port 443 after 21096 ms: Timed out

或者极慢（<10 KB/s），最终 error: RPC failed; curl 56 Recv failure: Connection was reset。

根因

国内网络到 GitHub 的 HTTPS 连接不稳定，特别是 github.com 和 raw.githubusercontent.com 域名经常被 SNI 干扰或连接重置。根本原因是 DNS 解析到的 GitHub CDN IP 在国内访问质量差。解决方案是使用 GitHub 镜像站点或 SSH 方式连接。

一览对比表

对比维度	修复前	修复后
连接方式	HTTPS 直连 github.com	镜像站点 / SSH
下载速度	< 10 KB/s 或超时	通常可达 MB/s 级别
DNS 解析	被污染或指向慢 CDN	镜像站点域名解析正常
可靠性	随时可能断开	镜像站点在国内有 CDN 节点

代码修复

方案 A：使用 ghproxy 镜像克隆（最简单）

# 使用 ghproxy 镜像
git clone https://ghproxy.com/https://github.com/affaan-m/everything-claude-code.git

cd everything-claude-code
git checkout v1.10.0

如果 ghproxy.com 也不可用，可尝试 https://mirror.ghproxy.com/ 或 https://gh-proxy.com/。这些免费镜像地址会变化，建议搜索"GitHub 镜像 2026"获取最新可用地址。

方案 B：使用 Git SSH 方式（需要先配置 SSH Key）

# 如果已配置 GitHub SSH Key
git clone git@github.com:affaan-m/everything-claude-code.git

cd everything-claude-code
git checkout v1.10.0

方案 C：配置 Git 全局代理（如果有 HTTP 代理）

# 假设本地代理运行在 127.0.0.1:7890
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# 再次克隆
git clone https://github.com/affaan-m/everything-claude-code.git

验证

cd everything-claude-code
git log --oneline -3

预期输出（能看到 v1.10.0 的提交记录）：

xxxxxxx Merge pull request #xxx from ...
xxxxxxx Release v1.10.0
...

---

十二、Debug #3 — ECC install.ps1 执行策略被拒绝

报错日志

.\install.ps1 : 无法加载文件 C:\Workspace\everything-claude-code\install.ps1，
因为在此系统上禁止运行脚本。有关详细信息，请参阅 https://go.microsoft.com/fwlink/?LinkID=135170
中的 about_Execution_Policies。
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

根因

Windows PowerShell 默认执行策略为 Restricted，禁止运行任何 .ps1 脚本。这是 Windows 的安全机制，防止用户无意执行恶意脚本。执行策略有四个级别：Restricted（禁止所有脚本）→ AllSigned（仅签名脚本）→ RemoteSigned（本地脚本可执行）→ Unrestricted（全部可执行）。我们需要设置为 RemoteSigned——允许本地脚本运行，但从网络下载的脚本仍需签名。

一览对比表

对比维度	修复前	修复后
执行策略	Restricted	RemoteSigned
本地 .ps1 脚本	被拒绝	正常执行
网络下载的脚本	被拒绝	仍需签名（安全）
影响范围	当前用户	仅当前用户

代码修复

# 查看当前策略
Get-ExecutionPolicy -List

# 设置当前用户的执行策略为 RemoteSigned
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

使用 -Scope CurrentUser 只影响当前用户，不需要管理员权限，也不会降低系统级安全策略。

验证

# 重新执行安装脚本
.\install.ps1 --profile full

预期输出：

[ECC] Installing dependencies...
[ECC] Installing rules...
...
[ECC] Done!

---

十三、Debug #4 — ECC Hooks 不触发或报错

报错日志

[Hook Error] TypeError: Cannot read properties of undefined (reading 'tool_input')
    at Object.<anonymous> (C:\Users\<用户名>\.claude\hooks\pre-tool-use.js:5:23)

或者 Hooks 完全没有反应，没有任何输出。

根因

ECC v1.8.0 之前部分 Hooks 用 Bash one-liner 实现，在 Windows 上因路径分隔符和引号转义问题经常失败。v1.8.0+ 全部改写为 Node.js 脚本，但如果你是通过手动复制文件而不是运行 install.ps1 安装的，可能缺少 scripts/ 目录中的 Node.js 脚本文件。Hooks 的 JSON 配置在 hooks/hooks.json 中，但实际执行逻辑在 scripts/hooks/ 目录的 .js 文件中——两者缺一不可。

一览对比表

对比维度	修复前	修复后
Hook 执行方式	Bash one-liner（Windows 不兼容）	Node.js 脚本（跨平台）
依赖文件	仅 hooks.json	hooks.json + scripts/hooks/*.js
安装方式	手动复制遗漏文件	使用 install.ps1 自动安装
stdin 输入	解析失败	正确读取 JSON 流

代码修复

第 1 步：确认 scripts 目录存在

ls C:\Workspace\everything-claude-code\scripts\hooks\

应看到：session-start.js、session-end.js、pre-compact.js、suggest-compact.js、evaluate-session.js

第 2 步：如果文件缺失，重新运行安装脚本

cd C:\Workspace\everything-claude-code
.\install.ps1 --profile full

第 3 步：确认 hooks.json 被正确加载

检查 C:\Users\<用户名>\.claude\settings.json 中是否包含 hooks 配置。如果使用插件方式安装，Hooks 会自动注册。如果手动安装，需要在 settings.json 中添加：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/hooks/session-start.js"
          }
        ]
      }
    ]
  }
}

验证

# 启动 Claude Code 并执行一个 Edit 操作
claude
# 在 Claude Code 中让它编辑一个文件，观察是否有 Hook 输出

正常情况下，PostToolUse Hook 应输出质量检查结果或格式化提示。如果使用 ECC_HOOK_PROFILE=strict，输出会更详细。

---

十四、日常维护

14.1 启停命令

# 启动 Claude Code
claude

# 退出 Claude Code（在会话中输入）
/exit
# 或按 Ctrl+C 两次

# 更新 Claude Code CLI
npm update -g @anthropic-ai/claude-code

# 更新 ECC（在仓库目录中）
cd C:\Workspace\everything-claude-code
git pull
.\install.ps1 --profile full

ECC 更新后需要重新运行安装脚本，以同步最新的 hooks、rules 和 agents。

14.2 Hook 运行时控制

# 切换 Hook 严格度
$env:ECC_HOOK_PROFILE = "minimal"    # 仅保留安全相关 Hook
$env:ECC_HOOK_PROFILE = "standard"   # 默认，平衡质量和安全
$env:ECC_HOOK_PROFILE = "strict"     # 严格模式，更多提醒

# 永久写入
[System.Environment]::SetEnvironmentVariable("ECC_HOOK_PROFILE", "standard", "User")

14.3 日志与调试

Claude Code 日志位置：

C:\Users\<用户名>\AppData\Roaming\claude-code\logs\

关键搜索词：

# 查找错误日志
Get-ChildItem "$env:APPDATA\claude-code\logs\*.log" | Select-String "Error" | Select-Object -First 20

# 查找 Hook 相关日志
Get-ChildItem "$env:APPDATA\claude-code\logs\*.log" | Select-String "Hook" | Select-Object -First 20

# 查找 MCP 连接问题
Get-ChildItem "$env:APPDATA\claude-code\logs\*.log" | Select-String "MCP|connection|timeout" | Select-Object -First 20

14.4 查看已安装组件

# 在 Claude Code 中查看已安装的插件
/plugin list

# 查看已安装的 MCP 服务器
claude mcp list

# 查看已配置的 skills
ls "$env:USERPROFILE\.claude\skills"

---

十五、速查卡

15.1 文件路径汇总

文件	绝对路径
Claude Code 配置	C:\Users\<用户名>\.claude\settings.json
项目级配置	C:\Users\<用户名>\.claude\settings.local.json
ECC 仓库目录	C:\Workspace\everything-claude-code\
ECC Rules（通用）	C:\Users\<用户名>\.claude\rules\common\
ECC Rules（语言专用）	C:\Users\<用户名>\.claude\rules\typescript\
ECC Agents	C:\Users\<用户名>\.claude\agents\
ECC Skills	C:\Users\<用户名>\.claude\skills\
ECC Hooks 配置	C:\Users\<用户名>\.claude\hooks\hooks.json
ECC Hook 脚本	C:\Workspace\everything-claude-code\scripts\hooks\
MCP 服务器配置	C:\Users\<用户名>\.claude\settings.json（mcpServers 字段）
项目 CLAUDE.md	C:\Workspace\你的项目\CLAUDE.md
用户级 CLAUDE.md	C:\Users\<用户名>\.claude\CLAUDE.md
Claude Code 日志	C:\Users\<用户名>\AppData\Roaming\claude-code\logs\
npm 全局目录	C:\Users\<用户名>\npm-global\

15.2 关键配置字段速查表

配置项	文件	说明
ANTHROPIC_API_KEY	环境变量	API 密钥
ANTHROPIC_BASE_URL	环境变量	API 代理地址（使用代理时必设）
ECC_HOOK_PROFILE	环境变量	Hook 严格度：minimal / standard / strict
ECC_DISABLED_HOOKS	环境变量	逗号分隔的禁用 Hook ID 列表
CLAUDE_PACKAGE_MANAGER	环境变量	包管理器偏好：npm / pnpm / yarn / bun
mcpServers	settings.json	MCP 服务器配置（command + args + env）
hooks	settings.json	Hook 事件绑定（PreToolUse / PostToolUse / Stop 等）

15.3 常见报错 → 解决方案映射表

报错特征	解决方案
EACCES / EPERM 全局安装	迁移 npm 全局目录到用户空间 → Debug #1
git clone 超时 / 速度极慢	使用镜像站点或 SSH → Debug #2
禁止运行脚本 / UnauthorizedAccess	Set-ExecutionPolicy RemoteSigned → Debug #3
Hook TypeError: Cannot read properties	确认 scripts/hooks/ 完整 → Debug #4
401 Invalid API Key	检查 Key 有效性 + Base URL 配置 → Debug #5
Connection error / 超时	检查 ANTHROPIC_BASE_URL 和网络代理
/plan 等命令无反应	确认 rules 和 agents 已安装（ls ~/.claude/rules）
MCP 服务器连接失败	确认从 PowerShell 启动，非 cmd.exe
command not found: claude	npm 全局目录未在 PATH 中，重新打开终端

15.4 作业流水线速查表

场景	流水线	命令序列
开始新功能	功能开发流	/plan → 确认 → /tdd → /code-review → /checkpoint
构建报错	修复流	/build-fix
上班开工	恢复流	claude → /resume-session
下班收工	保存流	/save-session
上下文快满了	压缩流	/context-budget → /checkpoint 或 /compact
旁问无关问题	旁路流	/aside
提交前审查	安全流	/security-review → /code-review
多人/全栈协作	多模型流	/everything-claude-code:multi-plan → multi-execute

---

十六、参考文献

• Claude Code 官方文档 — Anthropic 官方 Claude Code 文档，安装和认证方式的权威来源
• Everything Claude Code GitHub 仓库 — ECC v1.10.0 仓库，本文安装配置的核心参考
• Everything Claude Code 简体中文 README — ECC 中文翻译，快速入门步骤参考
• Anthropic Console — 获取 API Key 的官方入口
• npm @anthropic-ai/claude-code — Claude Code CLI 的 npm 包页面，确认最新版本号
• fnm (Fast Node Manager) — 推荐的 Node.js 版本管理器，避免 Windows 权限问题
• Model Context Protocol 规范 — MCP 协议官方文档，理解 MCP 服务器配置机制
• ECC Agents 文档 — ECC 子代理体系说明，理解 Agent 自动派遣机制
• ECC Commands Quick Reference — ECC 全部斜杠命令速查，第六~九章流水线的命令来源
• ECC Shortform Guide — ECC 快速上手指南，涵盖 Skills、Hooks、Rules 的核心用法