Leo/Arcrun

Files

T

Leo cadcaef3b0 ci: generic scan-based deploy workflow for all Workers

Rewrites deploy.yml to auto-discover every wrangler.toml in the repo
(excluding node_modules and Pages projects) rather than hardcoding
each Worker. Adding a new Worker only requires the new directory —
no workflow changes.

- Two-tier fanout: tier1 = .component-builds/* (WASM rebuild +
  deploy in parallel), tier2 = orchestration Workers (cypher-executor,
  registry, builtins) that depend on tier1 via service bindings.
- Diff-aware on push: only changed Worker dirs deploy; changes under
  registry/components/{name}/ cascade to .component-builds/{name}/.
- workflow_dispatch inputs: force_all (deploy everything) and only
  (comma-separated allow-list).
- TinyGo 0.40.1 rebuilds WASM from registry/components/{name}/main.go
  so deployed binaries always match source.
- max-parallel: 5 to stay under Workers API rate limit.

Adds .claude/rules/05-deploy-convention.md documenting the
"new Worker = new dir + wrangler.toml" invariant.

Per .agents/specs/arcrun/credential-primitives-wasm Phase 6.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-04-20 17:42:14 +08:00

4.6 KiB

Raw Blame History

部署慣例(CI/CD)

核心原則:新增 Worker = 新目錄 + wrangler.toml,不用改 workflow。

.github/workflows/deploy.yml 是通用掃描式 workflow,不該為每個 Worker 手寫 job。

Workflow 如何找到要部署的 Worker?

find . -name 'wrangler.toml' -not -path '*/node_modules/*' -not -name 'wrangler.test.toml'

每一個命中的目錄 = 一個部署單位。無論是:

cypher-executor/ (orchestration Worker)
registry/ (合約管理 Worker)
.component-builds/{name}/ (零件 Worker,25+ 個)
未來新增的任何 Worker

無需改 workflow,只要符合掃描規則就會自動部署。

觸發邏輯

觸發	部署範圍
`push` 到 main	diff 涉及的 Worker 目錄才部署
`push` 到 main + 改 `registry/components/{name}/`	連動 rebuild `.component-builds/{name}/component.wasm` 再 deploy
`workflow_dispatch` + `force_all=true`	全部 Worker
`workflow_dispatch` + `only=a,b,c`	只部署指定清單
`push` 但 base sha 不可及(首次)	全部 Worker

新增 Worker 的步驟

如果是新 WASM 零件 Worker

在 registry/components/{new_name}/ 建 main.go + component.contract.yaml
在 .component-builds/{new_name}/ 建 Worker 模板:
- wrangler.toml(name/routes/bindings)
- package.json(hono + workers-types + wrangler 即可,參考 auth_static_key/package.json)
- tsconfig.json(可直接複製)
- src/index.ts(WASI shim,方案 A:import ../../cypher-executor/src/lib/wasi-shim)
本地跑 pnpm install 產 pnpm-lock.yaml
本地跑 tinygo build -target=wasi -o {new_name}.wasm main.go 先驗證 build 通過
Commit push → CI 自動 rebuild WASM + deploy

如果是新 orchestration/service Worker

在 repo 根建新目錄(類似 cypher-executor/)
wrangler.toml + package.json + pnpm-lock.yaml + src/index.ts + tsconfig.json
Push → CI 自動部署

Runtime Secret 管理

CI 只提供 Cloudflare 驗證,不碰 runtime secret。

GH Actions secrets:CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID(一次性設好)
Runtime secret(例:ENCRYPTION_KEY、OPENAI_KEY、GOOGLE_API_KEY):
- 由 richblack 一次性手動 wrangler secret put <KEY> 設進各 Worker
- 不進 CI,不進 wrangler.toml [vars]
- 需要的 Worker:auth_static_key、auth_service_account(兩個都要 ENCRYPTION_KEY)

Lockfile 規範

統一使用 pnpm。新增 Worker 只放 pnpm-lock.yaml,不要 package-lock.json
若新建 Worker 時用 npm install 產出 package-lock.json,刪掉它,改跑 pnpm install
cypher-executor/ 和 registry/ 的 package-lock.json 已於 2026-04-20 刪除

現存例外(歷史遺產,混合期不強制遷移):

.component-builds/{if_control, switch, ... 16 個舊邏輯零件}/ 仍是 package-lock.json,workflow 有 fallback 分支(pnpm install --no-frozen-lockfile)可跑
builtins/、landing/ 同上

新增 Worker 一律 pnpm,不要製造新的混合情況。

WASM 來源

.component-builds/{name}/component.wasm 不 commit 進 repo(build 產物)。

本地開發:cd registry/components/{name} && tinygo build -target=wasi -o {name}.wasm main.go && cp {name}.wasm ../../../.component-builds/{name}/component.wasm
CI:workflow 在 deploy 前自動 rebuild + copy

例外:Phase 1-3 開發期為了加速驗證,部分 WASM 檔暫時 commit 進了 repo。之後會加 .gitignore 清理。

並行度

max-parallel: 5 — 避免觸發 Cloudflare Workers API rate limit。

Worker 數量 > 5 時,deploy 會分批跑。25 個 Worker 大約 5 輪 × ~30 秒 = 2-3 分鐘可完成全部。

禁止事項

禁止為新 Worker 手動加 deploy job 到 deploy.yml。通用掃描會自動處理,手加就是重複工作。
禁止把 runtime secret(API key / encryption key / credential)放進 GH Actions secrets 或 wrangler.toml [vars],只能用 wrangler secret put。
禁止在 CI 裡跑不必要的測試阻擋 deploy。測試在 PR / 本地跑,main 推上去就 deploy(trunk-based)。若要測試關,開新 workflow 檔,不要污染 deploy workflow。
禁止跳過 TinyGo rebuild 直接 deploy 舊 .wasm。CI 的 rebuild 步驟是確保部署的是最新 source。

驗證指令

本地模擬 CI 的掃描結果:

find . -name 'wrangler.toml' -not -path '*/node_modules/*' -not -name 'wrangler.test.toml' \
  | xargs -n1 dirname | sort -u

應列出 ~25 個目錄。任何「我新增了 Worker 但沒被 deploy」的問題,先跑這條確認目錄被掃到。

4.6 KiB Raw Blame History Unescape Escape