编写 Blocklet 会接合多份契约。分开维护，变更才可审阅。
三张编写面
| 面 | 问题 | 页面 |
|---|---|---|
| Manifest 与能力 | package 声明了什么？ | Manifest 与能力 |
| 数据与 AFS | 如何使用路径、mount、seed 与集合？ | 数据与 AFS |
| Web surface | 是 AUP UI、Web Device 站点，还是两者？ | Web surface |
推荐顺序
- 从匹配目标 surface 的 recipe 开始（空 package 用
basic，web+AUP+agent 用minimal-app，或按 构建第一个站点 手写 Web Device 文件）。 - 在把 package 当可分享物之前，填好身份 metadata（
name、description、logo…）。 - 只添加应用真正使用的 AFS mount、sites/bindings 或 replicated 集合。
- 每次有意义的变更后重跑
arc dsl validate、arc blocklet check与本地 run。
不要混用
| 不要 | 改为 |
|---|---|
| 把 AUP 页面树当作「就是 Blocklet」 | Blocklet = package 边界；AUP 是一种可能的 surface |
| 把产品语言绑到具体数据库 | 使用 AFS 路径与能力；见 AFS |
| 把 CLI 手册全文抄进应用 | 参数链到 arc blocklet |
| 从愿望清单发明 manifest 字段 | 只记录当前解析器/检查器接受的字段 |
package 目录入口
| 路径 / 文件 | 角色 |
|---|---|
blocklet.yaml | Package manifest（多数工作流需要） |
.aup/ | AUP 应用与页面 |
pages/ + .web/ | Web Device 布局、站点组件、SEO 原子 |
.route/ | 路由声明（web vs app handler） |
agents/ | Agent 定义 |
seed/ | instance 数据的首次初始化材料 |
skills/ | 打包的 skill（若使用） |
dist/ | 仅构建输出 |
无 blocklet.yaml 的约定-only package 仍作为教学样例存在（hello-html、hello-declarative）。新第三方工作优先显式 blocklet.yaml——create 总会写入一份。