跳到主要內容

arc blocklet

arc blocklet 覆蓋 blocklet 包和例項的整個生命週期：腳手架、構建、檢查、列表、單個部署，或者整隊部署。

arc blocklet 覆蓋一個 blocklet 的整個生命週期：搭一個新包的腳手架、構建它、校驗它、部署它，單獨部署，或者作為一支艦隊的一部分。

對照版本：arc 2.0.0-beta.50（commit a99fb2c37，main，2026-09-11）。複製 dump 前先跑 arc --version；釘住命令面的是 commit。

bash
arc blocklet <subcommand> [options]

全域選項（見 總覽）：--json、--view、--instance / -i（作用在哪個本地 ARC 例項；省略即 default），以及 --home（例項根；要指定作用在哪個例項，用 --instance）。

腳手架

arc blocklet create

搭一個新 blocklet 包的腳手架。別名是 arc blocklet init（為了向後相容保留）。

用法

bash
arc blocklet create [dir] [options]
  • [dir]（可選，預設當前目錄）：blocklet 目錄
  • --name <name>：blocklet 名字（預設用目錄名）
  • --recipe <name>（別名 --template）：腳手架配方，basic、blank、blog、agent、minimal-app、agent-workspace、support-community 之一（預設 basic）

--name 必須能派生出合法的 blocklet 識別符號——建目錄之前就會檢查並拒絕：

bash
$ arc blocklet create bad-dir --name "Not A Valid Name!"
ERROR: Error: Cannot derive a blocklet DID from --name "Not A Valid Name!": a blocklet identifier allows alphanumeric, hyphen, underscore only. Pass a valid identifier instead, e.g. --name Not-A-Valid-Name.

不會建出 bad-dir 目錄。合法的名字正常起作用，並列印一條 Next: 提示指向下一步：

bash
$ arc blocklet create my-app --recipe basic
Created blocklet.yaml with did: "did:blocklet:my-app"
Next: arc blocklet build /path/to/my-app

Next: 鏈跟著配方自身的能力走：帶 DSL 內容的配方（minimal-app、agent-workspace、support-community、agent、blog）會在構建前插入一步 arc dsl validate，純 manifest 配方（basic、blank）不會：

bash
$ arc blocklet create my-agent --recipe minimal-app
Created minimal app blocklet "my-agent" with 18 file(s).
Next: arc dsl validate /path/to/my-agent

$ arc dsl validate /path/to/my-agent
Passed DSL validation
  path: /path/to/my-agent
  files: 16
Next: arc blocklet build /path/to/my-agent

$ arc blocklet build /path/to/my-agent
Published 20 file(s) → /path/to/my-agent/dist
  .afs/manifest.json  (http-mount protocol)
  blocklet.dist.json  (flat manifest)
  instance: requires /instance DID Space

Next: arc blocklet run /path/to/my-agent

Deploy to CF Pages:
  arc blocklet deploy /path/to/my-agent --project <project-name>

帶 DSL 的腳手架在 Next: 裡提示的是 arc dsl validate，這條在全新的 minimal-app 上確實以 0 退出。DSL 檢查鏈的其餘部分並不是一律綠燈。arc blocklet create . --recipe minimal-app 之後零修改：

bash
$ arc dsl lint .
Passed DSL lint
  path: /path/to/my-agent
  files: 16

$ arc dsl format --check .
Would format 0 file(s) (dry-run) — nothing to change
  path: /path/to/my-agent
  files: 5

$ arc dsl generate --check .
ERROR: Failed DSL generate (dry-run) — would change 4 file(s)
  path: /path/to/my-agent
  files: 11
  changed: .aup/app.json, .aup/pages/agent.json, .aup/pages/home.json, .aup/wrapper.json

  WARNING missing_man_coverage .aup/man/home.yaml: page "home" declares node-bound action(s) but has no .aup/man/home.yaml coverage
  ERROR generated_changed .aup/app.json: Generated artifact is stale. Run arc dsl generate --write.
  ERROR generated_changed .aup/pages/agent.json: Generated artifact is stale. Run arc dsl generate --write.
  ERROR generated_changed .aup/pages/home.json: Generated artifact is stale. Run arc dsl generate --write.
  ERROR generated_changed .aup/wrapper.json: Generated artifact is stale. Run arc dsl generate --write.

$ arc dsl doctor .
ERROR: Failed DSL doctor
  path: /path/to/my-agent
  decompile step: failed (0 files, 0 changed)

lint 和 format --check 退出碼 0；generate --check 和 doctor 目前退出碼 5。這是 CLI 在零修改腳手架上的當前行為，不是文件用措辭抹平的缺口——不要因為 validate 過了就把這兩道閘當成綠的。

arc blocklet recipe

檢視有哪些可用的腳手架配方。

bash
arc blocklet recipe <subcommand>
  • arc blocklet recipe list：列出全部配方
  • arc blocklet recipe explain <name>：解釋某一個配方

示例

bash
$ arc blocklet recipe list
Blocklet scaffold recipes:
  basic
    Create only a blocklet manifest.
    capabilities: manifest
    generated files: 1
  ...
  minimal-app
    Create a tiny complete app with one web page, one AUP app, one agent, and generated settings.
    capabilities: web, aup, agent, settings
    generated files: 18
    source files: 14
  ...

$ arc blocklet recipe explain basic
Recipe: basic
  Create only a blocklet manifest.
  capabilities: manifest
  generated files:
    blocklet.yaml
  AFS data:
    blocklet.yaml
  checks:
    arc blocklet check <dir>

構建與校驗

這個儲存庫自己的構建加檢查流程（bun .claude/verify/config.ts）就是對 blocklets/arcblock 依次跑 arc blocklet check 和 arc blocklet build。

arc blocklet build

構建一份 Pages 就緒的 dist/，複製檔案並寫出 .afs/manifest.json 加一份扁平 manifest。

用法

bash
arc blocklet build [dir] [options]
  • [dir]（可選，預設當前目錄）：blocklet 目錄
  • --output <dir>：輸出目錄（預設 <dir>/dist）
  • --dry-run：只算 manifest，不複製檔案也不寫盤
  • --clean：寫入前先清空輸出目錄（預設 true）

成功時還會列印一條 Next: arc blocklet run <dir> 提示，加一條 Deploy to CF Pages: 提示——完整鏈路見上面 arc blocklet create 一節。

arc blocklet check

按 recipe/profile 契約校驗一個 blocklet。別名是 arc blocklet validate。

用法

bash
arc blocklet check [dir] [options]
  • [dir]（可選，預設當前目錄）：blocklet 目錄
  • --profile <name>：校驗 profile，basic、minimal-app、agent-workspace、support-community 之一（預設 basic）

和 create、build 不同，check 成功時不列印 Next: 提示。

arc blocklet dev

掃描 blocklet 目錄的約定並報告結果，這是對目錄結構本身的 lint，不是對 DSL 內容的（那是 arc dsl lint 的事）。

bash
arc blocklet dev [dir]

檢視

arc blocklet list

列出本地的 blocklet 包：發現 blocklet.yaml，報告發布狀態。

bash
arc blocklet list [dir]

arc blocklet inspect

顯示一個本地 blocklet 包的 manifest 和檔案列表。

bash
arc blocklet inspect <ref>
  • ref（必填）：blocklet 目錄的路徑

執行與部署

arc blocklet run

在 daemon 上服務單個 blocklet，列印它的訪問 URL。

用法

bash
arc blocklet run <path> [options]
  • path（必填）：要服務的 blocklet 目錄路徑

要讓源在 daemon 重啟後還在，記到具名例項上：arc service start --instance <name> --blocklet <path>。見 arc service。

arc blocklet deploy

一步完成：先本地釋出一個 blocklet，再部署到 Cloudflare Pages。

用法

bash
arc blocklet deploy [dir] [options]
  • [dir]（可選，預設當前目錄）：blocklet 目錄
  • --project <name>：Pages 專案名（預設用 blocklet id）；多個 blocklet 部署到同一個專案會共享一棵聚合的 http-mount 樹
  • --domain <domain>：要繫結的域名
  • --cloud <cf|none>：cf 推到 Cloudflare Pages，none 只 staging（預設 cf）
  • --branch <name>：部署用的 git 分支標籤（預設 main）
  • --staging-root <dir>：staging 目錄根路徑（預設 ~/.afs/blocklets-staging）
  • --cf-account-id <id> / --cf-api-token <token>：轉發給 wrangler
  • --verify：--cloud=cf 配合 --domain 時，驗證包、診斷資訊、實際路由（預設 true）
  • --routes <list>：空格/逗號分隔的要驗證的實際路由（預設 /）
  • --compare-local：同時拉取對應的本地路由，比較狀態/健康度
  • --local-port <n>：配合 --compare-local 用的本地 Arc 連接埠（不傳就查例項登錄檔）
  • --timeout-ms <n>：單次驗證請求的超時時間，毫秒（預設 10000）

arc blocklet instance

管理 blocklet 例項，也就是部署。

bash
arc blocklet instance <subcommand> [options]
  • arc blocklet instance deploy <ref>：把一份已釋出的 dist/ 部署到本地 Pages 並繫結域名。--cloud <fs|cf|none> 選目標（預設 fs）；--pages-root <dir> 設定 --cloud=fs 用的本地 Pages 儲存根路徑（預設 ~/.arc/pages）
  • arc blocklet instance list：列出已部署的例項，也就是 Pages 專案
  • arc blocklet instance inspect <id>：顯示某個已部署例項的詳情
  • arc blocklet instance destroy <id>：拆除一個已部署例項，移除全部部署和域名；需要 --force 確認
  • arc blocklet instance logs <id>：顯示某個 Pages 例項的部署歷史（沒有執行時日誌可看——Pages 沒有執行時日誌流）。--follow 已刪除（以前會被接受、然後立刻報錯"不支援"；現在直接作為未知引數被拒絕，退出碼 5）

艦隊

arc blocklet fleet 把一組 blocklet 作為一個聚合 Pages 專案來部署，這個站這類多域名站點艦隊，就是這麼一起部署的。

bash
arc blocklet fleet <subcommand> [dir] [options]

fleet 各子命令共享的選項：--blocklets <list>（覆蓋 --fleet）、--fleet <yaml>（預設 <dir>/site-fleet.yaml 或 <dir>/fleet.yaml）、--deployment <id>（從 instances.json 解析艦隊 manifest 路徑，和 --fleet 互斥）、--project <name>（預設 afsd-blocklets）、--domain-root <domain>（預設 afsd.io）。

--deployment/--fleet 在全部四個子命令上都是宣告並強制生效的互斥（不只是文字說明）：

bash
$ arc blocklet fleet deploy --deployment foo --fleet bar.yaml
ERROR: Arguments deployment and fleet are mutually exclusive
...

只傳兩個選項中的一個時，能過這道特定的檢查——接下來會因為一個不同的、預期內的原因失敗（這裡是沒有這份 fleet manifest），這正說明這道閘是有判別力的，不是逢引數就拒：

bash
$ arc blocklet fleet deploy --fleet bar.yaml
ERROR: Error: Fleet manifest not found: /path/to/bar.yaml
  • arc blocklet fleet deploy [dir]：用別名、Web Provider 資源、冒煙檢查，釋出並部署多個 blocklet。--publish 在 stage 之前給每個 blocklet 跑一遍 arc blocklet build（預設 true）；--web-library 把 Web Provider 主題/元件 stage 進 /web/.library（預設 true）；--web-library-dir <dir> 指定要 stage 的 Web Provider 包目錄（預設 providers/runtime/web-device）
  • arc blocklet fleet verify [dir]：驗證一支已部署的艦隊，不釋出也不推送改動
  • arc blocklet fleet doctor [dir]：檢查艦隊部署的本地前置條件（--cloud cf 時的 wrangler 可用性、staging root 等）
  • arc blocklet fleet rollback <deploymentId> [dir]：把一個 Cloudflare Pages 艦隊專案回滾到之前的某次部署