feat(web): 文稿视图——运行产物主从墙 + 续跑产物修复 - #88
Merged
Merged
Conversation
…gress 实时流增强 断点续跑的可复用节点不重新执行，其工作区文件物理上留在祖先运行的 runtime 目录，导致按当前 runId 定位的两处消费方全部失联： - persistRun 快照：snapshotRunArtifacts 在新 run 的节点工作区找不到文件， 可复用节点的产物整个进不了 artifactIndex（成果面板/导出缺文件） - /wf1/api/artifact 兜底：历史 resume 运行的过程产物 404 修法两层： - materializeResumedWorkspaces：持久化前把祖先运行中可复用节点的产物按 nodeStates.artifacts 物化拷贝进本次运行目录（COPYFILE_EXCL、路径越界 校验、失败仅告警不阻塞），让快照天然命中 - artifact 路由兜底沿 resumedFrom 祖先链回退解析（深度 10 防环）， 救已存在的历史 resume 运行数据 agent-progress 增强（文稿视图实时流消费）： - preview 截断 200→4096 字符：assistant 全文拼接，多轮生成期前端可看 文稿长大；带宽 = 4KB × 并发 agent ÷ 2s，量级安全 - 首个 turn/end 后延迟 2.5s 复查一次再确认结束：多工具轮 agent 常在 首轮文本后继续调用工具，立即退出会漏报后续轮次（单轮语义不变） 集成测试：seed 祖先运行工作区产物 → 续跑 → 断言新 run 目录物化拷贝 存在 + /artifact 路由 200 命中。
画布级第三视图（画布 | 文稿 | 工作流）：整块主区切换为「左侧节点列表 + 右侧大卡横向条带」的文稿墙，把一次运行的过程与成果铺成可读文档。 数据层 doc-wall-data.js（纯函数、node 直测）： - buildDocWallModel 把 run-results（磁盘事实投影）+ nodeStates（节点工作 区产物清单）+ progressByNode（SSE 实时态）整理成 主从模型：finals 成果 带 + nodes 按执行拓扑序分桶（doc/image/video 铺卡，data 折 chip） - 去重时带 downloadUrl 的行胜出：adaptRunResults 派生的 processFiles 只有 文件名，同键 stateArtifacts（scoped artifact URL）必须覆盖它 - 卡内正文 2000 字符截断；scopedArtifactUrl 工厂注入（apiUrl 带 sessionId） 视图 DocWallView.jsx： - DocCard：md 卡 MarkdownDocument 渲染；nodeStates 产物无内联正文，进入 视口后惰性 fetch（startedRef 防重入），失败渲染「正文暂不可读」占位 + 下载链接，不白屏；图片懒加载；视频不挂 <video> 只出预览占位 - LiveCard：agent 节点运行中的实时输出流卡（诚实标注「实时输出」+ 轮次）， 消费 agent-progress 的 4KB preview；run-end/run-error 时 progress 清空 退场，落卡由 run-results-ready 全量再投影接管 - 性能红线：IntersectionObserver 懒挂载、React.memo、chip 折叠 - 恢复原则：SSE 重连（距上次加载 >10s）与成果落盘一律全量再投影 接入：App.jsx 第三视图三态 + loadDocWall + results-ready 重载 + SSE open 再投影；ArtifactPreview 导出 runArtifact 供数据层复用；doc-wall 测试入 web 测试链。
- 点卡原文 window.open 跳新浏览器页，改为复用成果面板同款 ArtifactPreviewModal 页内预览（md/图片全格式，带全屏/下载），不离开文稿墙 - 节点卡 ≤2 张的条带（docwall-strip-cards-sparse）正文高度从固定 260px 改为随内容自适应（封顶 420px），短文档不再拖大片空白；卡多时维持 固定高对齐防条带过高
性能/正确性：
- 惰性拉取的正文补上 2000 字符截断红线（原实现全文渲染，244KB 大文件
也整卡渲染；现与内联 content 同口径，全文只进预览弹窗）
- 新端点 POST /wf1/api/artifacts/content：一次请求批量返回运行内 doc 产物
截断稿（总预算 1.5MB、条目 4KB、上限 200 条，超预算回 { omitted } 由
前端回退单卡拉取）；前端 BulkContext 预取，37 卡 37 请求 → 1 请求
- 运行中增量落卡：文稿墙可见且所看运行进行中时 8s 轻量轮询 runs/detail，
已完成节点的产物卡随跑随铺（run-end 仍由 results-ready 全量投影兜底）
- 真·流式生成文稿：agent-progress 附 docTail（引擎 2s 扫节点输出目录最新
文本产物的 2KB 尾部），流卡头显示「正在生成：<文件名>」并渲染文稿本体
尾部，替代此前只能看 agent 对话文本
体验：
- 总览模式点侧栏行滚动定位（spy 锁 700ms 防乱跳）+ scroll-spy 反向高亮
- toolbar 新增文件名搜索、类型过滤（文档/图片/视频）、只看有产物节点；
过滤纯前端投影，无匹配时给空态提示
- 视图状态进 URL hash（#docs/<runId>）：刷新保持、可直接分享定位
- 空态引导：无运行时给「去画布运行」按钮 + 最近运行直达列表
- toolbar 一键导出本次运行全部产物（复用 /runs/export zip 端点）
- 窄面板（<720px）适配：侧栏收成横向 chip 条、卡片收窄 300px
回归：orchestrator 23 套 + web 15 套全绿；实机复验批量预取 1 请求、
搜索过滤、滚动定位/spy、hash 同步、导出链路。
- 卡内引用互链：run 级产物清单经 FilesContext 下传 MarkdownDocument， 正文行内 code 引用的产物文件名自动变预览链接（复用 findArtifactByName）， 文稿间跳转无需回侧栏 - 新卡高亮：localStorage 记每 run 已读时间戳，完成时间晚于它的卡标 fresh 态（左缘 accent 竖线 + NEW 点标）；离开文稿视图自动推进已读； 文件行透传 finishedAt（stateArtifacts 继承运行完成时间） - 密度切换：S/M/L 三档卡宽（300/420/520px），toolbar 分段按钮，偏好持久化 - 键盘导航：J/K（↑/↓）节点间移动定位、Esc 关预览、/ 聚焦搜索框； 输入框聚焦时自动让位；hooks 全部上移到早退分支前修掉条件 hook 崩溃 - 预览复制工具条：预览弹窗打开时右下角浮层提供「复制全文」（拉取原文件） 与「复制链接」（产物 URL），DocumentPreviewDialog 本体不动（插件冻结面外） - 文稿 tab 徽标：画布视图期间运行成果落盘（results-ready）→ tab 挂小圆点， 进入文稿即消
- images/docwall-overview.jpeg：文稿墙总览（40 节点工程手册工作流， 审核区修订需求/审核意见/自检记录三卡并排，md 表格与结构渲染实拍） - images/docwall-preview.jpeg：点卡全屏预览 + 复制全文/链接工具条 - docs/doc-wall.md：功能说明（入口、成果/过程分带、实时流渲染、检索 浏览能力表、工程实现要点） - README「画布能力」补文稿视图一条链接到详细文档；聚合包 screenshots.json 增补总览截图 - 顺带修预览复制工具条 z-index：弹窗背层 2147483000 之上需 !important 压顶，否则工具条被盖不可见
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景
工作流一跑几十个节点，过程产物（md/图片/视频/中间文件）散在成果面板的清单里没法读。本 PR 落地定稿的原型 v2：画布级第三视图「文稿」——左侧节点列表、右侧大卡横向条带，把一次运行铺成可读文档墙；同时修掉实机验证暴露的续跑产物断链。
方案
前端（web/）
doc-wall-data.js：纯函数数据层，run-results（磁盘投影）+ nodeStates（工作区产物）+ progressByNode（SSE 实时态）→ finals 成果带 + 节点拓扑序分桶模型；doc/image/video 铺卡、data 折 chip；卡内 2000 字符截断DocWallView.jsx：主从布局；md 卡 MarkdownDocument 渲染，nodeStates 产物无内联正文 → 进视口惰性 fetch（防重入），失败显「正文暂不可读」占位不白屏；LiveCard 实时流卡（agent-progress 4KB preview，诚实标注「实时输出」+ 轮次），run-end 退场、落卡由 results-ready 再投影接管；IntersectionObserver 懒挂载 + memo；SSE 重连/成果落盘一律全量再投影引擎（orchestrator/）
materializeResumedWorkspaces持久化前把祖先运行可复用节点产物物化拷进新 run 目录（快照天然命中）；artifact 路由兜底沿resumedFrom祖先链回退（深度 10 防环）救历史数据验证
npm test全绿（web 含新增 doc-wall-data 边界 9 例；orchestrator 含新增集成断言）build-web.sh通过