agent-exec-transportandCursor
f5417fb721
governance / governance (pull_request) Successful in 14s
Replace the NOT_RUN note in the deployment acceptance bullet with the rerun result on dev@5360884: the 10-12 API checklist passes (11 items, no model calls), run through a temporary genui-accept role and account that were disabled afterwards. Also record that project.create now comes only from roles, so admin cannot create projects until a role is assigned. Why: the upgrade record still listed the GenUI acceptance as NOT_RUN. Evidence: agent-exec unit documents-genui-prod-acceptance-20261021 (cursor, attempt 1, terminal=success); prod API replay VERDICT PASS on 2026-10-21. Impact: documentation only. Refs: Dev task fix/genui-prod-upgrade-followups. Co-authored-by: Cursor <cursoragent@cursor.com>
120 lines
7.6 KiB
Markdown
120 lines
7.6 KiB
Markdown
---
|
||
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；后续按「已知边界」清单演进。
|