ECC 故障排查实战指南：内存、Harness、Hook 与安装问题全解析

导读

本文是 Everything Claude Code（ECC）插件体系在 Claude Code、OpenCode、Codex、Cursor 等 Agent Harness 环境中运行时的系统化排障手册。ECC 通过 Hooks、Skills、Memory（连续学习观测）与命令行工具把「过程感知」注入 Agent 工作流，因此大多数故障都集中在四个层面：上下文与记忆持久化、Agent/Harness 进程、Hook 触发与生命周期、安装与运行时环境。读完本文，你将掌握这些故障的典型症状、根因定位方法、可复制的修复命令，以及诊断信息的收集规范，从而在真实项目里把排查时间从数小时压缩到数分钟。文中所有命令均以仓库当前版本（VERSION 为 2.2.1）的安装布局与源码逻辑为依据，针对你的实际安装路径可微调后直接执行。

---

故障排查方法论：先定位，再动手

ECC 的常见故障大多可以沿三条主线定位：

1. 按调用链分层排查：Session 启动 → 记忆上下文装载（session-start.js）→ 每次工具调用前的观测钩子（observe-runner.js）→ PreCompact 状态保存 → Session 结束持久化。任一层损坏都会导致「记忆丢失」或「行为异常」。
2. 先看管理面，再动文件：安装或状态类故障优先运行 ecc doctor、ecc repair、ecc list-installed 这类自检工具（入口见 scripts/doctor.js、scripts/repair.js、scripts/list-installed.js），它们能报告文件漂移并修复，而不是直接删除或重装。
3. 保留现场，宁可备份不删除：对配置文件、观测文件、插件缓存一律先备份为带时间戳的副本，再做清理或重装。

下面的章节按原文档的分类逐项展开：Memory & Context、Agent Harness、Hook & Workflow、安装与 Setup、性能、常见错误信息与求助渠道。

---

一、内存与上下文问题（Memory & Context Issues）

ECC 的内存能力由 hooks/hooks.json 中注册的连续学习与持久化钩子驱动，可执行实现位于 scripts/hooks/，包括 session-start.js（会话启动时装载有界历史上下文）、pre-compact.js（压缩前保存状态）、session-end.js（会话结束持久化摘要）与 observe-runner.js（记录工具调用观测）。生命周期的完整约定见 hooks/memory-persistence/README.md。本节两个典型故障都围绕这套链路展开。

1.1 上下文窗口溢出（Context Window Overflow）

症状：出现 “Context too long” 报错，或 Agent 回复不完整。

常见成因：

• 单次上传超大文件，超出 token 上限；
• 会话内历史累积过多（多轮长对话、反复的完整文件回显）；
• 单次会话中多个工具产生超大输出（如 cat 整个目录、大日志全文）。

解决方案（按优先级执行）：

# 1. 清空会话历史，重新开始
# Claude Code：New Chat 或 Cmd/Ctrl+Shift+N

# 2. 分析前先裁剪文件体量（取前 100 行抽样）
head -n 100 large-file.log > sample.log

# 3. 大输出用流式/分页查看，而不是整段灌入上下文
head -n 50 large-file.txt

# 4. 把大任务拆成小批次
# 不要写："Analyze all 50 files"
# 而要写："Analyze files in src/components/ directory"

补充说明：在 ECC 的钩子体系里，PreCompact 阶段的 pre:compact 钩子（见 hooks/hooks.json 中 PreCompact 段）会在上下文压缩前保存状态。若经常溢出，可以主动触发压缩，而不是等系统提示；commands/ 目录中的相关命令（如 aside、checkpoint）也提供了会话状态管理手段，可作为长会话的辅助工具。

1.2 记忆持久化失败（Memory Persistence Failures）

症状：Agent 记不住之前的上下文与观测结果，每次会话都「失忆」。

常见成因：

• continuous-learning 相关的钩子被禁用（被 ECC_DISABLED_HOOKS、ECC_HOOK_PROFILE 等 profile 开关剔除，见 hooks/memory-persistence/README.md 的 Operator Expectations）；
• 观测文件（observations.jsonl）损坏或目录权限异常；
• 项目根目录检测失败，找不到当前项目对应的 hash id。

解决方案：

# 检查观测是否在正常落盘（按项目目录分组）
ls ~/.claude/homunculus/projects/*/observations.jsonl

# 找到当前项目的 hash id（ECC 按项目根路径哈希归档）
python3 - <<'PY'
import json, os
registry_path = os.path.expanduser("~/.claude/homunculus/projects.json")
with open(registry_path) as f:
    registry = json.load(f)
for project_id, meta in registry.items():
    if meta.get("root") == os.getcwd():
        print(project_id)
        break
else:
    raise SystemExit("Project hash not found in ~/.claude/homunculus/projects.json")
PY

# 查看该项目最近的观测记录
tail -20 ~/.claude/homunculus/projects/<project-hash>/observations.jsonl

# 在重建前先给损坏的观测文件做时间戳备份
mv ~/.claude/homunculus/projects/<project-hash>/observations.jsonl \
  ~/.claude/homunculus/projects/<project-hash>/observations.jsonl.bak.$(date +%Y%m%d-%H%M%S)

# 确认观测钩子仍被启用（settings 中应能找到 observe 相关注册）
grep -r "observe" ~/.claude/settings.json

原理解读：观测记录是在 PreToolUse（pre:observe:continuous-learning）与 PostToolUse（post:observe:continuous-learning）阶段由 observe-runner.js 写出的学习信号，这两个钩子在 hooks/hooks.json 中注册为异步且带 10 秒超时，设计为不阻塞主流程。观测文件长期不写入，除了检查 settings 注册，还应确认 hook 脚本可执行、目录可写；一旦确认 observations.jsonl 损坏，不要直接删文件，而应按上文先 mv 备份再让它重建。

---

二、Agent Harness 运行失败（Agent Harness Failures）

2.1 Agent 未加载（Agent Not Found）

症状：报 “Agent not loaded” 或 “Unknown agent” 错误。

常见成因：

• 插件未正确安装或未完成加载；
• Agent 路径配置错误（marketplace 安装与手动安装的目录不一致）；
• marketplace 缓存与手动安装相互干扰。

解决方案：

# 检查插件安装情况
ls ~/.claude/plugins/cache/

# 确认 marketplace 安装下 agent 存在
ls ~/.claude/plugins/cache/*/agents/

# 手动安装时，agents 应位于：
ls ~/.claude/agents/  # 仅自定义 agents

# 重载插件
# Claude Code → Settings → Extensions → Reload

2.2 工作流执行卡死（Workflow Execution Hangs）

症状：Agent 启动了但始终不结束。

常见成因：

• Agent 逻辑陷入死循环（观测回路、自递归任务）；
• 等待用户输入而被阻塞；
• 调用远端 API 时网络超时。

解决方案：

# 1. 找出卡住的进程
ps aux | grep claude

# 2. 开启调试模式，观察卡在哪个阶段
export CLAUDE_DEBUG=1

# 3. 设置更短的超时，避免无限等待
export CLAUDE_TIMEOUT=30

# 4. 检查网络连通性
curl -I https://api.anthropic.com

2.3 工具调用错误（Tool Use Errors）

症状：报 “Tool execution failed” 或 permission denied。

常见成因：

• 依赖缺失（npm、python 等未安装）；
• 文件/脚本权限不足；
• 引用路径不存在。

解决方案：

# 校验运行期依赖
which node python3 npm git

# 修复 hook 脚本的可执行位
chmod +x ~/.claude/plugins/cache/*/hooks/*.sh
chmod +x ~/.claude/plugins/cache/*/skills/*/hooks/*.sh

# 检查 PATH 是否包含必要二进制
echo $PATH

注意：ECC 的 JavaScript 钩子经 node 启动（注册入口为 node scripts/hooks/plugin-hook-bootstrap.js 转发到具体 runner，见 hooks/hooks.json），node 缺失或版本过旧会导致整套钩子静默失效，务必首先确认 node --version 满足要求（仓库 package.json 声明 engines.node >= 18）。

---

三、Hook 与工作流错误（Hook & Workflow Errors）

3.1 Hook 不触发（Hooks Not Firing）

症状：Pre/Post 钩子完全没有执行。

常见成因：

• settings.json 里未注册 hooks（或注册被覆盖）；
• hook 语法/JSON 结构错误；
• hook 脚本没有可执行权限。

解决方案：

# 检查 hooks 是否已注册到 settings
grep -A 10 '"hooks"' ~/.claude/settings.json

# 确认 hook 文件存在且可执行
ls -la ~/.claude/plugins/cache/*/hooks/

# 手动模拟一次 PreToolUse Bash 事件，验证 runner 是否工作
bash ~/.claude/plugins/cache/*/hooks/pre-bash.sh <<< '{"command":"echo test"}'

# 若使用插件方式安装，重新注册钩子：
# 在 Claude Code settings 中先禁用再启用插件

原理解读：仓库的插件级钩子定义在 hooks/hooks.json，它对不同事件（PreToolUse、PreCompact、SessionStart 等）注册了多个带独立 id 的钩子，例如 pre:observe:continuous-learning、pre:config-protection、pre:compact、pre:write:doc-file-warning 等。钩子实际执行时通过 plugin-hook-bootstrap.js 先解析 ECC 根目录（依据 CLAUDE_PLUGIN_ROOT 或 ~/.claude/plugins 下的候选路径），再加载具体 runner。因此「不触发」除了检查注册，还要留意解析出的插件根目录是否与安装位置一致。

3.2 Python / Node 版本不匹配

症状：报 “python3 not found” 或 “node: command not found”。

常见成因：

• Python / Node 未安装；
• PATH 未正确配置；
• Windows 上 python 与 python3 命名差异导致脚本解析失败。

解决方案：

# 缺失时先安装 Python 3
# macOS: brew install python3
# Ubuntu: sudo apt install python3
# Windows: 从 python.org 下载安装

# 缺失时安装 Node.js
# macOS: brew install node
# Ubuntu: sudo apt install nodejs npm
# Windows: 从 nodejs.org 下载安装

# 验证安装
python3 --version
node --version
npm --version

# Windows：确认 python（而非 python3）可用
python --version

3.3 开发服务器拦截误报（Dev Server Blocker False Positives）

症状：Hook 把本应放行的命令（参数里恰好包含 “dev”）误判为开发服务器并拦截。

常见成因：

• heredoc 内容命中模式匹配；
• 非 dev 命令的参数中包含 “dev” 字样。

解决方案：

# 该问题在 v1.8.0+（PR #371）已修复，优先升级插件到最新版本

# 绕过方案：把 dev 服务器放进 tmux 会话
tmux new-session -d -s dev "npm run dev"
tmux attach -t dev

# 临时禁用：编辑 ~/.claude/settings.json，移除 pre-bash hook 后重载

这是典型的「模式匹配误伤」类问题，与本仓库质量门禁钩子（pre:bash dispatcher 会拦截 pnpm dev / npm run dev 等命令，匹配规则见 scripts/lib/package-manager.js）的行为相关。升级后若仍需临时放行，优先用 tmux 包装而非长期关闭钩子。

---

四、安装与 Setup 问题（Installation & Setup）

4.1 插件不加载（Plugin Not Loading）

症状：安装后插件功能全部不可用。

常见成因：

• marketplace 缓存未刷新；
• Claude Code 版本不兼容；
• 插件文件损坏或复制不完整；
• 本地 Claude 环境被重置/清空。

解决方案：

# 1. 先检查 ECC 对当前机器的登记状态，而不是急于重装
ecc list-installed
ecc doctor
ecc repair

# 2. 仅当 doctor/repair 无法恢复缺失文件时才考虑重装

# 3. 动插件缓存之前先查看内容
ls -la ~/.claude/plugins/cache/

# 4. 用备份代替原地删除
mv ~/.claude/plugins/cache ~/.claude/plugins/cache.backup.$(date +%Y%m%d-%H%M%S)
mkdir -p ~/.claude/plugins/cache

# 5. 从 marketplace 重装
# Claude Code → Extensions → Everything Claude Code → Uninstall
# 然后重新从 marketplace 安装

# 若实际问题是 marketplace/账号访问，应走 ECC Tools 计费/账号恢复流程，
# 不要把重装当成账号恢复的替代手段

# 6. 检查 Claude Code 版本（ECC 要求 Claude Code 2.0+）
claude --version

# 7. marketplace 失败时的手动安装
git clone https://github.com/affaan-m/everything-claude-code.git
cp -r everything-claude-code ~/.claude/plugins/ecc

源码佐证：仓库 package.json 的 bin 字段声明了 ecc → scripts/ecc.js、ecc-install → scripts/install-apply.js 等命令别名，说明 ecc doctor / ecc repair / ecc list-installed 是官方提供的一线自检与修复入口（对应实现文件为 scripts/doctor.js、scripts/repair.js、scripts/list-installed.js）。先跑这三条命令、确认「已知漂移」被修复，通常可以避免整套重装的成本与风险。

4.2 包管理器识别错误（Package Manager Detection Fails）

症状：项目使用了错误包管理器（如本该 pnpm 却用了 npm）。

常见成因：

• 项目没有 lockfile；
• CLAUDE_PACKAGE_MANAGER 未设置；
• 多个 lockfile 同时存在导致检测歧义。

解决方案：

# 全局固定首选包管理器
export CLAUDE_PACKAGE_MANAGER=pnpm
# 写入 ~/.bashrc 或 ~/.zshrc 持久生效

# 或按项目固定
echo '{"packageManager": "pnpm"}' > .claude/package-manager.json

# 或用 package.json 的 packageManager 字段
npm pkg set packageManager="pnpm@8.15.0"

# 警告：删除 lockfile 会改变已安装依赖版本。
# 先提交或备份 lockfile，再全新安装并重跑 CI。
# 仅在确实要切换包管理器时才执行：
rm package-lock.json  # 切换至 pnpm/yarn/bun 时

原理解读（检测优先级）：从源码 scripts/lib/package-manager.js 可以看到，ECC 的包管理器解析顺序为：环境变量 CLAUDE_PACKAGE_MANAGER → .claude/package-manager.json 的 packageManager 字段 → 全局配置 → package.json 的 packageManager 字段 → lockfile 推断，其中 lockfile 推断按 DETECTION_PRIORITY = ['pnpm', 'bun', 'yarn', 'npm'] 执行（即项目同时存在多种 lockfile 时优先认 pnpm）。支持范围在文件头注释中标明：npm、pnpm、yarn、bun。因此「误用 npm」的排查顺序应该是：先确认没有残留的 package-lock.json 干扰判断，再检查上述各级显式配置是否存在冲突。

4.3 OpenCode 在 Termux / Android 上启动失败

症状：changed-files 追踪静默失效（OpenCode 日志出现一次性警告 [ECC] changed-files tracking disabled），或在旧版本上 OpenCode 启动即崩溃，抛出 Bun 的 ResolveMessage，例如：

ResolveMessage: Cannot find module '../plugins/lib/changed-files-store.js' from '.../.opencode/tools/changed-files.ts'

成因：~/.opencode 安装不完整——通常 tools/ 与 plugins/ 都在，但 plugins/lib/ 从未复制完成（安装被中断，或 Android 文件系统上的存储/权限抖动）。changed-files 工具与 ecc-hooks 插件都依赖 plugins/lib/changed-files-store.js；由于 ecc-hooks.ts 是 OpenCode 的插件入口（在会话启动时就加载，早于 tools/index.ts 的 barrel 文件），缺依赖会在任何钩子加载前把整个 OpenCode 会话拖垮，而不只是影响单工具。

解决方案：

# 从 ECC 仓库侧检查并修复缺失/不完整的受管文件
ecc doctor --target opencode
ecc repair --target opencode

# 若报告无漂移但设备上 plugins/ 仍然缺失，
# 则针对 opencode target 重新运行 ECC 安装器

附带提醒：如果你同时看到 ProviderModelNotFoundError: Model not found: openai/gpt-5.5 且引用 ~/.config/opencode/oh-my-opencode-slim.json，该文件属于第三方插件 oh-my-opencode-slim，并非 ECC 所写——ECC 从不写入 ~/.config/opencode/。请在该文件中修正模型前缀（写成 opencode/... 而不是 openai/...），或向该项目提交 issue。

---

五、性能问题（Performance Issues）

5.1 响应缓慢（Slow Response Times）

症状：Agent 响应耗时超过 30 秒。

常见成因：

• 观测文件（observations.jsonl）过大，会话启动装载历史过慢；
• 活跃钩子过多，每次工具调用串行开销放大；
• 到 API 的网络延迟。

解决方案：

# 归档超大观测文件（归档而非删除，保留历史可追溯）
archive_dir="$HOME/.claude/homunculus/archive/$(date +%Y%m%d)"
mkdir -p "$archive_dir"
find ~/.claude/homunculus/projects -name "observations.jsonl" -size +10M -exec sh -c '
  for file do
    base=$(basename "$(dirname "$file")")
    gzip -c "$file" > "'"$archive_dir"'/${base}-observations.jsonl.gz"
    : > "$file"
  done
' sh {} +

# 临时停用不用的钩子
# 编辑 ~/.claude/settings.json 注释或移除对应 hook

# 保持活跃观测文件小而精，大归档统一放
# ~/.claude/homunculus/archive/ 目录

参数与边界：会话启动装载的有界历史由环境变量控制——ECC_SESSION_START_MAX_CHARS 限定装载上限、ECC_SESSION_START_CONTEXT=off 可完全关闭装载（见 hooks/memory-persistence/README.md）。若观测文件持续膨胀影响启动速度，优先调整这两个变量或执行上述归档，而不是关闭整个记忆链路。

5.2 高 CPU 占用（High CPU Usage）

症状：Claude Code 进程 CPU 占用飙到 100%。

常见成因：

• 观测写入陷入死循环；
• 对超大目录做文件监听；
• hook 内存泄漏。

解决方案：

# 定位失控进程
top -o cpu | grep claude

# 临时停用 continuous learning
touch ~/.claude/homunculus/disabled

# 重启 Claude Code
# Cmd/Ctrl+Q 后重新打开

# 检查各目录观测文件体积
du -sh ~/.claude/homunculus/*/

touch ~/.claude/homunculus/disabled 是记忆系统的应急熔断开关：它不删除任何数据，只是让观测链路整体暂停，属于「先止血再定位」的标准操作。解除后删除该文件即可恢复。

---

六、常见错误信息速查（Common Error Messages）

6.1 “EACCES: permission denied”

权限不足，常见于钩子脚本或观测目录无写权限：

# 修复钩子脚本权限
find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;

# 修复观测目录权限（所有者读写，组与其他只读执行）
chmod -R u+rwX,go+rX ~/.claude/homunculus

6.2 “MODULE_NOT_FOUND”

某个 Node 模块缺失，通常是插件依赖未安装：

# marketplace 安装场景：进入缓存中的 ecc 目录补装依赖
cd ~/.claude/plugins/cache/ecc
npm install

# 手动安装场景
cd ~/.claude/plugins/ecc
npm install

6.3 “spawn UNKNOWN”

Windows 特有：shell 脚本因 CRLF 换行无法执行：

# 把 CRLF 转换为 LF
find ~/.claude/plugins -name "*.sh" -exec dos2unix {} \;

# 未装 dos2unix 时先安装
# macOS: brew install dos2unix
# Ubuntu: sudo apt install dos2unix

---

七、诊断信息收集与求助渠道

如果排查后问题依旧，请按下面的流程收集现场信息，这能让后续定位（无论自查还是提交 issue）事半功倍：

1. 打开调试日志：

   export CLAUDE_DEBUG=1
   export CLAUDE_LOG_LEVEL=debug
   

2. 收集环境快照：

   claude --version
   node --version
   python3 --version
   echo $CLAUDE_PACKAGE_MANAGER
   ls -la ~/.claude/plugins/cache/
   

3. 记录完整错误现场：把报错文本、hook 触发上下文（哪一次工具调用/生命周期事件）、改动前的配置文件一并保存。

从仓库侧可以进一步对照的权威资料包括：安装与功能总览见 README.md，命令级操作速查见 COMMANDS-QUICK-REF.md，Hook 生命周期契约见 hooks/memory-persistence/README.md，更细的架构与设计文档见 docs/architecture 与 docs/，完整的仓库规则与技能库入口见 RULES.md 与 skills/，示例参考 examples/。提交 issue 时附上第 1、2 步的调试日志、错误消息与诊断信息，是获得有效回复的关键。

---

小结：ECC 排障的核心心智模型

• 记忆类故障 → 查 ~/.claude/homunculus（registry、观测文件、archive），确认观测钩子注册与权限；
• Harness/进程类故障 → 查插件缓存、agent 目录、CLAUDE_DEBUG 与网络连通性；
• Hook 类故障 → 以 hooks/hooks.json 为基线核对注册项，手动回放事件验证 runner，留意 ECC 根目录解析路径；
• 安装/环境类故障 → 优先 ecc doctor / ecc repair / ecc list-installed，用时间戳备份代替删除，最后才考虑重装；
• 性能类故障 → 归档大观测文件、按 hooks/memory-persistence/README.md 的开关限流、必要时 touch ~/.claude/homunculus/disabled 熔断。

把这条链路记熟，大部分 ECC 问题都能在改动任何文件之前先被精确圈定。