affinity

Affinity 控制

Affinity（/Applications/Affinity.app，Canva 时代的统一应用）没有 AppleScript 字典、CLI 或 URL 方案，且其文件格式为专有格式。它唯一的自动化接口是 AI connector：启用后，应用会通过 http://localhost:6767/sse 提供其 JavaScript 脚本 SDK。该端点使用 MCP 协议，但此技能通过 HTTP/SSE 直接驱动它，并使用零依赖的 Node CLI——无需配置 MCP 客户端，也不会将工具架构加载到上下文中。已针对 Affinity 3.3.0（build 4850）完成端到端验证。

• scripts/affinity-cli.mjs — CLI（Node ≥ 18，无需 npm install）。
• references/api-reference.md — 已验证的端点工具约定 + SDK 前导内容摘要。编写脚本前请先阅读。
• references/sdk-map.md — 精选 SDK 摘要：模块映射、节点模型、创建示例（文本、图像、调整项）和注意事项。编写超出基本绘图示例的内容时请阅读。
• references/sdk-docs/ — 完整的随附 SDK 文档（142 个主题，约 1.8 MB）。先阅读 sdk-map.md，再用 grep 查找准确的签名；切勿完整阅读大型文件（nodes.js 约 300 KB）。
• 原生 *Api 层（随附 JS 所封装）的在线签名参考： https://sdk.affinity.studio/latest/js/（apis/<ApiName>/<method>.html、enums/<Enum>.html）。

控制循环

1. 预检 — 无法远程启用该端点：

   node scripts/affinity-cli.mjs ping     # → "OK http://localhost:6767 — Affinity 1.0.0"
   

   如果失败，请让用户启动 Affinity 并启用 AI connector（Affinity Settings → AI connector；参见设置指南——其中 Claude 端的连接器步骤无需执行，只需在应用内切换开关）。

2. 编写脚本 — 使用 Affinity SDK 编写 JavaScript。从 references/api-reference.md 开始，然后查看 references/sdk-map.md，以找到合适的模块和示例；用 grep 在 references/sdk-docs/ 中查找准确的签名。脚本是顶层可执行代码；仅通过 console.log() 输出（返回值会被丢弃）。入口：

   const { app } = require('/application');   // '/application.js' works too
   const doc = app.documents.current;          // null when no document is open
   

   几乎所有人编写第一个脚本时都会被以下三点绊住，请一开始就处理妥当：

   • 新建文档默认使用毫米。 NewDocumentOptions setter 只写不读；请在设置 o.width/height/dpi 前设置 o.units = UnitType.Pixel（来自 /units.js）。
   • 文本大小的单位是文档像素，而不是磅： px = pt * doc.dpi / 72。
   • app.documents.all 是普通 Array，而节点 .children 是惰性 Collection——参见 sdk-map。

   不确定用户设置允许哪些操作？编写需要相关权限的代码前，先记录 require('/environment').Environment.permissions（→ {fileSystem, network, genAI}）和 .fileSystemRoots。

   如果 API 不好用，请搜索众包提示库： node scripts/affinity-cli.mjs search "set blend mode"。

3. 执行：

   node scripts/affinity-cli.mjs run myscript.js
   

   通过端点的 execute_script 运行，并打印脚本的控制台输出。 错误会以文本形式返回——修改文件后重新运行。

4. 目视验证 — 切勿假定脚本已成功运行：

   node scripts/affinity-cli.mjs render --out /tmp/check.jpg            # current spread
   node scripts/affinity-cli.mjs render --selection --out /tmp/sel.jpg  # selection only
   

   然后 Read 该 JPEG（最大 1024 px）。系统会自动获取文档会话 uuid。

5. 交付 — 用户认可脚本后，将其安装以便重复使用：

   node scripts/affinity-cli.mjs add --title "My Script" --description "What it does" --file myscript.js
   

   库脚本会显示在 Affinity 的 Window → General → Scripts 下。

CLI 速查表

node scripts/affinity-cli.mjs ping                          # endpoint alive?
node scripts/affinity-cli.mjs run file.js                   # execute script, print console output
node scripts/affinity-cli.mjs run -                       # same, script read from stdin (heredoc)
node scripts/affinity-cli.mjs render [--selection] [--spread N] --out f.jpg
node scripts/affinity-cli.mjs tools [--json]                # list endpoint tools (verified list in api-reference)
node scripts/affinity-cli.mjs call <tool> '{"arg":"val"}'   # generic tool call
node scripts/affinity-cli.mjs add --title "T" --description "D" --file f.js
node scripts/affinity-cli.mjs list                          # library scripts
node scripts/affinity-cli.mjs save --title "T" --out f.js   # export library script to disk
node scripts/affinity-cli.mjs search "query"                # SDK hints search
node scripts/affinity-cli.mjs docs [<topic>]                # list / print SDK doc topics
node scripts/affinity-cli.mjs docs-dump <dir> [--force]     # (re-)vendor SDK docs; resumable

环境变量覆盖项：AFFINITY_MCP_URL（默认 http://localhost:6767）、AFFINITY_TIMEOUT_MS （默认 120000——长时间批处理脚本请调高）。

已知限制

• PERMISSION_DENIED 错误（SDK 前言中称为 NOT_ALLOWED）表示用户在 Affinity 设置中禁用了脚本的 AI／文件系统／网络访问权限——请让他们启用所需权限；不要尝试绕过限制。
• 脚本的文件系统访问仅限桌面端（app.userDesktopPath）；脚本代码无法访问网络。验证时优先使用 render，而不是在脚本中导出。
• 无法通过端点删除库脚本——只能从 Scripts 面板中删除。
• 设置当前跨页会清除所选内容；只有在实际切换时才设置。
• doc.close() 会关闭文档而不提示，并丢弃未保存的更改——只关闭脚本自身创建的文档，或先调用 save()。
• 长时间批处理期间，端点会话可能失效（POST → HTTP 404）——只需重新运行；每次 CLI 调用都会创建一个新会话（前言检查会自动处理）。
• Affinity 更新后，请将 app.version 与上文记录的版本核对。如果版本有变化，请将内容转储到一个空目录（docs-dump /tmp/sdk-new，然后替换 references/sdk-docs/）——转储到旧目录会保留过时文件，并跳过已更改的文件——然后更新 api-reference 和 sdk-map 摘要。
• 如果端点路由不可用，可退而使用 macOS GUI 自动化（System Events 按键／菜单），但这种方式脆弱且无法验证——仅用于简单的一次性操作，切勿用于编辑文档。

安全

与其他应用自动化技能不同，此技能不会自行开放端口——监听器属于 Affinity。但是否启用 AI 连接器仍是值得明确说明的决定。

• 启用连接器后，Affinity 会在 http://localhost:6767/sse 提供完整的脚本 SDK；该端点可对用户打开的文档执行 JavaScript。affinity-cli.mjs 只是该端点的客户端。
• 该端点没有身份验证：启用期间，每个本地进程以及共享计算机上的其他用户都能通过它操作 Affinity。CLI 会拒绝重定向到 AFFINITY_MCP_URL 来源之外的 SSE 端点，因此被劫持的会话无法悄悄将其重定向——但这保护的是此客户端，而非端点。
• 脚本可访问的内容受 Affinity 自身的 AI／文件系统／网络开关控制（PERMISSION_DENIED 错误表示其中一个开关已关闭）。启用某个开关会扩大所有客户端的操作能力，而不只是此技能——请先询问，不要擅自假定。
• **要关闭端点，请在 Affinity 设置中关闭 AI 连接器。**端点也会随之关闭；此技能安装的任何内容都不会继续监听。