Collaborate Canvas

---
name: collaborate-canvas
description: 在 ShowAI 画布上与仍在编辑的人协作，处理 Agent 多对话、可选位置参考、Page 内组件组织，以及 iPad 与 Mac 的配对、断联和保存状态。用于明确的边写边画、多端协作或运行位置问题；普通查找与页面创作沿各自技能。
---

# 与人协作编辑画布

先沿 [use-showai](../use-showai/SKILL.md) 核对当前连接、项目和页面。已有宿主注入的身份与完整目录时沿用，不重复发现。创作继续使用 [show-document](../show-document/SKILL.md) 的当前阶段；本技能补充协作规则。

## 让人持续编辑

Agent 运行期间，人可以继续书写、画画、选择对象和切换对话。宿主在发送任务前保存当前页面；运行中 MCP 默认只能看到已经保存的版本，不能读取尚未提交的笔迹或输入。不要宣称已看到这些临时内容。若当前请求必须依赖它们，先等用户完成并保存相关输入，再读取确认；独立位置的修改可以继续。每次写入前读取当前 Page 的 hash/revision，围绕本次请求使用 `page_apply` 修改稳定节点，保留无关节点、手写笔迹和布局。不要把任务开始时的整页快照作为最终覆盖稿。

保存遇到版本冲突时重新读取并比较本轮实际修改。独立修改可合并；双方改到同一内容时保留草稿并说明需要选择的差异，不重复提交旧 hash。保存错误中的完整原稿可能在恢复草稿中；先用 `drafts_list`、`draft_read` 查验，按当前工具 Schema 恢复。界面修复不可保存的链接时保留文字，并另外保存原始恢复稿；不要放宽 URL 校验以执行本机、脚本或不受支持的协议。自定义组件里指向本机文件的 `file:` 链接由宿主播放器处理（见 create-component 的「本机文件」），不属于这里的链接修复。

只修改当前请求涉及的页面和对象。不同对话各自保留输入与工具进展；不要因为用户切换对话便停止另一个仍获授权的任务。不能把某一对话的目标、位置参考或未发送内容借给另一对话。

## 组织 Page 与组件

Board 中的新文字、数据图表和交互组件等目录组件放在 Page 容器中；同一段讲解的多个组件尽量放进同一个 Page，让文字顺序和宽度一致。使用当前连接 `guide` 的 containers/authoring 说明及组件 Schema；`component.insert` 的 `kind:"page"` 创建原生 Page，后续插入明确使用该 Page 的稳定 ID。宿主的组件插入会为 Board 上的普通组件建立 Page 外层。手写笔迹、箭头和形状保留画布对象语义。

图形自己的文字写进矩形、椭圆或箭头的 `attrs.label`，不另建 Page 叠在图形上；方框加箭头的草图用一次 `diagram.insert` 写入。图形文字、字号、可省略字段、连线绑定，以及原生图形与流程图组件的取舍见 [Board 对象编辑](../show-document/references/board-authoring.md)，操作字段读取 `guide` 的 whiteboard 说明。用户正在调整的图只改其请求涉及的图形和连线，保留其余位置；用户要求整理连好的图形时，对涉及的对象用 `diagram.arrange` 沿连线重新排布。

需要融入画布时，原生 Page 的 `attrs.frameless:true` 去掉边框、背景和标题行；它仍保留内容结构和直接编辑能力。按用户要求整理散落的组件时，保留各对象的稳定 ID、内部内容、阅读顺序和连线关系，先读取再移动外框，不在查找任务中自动搬动整个画布。

文字使用可编辑的原生富文本。不要把需要继续编辑的正文烘焙进图片，或用仅能修改源码的组件替代普通文字。完成后分别核对内容、保存状态和实际界面。

## 使用位置参考

消息可能附带 surfaceId、一个点或矩形区域，以及画布世界坐标。这些坐标来自用户在输入框旁的「标记参考位置」。它们帮助理解“这里”“这块区域”等请求，属于 prompt 中的建议；结合现有结构选择合适的位置，不把矩形当作强制裁切框，也不据此扩大编辑权限。没有参考时不猜测用户曾框选过的位置。

切换页面或对话后，只使用当前消息附带的参考。取消或移除标记后，后续消息不携带旧坐标。

## 引用选区与组件状态

人可以在选中菜单或右键菜单中「复制引用」，把选区、Board 对象、整个 Board 或整页交给终端里的 Agent；对话预览中右键「引用到对话」则进入宿主输入区。ShowAI 先保存页面，引用固定在保存后的 hash/revision，其中的 position 与上面的位置参考含义相同。人在你运行期间继续编辑时，按 [use-showai 的处理用户引用](../use-showai/SKILL.md#处理用户引用) 先核对版本：版本已变就比较期间的变化并重新读取相关 ID；同一内容已被人改动时不覆盖，先说明差异。

组件状态来自组件的「交给对话」等操作，只描述人当前看到的参数，没有保存到页面。按它理解问题；人要求保留时再修改组件数据。

## iPad 与 Mac 运行和保存

iPad 在 Agent 的运行位置中选择 Cloud 或自己的 Mac。模型来源由用户配置；Cloud 使用用户提供的模型 API 或已完成的 ChatGPT 授权，Mac 使用本机配置。位置选择与内容同步是不同状态，不能把“保存到 Mac”说成“Agent 在 Mac 上运行”。

同一局域网中，在两台设备打开 ShowAI；iPad 点击「连接 Mac」后选「使用此 Mac」。首次连接在 Mac 核对相同的六位数字并确认，之后使用记住的证书与设备凭据自动重连。撤销授权或 Mac 身份变化时，宿主重新发起确认。无需二维码。附近连接默认开启，可在 Mac 的设置 → Agent 中关闭。首次身份确认不能由 Agent 在未经用户授权时代为批准。MCP 文档工具不管理配对；缺少宿主 UI 控制能力时说明相应入口。

附近 Mac 可以直接运行 iPad 本地项目，无需先登录云端、同步项目或手工选择项目权限。宿主自动建立仅供此 iPad 当前项目使用的 Mac 工作空间，不会因此开放 Mac 上其他已有项目。Mac 使用自己的模型配置。已绑定服务器的项目自动沿用自己的同步账号，不能要求用户另选相同账号才能使用 Mac。跨网络 WSS 连接仍在 Mac 的高级设置中配置服务器账号与允许访问的同步项目；iPad 在运行位置选择该账号下在线的 Mac，首次跨网络请求在 Mac 的设备授权列表中确认。

iPad 保留持久副本与待传修改，局域网提交后收到 Mac 的内容变化通知。原本由 Mac 代存到服务器的共享项目继续由 Mac 同步；新接入的 iPad 项目由 iPad 沿原有账号同步服务器，本地项目不自动上传云端。断联时修改留在 iPad，重连后合并补传，同处冲突保留待处理。只有已设置 WSS 且已开放的同步项目可在局域网外继续远程执行；新建立的本地工作空间需要恢复局域网连接。发送任务前先确认所选 Mac 已收到当前页面；检查 Mac 已接收该 Page 当前版本的专属回执，或读取两端当前 Page 的 hash/revision 核对。仅从服务器同步状态不能推断局域网已保存。

交付时准确区分：本机草稿、已保存到 Mac、已同步服务器、Agent 运行位置、页面是否实际展示。仅看到保存或工具成功回执，不能宣称另一端已收到。