blocklet.yaml 是 Blocklet package 的声明边界。字段是否被接受，以当前解析器（BlockletManifest）与 CLI 检查器为准——不是历史产品文档。
验证基线：arc 2.0.0-beta.28。
最小 package（脚手架）
arc blocklet create ./demo-basic --recipe basic --name demo-basic 写入：
specVersion: 2
id: demo-basic
name: demo-basic
did: did:blocklet:demo-basic
version: 0.1.0
description: ""足以通过 arc blocklet check（profile basic）与 arc blocklet build。
身份字段
| 字段 | 类型 | 说明 |
|---|---|---|
specVersion | number | 打包向 manifest 为 2 |
id | string | 稳定 package id |
name | string | 可读显示名（不强制 kebab） |
did | string | 脚手架生成 did:blocklet:<id> |
version | string | SemVer，如 0.1.0 |
description | string | 一句话用途 |
可发布 metadata（可选，推荐）
| 字段 | 类型 | 说明 |
|---|---|---|
logo | string | 相对路径或 URL（优先 SVG） |
keywords / tags | string[] | 发现 / UI 分类 |
author | { name, email?, url? } | 主作者 |
license、copyright | 法律归属 | 按需 |
homepage、documentation、community、support | string | 链接 |
repository | string 或对象 | 源码指针 |
hidden | boolean | true 时不在目录 UI 展示；仍可通过 ?blocklet= 激活 |
运行时声明字段
这些不是装饰 metadata。只声明 package 需要的项。
| 字段 | 含义 |
|---|---|
scope | app（默认）、user、root 或 agent |
mounts | Provider 挂载（uri 或 module + target + required） |
system | 系统服务依赖 |
sites | 命名站点：name、domains、可选 bindings |
surfaces | 对外可访问路径 |
instance | { required?, mount?, seed? } |
cron | 激活时注册的声明式定时任务 |
replicated | 复制集合契约（与 scope: root 不兼容） |
networkRead | 允许对选定 /instance/** 的网络源读取 |
redistributable | 再分发条款 |
index | 搜索索引域 |
blocklets / io / arc / engines / entrypoint | 组合、IO、兼容性、入口 |
save | 页面收藏与划词笔记。省略 = 开、侧栏。false / { enabled: false } 关闭。chrome: buttons 绑定 [data-arc-save]。未登录不出现。见 收藏与笔记。 |
Mount 形态（有代码依据）
mounts:
- uri: "ash://"
target: /ash
required: true
ops: [list, read]uri 与 module 互斥。
Scope 提醒
| Scope | 典型用途 |
|---|---|
app | 默认应用 package；可支持 replicated |
user | 调用者作用域叠加 |
root | 完整 host AFS——不与 replicated 组合 |
agent | 面向 agent 的打包 |
Recipe 暗示的能力
arc blocklet recipe explain minimal-app| 能力标签 | 典型文件 |
|---|---|
manifest | 仅 blocklet.yaml |
web | pages/、.web/ |
aup | .aup/ |
agent | agents/ |
settings | seed/settings/… |
检查器 profile
arc blocklet check . --profile basic
arc blocklet check . --profile minimal-app| Profile | 期望（摘要） |
|---|---|
basic | 有效 package 目录 / 最小契约 |
minimal-app | 按 recipe 的 AUP 页、web、agent、settings |
agent-workspace / support-community | 对应完整 app 契约 |
不要发明
- 不要记录只存在于规划稿或未合并设计中的字段。
- 不要仅凭 metadata 声称商店上架。
- 不要把
hidden: true当作安全边界——它只影响目录可见性。
完整 CLI：arc blocklet。数据路径：数据与 AFS。