打通多模态 UI 工作流与 Agent Runtime 路由
- 接入 Codex app-server 原生图片输入与隔离暂存 - 统一 UI 识别、合并、绑定到 Agent Runtime Provider - 增加页面自动发现、UI 资源桥接与阶段持久化 - 同步画布编辑器投影、测试与技术文档
This commit is contained in:
@@ -14935,3 +14935,10 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
|
||||
- AGC 工具：`agc_tools` 是唯一注入的外部工具桥，负责平台美术、资源、去背景、浏览器试玩和受控搜索；不把 legacy Runtime action、durable delegation 或 `platform-agent-harness` 变成 Codex 的第二持久化权威。
|
||||
- 安全：DirectProject 使用真实 `game/` writable root、`approvalPolicy=never`，原生命令网络保持关闭，联网资料继续走受控 `agc_web_search`；Codex 子 Agent、Apps、插件、hooks、图片生成、Goals、Workspace Dependencies、Tool Suggestion 与未审计浏览器/电脑控制继续关闭。配置了 AGC LLM Key 或可解析的 `OPENAI_API_KEY` 登录态时，真实 provider 凭据只留在 AGC 本地代理；前者仍走已配置上游，后者只走 OpenAI 官方 API，Codex 仅获得连接级随机代理令牌。无法安全代理的 OAuth `auth.json` 继续关闭原生 shell/unified exec。app-server 使用隔离 `CODEX_HOME`，shell 用 `shell_environment_policy` glob 排除 provider key、proxy、loopback bridge 和受控开关。
|
||||
- 上下文：Direct 系统提示词只保留身份、cwd、边界和 Skill 索引；不再预注入项目源码快照、项目提示词或 Skill 正文。浏览器工具回传结构化事实，不强制固定三次整改循环；Codex 自行解释证据并决定是否继续。sandbox writableRoots 不提供 deny-read，`.agent`/`../assets` 的不可读约束需靠行为合同和真实 smoke 验证。
|
||||
|
||||
## 2026-08-24 AGC UI 原型桥接与自主 UI workflow
|
||||
|
||||
- 决策：`ui-prototype` 图片与 `UI` JSON 编辑资源保持两种正式类型。Agent 通过受控 `ui.workflow.run` 按 `prepare -> recognize -> status -> finalize` 创建页面资源、关联源图、持久化 UI State 和 manifest 阶段；`recognize` 直接复用 UI Editor 的 provider-backed 结构识别、多树合并与组件绑定命令，按 `reference-ready -> structure-ready -> merge-ready -> binding-ready` 逐阶段写入并推进项目 revision。页面可显式关联已登记图片/图标和字体，图片/图标按 5 项一批绑定，字体安全元数据进入绑定上下文且未知引用失败关闭。Runtime 回执携带 `revisionAdvanceCount`；Provider 未配置、请求失败、工具调用缺失、结果不匹配、未产出可渲染组件或仍有待审节点时保留最近真实阶段，禁止用 deterministic seed 冒充语义处理完成。
|
||||
- 客户端：画布点击 `ui-prototype` 先幂等桥接到 `UI` JSON，并立即刷新 manifest；关联查找按 canonical resource identity 且优先已完成 workflow 资源。全部页面完成后，工作台自动打开首个页面的 UI 编辑器 `visual-binding` 最终阶段。
|
||||
- 完成门：`finalize` 必须为每个页面提供 `game/` 下真实 UTF-8 应用文件并安装当前 UI State revision 标记；缺少结构、组件、页面或标记时拒绝完成。详细输入、阶段与恢复契约见 [`docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md`](../../【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md)。
|
||||
- 验证：前端 bridge 6/6、资源实时集成 19/19、AppSurface 410/410、AGC typecheck、Rust workflow 定向测试覆盖 provider 前的 reference 阶段与真实调用失败关闭、Rust bridge 1/1、编码、格式和 diff 门禁通过；认证登录与真实 Provider 生成的桌面端 E2E 尚未具备可用会话，保持未验证。
|
||||
|
||||
@@ -1277,3 +1277,6 @@ game-project/
|
||||
本文早期关于“DirectProject 关闭通用 shell、原生网络和主动工具”的描述属于迁移前基线，现由以下覆盖规则取代：DirectProject 仅在真实 `game/` cwd 与 `workspaceWrite(writableRoots=[game])` 内恢复 Codex 原生文件/搜索/命令、图片查看和 Skill；其余 ToolHost/DirectHome 合同不变。客户端审核的 `agc_tools` MCP 继续承担平台美术、资源登记、去背景、浏览器试玩和受控搜索，并保留项目锁、幂等账本、下载校验、恢复与投影权威。
|
||||
|
||||
DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过泛化 ToolHost 包装；原生命令网络保持关闭，联网资料继续走受控 `agc_web_search`。多 Agent、Apps、插件、hooks、图片生成、Goals、Workspace Dependencies、Tool Suggestion 和原生浏览器/电脑控制仍关闭，避免绕过 AGC durable delegation、浏览器证据和副作用审计。app-server 使用隔离 `CODEX_HOME`，明确清空外部 MCP 后只注入 `agc_tools`；配置了 AGC LLM Key 或可解析的 `OPENAI_API_KEY` 登录态时，真实 provider 凭据只由 AGC 本地 provider proxy 持有，Codex 仅使用连接级随机代理令牌；无法安全代理的 OAuth `auth.json` 继续关闭 native shell/unified exec。shell 子进程采用 `shell_environment_policy` core 继承及 secret/proxy/bridge 排除，provider key 和桥接凭据不得进入命令环境。系统提示词不再预注入项目源码快照或 Skill 正文，Codex 按需读取当前 cwd 文件。
|
||||
## 2026-08-24 AGC UI 原型桥接与自主 UI workflow
|
||||
|
||||
- 2026-08-24 起，`ui-prototype` 与 UI 编辑器的 `UI` JSON 资源明确分离。设计图生成后必须由白名单 `ui.workflow.run` 按页面执行 `prepare → recognize → status → finalize`：为每个功能页面创建并关联 `UI` JSON，载入页面设计图和已登记图片/图标/字体，调用 UI Editor 的 provider-backed 结构识别、多树合并与分批组件绑定，持久化 State/revision，写入 `game/` 应用标记，并把 `reference-ready → structure-ready → merge-ready → binding-ready → application-ready → completed` 各阶段的 `generationKind` 和 manifest revision 投影给客户端。Provider 未配置、请求失败、工具调用缺失、结果不匹配、未知字体引用、未产出可渲染组件或仍有待审节点时保留最近真实阶段并返回 blocker，不得使用 deterministic seed 冒充完成。工作台点击 `ui-prototype` 时通过 `ensure_ui_design_resource_for_prototype` 幂等补齐关联资源；工作流完成后自动打开首个页面的 UI 编辑器 `visual-binding` 最终阶段，交给用户检查和手动调整。只生成图片、登记空 JSON 或进入普通图片画布均不构成 UI 工作流完成，详见 [`【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md`](../【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md)。
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
# UI 工作流资源桥接与 Runtime 执行
|
||||
|
||||
## 目标
|
||||
|
||||
`ui-prototype` 与 `UI` 是两种不同资源，不能通过修改投影 `subtype` 混为一种资源：
|
||||
|
||||
- `ui-prototype`：Agent 生成并登记到画布的界面设计图片。
|
||||
- `UI`：UI 编辑器使用的 JSON 资源，保存界面图、UI 树、组件绑定和 State revision。
|
||||
|
||||
自然语言生成链路必须把前者桥接为后者，并持续让 manifest 成为客户端资源投影的权威来源。游戏场景的页面清单由 Runtime 自动发现，Agent 不得凭空猜测页面。
|
||||
|
||||
## Runtime 工作流
|
||||
|
||||
Agent 通过白名单工具 `ui.workflow.run` 发起工作流。项目路径由 Runtime 注入，模型只能提交资源身份和页面描述，不能传入宿主路径。输入至少包含：
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "discover|prepare|recognize|status|finalize",
|
||||
"sourceAssetId": "ui-prototype manifest asset id",
|
||||
"pages": [
|
||||
{
|
||||
"pageId": "home",
|
||||
"title": "首页",
|
||||
"description": "页面用途和交互说明",
|
||||
"designAssetId": "页面设计图 manifest asset id",
|
||||
"spriteAssetIds": ["已登记的按钮、图片或图标 manifest asset id"],
|
||||
"fontAssetIds": ["已登记且可验证的项目字体 manifest asset id"],
|
||||
"applicationPath": "game/ui_home.gd"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`discover` 只需要 `sourceAssetId`，不推进 revision，也不创建资源。Runtime 先读取可选的 `game/ui-pages.json` 页面注册表；同时扫描设计阶段已生成的 `game/game_design.md`，以及实现阶段的 `game/index.html`、`game/game.js` 和 `game/style.css` 中的 `@genarrative-ui-page {JSON}` 声明。声明必须包含稳定的 `pageId`、标题、描述和 `game/` 下的 `applicationPath`，重复或越界输入直接拒绝。回执会按 `pageId` 排序返回 `requiredDesignAssetPath`（约定为 `assets/ui-pages/{pageId}.png`）和发现来源；design-foundation Agent 为每个页面生成并登记独立 `ui-prototype` 设计图后，才能继续 `prepare`。扫描器不会把一张 `ui-prototype` 图片冒充成多个页面，也不会凭空创建 UI JSON。
|
||||
|
||||
处理规则：
|
||||
|
||||
1. `prepare` 为每个页面创建确定性的 `kind=UI` JSON 资源，引用源 `ui-prototype` 和页面设计图，载入设计图尺寸与相对路径到 `ui_design_images`，并保存 State。
|
||||
2. `recognize` 依次执行 Provider 多模态结构识别、现有多树合并器、最多每批 5 项的图片/图标组件绑定，并把已登记字体的安全元数据提供给绑定器；阶段分别持久化为 `structure-ready`、`merge-ready`、`binding-ready`，重复执行从最近真实阶段恢复。
|
||||
3. `status` 只回读 State、页面阶段和 blockers，不推进项目 revision。
|
||||
4. `finalize` 只接受 `game/` 下的真实 UTF-8 文件，写入与 UI State revision 绑定的应用标记；所有页面通过应用门禁后才返回 `visual-binding` 最终阶段路由。缺少页面、资源、组件或应用标记时拒绝伪造完成。
|
||||
|
||||
每次 State 或 manifest 阶段变化都推进项目 revision。Runtime 回执带有 `revisionAdvanceCount`，用于并发项目 revision 门禁；manifest 资产的 `source.generationKind` 依次记录：
|
||||
|
||||
```text
|
||||
ui-workflow.reference-ready
|
||||
ui-workflow.structure-ready
|
||||
ui-workflow.merge-ready
|
||||
ui-workflow.binding-ready
|
||||
ui-workflow.application-ready
|
||||
ui-workflow.completed
|
||||
```
|
||||
|
||||
最终回执写入 `.agent/ui-workflows/<source-hash>.json`，客户端可据此恢复页面清单和最终编辑器路由。
|
||||
|
||||
`recognize` 现在直接复用 UI Editor 的 provider-backed `recognize_ui_impl`、`merge_ui_impl` 与 `bind_components_impl`：先对页面设计图执行多模态结构识别，再落盘合并后的唯一页面树，最后按 5 项一批绑定已登记图片/图标，并向模型提供 State 内已验证字体的 ID、family、face、weight 与 style。由 Agent Runtime 调用时，这三个阶段携带当前 `agent_id/run_id`，统一走活动 Provider 的 mode、请求快照、重试和恢复链路，不再从工作流偷偷创建另一套传统 HTTP client。Codex app-server 会把输入图片暂存到该连接的隔离工作区 `input-images/`，通过原生 `localImage` 输入发送；文本提示只保留图片占位符，避免把 base64 复制进提示词或 JSON-RPC。所有 LLM 工具参数仍沿用 UI Editor 的严格 schema、节点/深度/素材和字体白名单及有界输入校验。Provider 未配置、请求失败、工具调用缺失、结果不匹配、未知字体引用、绑定没有可渲染组件或仍有 `NeedReview/Blocked` 时，完成阶段不会推进；已落盘的中间阶段仍通过 manifest invalidation 更新客户端，不再使用 deterministic seed 冒充语义处理通过。
|
||||
|
||||
## 画布跳转与客户端更新
|
||||
|
||||
点击画布中的 `ui-prototype` 时，工作台调用 `ensure_ui_design_resource_for_prototype`：
|
||||
|
||||
- 按 manifest asset id、`source.resourceId`、`source.assetObjectId` 识别已有关联，避免重复创建。
|
||||
- 没有关联时原子创建 `ui/UI 设计 N.json`，登记 `kind=UI`、`application/json`，并把原型图作为首张页面设计图载入 State。
|
||||
- 成功后通过 `onManifestChange` 更新客户端资源投影，再打开 UI 编辑器；普通桥接从 `reference-analysis` 开始。
|
||||
|
||||
点击已有 `UI` 资源直接打开 UI 编辑器。若 manifest 阶段为 `ui-workflow.completed`，工作台自动打开该资源的 `visual-binding` 阶段（最远步骤为 2），交给用户做最终检查和手动调整。
|
||||
|
||||
## 诚实完成门禁
|
||||
|
||||
`ui-prototype` 图片登记、UI JSON 创建、页面 State 保存、结构树生成、游戏应用标记和最终路由是不同证据。Agent 只有拿到所有页面的 `completed` 状态与 `finalStageRoute` 才能报告完成；只生成图片、只创建空 JSON、只写计划或只打开普通图片画布均不算完成。
|
||||
Reference in New Issue
Block a user