CoreStudio Agent 集成

在你的 Agent 中使用 CoreStudio

CoreStudio 会从 Mac 上已签名的本机应用包安装一个宿主 Skill 和一份共享 CLI。可运行包内命令安装，也可在“应用设置 → Agent 集成”中安装。

官网只负责说明流程，不会检测你的 Mac，也不会执行安装。
Skill
为每个使用的 Agent 单独安装
CLI
只安装一次，六种受支持宿主共用
连接
本机 CoreStudio 与 Local Bridge

一次安装 Skill 与 CLI

不要下载 Skill 压缩包，也不要运行网络安装脚本。CoreStudio 使用已签名应用内自带的集成资源。

  1. 安装 CoreStudio

    尚未安装时，从 GitHub 下载最新签名 macOS 版本。安装集成本身不要求打开窗口；需要连接项目时再启动 CoreStudio 并开启 Agent Bridge，目标项目不需要预先打开桌面标签。

  2. 无需操作窗口即可安装

    有本地命令能力时运行应用包内 setup.sh，不需要 Computer Use 或运行中的 Bridge。只有浏览器能力时，请用户执行一次命令；设置中的安装按钮是可选入口。

  3. 安装所选宿主

    执行下方对应宿主的命令，或使用设置中的安装、更新或修复按钮。两种入口使用同一安装服务，准备宿主 Skill 和共享 CLI。

  4. 新建 Agent 对话

    已经打开的对话可能不会重新扫描刚安装的 Skill。首次使用前请新建一个本地对话。

/bin/bash "/Applications/CoreStudio.app/Contents/Resources/agent-integration/setup.sh" codex

命令只安装所选宿主。安装多个时，在命令末尾依次写需要的 ID，例如 workbuddy qwenwork doubaowork。应用在其他目录时使用实际路径。旧包缺少 setup.sh 时，更新 CoreStudio 或请用户在设置中安装，不要直接执行底层 install.sh，也不要下载替代脚本。安装不授权生图。需要访问项目时可用 open -b com.corestudio.desktop 启动 CoreStudio；登录、浏览器授权和新建宿主任务仍可能需要用户操作。

Agent 接入说明

WorkBuddy

使用当前本地任务提供的 agent-browser 或 playwright-cli；预览面板不等于可操作的浏览器。

  1. 使用 WorkBuddy 本地任务，通过包内 setup.sh 安装集成；只有登录阻碍继续操作时再请用户登录。
  2. 安装后新建任务，确认已发现 CoreStudio Skill 和浏览器技能；CLI 找不到时使用 Skill 记录的绝对路径。
  3. 让 Agent 打开所选项目的 Agent Board，读取真实页面并连接；仅打开预览或下载网页不代表连接成功。

实测任务未提供原生生图工具。能力以当前任务为准；无可用工具时，可按需授权使用 CoreStudio 当前图片服务，费用由对应服务商计收。

千问办公

通过官方 QwenWork 扩展操作外部 Chrome；本次接入未验证可操作的内置浏览器，Edge 未做实机验收。

  1. 登录千问办公中国版，使用本地任务，在 CoreStudio 中使用包内 setup.sh 安装千问办公集成。
  2. 在千问“连接器 → 已安装 → 浏览器”启用连接器。若等待扩展连接，检查实际使用的 Chrome 配置中的官方 QwenWork 扩展；缺失时按千问客户端提供的目录加载。
  3. 打开目标 Agent Board，在扩展中点击“连接”，确认当前标签页已连接。chrome://extensions 等受限页面不能用于连接验证。
  4. 新建千问任务加载 Skill 与浏览器工具。若仍没有工具，可在原画布点击“复制连接指令”，完整粘贴到千问本地任务；发送后不要刷新原页面。

实测任务能发现原生图片工具，但本轮未调用生图，不能保证每个账号或任务都有。生成结果需保存为本机可读图片再写回；CoreStudio 生图需另行授权并使用当前配置。

豆包工作

使用豆包工作“本地电脑”任务中的“操作浏览器”能力；云端任务无法直接访问这台 Mac 的 CoreStudio。

  1. 先登录豆包工作并运行一次“本地电脑”任务，让客户端建立默认本地技能目录。
  2. 在 CoreStudio 中选择豆包工作安装集成；目录未初始化时先完成上一步，不手工创建猜测路径。
  3. 新建本地电脑任务加载 Skill，用任务的操作浏览器能力打开并连接所选项目的 Agent Board。

实测已完成可见参考图导出和图片写回。原生图片工具可发现但未做收费生图验收；仅聊天预览不能写回，需取得本机原图。使用 CoreStudio 生图仍需单独开启权限。

先验证安装，再验证项目连接

安装完整与项目可连接是两个不同层级。先检查版本，再检查正在运行的 CoreStudio。

1. 安装完整性

这个命令不要求当前已经打开项目，也不要求 Local Bridge 可达。

corestudio --version --json

2. 本地连接

打开 CoreStudio 后再运行。它只报告 Bridge 状态，不修改项目数据；认领 Board 后，项目命令使用任务 session 绑定。

corestudio read status --json

让一个 Agent 任务绑定一个项目

保持 CoreStudio 运行并开启 Agent Bridge。Skill 会建立任务 session，并在认领 Agent Board 时绑定所选项目；桌面标签不决定目标。

打开我选择的 CoreStudio 项目，把当前任务绑定到它的 Agent Board，读取画布与选区，并告诉我可以继续做什么。

Skill 会为 Codex 建立并复用仅随当前进程存活的 Agent session；认领 Board 后，此任务独立绑定该项目，不受桌面标签影响。

CLI 常用任务

这里提供按任务组织的入口，不复制完整命令合同。Agent 调用应保留 JSON 输出，完整参数以原始合同为准。

只读检查 Local Bridge 与当前项目状态，不修改项目数据。

corestudio read status --json

读取当前画布选区与稳定图片引用。

corestudio read selection --agent-session <sessionRef> --jsonAgent session

取得当前项目或项目选择页的稳定本地 Agent Board 地址。

corestudio read board-url --json

通过 CoreStudio 校验和持久化写回本地生成图片及其实际最终提示词；确实没有提示词时可以省略。

corestudio write image /absolute/path/result.png --source-type generated --request-id <requestId> --origin agent-board --prompt "<finalPrompt>" --agent-session <sessionRef> --jsonAgent session

把 Mermaid 输入转换为项目中的原生可编辑 Excalidraw 图元。

corestudio write diagram --format mermaid --file /absolute/path/process.mmd --request-id <requestId> --anchor auto --agent-session <sessionRef> --jsonAgent session
打开完整 CLI 合同

先定位现象，不连续叠加修复

找到与当前现象匹配的一项，执行最短恢复路径，再验证一次后决定是否继续。

已安装 Skill，但任务没有浏览器工具或千问仍在等待扩展连接。
  1. 先确认是本地任务；安装或更改连接器后新建任务加载工具。
  2. 按当前宿主的准备步骤检查浏览器能力。千问分别检查客户端开关、实际 Chrome 配置中的 QwenWork 扩展、目标标签页的“已连接”状态。
  3. 无法使用浏览器工具时，从原 Agent Board 复制完整连接指令到目标本地任务；复制后保留原页，不刷新。

任务能从目标真实页面读取 nonce 并认领，或明确通过原页面复制引用完成 CLI 认领。

宿主找不到本机文件，或豆包安装提示默认技能目录未初始化。
  1. 使用当前 Mac 的本地任务；豆包先登录并运行一次“本地电脑”任务，让宿主建立默认技能目录。
  2. 回 CoreStudio 选择对应宿主安装，再新建任务加载 Skill；设置中没有该宿主时先安装包含此支持的应用版本。

本地任务能加载 Skill，并用其中的绝对 CLI 路径读取版本和本机状态。

Agent 能聊天或展示图片，但没有可写回的本机原图。
  1. 检查当前任务实际图片工具与账号能力；聊天预览不是原始文件。
  2. 将宿主生成结果保存或下载到本地任务可读路径，保存真实最终提示词与参考关系，再经 CLI 写回。
  3. 参考图使用 read image-paths --visible 按元素导出可见区域；临时导出文件失效时重新导出。无原生工具时仅在用户授权后使用 CoreStudio 生图。

写回返回 persisted: true，重新读取记录或画布能找到结果；收费生成不能盲目重试。

当前 Agent 对话可能没有重新扫描对话启动后安装的 Skill。
  1. 新建一个本地 Agent 对话，然后重试同一条自然语言任务。

先确认新对话已经识别 CoreStudio Skill，再运行项目命令。

图形化 Agent 宿主可能没有继承包含 ~/.local/bin 的终端 PATH。
  1. 让已安装 Skill 使用 CoreStudio 记录的 CLI 绝对路径。

通过 Skill 记录的路径运行 corestudio --version --json。

CoreStudio 没有运行，或本机会话尚未变为可达。
  1. 打开已安装的 CoreStudio，等待启动完成，然后只运行一次 read status。

corestudio read status --json 返回结构化状态。

Bridge 已可达，但当前 Agent 任务还没有认领并绑定项目。
  1. 让 Agent 读取 CoreStudio 项目列表，打开稳定项目选择页，并认领选中的 Board。

任何写入前，使用同一 Agent session 的 read project 已报告目标绑定项目。

受管 Skill、CLI 包装器或集成合同缺失或过期。
  1. 打开“应用设置 → Agent 集成”，对当前宿主执行更新或修复。

corestudio --version --json 报告当前集成合同。

CoreStudio 重启后，Agent session 会失效。
  1. 保持 CoreStudio 运行，让 Skill 为当前对话重新建立 Agent session。

通过 Skill 重试读取或写入，确认新 session 已被接受。

Agent Board 页面闲置时间较长，或 CoreStudio 已重新启动，房间连接因此失效。
  1. 在画板恢复提示中点击“刷新页面”，重新建立房间连接。

同一个稳定 Board 重新打开已绑定项目并回到可编辑画布。

当前宿主未获 CoreStudio 图片生成授权，或没有配置可用的当前服务。
  1. 在 Agent 集成设置中检查当前宿主权限；需要时另行配置图片服务。

生成前，read capabilities 同时报告 supported、authorized、configured 为 true。

查看原始文档