Cherri 编译器揭秘:从 .cherri 源码到签名 .shortcut 的 Go 单文件编译流水线

原创2026-10-11 17:50:411,967 阅读

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:

  1. 包管理:如果目录下有 info.plist,加载包信息并安装远程 Git 仓库依赖包(内置的 Go-based 包管理器,源码见 packages.go)
  2. #include 内联:includes.go 中的 parseIncludes() 递归地查找 #include 'path/to/file.cherri',把被引用文件的内容直接拼进源码——如果拼了新内容就重新扫描一遍,直到没有新文件被引入。这也是标准库的工作方式:actions/ 目录下 26 个 .cherri 分类文件(network、device、math、web…)通过 action.go 的 go:embed 内嵌进二进制
  3. 函数头注入:functions.go 收集所有 function 定义后,在源码顶部注入一段自动生成的分发头。函数调用会被编译为 runSelf(字典) 自调用动作,由头部负责按名字分发、类型转换参数——这是用纯 Shortcut 机制模拟作用域的巧妙设计
  4. #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:

  1. 写出未签名文件:workflowName_unsigned.shortcut(plist XML 格式)
  2. 签名:signing.go 的策略是"本地优先、远程兜底"——
    • 在 macOS 上直接调用系统命令 shortcuts sign -i ... -o ... -m contacts
    • 非 macOS 系统或签名失败时,自动回退到 RoutineHub 的 HubSign 远程签名服务
    • 也可以用 --signing-server= 指定任意兼容的签名服务器,--share=anyone 控制共享范围
  3. 清理与打开:签名成功后删除未签名中间文件;加 --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 程序实现了经典编译器的完整形态:

  1. 读取 → 字符光标模型(handleFile)
  2. 预处理 → include 内联 + 函数头注入(preParse)
  3. 分析 → 逐字符 token 流(parse,token 定义在 token.go)
  4. 代码生成 → token 到 WF 动作的翻译(shortcutgen.go)
  5. 序列化 → plist XML(output.go)
  6. 签名 → macOS 本地 / 远程服务兜底(signing.go)

如果你想亲手跑一遍,仓库地址:git clone https://gitcode.com/gh_mirrors/ch/cherri,然后 go run . tests/hello-world.cherri --debug 就能看到完整的流水线输出。对于想长期维护大型 Shortcuts 项目的人,这门"编译到 Shortcuts"的语言值得一试 🍒

登录后查看全文
cherri