ARTICLE · 1312906

rea入门:AI 助手与 MCP 配置

发布时间：2026-11-05 10:54:25 最近访问：2026-11-05 10:54:26

rea入门:AI 助手与 MCP 配置

字数 3234，阅读大约需 17 分钟

本章帮助零基础用户把 REA 连接到支持 MCP 的 AI 客户端。
完成后，你应能：

1. 理解 MCP 注册、server、skill 和 prompt 的区别；
2. 用 setup --dry-run 先审阅变化；
3. 为单个客户端配置并验证；
4. 处理 Windows GUI 的 PATH 与配置位置问题；
5. 正确理解 guided prompts，不把它们当自动执行；
6. 区分文件配置健康与真实会话可用。

版本基线是仓库 6.8.0 与当前 main。
main 能力不代表 npm 上所有版本均已发布。
先用 rea --version --json 确认实际 server 版本。
FreeBuff setup 需要 6.8.0 或更高版本，但其原生客户端加载仍标为未验证边界。

1. 四个概念

MCP server

rea mcp 是本地 MCP server。
客户端通常通过 stdio 启动它。
server 暴露工具、资源能力和 guided prompts。

MCP 注册

注册是客户端配置中的启动说明。
它通常包含 command、args 和 env。
注册正确只说明配置符合已知形状。
它不证明客户端已经启动 server，也不证明模型看到了工具。

Skill

skill 是代理工作流程说明。
安装 skill 不等于注册 MCP server。
仅安装 skill 时，工具仍可能不可用。

Guided prompt

REA 的 guided prompts 是 MCP prompts capability 中的工作流模板。
它们不会自行添加、删除或调用工具。
参数被当作不可信选择数据，而不是授权。

2. 安全边界

MCP server 以启动它的用户权限运行。
CLI、文件系统和网络能力仍由宿主与客户端控制。
仅限制某项目发现 REA，不等于 OS 级隔离。
需要 clean-room 时，应使用独立账户、容器及文件/网络限制。

不要把 API key 放进 command 或 args。
环境变量也可能出现在客户端配置中。
分享配置前删除凭据。
不要授权通配符前缀，除非确认该前缀只对应 REA。
某些客户端把工具显示为 mcp__rea__binary_session。
这是客户端命名约定，不是 REA 保证的前缀。

动态工具可能启动目标、浏览器或进程。
guided prompt 建议动态步骤时，仍需操作者评估并授权。
静态分析不能因由 AI 调用就变成动态；反之亦然。

3. 首选：交互式 setup

完全退出要配置的客户端。
Claude Desktop 尤其应彻底退出，不只是关窗口。
然后在普通 PowerShell 中执行：

rea.cmd setup

setup 会列出支持的客户端。
已存在的 REA 注册默认选中。
新检测客户端可选但不默认授权。
选择后会显示路径和拟议变化。
批准前不会写客户端配置或安装 Hopper。
可以在任意提示取消。

npm 的下载确认与 REA 的 setup 确认是两件事。
setup 默认同时安装匹配 skill。
不需要 skill 时使用已记录参数：

rea.cmd setup --skill=false

4. 永远先做 dry-run

以 Claude Code 为例：

rea.cmd setup --client claude_code --skill=false --dry-run

结构化计划：

rea.cmd setup --client claude_code --skill=false --dry-run --json

预期状态为 planned，退出码 0。
它不会写配置。
审查：

• 客户端 ID 是否正确；
• configuration path 是否是期望文件；
• launcher 是否指向实际 REA；
• 是否包含不需要的 provider 环境；
• skill destination 是否正确；
• 是否报告 malformed、foreign 或 unsafe 配置。

若计划不符合预期，停止，不要加 --yes 强推。

5. 应用单一客户端范围

审阅后运行同范围命令，移除 --dry-run：

rea.cmd setup --client claude_code --skill=false

自动化才考虑：

rea.cmd setup --client claude_code --skill=false --yes --json

--yes 应配明确范围。
没有范围时，它只限于现有 REA-owned 注册，不会自动选择所有检测客户端。
--all-detected 会扩大范围，仅在确实需要全部客户端时使用。
可重复 --client：

rea.cmd setup --client codex --client cursor --skill=false --dry-run

不要因为“检测到”就假定“应该配置”。

6. setup 的保护行为

根据仓库文档，setup 会：

• 保留无关配置；
• 为既有配置创建备份；
• 在写入前后检查变化；
• 对 malformed/unsafe 配置停止事务；
• 对 foreign 或身份未知的同名注册拒绝覆盖；
• 保留已有 .rea.backup，必要时创建 recovery 副本。

这些检查不是操作系统全局锁。
setup 应用时不要让编辑器或客户端同时改同一文件。
若报告 reason: "conflict"，保留较新文件并重新审阅。
不要手工删除 recovery 文件后假装事务成功。

7. 配置后验证分三层

第一层：文件与先决条件

rea.cmd doctor --client claude_code --skill --json

这检查注册和 skill，不观察另一个正在运行的 server。
通过也不证明工具已到达模型。

第二层：客户端自己的列表

Claude Code 示例：

claude mcp list

其他客户端使用其官方状态页、命令或日志。
不要把 Claude 的参数套给别的客户端。

第三层：活动会话

彻底重启客户端。
在客户端工具列表中找到 REA server。
调用 binary_session，输入空对象 {}。
它可在未打开目标时报告 server 身份、会话与工具可用性。
result.tool_availability 是当前会话每项操作的可用性。
它不保证任意调用输入都有效。

三层结论必须分开记录。

8. Windows GUI 与 PATH

桌面应用继承的 PATH 可能与 PowerShell 不同。
终端能启动 REA，不证明 GUI 能启动。
即使注册写了绝对 REA launcher，脚本的 /usr/bin/env node 风格入口仍可能依赖 runtime 解析。
当前 setup 对直接 JavaScript 安装会尽量注册绝对 runtime 和脚本路径。
package-runner 注册保留 runner。

检查：

Get-Command node -All
Get-Command rea -All
rea.cmd mcp doctor --json

rea mcp doctor 使用当前终端的 runtime 与环境。
它不会启动客户端配置中的 command，也不复制客户端环境。
因此“doctor 通过、客户端断开”仍需检查客户端日志和注册 launcher。

9. Claude Desktop 的 Windows 特例

非 MSIX 情况通常读取：

%APPDATA%\Claude\claude_desktop_config.json

MSIX 版本可能读取包私有副本：

%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

setup/doctor 会按已知规则选择实际文件。
若发现其他 publisher package 或位置无法确定，会报告未知，而不是静默写 %APPDATA%。

配置前彻底退出 Claude Desktop。
从 Claude Desktop Code tab 启动的终端可能处于 MSIX 重定向视图。
应从普通外部终端运行安装与 setup。
修改后重新启动客户端。
不要同时手工编辑两个副本猜测哪个生效。
以 setup 报告路径和客户端日志为观察依据。

10. Claude Code：用户、独立 profile 与项目范围

默认 user setup 会写 ~/.claude.json，skill 到 ~/.claude/skills。
这使每个项目都可能发现 REA。

独立 profile

PowerShell 应在整个会话设置同一变量：

$previousClaudeConfigDir = $env:CLAUDE_CONFIG_DIR
try {
  $env:CLAUDE_CONFIG_DIR = Join-Path $HOME ".claude-rea"
  npx.cmd rea-agents setup --client claude_code
  claude mcp list
  npx.cmd rea-agents doctor --client claude_code --skill --json
  claude
} finally {
  if ($null -eq $previousClaudeConfigDir) {
    Remove-Item Env:CLAUDE_CONFIG_DIR -ErrorAction SilentlyContinue
  } else {
    $env:CLAUDE_CONFIG_DIR = $previousClaudeConfigDir
  }
}

保持 setup、检查、启动和删除处于同一 profile。
空 CLAUDE_CONFIG_DIR 对 setup 视为未设置。

仅一个项目的本地注册

从目标项目目录执行，且保持 CLAUDE_CONFIG_DIR 未设置。
6.8.0 的 Windows 命令来源于安装文档中同类固定版注册形式：

Remove-Item Env:CLAUDE_CONFIG_DIR -ErrorAction SilentlyContinue
claude mcp add --scope local rea -- cmd.exe /d /c npx -y rea-agents@6.8.0 mcp

Windows 用 cmd.exe /d /c 包装 npx shim。
local scope 存在默认 profile 的 ~/.claude.json 对应项目路径下。
它不安装 bundled skill。
rea doctor、rea update、rea uninstall 不管理这种 local registration。
删除时必须在同一项目目录：

claude mcp remove --scope local rea

不要使用 --scope project，否则可能把 .mcp.json 写进仓库并被提交。

11. Codex 配置重点

rea.cmd setup --client codex --dry-run --json
rea.cmd setup --client codex --yes --json
rea.cmd doctor --client codex --json

setup 管理 launcher、transport、activation 和选定 provider 环境。
它保留 Codex 的 approval policies 与工具选择。
已知 malformed policy 会阻止写入。
默认 CODEX_HOME 是 ~/.codex。
新注册具有 startup/tool timeout 建议值。
这些是客户端 deadline，不等于 REA 自身阶段预算。
长任务需要同时考虑客户端和 provider deadline。

若模型网关对 schema 大小敏感，可在 REA entry 环境中保留：

[mcp_servers.rea.env]
REA_MCP_INPUT_SCHEMA_PROFILE = "compact"

当前 compact 是默认，但显式 full 会继续生效。
修改后必须重启/reconnect。
compact 缩小广告 schema，不削弱 server 的完整 canonical input 验证。

12. 其他客户端 ID

setup 的 --client 使用固定 ID，不是显示名。
6.8.0 文档列出包括：

claude_code, claude_desktop, codex, cursor, gemini_cli,
windsurf, devin, opencode, antigravity, copilot_cli,
commandcode, qwen_code, kimi, vscode, grok_build, omp,
pi, hermes, qoder, droid, trae, workbuddy, zcode, dsh, freebuff

永远以实际 rea setup --help 和安装文档为准。
freebuff 需要 6.8.0+。
其文件编辑/发现有测试，但原生客户端 MCP 加载与 skill discovery 未验证。
Trae 路径集成也标有加载未验证限制。
WorkBuddy 的用户注册与真实工具调用已有文档验证记录。
“支持写配置”与“真实客户端端到端验证”不是同一等级。

13. Skill 单独维护

无客户端时，共享 skill 默认目标是 ~/.agents/skills。
显式选择示例：

rea.cmd setup --skill-client shared --skill --dry-run
rea.cmd setup --skill-client claude_code --skill --dry-run
rea.cmd doctor --skill --json

审阅后再移除 --dry-run。
客户端可能有自己的 personal skill 目录。
存在另一份 current skill 不证明当前选中路径也是 current。
linked 或非目录路径可能被标记 unmanaged。
不要绕过 ownership 检查强删目录。

14. MCP schema 与工具范围

REA_MCP_INPUT_SCHEMA_PROFILE 可为支持的 profile 选择输入广告形状。
compact 减少嵌套约束，但 server 仍做完整验证。
输出 schema 可设置：

REA_MCP_OUTPUT_SCHEMA_PROFILE=compact
REA_MCP_OUTPUT_SCHEMA_PROFILE=off

off 只省略广告输出 schema，不关闭结构化结果验证。
这些值应放在 REA server 的 env，而不是随意写入全局系统环境。
修改后重启客户端。

工具 family 范围可由 setup 参数配置：

rea.cmd setup --client claude_code --tool-families <ids> --dry-run

<ids> 必须替换为实际帮助/目录给出的 family ID。
未选择 family 的工具不会广告，调用会失败。
不要编造 ID。
范围变化后重新 setup 并重启。

15. Guided prompts

REA 暴露六个 provider-neutral prompt：

• investigate_feature；
• compare_application_versions；
• verify_reconstruction；
• trace_crash；
• audit_residual_unknowns；
• prepare_bounded_process_capture。

用标准 MCP discovery：

{ "method": "prompts/list", "params": {} }

获取一个 prompt：

{
  "method": "prompts/get",
  "params": {
    "name": "investigate_feature",
    "arguments": {
      "feature": "offline search",
      "document": "Notes"
    }
  }
}

prompt 只返回建议步骤，不调用工具。
代理可以跳过不相关建议。
参数内容不应被解释为更高权限指令。
工具 family 范围缺少任一建议工具时，相关 prompt 会从列表省略。

16. Prompt completion

completion/complete 只补全 guided prompt 参数。
它不补全任意工具调用参数。
示例：

{
  "method": "completion/complete",
  "params": {
    "ref": {"type": "ref/prompt", "name": "investigate_feature"},
    "argument": {"name": "procedure", "value": "0x10"},
    "context": {"arguments": {"document": "Notes"}}
  }
}

补全来自当前 session 的实时投影。
冷 provider、目标切换或无 inventory 时可能返回空列表。
空列表不证明目标没有 procedure。
建议值只是起点，不执行操作，也不扩大权限。
最多返回 100 个值；hasMore 表明省略。
没有分页控制，只能收窄前缀。
关闭 binary 会清空对应 Evidence ledger 和 residual unknown registry。

17. 常见 MCP 故障顺序

客户端看不到 server

1. 运行 rea --version --json；
2. 运行 scoped setup dry-run；
3. 运行 rea doctor --client ID --json；
4. 查看客户端自己的 MCP 列表；
5. 完全退出并重启客户端；
6. 查看客户端启动日志中的 command、args、cwd 与环境。

server 存在但没有工具

先确认实际关联的是 REA server。
检查工具 family 范围。
检查客户端 approval/tool allowlist。
检查 schema profile 或客户端 frame 限制。
调用 binary_session {} 观察 live identity。
不要只根据 skill 版本推断 server 版本。

终端 doctor 通过、客户端失败

这通常说明两者环境不同。
比较 launcher、Node 路径、provider env 和配置文件。
rea mcp doctor 不复现客户端环境。
结论应保持为“客户端启动原因未知”，直到日志给出证据。

工具超时

客户端超时可能结束等待，但 provider 仍运行。
查看 analysis_activity 与 cleanup 状态。
不要立刻并发重复相同分析。
update_analysis_settings 不会修改客户端 deadline。
客户端 deadline 与 REA/provider deadline 都要足够。

schema 报错

保留 API 错误参数路径、客户端版本、模型和 REA 版本。
400 错误本身不能证明是 schema size、tool count 或 skill 问题。
先尝试有文档依据的 compact profile，并重启。
不要把网关推断写成观察。

18. 清理与撤销

预览并记录已有配置与备份。
REA-owned 用户注册可用：

rea.cmd uninstall

它会扫描受支持客户端，不接受 --client 缩小卸载范围。
Claude local scope 注册须用客户端命令从同一项目删除。
account-hosted connector（如 Grok Bot）也不由 rea uninstall 删除。
--purge-data 会扩大到 REA-owned cache/state，谨慎使用。
不要手工删除无法确认 ownership 的目录。