Cherri 编译器揭秘:从 .cherri 源码到签名 .shortcut 的 Go 单文件编译流水线
Cherri 编译器揭秘:从 .cherri 源码到签名 .shortcut 的 Go 单文件编译流水线
Cherri 编译器是什么?它是一个用 Go 编写的单文件编译器,能把类 Ruby/Go 语法的 .cherri 源码,一路编译成 Apple Shortcuts 可以直接运行的签名 .shortcut 文件——包括词法分析、预处理、动作生成、plist 序列化与 macOS 本地签名,全部内置在这一条 CLI 流水线里。这篇文章带你逐步拆解这条流水线的 6 个阶段,看看一行 cherri file.cherri 背后到底发生了什么。
为什么需要 Cherri 编译器?
手写 Shortcuts 的人都知道:几十个动作排下来,没有变量类型、没有模块化、没法复用,稍复杂的工作流就难维护了。Cherri 的思路是把 Shortcuts 当作"目标平台",提供一门真正的编程语言来编程它:
- 📦 单文件交付:整个编译器就是一个 Go 二进制,用 Homebrew 或 Nix 安装即可,go.mod 显示它甚至只依赖少量第三方库
- 🖥️ 桌面开发:CLI + VSCode 扩展 + macOS 应用,告别在手机上摆积木
- 📋 模块化:
#include可以把其他文件合并进编译,支撑大型 Shortcut 项目 - 🧪 类型检查:有完整的类型系统与类型推断,还能把函数编译为 Shortcut 内部的"自调用分发"
一句话:你写代码,Cherri 编译器替你摆好每一个 Shortcut 动作并签好名。
编译流水线全景图
在 main.go 中,编译一个文件的主流程清晰得令人惊讶,只有四步:
handleFile() → 读取 .cherri 源码
initParse() → 预处理 + 词法/语法分析(生成 token 流)
generateShortcut() → 把 token 流翻译成 Shortcut 动作(plist 数据)
createShortcut() → 序列化 plist → 签名 → 写出 .shortcut
而 AGENTS.md 给出的更详细的流水线图是:
.cherri 源码
↓ handleFile() — 读取文件,切分成行/字符
↓ initParse() — 初始化全局状态
↓ preParse() — 顺序预处理:
handleIncludes() — 内联 #include 文件
handleFunctions() — 收集函数定义,注入分发头
handleActionDefinitions() — 收集自定义 action 块
↓ parse() — 主分析:逐字符遍历,产出 tokens[]
↓ generateShortcut() — 遍历 tokens[],构建 WFWorkflowActions
↓ createShortcut() — 序列化 plist、签名、写出 .shortcut
下面逐阶段拆解。
阶段一:读取源码(handleFile)
入口在 main.go:命令行第一个参数只要包含 .cherri 就进入编译模式;checkFile() 会校验文件存在且扩展名正确,否则直接报错退出。
handleFile() 会把文件读入内存,拆成 lines(行数组)和 chars(rune 数组)——后面所有解析都在这两个数组上用字符光标进行,而不是逐字节流式读取。
阶段二:预处理(preParse)——把多文件变成单文件
这是流水线里最有意思的部分,parser.go 中的 preParse() 按固定顺序执行一系列"改写源码"的 pass:
- 包管理:如果目录下有
info.plist,加载包信息并安装远程 Git 仓库依赖包(内置的 Go-based 包管理器,源码见 packages.go) #include内联:includes.go 中的parseIncludes()递归地查找#include 'path/to/file.cherri',把被引用文件的内容直接拼进源码——如果拼了新内容就重新扫描一遍,直到没有新文件被引入。这也是标准库的工作方式:actions/ 目录下 26 个.cherri分类文件(network、device、math、web…)通过 action.go 的go:embed内嵌进二进制- 函数头注入:functions.go 收集所有
function定义后,在源码顶部注入一段自动生成的分发头。函数调用会被编译为runSelf(字典)自调用动作,由头部负责按名字分发、类型转换参数——这是用纯 Shortcut 机制模拟作用域的巧妙设计 #import、copy-paste、自定义 action 块的收集
每改写一次源码,都会调用 resetParse() 重建字符数组并清零 token 流,保证后续 pass 看到的一定是最新源码。
阶段三:词法与语法分析(parse)
真正的 token 化在 parser.go 的 initParse() 中完成:光标从第一个字符开始逐字推进,遇到关键字、字符串、运算符就发出 token。
token 的类型系统定义在 token.go 中,涵盖:
- 关键字:
const、if/endif、repeat、menu/item、#define、#include、#question、function等 - 数据类型:
text、number、float、bool、dictionary、array、date、nil… - 运算符:
= += -=、== != > >= < <=、contains、beginsWith、<>(区间)等
一个 hello world 示例(tests/hello-world.cherri):
#define color yellow
#define glyph smileyFace
#define name Hello, Cherri!
@message = "Hello, Cherri!"
alert(@message)
#define 声明的是 Shortcut 的名称、图标(glyph + 颜色)、输入输出类型等元数据;@变量 = 值 会被编译成"设置变量"动作;alert(@message) 则是一个带参数的标准动作调用。分析结束后,整个文件被压平成一维 tokens[] 数组,等待下一阶段消费。
阶段四:生成 Shortcut 动作(generateShortcut)
shortcutgen.go 是"后端代码生成器":它先构建 Shortcut 元数据(图标、输入/输出类型、触发器、导入问题),然后 generateActions() 遍历 token 流,按 token 类型分发到不同的动作构造器(shortcutgen.go):
| token 类型 | 生成的 Shortcut 动作 |
|---|---|
| 变量赋值/算术 | Set Variable / 计算 |
Action |
查 actions 映射表,构建标准动作参数 |
repeat / for |
Repeat / For Each |
menu / item |
Menu / Menu Item |
if 条件 |
If 条件组 |
其中字符串参数会经过 attachmentValues() 处理:"{@name}" 这种插值会被拆成 WFTextTokenString + 变量附件,精确还原 Shortcuts 原生 plist 结构——这正是它能被 Shortcuts 运行时直接执行的原因。所有 plist 结构体定义在 docs.go 之外的 Shortcut/WFActionReference 等类型中,由 howett.net/plist 库负责编码。
阶段五:序列化与签名(createShortcut)
最后一步在 output.go:
- 写出未签名文件:
workflowName_unsigned.shortcut(plist XML 格式) - 签名:signing.go 的策略是"本地优先、远程兜底"——
- 在 macOS 上直接调用系统命令
shortcuts sign -i ... -o ... -m contacts - 非 macOS 系统或签名失败时,自动回退到 RoutineHub 的 HubSign 远程签名服务
- 也可以用
--signing-server=指定任意兼容的签名服务器,--share=anyone控制共享范围
- 在 macOS 上直接调用系统命令
- 清理与打开:签名成功后删除未签名中间文件;加
--open会直接open打开结果
至此,.cherri 源码已变成 iPhone 上双击即可运行的 .shortcut。
关键 CLI 参数速查
编译时最实用的参数(完整注册见 args.go):
| 参数 | 作用 |
|---|---|
--debug / -d |
输出解析调试信息,并额外写出 .plist 和 _processed.cherri 预处理文件 |
--output= / -o |
指定自定义输出路径 |
--skip-sign |
跳过签名,只产出 _unsigned.shortcut |
--hubsign |
强制使用远程签名服务 |
--comments |
把源码注释也编译进 Shortcut |
--import= |
反向操作:把 iCloud 链接的 Shortcut 反编译为 Cherri |
--action=名称 |
查询内置动作的签名(raw_actions.go、search.go 提供搜索) |
调试技巧:--debug 写出的 _processed.cherri 能看到 include/函数注入后的真实源码,.plist 则可与 Shortcuts 官方生成的 plist 逐字段对比,是理解生成结构最快的方式。
彩蛋:它还能反向工作
这条流水线几乎是双向的:decompile.go 实现了 .plist → .cherri 的反编译器,用 cherri --import=链接 可以把现有 Shortcut(含 iCloud 分享链接)转换回 Cherri 源码继续维护。项目自带的 tests/ 目录有 40 余个 .cherri 测试文件,cherri_test.go 会把它们全部走一遍编译流水线,而 TestDecomp 则验证反编译结果的字节级一致性。
总结:一条极简但完整的编译流水线
回看全局,Cherri 编译器用单文件 Go 程序实现了经典编译器的完整形态:
- 读取 → 字符光标模型(
handleFile) - 预处理 → include 内联 + 函数头注入(
preParse) - 分析 → 逐字符 token 流(
parse,token 定义在 token.go) - 代码生成 → token 到 WF 动作的翻译(shortcutgen.go)
- 序列化 → plist XML(output.go)
- 签名 → macOS 本地 / 远程服务兜底(signing.go)
如果你想亲手跑一遍,仓库地址:git clone https://gitcode.com/gh_mirrors/ch/cherri,然后 go run . tests/hello-world.cherri --debug 就能看到完整的流水线输出。对于想长期维护大型 Shortcuts 项目的人,这门"编译到 Shortcuts"的语言值得一试 🍒