从需求到画布，再到可协作文档

Pixso × Ardot × 飞书
画板配置与编辑手册

一份可重复执行的端到端指南：连接设计 MCP、完成最小权限授权、读取目标画布、创建或修改节点、把流程图放进飞书文档，并回读验证结果。

适用对象：Codex 用户包含：云端与本地 MCP在线版本：私有访问

1 · 需求与目标节点→2 · MCP 连接与授权→3 · 画板读写→4 · 飞书沉淀与校验

01 / 连接

先选对服务模式

远程服务适合通过文件/图层链接跨设备使用；本地服务依赖桌面客户端和当前选中的设计文件。

02 / 编辑

先读结构，再写画布

确认文件、选区、权限和节点 ID；明确修改范围后批量编辑，避免误改整张画布。

03 / 交付

飞书画板需要单独写入

Ardot 画布与飞书文档里的白板块是两套资源；写入后要用文档链接和 board token 回查。

账号、授权与权限边界

一次连接不等于拥有目标文件的读写权限；MCP 授权、团队邀请和文件共享也不是同一件事。

连接前逐项核对

确认 MCP 服务名称和 URL 来自产品官方文档。
授权页显示的账号是准备操作设计稿/文档的账号。
核对 scope。只授权当前任务所需能力；出现非预期权限先取消并查证。
目标设计稿对当前账号可见；要改画布还须具备编辑权限或相应席位。
团队邀请链接仅代表加入团队的邀请；MCP OAuth 同意页仅代表授权服务。不要把二者混为一谈。

本次授权页示例

授权页面会说明调用方、当前账号与授权范围，例如“调用 MCP 服务 / mcp:use”。点击同意前，应确认这是自己刚添加的 MCP、账号正确、授权范围符合预期。

不要把凭据放进文档。 不要复制分享 access token、device code、App Secret 或 OAuth 回调参数。截图、日志和示例配置也应使用占位符。

如只需要查看设计，先确认账户席位与文件查看权限；写入工具通常还要求文件编辑权限。

Pixso MCP：配置、定位页面与编辑

Pixso 支持 Remote MCP 和 Local MCP。公开云端地址与私有化部署地址不同；本地默认端口也可能变化。

远程接入（Codex）

添加 HTTP MCP 服务

Codex 设置 → Integrations → Plugins → MCP → Add server，选择 Streamable HTTP，地址填写公开云端服务 URL。

完成 OAuth

在 Pixso 授权页面确认账号后授权。Access Token 仅在 OAuth 不可用等场景使用，并保存在安全凭据库中。

把目标图层链接发给 Agent

复制目标 Frame/图层链接。指定单个图层时优先使用带 item-id 的图层链接；普通分享链接或只有 page-id 的链接可能不足以定位图层。

先只读核对，再编辑

让 Agent 读取选中节点、样式或截图，确认标题/Frame 与预期一致后，再给出具体改动范围。

{
  "mcpServers": {
    "pixso-oauth-mcp": {
      "url": "https://pixso.net/mcp"
    }
  }
}

Pixso 官方文档将此 URL 标注为 public-cloud 地址。私有化部署请使用企业环境提供的域名，不要照搬公网地址。

本地接入（当前桌面文件）

打开 Pixso Desktop 并登录

本地 MCP 文档要求 Pixso Desktop 2.2.0 或更新版本；打开目标设计文件并保持标签激活。

在画布启用 MCP

点设计文件顶部 MCP 配置入口并开启服务。端口默认 3667，冲突时可能变化，以 Pixso 客户端当前显示地址为准。

添加 Streamable HTTP 服务

在 Codex MCP 设置中新增服务，填当前客户端显示的 URL。不要让 Desktop 与 IDE 插件同时占用本地服务，避免端口冲突。

选中目标容器

依赖“当前选中图层”的任务，在画布先选中一个 Frame/容器。也可使用带 item-id 的链接定位。

{
  "mcpServers": {
    "pixso-local": {
      "type": "http",
      "url": "http://127.0.0.1:3667/mcp"
    }
  }
}

Local MCP 只连当前机器的活动设计文件；Codex 若运行在远端容器/沙箱，可能无法访问宿主机 127.0.0.1。

设计任务的提问模板

新增登录页面“使用 Pixso MCP。目标是此链接中的登录页面 Frame。先读取当前页面与设计规范，再新增登录页面；沿用现有品牌色、字体与间距，补充密码登录、记住我、忘记密码、注册入口和表单错误状态。写入后截图检查文字、层级和对齐。”

精确修改已有图层“只修改链接中这个 Frame 的视觉风格：保留现有文案、节点层级和尺寸。先读当前颜色与字体，提出风格方向后统一调整颜色、描边、圆角与字号。完成后检查布局和文字溢出。”

Ardot MCP：连接设计文件

Ardot 既可以使用云端 Remote MCP，也可以使用桌面客户端提供的 Local MCP。

模式	服务名 / 地址	授权	适用情形
云端 Remote	`ardot-remote` `https://ardot.tencent.com/mcp`	Agent 信任 + 浏览器 OAuth	通过设计文件/节点 URL 操作，跨设备使用
本地 Desktop	`ardot-local` `http://127.0.0.1:50501/api/v1/mcp`	不需 OAuth；需要本机客户端	操作当前打开的设计文件；端口以客户端显示为准

Codex CLI 添加云端服务

codex mcp add ardot-remote --url https://ardot.tencent.com/mcp
codex mcp list

运行添加命令，允许 Codex 信任该 MCP。
浏览器打开 Ardot OAuth 授权页，核对账号后同意。
运行 codex mcp list 确认服务已连接。
新开对话，使用读取当前编辑器/文件信息的最小任务验证。

桌面 Local MCP

启动 Ardot Desktop，打开目标设计文件。
在客户端首页右上角 MCP 配置入口启用 Agent。
使用客户端界面显示的本机地址配置 Codex。
确认目标文件当前处于活动状态，再在新对话中读取选区或文件信息。

端口被占用时 Ardot 会换端口。不要仅凭示例中的 50501 判断连接地址；以 MCP 配置入口显示的地址为准。

Ardot 常用能力

阶段	工具	用途
确认上下文	`fetch_editor_state` / `fetch_file_info`	读取当前文件、页面、选区、文件 ID 与权限
读取结构	`batch_read` / `capture_layout`	按节点 ID 或模式读取图层、属性和布局问题
统一风格	`fetch_variables` / `search_style_guide` / `build_style_guide`	复用设计变量、组件和风格参考
读写节点	`batch_edit`	批量 Insert、Copy、Update、Move、Delete、Image 操作
检查结果	`capture_screenshot` / `export_nodes`	视觉复核或导出 PNG、SVG、PDF 等资源

Ardot 画板：日常编辑工作流

适用于新增页面、修改视觉风格、调整结构、补节点、移动图层和导出资源。

把目标说具体

提供文件 URL 和目标 Frame/节点；说明要保留什么、允许改什么、验收标准是什么。选中节点上下文出现时，也要核对名称与 ID。

读取权限、节点结构和设计规范

先读文件信息、选区、节点层级、变量/样式；复杂布局读到目标 Frame 即可，不必一次拉取整份文件。

选编辑路径

视觉微调用 Update；新增/复制节点用 Insert/Copy；移动用 Move；删除用 Delete。若只是换风格，优先保留内容和布局，只改颜色、字体、描边、圆角与间距。

批量写入并读取返回值

每次最多 25 个操作。Insert/Copy 要有新的绑定名；插入画布根节点前先查空白区域；新节点必须命名并设置尺寸。

检查布局与截图

用布局检查发现裁切、重叠和空间异常；在一组改动完成后再截图，逐项检查文字、层级、对齐与色彩对比。根据发现的问题一次性修复后再复核。

安全的风格微调示例

U("目标卡片ID", {
  fill: "#FFFFFF",
  stroke: "#DCE4EE",
  strokeWeight: 1,
  cornerRadius: 18
})
U("标题节点ID", { fill: "#10243A" })

节点 ID 应从本次读取结果复制。不要把示例 ID 直接用于其他文件。

新增元素示例

title=I("目标FrameID", {
  type: "text",
  name: "权限说明标题",
  content: "权限说明",
  x: 32, y: 24, width: 280, height: 30,
  fontSize: 20,
  fontName: {family: "Noto Sans SC", style: "Bold"},
  fill: "#10243A"
})

实际字体必须从工具返回的可用字体列表选；尺寸和坐标根据父节点布局调整。

改动范围提醒：“风格调整”默认理解为保留已有内容和结构的视觉微调。如果要删改整张图、替换整页，先明确说明这是整板重建并确认版本/备份策略。

Ardot 画板编辑提示词“使用 Ardot MCP 操作这个文件。先确认文件权限、当前页面和目标 Frame；读取目标节点、布局、变量与组件。我的目标是……保留……只改……一次调用不超过 25 个相关操作。完成后用布局检查和截图验证，不要顺手改其他 Frame。”

飞书文档与画板：配置、创建、编辑

本次对话使用的是 Lark CLI/技能进行文档和白板操作；它与 Ardot MCP 是分开的连接及资源。

关键区别：Ardot MCP 修改 Ardot 设计文件中的节点；Lark CLI 把画板作为白板 block 放进飞书云文档，或编辑已有飞书画板。两个画布不会自动双向同步。要从 Ardot 转交到飞书，需导出/转换内容并写入飞书画板。

一次性初始化与用户授权

安装/配置 CLI

按官方说明安装 Lark CLI；首次配置时运行 lark-cli config init。CLI 需要什么 App 权限取决于所调用的业务域。

按最小范围申请用户权限

只操作云文档时优先申请 docs 域；需要云盘文件上传/管理时再加 drive。用户身份和 bot 身份代表不同主体。

完成浏览器授权并校验状态

跟随 verification URL 和二维码完成授权；回来后完成 device-code 步骤，再运行状态验证。授权码有时限，过期要重新发起。

每条写命令显式指定身份

使用 --as user 操作个人可见文档。Bot 只访问应用身份资源，不能代表用户创建其私有文档。

# 按本次任务申请 docs 范围
lark-cli auth login --domain docs --no-wait --json

# 用户完成授权后，由 Agent 完成设备码确认
lark-cli auth login --device-code <device_code>

# 验证当前用户和授权范围
lark-cli auth status --json --verify

不要把 device_code、token 或完整登录 JSON 贴进共享文档。若返回 scope 不足，按报错只申请缺少的 scope，不要默认申请 all。

新建含画板的飞书文档

先梳理受众、目的和内容结构，选择 Mermaid 或 SVG。
运行 docs +script init-draft，按返回路径写入完整 XML 草稿。
将画板作为 <whiteboard type="mermaid"> 或 <whiteboard type="svg" path="@./..."> 插入。
运行 docs +script parse，确认 assessment 为 passed，并手动检查 XML 规则。
调用 docs +create，从返回值取文档 URL 和新建画板 block token。
用 docs +fetch --detail with-ids 回读，确认标题、画板 block 与 token。

XML 结构最小例

<title>业务流程图</title>
<p>说明流程范围与参与角色。</p>
<whiteboard type="svg" path="@./diagrams/diagram.svg"></whiteboard>

流程、分支、架构适合画板。SVG 要包含完整根节点和 viewBox，不引用外部脚本或远程资源。

编辑已有飞书画板：先导出，再选路径

编辑目的	推荐方法	写入风险
查看/检查原图	导出 preview；需要矢量内容时导出 SVG	只读
改 Mermaid/PlantUML 原图	导出 source，改源码后按原格式 update	overwrite 会重建整板，先确认
只改少数节点文字/颜色	导出 raw 到文件，编辑目标节点字段	raw 写回若 overwrite，同样是整板重建
在原图上增加一段内容	先预览和导出节点确定位置，再 update 追加	默认追加，不带 overwrite
重新排版或结构重绘	先评估能否增量改；整板重画会覆盖旧内容	需要事先确认

# 从文档取 board_token 后导出预览 / SVG / raw
lark-cli whiteboard +export \\
  --whiteboard-token <board_token> \\
  --output-type preview --output ./preview.png --as user

# 修改 SVG 后写回。--overwrite 会删除画板现有内容再重建。
lark-cli whiteboard +update \\
  --whiteboard-token <board_token> \\
  --input_format svg --source @./diagram.svg \\
  --overwrite --as user

只要保留原画板内容，就不要加 --overwrite；默认行为是追加。要整板替换时，先说明覆盖范围，并取得明确同意。重复请求使用同一个幂等 token，避免重试时重复写入。

飞书文档常用命令速查

# 回读文档中的白板 block 和 token
lark-cli docs +fetch --doc <文档URL或token> --detail with-ids --as user

# 导出飞书白板
lark-cli whiteboard +export --whiteboard-token <board_token> \\
  --output-type svg --output ./board.svg --as user

# Mermaid 增量追加（省略 --overwrite）
lark-cli whiteboard +update --whiteboard-token <board_token> \\
  --input_format mermaid --source @./diagram.mmd --as user

本机 CLI 帮助可能随版本更新；运行 lark-cli docs --help、lark-cli whiteboard --help 查看当前可用参数。

故障排查清单

按“连接 → 身份 → 文件上下文 → 权限 → 操作参数”的顺序定位。

现象	优先检查	处理方式
MCP 服务没出现/未连接	Agent 配置字段、传输类型、URL、客户端版本	刷新或重启 Agent；Local MCP 检查 Ardot/Pixso 客户端当前实际端口
授权页失败/账号不对	当前登录账号、OAuth 状态、授权范围	取消非预期授权；确认账号后重新连接。不要复用过期 device code
无法读取目标文件	是否提供正确文件/图层链接；当前账号是否有访问权	Pixso 用带 item-id 的图层链接或选中 Frame；Ardot Remote 提供目标文件/节点链接
Local MCP 找不到当前画布	目标文件是否在桌面客户端打开并激活；文件是否连接 MCP	切回目标设计文件，重启 MCP 服务；必要时重启客户端和 Agent
修改操作报错	节点 ID、父节点、属性名/类型、绑定名、批次大小	重新 batch_read 精确读取目标；校验 schema；每批不超过 25 操作
布局或文字异常	Frame 尺寸、文字宽度/字号、自动布局、裁切	capture_layout 查问题，改完一批后截图复核
飞书白板写入失败	board_token、当前身份、编辑权限、输入格式与内容	从目标文档 fetch 最新 token；先导出验证内容，确认 append/overwrite 模式
macOS 出现 Keychain 错误	CLI 在沙箱/后台是否能访问系统钥匙串	在可访问钥匙串的交互终端重试；只在理解安全影响后调整 Keychain 配置