故障排除指南¶

Everything Claude Code (ECC) 插件的常见问题和解决方案。

目录¶

内存与上下文问题
智能体框架故障
钩子与工作流错误
安装与设置
性能问题
常见错误消息
获取帮助

内存与上下文问题¶

上下文窗口溢出¶

症状： “Context too long” 错误或响应不完整

原因： - 上传超过令牌限制的大文件 - 累积的对话历史 - 单个会话内多个大型工具输出

解决方案：

# 1. 会話履歴をクリアして新しく開始
# Claude Code: 「New Chat」または Cmd/Ctrl+Shift+N

# 2. 分析前にファイルサイズを縮小
head -n 100 large-file.log > sample.log

# 3. 大きな出力にはストリーミングを使用
head -n 50 large-file.txt

# 4. タスクを小さなチャンクに分割
# 代わりに: 「50ファイルすべてを分析して」
# 使用: 「src/components/ ディレクトリのファイルを分析して」

内存持久化失败¶

症状： 智能体无法记住之前的上下文或观察

原因： - 持续学习钩子被禁用 - 观察文件损坏 - 项目检测失败

解决方案：

# 観測が記録されているか確認
ls ~/.claude/homunculus/projects/*/observations.jsonl

# 現在のプロジェクトのハッシュ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("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)

# フックが有効か確認
grep -r "observe" ~/.claude/settings.json

智能体框架故障¶

找不到智能体¶

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

原因： - 插件未正确安装 - 智能体路径配置错误 - Marketplace 与手动安装不一致

解决方案：

# プラグインのインストールを確認
ls ~/.claude/plugins/cache/

# エージェントの存在を確認（Marketplaceインストール）
ls ~/.claude/plugins/cache/*/agents/

# 手動インストールの場合、エージェントは以下に配置:
ls ~/.claude/agents/  # カスタムエージェントのみ

# プラグインをリロード
# Claude Code → Settings → Extensions → Reload

工作流执行挂起¶

症状： 智能体启动但无法完成

原因： - 智能体逻辑中存在无限循环 - 被用户输入阻塞 - 等待 API 的网络超时

解决方案：

# 1. スタックしたプロセスを確認
ps aux | grep claude

# 2. デバッグモードを有効化
export CLAUDE_DEBUG=1

# 3. より短いタイムアウトを設定
export CLAUDE_TIMEOUT=30

# 4. ネットワーク接続を確認
curl -I https://api.anthropic.com

工具使用错误¶

症状： “Tool execution failed” 或权限拒绝

原因： - 缺少所需依赖项（npm、python 等） - 文件权限不足 - 找不到路径

解决方案：

# 必要なツールがインストールされているか確認
which node python3 npm git

# フックスクリプトのパーミッションを修正
chmod +x ~/.claude/plugins/cache/*/hooks/*.sh
chmod +x ~/.claude/plugins/cache/*/skills/*/hooks/*.sh

# PATHに必要なバイナリが含まれているか確認
echo $PATH

钩子与工作流错误¶

钩子未触发¶

症状： Pre/Post 钩子未执行

原因： - 钩子未在 settings.json 中注册 - 无效的钩子语法 - 钩子脚本不可执行

解决方案：

# フックが登録されているか確認
grep -A 10 '"hooks"' ~/.claude/settings.json

# フックファイルが存在し実行可能か確認
ls -la ~/.claude/plugins/cache/*/hooks/

# フックを手動でテスト
bash ~/.claude/plugins/cache/*/hooks/pre-bash.sh <<< '{"command":"echo test"}'

# フックを再登録（プラグイン使用時）
# Claude Code設定でプラグインを無効化してから再度有効化

Python/Node 版本不匹配¶

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

原因： - 未安装 Python/Node - 未设置 PATH - 错误的 Python 版本（Windows）

解决方案：

# 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: python3ではなくpythonが動作することを確認
python --version

开发服务器拦截器误报¶

症状： 钩子拦截包含 “dev” 的合法命令

原因： - Here-document 内容触发模式匹配 - 参数中包含 “dev” 的非开发命令

解决方案：

# v1.8.0+で修正済み（PR #371）
# プラグインを最新バージョンにアップグレード

# 回避策: 開発サーバーをtmuxでラップ
tmux new-session -d -s dev "npm run dev"
tmux attach -t dev

# 必要に応じてフックを一時的に無効化
# ~/.claude/settings.jsonを編集してpre-bashフックを削除

安装与设置¶

插件无法加载¶

症状： 安装后无法使用插件功能

原因： - Marketplace 缓存未更新 - Claude Code 版本不兼容 - 插件文件损坏 - 本地 Claude 配置被清除或重置

解决方案：

# まずECCがこのマシンについて認識している情報を確認
ecc list-installed
ecc doctor
ecc repair

# doctor/repairで不足ファイルを復元できない場合のみ再インストール

# 変更前にプラグインキャッシュを確認
ls -la ~/.claude/plugins/cache/

# プラグインキャッシュを削除せずバックアップ
mv ~/.claude/plugins/cache ~/.claude/plugins/cache.backup.$(date +%Y%m%d-%H%M%S)
mkdir -p ~/.claude/plugins/cache

# Marketplaceから再インストール
# Claude Code → Extensions → Everything Claude Code → Uninstall
# その後Marketplaceから再インストール

# 問題がMarketplace/アカウントアクセスの場合、ECC Toolsのbilling/アカウントリカバリーを別途使用
# 再インストールをアカウントリカバリーの代替として使用しない

# Claude Codeバージョンを確認
claude --version
# Claude Code 2.0+が必要

# 手動インストール（Marketplaceが失敗する場合）
git clone https://github.com/affaan-m/everything-claude-code.git
cp -r everything-claude-code ~/.claude/plugins/ecc

包管理器检测失败¶

症状： 使用了错误的包管理器（例如使用 npm 而不是 pnpm）

原因： - 不存在锁文件 - 未设置 CLAUDE_PACKAGE_MANAGER - 多个锁文件导致检测混乱

解决方案：

# 優先パッケージマネージャーをグローバルに設定
export CLAUDE_PACKAGE_MANAGER=pnpm
# ~/.bashrcまたは~/.zshrcに追加

# またはプロジェクトごとに設定
echo '{"packageManager": "pnpm"}' > .claude/package-manager.json

# またはpackage.jsonフィールドを使用
npm pkg set packageManager="pnpm@8.15.0"

# 警告: ロックファイルの削除はインストールされた依存関係のバージョンを変更する可能性がある
# まずロックファイルをコミットまたはバックアップし、フレッシュインストールを実行してCIを再実行
# パッケージマネージャーを意図的に切り替える場合のみ実行
rm package-lock.json  # pnpm/yarn/bunを使用する場合

性能问题¶

响应延迟¶

症状： 智能体响应超过 30 秒

原因： - 大型观察文件 - 活动钩子过多 - 到 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を編集

# アクティブな観測ファイルを小さく保つ
# 大きなアーカイブは ~/.claude/homunculus/archive/ に配置

高 CPU 使用率¶

症状： Claude Code 占用 100% CPU

原因： - 无限观测循环 - 监视大型目录 - 钩子中的内存泄漏

解决方案：

# 暴走プロセスを確認
top -o cpu | grep claude

# 継続学習を一時的に無効化
touch ~/.claude/homunculus/disabled

# Claude Codeを再起動
# Cmd/Ctrl+Q で終了後、再起動

# 観測ファイルのサイズを確認
du -sh ~/.claude/homunculus/*/

常见错误消息¶

"EACCES: permission denied"¶

# フックのパーミッションを修正
find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;

# 観測ディレクトリのパーミッションを修正
chmod -R u+rwX,go+rX ~/.claude/homunculus

"MODULE_NOT_FOUND"¶

# プラグインの依存関係をインストール
cd ~/.claude/plugins/cache/ecc
npm install

# または手動インストールの場合
cd ~/.claude/plugins/ecc
npm install

"spawn UNKNOWN"¶

# Windows固有: スクリプトが正しい改行コードを使用していることを確認
# CRLFをLFに変換
find ~/.claude/plugins -name "*.sh" -exec dos2unix {} \;

# またはdos2unixをインストール
# macOS: brew install dos2unix
# Ubuntu: sudo apt install dos2unix

获取帮助¶

如果问题仍未解决：

查看 GitHub Issues：github.com/affaan-m/everything-claude-code/issues

启用调试日志：

export CLAUDE_DEBUG=1
export CLAUDE_LOG_LEVEL=debug

收集诊断信息：

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

创建 Issue：请包含调试日志、错误消息和诊断信息

README.md - 安装与功能
CONTRIBUTING.md - 开发指南
docs/ - 详细文档
examples/ - 使用示例

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC

故障排除指南¶

目录¶

内存与上下文问题¶

上下文窗口溢出¶

内存持久化失败¶

智能体框架故障¶

找不到智能体¶

工作流执行挂起¶

工具使用错误¶

钩子与工作流错误¶

钩子未触发¶

Python/Node 版本不匹配¶

开发服务器拦截器误报¶

安装与设置¶

插件无法加载¶

包管理器检测失败¶

性能问题¶

响应延迟¶

高 CPU 使用率¶

常见错误消息¶

"EACCES: permission denied"¶

"MODULE_NOT_FOUND"¶

"spawn UNKNOWN"¶

获取帮助¶

相关文档¶