---
name: codex-canvas
description: 安装、更新并使用 Codex-Canvas。通过 Red SkillHub 或其他 Skill 渠道获得本 Skill 后，继续把最新稳定版 Codex-Canvas 安装为 Codex personal plugin；Skill 安装不是终态。适用于用户要求安装或升级 codex-canvas、输入 /canvas、打开本地无限画布、收集生成图片、把画布图片发送回 Codex 对话，或运行 Quick Edit、Remove BG、Expand、Edit Text、Edit Elements 等图片操作。
---

# Codex-Canvas

把这个根 Skill 作为 Codex-Canvas 的发现和安装入口。最终运行形态必须是完整 Codex 插件：personal marketplace 中存在 `codex-canvas@personal`，Codex 已把插件复制到版本化缓存，并在新任务中加载插件自带的 skills 和 MCP server。

## 安装为 Codex 插件

当用户要求安装、升级或修复 Codex-Canvas，或者当前目录来自 `redskill install codex-canvas` 时，先执行本节。不要在 Skill 文件下载完成后停止。

1. 将包含本文件的目录视为 `<codex-canvas-skill-root>`。如果本 Skill 刚由 RedSkill 安装，优先使用 `redskill install` 输出的安装目录；默认通常是当前 workspace 下的 `skills/codex-canvas/`。
2. 在 `<codex-canvas-skill-root>/scripts/` 中查找唯一以 `install-codex-plugin` 命名的 JavaScript 安装器。仓库源码与 SkillHub 兼容包可能使用不同的模块扩展名；只运行实际存在的那个文件。
3. 执行：
   `node <installer-path> --json`
4. 安装器必须完成整条稳定链路：把官方 GitHub 仓库放到用户长期目录、切换到最新已发布且校验通过的稳定 Release、安装锁定依赖、写入 personal marketplace、执行 `codex plugin add codex-canvas@personal`，再用 `codex plugin list --json` 验证安装状态和版本。
5. 默认跳过可选 RapidOCR 安装，以保持首次安装稳定快速。只有用户明确要求同时安装本地 OCR 时，才追加 `--with-ocr`。
6. 如果安装器报告缺少 `git`、`node`、`npm` 或 `codex`，如实报告缺失项。不要改用未校验的 `main` 分支、手工拼装插件缓存、系统 UI 自动化或直接链接临时 workspace Skill 目录。
7. 成功后告诉用户：插件已经安装，但当前任务不会动态获得刚安装插件的 MCP server 和专用 skills；关闭旧画布并新建一个 Codex 任务，再使用 `@Codex-Canvas`、`$canvas` 或“打开 Codex-Canvas 画布”。

重复执行安装器应更新或复用同一个稳定源码目录和 personal marketplace 条目。遇到非 Codex-Canvas 仓库、脏工作树或普通目录占用了目标位置时必须停止，不得覆盖用户文件。

## 定位运行时

1. 完成上面的插件安装后，优先使用已安装插件缓存中的 Codex-Canvas runtime。只有安装或故障恢复期间才把当前 Skill 目录视为 `<codex-canvas-root>`。
2. 执行 CLI 前，先确认 `<codex-canvas-root>/bin/codex-canvas.mjs` 存在。
3. 使用 Node.js 18.18 或更新版本运行命令。
4. 将所有画布数据保存在当前工作区的 `canvas/` 目录下。

## 打开画布

1. 使用以下命令启动或复用项目本地画布：
   `node <codex-canvas-root>/bin/codex-canvas.mjs open --project <workspace>`
2. 如果能拿到当前 Codex thread id，传入 `--thread-id <thread-id>`。Codex-Canvas 也会读取 `CODEX_THREAD_ID` 和 `CODEX_CANVAS_CODEX_THREAD_ID`。
3. 优先使用 `open`，不要直接用 `start`；`open` 会复用健康的已保存运行时，只在需要时启动 detached server。
4. 当 Codex in-app browser 控制能力可用时，直接在 Codex 内置浏览器打开返回的 URL。
5. 如果当前环境无法控制内置浏览器，返回画布 URL 的 Markdown 链接。不要启动系统默认浏览器。

## 图片收集

1. 对生成或编辑后的图片，尽量将输出保存到当前工作区。
2. 已知图片路径时，用以下命令导入：
   `node <codex-canvas-root>/bin/codex-canvas.mjs import <image-path> --project <workspace> --thread-id <thread-id>`
3. 如果输出路径不明确，用以下命令收集近期图片：
   `node <codex-canvas-root>/bin/codex-canvas.mjs collect --project <workspace> --thread-id <thread-id> --since-minutes 30 --limit 5`
4. 默认收集只扫描 `~/.codex/generated_images/<thread-id>`。未绑定 thread 时默认收集会安全地不执行；只有用户明确要求手动恢复时，才使用 `--from <dir,dir>` 扫描指定目录。
5. 遵守 Codex-Canvas 的放置规则：同一批生成图横向排列；从画布对象派生的结果放到源图片右侧。

## AI 操作边界

AI 图片操作必须使用稳定的 Codex-Canvas action id 和后端 job。不要把具体操作 prompt 写进前端代码。

- `quick-edit`：使用 `skills/canvas-quick-edit/SKILL.md`。
- `remove-bg`：使用 `skills/canvas-remove-bg/SKILL.md`。
- `expand`：使用 `skills/canvas-expand/SKILL.md`。
- `edit-text`：使用 `skills/canvas-edit-text/SKILL.md`。
- `edit-elements`：使用 `skills/canvas-edit-elements/SKILL.md`。

只有在对应 action 被请求时，才加载匹配的操作技能。平移、缩放、拖拽、选择、删除、铅笔绘制、文本对象编辑、工具栏状态、视口 framing 等确定性画布交互应保留在本地应用代码中。

## 跨平台规则

- 保持 macOS 和 Windows 跨平台兼容。
- 核心行为不要依赖 AppleScript、`osascript`、System Events、Windows UI Automation、坐标点击、模拟按键、剪贴板粘贴或操作系统特定的浏览器启动方式。
- 优先使用 Codex 支持的浏览器、插件、MCP、CLI 和后端 job 集成面。
- 修改工具栏、dock 和控件 UI 时，使用成熟图标集和应用既有图标风格。

## 插件兼容

不要要求 `.codex-plugin/plugin.json` 指向这个根 Skill。Skill 负责发现、bootstrap 和故障恢复；正式使用由 personal marketplace 安装的插件负责。插件安装路径继续暴露现有 `skills/` 目录和 MCP server 配置。