---
title: Generative UI usage guide and U1-U6 evaluation record
date: 2026-10-12
type: feat
revision: r1
status: final
product_contract_source: generative-ui-r2
---

# Generative UI 使用说明与 U1–U6 评测记录

本文是主记录 r2（2026-10-10-generative-ui-plugin.md）的配套文档：面向使用者的启用/使用/
禁用说明，以及 U1–U6 各增量落地后的组合评测结论。状态：**final**（方向收口稿）。

## 一、使用说明（dev 实例实测口径，2026-10-12）

### 启用与禁用（owner 级）

```bash
# 启用（需 API key；服务以 --auth on 运行）
curl -X POST http://<host>/api/plugins/generative-ui/activation \
  -H "Authorization: Bearer <key>" -H "Content-Type: application/json" \
  -d '{"enabled":true}'
# 禁用（新页面/新动作/迟到提交全部拒绝；历史页面保留只读）
curl -X POST ... -d '{"enabled":false}'
```

- 启用后 `generative-ui.present` 工具对模型可见（禁用时工具不注入）。
- 禁用即时生效：进行中的提交按 epoch 失配被拒，已保存页面按权限保留。

### 生成与修订页面（对话内）

对话中说「把 X 整理成一页对比 / 报告页 / 时间线」——模型调用 present 提交声明式页面：
- 页面自动在**文件预览区**打开；修订时说「改为按 Y 组织」，模型带 surfaceId+baseRevision 重提。
- 表单页可直接填写并点「提交」按钮（数据落插件台账，走命令总线审计）。

### 任务工作区（U6）

- **工作**入口的当前任务卡下方出现「任务页面」紧凑区：默认显示最新一页；📌 固定后
  新页面不抢占；↗ 跳转文件预览全屏。
- 项目级跨会话聚合：`GET /api/projects/{id}/surfaces`（owner 作用域）。

### API 速查

| 端点 | 说明 |
|---|---|
| POST /api/plugins/{id}/activation | 启禁（epoch 递增） |
| POST /api/surfaces | 提交页面（直接 API，与插件同咽喉） |
| GET /api/surfaces/{id} | 读取整页快照（禁用后仍可读） |
| GET /api/conversations/{id}/surfaces | 会话内页面列表 |
| GET /api/projects/{id}/surfaces | 项目级跨会话聚合（U6） |
| POST /api/surfaces/{id}/actions | 页面动作（白名单：generative-ui.submit、builtin.help、system.intent；后者 button 只读匹配） |

## 二、U1–U6 落地与评测结论

| 增量 | 交付 | 关键证据 | 结论 |
|---|---|---|---|
| U1 受控试验 | Documents #62（r2） | R1 分化 6/6；文本通道下界 60%/83%；工具通道探针消除语法类失败；M3 ¥0.067/页；highspeed 否决为生成档 | 方向成立，生成走工具参数通道 |
| U2 契约/启禁/持久化 | Core #25/#26、Backend #143/#146、Dev #336 | 修订 1→2 冲突守卫、epoch 语义、事件恢复、SQLite/PG 双档 | 宿主地基就位 |
| U3 插件与上下文闭环 | Backend #149、Dev #345 | 真实模型回放 PASS（≈¥0.08）；禁用不注入工具；语义投影回灌 | 模型可提交、可修订 |
| U4 只读渲染与恢复 | Core #27/#28、UI #42–#45、Frontend #53、Dev #351 | 刷新恢复、revision 守卫、SurfaceView | 页面用户可见 |
| U5 动作闭环 | Backend #155、UI #46/#47、Frontend #56、Dev #367 | 幂等同参回放/异参拒绝、DangerHigh 经确认卡不可伪造、草稿只在动作载荷 | 表单可提交且受控 |
| U6 工作区与项目聚合 | Backend #163、Frontend #62、Dev #408 | owner 隔离/跨 owner 零可见/禁用保留；pin 固定不抢占 | 页面进工作视图 |

### 现场体验驱动的修复（2026-10-11–12）

用户实测反馈「页面未出现 + 同名工件 ×3」→ 三个根因逐一修复（Backend #156/#160、
Frontend #58/#59，Dev #381/#382/#387/#388）：工具描述缺「何时用」引导、事件分支缺
右栏切换、children 对象形状偏差、面板同名并列。修复后 E2E：真实模型 present 成功
（rev 1），surfaces 表落库，前后对照成立。

### U7 组合验收（2026-10-12，dev@b634a27，真实 MiniMax-M3）

- 会话内：新指令「实施进度页」→ 模型自主 present（steps 步骤条、三阶段、状态正确），
  会话 surfaces = 2（对比页 rev1 + 进度页 rev1），修订链完整。
- 项目聚合：GET /api/projects/{id}/surfaces 返回跨会话页面（owner 作用域验证）。
- 工作区：前端「任务页面」容器显示最新页（pin/follow 测试覆盖）。
- 收据：Dev 任务卡 feature/generative-ui-u7-acceptance（SELF；CI GATE 随发布 PR）。

### 现场体验驱动的修复记录

| 日期 | 症状 | 修复 | PR |
|---|---|---|---|
| 2026-10-12 | `POST /api/surfaces/{id}/actions` 对无确认卡的 committed 动作 panic（nil Card） | dispatcher 空指针守卫 | Backend#173 |
| 2026-10-12 | `system.intent` button 动作恒报 missing text | action data 键上浮到命令 params | Backend#174 |

## 已知边界与后续项

- 自动触发 opt-in：settings `plugins.generative-ui.autoPresent`（默认关；须同时
  Surface activation）；语义事件 + 预算≤3/时 + 冷却≥60s；设计见
  `2026-10-12-generative-ui-auto-trigger.md`。
- B 类命令：已加白 `builtin.help` / `system.intent`（button 入口 intent 只读匹配、
  不嵌套分发；提案 `2026-10-12-generative-ui-bclass-help-intent.md`）；其余仍逐条评审。
- 人类可用性对照以 owner 实际使用替代（2026-10-11 用户裁定），本轮体感「初步不错」，
  小问题另行修复。
- 部署与运行验收：2026-10-12 本机 `prod`（127.0.0.1:8787，`--auth on`，PG `pg1/prod`）
  两刀部署至 `dev@b4649d7`（含 Backend#173/#174）；验收覆盖启禁、present、B/C 类动作、
  项目聚合、未登录 401。2026-10-21 经用户授权升级至 `dev@5360884`，库 schema v25→v51
  （升级前已备份 PG 与运行目录，并在库副本上完整演练）；`prod` 与 `pg1` 均由 Dev 主检出
  `scripts/svc.sh` 管理（`runtime/prod`、`runtime/pg1`），DSN 只经环境变量
  `AGENT_SYSTEM_DSN` 交付、不进命令行。开启认证需超级管理员：账户 `superadmin`，凭据文件
  `runtime/prod/super-admin.env`（0600），`deploy/start/restart` 时以 `AGENT_SYSTEM_ENV_FILE`
  指向该文件（svc 不持久化该凭据，缺失时服务拒绝启动）；原 `admin` 账户保留。升级后验证
  healthz/readyz/UI 200、superadmin 登录、未登录 401。2026-10-21 在 `dev@5360884` 上按
  10-12 清单重放 GenUI API 验收，结果 PASS（11 项：登录、未登录 401、`autoPresent` 默认关、
  建项目与会话、present 201、`builtin.help`/`system.intent`/`generative-ui.submit` 动作 200、
  未知动作 400、项目聚合 200、禁用后 403）；不调用模型、无费用。执行方式：用 `superadmin`
  建临时角色 `genui-accept`（仅 `project.create`）与同名临时账户执行，验收后账户与角色均已
  停用，验收产生的项目/会话/页面留在该账户名下。发现：新版本 `project.create` 只来自角色
  （管理员标记与系统授权都不授予），prod 升级后没有可用的业务角色，`admin` 目前不能新建
  项目，需按使用需要在管理区建角色并分配。
  经验：schema v27 之前的旧库经 svc 部署前，须先以候选二进制执行 `agent-system migrate`
  （svc 身份门禁的 identity ensure 不做迁移）。

## 三、结论

Generative UI 方向按主记录 r2 的 U1–U7 全部增量落地：调研→契约→生成插件→只读渲染→
动作闭环→工作区→组合验收，每个增量独立走组件 PR + Dev 组合 CI + 任务闭环，真实模型
证据贯穿（试验、回放、现场 E2E）。方案收口为 final；后续按「已知边界」清单演进。