使用手册 · CanvasOK

安装与准备

应用已包含运行 MCP 所需的 Node 环境，无需单独安装 Node，也不需要 CanvasOK 专用 API 密钥。AI 服务的登录及使用设置由所选工具管理。

从首页下载支持调用名称与简称的 macOS ZIP，解压后将 CanvasOK.app 复制到 Applications 文件夹。目前为 Apple Silicon 试用版，尚未进行公开签名和公证。
将 MCP 连接包解压到独立文件夹。在终端中把下面的 /path/to/CanvasOK-mac-connect 替换为实际连接包路径，再执行命令。
按生成的 commands.txt 中对应工具的步骤注册。将 canvasok 条目合并到现有配置，避免覆盖整个文件。准备脚本本身不会自动修改 AI 工具的设置。

mkdir -p "$HOME/Documents/CanvasOK-test"
cd /path/to/CanvasOK-mac-connect
python3 prepare.py \
  --app /Applications/CanvasOK.app \
  --project "$HOME/Documents/CanvasOK-test"

在多个 AI 工具中继续同一项工作时，请使用同一个项目绝对路径。如果移动应用或连接包，请重新运行 prepare.py，并更新已注册的路径。比较模型时，建议每次运行使用单独的项目文件夹。

本次提供 macOS arm64 试用版，暂未提供 Windows 和 Linux 安装包。应用界面目前支持韩语和英语，与四种语言的调用名称是不同的功能。

连接 AI 工具

连接包会生成调用同一原生应用的本地 stdio MCP 配置。外部注册的 MCP 服务器名称保持为 canvasok。下表说明配置方式，不保证每个工具和模型都能理解所有自然语言名称。

配合 commands.txt 使用的工具配置模板
AI 工具	配置与启用
Codex	使用 codex.toml 或 commands.txt 中的 Codex 注册命令。同一本地主机上的 Codex CLI 和 Desktop 共享 MCP 配置。注册后，在新对话中检查工具连接。
Claude Code / Claude Desktop	Claude Code CLI 和 Desktop 的 Code 模式参考 claude-code.mcp.json。Claude Desktop 的普通 Chat 使用独立的 claude-desktop.json 配置。将 mcpServers 合并到现有设置，然后完全退出并重新打开 Desktop。
Gemini CLI Antigravity	Gemini CLI 使用 gemini.settings.json，Antigravity 使用 antigravity.mcp.json。在 Antigravity 中选择 Gemini 模型与使用普通 Gemini 应用是两种方式。普通 Gemini 应用的本地 stdio 连接不在此连接包的支持范围内。
OpenCode	当前验证环境中的 OpenCode v1 使用 opencode-v1.json。v2 的 mcp.servers 结构另见 opencode-v2.json。请选择符合已安装版本的文件；Desktop 需要使用同一个本地服务器与项目。
Cursor	将 cursor.mcp.json 中的 mcpServers 合并到 Cursor 的 MCP 设置。在 CLI 或桌面编辑器中启用对应项目的 MCP 服务器，并检查工具列表。
Kimi Code	将 kimi-code.mcp.json 注册到 Kimi Code 的 MCP 设置。确认 CLI 与 Desktop 读取了预期的本地配置，再重启 MCP 服务器。
ZCode / Z.ai	将 zcode.config.json 中的 MCP 设置合并到 ZCode。在当前版本的 MCP 管理界面启用本地 canvasok 服务器。
DeepSeek Harness	参考 deepseek-harness.cordis.yml，将服务器注册到 dsh 的 MCP 客户端插件。开发者预览版本与插件结构可能变化，请按 commands.txt 操作并检查实际工具列表。

这些模板用于辅助注册。请另行确认已安装的工具版本、MCP 插件和模型的工具调用支持。远程 AI 工具服务器无法直接执行这台 Mac 上的本地应用路径。

先在一个 AI 客户端中打开项目并调用 CanvasOK 工具，应用会显示同一会话。使用多个客户端时，请重新读取共享项目状态并依次编辑。

确认工具列表中有 canvasok，再尝试：“用 CanvasOK 画一只 32×32 像素的猫，背景透明。”像素编辑可以在没有外部引擎的情况下试用。

多语言名称与自定义简称

以下名称为内置名称，均指向同一个 CanvasOK 工具，不会改变文档、图层名称或 AI 工具的执行命令。

内置调用名称 · 重置自定义简称后仍会保留
语言	调用名称
한국어	캔버스오케이 · 캔버스 오케이
English	CanvasOK · Canvas OK
日本語	キャンバスオーケー
中文	画布OK · 畫布OK

在应用中注册

打开 Tools → Invocation names and aliases（韩语界面为“도구 → 호출 이름·약칭”）。添加“画布助手”等名称后会立即保存。点击 Copy AI invocation instructions，可复制说明并粘贴到当前对话。最多可注册 16 个自定义简称，每个不超过 32 个 Unicode 码点。允许字母、数字、组合字符、空格及 . _ -，且必须至少包含一个字母或数字。

在终端中注册

执行 prepare.py 后，可在连接包文件夹中运行以下命令。list 查看名称，add 添加名称，resolve 检查名称，remove 删除自定义简称。--json 输出便于程序读取的结果。

./bin/canvasok aliases list --json
./bin/canvasok aliases add "캔오케" --json
./bin/canvasok aliases resolve "캔오케" --json
./bin/canvasok aliases remove "캔오케" --json

要清空自定义简称，请运行 ./bin/canvasok aliases reset --json，内置名称不会被删除。显示时保留原始写法；匹配时进行 NFKC 规范化、合并 Unicode 空格并忽略字母大小写。名称保存在用户数据目录的 aliases.json 中，也可通过 CANVASOK_ALIASES_FILE 指定其他路径。

保存的名称会出现在 MCP 初始化说明及文档工具的描述和元数据中。部分工具会刷新变化后的工具列表；如果新简称未出现，请重启 MCP 服务器并开始新对话。还需确认应用和服务器读取同一个名称文件。外部 AI 工具的配置不会被自动修改。

试着这样呼唤

캔오케로 32×32 투명 배경 고양이 도트를 만들어줘.

Use Canvas OK to create a 32×32 pixel cat on a transparent background.

キャンバスオーケーで、背景が透明な32×32ピクセルの猫を描いて。

用画布OK画一只32×32像素的猫，背景透明。

简称是帮助模型选择工具的自然语言提示，不会创建 /画布助手这样的斜杠命令，也不会增加执行权限。可将 harness-instructions.md 加入 AI 工具的指令。如果模型没有理解，请明确说明：“画布助手指的是 canvasok MCP 工具。先检查当前文档再操作。”

在 AI 与手动编辑之间切换

请 AI 创建并编辑像素文档，在 CanvasOK 窗口查看同一文档的变化。
想亲自修改时，在应用中暂停 AI 编辑，等待当前批次安全完成。
手动修改眼睛、耳朵或颜色，再应用变更。请使用当前编辑器对应的应用操作。
在应用中恢复后，请外部 AI 工具重新读取最新状态。暂停前排队的命令不会自动执行。

重新读取当前文档，保留我修改的眼睛，只调整尾巴形状。

暂停控制的是 CanvasOK 中 AI 的写入权限，不会停止外部模型的推理或计费。因旧状态而被拒绝的变更，需要读取最新状态后重新请求。

记录过程并导出 MP4

可将 2D 文档的编辑过程记录为事件，再导出视频。明确登记的提示词会按记录时间在视频底部累积显示。

在应用的记录与视频菜单中开始记录，同时登记需要显示的提示词，或明确要求 AI 记录提示词。
继续 AI 编辑与已应用的手动编辑，暂停和恢复操作也会留下记录。导出前先查看预览。
选择播放倍速并导出 MP4，同时将可编辑的原始项目另存为项目包。

MP4 导出需要单独安装 FFmpeg。目前输出无声视频，不会自动录制全部外部聊天或桌面屏幕。

输入文件与当前功能范围

图片与 AI 上下文: 可导入图片进行编辑，或选择参考区域。图片上下文仅在所选输入和允许传输的连接设置中提供。打开本地文件不会自动将其发送给外部模型；AI 工具和模型也需要支持图片输入。
MIDI: 导入 MIDI，与 AI 一起编辑音符和轨道，再保存 MIDI。乐器声音播放与 MIDI 渲染属于后续功能。
音频片段: 支持 WAV/MP3 输入、播放与波形显示，编辑片段范围、音量和淡入淡出，并导出 WAV。暂不包含语音识别、语音生成或音乐生成。
外部引擎与后续方向: 像素、MIDI 和音频编辑可使用内置功能开始。矢量编辑需要 VectorCraft，部分画笔和图层操作需要 PhotoCraft。3D 与完整视频编辑属于后续范围。

故障排查

AI 不理解新简称: 使用 aliases list 检查注册，重启 AI 工具的 MCP 服务器并开始新对话。设置 CANVASOK_ALIASES_FILE 时，应用与 AI 工具需读取同一个文件。不同模型的识别情况不同，可在请求中明确写出 canvasok。
应用未打开或显示了其他文档: 检查应用、连接包位置与项目绝对路径，并重新运行 prepare.py。参考生成的 commands.txt 中的手动会话连接命令，移除仍指向旧项目的重复 MCP 注册。
AI 的修改被拒绝: 检查 AI 写入是否暂停，或手动应用后文档状态是否发生变化。恢复后重新读取文档与任务状态，再请求新变更，不要原样重发旧的被拒绝命令。
如何比较模型？: 用相同输入、提示词和预算建立独立项目，分别记录模型名称与 AI 工具名称、版本，同时比较结果、人工介入次数、耗时和过程视频。

support@mdok.net ↗

用熟悉的名字呼唤，一起创作。