17 — Blueprints as a First-Class Tier (Skill Model)

🔄 更名注记（2026-09-17，PLAN-639）：中层正式更名 Blueprint（代码缩写 bp），消除与 auto-down 文档块（PBlock）、语言 AST block 的三重撞名；三层定名 Widget / Blueprint / App。本文目录随之 docs/design/blocks/ → blueprints/，包库 blocks/ → blueprints/，CLI auto block → auto bp。全文术语已同步改写；历史论证（2026-06-26 原文）原样保留。消费机制自本设计 original copy/eject 单轨升级为三通道分级消费，见 §13。

📦 归位注记（2026-08-28，Plan 468）：本文档原为 docs/design/blocks/blocks-first-class.md（Design 17），经审计属需求级/专题类设计而非域级章，按模块归位原则移入blocks/。历史文献中的“Design 17”即指本文。

状态:设计文档(概念设计) 日期:2026-06-26 关联:Design 16 App Generation、widget 层(Plan 331/336/337)、/auto-lang-creator skill、examples/a2ui-composer、examples/a3ui-replica目的:把 blueprint 提升为 widget / blueprint / app 三层里的"一等公民",并回答核心难题——如何定义"常见、又需要灵活订制"的 blueprint 的范围与边界。 核心论点:Widget : Tool :: Blueprint : Skill。blueprint 不是预烘焙的代码库,而是自然语言 spec + 结构化契约,由 AI 用 widget 当积木组装出 .at;消费者拥有生成的源码、可改可 eject。库的原子是 spec(及 reference 输出),不是成品代码。

1. 背景:三层里的"中层"缺位

层	粒度	当前 Auto 的"身份"	缺口
Widget	原语(Button/Input/Card)	✅ 真值源:`WidgetRegistry` + `@auto-ui/widgets` + `examples/vue-gallery`	已立
Blueprint	组合卡(LoginForm/DataTable/KanbanColumn/StatsBoard)	❌ 散落在 `examples/a2ui-composer`、`a3ui-replica`、`examples/ui/001-014`;无 registry、无规范、无身份	本文档
App	完整产品(路由/shell/后端契约)	✅ 基准阶梯(Design 16,M1-M6)	已立

中层缺位的代价:在 app 生成(Design 16)时,缺一个中间粒度的复用目标。AI 只能在 widget(太细,组合空间爆炸)与 app(太粗,一次性生成整体)之间二选一。blueprint 正是连接两层的榫卯:app = shell + 路由→blueprint 选择 + blueprint 数据接线;blueprint = widgets + 局部状态 + 数据源。

2. 核心张力:common yet flexible

Widget:紧契约(props/variants),低自由 → 可黑盒复用。
Blueprint:有"可辨识形状"(DataTable/LoginForm 一眼认出是哪类模式),但每个 app 都要改(字段、列、数据源、样式、动作)。
App:独一无二,完全定制。

把 blueprint 当 widget 那样做黑盒 → 配置项爆炸,永远不够用(一个 LoginBox 的 props 会膨胀到 SSO/2FA/魔法链接/校验规则/主题/视觉密度…,变体空间是高维的,参数覆盖不到)。把 blueprint 当纯示例 → 不算复用,只是样板代码。

Widget : Tool :: Blueprint : Skill。

Widget ↔ Tool:粒度小、功能清晰、固定实现、靠参数给不同行为。
Blueprint ↔ Skill:变体多到无法参数化;用自然语言描述意图,AI 组装多个 widget + 逻辑成可用模块;按结果(acceptance)评判,而非按 config。

正如 Skill 是"模型要遵循的自然语言指令 + 对 tool 的编排"(不是预烘焙的程序),blueprint 也不是预烘焙的代码工艺品,而是自然语言描述的能力 + 对 widget 的编排。

2.2 本设计的回答(基于该类比)

blueprint 的本质是 Skill:一个"自然语言规格 + 结构化契约",由 AI 用 widget 当积木组装出 .at;消费者拥有生成的源码、可改可 eject。

由此,§2.1 的几个判断要更新:

库的原子是"规格(spec)",不是烘焙好的代码。 BlueprintRegistry 存的是 blueprint 规格(NL 意图 + 结构化 frontmatter),不是成品 .at。auto bp add 读 spec + 当前 app 的需求,AI 生成一份定制 .at。
AI 是组装机制本身。 订制的主通道是"用自然语言说你想要什么",不是配 20 个 props。
靠 acceptance(验收)兜底,不是靠参数化。 没有"一个 LoginBox 覆盖大多数 app"的参数集;有的是一份验收清单(编译过、暴露必需扩展点、只用调色板 widget、处理 loading/error/empty、可访问、满足所述意图)—— AI 输出按此评判。

从原 owned-source 模型保留下来的(现在是"生成/输出"侧的机制,而非配置):

拥有并可编辑的 .at 输出 —— 你仍拿到源码、可改可 eject。拥有的是输出,不是库。
kind + 扩展点词汇表(§4.2/§7) —— 这些现在活在规格里,作为约束 AI 的结构("你在造一个 Form 类 blueprint;必须暴露这些扩展点;只能用这些 widget")。kind 是规格的 schema,不是运行时类型。
dataSource / eject / design token —— 对生成的输出而言不变。

2.3 双产物模型(库 vs AI 的二元消解)

每个 blueprint 在库里发布两份产物,消费者二选一:

Spec(即 Skill) —— NL + 结构化 frontmatter。AI 按 app 现场实例化、订制。
参考实现集(.at) —— 见 §2.4:不止一份,而是每个 variant 一份,作为默认拷贝源 + 回归 fixture + 变体范围的物化样本。

于是两者都有:要开箱即用的标准 LoginBox → 拷某个 reference;要适配你的 SSO+2FA+品牌 → 让 AI 照 spec 生成。维护 reference 反过来校验 spec。这也呼应 /auto-lang-creator skill —— blueprint spec 本质是一份"经库策展的、专门的 skill 文件"。

2.4 两个一等模块:参考实现集 + gotchas

spec/文字描述"如何组装",但具体代码对 AI/人都远胜文字。故 blueprint 定义除 spec 外,还应有两个一等模块:

(a) 参考实现集(reference implementations) —— 不止一份,而是每个 variant 一份(minimal / with_sso / magic_link …)。价值三重:

默认拷贝源(要"标准版"者直接拷)。
回归 fixture("AI 能否仅凭 spec 复现等价物?"——既做 spec 仓 CI,也做 Design 16 的 AI 修复轮次 N 的评测锚)。
变体范围的物化样本——把 spec 说的"本 blueprint 吸收这些变化"用真代码落到底,展示 blueprint 的柔性边界。

(b) Gotchas(反例模块) —— 负样本是强有力的教学。每条结构:错误做法 + 为什么错 + 正确做法(尽量带反例代码)。比 prose 的 pitfalls 列表更具操作性。Gotchas 可从稀疏起步,随 AI 实际失败模式累积(AI 每生成该 blueprint 犯一次错 → 沉淀一条 gotcha)—— 自增强闭环。

三者合成一个 blueprint 包(类 skill 库的组织):

blueprints/form/login/
  spec.md            # frontmatter + intent + 组装指引
  reference/
    minimal.at       # 每个 variant 一份参考实现
    with_sso.at
    magic_link.at
  gotchas.md         # {错误, 为什么, 正确}(带反例代码)

参考实现同时是 spec 自身的 CI fixture,故非额外负担,而是本就该有的测试床。

具体 spec 形态示例(LoginBox):

# blueprint: form/login
kind: form
palette: [Input, Button, Label, Checkbox, Separator, ErrorState]
dataSource: { attempt: (creds) => Session, providers?: []Provider }
extension_points: [fields, submit, third_party, success, error_display]
variants: [minimal, with_remember, with_sso, magic_link]
acceptance:
  - auto build green; 只用调色板 widget(+ 原生)
  - 暴露 {fields, submit, error} 扩展点为 EDIT 区
  - 处理 loading + error 状态(契约)
  - 可访问:label 关联、error 播报、键盘可达
---
# Intent
凭据采集表单,向后端 session 端点认证。

# 本 blueprint 吸收的变化(per-app 变体)
fields / SSO / 2FA / captcha / 成功跳转 vs 内联 / 校验规则 / 密码规则 / 视觉密度。

# 组装指引
每个字段用 Label+Input;submit → dataSource.attempt;Button 显 loading;
错误经 error 槽显示;输出里标 EDIT 区。

# References(见 reference/*.at,每 variant 一份)
minimal / with_sso / magic_link

# Gotchas(见 gotchas.md,每条 = 错误 + 为什么 + 正确)
端点写死 / 漏 loading-error 契约 / label 未关联 / ……

frontmatter = AI 读取的机器可检契约;正文 = 人/AI 可读的组装说明;reference = 锚点。

4. 范围与边界:如何圈住"自由"(用户最关心的问题)

4.1 三个边界判据

In-scope(一个 blueprint 该承担的):一个可辨识 UX 模式 + 一个固定行为契约 + 一组有界的扩展点词汇表(由 blueprint 的 kind 决定,见 4.2)。
Out-of-scope(交给 app 层组合):横切基础设施(auth / routing / theming / 全局 store)、跨多模式的业务工作流。
逃生口(eject)= 天花板:blueprint 不追求覆盖 100%;当订制超出其扩展点词汇表 → 消费者完整接管(已拥有源码)。这是 blueprint 保持"有限"的关键,防止退化为"上帝组件"。

4.2 blueprint kind = 限制自由的关键机制

不泛泛定义"一个 blueprint",而是定义"类别",每类有固定的扩展点词汇表。 某个 blueprint 实例只能在它所属 kind 的词汇表内变化;超出 → eject。这是把"自由"圈住的核心:

例:所有 DataTable 类 blueprint 暴露相同扩展点词汇表:columns / row / cell(:col) / empty / loading / error / toolbar / pageSize。一个具体 DataTable 在这套词汇里变化;消费者要"行内嵌视频播放器" → 已超出词汇表 → eject 接管。

词汇表把"可订制"从"无边 props"收敛为"几类固定切面",既保灵活又可枚举、可文档化、可被 AI 当稳定目标。

4.3 变体(variants)而非无限 props

一个 blueprint 自带命名变体(compact / with-filters / dense),而不是 30 个布尔 prop。变体是预先调好的"已订制档位";超出变体 → 改源码或 eject。

4.4 配色/spacing 归 design token,不进 blueprint

blueprint 不内联颜色/间距硬编码,而消费 token(未来的 Design Token Compiler)。这让同一份 blueprint 源码在不同主题下零改动可用 —— 订制走 token,不走 blueprint 内部。

5. Auto 中的 blueprint 解剖

一个 blueprint = 一个 widget,它:

在 view 里组合 widgets(来自 @auto-ui/widgets 调色板)。
声明 model(自身状态)+ msg(行为契约:加载/失败/选中/提交/分页…)。
接一个 dataSource 作为 prop(typed fetcher 或 #[api] 引用 + 参数)—— blueprint 与具体后端解耦(它不知道也不该知道 /api/notes)。
扩展点:Phase 1 = 源码里标好的编辑区(注释标记 + 文档);Phase 2 = AURA 命名 slot(运行时投影,见 §11)。

此示例依赖多文件模块，不能在书页内运行——请到 Playground

auto

// 伪代码:一个 DataTable blueprint 的形态
use widgets: Table, Pagination, EmptyState, ErrorState
use back.api: Note   // 仅类型,不绑具体端点

widget DataTableBlueprint[T](items []T, columns []Column, on_select msg) {
    msg { PageChanged(int), SortChanged(str), Retry }
    model { var loading bool = true; var error str = ""; var page int = 0 }
    view {
        // ── EDIT: toolbar(扩展点:工具条)──
        // ── EDIT: column header render(扩展点)──
        Table(items, columns) { … }
        // ── EDIT: empty / loading / error(扩展点)──
        Pagination(page) { onchange: .PageChanged }
    }
    on { /* 行为契约:抓取/重试/分页/排序,接 dataSource */ }
}

EDIT: 注释 = 文档化的编辑区(owned-source 的扩展点形态)。AI/人类在区内改,不改骨架契约。

6. 订制模型:Auto 在 config–composition 谱系上的落点

谱系两端:纯 config(一堆 props)↔ 纯 composition(小组件自拼)。

Auto 的选择:默认 adopt-and-edit(拥有源码),辅以三种订制渠道,按"变化类型"分流:

变化类型	订制渠道	例子
数据驱动(结构化)	schema/config(columns、fields 定义)	表格列、表单字段集
结构性(布局)	slot(Phase 2 AURA 命名投影)	自定义 cell 渲染、工具条
风格	design token	主题/间距
超出词汇表	eject(接管源码)	"我要在表格行嵌视频"

Auto 明确不做"配置驱动的万能 blueprint 引擎"(会退化成低代码地狱)。owned-source 是默认;config/slot 是便利;eject 是兜底。

7. blueprint kind 分类法(每类 = 一套扩展点词汇表)

Kind	职责	扩展点词汇表	示例 blueprint
Form	结构化输入与提交	fields schema、submit、validation、actions(第三方登录等槽)、success/error	login、contact、settings、search
Data-display	展示集合 + 状态	columns/items renderer、dataSource、empty/loading/error、toolbar、分页/排序/过滤	data-table、card-grid、stats-board、note-list(→ M1 用)
Feedback	瞬时/状态反馈	content、触发契约	toast-region、empty-state、error-boundary、confirm-dialog
Layout	容器/骨架	named slots(主体区)	app-shell、sidebar、header、dashboard-grid、tabs-shell
Composite/Action	带局部状态机的交互	item renderer、actions、局部状态机	kanban-column(→ M2)、comment-thread、chat-message-list(→ M3)、file-uploader

每类 = 一份"扩展点契约"文档 + gallery 里若干实例。M1-M3 基准需要的 blueprint 正好覆盖 Data-display / Form / Composite 三类 —— blueprint 生态与 Design 16 基准阶梯天然对齐。

8. 数据契约(`dataSource`)

blueprint 不绑死 /api/notes;接 typed fetcher(dataSource: list_notes + params)。
直接喂给 Design 16 的 Rung 2(类型化后端契约):blueprint 是"前端如何消费 typed API"的标准形态。
loading/error/empty 是一等 view 状态(不是事后补丁)—— Rung 2 的数据生命周期在此落地为 blueprint 的强制槽。这让每个数据型 blueprint 天然带状态机,AI 生成时不会漏掉 loading/error。

9. blueprint 的载体:spec 库 + 生成器 + gallery + `auto blueprint`

按 §2 的 Skill 模型,库的原子是 spec(+ reference 输出),不是烘焙好的代码。

BlueprintRegistry(crates/.../ui_gen/blueprint/):按 kind + name 索引;每条是一份 blueprint spec = 结构化 frontmatter(kind / palette 子集 / extension_points 词汇表 / dataSource 期望签名 / variants / acceptance 验收清单)+ NL 正文(intent / 变体说明 / 组装指引 / pitfalls)+ 指向 reference .at 输出。
生成器(AI):消费 spec + 当前 app 的需求(自然语言)→ 生成定制 .at;由 acceptance 清单 + auto build/vue-tsc 编译 + preview 回路校验(回路本身是 Design 16 Rung 5)。可复用 /auto-lang-creator skill 基建。
examples/bps-gallery:每类若干 blueprint;每个 blueprint 给 reference(默认输出) + AI 订制实例 + 标注的 EDIT 扩展点 三视图对照 —— 同时是展示、是 spec 的回归 fixture、是"边界:默认能走多远、何时 eject"的样例。
auto bp add <kind>/<name> 两种模式:
- --reference:拷 reference .at(开箱即用,等价 §2.3 的 adopt)。
- 默认 / --from "<自然语言需求>":AI 照 spec 生成定制 .at;提示关联 widget 依赖 + 标注 dataSource 接入点。
auto bp list / backlog:对照 widget registry 与 app 实际用到的 blueprint,看缺口(与 337 的 auto ui backlog 同构)。

10. 与其它两层的关系

Widget : Tool / Blueprint : Skill / App : 由 skill 编排的 plan。
向下:blueprint 的 spec 指定它编排哪些 widget(消费 @auto-ui/widgets 调色板)。widget 天花板直接决定 blueprint 天花板 → Plan 337 TODO-A(全量 widget)同时抬高两层。
向上:app = shell + 路由→blueprint-intent,每个 intent 由其 spec 现场实现(Design 16)。blueprint 是 app 生成的中间粒度"生成目标"(不是复用目标);把"生成一个 app"缩小为"每块照 spec 生成一个 blueprint + 接数据"。
三层形成完整阶梯:widget(词法)→ blueprint(句法/模式,AI 编排)→ app(篇章)。

11. 实施阶段(概览,各自单独立 Plan)

Phase A(blueprint 包基础):定 blueprint 包格式(spec frontmatter + NL 正文 + acceptance + 参考实现集 reference/*.at + gotchas.md)+ BlueprintRegistry 数据模型 + examples/bps-gallery 骨架(先 Form + Data-display 两类)。每类手写 1-2 个 blueprint 包:spec + 每个 variant 一份参考实现 + 起步 gotchas。参考实现同时作 spec 的回归 fixture(能否 AI 复现)。产出:包格式规范 + 两类各 1-2 个完整 blueprint 包。
Phase B(AI 生成器 + CLI):auto bp add 两模式(reference 拷贝 / AI-from-spec 生成);生成器接 /auto-lang-creator 基建 + auto build 校验回路;dataSource 接入约定;与 337 同构的同步/守卫测试(spec ↔ reference 一致性、生成器能否复现 reference)。
Phase C(覆盖基准):每类补齐 spec,优先覆盖 Design 16 的 M1-M3:note-list(Data-display)、login(Form)、chat-message-list(Composite)。
Phase D(依赖 AURA 扩展,较远):命名 slot / projection,让 blueprint 可作"活组件"运行时复用(非生成/非拷贝)。此前一律"spec→AI 生成"或"拷 reference"。

12. 非目标 / 开放问题

不做配置驱动的万能 blueprint 引擎(低代码地狱)。
不做"预烘焙 blueprint 成品库"作为主形态(spec + reference 才是;reference 是 spec 的默认产物/回归 fixture,不是库的原子)。
不在本设计定 dataSource 的类型系统细节(归 Rung 2 / Design 16)。
开放:AI 生成的可复现性——同 spec 多次生成可能产出不同 .at;靠 acceptance + reference 锚定 + 编译/preview 回路收敛。是否需要"确定性种子"留给 Phase B。
开放:eject 后的升级路径——消费者拥有生成源码后,spec 改进如何回流?短期不做(纯 owned);长期可能需要 spec diff/patch 提示。
开放:spec 的作者侧工具链——谁写 spec、如何验证 acceptance(spec 仓的 CI:每个 spec 能被 AI 复现出通过 acceptance 的 .at)。
开放:blueprint 是否需要"泛型"(如 DataTableBlueprint[T])——取决于 Auto 泛型在 UI 场景的成熟度。

13. 消费分级：三通道与产物纪律（PLAN-639 增补，2026-09-17）

本节为 PLAN-639 的规范增补，不改动 §1–§12 的历史结论；契约六问的正式裁定文本在 docs/specs/blueprint/contract.md。

原设计（§2.3/§9）的消费面是 copy/生成单轨：要么拷 reference（adopt-and-edit），要么让 AI 照 spec 现场生成。多应用消费实践（jade desktop / 041-auto-edit 的 filetree 四件 sha256 各异、tree_chevron 分叉、tabs_store 孪生）暴露了单轨的根因缺陷：每个消费动作都产生可漂移副本。故升级为三通道分级：

通道	形态	适用	产物纪律
L1 import/bind（平台化主通道，新增）	应用 pac.at 声明包依赖（PLAN-635 跨包解析：声明门控+`resolve_module_path`）→ `use` 导入 bp 参考实现 + 声明式绑定（`src/front/bps/<name>.bind.at`：slot→布局容器、action 注入、token 覆盖），VM 轨运行时解析 + a2ts 编译期内联	结构满足 spec、只需数据/动作/token 接线的标准消费	零副本——固化产物是产物不是资产；bind 工件带 GENERATED 头注，重生成安全
L2 copy reference（原 adopt 轨，保留）	`auto bp add --reference <variant>` 拷贝参考实现	离线场景、深度定制起点	落地文件归应用所有（eject 语义不变）；头注登记行（来源 bp+版本+日期）为未来回迁 L1 留账面
L3 agent generation（原生成轨，保留）	spec + 自然语言需求 → AI 组装 `.at` → `auto bp check` + `auto build` acceptance 门	spec 未覆盖的创新组合	同 L2 登记行；结构性差异走变体提升评审（下）

通道选择原则：能 L1 不 L2，能 L2 不 L3——副本数量是漂移风险的线性函数； L1 让"升级共享 bp"变成消费方的零成本重构建，而非 N 份副本的 N 次手工同步。

13.1 变体提升评审（variant promotion，轻量流程）

L3（或深度定制的 L2）产出出现 spec 未声明的结构性差异时：

在该 bp 包 spec.md 增 promotions: 小节：差异描述 → slot/action 点提案；
评审通过 → 差异进 spec 正式声明（slot/action 点/变体），下个应用经 L1 免费复用；
拒绝 → 差异留应用侧，登记 docs/plans/KNOWN-DEBT-AND-RISKS.md（不阻塞该应用）。

流程写入 agent-generation-workflow.md；这是 §2.4 gotchas 自增强闭环的结构面对偶——gotchas 沉淀"怎么做错"，promotions 沉淀"长出什么新结构"。

13.2 与六问契约的对应

输入/输出声明面（data props / events / action id）进入 spec frontmatter， L1 bind 的一致性校验以此为准（缺位即构建错）；
状态归属：平台服务（workspace/tabs/theme/keybinding）单例注入，bp 禁止私有副本——§9.5 教训（jade tabs_store 孪生登记册）成文为契约第三问；
双形态：L1 绑定在 vue 发射轨（a2ts）与 VM 解释轨同语义，含 actions/menubar/ toolbar 配置双轨发射。

17 — Blueprints as a First-Class Tier (Skill Model) ​

1. 背景:三层里的"中层"缺位 ​

2. 核心张力:common yet flexible ​

2.1 关键类比:Blueprint 之于 Widget,正如 Skill 之于 Tool ​

2.2 本设计的回答(基于该类比) ​

2.3 双产物模型(库 vs AI 的二元消解) ​

2.4 两个一等模块:参考实现集 + gotchas ​

4. 范围与边界:如何圈住"自由"(用户最关心的问题) ​

4.1 三个边界判据 ​

4.2 blueprint kind = 限制自由的关键机制 ​

4.3 变体(variants)而非无限 props ​

4.4 配色/spacing 归 design token,不进 blueprint ​

5. Auto 中的 blueprint 解剖 ​

6. 订制模型:Auto 在 config–composition 谱系上的落点 ​

7. blueprint kind 分类法(每类 = 一套扩展点词汇表) ​

8. 数据契约(dataSource) ​

9. blueprint 的载体:spec 库 + 生成器 + gallery + auto blueprint ​

10. 与其它两层的关系 ​

11. 实施阶段(概览,各自单独立 Plan) ​

12. 非目标 / 开放问题 ​

13. 消费分级：三通道与产物纪律（PLAN-639 增补，2026-09-17） ​

13.1 变体提升评审（variant promotion，轻量流程） ​

13.2 与六问契约的对应 ​