lunanting/ai-chatbot

Fork 0

Your Name 10e1096c83

Lint / build (20) (push) Has been cancelled

Details

Playwright Tests / test (push) Has been cancelled

Details

feat: add detail surface protocol workflow

2026-03-21 20:55:04 +08:00

19 KiB

Raw Permalink Blame History

Canvas UI Surface Protocol 设计方案（基于 Google Stitch / A2UI 调研）

日期：2026-03-21 目标：把我们当前“会聊天、会生图、会在画布上落结果”的 Agent，升级成“能稳定产出结构化界面、支持交互、支持持续迭代、支持原型播放”的系统。

1. 先说结论

1.1 Google Stitch 对我们的帮助是什么

从官方资料看，Stitch 的核心路线不是单纯生一张 UI 图，而是把“想法 → 界面设计 → 代码/原型”缩短为一条连续链路。

目前我能确认到的官方能力有：

2025-05-20：支持 自然语言/图片/线框 → UI 设计 + 前端代码，支持 交互式迭代、多版本探索、Paste to Figma、导出前端代码。
2025-11-18 之后：随着 Gemini 3 接入，官方明确提到 Stitch 的 UI 生成质量提升。
2025-12-23：官方确认 Nano Banana Pro 已可在 Stitch 中使用，说明 Stitch 已接入更强图像生成/编辑能力。
2026-02（官方可检索到的最新明确更新）：Google 官方已给 Stitch 加入 Prototypes，可以把多个 screen 串成 可交互原型流。

1.2 A2UI 对我们的帮助是什么

A2UI 最值得我们学的不是视觉风格，而是它的运行时协议思想：

Agent 不直接输出任意 HTML/JS，而是输出 声明式 UI 协议
客户端只渲染 白名单 catalog 中的可信组件
结构（components） 与 数据（data model） 分离
支持 增量更新
支持 用户动作回传给 Agent

这套思想非常适合我们，因为我们现在最缺的不是“多一个好看的卡片”，而是Agent 产出 UI 的统一运行时。

1.3 最终判断

我们最优路线不是“抄 Stitch UI”，也不是“整套照搬 A2UI”，而是：

借鉴 Stitch 的产品路线：从结果图升级到“设计迭代 + 原型 + 代码/结构化输出”
借鉴 A2UI 的系统路线：把 Agent 输出收进统一的 UI Surface Protocol
结合我们现有 conversation-state-protocol：形成“对话理解协议 + UI surface 协议”双协议架构

2. 外部调研纠偏

2.1 关于 Stitch，需要纠正的点

我这次在线检索后，没有找到 Google 官方可验证来源来证明以下功能已经正式公开：

“DESIGN.md”
“Agent Manager”
“无限画布”
“语音设计批改”

这些概念在社区讨论和第三方文章里有出现，但本方案不把它们当作已被官方确认的能力。

本方案只基于已确认的官方信息来提炼技术路线：

多模态输入
UI 生成
多版本探索
Figma / 前端代码导出
原型串联
更强图像模型接入

2.2 关于 A2UI，需要纠正的点

A2UI 非常强，但它不是“可直接拿来替代我们前端”的现成方案。

官方 README 里明确写了：

目前仍是 Early stage public preview
v0.8 可用，但协议仍在演进
适合学习其 协议设计、渲染器架构、catalog 白名单机制
不适合让我们当前系统重度依赖其未稳定版本

所以正确姿势是：借鉴架构，不强绑定实现。

3. 我们当前系统已经具备的基础

3.1 已有的对话/工作流协议基础

我们已经有一条很重要的底座：

lib/ai/conversation-state-protocol.ts
lib/ai/conversation-state-protocol-events.ts

这意味着我们已经不是“全靠 route 里写很多 if/else”的状态了，而是已经有：

工作状态读取
事件化写回
图片/视频/分镜等流程记忆
用户意图与上下文边界管理

这部分非常重要，它可以继续作为上层 Agent 理解协议保留。

3.2 已有的详情模式 UI 协议雏形

我们已经做了 detail mode 的第一代结构化协议：

lib/detail-ui-protocol.ts
lib/detail-ui-renderer.ts
lib/detail-ui-validator.ts
app/api/canvas/detail-plan/route.ts
app/api/canvas/detail-review/route.ts

这说明我们已经迈出了最难的一步：

不再只是一张整图
开始区分背景图层与文字层
开始让 review 直接 patch 协议

但当前它仍然是**“详情模式专用协议”**，不是通用 UI Surface 协议。

4. 当前距离“最优体验”还缺什么

如果以 Stitch 的产品方向 + A2UI 的系统方向为参照，我们还缺 8 个关键层级。

4.1 缺统一 UI Surface 协议

当前 detail-ui-protocol 只覆盖：

title
subtitle
body
safe area

这还不是一个通用 UI 表达层，无法稳定表示：

商品参数区
卖点列表
价格区
对比表
买家评价卡
按钮区
标签/角标/徽章
多区域联动布局

4.2 缺“结构”和“数据”的彻底分离

A2UI 的一个核心点是：

结构描述组件树
数据模型存值
组件通过 path 绑定数据

我们现在 detail 协议里的文本内容还是直接写死在 block 里，导致：

改一段文案需要改整个 block
很难做局部 patch
很难做模板复用

4.3 缺用户动作回传协议

现在的 Agent 还是更像“对话生成 + 画布落图”，还不是真正的“UI agent runtime”。

我们缺：

点击某个卡片后告诉 Agent 用户想放大这一块
编辑某个标题后告诉 Agent 用户要保留结构仅改文案
拖拽组件后告诉 Agent 用户偏好布局发生变化
点击“生成变体”后让 Agent 只重做某个 section

4.4 缺流式 patch 更新

现在很多地方仍然是：

plan 完整返回
review 完整返回
再由前端一次性处理

缺少：

surface.created
components.appended
data.updated
review.patch_applied
prototype.link_added

这种统一流式 surface update。

4.5 缺受控组件 catalog

我们目前的详情协议本质上还是自由度比较高的“文字块+图片”。

真正稳定后，Agent 不应该直接自由拼任何 UI，而应该只能调用受控 catalog，例如：

HeroBlock
SellingPointGrid
FeatureSpecTable
ComparisonCard
TrustBadgeRow
ReviewCard
CTASection
StickyBottomBar

这样才能保证：

风格一致
质量稳定
patch 容易
renderer 可预测

4.6 缺原型图与 screen flow 层

Stitch 已经明确加了 Prototypes。

而我们现在详情模式仍偏“长图生产”，没有统一表达：

screen 之间跳转关系
点击区域
hotspot
状态切换
原型播放

如果未来我们想让“Agent详情模式”真正高级，必须支持：

从静态 screen 升级为可交互 flow
在画布里直接预览原型行为

4.7 缺设计系统记忆层

这是我们现在最容易被忽视，但长期最重要的能力。

我们需要一个项目级设计系统记忆，不一定叫 DESIGN.md，但本质要存在：

颜色 token
字体等级
间距规则
卡片圆角
阴影
图片风格
品牌语气
常用 section 模板

否则 Agent 每次都像第一次做设计，结果不可能稳定。

4.8 缺多 Agent 分工

现在很多能力压在一个 route 或一轮模型输出里。

理想形态应该拆成：

Design Orchestrator
Surface Planner
Copy Agent
Visual Critic
Prototype Linker
Action Interpreter

这样才能做到：

规划与执行分离
文案与布局分离
质检与生成分离
交互与渲染分离

5. 新目标：Canvas UI Surface Protocol（CUSP）

建议正式定义一套内部协议：

Canvas UI Surface Protocol（简称 CUSP）

它不是替代 conversation-state-protocol，而是和它并列：

Conversation State Protocol：负责“用户在说什么、当前任务做到哪、记忆怎么延续”
Canvas UI Surface Protocol：负责“当前 UI 长什么样、有哪些组件、数据是什么、用户点了什么、下一步怎么 patch”

6. CUSP 的核心对象

6.1 Surface

一个可被 Agent 管理、可被前端渲染、可被 patch 的界面单元。

建议字段：

surfaceId
projectId
chatId
surfaceType：detail_page / agent_panel / storyboard / prototype_screen
mode：draft / review / published
designSystemId
rootComponentId
status

6.2 Components

受控 catalog 中的组件树，建议采用 扁平邻接表，类似 A2UI 的思路。

建议字段：

id
type
parentId
slot
props
bindings
styleTokens
layout
visible

6.3 Data Model

每个 surface 都应该有自己的数据模型。

示例：

{
  "product": {
    "name": "由点笔迹 离线日记",
    "tagline": "离线可用，私密记录"
  },
  "hero": {
    "title": "Capture your day, anytime.",
    "subtitle": "离线优先的私人记录空间"
  },
  "sections": {
    "features": [
      { "title": "离线优先", "desc": "无网络也能访问内容" },
      { "title": "隐私保护", "desc": "支持密码与 Face ID" }
    ]
  }
}

6.4 Bindings

组件不直接存最终文案，而是尽量绑定到 data model：

text: { path: "/hero/title" }
items: { path: "/sections/features" }

这可以带来：

改文案不改结构
改数据不重做整屏
可做局部翻译/局部重写

6.5 Actions

前端产生的交互动作，回传给 Agent。

建议动作类型：

surface.regenerate_section
surface.edit_copy
surface.move_component
surface.replace_asset
surface.generate_variant
surface.link_prototype
surface.publish_snapshot

6.6 Patch

Agent 不应该每次都重新返回整棵 UI 树，而应该支持 patch：

append_components
replace_component
remove_component
update_data
update_binding
update_style_tokens
reorder_children

7. CUSP 与我们现有协议的关系

7.1 不推翻 conversation-state-protocol

现有：

lib/ai/conversation-state-protocol.ts
lib/ai/conversation-state-protocol-events.ts

继续保留，负责：

意图理解
工作流阶段
图片/视频/分镜记忆
目标资产解析

7.2 detail-ui-protocol 升级为 CUSP adapter

现有：

lib/detail-ui-protocol.ts

建议不要直接废弃，而是把它变成：

detail-page 类型 surface 的兼容适配器

也就是说：

旧 detail 协议仍可用
新系统统一转成 CUSP surface
渐进迁移，不一次性推倒

7.3 Canvas node 变为 artifact / render target

当前画布节点更像“结果容器”。

未来建议分层：

surface：结构化 UI
artifact：图片、视频、导出图、切图结果
canvas node：在无限画布上的可视承载对象

这样就能同时支持：

一个 surface 多个版本
一个版本多个 artifact
一个 artifact 多个展示位置

8. 数据库设计建议

8.1 `UiSurfaceSession`

用于描述一个 surface 的主记录。

建议字段：

id
projectId
chatId
canvasId
surfaceType
mode
status
designSystemId
currentBranchId
latestSnapshotId
createdBy
createdAt
updatedAt

8.2 `UiSurfaceBranch`

用于支持多方案探索。

建议字段：

id
surfaceSessionId
name
sourceSnapshotId
status
summary
createdAt

8.3 `UiSurfaceSnapshot`

用于版本化保存协议结果。

建议字段：

id
surfaceSessionId
branchId
version
protocolVersion
surfaceJson
dataModelJson
validationJson
reviewJson
createdAt

8.4 `UiSurfaceAction`

用于保存用户交互与 Agent 响应事件。

建议字段：

id
surfaceSessionId
snapshotId
actionType
actionPayload
source：user / agent / system
messageId
createdAt

8.5 `DesignSystemProfile`

项目级设计记忆层。

建议字段：

id
projectId
name
brandVoice
colorTokensJson
typographyTokensJson
spacingTokensJson
componentRulesJson
imageStyleRulesJson
updatedAt

9. API 设计建议

9.1 规划接口

POST /api/canvas/ui-surface/plan

输入：

用户需求
当前项目上下文
参考图/参考资产
design system profile
surfaceType

输出：

surfaceSession
initialSnapshot
validation
executionPlan

9.2 流式更新接口

POST /api/canvas/ui-surface/stream

输出事件建议：

surface.created
branch.created
components.appended
data.updated
validation.updated
review.patch_ready
artifact.generated
surface.completed

9.3 动作回传接口

POST /api/canvas/ui-surface/action

前端把动作结构化发回：

点击按钮
编辑文案
拖拽卡片
请求生成变体
接受/拒绝 Agent patch

9.4 原型接口

POST /api/canvas/ui-surface/prototype/link

用于表达：

当前 screen 到下一 screen 的跳转
hotspot
过渡信息
行为上下文

9.5 导出接口

POST /api/canvas/ui-surface/export

导出方向：

JSON snapshot
前端组件 DSL
Figma intermediary schema
静态预览图

10. 前端渲染层建议

10.1 新增 `SurfaceProvider`

作用类似 A2UI Provider，但不强依赖其实现。

职责：

接收 surface snapshot / patch
管理本地 data model
管理交互 action
维护 renderer catalog

10.2 新增 `SurfaceRenderer`

统一把 surface 渲染到：

详情模式面板
Agent 详情模式
原型预览器
画布节点内部 preview

10.3 新增 `SurfaceCatalog`

统一注册可信组件：

HeroBlock
FeatureGrid
SpecTable
ReviewCard
BadgeRow
CTASection
ComparisonTable

10.4 新增 `PrototypePlayer`

用于：

screen 间跳转
交互热点高亮
模拟点击流程
从静态详情升级到可交互原型

10.5 新增 `SurfaceInspector`

用于：

查看当前组件树
查看 data binding
查看 validation issue
人工修正 style token

11. Agent 侧需要新增的能力

11.1 Design Orchestrator

负责：

理解用户目标
选择 surfaceType
分配子 Agent
决定是改数据、改结构还是改资产

11.2 Surface Planner

负责：

生成初始 surface 结构
选择 catalog 组件
输出 bindings 与 layout

11.3 Copy Agent

负责：

生成标题/副标题/卖点文案
根据品牌语气做变体
局部重写

11.4 Visual Critic

负责：

层级校验
安全区校验
文案长度校验
信息顺序校验
风格一致性校验

11.5 Prototype Linker

负责：

定义按钮跳转关系
定义 screen flow
构建 demo 路径

11.6 Action Interpreter

负责：

把用户在 UI 上的点击/编辑/拖拽解释成结构化意图
决定下一步是 update_data、replace_component 还是 generate_variant

12. Prompt / System 规则要怎么升级

我们现在的 Agent prompt 偏“直接回答用户”和“调用技能”。

未来增加一层 UI surface 之后，prompt 里要明确告诉模型：

12.1 什么时候输出 surface，而不是聊天文本

例如：

用户要求“给我一个详情页结构”
用户要求“改这一块 UI”
用户要求“把这个区域做三个方案”
用户要求“把几屏串成演示流程”

12.2 什么时候只 patch 数据，不重建结构

例如：

“把标题再短一点”
“这一屏换成更像苹果风”
“第二块卖点文案改成更偏功能”

12.3 什么时候只 patch 资产

例如：

“把主图换成更干净的白底”
“把图标统一成线性风格”

12.4 什么时候向用户确认

例如：

改动会影响整体结构
需要重做多屏
需要丢弃已有 branch
需要进入 prototype flow

13. 推荐开发顺序（务实版）

Phase 1：把详情模式正式抽象成 surface

目标：

先不要碰所有 Agent UI
先把 AI详情生成 升级成第一个正式的 surfaceType=detail_page

产出：

UiSurfaceSession
UiSurfaceSnapshot
SurfaceRenderer
detail-ui-protocol -> CUSP adapter

Phase 2：支持 data model + binding

目标：

title/subtitle/body 不再直接写死在 block 上
让内容更新优先走 data update

产出：

surface data model
path binding
copy patch

Phase 3：支持 action 回传

目标：

用户在 UI 上直接操作
Agent 理解这些操作，而不是都回退成聊天文本

产出：

action schema
action -> protocol patch pipeline
前端交互埋点

Phase 4：支持 branch / variant

目标：

用户一键出 2~4 套方案
方案可以并行存在、比较、切换

Phase 5：支持 prototype flow

目标：

screen 间连线
点击预览
演示模式

14. 这件事做成后，我们的体验会怎么变

现在的模式更像：

Agent 理解用户
生成结果
落到画布

升级后会变成：

Agent 理解用户
决定输出 聊天 / 工作流 / UI surface / 原型
UI 不是一次性结果，而是一个可持续演化的对象
用户在画布里的行为也成为 Agent 输入

这时我们的 Agent 就不是“很多智能 patch”，而是真正的：

对话协议 + UI 协议 + 工作流协议 三层统一系统。

15. 下一步的最小可落地任务

建议立刻开始的第一批任务：

新建 lib/ui-surface-protocol.ts
定义 Surface / Component / DataModel / Action / Patch 基础 schema
新建 lib/ui-surface-renderer.ts
把 detail-ui-protocol.ts 适配到新 schema
新建 UiSurfaceSession / UiSurfaceSnapshot 两张表
增加 /api/canvas/ui-surface/plan
增加 /api/canvas/ui-surface/action
在 CanvasChatPanel 中插入 SurfaceRenderer
先支持 5 个基础组件：HeroBlock / FeatureGrid / ReviewCard / CTASection / SpecTable
再把 detail mode 升级为第一条正式 surface workflow

16. 参考资料（本次在线调研）

Google 官方：Stitch

Stitch 首发（2025-05-20）：
https://developers.googleblog.com/stitch-a-new-way-to-design-uis/
Stitch 接入 Gemini 3 与 Prototypes：
https://blog.google/innovation-and-ai/models-and-research/google-labs/stitch-gemini-3/
Nano Banana Pro 已可在 Stitch 中使用：
https://blog.google/products-and-platforms/products/gemini/where-to-use-nano-banana-pro/

Google 官方：A2UI

A2UI README：
https://github.com/google/A2UI
A2UI 数据绑定：
https://github.com/google/A2UI/blob/main/docs/concepts/data-binding.md
A2UI Client-to-Server Actions：
https://github.com/google/A2UI/blob/main/docs/concepts/client_to_server_actions.md
A2UI Renderers：
https://github.com/google/A2UI/blob/main/docs/reference/renderers.md

17. 最终判断

Stitch 告诉我们产品应该长成什么样。

A2UI 告诉我们底层协议应该怎么搭。

而我们现有的 conversation-state-protocol，决定了我们有机会把“聪明 Agent”真正做成统一系统。

接下来不该再继续堆零散 patch。

接下来应该正式进入：

Conversation State Protocol + Canvas UI Surface Protocol + Workflow Events

这三层统一化。

19 KiB Raw Permalink Blame History Unescape Escape

Canvas UI Surface Protocol 设计方案（基于 Google Stitch / A2UI 调研）

1. 先说结论

1.1 Google Stitch 对我们的帮助是什么

1.2 A2UI 对我们的帮助是什么

1.3 最终判断

2. 外部调研纠偏

2.1 关于 Stitch，需要纠正的点

2.2 关于 A2UI，需要纠正的点

3. 我们当前系统已经具备的基础

3.1 已有的对话/工作流协议基础

3.2 已有的详情模式 UI 协议雏形

4. 当前距离“最优体验”还缺什么

4.1 缺统一 UI Surface 协议

4.2 缺“结构”和“数据”的彻底分离

4.3 缺用户动作回传协议

4.4 缺流式 patch 更新

4.5 缺受控组件 catalog

4.6 缺原型图与 screen flow 层

4.7 缺设计系统记忆层

4.8 缺多 Agent 分工

5. 新目标：Canvas UI Surface Protocol（CUSP）

6. CUSP 的核心对象

6.1 Surface

6.2 Components

6.3 Data Model

6.4 Bindings

6.5 Actions

6.6 Patch

7. CUSP 与我们现有协议的关系

7.1 不推翻 conversation-state-protocol

7.2 detail-ui-protocol 升级为 CUSP adapter

7.3 Canvas node 变为 artifact / render target

8. 数据库设计建议

8.1 UiSurfaceSession

8.2 UiSurfaceBranch

8.3 UiSurfaceSnapshot

8.4 UiSurfaceAction

8.5 DesignSystemProfile

9. API 设计建议

9.1 规划接口

9.2 流式更新接口

9.3 动作回传接口

9.4 原型接口

9.5 导出接口

10. 前端渲染层建议

10.1 新增 SurfaceProvider

10.2 新增 SurfaceRenderer

10.3 新增 SurfaceCatalog

10.4 新增 PrototypePlayer

10.5 新增 SurfaceInspector

11. Agent 侧需要新增的能力

11.1 Design Orchestrator

11.2 Surface Planner

11.3 Copy Agent

11.4 Visual Critic

11.5 Prototype Linker

11.6 Action Interpreter

12. Prompt / System 规则要怎么升级

12.1 什么时候输出 surface，而不是聊天文本

12.2 什么时候只 patch 数据，不重建结构

12.3 什么时候只 patch 资产

12.4 什么时候向用户确认

13. 推荐开发顺序（务实版）

Phase 1：把详情模式正式抽象成 surface

Phase 2：支持 data model + binding

Phase 3：支持 action 回传

Phase 4：支持 branch / variant

Phase 5：支持 prototype flow

14. 这件事做成后，我们的体验会怎么变

15. 下一步的最小可落地任务

16. 参考资料（本次在线调研）

Google 官方：Stitch

Google 官方：A2UI

17. 最终判断

19 KiB

Raw Permalink Blame History

8.1 `UiSurfaceSession`

8.2 `UiSurfaceBranch`

8.3 `UiSurfaceSnapshot`

8.4 `UiSurfaceAction`

8.5 `DesignSystemProfile`

10.1 新增 `SurfaceProvider`

10.2 新增 `SurfaceRenderer`

10.3 新增 `SurfaceCatalog`

10.4 新增 `PrototypePlayer`

10.5 新增 `SurfaceInspector`