故障排查与常见问题

如果遇到问题，请从这里开始。大多数问题可以通过运行以下命令解决：

bash

planu doctor

此命令会检查您的安装、配置文件和 AI 工具连接，然后告诉您需要修复的确切内容。

安装问题

安装后 MCP 未被检测到

您的 AI 工具需要完全重启 — 不只是关闭窗口，而是整个进程。

Claude Code：

bash

# 完全退出 Claude Code，然后重新打开
# 验证 Planu 是否出现在列表中：
claude mcp list

Cursor / Windsurf / Zed： 从任务栏或 Dock 关闭应用程序（不只是窗口），然后重新打开。

仍未检测到？

运行 planu doctor — 它将显示写入了哪些配置文件以及 AI 工具是否能看到它们。

配置文件路径错误

Planu 根据您的操作系统和范围（用户或项目）将配置写入不同位置。

范围	Claude Code	Cursor	Windsurf
用户（macOS/Linux）	`~/.claude/claude.json`	`~/.cursor/mcp.json`	`~/.codeium/windsurf/mcp_config.json`
用户（Windows/WSL）	`%APPDATA%\Claude\claude.json`	`%APPDATA%\Cursor\mcp.json`	`%APPDATA%\Windsurf\mcp_config.json`
项目	`.claude/claude.json`	`.cursor/mcp.json`	`.windsurf/mcp_config.json`

如何检查哪个配置文件处于活动状态

bash

planu doctor

输出包含一个 Config files 部分，显示写入的确切路径以及 AI 工具是否能读取它们。

对于 Claude Code：

bash

claude mcp list
# 预期输出包含：
# planu — planu serve

运行 npx 时出现权限错误

在 macOS/Linux 上修复 npm 权限

当 npm 的全局目录由 root 拥有时会发生此问题。不使用 sudo 进行修复：

bash

# 选项 1：使用用户拥有的前缀
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc  # 或 ~/.bashrc
source ~/.zshrc

# 选项 2：使用 nvm（推荐用于开发者）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 然后通过 nvm 重新安装 Node.js

修复后验证：

bash

planu install --global

切勿对 npm 使用 sudo

运行 sudo npm install -g 会掩盖权限问题，并创建由 root 拥有的文件，这会在之后导致更多错误。请修复底层权限问题。

npm install -g 后提示 "command not found: planu"

npm 的全局二进制目录不在您的 PATH 中。

bash

# 找出 npm 在哪里安装全局二进制文件：
npm config get prefix
# 典型输出：/usr/local  →  二进制文件在 /usr/local/bin

# 如果缺少，添加到 PATH（macOS/Linux）：
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证：
planu --version

优先使用 npx 而非全局安装

您始终可以使用 planu <命令> 而无需全局安装。安装程序在内部使用 npx，因此全局安装是可选的。

AI 工具连接性

Claude Code 未显示 Planu 工具

运行 planu doctor 验证配置是否正确写入
运行 claude mcp list — Planu 必须出现在输出中
开始新对话并输入：list my planu tools
如果 Claude Code 请求权限，请批准（或配置自动批准 — 请参阅快速入门）

bash

claude mcp list
# 预期输出：
# planu    planu serve    [active]

MCP 工具是按对话的

工具在对话开始时加载。如果您在对话打开时安装了 Planu，请开始新对话。

安装后 Cursor / Windsurf 无法识别 MCP

手动验证配置文件

Cursor — 检查 ~/.cursor/mcp.json：

json

{
  "mcpServers": {
    "planu": {
      "command": "planu",
      "args": ["serve"]
    }
  }
}

Windsurf — 检查 ~/.codeium/windsurf/mcp_config.json（相同结构）。

如果文件正确但工具仍未出现：

完全关闭应用程序
重新打开
等待约 10 秒让 MCP 服务器启动
打开新聊天并输入 Planu 命令

Claude 中出现"Tool not found"错误

这意味着 Claude 在当前对话中未连接到 Planu MCP 服务器。

bash

# 重新验证安装：
planu doctor

# 如有需要重新添加：
claude mcp add planu -- npx -y @planu/cli@latest

然后开始新对话 — MCP 连接在每次对话开始时建立。

如何验证安装

bash

planu doctor

预期输出：

Planu Doctor v0.89.0
====================
Node.js:     24.x     OK
npx:         10.x     OK
Config:
  Claude Code  ~/.claude/claude.json     found
  Cursor       ~/.cursor/mcp.json        found
License:     Pro — user@email.com
Status:      All checks passed

Spec 工作流问题

即使实现后 `validate` 仍然失败

validate 工具检查您的代码是否符合 spec 的验收标准。失败的几个常见原因：

标准太模糊 — 在实现前运行 check_readiness 来改进它们
项目路径错误 — 确保传入正确的源代码目录
Spec 和代码真正不匹配 — 检查哪些标准失败并实现缺失的部分

Prompt: "Validate spec SPEC-003 against the code at /path/to/src"

当 validate 持续失败时该怎么做

Prompt: "Show me which criteria are failing for spec SPEC-003"

这会列出每个标准及其覆盖状态。专注于未覆盖的标准。如果某个标准已满足但仍然失败，可能是以验证器无法检测的方式描述的 — 使用 reconcile_spec 更新措辞以匹配实际实现。

错误地检测到漂移（误报）

detect_drift 将您的当前代码与 spec 描述的内容进行比较。误报发生在以下情况：

Spec 写有非常具体的实现细节，这些细节已更改（但行为相同）
您重构了代码但没有更新 spec

如果漂移是故意的（spec 需要更新以匹配实际实现）：

Prompt: "Reconcile spec SPEC-003 with the implementation changes in project [id]"

reconcile_spec 会引导您逐个检查每处更改，并在更新 spec 之前请求逐项批准。

漂移并不总是坏事

漂移意味着"计划和代码不一致"。有时代码是正确的，计划已过时 — 这时需要协调。有时代码是错误的 — 这时需要修复代码。

工具找不到 Spec

工具通过 ID（例如 SPEC-003）在项目中识别 spec。如果找不到 spec：

bash

# 检查当前目录的项目 ID：
planu status

# 列出项目中的所有 spec：
# Prompt: "List all specs in project [id]"

常见原因：

使用了错误的项目 ID（Planu 使用项目路径的哈希值）
Spec 是在与当前目录不同的目录中创建的

`create_spec` 在大型项目中超时

在非常大的项目（数百万个文件）中，初始扫描可能比预期花费更长时间。

限制扫描范围：

Prompt: "Create a spec for [feature] in project [id], scan only the src/ directory"

您也可以预先运行一次扫描来缓存结果：

Prompt: "Scan project [id] at path /path/to/project, limit to src/"

同一项目的后续 create_spec 调用将使用缓存的扫描。

性能

首次响应缓慢（冷启动）

新对话中的首次响应较慢，因为：

npx 下载最新版本的 @planu/cli（几秒钟）
MCP 服务器初始化并加载项目数据

这是每次对话的一次性成本。后续工具调用很快。

减少冷启动时间

使用 --prefer-online（已包含在默认配置中）在本地缓存包。首次运行后，npx 重用缓存版本并只检查更新。

大型项目扫描耗时过长

Prompt: "Scan project [id] at /path/to/project, limit scan to src/ and tests/"

您也可以通过列出要排除的目录：

Prompt: "Scan project [id], exclude node_modules, dist, .git, and vendor directories"

如何限制扫描范围

创建 spec 或扫描时传入明确的路径限制：

Prompt: "Create a spec for payment processing, scanning only src/payments/ in project [id]"

Planu 会遵守这些边界，不会分析指定路径之外的文件。

获取帮助

如果以上步骤均未解决您的问题，请先收集诊断信息：

bash

planu doctor

复制完整输出并将其包含在 bug 报告中。

Bug 报告应包含的内容

planu doctor 的完整输出
触发问题的命令或提示词
确切的错误消息或意外行为
您的操作系统和 Node.js 版本：node --version
您的 AI 工具及版本（例如 Claude Code 1.x、Cursor 0.4x）

报告问题

请让已安装的 Planu Agent 使用 submit_feedback，附上 planu doctor 输出以及预期和实际结果。如果 Planu 无法启动，请使用公开的 Discord 支持频道。

社区支持

在提交新 Issue 前请先搜索现有 Issues — 您的问题可能已有解决方案或临时解决办法。

故障排查与常见问题 ​

安装问题 ​

安装后 MCP 未被检测到 ​

配置文件路径错误 ​

运行 npx 时出现权限错误 ​

npm install -g 后提示 "command not found: planu" ​

AI 工具连接性 ​

Claude Code 未显示 Planu 工具 ​

安装后 Cursor / Windsurf 无法识别 MCP ​

Claude 中出现"Tool not found"错误 ​

如何验证安装 ​

Spec 工作流问题 ​

即使实现后 validate 仍然失败 ​

错误地检测到漂移（误报） ​

工具找不到 Spec ​

create_spec 在大型项目中超时 ​

性能 ​

首次响应缓慢（冷启动） ​

大型项目扫描耗时过长 ​

如何限制扫描范围 ​

获取帮助 ​

Bug 报告应包含的内容 ​

报告问题 ​

故障排查与常见问题

安装问题

安装后 MCP 未被检测到

配置文件路径错误

运行 npx 时出现权限错误

npm install -g 后提示 "command not found: planu"

AI 工具连接性

Claude Code 未显示 Planu 工具

安装后 Cursor / Windsurf 无法识别 MCP

Claude 中出现"Tool not found"错误

如何验证安装

Spec 工作流问题

即使实现后 `validate` 仍然失败

错误地检测到漂移（误报）

工具找不到 Spec

`create_spec` 在大型项目中超时

性能

首次响应缓慢（冷启动）

大型项目扫描耗时过长

如何限制扫描范围

获取帮助

Bug 报告应包含的内容

报告问题