UI Workflow API

UI Workflow 将对话式 UI 请求统一为 ui.workflow.v1 Input/Output。Phase 2 内置实现不依赖 AI：它通过 UI Source 创建或 CAS 更新安全 HTML，并返回可直接打开的 Document URL、ChangeSet 与缩略图状态。

认证与边界

同步执行、异步受理和运行查询仅接受 Agent Token：

Authorization: Bearer wna-...
Content-Type: application/json

Agent 必须属于 Input 的 scope.team_id，目标项目也必须属于该团队。普通用户 JWT、API Key、跨团队 Agent Token 均会被拒绝。请求体最大 1 MiB。

Input

{
  "contract_version": "ui.workflow.v1",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "operation": "create",
  "request": { "text": "创建一个订单确认页", "locale": "zh-CN" },
  "conversation": {
    "conversation_id": "conversation-uuid",
    "message_id": "message-uuid",
    "recent_messages": []
  },
  "scope": { "team_id": "team-uuid", "project_id": "project-uuid" },
  "target": null,
  "focus": null
}

Create 的 target/focus 必须为 null。Update 必须提供 target.document_id/source_revision/url，可用 focus.element_id 指定页面 Hash 定位。request_id 是端到端幂等键：完全相同的 Input 重放返回同一结果；首个 run 仍在执行时，重放只等待既有终态，不会第二次执行 Source 或缩略图；不同 Input 复用会返回 IDEMPOTENCY_KEY_REUSED。

同步执行

POST /ui-workflows/v1/echo

返回 contract Output，状态为：

• succeeded：Document、ChangeSet 与缩略图均成功。
• succeeded_with_warnings：Document/ChangeSet 已提交，缩略图失败或待补。
• failed：结构化失败；不会伪造成功网页卡片。

成功 Output 的 document.url 是 /o/{team}/p/{project}/ui?uiId={document} canonical URL，可追加合法 Element ID Hash；URL 不包含 Token 或 API Key。

异步受理与 callback

POST /ui-workflows/v1/runs

未完成时返回 202、result_url，并且只在本次响应头返回 run-scoped credential：

X-UI-Workflow-Callback-Token: uwcb_...
Cache-Control: no-store

数据库只保存 credential hash。credential 不会进入响应 JSON、URL、日志、ROMP 消息或 Document Output。

Provider 完成后回传：

POST /ui-workflows/v1/runs/{request_id}/result
Authorization: Bearer uwcb_...
Content-Type: application/json

callback body 包含同一 request_id/input_hash/output。服务端校验 credential、Input hash、Output schema 与 terminal 状态；完全相同的 terminal replay 幂等成功，不同结果返回 CALLBACK_RESULT_MISMATCH。

查询运行状态

GET /ui-workflows/v1/runs/{request_id}

只允许同团队 Agent 查询，返回 queued、running 或 terminal。terminal 时附带最终 Output。响应设置 Cache-Control: no-store。

常见错误

code	HTTP	retryable	含义
INVALID_WORKFLOW_INPUT	400	否	Input 或跨字段约束不合法
TOKEN_SCOPE_MISMATCH	403	否	Agent、team 或 project scope 不一致
WORKFLOW_RUN_NOT_FOUND	404	否	request ID 不存在
SOURCE_REVISION_CONFLICT	409	是	Update revision 已过期，未覆盖新内容
IDEMPOTENCY_KEY_REUSED	409	否	request ID 被不同 Input 复用
CALLBACK_UNAUTHORIZED	401	否	callback credential 缺失或无效
CALLBACK_INPUT_HASH_MISMATCH	409	否	callback Input hash 不一致
UI_SOURCE_TOO_LARGE	413	否	请求或 sanitize 后 HTML 超限

完整 schema、fixture 与错误注册表位于仓库 packages/shared/contracts/ui-workflow-v1/。

ROMP 内置用法

团队 Owner 在 Agent 设置中选择“UI Workflow”并指定目标项目即可，无需配置外部 Webhook。ROMP adapter 最多注入 20 条最近消息，把成功 Output 发布为一个摘要 text part 和一个标准 webpage part；重复触发使用确定性消息 ID 去重。