跳到主要内容

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 舰队项目回滚到之前的某次部署