@chatablex/chatablex-app

npm 分发壳：默认内置 Linux x64 Flutter bundle（已嵌入 PyInstaller 后端）的 ChatableX.zip，以及 release-manifest.json（含可选 bundles 列表）。可选同一套编排产出 Windows（ChatableX-windows.zip）、macOS（ChatableX-macos.zip）。

编排逻辑见 PRD：docs/prd/platform/prd-orchestrated-npm-release-202605.md（在 monorepo 根目录时路径为 ../../docs/...）。

本仓库在 GitHub 上需要单独存在

GitHub Actions 只读取仓库根目录下的 .github/workflows/。本目录若仍躺在父 monorepo 里，请把 chatablex-app/ 推成独立远端仓库（或 subtree split），否则这些 workflow 不会在父仓库生效。

配置（GitHub → Settings）

Repository variables

格式：只填 GitHub 的 owner/repo（也叫 组织或用户名/仓库名），不要写完整 URL；保存 Variable 时勿带行尾回车（\r/换行），否则 gh 会报 URL 非法——workflow 与脚本已做 strip，仍建议你在网页里删掉多余换行。

• 正确：chatablex/chatablex-local-service
• 错误：https://github.com/chatablex/chatablex-local-service（gh --repo 与脚本里的 API 都不吃这种写法）

| Name | 示例 | 说明 | |------|------|------| | CHATABLEX_REPO_LOCAL_SERVICE | myorg/chatablex-local-service | 后端仓库 owner/name | | CHATABLEX_REPO_DESKTOP | myorg/chatablex-desktop-app | Flutter 桌面仓库 owner/name | | CHATABLEX_ORCH_PLATFORMS | linux 或 linux,windows,macos | 可选。不设或空则只打 Linux。若要顺带打 Win/mac，必须仍包含 linux，否则本站 Release orchestrate 会在配置检查阶段失败（npm publish 依赖 ChatableX.zip）。全平台会拉长 CI；npm publish 仍只含 ChatableX.zip，Win/mac zip 仅在工作区生成。 |

两仓需在 同一 v* tag 上可 workflow_dispatch：每个上游仓库里都必须已有该 tag，否则会报 HTTP 422: No ref found。

自动在两上游打同名 tag（在 两上游各自指定分支的当前 HEAD 上创建，再 workflow_dispatch）：

1. CHATABLEX_DISPATCH_TOKEN（PAT） 对两上游仓至少 Contents: Read（解析分支/commit），自动建 tag 还须 Contents: Write；否则 commits/refs 或创建 tag 会 403。
2. 推 v* tag 触发编排时，默认会 ORCH_CREATE_UPSTREAM_TAGS=true（只推 chatablex-app 的 tag 也会去两上游建同名 tag）。若不要此行为，在本仓库 Variables 设 ORCH_CREATE_UPSTREAM_TAGS = false。
3. 手动 Run workflow：默认 不 自动打 tag；需勾选 create_upstream_tags，或设 Variable 为 true。
4. 可选 CHATABLEX_UPSTREAM_BRANCH：两仓都用同一条分支名时填写（如 main）。不设或某仓没有该分支时，每个仓库各自用 GitHub 上的 default_branch（可能一个是 master、一个是 main）。

注意：自动打的是 当时各仓该分支 HEAD；两仓未对齐则不是「同一份代码」。固定 commit 请仍在各仓手动打 tag。

Secrets

| Name | 说明 | |------|------| | CHATABLEX_DISPATCH_TOKEN | 跨仓触发/下载用的 GitHub PAT；可放在 Actions Secret 或 Actions Variable（workflow 里 Secret 优先，未配置 Secret 则用 Variable）。敏感值建议用 Secret。说明见下节 | | NPM_TOKEN | 可选。未配置时由 npm Trusted Publishing（OIDC） 发 npmjs（见下节）。若仍用 token 发 npmjs，填 Secret 或 Variable |

npm Trusted Publishing（推荐，免长期 NPM_TOKEN）

前提：使用 GitHub 托管的 ubuntu-latest（本 workflow 已满足）；npm 要求 Node ≥ 22.14、npm CLI ≥ 11.5.1（workflow 里已用 setup-node + 全局升级 npm）。

1. （仅首次） 若 registry 上还没有 @chatablex/chatablex-app：可先临时配置 NPM_TOKEN（Automation 类 granular token 等）成功发版一次，或由 npm 组织管理员按你们流程创建包。
2. 打开 npm 上该包 → Package settings → Trusted publishing → 选 GitHub Actions，填写与本仓库 完全一致 的 owner/repo，Workflow filename 填 release-orchestrate.yml（仅文件名，区分大小写）。
3. 在本 GitHub 仓库 删除 NPM_TOKEN Secret/Variable（或留空），合并已带 id-token: write 的 workflow 后重新跑发版。CI 会在发布前写入 package.json 的 repository，使其与 github.repository 一致（npm 校验用）。

若 npm publish 报 EOTP / requires a one-time password（且你仍打算用 token 而非 OIDC）：说明当前 token 或账号策略在发布时仍要求 2FA。请到 npm Access Tokens 新建 Granular Access Token，Token type 选 Automation（供 CI 使用，发布时不必传 --otp），并对 @chatablex 等有 Write 权限；把该 token 写入 NPM_TOKEN。不要用仅适合本机交互发布的 Publish 类 token 跑 Actions。

嵌入用的 backend/.env 不再在本仓库配置：由 chatablex-local-service 的 Release workflow 上传 artifact chatablex-local-service-embed-env（见该仓 README「Release 与 npm 编排」）。编排脚本会随 Linux 二进制一起下载该文件。

CHATABLEX_DISPATCH_TOKEN 是什么？从哪里来？

这是你自己在 GitHub 上 生成的一个 Token（常见做法是 Personal Access Token，PAT），复制后只出现一次 → 贴到本仓库 Settings → Secrets and variables → Actions → New repository secret，名字填 CHATABLEX_DISPATCH_TOKEN。

为什么要单独一个 token？
编排机里的默认 GITHUB_TOKEN 不能随便对别的仓库执行 workflow_dispatch、下载对方 Actions 产物。脚本里用的是 GH_TOKEN=${{ secrets.CHATABLEX_DISPATCH_TOKEN }}，所以需要一枚 能访问两个上游仓 的凭证。

在哪里创建？

1. 用你的 GitHub 账号登录（建议用 机器人账号 或专职发版账号，不要用个人主号长期挂高权限 token）。
2. Classic PAT：头像 → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token。
   至少勾选与两上游仓相关的：repo（私有仓必需；若两仓都是 public，有时仍要给 repo 才能稳定 dispatch/下 artifact，以实测为准），并勾选 workflow（触发 workflow）、read:actions 或等价 Actions 读权限（下载 artifact）。
3. Fine-grained PAT：创建时 Resource owner 选组织/用户，Repository access 勾选那 两个上游仓库。权限建议：
   • Contents: Read and write — Read 用于解析分支 HEAD（commits/refs API）、读仓库；Write 用于 ORCH_CREATE_UPSTREAM_TAGS 在上游自动创建 tag。仅 Metadata 会导致 GET .../commits/... 报 403「Resource not accessible by personal access token」。
   • Actions: Read and write — 触发 workflow_dispatch、轮询 run、下载 artifact（与当前 GitHub UI 一致即可）。

生成后 立刻复制 存入本仓库 Secret；不要写进代码、不要发聊天明文长期留存。

若以后改用 GitHub App 安装到组织、由 workflow 换 installation token，也可以替代 PAT；当前脚本按 PAT → Secret 即可工作。

Workflow 权限

本 workflow 已声明 id-token: write（npm Trusted Publishing / OIDC）。

触发方式

• 推 tag：git tag v0.2.0 && git push origin v0.2.0（本仓库）
• 手动：Actions → Release orchestrate (npm) → Run workflow → 输入 tag

本地只跑嵌入 / 打包（不调上游）

准备好：

1. 后端 Linux 二进制（与 CI artifact 同名布局即可）
2. Flutter build/linux/x64/release/bundle 目录树
3. 一份 .env（与 chatablex-local-service 里用于 prod 的一致）

将目录摆成「仿 chatablex-desktop-app 根目录」后：

./scripts/embed_backend.sh --platform linux \
  --backend-bin /path/to/chatablex-local-service \
  --desktop-build-tree /path/to/fake-desktop-root \
  --env-file /path/to/.env

再在 build/linux/x64/release 下 zip -qr ../../ChatableX.zip bundle。

Windows / macOS 嵌入（本地、与 CI 同源布局）：embed_backend.sh 已支持 --platform windows|macos；Windows 期望 build/windows/x64/runner/Release，macOS 期望 build/macos/Build/Products/{Release,...}/ChatableX.app。

编排脚本（scripts/）

| 脚本 | 说明 | |------|------| | orchestrate_release.sh | 主入口；读 CHATABLEX_ORCH_PLATFORMS（默认 linux） | | orchestrate_release_linux.sh | 等价 CHATABLEX_ORCH_PLATFORMS=linux | | orchestrate_release_windows.sh | 仅 Windows | | orchestrate_release_macos.sh | 仅 macOS | | orchestrate_release_all.sh | linux,windows,macos 一次打完 | | embed_backend.sh | 仅嵌入，不调上游 |

上游 artifact 名（须与 chatablex-desktop-app / chatablex-local-service 的 CI 一致）：Flutter — chatablex-linux / chatablex-windows / chatablex-macos；后端 — chatablex-local-service-linux-x64 / chatablex-local-service-windows-x64 / chatablex-local-service-macos；embed 用 .env — chatablex-local-service-embed-env。