Claude-Code配置学习笔记-MCP-Hooks与ECC插件系统

摘要：Claude Code配置指南（Windows平台）本文记录了在Windows 11环境下配置Claude Code的ECC插件系统的完整过程，重点解决MCP服务器连接、Hooks不生效等常见问题。主要内容包括： MCP服务器配置：详细介绍Windows特有的路径格式和cmd/c包装器解决方案提供完整的JSON配置示例和环境变量设置包含常见错误速查表，如"spawn nod

WMM3302512997

396人浏览 · 2026-05-04 00:14:02

WMM3302512997 · 2026-05-04 00:14:02 发布

Claude-Code配置学习笔记-MCP-Hooks与ECC插件系统

📅 整理时间：2026-05-01 ~ 2026-05-03
💻 环境：Windows 11 + Node.js v24.12.0 + Git Bash
⏱️ 预计阅读：25 分钟
🏷️ 关键词：Claude Code, MCP, Hooks, Plugins, ECC, Windows 配置

写在前面

这篇文章是我配置 ECC (Everything Claude Code) 插件过程中的完整学习记录。

在尝试安装 ECC 插件时，我遇到了一系列问题：MCP 服务器连接失败、Hooks 不生效、配置文件加载异常……折腾了整整两天，查阅了官方文档、GitHub Issues、社区文章，才逐一解决。

过程中我意识到，Claude Code 的配置体系虽然强大，但学习资料相对分散，尤其是 Windows 平台的坑特别多（根据社区反馈，配置失败率高达 70%）。于是决定把自己的踩坑经历整理成文，希望能帮到同样在配置路上的朋友。

本文特色：

✅ 从实际问题出发，而非抽象的概念介绍
✅ Windows 平台专属排坑指南
✅ 配置验证命令和检查清单
✅ 结合官方文档和社区经验的理论总结

前言

Claude Code 是 Anthropic 官方推出的 AI 编程助手 CLI 工具。其扩展体系包含 七大核心系统：

序号	系统	全称	作用
1	MCP	Model Context Protocol	扩展 Claude 能力的工具协议
2	Skills	技能	预定义的任务模板，通过 `/skill-name` 调用
3	Rules	规则	定义 Claude 默认行为的指令文件
4	Plugins	插件	一键开启完整功能套件的打包容器
5	Agents	代理	针对特定任务优化的专用 AI 代理
6	Hooks	钩子	工具执行前后的自动化机制
7	Commands	命令	可执行的脚本命令

系统关系：Plugins 是容器，打包了 Skills、Rules、Agents、Hooks、Commands；MCP 是独立的工具协议层。

📝 本文范围：本文重点介绍 MCP、Hooks 和 Plugins 三大系统，并涉及 Plugins 内包含的 Skills、Rules、Agents、Commands 组件。这些是我在配置 ECC 插件过程中实际接触和学习的部分。

本文将从实际配置问题出发，并特别针对 Windows 平台提供详细的排坑指南。

一、MCP 服务器配置

1.1 什么是 MCP

MCP (Model Context Protocol) 是 Anthropic 推出的开放协议，允许 Claude Code 连接外部工具和数据源。通过 MCP，Claude 可以：

读写本地文件系统
搜索 GitHub 仓库
查询文档库（如 Context7）
操作数据库
调用自定义 API

1.2 MCP 服务器类型

类型	通信方式	适用场景
`stdio`	标准输入输出	本地工具、文件系统
`http`	HTTP 请求	云服务、远程 API
`sse`	Server-Sent Events	实时数据流

1.3 Windows 平台 MCP 配置问题

根据网络搜索结果，Windows 上 MCP 配置失败率高达 70%。以下是主要问题及解决方案。

问题一：缺少 `cmd /c` 包装器

Windows 的 stdio 管道机制与 Unix 不同。Claude Code 启动 MCP 子进程时，直接使用 "command": "node" 在 Windows 上常常导致 stdio 握手失败。

解决方案：使用绝对路径或 cmd /c 包装

// 方案一：直接使用 node.exe 绝对路径（推荐）
{
  "command": "C:/Program Files/nodejs/node.exe",
  "args": ["path/to/server.js"]
}

// 方案二：cmd /c 包装
{
  "command": "cmd",
  "args": ["/c", "node", "path/to/server.js"]
}

问题二：PATH 环境变量作用域问题

应用启动子进程时不加载 shell 配置文件（.bashrc 等），因此：

在终端中 node -v 正常
但 MCP 子进程报 spawn node ENOENT（找不到命令）

解决方案：在 settings.json 中正确设置 PATH

// ❌ 错误 - Git Bash 风格，Windows 原生环境不认识
"PATH": "...;/c/Program Files/nodejs;$PATH"

// ✅ 正确 - Windows 风格
"PATH": "...;C:/Program Files/nodejs;${PATH}"

问题三：Health Check 误报

Claude Code 的 claude mcp list 健康检查不会发送 initialize 请求（GitHub Issue #9662），导致 stdio 服务器在 health check 时超时。

⚠️ 这是官方已知问题。health check 失败 ≠ MCP 无法使用，需要在实际对话中测试。

1.4 完整配置示例

`~/.claude.json` (MCP 服务器配置)

{
  "mcpServers": {
    "filesystem": {
      "command": "C:/Program Files/nodejs/node.exe",
      "args": [
        "C:/Users/[用户名]/AppData/Roaming/npm/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js",
        "C:/Users/[用户名]"
      ]
    },
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "your-api-key"
      }
    },
    "memory": {
      "command": "C:/Program Files/nodejs/node.exe",
      "args": [
        "C:/Users/[用户名]/AppData/Roaming/npm/node_modules/@modelcontextprotocol/server-memory/dist/index.js"
      ]
    },
    "github": {
      "command": "C:/Program Files/nodejs/node.exe",
      "args": [
        "C:/Users/[用户名]/AppData/Roaming/npm/node_modules/@modelcontextprotocol/server-github/dist/index.js"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    }
  }
}

`~/.claude/settings.json` (环境变量配置)

{
  "env": {
    "PATH": "C:/Program Files/nodejs;C:/Users/[用户名]/AppData/Roaming/npm;${PATH}"
  }
}

1.5 配置规则速查表

配置项	Windows 要求
`command`	使用 `node.exe` 完整绝对路径，或通过 `cmd /c` 包装
路径格式	使用 `/` 正斜杠或 `\\` 双反斜杠
PATH 变量	Windows 风格路径 + `${PATH}`（非 `$PATH`）
环境变量	在 `env` 字段中设置

1.6 验证 MCP 是否正常工作

手动测试 stdio MCP 服务器

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node "path/to/server.js" "allowed/path"

如果返回 JSON 响应（包含 serverInfo），说明服务器本身正常。

1.7 常见错误速查

错误信息	原因	解决方案
`spawn node ENOENT`	node 不在 PATH 中	使用 node.exe 绝对路径
`spawn npx ENOENT`	npx 不在 PATH 中	使用 `cmd /c npx` 或 npx.cmd 绝对路径
`-32000: Connection closed`	stdio 管道建立失败	使用 `cmd /c` 包装或绝对路径
`startup() initialize handshake timed out`	npx 下载超时	预先全局安装包，或增加 `MCP_TIMEOUT`
health check 失败但功能正常	Issue #9662 已知 Bug	忽略，在实际对话中测试

💡 核心原则：Windows 上 MCP 配置的关键是绕过 PATH 解析，使用绝对路径是最可靠的方式。

二、Hooks 钩子系统

2.1 什么是 Hooks

Hooks 是 Claude Code 的核心自动化机制，允许在工具执行前后插入自定义逻辑，实现：

🔒 安全保护（阻止危险操作）
✨ 自动格式化
✅ 质量检查
📊 状态追踪

2.2 Hook 生命周期

┌─────────────────────────────────────────────────────────────┐
│  SessionStart                                                │
│  └─ 加载上下文、检测包管理器                                   │
├─────────────────────────────────────────────────────────────┤
│  PreToolUse (工具执行前)                                      │
│  ├─ block-no-verify: 阻止跳过 git hooks                      │
│  ├─ auto-tmux-dev: 自动启动开发服务器                         │
│  ├─ tmux-reminder: 提醒使用 tmux 运行长命令                   │
│  ├─ git-push-reminder: git push 前提醒审查                   │
│  ├─ config-protection: 保护配置文件不被修改                   │
│  ├─ mcp-health-check: MCP 健康检查                           │
│  └─ insaits-security: AI 安全监控 (需启用)                    │
├─────────────────────────────────────────────────────────────┤
│  PostToolUse (工具执行后)                                     │
│  ├─ quality-gate: 质量门检查                                 │
│  ├─ format: 自动格式化 JS/TS 文件                             │
│  ├─ typecheck: TypeScript 类型检查                           │
│  ├─ console-warn: console.log 警告                           │
│  └─ observe: 持续学习观察                                    │
├─────────────────────────────────────────────────────────────┤
│  PostToolUseFailure (工具执行失败后)                          │
│  └─ mcp-health-check: 追踪失败的 MCP 调用                     │
├─────────────────────────────────────────────────────────────┤
│  Stop (每次响应结束时)                                        │
│  ├─ check-console-log: 检查 console.log                      │
│  ├─ session-end: 持久化会话状态                               │
│  ├─ evaluate-session: 评估会话模式                           │
│  └─ cost-tracker: 成本追踪                                   │
├─────────────────────────────────────────────────────────────┤
│  SessionEnd                                                  │
│  └─ 会话结束标记                                              │
└─────────────────────────────────────────────────────────────┘

2.3 Hook 类型

类型	触发时机	典型用途
`SessionStart`	会话开始时	加载上下文、初始化环境
`PreToolUse`	工具执行前	验证、参数修改、安全检查
`PostToolUse`	工具执行后	自动格式化、质量检查
`PostToolUseFailure`	工具执行失败后	错误追踪、重连
`Stop`	每次响应结束时	状态持久化、成本追踪
`SessionEnd`	会话结束时	清理、标记

2.4 Matcher 匹配规则

matcher 字段决定 hook 触发时机：

Matcher	触发条件
`"Bash"`	执行 Bash 命令时
`"Edit"`	编辑文件时
`"Write"`	写入文件时
`"Edit\|Write"`	编辑或写入文件时
`"Bash\|Write\|Edit"`	多种工具操作时
`"*"`	所有工具操作时

2.5 Hook 配置结构

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "npx block-no-verify@1.1.2",
            "description": "阻止跳过 git hooks"
          }
        ]
      }
    ]
  }
}

2.6 执行模式参数

参数	说明	示例
`type`	执行类型	`"command"`
`command`	执行命令	`"node script.js"`
`async`	异步执行（不阻塞主流程）	`true`
`timeout`	超时时间（秒）	`30`
`description`	功能描述	`"自动格式化"`

2.7 配置位置

配置类型	路径
全局配置	`~/.claude/settings.json`
全局 MCP	`~/.claude.json`
ECC 插件 Hooks	`~/.claude/everything-claude-code/hooks/hooks.json`

2.8 核心 Hooks 功能说明

安全保护类

Hook	功能
`block-no-verify`	阻止使用 `--no-verify` 跳过 git hooks
`config-protection`	阻止修改 linter/formatter 配置文件
`insaits-security`	AI 安全监控（需 `ECC_ENABLE_INSAITS=1`）

自动化类

Hook	功能
`auto-tmux-dev`	自动在 tmux 中启动开发服务器
`post-edit-format`	编辑 JS/TS 文件后自动格式化
`post-edit-typecheck`	编辑 TypeScript 文件后自动类型检查

质量检查类

Hook	功能
`quality-gate`	文件编辑后运行质量门检查
`console-warn`	检测并警告 `console.log` 语句

运维类

Hook	功能
`mcp-health-check`	检查 MCP 服务器健康状态
`cost-tracker`	追踪 token 使用和成本
`session-end`	持久化会话状态

2.9 Token 消耗说明

项目	Token 消耗
Hook 执行过程	0 token
Hook 输出内容	进入上下文后会被计费
调用模型	从不（hooks 是纯本地/webhook）

关键理解：

Hooks 本身不消耗 token，不调用 Claude API
执行方式是本地 shell 命令或 webhook HTTP 请求
但 Hook 的输出会加入对话上下文，后续对话会消耗这些 token
建议：让 hooks 输出保持简洁，避免大量无用信息进入上下文

2.10 自定义 Hook 示例

方法一：在 settings.json 中添加

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Custom hook: About to run bash command'"
          }
        ]
      }
    ]
  }
}

方法二：创建自定义脚本

// scripts/hooks/my-custom-hook.js
const input = process.stdin.read();
const toolData = JSON.parse(input);

// 检查条件
if (toolData.tool === 'Bash' && toolData.input.command.includes('rm')) {
  console.error('BLOCK: Dangerous rm command detected');
  process.exit(2); // 阻止执行
}

// 允许执行
process.exit(0);

三、插件 Plugins 的使用

3.1 什么是插件

插件是 Claude Code 的扩展机制，允许一键开启一套别人写好的配置。

插件本质理解：

┌─────────────────────────────────────────────────┐
│     插件 (容器)                                 │
│                                                 │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐          │
│  │ Agents  │ │ Skills  │ │Commands │          │
│  └─────────┘ └─────────┘ └─────────┘          │
│  ┌─────────┐ ┌─────────┐                       │
│  │ Hooks   │ │ Rules   │                       │
│  └─────────┘ └─────────┘                       │
└─────────────────────────────────────────────────┘

插件 = 一键开启一套别人写好的配置

类比理解：

插件 ≈ VS Code 扩展 / Chrome 插件
安装后功能模块自动激活
无需逐个复制配置文件

3.2 ECC 插件简介

ECC (Everything Claude Code) 是目前最全面的 Claude Code 插件包，包含：

组件	数量	说明
Agents	38	专用 AI 代理
Skills	156	斜杠命令技能
Commands	72	可执行命令
Rules	16+	行为规则
Hooks	30+	事件驱动自动化

3.3 Skills 详解

Skills 是预定义的任务模板，通过 /skill-name 方式调用。

Skills 分类

ECC 插件提供 156 个 Skills，涵盖多个领域：

分类	示例 Skills
开发流程	`plan`, `review`, `tdd`, `verify`, `ship`
代码质量	`code-review`, `quality-gate`, `test-coverage`
构建修复	`cpp-build`, `go-build`, `rust-build`, `kotlin-build`
代码审查	`python-review`, `rust-review`, `go-review`, `kotlin-review`
调试分析	`investigate`, `health`, `benchmark`
文档生成	`update-docs`, `update-codemaps`, `make-pdf`
部署运维	`setup-deploy`, `canary`, `land-and-deploy`
设计相关	`design-review`, `design-shotgun`, `design-consultation`
测试相关	`e2e`, `qa`, `qa-only`
会话管理	`save-session`, `resume-session`, `context-save`

Skill 文件结构

每个 Skill 是独立目录，包含 SKILL.md 文件：

~/.claude/everything-claude-code/skills/
├── plan/
│   └── SKILL.md          # /plan 技能定义
├── review/
│   └── SKILL.md          # /review 技能定义
├── tdd/
│   └── SKILL.md          # /tdd 技能定义
└── ...

使用示例

# 生成实现计划
/plan

# 代码审查
/review

# TDD 开发流程
/tdd

# 保存会话上下文
/context-save

3.4 Rules 详解

Rules 是行为规则和指令，定义 Claude 的默认行为。

Rules 目录结构

ECC 插件按语言分类组织 Rules：

~/.claude/everything-claude-code/rules/
├── common/              # 通用规则
│   ├── agents.md        # Agent 编排规则
│   ├── code-review.md   # 代码审查规则
│   ├── coding-style.md  # 编码风格
│   ├── development-workflow.md  # 开发流程
│   ├── git-workflow.md  # Git 工作流
│   ├── hooks.md         # Hooks 使用规则
│   ├── patterns.md      # 设计模式
│   ├── performance.md   # 性能优化
│   ├── security.md      # 安全规范
│   └── testing.md       # 测试规范
├── python/              # Python 专属规则
│   ├── coding-style.md
│   ├── patterns.md
│   ├── security.md
│   └── testing.md
├── rust/                # Rust 专属规则
├── golang/              # Go 专属规则
├── kotlin/              # Kotlin 专属规则
├── java/                # Java 专属规则
├── typescript/          # TypeScript 专属规则
├── cpp/                 # C++ 专属规则
├── csharp/              # C# 专属规则
├── dart/                # Dart/Flutter 专属规则
├── swift/               # Swift 专属规则
├── web/                 # Web 前端专属规则
└── zh/                  # 中文版规则

每个语言的 Rules 包含

Rule 文件	内容
`coding-style.md`	编码规范和风格指南
`patterns.md`	语言特定的设计模式
`security.md`	安全最佳实践
`testing.md`	测试策略和规范
`hooks.md`	语言相关的 Hooks 配置

Rules 加载机制

Claude Code 会根据项目类型自动加载对应的 Rules：

检测项目语言（通过文件后缀、配置文件等）
加载 common/ 下的通用规则
加载对应语言的专属规则
用户目录的 Rules 覆盖插件默认规则

3.5 Agents 详解

Agents 是专用 AI 代理，针对特定任务优化。

ECC 提供的 Agents (38 个)

分类	Agents
代码审查	`code-reviewer`, `rust-reviewer`, `python-reviewer`, `go-reviewer`, `kotlin-reviewer`, `typescript-reviewer`, `java-reviewer`, `cpp-reviewer`, `flutter-reviewer`, `csharp-reviewer`
构建修复	`build-error-resolver`, `rust-build-resolver`, `go-build-resolver`, `kotlin-build-resolver`, `java-build-resolver`, `cpp-build-resolver`, `pytorch-build-resolver`, `dart-build-resolver`
安全审查	`security-reviewer`, `database-reviewer`
测试相关	`tdd-guide`, `e2e-runner`
架构设计	`architect`, `planner`
文档维护	`doc-updater`
代码重构	`refactor-cleaner`
性能优化	`performance-optimizer`
其他	`chief-of-staff`, `docs-lookup`, `general-purpose`, `loop-operator`

Agent 自动调用规则

在 ~/.claude/rules/agents.md 中定义了自动调用规则：

场景	自动调用的 Agent
复杂功能请求	`planner`
代码刚写完/修改	`code-reviewer`
Bug 修复或新功能	`tdd-guide`
架构决策	`architect`
构建失败	`build-error-resolver`

3.6 Commands 详解

Commands 是可执行的脚本命令，共 72 个。

常用 Commands

命令	功能
`/init`	初始化新项目
`/review`	代码审查
`/security-review`	安全审查
`/plan`	生成实现计划
`/tdd`	TDD 开发流程
`/verify`	验证实现

3.7 版本更新记录 (v1.9.0 → v1.10.0)

组件	v1.9.0	v1.10.0	变化
Agents	28	38	+10
Skills	56	156	+100
Commands	62	72	+10
Rules	12	16	+4

新增 Agents (v1.10.0)

Agent	功能
`csharp-reviewer`	C# 代码审查
`dart-build-resolver`	Dart/Flutter 构建问题
`gan-evaluator` / `gan-generator` / `gan-planner`	GAN 相关
`healthcare-reviewer`	医疗代码审查
`opensource-forker` / `opensource-packager` / `opensource-sanitizer`	开源项目工具
`performance-optimizer`	性能优化

3.8 配置文件位置

文件	路径
全局配置	`~/.claude.json`
插件配置	`~/.claude/plugins/installed_plugins.json`
用户 Agents	`~/.claude/agents/`
用户 Skills	`~/.claude/skills/`
用户 Rules	`~/.claude/rules/`
ECC 插件	`~/.claude/everything-claude-code/`

3.9 加载优先级

用户目录 (~/.claude/)  →  优先加载（覆盖默认）
         ↓
插件目录 (ECC)  →  作为后备

优先级规则：

用户目录的配置优先于插件默认配置
如果用户目录和插件都有同名文件，用户版本生效
如果用户目录没有某个配置，则使用插件版本

3.10 启用特定功能

通过环境变量控制：

# 启用 AI 安全监控
export ECC_ENABLE_INSAITS=1

# 启用治理捕获
export ECC_GOVERNANCE_CAPTURE=1

3.11 插件 vs 手动配置

方式	操作	维护
插件安装	一键安装所有组件	`claude plugin update` 统一更新
手动配置	逐个复制文件	需要手动同步更新

推荐做法：

安装 ECC 插件获取完整功能
在用户目录添加自定义配置（覆盖或补充）
定期运行 claude plugin update 获取更新

四、配置生效与重启

4.1 彻底重启方法

修改配置后需要彻底重启才能生效：

Claude Code（独立终端版）

输入 /exit 或 Ctrl+C 退出
关闭终端窗口
打开新终端，重新运行 claude

Claude Code（IDE 扩展版，如 Trae、VSCode）

关闭所有 Claude Code 会话
重启 IDE
重新打开 Claude Code

五、故障排查

5.1 MCP 问题排查

问题	排查步骤
连接失败	1. 检查 command 是否使用绝对路径
	2. 检查 PATH 环境变量格式
	3. 手动测试 MCP 服务器
Health check 失败	忽略，在实际对话中测试功能

5.2 Hook 未触发

检查 matcher 是否正确
检查命令路径是否正确
查看日志输出

5.3 Hook 阻塞

检查是否设置了 async: true
增加 timeout 值
检查脚本是否有死循环

六、最佳实践

6.1 安全优先

始终启用 block-no-verify 和 config-protection hooks。

6.2 异步执行

耗时操作使用 async: true 避免阻塞。

6.3 合理超时

设置适当的 timeout 防止卡住。

6.4 日志记录

在 hook 脚本中输出有意义的日志。

6.5 测试验证

新 hook 先在测试环境验证。

七、ECC 插件安装指南

7.1 安装前准备

确保已安装以下依赖：

依赖	版本要求	检查命令
Node.js	v18+	`node -v`
npm	v9+	`npm -v`
Git	任意	`git --version`
Claude Code	最新版	`claude --version`

7.2 安装步骤

方法一：通过 Git 安装（推荐）

# 1. 克隆仓库到用户目录
cd ~/.claude
git clone https://github.com/affaan-m/everything-claude-code.git

# 2. 运行安装脚本
cd everything-claude-code
./install.sh        # Linux/macOS
# 或
powershell -File install.ps1   # Windows PowerShell

方法二：手动下载安装

访问 ECC Releases
下载最新版本的 ZIP 包
解压到 ~/.claude/everything-claude-code/
重启 Claude Code

7.3 验证安装

# 检查插件是否加载
claude plugin list

# 检查 skills 是否可用
ls ~/.claude/everything-claude-code/skills/ | wc -l

# 检查 rules 是否加载
ls ~/.claude/everything-claude-code/rules/common/

7.4 更新 ECC

cd ~/.claude/everything-claude-code
git pull origin main

# 或重新下载最新版本

八、配置验证清单

8.1 MCP 验证命令

# 列出所有 MCP 服务器状态
claude mcp list

# 手动测试 stdio MCP 服务器
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node "path/to/server.js"

8.2 配置文件检查清单

检查项	路径	命令
全局配置存在	`~/.claude.json`	`cat ~/.claude.json`
用户设置存在	`~/.claude/settings.json`	`cat ~/.claude/settings.json`
插件已注册	`~/.claude/plugins/installed_plugins.json`	`cat ~/.claude/plugins/installed_plugins.json`
MCP 服务器配置正确	`~/.claude.json` 中的 `mcpServers`	检查 JSON 格式

8.3 完整配置检查脚本

#!/bin/bash
# 保存为 check-claude-config.sh

echo "=== Claude Code 配置检查 ==="
echo ""

echo "1. 检查 Node.js..."
node -v || echo "❌ Node.js 未安装"

echo ""
echo "2. 检查 Claude Code..."
claude --version || echo "❌ Claude Code 未安装"

echo ""
echo "3. 检查 MCP 配置..."
if [ -f ~/.claude.json ]; then
    echo "✅ ~/.claude.json 存在"
    cat ~/.claude.json | grep -o '"mcpServers"' > /dev/null && echo "✅ MCP 服务器已配置" || echo "⚠️ 未配置 MCP 服务器"
else
    echo "❌ ~/.claude.json 不存在"
fi

echo ""
echo "4. 检查用户设置..."
if [ -f ~/.claude/settings.json ]; then
    echo "✅ ~/.claude/settings.json 存在"
else
    echo "⚠️ ~/.claude/settings.json 不存在（使用默认设置）"
fi

echo ""
echo "5. 检查 ECC 插件..."
if [ -d ~/.claude/everything-claude-code ]; then
    echo "✅ ECC 插件已安装"
    SKILLS=$(ls ~/.claude/everything-claude-code/skills/ 2>/dev/null | wc -l)
    RULES=$(find ~/.claude/everything-claude-code/rules -name "*.md" 2>/dev/null | wc -l)
    AGENTS=$(ls ~/.claude/everything-claude-code/agents/ 2>/dev/null | wc -l)
    echo "   - Skills: $SKILLS"
    echo "   - Rules: $RULES"
    echo "   - Agents: $AGENTS"
else
    echo "⚠️ ECC 插件未安装"
fi

echo ""
echo "=== 检查完成 ==="

九、记忆系统

9.1 什么是记忆系统

Claude Code 提供了记忆（Memory）功能，允许跨会话保存和检索信息。

9.2 记忆存储位置

类型	路径	作用域
全局记忆	`~/.claude/memory/`	所有项目共享
项目记忆	`~/.claude/projects/[project-id]/memory/`	单个项目

9.3 记忆相关 MCP 工具

通过 memory MCP 服务器提供以下工具：

工具	功能
`create_entities`	创建实体
`create_relations`	创建关系
`add_observations`	添加观察
`search_nodes`	搜索节点
`read_graph`	读取图谱
`delete_entities`	删除实体

9.4 使用场景

记住用户偏好和习惯
保存项目特定的约定和规则
跨会话保持上下文信息

十、常见问题 FAQ

Q1: MCP 服务器显示连接失败，但功能正常？

原因：Claude Code 的 health check 有 Bug（Issue #9662），不会发送 initialize 请求。

解决：忽略 health check 结果，在实际对话中测试 MCP 功能。

Q2: 修改配置后不生效？

原因：Claude Code 可能有残留进程。

解决：

输入 /exit 退出
关闭终端窗口
重新打开终端运行 claude

Q3: Windows 上报 `spawn node ENOENT`？

原因：子进程不加载 shell 配置，找不到 node 命令。

解决：在 MCP 配置中使用 node.exe 的绝对路径：

{
  "command": "C:/Program Files/nodejs/node.exe",
  "args": ["path/to/server.js"]
}

Q4: Hooks 没有触发？

排查步骤：

检查 matcher 是否正确
检查命令路径是否正确
查看终端是否有错误输出
确认配置文件位置正确

Q5: 如何查看当前加载了哪些 Skills/Rules？

# 查看 ECC 插件的 Skills
ls ~/.claude/everything-claude-code/skills/

# 查看用户自定义的 Skills
ls ~/.claude/skills/

# 查看 Rules
ls ~/.claude/everything-claude-code/rules/common/
ls ~/.claude/rules/

Q6: 插件和用户配置冲突怎么办？

优先级规则：用户目录 > 插件目录

如果用户目录有同名文件，用户版本会覆盖插件版本。建议：

十一、参考资源

官方文档

社区资源

GitHub Issues

Issue #9662 - Health Check Bug

结语

写这篇文章的时候，我回顾了自己两天的踩坑历程：从最初 MCP 连接失败的迷茫，到逐一排查 PATH、绝对路径、health check bug；从对 Hooks 一知半解，到理解其事件驱动的工作机制；从手动复制配置文件，到发现插件"一键开启"的便利。

这个过程中最大的感悟是：Claude Code 的配置体系设计得很好，但文档分散、Windows 兼容性问题多。希望这篇文章能帮助后来者少走弯路。

七大核心系统速查：

系统	核心理解
MCP	工具协议，连接外部工具和数据源，Windows 上使用绝对路径
Skills	任务模板，通过 `/skill-name` 调用，156+ 个可选
Rules	行为规则，定义 Claude 默认行为，按语言分类组织
Plugins	功能套件，一键开启完整配置，包含其他组件
Agents	专用代理，针对特定任务优化，38+ 个可选
Hooks	自动化机制，事件驱动，零 token 消耗
Commands	可执行命令，72+ 个可用

本文重点：MCP 配置（Windows 排坑）、Hooks 系统、Plugins 插件（含 Skills/Rules/Agents/Commands）。

配置优先级：用户目录 > 插件目录

如果你在配置过程中遇到其他问题，欢迎在评论区交流！

作者：王木木
整理工具：Claude Code + Obsidian

附录：文章结构导航

前言：七大核心系统概览（本文聚焦 MCP、Hooks、Plugins）

一、MCP 服务器配置
   ├── 什么是 MCP
   ├── MCP 服务器类型
   ├── Windows 平台配置问题（重点）
   ├── 完整配置示例
   └── 常见错误速查

二、Hooks 钩子系统
   ├── Hook 生命周期
   ├── Hook 类型与匹配规则
   ├── 配置结构
   └── Token 消耗说明

三、Plugins 插件系统
   ├── 什么是插件
   ├── ECC 插件简介
   ├── Skills 详解
   ├── Rules 详解
   ├── Agents 详解
   ├── Commands 详解
   └── 加载优先级

四、配置生效与重启

五、故障排查

六、最佳实践

七、ECC 插件安装指南

八、配置验证清单

九、记忆系统

十、常见问题 FAQ

十一、参考资源

openEuler 社区

openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目，面向数字基础设施四大核心场景（服务器、云计算、边缘计算、嵌入式），全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构

更多推荐

操作系统之线程

进程是资源分配的基本单位，而线程是任务器进行任务调度的最小单位线程和进程在某一些程度上是差不多的，所以我们可以类比一下对于进程，我们有PCB，而对于线程，我们也有，叫TCB，保存每一个线程的状态。但是线程之间的上下文切换有一点主要的区别：地址空间保持不变（即不需要切换当前使用的页表）线程和进程之间的主要区别在于栈，在传统的进程地址空间模型可以称为单线程，只有一个栈但是在多线程运行的时候，每个线程可

openEuler 社区

端口号：明明是“本地”的，为什么还要“统一分配”？

问题答案端口号是本地意义吗？是，只在一台主机内区分进程为什么还要统一分配？为了让客户端无需配置就能找到服务器统一分配强制吗？熟知端口是强烈约定，登记端口是建议谁需要固定端口？只有服务器客户端用什么端口？临时端口，动态分配端口冲突发生在哪？同一台主机上的多个服务器之间同一主机内通信必须用端口吗？走 TCP/IP 需要，走其他 IPC 不需要MySQL 下载的是服务器还是客户端？通常两者都有前端/后端

openEuler 社区

揭秘epoll：高并发服务器的终极武器

openEuler 社区

所有评论(0)

查看更多评论

WMM3302512997

@WMM3302512997

已为社区贡献2条内容

Claude-Code配置学习笔记-MCP-Hooks与ECC插件系统

WMM3302512997

Claude-Code配置学习笔记-MCP-Hooks与ECC插件系统

写在前面

前言

一、MCP 服务器配置

1.1 什么是 MCP

1.2 MCP 服务器类型

1.3 Windows 平台 MCP 配置问题

问题一：缺少 cmd /c 包装器

问题二：PATH 环境变量作用域问题

问题三：Health Check 误报

1.4 完整配置示例

~/.claude.json (MCP 服务器配置)

~/.claude/settings.json (环境变量配置)

1.5 配置规则速查表

1.6 验证 MCP 是否正常工作

手动测试 stdio MCP 服务器

1.7 常见错误速查

二、Hooks 钩子系统

2.1 什么是 Hooks

2.2 Hook 生命周期

2.3 Hook 类型

2.4 Matcher 匹配规则

2.5 Hook 配置结构

2.6 执行模式参数

2.7 配置位置

2.8 核心 Hooks 功能说明

安全保护类

自动化类

质量检查类

运维类

2.9 Token 消耗说明

2.10 自定义 Hook 示例

方法一：在 settings.json 中添加

方法二：创建自定义脚本

三、插件 Plugins 的使用

3.1 什么是插件

3.2 ECC 插件简介

3.3 Skills 详解

Skills 分类

Skill 文件结构

使用示例

3.4 Rules 详解

Rules 目录结构

每个语言的 Rules 包含

Rules 加载机制

3.5 Agents 详解

ECC 提供的 Agents (38 个)

Agent 自动调用规则

3.6 Commands 详解

常用 Commands

3.7 版本更新记录 (v1.9.0 → v1.10.0)

新增 Agents (v1.10.0)

3.8 配置文件位置

3.9 加载优先级

3.10 启用特定功能

3.11 插件 vs 手动配置

四、配置生效与重启

4.1 彻底重启方法

Claude Code（独立终端版）

Claude Code（IDE 扩展版，如 Trae、VSCode）

五、故障排查

5.1 MCP 问题排查

5.2 Hook 未触发

5.3 Hook 阻塞

六、最佳实践

6.1 安全优先

6.2 异步执行

6.3 合理超时

6.4 日志记录

6.5 测试验证

七、ECC 插件安装指南

7.1 安装前准备

7.2 安装步骤

方法一：通过 Git 安装（推荐）

方法二：手动下载安装

7.3 验证安装

7.4 更新 ECC

八、配置验证清单

问题一：缺少 `cmd /c` 包装器

`~/.claude.json` (MCP 服务器配置)

`~/.claude/settings.json` (环境变量配置)

Q3: Windows 上报 `spawn node ENOENT`？