aseprite-mcp 工具不够用时怎么办:run_lua_script Lua 逃生舱用法与 run 命令安全边界
aseprite-mcp 工具不够用时怎么办:run_lua_script Lua 逃生舱用法与 run 命令安全边界
aseprite-mcp 是一个让 AI 助手直接操控 Aseprite 创作像素画的 MCP 服务器,内置 123 个开箱即用的工具;当这些工具覆盖不了你的需求时,run_lua_script 就是那个 Lua 逃生舱。本文带你快速看懂它的用法,以及 run 命令背后设置的 4 道安全边界。
🧰 先穷尽现成工具,再谈"逃生舱"
aseprite-mcp 把 Aseprite 的能力拆成了 18 类、123 个工具:画布、绘制、图层、动画、调色板、特效、切片、瓦片地图、导出、检查与分析……绝大多数像素画工作流根本不需要碰 Lua。
项目文档 README.md 的 Scripting 一节把 run_lua_script 明确定义为 the last resort(最后手段),只在两种场景下才该出手:
- 所有专用工具都覆盖不了:比如写一个自定义程序化特效;
- 一次批量办成许多事:每调用一个专用工具,服务器就要启动一次 Aseprite 进程,用一段 Lua 脚本把多步操作合并进同一次 Aseprite 启动,能省掉大量往返。
剑士挥剑动画的 4 帧序列帧(examples/swordsman/swordsman_slash_sheet.png),正是这类 Aseprite 批量脚本的典型产物。
⚙️ run 命令执行链路:一次调用发生了什么
run_lua_script 的定义很薄(见 script.py),真正干活的是 AsepriteCommand。完整链路如下:
- 输入校验:脚本为空 → 返回
Script cannot be empty;filename不存在 → 返回File xxx not found(script.py),校验不过就不会启动 Aseprite; - 落盘:把 Lua 源码写入一个临时
.lua文件; - 执行:调用
aseprite --batch <filename> --script <临时脚本>,Aseprite 二进制优先取环境变量ASEPRITE_PATH(参考 sample.env); - 收尾:成功时捕获 stdout 作为结果返回,失败时返回 stderr,并在
finally中删除临时脚本(commands.py)。
其中静态方法 run_command 负责真正的子进程调用,是 Aseprite 进程被拉起的最后一站——这就是标题里"run 命令"所在的位置。
📝 batch 模式写 Lua 的四要素
Aseprite 的 batch 模式和交互模式行为不同,写脚本前记住这四点(来自 script.py 的官方注释):
| 要素 | 说明 |
|---|---|
app.activeSprite |
传了 filename 时会先打开该文件,画布对象就是 app.activeSprite |
print() 是唯一出口 |
想拿到数据只能 print;进程正常退出 不等于 逻辑成功 |
| 手动保存 | 改动不会自动落盘,结尾要写 spr:saveAs(spr.filename) |
| cel 局部坐标 | getPixel/putPixel 的坐标是 cel 局部的,画布全局坐标要先减去 cel.position |
一个最小示例(取自 tests/test_script.py):
local spr = app.activeSprite
print("size=" .. spr.width .. "x" .. spr.height)
🛡️ run 命令的 4 道安全边界
run_lua_script 是整个服务器里权限最大的工具,源码在多处为它划了边界:
- 输入校验:空脚本、不存在的
filename直接拒绝,不启动 Aseprite; - 路径穿越拦截:reject_traversal() 拒绝含
..路径段的用户输入,被create_canvas等专用工具引用,防止借文件名越权读写其他目录; - 错误必须大声失败:batch 模式下 Lua 无法影响进程退出码,专用工具统一采用
ERROR:协议——脚本失败时打印ERROR:<message>,由 execute_lua_script_checked() 捕获并转成失败返回,杜绝"假成功"(对应 tests/test_error_propagation.py 的回归测试); - 无沙箱,仅限可信脚本:工具文档明确警告——它在宿主机上执行不受限代码(包括
io/os模块访问),"Only pass scripts you trust"。其余 122 个工具都是参数化的固定命令,而run_lua_script把完整 Lua API 交到你手里,"只跑自己写的、或完全信任的脚本"是它唯一的前提。
✅ 安全使用逃生舱的检查清单
- [ ] 已确认没有专用工具能替代(
draw_rows、replace_color、compare_frames、view_sprite…) - [ ] 一段脚本尽量批量完成多步操作,减少 Aseprite 启动次数
- [ ] 关键结果都
print出来,用输出验证逻辑真的跑通了 - [ ] 有改动就在结尾
spr:saveAs(spr.filename) - [ ] 脚本是自己写的、或完全信任后才执行
- [ ] 跑完用
view_sprite、lint_sprite复检画面
📂 相关源码速查
| 文件 | 内容 |
|---|---|
| aseprite_mcp/tools/script.py | run_lua_script 工具定义与安全警告 |
| aseprite_mcp/core/commands.py | run_command / execute_lua_script / ERROR: 协议 |
| aseprite_mcp/core/lua.py | 各专用工具共享的 Lua 片段库 |
| tests/test_script.py | 逃生舱的端到端测试 |
| README.md | 18 类 123 个工具的完整清单 |
登录后查看全文
