ECC（Everything Claude Code）故障排查实战指南：从上下文溢出到 Hook 失效的完整修复手册

本指南面向使用 ECC（Everything Claude Code） 插件与跨 Harness 工作流的开发者。它系统梳理了记忆与上下文、Agent Harness、Hook 生命周期、安装配置、性能退化等六大类高频故障，并给出可复制的诊断命令与修复步骤。读完本文你将掌握：如何定位并修复观察记忆（observations）不写入、Hook 不触发、Agent 未加载、包管理器误检等典型问题，同时深入理解 ECC 运行时（hooks/hooks.json、scripts/lib/package-manager.js、scripts/lib/observer-sessions.js）在这些问题背后的实现机理。本文对应官方文档 docs/es/TROUBLESHOOTING.md（英文原版见 TROUBLESHOOTING.md），代码版本为 VERSION 记录的 2.2.1。

目录

• 1. 记忆与上下文问题
• 2. Agent Harness 故障
• 3. Hook 与工作流错误
• 4. 安装与配置问题
• 5. 性能问题
• 6. 常见错误消息速查
• 7. 获取帮助与诊断信息收集

---

1. 记忆与上下文问题

记忆（Memory）与上下文（Context）是 ECC 的「研究优先」工作流（research-first development）赖以运转的底座。上下文窗口溢出与观察记忆不持久化，是最先遇到也最影响体验的两类故障。

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

症状： 抛出 Context too long 错误，或模型回答被截断、不完整。

常见原因：

• 单次读取超大文件，超出 token 上限；
• 会话内对话历史不断累积；
• 单次会话中产生多个超大工具（tool）输出。

解决步骤（按优先级执行）：

# 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. 把大任务拆成小片段
# 不建议: "Analiza los 50 archivos"（分析全部 50 个文件）
# 建议:   "Analiza los archivos en el directorio src/components/"（先分析该目录）

深度解读： ECC 运行时里对上下文膨胀有内建的前置防线。以 hooks/hooks.json 中的 pre:edit-write:suggest-compact（对应 scripts/hooks/suggest-compact.js）为例，它在每次 Edit|Write 前以标准/严格模式运行，在逻辑间隔点主动提示手动压缩上下文（suggest manual compaction at logical intervals）。同样位于 hooks/hooks.json 的 PreCompact 钩子（pre-compact.js）则会在压缩动作真正发生前保存会话状态，避免压缩后丢失关键中间结论。也就是说，「新建会话 + 裁剪输入」是最终兜底手段，而日常更推荐让这些前置钩子替你提前发现膨胀。

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

症状： Agent 记不住之前的上下文或观察（observations），跨会话学习失效。

常见原因：

• continuous-learning 相关 Hook 被禁用；
• 观察记录文件（observations.jsonl）损坏；
• 项目检测（project detection）失败，无法把会话归属到正确的项目 ID。

排查与修复：

# 检查观察记录是否在写入
ls ~/.claude/homunculus/projects/*/observations.jsonl

# 查找当前项目的 hash id
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("Hash del proyecto no encontrado en ~/.claude/homunculus/projects.json")
PY

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

# 文件损坏时先做带时间戳的备份，再重建
mv ~/.claude/homunculus/projects/<hash-del-proyecto>/observations.jsonl \
  ~/.claude/homunculus/projects/<hash-del-proyecto>/observations.jsonl.bak.$(date +%Y%m%d-%H%M%S)

# 确认 hooks 仍被启用（观察捕获钩子包含 "observe" 字样）
grep -r "observe" ~/.claude/settings.json

实现机理（源码级）： 观察记忆不是凭空写入的，它的整条链路都落在 ECC 的 Hook 与运行时库里：

• 观察捕获钩子：在 hooks/hooks.json 的 PreToolUse 段，注册了 pre:observe:continuous-learning，其命令执行 scripts/hooks/observe-runner.js，并标注 "async": true、"timeout": 10——即每次工具调用前异步抓取「用户行为观察」，用于连续学习（continuous learning，技能目录见 docs/es/skills/continuous-learning-v2/SKILL.md）。
• 存储目录解析：观察落到哪个目录，由 scripts/lib/observer-sessions.js 的 getHomunculusDir() 决定，其解析顺序是：环境变量 CLV2_HOMUNCULUS_DIR（须为绝对路径）→ 环境变量 XDG_DATA_HOME（拼成 <XDG_DATA_HOME>/ecc-homunculus）→ 默认 ~/.local/share/ecc-homunculus。注意：与本文档沿用的旧式路径 ~/.claude/homunculus 不同，2.2.x 的实际默认目录是 ~/.local/share/ecc-homunculus，若你的机器设置了 XDG_DATA_HOME，观察文件会迁移到对应位置。用旧路径查不到文件、误判「记忆丢失」是最高频的假阳性，请优先以 projects.json 注册表实际路径为准。
• 项目归属：同文件中的 computeProjectId() 使用项目 git remote URL（去凭据、去 file://、小写归一化）哈希得到项目 ID，注册表保存在 homunculus 目录下的 projects.json。因此，在非 git 目录、或 remote URL 变化后使用同一会话，容易出现「项目检测失败」导致记忆归属漂移。

---

2. Agent Harness 故障

ECC 把 agents/ 目录下的角色 Agent（如 code-reviewer、security-reviewer、python-reviewer 等，参见 agents/）编排进不同客户端的 Harness。这类故障通常表现为「Agent 找不到」或「流程挂起」。

2.1 Agent 未找到（Agent Not Found）

症状： 报 Agent not loaded 或 Unknown agent。

常见原因：

• 插件未正确安装；
• Agent 路径配置错误；
• Marketplace 安装与手动安装混用，路径不一致。

排查：

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

# 确认 agent 存在（Marketplace 安装时）
ls ~/.claude/plugins/cache/*/agents/

# 手动安装时，自定义 agent 应放在:
ls ~/.claude/agents/   # 仅含自定义 agents

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

提示：仓库侧的 Agent 定义文件位于 agents/，安装后会被分发到对应客户端的插件目录；若你在仓库里能看到、客户端却报「Agent not loaded」，多半是安装目标目录与 Marketplace 缓存不一致，优先执行第 4 节的 ecc doctor/ecc repair 自检。

2.2 工作流挂起（Workflow 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 包含必要的 bin
echo $PATH

---

3. Hook 与工作流错误

Hook 是 ECC 与 Claude Code/Codex/OpenCode 等客户端交互的神经末梢。仓库侧统一的 Hook 注册清单是 hooks/hooks.json，其中包含 PreToolUse（Bash 分发器、doc-file-warning、suggest-compact、observe、governance-capture、config-protection、mcp-health-check、gateguard-fact-force）、PreCompact、SessionStart 等事件。Hook 一旦失效，记忆、门禁、质量护栏会整片静默。

3.1 Hook 不触发（Hooks Not Firing）

症状： pre/post 钩子没有执行。

常见原因：

• Hook 未在 settings.json 中注册；
• Hook 语法非法；
• Hook 脚本没有可执行权限。

解决：

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

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

# 手动喂入 stdin 测试 hook（以 pre-bash 为例）
bash ~/.claude/plugins/cache/*/hooks/pre-bash.sh <<< '{"command":"echo test"}'

# 重新注册（若使用插件）：在 Claude Code 配置中禁用再启用插件

实现机理： 注册清单 hooks/hooks.json 中的 Bash 前置分发器（pre:bash:dispatcher）会先通过 resolve-ecc-root 解析出插件真实根目录，再引导执行脚本目录下的分发逻辑。如果该解析在安装被中断或 CLAUDE_PLUGIN_ROOT 指向错误时失效，所有 Bash 相关钩子都会静默不触发——这正是第 4 节用 ecc doctor 检测「漂移（drift）」的典型场景。此外，历史版本存在 Node 21+ 下 require.main 为 undefined 导致插件 hook 静默空转的问题（见 CHANGELOG.md 2.0.0 的修复说明），升级到当前 2.2.x 即可规避。

3.2 Python / Node 版本不匹配

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

常见原因：

• 未安装 Python/Node；
• PATH 未配置；
• Windows 下 Python 版本（python vs python3）不对。

解决：

# 缺失时按平台安装
# 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 拦截了本身合法、但参数或 heredoc 内容里包含 dev 的命令。

常见原因：

• heredoc 内容触发了模式匹配；
• 非 dev 命令的参数中出现 dev 字样。

解决：

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

# 临时规避：把 dev server 包进 tmux，让其非阻塞运行
tmux new-session -d -s dev "npm run dev"
tmux attach -t dev

# 仍被误拦时，临时禁用该 hook：
# 编辑 ~/.claude/settings.json 移除 pre-bash hook

实现佐证： 仓库中 scripts/hooks/auto-tmux-dev.js 正是围绕这一思路设计的自动 tmux 化工具：当检测到命令是 dev server（npm run dev、pnpm dev、yarn dev、bun run dev）时，在 Unix 上自动放入命名 tmux 会话（非阻塞），Windows 上改开新 cmd 窗口；若机器没装 tmux 则回退到原始命令。它同时检查 tmux 可用性再决定是否改写，配合 tmux capture-pane -t <session> -p 可随时查看 dev server 日志而不占用会话上下文。

---

4. 安装与配置问题

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 版本（要求 Claude Code 2.0+）
claude --version

# 7. Marketplace 失败时走手动安装
# 将插件仓库克隆/拷贝到 ~/.claude/plugins/ecc（路径要与客户端识别规则一致）

实现机理： ecc 是仓库发布的一等 CLI（见 package.json 的 bin 字段指向 scripts/ecc.js），ecc.js 会把 list-installed、doctor、repair 等子命令分别路由到 scripts/list-installed.js、scripts/doctor.js、scripts/repair.js。它们基于安装生命周期库 scripts/lib/install-lifecycle.js 工作：

• ecc list-installed [--target <...>] [--json] —— 检查当前 home/项目上下文中的 ECC install-state 文件；
• ecc doctor [--target <...>] [--json] —— 对 ECC 管理的受管文件做漂移诊断（drift and missing managed files）；
• ecc repair [--target <...>] [--dry-run] [--json] —— 依据 install-state 重建 ECC 受管文件，--dry-run 可先预览将重建什么。

--target 支持多客户端目标（Claude Code、Codex、OpenCode、Cursor 等）。这解释了官方推荐顺序的内在逻辑：先 doctor 找出丢失/漂移的受管文件，再 repair 精确重建，只有两者都失败才考虑整包重装，从而避免无谓地破坏本地已有配置与用户文件。

4.2 包管理器检测失败（Package Manager Detection Fails）

症状： 用了错误的包管理器（比如该用 pnpm 却用了 npm）。

常见原因：

• 项目缺少 lock 文件；
• CLAUDE_PACKAGE_MANAGER 未设置；
• 多个 lock 文件并存，干扰检测。

解决（三种方式由全局到项目）：

# 方式 A：全局指定首选包管理器
export CLAUDE_PACKAGE_MANAGER=pnpm
# 并写入 ~/.bashrc 或 ~/.zshrc 使其持久生效

# 方式 B：项目级配置
echo '{"packageManager": "pnpm"}' > .claude/package-manager.json

# 方式 C：使用 package.json 的 packageManager 字段
npm pkg set packageManager="pnpm@8.15.0"

# 警告：删除 lock 文件会改变已装依赖版本。
# 先提交或备份 lock 文件，再执行全新安装并重跑 CI。
# 只有在刻意切换包管理器时才这样做：
rm package-lock.json   # 仅当你切换到 pnpm/yarn/bun 时

实现机理（源码级）： scripts/lib/package-manager.js 是 ECC 包管理器选择的核心实现，它对 npm/pnpm/yarn/bun 各定义了 lockFile 与对应的 install/run/exec/test/build/dev 命令（PACKAGE_MANAGERS 表）：

包管理器	lock 文件（含别名）	典型安装命令	exec 命令
npm	package-lock.json	npm install	npx
pnpm	pnpm-lock.yaml	pnpm install	pnpm dlx
yarn	yarn.lock	yarn	yarn dlx
bun	bun.lock（兼容旧 bun.lockb）	bun install	bunx

getPackageManager() 的完整检测优先级为（对应注释第 1–6 步）：

1. 环境变量 CLAUDE_PACKAGE_MANAGER；
2. 项目内 .claude/package-manager.json；
3. package.json 的 packageManager 字段（格式 pnpm@8.6.0 取 @ 前部分）；
4. lock 文件检测，其顺序为 ['pnpm', 'bun', 'yarn', 'npm']；
5. 全局用户偏好 ~/.claude/package-manager.json；
6. 兜底默认 npm（不再派生子进程探测）。

其中第 6 步的设计有明确历史教训：早期版本在无匹配时会调用 getAvailablePackageManagers()（内部对每个包管理器执行 where.exe/which 派生进程），而 session-start 钩子在 Bun 初始化期间运行，派生进程会超过 Windows 的 spawn 上限导致整个插件冻结（源码注释中的 #162）。启示：若你看到「会话启动即冻结」且伴随多包管理器环境，先检查是否有残留旧版本逻辑或 CLAUDE_PACKAGE_MANAGER 是否指向了未安装的包管理器。对应交互式配置脚本见 scripts/setup-package-manager.js，配置格式可对照 schemas/package-manager.schema.json。

---

5. 性能问题

5.1 响应缓慢（Slow Response Times）

症状： Agent 响应超过 30 秒。

常见原因：

• 观察文件体积过大；
• 激活的 Hook 过多；
• 到 API 的网络延迟。

解决：

# 把大观察文件归档（gzip）而不是直接删除
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 {} +

# 临时禁用未使用的 hooks
# 编辑 ~/.claude/settings.json

# 保持活跃观察文件精简；大文件归档应置于 ~/.claude/homunculus/archive/

目录说明：归档路径与上文 1.2 一致——若你的实际 homunculus 目录在 ~/.local/share/ecc-homunculus（默认）或 $XDG_DATA_HOME/ecc-homunculus，请把脚本中的 ~/.claude/homunculus 替换为实际目录。

5.2 高 CPU 占用（High CPU Usage）

症状： Claude Code 进程吃掉 100% CPU。

常见原因：

• 观察循环死循环；
• 在超大目录上做文件监听；
• Hook 内存泄漏。

解决：

# 查看失控进程
top -o cpu | grep claude

# 临时禁用连续学习（创建 disabled 标记文件）
touch ~/.claude/homunculus/disabled

# 重启 Claude Code（Cmd/Ctrl+Q 后重开）

# 查看观察文件大小
du -sh ~/.claude/homunculus/*/

实现佐证： observe 类钩子在 hooks/hooks.json 中被标记为 async 且带 10 秒超时，正是为了把「异步抓取观察」与「主会话性能」解耦；一旦发现 CPU 长期打满，优先按上文检查是否有旧版观察循环、异常大的观察目录或第三方 hook 泄漏，再考虑用 disabled 标记暂时关停连续学习（相关技能与开关说明见 docs/es/skills/continuous-learning/SKILL.md）。

---

6. 常见错误消息速查

6.1 EACCES: permission denied

# 修正 hook 权限
find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;

# 修正观察目录权限
chmod -R u+rwX,go+rX ~/.claude/homunculus

6.2 MODULE_NOT_FOUND

# 安装插件依赖（Marketplace 缓存安装）
cd ~/.claude/plugins/cache/ecc
npm install

# 或手动安装路径
cd ~/.claude/plugins/ecc
npm install

6.3 spawn UNKNOWN

# Windows 专属：确保脚本使用正确换行符（CRLF 转 LF）
find ~/.claude/plugins -name "*.sh" -exec dos2unix {} \;

# 未装 dos2unix 时按平台安装
# macOS:  brew install dos2unix
# Ubuntu: sudo apt install dos2unix

从实现看，spawn UNKNOWN 也常与「运行环境无法正确 spawn 子进程」有关（Windows + Bun 场景下尤其明显），换行符与旧版派生进程逻辑是两个主要嫌疑，升级到当前 2.2.x 版本后再做换行处理通常可一并解决。

---

7. 获取帮助与诊断信息收集

若上述方案仍未解决，请按以下顺序收集信息后再寻求帮助或上报：

第一步：开启调试日志

export CLAUDE_DEBUG=1
export CLAUDE_LOG_LEVEL=debug

第二步：收集诊断快照

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

第三步：附带最小复现信息上报 上报时应包含：调试日志、错误消息、上述诊断快照，以及你执行过的 ecc doctor 输出——它能直接反映安装状态与受管文件漂移情况，帮助维护者快速定位是安装问题还是运行时问题。

---

相关文档

• README.md —— 项目安装与功能总览（另有 docs/es/README.md 西班牙语版）
• TROUBLESHOOTING.md —— 本文英文原版（包含 OpenCode/Termux/Android 启动失败的补充章节）
• CHANGELOG.md —— 版本修复记录（Hook 空转、Windows 可靠性、观察存储等历史问题的修复均可在此核对，docs/es/CHANGELOG.md 为西语版）
• hooks/hooks.json —— 统一 Hook 注册清单（本指南多数 Hook 故障的对照基准）
• agents/ —— 角色 Agent 定义目录
• docs/ —— 详细文档
• examples/ —— 使用示例