MCP / Code Agents 问题
本页说明
本页用于处理 MCP Servers 和 Code Agents / ACP 这两类高级本地能力的常见异常。遇到问题时，先判断它到底属于“高级能力本身没有正常工作”，还是更前面的 Companion、工作区或基础本地能力还没有准备好。
先判断是不是这页要处理的问题
| 现象 | 优先判断 |
|---|---|
| 技能提示需要 MCP，或相关工具不可用 | 这是 MCP 工具层问题 |
| Code Agent 无法启动 | 先判断基础接入和本地环境是否已经满足 |
| Code Agent 长时间没有进展 | 先判断是等待、暂停，还是确实启动失败 |
| Companion 本身还没有被扩展识别 | 这还不是本页问题，应先处理连接问题 |
如果当前连 Companion 都还没有稳定识别，或安装包还未被系统放行，那么应先回到Companion 连接问题处理，而不是直接进入 MCP 或 Code Agents 排查。
在进入这页前，先排除哪些问题
更稳妥的顺序是先确认下面几项基础条件：
- Companion 已经安装完成，并且扩展能够正常识别。
- 工作区已经连接完成。
- 命令运行时和其他基础本地能力能够正常使用。
- 当前本地边界和权限模式符合你的预期。
这一步很重要，因为 MCP 和 Code Agents 都建立在这些基础能力之上。前面的基础路径没有跑顺时，后面的高级能力通常也不会稳定。
MCP 相关问题怎么处理
如果你遇到的是 MCP 工具不可用、技能提示仍需要 MCP，或相关高级工具没有按预期出现，建议按下面顺序处理：
- 先确认 Companion 当前已经正常连接。
- 再确认问题不是工作区边界或权限模式造成的限制。
- 再进入诊断与自检，查看本机环境和相关工具可用性。
- 最后再回头核对当前技能或使用路径，是否本来就明确依赖额外本地工具能力。
对普通用户来说，最重要的判断是：技能提示需要 MCP，并不一定代表产品异常；很多时候，这只是说明当前任务确实依赖更深入的本地工具层。
Code Agents / ACP 相关问题怎么处理
如果你遇到的是 Code Agent 无法启动、启动后没有正常工作，或相关高级代码能力不可用，建议按下面顺序处理：
- 先确认 Companion 当前已经正常连接。
- 再确认工作区、权限模式和命令运行时已经正常工作。
- 如果仍然异常，再进入诊断与自检。
- 最后再回到 Code Agents / ACP 页面，核对自己是否已经进入适合使用这条能力的阶段。
也就是说，不要把 Code Agent 的问题单独看成一层完全独立的问题；很多时候，它实际上是前面基础能力没有准备好。
长时间没有进展时，先不要立刻判断失败
如果 Code Agent 已经开始运行，但长时间没有明显新进展，更稳妥的做法是先不要立刻判断为失败。
当前更常见的几种情况包括：
- 任务正在等待进一步输出
- 任务进入了暂停状态，需要继续后续步骤
- 本地环境或高级能力条件不足，导致执行没有顺利推进
也就是说，“没有继续输出”不一定等于“没有启动成功”；先区分是等待、暂停还是环境问题，排查会更准确。
MCP Servers 和 Code Agents / ACP 都属于建立在 Companion、工作区和基础本地能力之上的高级能力层。对普通用户而言，排查这类问题时，推荐顺序始终是先确认基础接入、再判断问题类别、最后进入高级能力层本身；如果 Companion 连接、工作区或命令运行时还未稳定，这些问题通常不应被直接归因于 MCP 或 Code Agents。