从 Codex Desktop 到数字人控制台：布局怎么借，Assistant UI × Mastra 怎么接

Codex Desktop 的核心布局逻辑，是把“任务选择、任务执行、变更验收”拆成不同层级。项目与 thread 负责在多个长期任务之间切换；thread 主区保留用户目标、Agent 进展、工具行为和追问；diff、文件、终端或浏览器结果则作为可检查的工作表面出现。Composer 固定在任务上下文内，所以用户追加要求时，不需要重新解释仓库、分支和当前阶段。

这套布局真正值得借鉴的是稳定视线顺序：先在任务列表判断哪件事需要关注，再进入 thread 看当前进度，最后打开产物或 diff 做验收。高频导航保持窄而稳定，长文本占据主阅读宽度，复杂产物获得更大的独立表面。它没有强迫消息气泡同时承担导航、执行日志、文件预览和审批。

数字人控制台要复刻的是这套空间关系，而不是配色和像素。左侧回答“我有哪些任务”；中间回答“当前任务发生了什么”；产物区回答“Agent 交付了什么”；右侧 Inspector 回答“这一步基于什么上下文、参数和权限”。四个问题稳定占据四类表面，用户才不必在一条无限消息流里寻找状态。

Codex 的左侧项目 / thread 列表，对应数字人的栏目、人物和生产任务。第一层可以是人物或内容项目，第二层是具体 run，例如“7 月新品口播”“直播切片批处理”。列表项固定展示任务阶段、阻塞状态、最近活动和负责人；等待审批、执行失败、后台运行使用不同但克制的信号。切换任务后恢复原滚动位置、选中产物与侧栏状态。

中间 Thread 对应协作主线，但应从聊天升级为事件叙事。用户要求、Agent 阶段摘要、关键 Tool UI、审批请求和最终交付按时间排列；连续的搜索、转码或渲染调用折叠为一个 step group。底部 Composer 除文本外，还要支持素材附件、@人物设定、工作模式、暂停当前 run 和 follow-up，让“继续改”明确作用于当前任务。

Codex 的 Diff / 文件检查表面，在数字人场景中应变成 Artifact Workspace。脚本使用逐段 diff，视频使用时间轴与画面预览，声音使用波形与试听，图片使用版本对比，发布任务使用渠道预览。用户点击时间线节点时，Thread 定位到相关消息，Artifact 定位到对应版本，Inspector 展示这一步的输入、来源和审计信息。

桌面端可以从 280px 任务栏、minmax(560px, 1fr) 主工作区、360px Inspector 起步。主工作区内部再分为固定高度的 Task Header、可滚动的 Thread / Artifact Surface 和底部 Composer。Task Header 只放任务名、当前阶段、运行环境、总状态以及 Pause / Resume / Review 等主动作，不要塞满统计卡。

默认状态下，主工作区以 Thread 为主；打开脚本、视频或生成式界面后，切成 Thread + Artifact 的 40/60 分屏。Artifact 是任务的一级工作表面，不是消息气泡附件。Inspector 可以收起，但等待审批时应自动打开相应面板；原始日志默认折叠，保持 Codex 那种“进展可见、噪声后置”的密度。

窄于 1180px 时先把 Inspector 变成抽屉，保住任务栏和主工作区；窄于 760px 时任务栏变成任务选择 Sheet，Artifact 使用全屏二级页面，Composer 保持底部固定。响应式变化只能改变表面位置，不能改变事件含义和审批优先级。

第一，任务列表不是导航菜单，而是运行状态面板：未读变化、等待用户、后台执行和失败必须能在进入任务前被判断。第二，Composer 属于当前 thread，附件、follow-up、停止和重新执行都继承同一个任务上下文。第三，工具过程按阶段摘要，用户先看结论，需要审计时再展开命令、日志和参数。

第四，产物与对话保持双向定位。消息中的“已修改脚本第 3 段”应能打开 Artifact 对应版本；用户在 Diff 上评论，又应回到同一个 run 形成 follow-up。第五，审批是执行链中的暂停点，不是通用弹窗：它要保留触发它的步骤、目标对象、影响范围和批准后的继续位置。

因此所谓“参照 Codex 设计”，可以被写成可验收条件：切换任务不丢上下文；十秒内识别阻塞任务；消息、事件和产物能互相定位；高风险动作在原步骤暂停并恢复；复杂输出拥有独立工作面，而不是全部塞进聊天气泡。做到这些，比复刻暗色主题、圆角和按钮位置更接近 Codex 的产品设计。

Mastra 位于服务端执行层：Agent 组合 model、instructions、memory 和 tools，workflow 承载确定性的多步骤编排，evals 与 observability 检查运行质量。Assistant UI 位于客户端交互层：runtime 管理 thread、message parts、composer、附件、tool 展示、运行状态和用户动作，primitives 决定这些状态最终如何渲染。

两者之间没有一个神奇的 @assistant-ui/react-mastra runtime package。官方推荐链路是 Assistant UI 的 useChatRuntime 使用 AI SDK adapter；API route 调用 Mastra 的 agent.stream(messages)；@mastra/ai-sdk 的 toAISdkStream 将 Mastra-native stream 转成 AI SDK UI message parts；createUIMessageStreamResponse 再把它作为流式 HTTP 响应返回前端。

因此边界非常清楚：Mastra 决定 Agent 能做什么，Assistant UI 决定用户能看到什么、能操作什么。Memory、workflow 和 eval 不会自动在前端长出面板；如果数字人控制台需要任务阶段、费用、产物或审批，就要把这些事实转换成标准 message part、data part 或应用事件。

用户在 Composer 输入文本、添加素材或设置 run config 后，Assistant UI runtime 通过 useChatRuntime 发起请求。API route 读取 messages 和业务上下文，定位 Mastra Agent，然后调用 agent.stream。Mastra 在生成过程中可能依次产生 text、reasoning、tool call、tool result、error 等 stream part。

toAISdkStream 是关键适配层：它把 Mastra stream 转成 AI SDK v6 形状；createUIMessageStream 把各 part 写入同一条 UI stream；前端 runtime 合并增量并更新 thread。文本增量进入 Text part，工具调用进入 Tool part，错误进入 Error 状态，运行结束后 Assistant UI 才解除 isRunning。

数字人业务事件不要藏进自然语言。脚本版本、素材选择、渲染进度、发布审批等数据需要稳定的 runId、stepId、toolCallId 和 artifactId。可以在 Mastra tool / workflow 中写入事件库，再通过 data part 或独立订阅投影到任务时间线和 Artifact 面板。聊天流负责叙事，事件存储负责恢复与审计。

基础消息能力包括流式 Text、Reasoning、Tool Call、Error、附件与自定义 Message Part；Thread 提供消息列表、自动滚动、空态、suggestion 和运行状态；Composer 提供发送、取消、附件、编辑模式、引用、语音输入以及发送条件控制。编辑历史消息、重新生成和 Branch Picker 可以把一次修改保留为分支，而不是覆盖原上下文。

运行时能力包括 single thread、远程 thread list、history adapter、attachment adapter、feedback、speech、dictation、suggestion 和 model context。ThreadRuntime 还暴露 send、cancel、setRunConfig、addAttachment、queue、dictation 等动作。需要注意：UI primitive 只提供交互外壳，对应 adapter 或 callback 没接入时，持久化、语音、上传和反馈不会凭空工作。

Agent 产品最重要的是 Tools：Assistant UI 可以按 tool name 注册专用 renderer，读取 args、result、status 和 error，把未知工具降级到 ToolFallback。Toolkits 还能把 schema、execute、streamCall 和 render 组织在一起；Interactables 则让用户与模型共同读写应用级面板或 thread 内组件，适合任务板、脚本编辑器、素材选择器和参数面板。

第一类是自动执行工具。Mastra Agent 决定调用 searchAssets、generateScript 或 renderVoice，Assistant UI 根据 tool name 渲染业务组件：参数仍在流式生成时显示 input-streaming，执行中显示阶段，完成后展示结构化 result，失败后保留原参数并提供安全重试。

第二类是 Human in the Loop。对人物替换、付费渲染、账号发布等高风险工具，服务端不能先执行再补确认。Mastra workflow 或 tool policy 应暂停 run，返回结构化的 approval 请求；Tool UI 展示意图、目标、影响范围、费用和可撤销性，用户批准、修改或拒绝后，把 action 与 toolCallId 回传，服务端鉴权并 resume 原 run。

第三类是客户端工具或 human tool。它们不一定在 Mastra 服务端直接执行，而是要求浏览器打开选择器、读取当前工作台状态或让用户填写表单。Assistant UI 负责组件和回调，Mastra 只看到经过校验的 tool result。边界必须明确：客户端不得把任意 tool args 当作 URL、HTML 或代码直接执行。

Assistant UI thread 是交互会话容器，默认可以只是内存状态；Mastra memory 是 Agent 在后续推理中读取的上下文能力；数字人 production task 则是业务实体，拥有阶段、产物、审批和负责人。三者可以关联，但不能共用一个 ID 或把任一方当成另外两方的数据库。

推荐保存 threadId ↔ taskId ↔ Mastra memory resource/thread 的显式映射。Assistant UI 的 thread list 负责导航与标题，history adapter 恢复消息；任务服务恢复 run、step、artifact 与 approval；Mastra memory 为 Agent 取回人物偏好、历史决策和必要上下文。刷新页面时先恢复业务任务，再让 runtime 加载消息，而不是仅靠最后一段聊天推断状态。

取消也要区分层次：Composer cancel 停止当前前端 run，不代表外部渲染工具一定取消；Mastra 需要将 abort signal 传递给可取消步骤，并把无法取消的后台任务标成仍在执行。界面应分别显示“停止接收”“正在取消”和“执行已终止”。

已知业务交互优先使用 Tool UI：模型选择工具，客户端使用稳定 React 组件渲染，最容易校验、审计和埋点。需要用户与 Agent 共同编辑一个长期存在的组件状态时，使用 Interactables；应用级 Interactable 可以放在侧栏或 Artifact 工作区，thread-scoped Interactable 可以随 tool call 出现在消息中。

当界面结构也需要由 Agent 动态组合时，再考虑 Assistant UI 的 Generative UI 或 A2UI。它们都应限制在客户端允许的组件 Catalog 中，并对 props、action、URL 与权限做 schema 校验。不要让 Mastra 返回任意 JSX、HTML 或 JavaScript 直接进入宿主应用。

A2UI 更适合跨 Agent、跨语言或跨端传递声明式 surface；Assistant UI 则是具体的 React 交互运行时和组件体系。两者不是替代关系：Mastra 可以生成 A2UI payload，Assistant UI 工作台中的专用 surface renderer 消费它，但第一阶段通常用 Tool UI 与 data part 已经足够。

主工作区由 Assistant UI Thread 与 Composer 承担自然语言协作；Tool UI 在消息中展示搜索、脚本、语音和渲染步骤；Artifact 工作区承载可编辑脚本、音频波形、视频预览和版本 diff；任务时间线消费业务事件；右侧 Inspector 展示人物设定、素材来源、费用、权限与审批详情。

同一个 Mastra tool call 可以有多个投影，但只有一个事实来源：消息流显示可读摘要，时间线显示执行节点，Artifact 打开结果，Inspector 展示参数和审计信息。所有投影使用同一个 toolCallId / artifactId，避免四个区域各自维护 loading。

这里不是把 Codex 降级成一句“布局启发”，而是用 Assistant UI 和 Mastra 把前文拆出的结构做出来：Thread 承接协作叙事，Artifact / Diff 验收产物，任务列表切换长期工作，Inspector 读取同一 run 的上下文和审计数据。Mastra stream 进入 Assistant UI 后，每一种事件都应落到这些明确的工作表面。

第一阶段打通 text streaming、一个只读 Tool UI、一个产生结构化结果的 Tool UI、一个 approval + resume、thread history 和 cancel/error 六条链路。每条链路都要验证刷新恢复、重复事件、失败重试和权限校验。

第二阶段增加附件上传、远程 thread list、Mastra memory 映射、任务时间线与 Artifact；第三阶段再评估 voice、Interactables、Generative UI、A2UI 和 sandboxed code artifact。这样不会在基础事件契约尚未稳定时同时维护多套动态 UI 协议。

验收时逐项回答：Mastra 产生了哪个 stream part？Adapter 把它变成什么 UI part？Assistant UI 用哪个 renderer 展示？用户操作调用哪个 callback？服务端如何鉴权并恢复 run？页面刷新后从哪里重建？六个问题都有明确答案，交互链路才真正闭环。