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 工具。其扩展体系包含 七大核心系统：

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

系统关系：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标准输入输出本地工具、文件系统
httpHTTP 请求云服务、远程 API
sseServer-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 ENOENTnode 不在 PATH 中使用 node.exe 绝对路径
spawn npx ENOENTnpx 不在 PATH 中使用 cmd /c npx 或 npx.cmd 绝对路径
-32000: Connection closedstdio 管道建立失败使用 cmd /c 包装或绝对路径
startup() initialize handshake timed outnpx 下载超时预先全局安装包，或增加 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-securityAI 安全监控（需 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 插件包，包含：

组件数量说明
Agents38专用 AI 代理
Skills156斜杠命令技能
Commands72可执行命令
Rules16+行为规则
Hooks30+事件驱动自动化

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：

  1. 检测项目语言（通过文件后缀、配置文件等）
  2. 加载 common/ 下的通用规则
  3. 加载对应语言的专属规则
  4. 用户目录的 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生成实现计划
/tddTDD 开发流程
/verify验证实现

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

组件v1.9.0v1.10.0变化
Agents2838+10
Skills56156+100
Commands6272+10
Rules1216+4
新增 Agents (v1.10.0)
Agent功能
csharp-reviewerC# 代码审查
dart-build-resolverDart/Flutter 构建问题
gan-evaluator / gan-generator / gan-plannerGAN 相关
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)  →  作为后备

优先级规则：

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

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（独立终端版）
  1. 输入 /exit 或 Ctrl+C 退出
  2. 关闭终端窗口
  3. 打开新终端，重新运行 claude
Claude Code（IDE 扩展版，如 Trae、VSCode）
  1. 关闭所有 Claude Code 会话
  2. 重启 IDE
  3. 重新打开 Claude Code

五、故障排查

5.1 MCP 问题排查

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

5.2 Hook 未触发

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

5.3 Hook 阻塞

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

六、最佳实践

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.jsv18+node -v
npmv9+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
方法二：手动下载安装
  1. 访问 ECC Releases
  2. 下载最新版本的 ZIP 包
  3. 解压到 ~/.claude/everything-claude-code/
  4. 重启 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.jsoncat ~/.claude.json
用户设置存在~/.claude/settings.jsoncat ~/.claude/settings.json
插件已注册~/.claude/plugins/installed_plugins.jsoncat ~/.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 可能有残留进程。

解决：

  1. 输入 /exit 退出
  2. 关闭终端窗口
  3. 重新打开终端运行 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 没有触发？

排查步骤：

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

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

结语

写这篇文章的时候，我回顾了自己两天的踩坑历程：从最初 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

十一、参考资源
# 学习
Logo
AI编程社区

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

码道 · 寻艺——从零构建“非遗交互式对话平台“的完整实践

avatar AI编程社区

码道：用 Python + FastAPI 快速构建一个学生信息管理接口：从零到 Swagger 在线文档

在日常开发和教学中，我们经常需要一套简单、可控、能快速上手的后端接口来演示"前后端分离"、练习 Restful API 设计，或者作为前端联调的 Mock 服务。传统做法往往是搭一套完整的 Web 工程：配置数据库、编写 DAO、引入 ORM、做请求分发……一套流程下来，光环境搭建就要花去不少时间，对于想快速验证想法、或者刚入门 API 开发的同学来说，显得过于沉重。

avatar AI编程社区

码道：从零构建学生信息管理系统 API：FastAPI 内存版 CRUD 项目全解析

FastAPI 的强大，很大程度上来自 Pydantic 的校验能力。我们写下类型声明，FastAPI 在运行时自动把它变成边界检查器。name：字符串，长度限制 1 到 50；age：整数，限制在 6 到 120 之间（ge大于等于、le小于等于）；gender：字符串，用正则限定只能是"男"“女”“其他”；email：邮箱格式字符串；grade与major：可选字段，代表班级和专业方向。

avatar AI编程社区