blue-mink/moo/fpk-build-to-moo

从构建 FPK 到发布「Moo 应用源」 — 全链路 Skill

全流程：构建 FPK → 本地/测试机验证 → 写索引 → 放仓库 → 自测 → 添加为源 → 详情页验收 → 版本迭代。

整合来源：Moo 应用源协议（docs/Moo应用源协议.md）+ 仓库内两个生成器

（tools/gen-moo-json、tools/gen-repo-moo-json.py）+ Moo 仓库自身被当作应用源的完整实战。

深层构建规范（完整字段表 / 环境变量 / 生命周期）见姊妹技能 `fn-fpk-builder`；

发布到 FnDepot 开源商店请用姊妹技能 fpk-build-to-fndepot。

一、全链路总览

① 构建 FPK（源码 → 包）              → references/fpk-build.md
        ↓  判据：产出 *.fpk、manifest/ICON 齐（全槽位 ≥512）、记下 sha256
② 本地/测试机验证（装一次、启一次）    → references/fpk-build.md §七
        ↓  判据：能装能启、功能可用、版本号与 manifest 一致
③ 写 moo.json（手写 / 生成器一键生成） → 本文件 §2
        ↓  判据：json 合法、download_url + sha256 齐、单位正确、分类取自固定清单
④ 放到仓库（仓库根或任意 HTTP 路径）   → references/publish-workflow.md §4
        ↓  判据：curl -sI 链接 = 200，图标（≥512）/预览/README/包都能匿名取到
⑤ 自测：链接粘到 Moo 首页搜索框        → 本文件 §3
        ↓  判据：能即时列出该源应用且展示名/版本/图标（≥512）正确
⑥ 添加为源 + 详情页验收               → 本文件 §3
        ↓  判据：体积/校验和/预览/README/更新日志/分类/运行方式都对，且真装一次成功
⑦ 版本迭代与发布卫生                  → references/publish-workflow.md §7 + 本文件 §七

按需阅读（路由）

二、生成 moo.json

2.1 从 FPK 目录生成（最常用）

cd moo && go run ./tools/gen-moo-json \
  -dir /path/to/fpk-store \                 # 递归扫描 *.fpk
  -name "我的应用仓" -distributor "MyOrg" \
  -base-url "https://example.com/apps" \    # download_url 前缀（省略则写相对路径）
  -out moo.json

自动完成：读 FPK 内 manifest（appname / version / display_name / desc / author / platform / service_port…） → 算 sha256 与字节体积 → FPK 旁有 ICON.PNG 自动带 icon_url → 同名应用按版本比较只留最高版。

2.2 从仓库 releases 生成（「以 release 发布 FPK」的仓库）

python3 tools/gen-repo-moo-json.py \
  --repo https://gitea.example.com/owner/repo --user <user> --password <token> \
  --app myapp --name "我的应用" --distributor "MyOrg" \
  --labels "系统工具" --install-type root \
  --preview "docs/shot-1.png,docs/shot-2.png" \
  --readme-file "README.md" --icon-file "icons/demo.png" \
  --out moo.json

遍历全部 release：生成器当前每个 release 取一个 FPK（默认按 x86）写 packages.x86（直链 + sha256 + 字节体积 + 发布时间）， 自动汇总真实下载数与最早发布时间；--preview/--readme-file/--icon-file 传仓库内相对路径会自动转 raw 链接。 同一版本同时有 x86+arm 两个包时，用 §2.4 的 update_moo_json.py --fpk a_x86.fpk a_arm.fpk 合并成 packages.x86 / packages.arm； 不要手工只补一个架构。

2.3 手写最小可用

{
  "schema_version": "moo",                     // 固定写 "moo"
  "source_info": { "name": "我的应用仓" },
  "apps": {
    "myapp": {                                 // key = appname，必须与包内 manifest 一致
      "display_name": "我的应用",
      "version": "1.0.0",
      "download_url": "https://example.com/myapp-1.0.0.fpk",
      "sha256": "<64 位十六进制>",
      "size": 3.2,                              // 条目级体积：MB
      "categories": ["实用效率"],                // 分类只能取协议清单里的值
      "desc": "一句话简介。"
    }
  }
}

2.4 已有索引的一键维护（持续发版推荐）

仓库里已经有 moo.json 时别重跑生成器——用零依赖脚本增量更新，只动目标应用的 releases 节点与顶层跟版字段，其余应用逐字节不变：

# 独立安装：脚本随 bundled/tools/ 一起装好；仓库内用 tools/update_moo_json.py
UPD="bundled/tools/update_moo_json.py"    # 仓库内改为 tools/update_moo_json.py
# 单架构 x86
python3 "$UPD" --version 1.2.3 --fpk dist/myapp_1.2.3_x86.fpk --repo OWNER/REPO
# 双架构：一次传两个包，分别写 packages.x86 / packages.arm
python3 "$UPD" --version 1.2.3 \
  --fpk dist/myapp_1.2.3_x86.fpk dist/myapp_1.2.3_arm.fpk --repo OWNER/REPO
python3 "$UPD" --check --version 1.2.3 \
  --fpk dist/myapp_1.2.3_x86.fpk dist/myapp_1.2.3_arm.fpk --repo OWNER/REPO
# 没有随技能副本时才回退到远程 raw（不推荐；版本不可控）
# curl -fsSL https://raw.githubusercontent.com/Blue-Mink/moo/main/tools/update_moo_json.py -o /tmp/update_moo_json.py

• 版本 / appname / 平台默认从包内 manifest 读，--version 与包内不一致时脚本直接拒绝；
• --fpk 可一次传多个包（x86+arm）：按各自 manifest 分别写 packages.x86 / packages.arm；只传一个就只写一个架构，不要手工补另一个；
• 新架构会增补到应用级 platform（默认；--no-platform-sync 可关），否则 arm 客户端可能仍按旧架构过滤；
• 多应用索引必须能定位目标条目（包内 appname 或 --appname），脚本不会猜；
• --tag 处理非规范 tag（如 release-1.2.3）；--keep 控制保留版本数（默认 2）；
• 同版本换包默认拒绝（防已缓存用户校验失败），确需覆盖加 --allow-republish；
• 想让它跟着 Release 自动跑：把 templates/moo-autoupdate.yml 放进自己仓库的 .github/workflows/；
• 三种接入方式与排错表见 `templates/MOO_JSON_MAINTENANCE.md`。

2.5 图标：FPK 全槽位 + moo.json 商店索引（2026-11-02）

飞牛取图标有三条独立通道，任一通道拿到 64 小图就会糊：

1. 桌面 / 列表：ui/images 下的槽位图（serviceicon，?size=N）；
2. 详情弹窗：FPK 根目录 ICON.PNG；
3. 商店卡片：moo.json 的 icon_url 指向仓库树内的 <app>/ICON.PNG，与装机图标是两套独立文件。

做法（完整口径见姊妹技能 fn-fpk-builder 的 references/official-contract.md「图标清晰度」）：

• 做一张 ≥512 母版，原样铺满 FPK 的全部实际槽位，不要按 64/256 分别降采样：
• ui/config 用 images/icon_{0}.png 的项目：ui/images/icon_0.png / icon_64.png / icon_128.png / icon_256.png / icon_512.png + 根 ICON.PNG / ICON_256.PNG；
• ui/config 用 images/ICON.PNG 的项目（如 Moo）：ui/images/ICON.PNG / ICON_64.PNG / ICON_256.PNG + 根 ICON.PNG / ICON_256.PNG；不要额外造 5 个小写槽位。
• 商店索引：moo.json 的 icon_url 路径不用改；但 icon_url 指向的仓库树内 ICON.PNG 与同目录 ICON_256.PNG（如有）都要换成同一张 ≥512。只改 FPK、不改树内文件 → 商店卡片仍糊。
• 验收：curl 取 icon_url 与 FPK 根图标，尺寸都 ≥512；装机后详情弹窗/桌面强刷（图标 URL 有 7 天 immutable 缓存）；源码 == 包内 == 设备，三处 md5 一致。

2.6 moo.json 字段速查（别只写最小子集）

最小示例只覆盖 display_name/version/download_url/sha256/size/categories/desc；实际还常用：

完整字段表、单位、示例与生成器能力边界见 references/moo-json-fields.md。

别把 FnDepot 的字段直接抄过来：Moo 是 14 类、条目 size=MB；FnDepot 是 9 类、packages.size=字节；Moo install_type 自适应，FnDepot 用 run_as+install_type；manifest.platform 两边都是字符串。

2.7 源级安装向导 wizard

moo.json 可以声明安装前向用户收集的参数：

"wizard": {
  "fields": [
    { "key": "SITE_TITLE", "label": "站点标题", "default": "我的博客", "required": true },
    { "key": "PORT", "label": "服务端口", "default": "8090" }
  ]
}

• 0.6.269+：Moo 安装前弹窗收集，值随安装请求下发给应用；键名由应用自己定义，不强制 wizard_ 前缀。
• 这是 Moo 源级 一层；FPK 里的 wizard/install 是平台级另一层。两层可能同时存在，键名/合并顺序/优先级由应用安装逻辑处理；发布前用 Moo 客户端真装一次抓请求确认。
• required/default 只是客户端提示；安装回调/服务端必须再校验。
• gen-moo-json 目前不生成 wizard，需手写或由发布脚本合并。

三、自测与发布（别跳过第 4 步）

1. 搜索框自测：把 moo.json 链接粘到 Moo 首页搜索框 —— 不添加源也能即时列出该源全部应用；
2. 能列出 → 设置 → 应用源设置 → 添加应用源（粘同一链接）；
3. 打开该应用详情页逐项验收：

• 图标（≥512）、展示名、版本；
• 安装包大小与 SHA256（= 单位写对没）；
• 预览图（可点开、支持双指缩放）、README（默认约 10 行，可展开）；
• 更新日志（默认最近 3 条，可展开）、分类标签、运行方式/安装位置；

1. 真装一次（点「安装」）确认下载与校验通过。

3.5 安装 / 卸载 / 升级与装后四铁律

• 命令：appcenter-cli install-fpk <fpk> --volume <N> --env /tmp/<app>.env，必须 root；install-fpk 不是独立命令。
• appcenter-cli install-fpk 对已装应用是 no-op；换版走 停→卸→appcenter-cli check 确认没了→装→启，或 daemon /rpc/v1/update/task。
• start 报 10500 是“已在运行”，不是失败；uninstall 报 10150 是本地应用禁卸；常驻入口 checkport=false，否则停用后再启用报 11000。
• 安装回调约 190 秒看门狗：重活必须“秒回 + 后台 worker”。
• 装后四铁律：新 PID / 运行态二进制 sha == 包内 / 版本 + 前端 bundle 指纹 / 数据零回归（源数/卡数/已装数/禁用集合逐字一致）；冷启动前几秒偏低是瞬态。
• 旧版/失败回滚：保留上一版 FPK + @appdata 备份；失败时 stop→uninstall→装上一版→start。
• 向导、数据删除边界、config/upgrade 与更多错误码见 references/wizard-lifecycle.md。

四、核心坑点速览

五、版本与更新判定（会被坑的地方）

Moo 比较版本：去前导 v → 拆「数字前缀 + 后缀」→ 数字逐段数值比较 → 相同再比后缀（非空 > 空）。

一条线路一个 moo.json：稳定版与测试版别混在同一份索引里，否则会把测试版当"最新"。

5.5 发布 / 自更新 / 签名（摘要）

• 自更新应用每架构三件套：FPK + .sha256 + .minisig；缺一 fail-closed；老客户端缺 .sha256 会永远升不上来。
• 签名私钥离线，公钥 go:embed；CI 只构建/上传，签名只在发布机。
• 资产矩阵：Moo 7 件（6 手工 + CI 二进制），Mate 6 件；tag vX.Y.Z / mate-vX.Y.Z；release 必须 public。
• 索引永远晚于 release；moo.json 的 releases 只留最近 2 版；同版本不替换包。
• 兜底通道每条都要同时给 FPK + .sha256 + .minisig 三个 URL；国内 API 限流时几乎恒走兜底。
• 完整清单见 references/self-update-signing.md。

六、命令速查

6.5 Moo / Moo Mate 实战差异