Troubleshooting.zh

故障排除

VCP

Skill 找不到配置

在项目根目录运行：

/vcp-init

Codex 使用 $vcp-init。

Hook 看起来没有运行

确认已安装 Bun，并启用 debug 日志：

/vcp-config global set debug true

然后查看 .vcp/vcp.log。

Security gate 误报

优先修复代码。如果该模式确实不适用，将 CWE 加入项目 ignore：

{ "ignore": ["CWE-798"] }

Codex

Skills 缺失

确认仓库安装在：

~/.codex/plugins/vcp

在该目录运行 bun install 并重启 Codex。

MCP server 缺失

运行 /mcp。如果缺少 server，按 docs/codex-install.md 在 ~/.codex/config.toml 加入绝对路径的 mcp_servers。

MCP resources 不可见

使用配对工具：

• VCP：get_prompt、resolve_config
• Dev Buddy：get_run_state、get_stage_definition、list_presets
• MCP Doc：get_prompt、get_host_instructions

Dev Buddy

配置验证失败

bun plugins/dev-buddy/scripts/pipeline-config.ts validate --cwd /path/to/project

常见原因：

• ~/.vcp/ai-presets.json 中缺少 preset
• 未知 system_prompt
• active pipeline stage 没有 executor
• 多 executor stage 最后一个 executor 设置了 parallel: true

Legacy Ralph run 已过期

Legacy stage-skill 状态在 .vcp/plan/ 下。归档或删除匹配的 plan slug：

.vcp/plan/ralph-{slug}.md
.vcp/plan/ralph/{slug}/
.vcp/plan/.state/ralph-{slug}/

不要删除无关 active run。

MCP Ralph run 已过期

MCP 骨架状态在 .vcp/ralph/<run-id>/ 下。删除前先用 ralph_list 和 get_run_state 确认 run。

Build unit 卡住

查看：

.vcp/plan/.state/ralph-{slug}/units/unit-N.json

检查重复机械上下文、review feedback 和 attempt count。当相同失败反复出现时，可能需要人工介入。

MCP Doc

找不到生成的 server

重新运行 /mcp-doc-init 或 $mcp-doc-init。它应创建 .mcp/manifest.yml、.mcp/actions/ 和 .mcp.json。