腾讯设计

中文

English

中文

English

外观

故障排查 ​

遇到连接失败、工具不可用或调用报错时，先确认你正在使用的接入方式，再按对应章节排查。

  • 本地 MCP
  • 云端 MCP

不论使用哪种方式，建议先按下面顺序过一遍。多数连接类问题可在前几步解决。

  1. 确认接入方式与配置一致

    Agent 里配置的是本地地址还是云端 URL？是否与当前实际使用方式一致？

  2. 确认版本足够新

    Ardot 客户端、AI Agent，以及相关插件/扩展尽量升级到最新稳定版。

  3. 确认基础环境可用

    • 本地 MCP：本机可访问 MCP 服务端口，防火墙/代理未拦截本地回环地址。
    • 云端 MCP：网络可访问 https://ardot.tencent.com/mcp，OAuth / 信任流程已完成。

  4. 确认设计上下文存在

    需要读写画布时，应已打开目标设计文件，或已在对话中提供可用的文件/节点链接。

    • 本地 MCP：已打开设计文件。
    • 云端 MCP：已提供可用的文件/节点链接。

  5. 确认 Agent 侧 MCP 已生效

    在 AI Agent 的 MCP / 连接器面板中，对应服务显示为已连接，且能列出 Ardot 相关工具。

  6. 做一次最小验证

    新开对话，执行一条简单指令（例如创建矩形、读取当前选中节点），排除历史会话缓存干扰。

排查时请保留完整报错原文（含 code / message），便于反馈给支持渠道。

本地 MCP ​

本地 MCP 由 Ardot 客户端在打开设计文件时于后台提供服务，默认监听 127.0.0.1:50501（端口被占用时可能自动切换）。

自查指南 ​

按顺序确认：

  1. 服务是否在跑 浏览器访问 http://127.0.0.1:50501/api/v1/health，确认健康检查返回正常。 也可访问 http://127.0.0.1:50501/api/v1/agents 查看 Agent 相关状态。

  2. Ardot 客户端是否就绪 客户端已启动，且已打开目标设计稿（服务通常仅在文件处于活动状态时可用）。

  3. 设计稿是否已连接 MCP 在客户端内确认当前文件已连接到 MCP（状态指示正常）。

  4. Agent 配置是否指向正确地址 配置中的 URL 应与实际端口一致，例如：

    json
    {
  "ardot": {
    "type": "http",
    "url": "http://127.0.0.1:50501/api/v1/mcp"
  }
}

  5. Agent 能否访问本机端口 部分沙箱/远程开发环境无法访问宿主机的 127.0.0.1，需改用本机直连或云端 MCP。

  6. 仍失败时的恢复动作 重新开关 MCP → 重启 Agent → 重启 Ardot 客户端 → 重新打开设计文件。

更多配置说明见 本地 MCP。

调用报错 NO_ADAPTER ​

如果出现：

text
NO_ADAPTER: No design file is open or connected. Please open a design file and try again.

通常表示当前没有可用的设计稿适配器。请确认：

  1. Ardot 客户端中已打开设计稿。
  2. 该设计稿已连接到 MCP。
  3. 若以上均正常，尝试刷新标签页或重启 Ardot 客户端后再调用。

配置错误 CONFIG_PARSE_ERROR ​

如果访问 http://127.0.0.1:50501/api/v1/agents 报类似错误：

json
{
  "error": {
    "code": "CONFIG_PARSE_ERROR",
    "message": "Failed to parse config file: ~/.codebuddy/.mcp.json (error at offset 487)",
    "status": 409
  }
}

说明 MCP 配置文件 JSON 无法解析。请检查相关配置文件是否存在多余逗号、缺引号、注释等非法 JSON/TOML 语法。

可借助 AI Agent 修复，例如：

text
帮我修复 MCP 配置文件中的错误。报错信息如下

<报错信息原文>

修复后重新加载 MCP / 重启 Agent。

权限错误 PERMISSION_DENIED ​

如果访问 http://127.0.0.1:50501/api/v1/agents 或启用 MCP 时报错 PERMISSION_DENIED，常见原因是：配置文件（或其上级目录）曾被以管理员 / root 身份创建或修改，属主变成了 root；而本地 MCP 的服务以当前普通用户运行，没有权限读写这些文件。

典型诱因包括：用 sudo 安装或编辑过 Agent / MCP 配置、用管理员权限启动过相关工具等。

处理思路：把文件属主改回当前用户。可按报错信息中的路径操作，例如 CodeBuddy 配置：

bash
# 查看属主（若 Owner 为 root，即可确认）
ls -l ~/.codebuddy/.mcp.json

# 将文件属主改回当前用户（按需替换路径）
sudo chown "$(whoami)" ~/.codebuddy/.mcp.json

# 若整个配置目录都是 root 属主，可一并修复
sudo chown -R "$(whoami)" ~/.codebuddy

其他 Agent 同理，把路径换成报错里的配置文件或目录即可（如 Cursor 的 MCP 配置目录等）。

也可把完整报错交给 AI Agent 处理：

text
帮我修复 MCP 配置文件的权限问题：配置曾被 root 创建/修改，本地 Node 服务以普通用户运行导致 PERMISSION_DENIED。报错信息如下

<报错信息原文>

修复后重新加载 MCP / 重启 Agent，再访问健康检查或 Agents 接口确认是否恢复。

云端 MCP ​

云端 MCP 通过 https://ardot.tencent.com/mcp 连接，依赖网络与授权状态。

自查指南 ​

  1. URL 是否正确 Agent 配置应指向官方云端地址，类型一般为 http。
  2. 是否完成信任与 OAuth 首次连接通常需要在 Agent 内信任该 MCP，并完成登录授权。
  3. 账号与文件权限 当前登录账号是否对目标设计文件有足够权限。
  4. 对话中是否提供了文件上下文 云端场景下，常需粘贴文件或节点链接，以便 MCP 定位操作对象。
  5. 网络与代理 公司代理、VPN 或证书拦截可能导致握手失败；可先用浏览器确认服务可达。
  6. 仍失败时 重新授权 → 删除后重建 MCP 条目 → 新开对话重试。

更多配置说明见 云端 MCP。计费相关见 权限与计费。

工具调用常见问题 ​

以下问题通常发生在 MCP 已连接、但具体工具调用失败时。

batch_edit 操作报错 ​

  • 确保每个 Insert / Copy / Replace 操作都有绑定名。
  • 单次调用不超过 25 个操作。
  • 不要对刚复制的节点的子节点使用 Update，因为子节点 ID 会重新生成。

截图为空或不完整 ​

  • 确认 nodeId 指向的节点在画布可见范围内。
  • 检查节点是否有实际内容（空 Frame 通常不会产生有意义的截图）。

batch_read 工具读取的信息较少 ​

读取较大的数据时，比如一次读取 500 多个节点的属性，会返回大量数据，极度占用上下文窗口，因此工具做了精简处理。建议分批读取。

排查后仍未解决 ​

如果按上文自查后问题依旧，请收集诊断信息后再寻求帮助。完整、可复现的反馈能显著缩短定位时间。

1. 先收集这些信息 ​

信息说明
接入方式本地 MCP / 云端 MCP
环境信息操作系统及版本；Ardot 客户端版本；AI Agent 名称与版本
配置摘要MCP 服务名、类型、URL（可打码敏感信息）；是否完成 OAuth
复现步骤从打开文件/启动 Agent 到出现问题的最短步骤
期望 vs 实际期望发生什么，实际发生了什么
报错原文完整错误码与 message，不要只截局部
发生时间大致时间点，便于对照日志
附件截图、短录屏、相关日志片段

2. 附上日志（针对本地 MCP） ​

本地 MCP 出问题时，把 Ardot 的运行日志一并附上，能帮助我们更快定位。按你的系统找到日志文件夹即可：

macOS ​

  1. 打开「访达」（Finder）。

  2. 顶部菜单栏选择 前往 → 前往文件夹…（或按 Shift + Command + G）。

  3. 粘贴下面路径后回车：

    text
    ~/Library/Logs/ardot

  4. 将会进入日志文件夹

Windows ​

  1. 按 Win + R 打开「运行」。

  2. 粘贴下面路径后回车：

    text
    %LOCALAPPDATA%\ardot\logs

  3. 将会进入日志文件夹

提交前请勿附带含密码、Token、内网地址或客户数据的内容；不确定时，优先附带时间最接近的几个 .log 文件即可。

3. 寻求帮助 ​

在 Ardot 内点击右上角的头像图标，选择「意见反馈」，填写问题描述与附件。反馈时附上信息与日志，便于同学快速复现。

打开意见反馈

更多帮助方式参考 联系我们。若你愿意补充最小可复现示例（例如一份脱敏后的公开设计文件链接、或最小 MCP 配置），定位通常会更快。

Copyright © 1998-2026 Tencent. All Rights Reserved.