Leo/Arcrun
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fb2d0b0c2d0520d5457b7ad3acfbbcc99f44de5c
Arcrun/.claude/rules/05-deploy-convention.md
T
Leo fb2d0b0c2d feat(self-hosted): acr init --self-hosted installer + recipe push 把關 + commit 部署 wasm 
讓任何 CC 用自己的 CF 帳號一鍵 self-host arcrun（戰法轉 self-hosted 開源）。

Task 1 — acr init --self-hosted installer（用戶只給 CF Account ID + token，其餘自動）：
- cli/src/lib/cf-api.ts: CfAccountClient（驗 token / 建 KV 冪等 / 建 R2 / 查 workers.dev subdomain）
- cli/src/lib/deploy.ts: 從 GitHub codeload tarball 拉部署物 → 注入用戶 KV id → wrangler deploy
  （tier1 component-builds 先、tier2 cypher-executor/registry 後；部分失敗誠實回報不假綠）
- cli/src/lib/api-recipe-seeds.ts: 10 個現役 API recipe 種子（KBDB 採 Supabase 模式）
- cli/src/commands/init.ts: initSelfHosted() 改寫成 installer 流程
- cli/src/commands/update.ts: acr update（拉新 ref 重部署）
- cypher-executor/scripts/seed-api-recipes.ts: prod 補灌腳本

Task 2 — recipe 入庫把關（封鎖自製零件後，CC 唯一能擴充的是 recipe）：
- cli/src/commands/recipe.ts: 新增 probeRecipeEndpoint 打通檢查（提醒級不硬擋，
  含模板誠實說明待 run 才知，401/403 標多半缺 credential 非 bug）
- 資料外流提醒沿用既有 obtainExposureConsent（非 TTY 拒絕）

部署物產製：commit 預編譯 wasm 進 repo（推翻 rule 05「wasm 不 commit」）：
- .gitignore: 放行 .component-builds/**/component.wasm（registry 中間產物仍排除）
- 只 commit 19 個正當零件 wasm；claude_api / km_writer / kbdb_upsert_block 排除
  （非薄殼、是把工作流硬塞進零件，違反 DECISIONS §1，待降級）
- rule 05 同步記錄此慣例變更 + 膨脹 trade-off

SDD: sdk-and-website/self-hosted-init.md（installer 定案）、
     component-gatekeeping/recipe-push-gatekeeping.md（recipe 把關）
README 重寫成單一 self-hosted 路徑。CLI typecheck exit 0。

未完（待 richblack）：push 此 commit 到 GitHub 後 codeload 才拿得到 wasm；
用第二 CF 帳號端對端驗收 acr init --self-hosted。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-02 18:44:41 +08:00

5.8 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

  1. 在 registry/components/{new_name}/ 建 main.go + component.contract.yaml
  2. 在 .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)
  3. 本地跑 pnpm install 產 pnpm-lock.yaml
  4. 本地跑 tinygo build -target=wasi -o {new_name}.wasm main.go 先驗證 build 通過
  5. Commit push → CI 自動 rebuild WASM + deploy

如果是新 orchestration/service Worker

  1. 在 repo 根建新目錄(類似 cypher-executor/)
  2. wrangler.toml + package.json + pnpm-lock.yaml + src/index.ts + tsconfig.json
  3. 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 來源

⚠️ 慣例變更（richblack 2026-06-02，self-hosted 開源策略）： 原慣例「.component-builds/{name}/component.wasm 不 commit 進 repo」已推翻。 現在 commit .component-builds/*/component.wasm 進 repo，因為 self-host 用戶 / acr init --self-hosted 從 GitHub（codeload tarball）直接拿這份 wasm 部署到自己的 CF——repo 必須自帶可部署的 wasm。 決策依據：.agents/specs/arcrun/sdk-and-website/self-hosted-init.md §6。

現行規則（2026-06-02 起）

  • .component-builds/*/component.wasm → commit 進 repo（部署來源）。.gitignore 用否定規則放行： 
    *.wasm                                   # 預設排除
!.component-builds/**/component.wasm      # 例外放行部署物
  • registry/components/*.wasm → 仍不 commit（build 中間產物，部署不直接用，.gitignore 仍排除）。
  • 本地開發 build：cd registry/components/{name} && tinygo build -target=wasi -o {name}.wasm main.go && cp {name}.wasm ../../../.component-builds/{name}/component.wasm，然後 commit .component-builds/{name}/component.wasm。
  • CI（deploy.yml）：仍在 deploy 前自動 rebuild + copy（部署 prod 用最新 source；與 repo 內 commit 的 wasm 不衝突——前者給 CI deploy prod，後者給 self-host 用戶當部署來源）。

誠實 trade-off（mindset §7）

commit wasm 進 repo → 每次 rebuild 在 git 歷史累積二進位，repo 長期會膨脹。 可接受（self-host 體驗優先），未來若膨脹過劇再考慮 git-lfs / 按需安裝（self-hosted-init.md §6.6）。

並行度

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

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

禁止事項

  1. 禁止為新 Worker 手動加 deploy job 到 deploy.yml。通用掃描會自動處理,手加就是重複工作。
  2. 禁止把 runtime secret(API key / encryption key / credential)放進 GH Actions secrets 或 wrangler.toml [vars],只能用 wrangler secret put。
  3. 禁止在 CI 裡跑不必要的測試阻擋 deploy。測試在 PR / 本地跑,main 推上去就 deploy(trunk-based)。若要測試關,開新 workflow 檔,不要污染 deploy workflow。
  4. 禁止跳過 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」的問題,先跑這條確認目錄被掃到。

Reference in New Issue View Git Blame Copy Permalink