不熟悉命令行？ 把 INSTALL-FOR-AI.md 整个发给你的 AI 编程助手，附一句「请严格按照这份文档帮我安装」——AI 会替你完成安装、配置和逐项验证，全程走国内 npm 镜像，不需要科学上网。
在配置好的项目里，让 ZCode 中的 Agent 稳定优先使用 codegraph MCP 工具探索代码（而不是退回 grep/Glob），并且索引自动保持最新。由四部分组成：
| 脚本 | 挂载事件 | 作用 |
|---|---|---|
codegraph-sync.js |
SessionStart(matcher startup|resume)、PostToolUse(matcher Write|Edit|ApplyPatch) |
会话启动时、每次改文件后同步 .codegraph/ 索引（codegraph sync -q），Agent 无需手动 sync |
codegraph-context.js |
SessionStart（无 matcher，compact/clear 后也会触发） |
向会话注入 codegraph 优先策略（含豁免规则与“budget 文案只是建议”的反制条款） |
codegraph-gate.js |
PreToolUse(matcher Grep|Bash)、PostToolUse(matcher codegraph) |
决策点闸门：每回合首次 Grep/Bash-grep 被拦一次，拦截消息即策略注入（免疫上下文压缩）；重发同一命令放行；codegraph 调用真实报错则 10 分钟自动放行 |
codegraph-nudge.js |
UserPromptSubmit |
(1) 每条用户消息删除闸门回合状态，使其按“回合”生效；(2) 提问命中“探索/定位/修改代码”类中英文关键词时注入一行 codegraph 提醒（不节流——注入只有一行，长会话持续在场比省 token 重要）；闲聊不注入 |
注入文案与代码注释均为英文（受众是模型和贡献者，任何语言环境通用）。
全套钩子与安装器是纯 Node.js 单实现（v0.3.0 起取代早期的 bash/Python 双实现）：macOS/Linux 注册为 type: "command" shell 行，Windows 原生注册为 type: "process"（node.exe + 脚本路径，参数向量直传、不经 shell）。选 Node 的原因：npm 既是本包的分发渠道（npx），又是 codegraph CLI 的安装渠道，所以 Node 是每个用户必然已经装好的运行时——kit 不再引入任何额外运行时依赖（不再需要 python3，也不需要 bash/WSL）。
每个钩子都有自保护：项目根没有 .codegraph/ 目录、找不到 codegraph 可执行文件、stdin 数据畸形、或设置了环境变量 ZCODE_CODEGRAPH_DISABLE=1 时，一律静默退出 0，绝不阻塞会话。因此全局注册是安全的，非 codegraph 项目零干扰。
# 1. ZCode 已安装（存在 ~/.zcode/cli/ 目录）
# 2. Node.js ≥ 16 + npm，全局安装 codegraph CLI（本包不含 CLI 本体，约 280MB；测试版本 1.6.0）
npm install -g @colbymchenry/codegraph
codegraph --version # 应输出版本号Node 本身无需额外安装：能用 npx 跑本包就说明它已就位。
npx zcode-codegraph-kit # 一行安装；预览加 --dry-run升级同样一行（安装器幂等，重复执行安全）：npx zcode-codegraph-kit@latest
源码方式（等价，macOS/Linux/Windows 原生同一命令）：
git clone https://github.com/simpleKalvin/zcode-codegraph-kit
cd zcode-codegraph-kit
node install.js # 一键安装；先预览用 node install.js --dry-run它会：复制 5 个 JS 文件（4 个钩子 + codegraph-common.js 共享模块）到 ~/.zcode/hooks/ → 备份 ~/.zcode/cli/config.json → 结构化幂等合并（顺带清掉 ≤0.2.x 旧版留下的 bash/Python 注册与旧文件）→ 校验 JSON → 检查 codegraph CLI。前置条件不满足（无 ZCode）会报错退出，不做任何修改。
注册方式（均为安装时解析出的绝对路径——配置文件钩子不展开模板变量，Windows 上裸命令名会 spawn ENOENT）：
- Windows 原生：process 型钩子，
command= node.exe 绝对路径、args= 脚本绝对路径，超时字段timeoutMs单位是毫秒；不需要 Git Bash，也不需要 WSL； - macOS/Linux：command 型 shell 行（
node绝对路径 + 脚本绝对路径），超时字段timeout单位是秒； - MCP server 注册为
codegraph的绝对路径（找不到时退回裸命令名），codegraph serve --mcp（stdio，本地）。
合并脚本做三件事（结构化合并，绝不整体覆盖，无关字段一律保留）：
- 设
hooks.enabled = true（配置文件钩子默认不启用，这是最常见的失效原因）； - 把内置
HOOK_EVENTS表（merge-config.js，唯一事实来源）的事件条目按事件合并进hooks.events.*，已注册的（按command+ 参数向量判重）跳过； - 把 codegraph 对象写入
mcp.servers.codegraph。
然后在每个需要 codegraph 的项目里初始化一次索引：
cd /path/to/project
codegraph init # 生成 .codegraph/ 目录并建立初始索引
codegraph status # 查看索引统计.codegraph/ 是机器本地数据，不应提交进 git（init 会自带 .codegraph/.gitignore）。钩子与 MCP 配置对新会话生效。
自动化（使用假 HOME、假 codegraph CLI 和假项目，不碰真实环境；macOS/Linux/Windows 通用）：
node tests/smoke.js # 或 npm test覆盖完整回路：安装 → 重复安装幂等 → 每个钩子的行为（含闸门的拦截/放行/报错豁免）→ 旧版升级清理 → 紧急禁用 → 卸载后配置精确还原（含外来条目保留）→ npm 打包回装验证。
手工验证（在已 codegraph init 的项目里，或设 ZCODE_PROJECT_DIR 指向该项目）：
# 1. SessionStart 引导钩子: 输出合法 JSON, additionalContext 含 codegraph_explore
node ~/.zcode/hooks/codegraph-context.js <<< '{}' | python3 -m json.tool
# (Windows PowerShell: '{}' | node "$env:USERPROFILE\.zcode\hooks\codegraph-context.js")
# 2. UserPromptSubmit 提醒钩子: 命中即输出 JSON(不节流), 闲聊不注入
echo '{"prompt":"帮我找一下登录逻辑在哪里","session_id":"verify-1"}' \
| node ~/.zcode/hooks/codegraph-nudge.js # 应输出 JSON
echo '{"prompt":"谢谢","session_id":"verify-1"}' \
| node ~/.zcode/hooks/codegraph-nudge.js # 应无输出
# 2b. 闸门钩子: 同 session 首次 Grep 拦(exit 2 + stderr 策略), 重发放行
echo '{"hook_event_name":"PreToolUse","tool_name":"Grep","session_id":"verify-1"}' \
| node ~/.zcode/hooks/codegraph-gate.js; echo "exit=$?" # 期望 exit=2
echo '{"hook_event_name":"PreToolUse","tool_name":"Grep","session_id":"verify-1"}' \
| node ~/.zcode/hooks/codegraph-gate.js; echo "exit=$?" # 期望 exit=0
rm -rf "${TMPDIR:-/tmp}/zcode-codegraph-gate"
# 3. 同步钩子: 改文件后静默执行, 手工跑一次确认 exit 0
echo '{"tool_input":{"file_path":"'"$PWD"'/README.md"}}' \
| node ~/.zcode/hooks/codegraph-sync.js; echo "exit=$?"
# 4. 配置合法性
python3 -m json.tool ~/.zcode/cli/config.json > /dev/null && echo valid最后开一个新 ZCode 会话：会话开头应出现 [codegraph] This project has a codegraph index… 引导；向 Agent 提一个代码探索类问题（如“XX 逻辑在哪里”），Agent 应优先调用 mcp__codegraph__* 工具（首选 codegraph_explore）。
npx zcode-codegraph-kit uninstall # 或源码目录里 node install.js --remove
export ZCODE_CODEGRAPH_DISABLE=1 # 临时禁用（取消设置即恢复），所有钩子立即变 no-op卸载不会动 hooks.enabled（其他钩子可能需要）和各项目的 .codegraph/ 索引；后者在项目内执行 codegraph uninit（或直接删 .codegraph/ 目录）即可移除。
- codegraph 1.6.0 实际注册的工具包括
codegraph_explore / codegraph_search / codegraph_node / codegraph_files / codegraph_callers / codegraph_callees / codegraph_impact / codegraph_status，但不同会话实际暴露给模型的工具子集可能不同（上游默认工具面就是codegraph_explore单工具）。因此引导文案统一写"首选codegraph_explore，其余以会话中实际可见的mcp__codegraph__*为准"，不要硬编码完整工具列表。 - 钩子超时配置：macOS/Linux 是 command 型钩子，
timeout单位秒；Windows 是 process 型钩子，timeoutMs单位毫秒。 - 注册命令均为绝对路径（node、钩子脚本、codegraph CLI）——移动 Node 安装位置或 npm 全局目录后需重跑
node install.js刷新；MCP 若在 Settings 里显示 failed，先确认 codegraph 命令路径仍存在。 - 原机器另有一个与 codegraph 无关的 SessionStart 钩子
context-mode-cache-heal.mjs（缓存修复用途），不在本包内，勿混淆。 - MCP server 以
codegraph serve --mcp常驻（stdio，本地），daemon 数据在项目.codegraph/下（codegraph.db、daemon.sock 等）。 - 若索引损坏或行为异常：
codegraph index全量重建。 - 从 ≤0.2.x（bash/Python 双实现版本）升级：直接重跑安装器即可，它会移除旧注册并删除旧钩子文件，无需先卸载。
MIT。codegraph 本体是 colbymchenry/codegraph 的独立项目，本包只做配置集成，不包含也不修改它。