Files

T

weichen e39d327850 Record GenUI prod-acceptance action fixes on the usage guide

Why: Capture nil-card panic and intent data-flatten field fixes found
during local prod acceptance without revising the final closure verdict.
Evidence: Backend#173 #174; prod action checklist
Impact: Field-fix log lists the two hotfixes and their PRs.
Refs: GenUI prod deploy; fix track

2026-10-12 04:17:07 +00:00

6.0 KiB

Raw Blame History

title, date, type, revision, status, product_contract_source

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

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

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

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

启用与禁用（owner 级）

# 启用（需 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 用户裁定），本轮体感「初步不错」，小问题另行修复。
部署与运行验收：本机 prod 实例已登记（scripts/svc.sh prod，--auth on， PG pg1/prod，来源 dev@c76f2bb+后端 nil-card 修复）；验收覆盖启禁、present、 B/C 类动作、项目聚合、未登录 401。

三、结论

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

6.0 KiB Raw Blame History Unescape Escape