乐趣国学 · 微信小程序（国学成语挑战）

版本管理（broth）

itch 通过名为 broth 的系统自动管理 butler 与 itch-setup 的版本。broth 是官方运行的服务，它代理 itch.io API，为 itch 应用相关的二进制与资源提供固定的下载地址。

• 远程分发：二进制托管在 https://broth.itch.zone/{package}/{platform}/{version}，平台格式为 {os}-{arch}，例如 linux-amd64、darwin-arm64、windows-386。
• 本地存储：以 Linux 的 ~/.config/itch/broth/ 为例，目录下按包名分目录，包含 versions/{version-hash}/（解压后的二进制）、downloads/（下载临时目录）与 .chosen-version（当前激活版本）。
• 版本选择：使用 src/main/broth/formulas.ts 中定义的 semver 约束——butler 为 ^15.20.0，itch-setup 为 ^1.8.0；拉取 /versions 端点后挑选满足约束的最新版本。Canary 构建使用 -head 通道且不设约束（始终取最新）。
• 升级流程：启动时校验 .chosen-version 与已安装标记；若应用版本自上次运行后发生变化，则检查组件新版本；随后下载 zip、带 CRC32 校验地解压、执行 sanity check，最后更新 .chosen-version 并清理旧版本。
• 开发覆盖：可用 BROTH_USE_LOCAL=butler npm start 让应用使用本地构建的 butler，而非受管版本。

关键源码文件为 src/main/broth/package.ts、src/main/broth/formulas.ts、src/main/broth/manager.ts。

butlerd 绑定

itch 与 butler 之间通过名为 butlerd 的 JSON-RPC 2.0 协议通信。所有 RPC 请求、通知与数据类型的 TypeScript 类型定义位于 src/common/butlerd/messages.ts，该文件由 butler 仓库中的 Go 类型定义经 generous 工具自动生成。

生成代码依赖 @itchio/butlerd npm 包，它提供与 butler 守护进程通信的运行时（启动进程、TCP 连接、收发 JSON-RPC 消息）。若 butler 的 API 发生变化，可在将 butler 仓库检出为同级目录（../butler）后运行 npm run sync-butler 重新生成绑定；该命令以 ts 模式运行 generous 工具，解析 Go 结构体及其注释标注（如 @name、@category、@caller），产出 TypeScript 接口、枚举与请求/通知辅助函数。生成的 messages.ts 应提交到本仓库。butlerd API 文档见 https://docs.itch.zone/butlerd/master/。

开发快速开始

README 给出的开发命令如下：

# 安装依赖
npm install

# 以开发模式启动应用（监听变化并重新构建）
npm start

# 类型检查
npm run ts-check

# 构建资源
npm run compile

# 使用本地/开发版 butler 而非内置版本
BROTH_USE_LOCAL=butler npm start

itch 与 kitch 两种变体

代码库支持两个应用变体：itch（稳定版）与 kitch（canary 版）。二者可并排安装，通过构建时使用的 git tag 区分——以 -canary 结尾的 tag（如 v0.1.2-canary）产出 kitch，其余产出 itch。用 npm start 启动的开发版会以 kitch 模式运行。

• 构建时：release/common.js 检查 git tag，-canary 后缀选择 kitch，否则为 itch。package.json 的 name 字段默认为 "kitch"，因此本地开发始终以 kitch 运行；生产打包时，非 canary 构建会把名称覆写为 "itch"。
• 运行时：src/main/env.ts 调用 app.getName()（返回 package.json 中的 name）来设置 env.isCanary、env.appName 与 env.channel。

两者的主要差异包括：URL 协议（itch 为 itchio://、itch://（仅生产），kitch 为 kitchio://、kitch://）、broth 通道（kitch 带 -head 后缀）、semver 约束（kitch 无约束，始终最新）、macOS bundle ID（io.itch.mac 与 io.kitch.mac）、托盘/窗口图标路径，以及二进制/产物名称。

集成测试

项目包含使用 ChromeDriver 控制 Electron 应用的集成测试，覆盖登录、安装游戏、UI 导航等用户流程。运行要求包括：Go（测试运行器用 Go 编写，需先编译）、桌面环境（Linux CI 上使用 xvfb）、以及来自特定测试账号的 itch.io API key。

集成测试会下载与 Electron 版本匹配的特定 ChromeDriver 版本；若更新 package.json 中的 Electron 版本，必须同步更新 integration-tests/versions.go 中的 electronVersion 与 chromeDriverVersionString。正确 Chrome 版本可查阅 Electron Releases 页面。

# 设置测试账号（itch-test-account）的 API key
export ITCH_TEST_ACCOUNT_API_KEY="your-api-key"

# 针对打包构建运行集成测试
npm run integration-tests

# 针对开发版运行（迭代更快，无需打包）
node release/test.js --test-dev

# 全新运行（清除缓存的 chromedriver 与测试产物）
rm -rf integration-tests/.chromedriver integration-tests/tmp integration-tests/screenshots
node release/test.js --test-dev

许可证与相关项目

itch 以 MIT 许可证发布，详见仓库中的 LICENSE 文件。README 末尾还列出了社区其他应用，例如 Android 平台的 Mitch。