Voyager 业务线学习：Agent 页面写入契约与图片交付语义

source_automation: voyager-merged-pr run_date: 2026-07-29 anchor_pr_number: 5294 pr_number: 5294 pr_title: “refactor(agent): unify the page write surface behind update_page” pr_url: https://github.com/adastralab-ai/voyager/pull/5294 ↗ author: “Horcrux (@magicismight)” merged_at: “2026-07-28T15:21:50Z” modules:

• backend/workers/agent/src/tools
• backend/workers/agent/src/agent.ts
• backend/workers/agent/src/agentProfile.ts
• backend/workers/agent/src/designAction.ts
• backend/workers/agent/src/gen/skillsBundle.ts
• agent-eval
• packages/common/src/agentChat
• packages/site/src/app/(main)/_agent/chat files_changed: 48 changed_files:
• agent-eval/README.md
• agent-eval/asserts/pages.ts
• agent-eval/asserts/trajectory.ts
• agent-eval/cases/behavior/failure-phrasing.yaml
• agent-eval/cases/design/commit-failure.yaml
• agent-eval/cases/design/creation-directive.yaml
• agent-eval/cases/design/format-switch.yaml
• agent-eval/cases/design/whiteboard-edit.yaml
• agent-eval/cases/doc/create.yaml
• agent-eval/cases/doc/write.yaml
• agent-eval/cases/image/generation.yaml
• agent-eval/cases/image/image-mode.yaml
• agent-eval/cases/route/sticky.yaml
• agent-eval/mocks.ts
• backend/workers/agent/src/agent.ts
• backend/workers/agent/src/agentProfile.ts
• backend/workers/agent/src/designAction.test.ts
• backend/workers/agent/src/designAction.ts
• backend/workers/agent/src/exportApi.ts
• backend/workers/agent/src/gen/skillsBundle.ts
• backend/workers/agent/src/prompts.ts
• backend/workers/agent/src/routes/agentEval.ts
• backend/workers/agent/src/skills/document/SKILL.md
• backend/workers/agent/src/skills/edit-design/SKILL.md
• backend/workers/agent/src/skills/generate-webpage/SKILL.md
• backend/workers/agent/src/tools/elementFragments.ts
• backend/workers/agent/src/tools/htmlPipeline.ts
• backend/workers/agent/src/tools/index.ts
• backend/workers/agent/src/tools/insertPageTool.ts
• backend/workers/agent/src/tools/loadCreationTargetTool.test.ts
• backend/workers/agent/src/tools/pageCommitFailure.test.ts
• backend/workers/agent/src/tools/pageCommitFailure.ts
• backend/workers/agent/src/tools/readElementsTool.ts
• backend/workers/agent/src/tools/snapshotTool.ts
• backend/workers/agent/src/tools/toolDefs.ts
• backend/workers/agent/src/tools/updateCodeTool.ts
• backend/workers/agent/src/tools/updateDesignTool.ts
• backend/workers/agent/src/tools/updateDocTool.ts
• backend/workers/agent/src/tools/updateElementsTool.ts
• backend/workers/agent/src/tools/updatePageTool.test.ts
• backend/workers/agent/src/tools/updatePageTool.ts
• packages/design-html/src/designToHtml/roundTrip.test.browser.ts
• packages/site/src/app/(main)/_agent/chat/_components/AgentChat.stories.tsx
• packages/site/src/app/(main)/_agent/chat/_lib/agentUiSchema.ts
• packages/site/src/app/(main)/_agent/chat/_toolPart/_components/ToolPartPrimitives.stories.tsx
• packages/site/src/app/(main)/_agent/chat/_toolPart/_lib/parts/goToPage.tsx
• packages/site/src/app/(main)/_agent/chat/_toolPart/_lib/parts/nodes.tsx
• packages/site/src/app/(main)/_agent/chat/_toolPart/_lib/toolPartRegistry.tsx learning_tags:
• agent-runtime
• page-write-contract
• read-write-semantics
• replace-merge
• whiteboard-safety
• design-html-roundtrip
• image-delivery
• ephemeral-ui-state
• backward-compatibility
• agent-eval
• billing-boundary business_line: “Agent 页面写入契约与图片交付语义” related_prs: [5222, 5295, 5293, 5333, 4979] related_prior_prs: [5143] line_stage: “图片目标解析与落页 -> 生成后强制交付 -> 生成中 slot 预留 -> update_page 统一写入契约 -> redo 追加新图 -> canvas background 往返修复” open_questions:
• “update_page 在 worker 侧先 fetchPageWithAllDeltas 再 submitPageDelta，提交体只携带 delta；服务端是否有足够的版本/协同保护来避免 stale read 下的覆盖，需要真实并发编辑验证。”
• “replace 对 video、image adjustments 或 clip timing 等 HTML 无法表达的背景状态仍可能有损；#4979 将背景从销毁收敛为保留/告警，但没有建立 lossless editor path。”
• “merge 只允许按已有 data-canvas-background-id 原位改背景，不表达新增、删除或多背景层；这是否与白板背景的产品能力边界长期一致，仍待确认。”
• “writeMode 来自较早的 get_page_context/read_elements；执行时虽重新读取 page.type，但没有把读取版本或模式 token 作为写入前提，页面切换和长 turn 期间的 stale context 需要端到端测试。”
• “image slot 是客户端 session state，刷新会丢失；slot placement 失败会回落到 insert_image_node，需验证重连、Continue 和重复 tool call 不会产生重复节点或悬挂占位。”
• “#5333 的 redo eval 在修复后连续 8 次为绿，但修复前复现概率只有 1/3；需要更确定性的轨迹/seed 或线上行为监测。”
• “历史 tool alias 保留了 UI 卡片和打开页面能力，但失败旧提交回放会失去 pageCommitToModelOutput 的不要重试指令；需要确认一次自纠 tool-error 的成本和可观测性可接受。” feishu_doc_url: null github_repository: joyehuang/ai-agent-field-notes github_path: outputs/voyager-daily-pr-study/2026-07-29-pr-5294-agent-page-write-surface-image-delivery.md github_commit: e2190ca51daa6da7da951f51650a9f561339b551 voyager_merge_commit: ad2dbdbfe1357277714469ff22df4c450b61c91e

业务线概览#

这条业务线解决的是 Agent 把用户意图落到 Voyager 页面时，读到的内容形态、选择的写入工具和最终持久化结果必须保持一致。范围覆盖常规 DESIGN、白板、DOC、CODE，以及独立图片生成后的画布交付。用户侧表现是“改页面”“把图放到画布”“重新生成一版”；工程侧真正要守住的是 pageId、页面类型、HTML 中间表示、page delta、Undo 记录和聊天 transcript 之间的边界。

锚点 #5294 之前，页面写入工具按两条轴增长：design/doc/code 是一条轴，整页/元素片段是另一条轴。模型只能靠描述里的互相指路猜该调哪个工具；更危险的是白板只返回当前 viewport 附近的片段，如果按整页语义提交，缺失的屏外节点会被误当成删除。#5294 将这条契约收束为“读取结果携带 writeMode，写入工具只表达 update_page”，而图片链则继续保留 image node 专用工具，因为图片资产、位置、slot 和 redo 有独立语义。

本次学习的单位不是一个孤立的工具重命名，而是同一条能力线的工程演进：先解决图片落到正确页面，再把等待中的位置变成客户端状态，随后统一页面写入和 round-trip 保护，最后用 eval 把“redo 是新增图、移动才更新旧节点”钉成行为边界。

今日锚点#

选择 #5294 还有一个实际理由：它的关联关系能由真实代码闭环，而不是标题相似。#5222、#5295、#5293 都直接触及图片如何找到 page、何时写入以及是否必须交付；#5333 继续约束 insert_image_node 与 update_image_node 的边界；#4979 则在锚点之后直接修复 update_page 的 canvas attribute round-trip。

演进时间线#

上述 6 个 PR 的 merge commit 都已用 git merge-base —is-ancestor 对当前 origin/main 验证。时间窗口遵循 Melbourne 今天优先；#5294 是今天窗口内适合做架构锚点的 PR，#5320 昨天已经作为锚点学习过，因此没有重复选择。

当前架构与数据流#

flowchart LR
  A["用户消息 / pageId"] --> B["get_page_context 或 read_elements"]
  B --> C["读取完整页或 viewport fragment"]
  C --> D["writeMode: replace / merge / absent"]
  D --> E["update_page discriminated schema"]
  E --> F["按 page.type 选择 DOC / CODE / DESIGN delta"]
  F --> G["Go pageServiceSubmitPageDeltas"]
  G --> H["agent-page-edit inverse delta -> HistoryManager"]
  I["image_generation"] --> J["holdImageSlot"]
  J --> K["image task / asset"]
  K --> L["placeImageInSlot 或 insert_image_node"]
  L --> G

1. worker 的 buildAgentTools 在 get_page_context 中先读取 page。常规 DESIGN 序列化完整 HTML 并返回 replace；白板只序列化 viewport fragment 并返回 merge；DOC 和 CODE 返回完整可写源并返回 replace；SHEET 仍可读但不返回 writeMode，因而模型不能把它伪装成可写页面。
2. 模型把读取时的模式原样带进 update_page。replace 的输入是 working file 的 htmlPath；merge 的输入是 inline html，或者只带 deleteNodeIds 的删除操作。这让“片段不能当整页”成为 schema 形状，而不仅是工具描述。
3. update_page 执行时重新 fetchPageWithAllDeltas。DOC 使用 docHtmlToReplaceDelta，CODE 对存储的 CodeValue 使用 getCodeDelta，DESIGN 经过 HTML pipeline 后按 replace 或 merge 组装 DesignValue，再由 diffDesignValues 生成 delta。merge 会保留省略节点；deleteNodeIds 会展开 group descendants；replace 对白板直接抛错，不提交任何 delta。
4. Go API 的 submitPageDelta 负责把 delta 包装成 page delta record。成功后 worker 广播逆向 delta；这条路径让 agent 写入进入客户端 HistoryManager，而不是只作为 SOURCE_REMOTE 同步，因而 Cmd/Ctrl+Z 有机会撤销它。
5. UI 侧的 update_page result 通过 editorType 生成中性的页面标题；旧的 update_design、update_html、update_elements、update_code、update_doc 作为 alias 仍能渲染历史 tool part 和“打开页面”按钮。模型/存储迁移是一次性收敛，兼容层被放在 tool registry，而不是让运行时继续维护五套 writer。
6. 图片链不把 standalone image 强行塞进 update_page。#5222 的 ImageDelivery 解析相关页、default canvas 和 viewport；#5293 的 slot 只广播暂态 UI，不写文档；成功后仍提交单个 image node。这样 HTML round-trip 的整页/片段语义与图片资产的插入、重排、redo 语义保持分离。

关键代码#

1. 由读取结果决定写入形状#

来源：#5294，backend/workers/agent/src/tools/toolDefs.ts，diff hunk around lines 746-818。

write: z.discriminatedUnion("mode", [
  z.object({ mode: z.literal("replace"), ...wholePageWriteSchema.shape }),
  z.object({
    mode: z.literal("merge"),
    html: z.string().min(1).optional(),
    deleteNodeIds: z.array(z.string()).min(1).optional(),
  }),
])

replace 只能从 working file 提交完整页；merge 只能提交片段或显式删除。这个 schema 同时阻止了 fragment 误当 whole page，也让 delete-only write 不必制造一份无意义 HTML。

2. 白板的破坏性误用在 runtime 被拒绝#

来源：#5294，backend/workers/agent/src/tools/updatePageTool.ts:170-191。

if (write.mode === "replace" &&
    prevValue.attributes.presetId === "whiteboard") {
  throw new Error(
    'A whiteboard is read as a viewport window, not the whole canvas; ' +
    'use "merge" and name anything to remove in deleteNodeIds.',
  );
}

这条保护位于已经读取真实 page 内容的 worker，而不是只存在于 prompt。测试还验证了 submitPageDelta 在该分支不会被调用，因此不会返回“成功但页面没更新”的假结果。

3. merge 只合并读回来的元素，replace 才拥有整页属性#

来源：#5294，backend/workers/agent/src/tools/updatePageTool.ts:193-279；#4979 后续把 background 分支扩展到 backend/workers/agent/src/tools/elementFragments.ts:122-147。

const submitted = source ? await commitHtmlSourceAssets({...commitBase, ...source}) : undefined;
const parsed = submitted
  ? await runHtmlToDesignPipeline({
      html: submitted.html,
      canvasDimensions: write.mode === "replace"
        ? prevValue.attributes.dimensions
        : undefined,
      reuseExistingIds: true,
    })
  : undefined;

if (parsed && write.mode === "merge")
  nextNodes = reconcileElements(prevValue, parsed.designValue).nextNodes;

锚点先把 node omission 的语义分开；#4979 又证明 canvas-level attribute 也必须有同样的边界：replace 可以接收整页背景，merge 只能按已有 id 修改且对 HTML 无法承载的 video、adjustments、clip timing 保守告警。

4. 图片落点由 worker 解析，不让模型重复实现布局#

来源：#5222，backend/workers/agent/src/tools/imageDelivery.ts:45-76。

const target =
  (await load(relatedPageId)) ??
  (await load(context.defaultCanvas?.pageId));
if (target) return target;

context.canvasCreation ??= createDefaultCanvas(go, fileId, signal);
return context.canvasCreation;

page kind、默认载体和同一 turn 只建一次的规则集中在 ImageDelivery；insert_image_node 只提交最终 addNode，并广播 page focus 与 inverse delta。

5. slot 是“承诺的位置”，不是持久化节点#

来源：#5293，backend/workers/agent/src/tools/imageDelivery.ts:112-203；packages/common/src/agentChat/protocol.ts:117-130。

const slot = {
  slotId: request.slotId,
  pageId: target.pageId,
  bounds: claimImageBounds(context, target, requestedImageSize(request)),
  order: target.topOrder,
};
delivery.broadcastSlot(slot, "pending");

// later
await submitPageDelta(go, {pageId: slot.pageId, signal}, [addNodeAt(slot)]);
delivery.broadcastSlot(slot, "placed");

slotId 复用 image task idempotency key，重连/Continue 可以重新挂回同一个 promise。广播 envelope 只含 slotId、pageId、bounds、status；站点刷新会丢掉 pending slot，页面本身仍只保存真实节点。

6. redo 和 background 都把“语义边界”落成验证#

来源：#5333，backend/workers/agent/src/prompts.ts:281-284 与 agent-eval/cases/image/generation.yaml:55-87；#4979，packages/design-html/src/htmlToDesign/extractors/extractCanvasBackground.ts diff hunk around lines 76-97。

Delivery only ever adds: each generation is delivered as its own image
and never replaces an image delivered earlier.

对应 eval 要求 redo 同时使用 image_generation 和 insert_image_node，且不使用 update_image_node；#4979 则让 parser 优先查找 data-canvas-background-id，复用背景 id 并消费该元素，避免同一背景既进入 attributes.backgrounds 又作为顶层普通 node。

工程取舍#

设计边界#

• 工具名只保留动作：update_page 负责已有页面的 HTML/结构写入，insert_page 负责建页，insert_image_node/update_image_node 负责独立图片节点。page kind 从 pageId 和读取结果推导，避免 design/doc/code 的工具集合继续膨胀。
• replace/merge 不是两个 UI 模式，而是读回内容的完整性声明。完整页可以用 omission 表达删除；viewport/window 不能，所以 merge 把删除变成显式 deleteNodeIds，并把缺失节点保留下来。
• 白板不能 replace 是服务端不变量；白板上的图片移动仍走 update_image_node，因为 merge 片段不携带已有元素的完整 canvas coordinates。

兼容性#

• 旧 writer 名字在 update_page tool part 上保留 alias，历史消息不因运行时 schema 变化而无法渲染；新的 result 通过 editorType 再生成 design/document/page 标题。
• 这是一次性迁移，不做双发。代价已经写在代码路径里：历史失败 commit 回放时可能只剩 status=failed，失去 pageCommitToModelOutput 的不要重试提示；模型若抄回旧 tool name，会多一次 SDK tool-error 自纠。
• update_code(mode: “create”) 被移除，建页职责回到 insert_page；这减少 mode 组合，但也放弃旧的“从 CODE 页复制一份新页”入口，需要产品层明确使用 insert_page。

性能与资源#

• 常规设计页仍设置 200,000 字符上限，因为 replace 需要完整 round-trip；白板用 viewport fragment 控制输入规模，merge 不重新提交屏外节点。
• 图片生成前的 slot 将等待从“无页面状态”变成客户端可见状态，但不把未完成图片写进 page delta。并发图片通过 claimedSlots 占用位置，避免多个生成任务读同一 snapshot 后落到同一点。
• update_page 对 HTML 转换和资产提交保持已有 pipeline，避免为统一工具复制 DOC/CODE/Design 的持久化实现；统一的是入口和 mode，不是把三种存储格式强行变成一个 schema。

可靠性与测试策略#

• #5294 新增 updatePageTool 单测覆盖 delete-only merge、whiteboard replace 拒绝和 replace 不接受 inline HTML；agent-eval 新增 whiteboard-edit，断言 merge 和 deleteNodeIds。
• #5293 有 design image-slot 的几何测试，并在 client store 中明确 pending slot 只属于 session；#5295 和 #5333 用轨迹 eval 约束“生成后交付”“redo 新图/移动旧图”的选择。
• #4979 在 design-html 的 browser test 中验证显式背景 id、背景不重复成为 node，以及 crop 的 px round-trip；但其端到端验证仍依赖 export-worker 部署到 dev，不能把 parser 单测当成线上覆盖。
• 计费集合也跟着动作边界收敛：designAction 将 update_page、insert_image_node、update_image_node 统一视为 edit；DOC/CODE 的 edit floor 从 100 降到 5，但这两类功能由 workspace feature gate 控制，生产默认不可达。

和最近学习记录的关系#

最近的 #5143 报告学习了 Agent 图片节点 insert/update 的逆向 delta 和 Undo 接缝。本次不重复把“如何广播 removeNode/reverse delta”当作主线，而是把它放到统一写入契约里重新定位：update_page 的结构写入和 image node 的资产写入共享 page-edit/HistoryManager 接口，但不共享同一个 HTML 工具。#5293 的 slot placement 也复用同一逆向 delta seam。

上一轮 #5320 是 Export Workflow 的大页有界并行，属于导出任务的异步 runtime line，不是本报告的正式关联 PR。两条线的交点只是 page/design value 最终会被下游渲染读取；本次没有把导出性能结论外推为 Agent page write 已验证。

我会怎么吸收#

1. 先定义 read envelope 的完整性，再定义 write contract：先问“读回来的是否是全量”，再决定 omission 是删除还是保留。
2. 把不可逆的错误升级成类型和 runtime invariant：discriminated union、whiteboard replace 拒绝、delete-only 分支都比 prompt 提醒更可靠。
3. 把未落库的中间状态留在最小的 session/UI 层：图片 slot 可见但不写 page，只有真实 asset 成功后才产生 durable node。
4. 把兼容性放在 registry/alias 边界：历史消息继续可读，核心 runtime 不需要长期维护多套新旧实现。
5. 测试负面语义而不只测成功路径：白板不能 replace、未知背景 id 告警、redo 不能 update 旧节点，这些才是跨层回归最容易破坏的契约。

边界、风险与未解问题#

代码验证事实#

• #5294 的 update_page 在执行时重新读取 page.type；DOC、CODE、DESIGN 分支生成不同 delta，SHEET 明确不可写。
• merge 的节点集合从 prevValue 出发，解析到的元素只更新/新增，省略元素不会自动删除；deleteNodeIds 会展开 group descendants。
• #4979 的 merge background 只接受已有 id，HTML 无法表达的背景状态保持不动并给 warning；replace 仍可能对 video 或带 image adjustments 的状态有损。
• #5293 的 slot 广播通过 agent-image-slot envelope 传输，站点 store 标明它是 session state；slot placement 失败会让后续 insert_image_node 继续承担最终落盘。

合理推断#

• update_page 统一了入口，但并没有消除三种存储格式、三种 HTML round-trip 能力和三种失败语义；维护成本从“工具选择”转移到了 mode、converter 和 metadata preservation。
• mode 来源于更早的模型读操作，执行时重新 fetch 能减少 page type 漂移，但不能自动证明模型提交的 HTML 仍基于当前版本；协同编辑和长 turn 是主要风险面。
• alias 兼容让迁移成本集中在一次性 tool registry，但历史失败输出缺失“不重试”指令，说明兼容层并非完全语义等价，需要 telemetry 观察 self-correct 是否增加 token/turn 成本。

仍待确认#

• 真实协同编辑下，两个 turn 同时 replace 同一 page 或 merge 同一白板时，Go page delta 服务如何处理 stale reads、顺序和冲突。
• 包含视频、裁剪图片、image adjustments、多背景层的页面，在 replace/merge 后是否需要明确的“不可通过 Agent HTML 编辑”提示和 editor fallback。
• 断线、刷新、Continue、跨 tab 时 slot 的生命周期、asset idempotency 与最终 addNode 是否仍然至多一次。
• #5333 的概率性 eval 现象、#5293 的真实 WebSocket broadcast 以及 #4979 的 export-worker 部署 skew，都需要真实 runtime/browser 验证。

候选说明#

Melbourne 2026-07-29 今日窗口有 #5340（中断工具后的 Continue）、#5335（Think 迁移后的 turn system stack）、#5333（图片 redo）、#5294（统一 page write surface）、#5325（task-worker 失败关联）和 #5308（浏览器快照导入）等候选。#5364、#5338 等主要是 UI/布局；#5340、#5335 虽然有 Agent runtime 价值，但与页面写入和图片落地不能自然串起本次五个关联 PR；#5308 属于 Brand import 线。#5294 同时有架构级入口变化和明确的前后置代码证据，因此选作今天锚点。

昨天的 #5320 已在学习日志中作为锚点，未重复选择；本报告只回看到最近 30 天内、且能通过同一 page write/image delivery 数据流证明关系的 PR。#4979 虽然编号较早，但它今天 merge 且直接修改 update_page/design-html round-trip，因此纳入后续阶段。

GitHub 文档#

• 报告文件：outputs/voyager-daily-pr-study/2026-07-29-pr-5294-agent-page-write-surface-image-delivery.md
• 锚点 PR：github.com/adastralab-ai/voyager/pull/5294 ↗
• Voyager merge commit：ad2dbdbfe1357277714469ff22df4c450b61c91e
• 目标仓库：joyehuang/ai-agent-field-notes
• 报告首次写入 commit：e2190ca51daa6da7da951f51650a9f561339b551
• 最终分支同步 commit：以本次自动化日志中的 githubCommit 为准。
• Feishu 文档：null（本自动化不创建或更新 Feishu/Lark 文档）