shiyue/cc-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d9db66ca8fd7233bbc3ecac5790da942cc4ec70d
cc-web/.planning/2026-08-11-failed-insert-card-actions/findings.md

8.9 KiB
Raw Blame History

失败插入卡片重试与删除：发现记录

用户需求

  • 用户希望“插入失败”的卡片增加“重试”和“删除”按钮。
  • 截图中的失败项位于用户消息卡片内，包含图片预览、文件名、尺寸/状态信息和红色“插入失败”状态。

视觉观察

  • 当前失败状态只有红点和“插入失败”文本，没有恢复或清理入口。
  • 操作应靠近失败状态区域，保持卡片宽度和当前主题视觉，不应抢占消息正文。

工作区约束

  • 当前分支为 main，已有另一任务留下的未提交改动。
  • 已确认 .trellis/.current-task 指向 08-11-task-board，本任务不会覆盖该指针。
  • 与本任务可能重叠的已修改文件包括 public/app.js、public/index.html、scripts/regression.js 和 server.js；后续必须做局部差异审查。

待确认的代码事实

  • 失败状态的数据结构、稳定标识和持久化位置。
  • 原始插入请求的入口、请求参数及重试时可复用的数据。
  • 删除应落在草稿状态、消息附件状态还是服务端持久化层。
  • 现有测试中与运行时图片插入相关的覆盖位置。

初步代码定位

  • codebase-memory-mcp 项目 home-cc-web 索引状态为 ready（5737 节点、12312 边）。
  • “插入失败”不是普通上传失败文案，而是 Codex App 运行中消息插入（steer）状态：前端入口命中 codexAppSteerStatusLabel 与相邻的 setCodexAppSteerStatusElement。
  • 服务端入口命中 handleCodexAppSteerMessage：turn/steer 成功发送 inserted，失败发送 failed，且消息会先以 persistedUserMessage 写入会话。
  • 下一步需要确认状态事件携带的稳定标识、前端如何找到对应用户消息，以及重试是否可以复用现有 handleCodexAppSteerMessage 消息形状。

已确认的数据与渲染契约

  • 前端 updateCodexAppSteerMessage(clientMessageId, status, message) 使用 userMessageIndex 或消息元素的 data-message-id 精确定位卡片，稳定标识已经存在，无需按文件名匹配。
  • setCodexAppSteerStatusElement 目前只切换 pending / inserted / failed 三种 CSS class，并把状态区域写成纯文本；操作按钮应由这里或紧邻的单一渲染函数统一维护，避免重复绑定。
  • 服务端回归 runCodexAppRuntimeImageSteerRegression 已覆盖 clientMessageId、失败状态和成功插入；失败的“附件不可用”消息明确不会持久化，说明截图里的失败卡片至少有一类是客户端临时项。
  • 现有成功分支会持久化一条带附件的用户消息，并最终发送 inserted；重试实现必须避免把失败项或成功项重复写入会话。

调用链与主要风险

  • handleServerMessage 仅在 codex_app_steer_status 分支调用 updateCodexAppSteerMessage；当前状态事件已是最小可扩展协议面。
  • handleCodexAppSteerMessage 在真正调用 turn/steer 之前 把用户消息写入会话。若 turn/steer 异步失败，该持久化消息当前不会回滚，因此“重试”若直接重发原消息会造成重复持久化。
  • 失败分为两类：附件解析/空消息等同步前置失败（未持久化）与准备/turn/steer 异步失败（可能已持久化）。删除和重试必须能区分或统一修正这两类，否则刷新后的行为会不一致。
  • 下一步要确认本地消息对象是否保存 clientMessageId、服务端是否已有单条消息删除/替换协议，以及附件引用在失败后是否仍可用。

客户端入口补充

  • sendMessage 为运行中 Codex App 插入创建本地 messageId，用该值注册 userMessageIndex，并作为 WebSocket 消息的 clientMessageId 发送；因此失败卡片已有天然的单项操作键。
  • 当前前后端没有通用的“删除单条消息”协议；仅有排队消息、提示卡等其他局部删除实现，不能直接用于持久化的 steer 用户消息。
  • 需要在服务端把 clientMessageId 与持久化消息关联起来，或在 steer 失败时回滚该消息，才能让删除和重试同时满足“不重复”和“刷新一致”。

可行实现方向

  • 本地卡片由 sendMessage 创建，包含完整 text 与克隆后的 attachments；扩展 userMessageIndex 即可保存重试载荷，不需要从 DOM 反解析。
  • createMsgElement 是失败状态和附件预览的共同装配点，setCodexAppSteerStatusElement 是状态区域的唯一更新点，适合统一创建/移除按钮并维护 disabled / aria-busy。
  • 推荐服务端在真实 turn/steer 最终失败时按对象引用回滚刚持久化的用户消息。这样所有失败卡片都保持客户端临时态，删除无需新增持久化删除协议，重试也不会制造历史重复项。
  • 重试仍需校验当前 Codex App turn 是否在运行；若运行已结束，应给出明确失败状态，不能让卡片永久停在 pending。

本地源码校验

  • 当前样式集中在 public/style.css 的 .codex-steer-* 区域，失败卡片已有红色边框/背景和 11px 状态行；新操作可在同一区域追加，避免影响其他消息卡片。
  • 项目没有 DOM 测试依赖，仅有 node scripts/regression.js；前端交互测试需要使用轻量假 DOM/纯函数抽取，或在现有回归中增加协议和静态契约断言。
  • 本任务开始时的重叠文件基线：public/app.js 已有 +155 行、server.js +532/-7 行、scripts/regression.js +73/-11 行、public/index.html +14 行，均来自既有“任务看板”工作，后续差异必须按目标函数/样式区段核对。
  • public/style.css 当前没有未提交改动，是本任务新增样式的低冲突落点。

测试与冲突边界

  • 现有 runCodexAppStaleRunningRegression 已有一个稳定的 expectedTurnId 不匹配失败夹具，适合新增“失败后持久化消息已回滚”的服务端断言。
  • 现有成功恢复分支已断言用户消息只持久化一次，可继续保护“重试/恢复不重复”。
  • 既有未提交 diff 的 hunk 不覆盖 setCodexAppSteerStatusElement、sendMessage 或 handleCodexAppSteerMessage 主体；可以对这些区段做局部补丁，但最终仍需逐 hunk 复核。
  • 仓库已有未跟踪的任务看板 MiniDOM 单测脚本，但它属于另一任务；本功能不能修改或依赖该未提交测试文件。若需要 DOM 单测，应建立独立、最小的测试入口。

失败夹具与规范结论

  • mock app-server 的 mismatch 夹具会保留一个不同的活动 turn，因此每次 turn/steer 都稳定返回 expectedTurnId does not match active turn；可用于重复验证失败与回滚，但不能作为成功重试夹具。
  • 前端 Trellis 规范除“静态资源版本握手”外大部分仍是模板占位，没有额外组件框架约束；本任务应遵循仓库现有原生 DOM + CSS 组织方式。
  • 回归脚本已有按 target 执行的分支，可为本功能提供小范围测试入口，避免每次执行完整回归超过 60 秒。

资源

  • 用户截图：sessions/_attachments/8da11ed4-5989-4d30-a12a-f27522138799.png
  • Trellis 任务：.trellis/tasks/08-11-failed-insert-card-actions/

最终实现状态

  • 前端新增 codexAppSteerRecords，保存失败项的原文本、附件、会话、模式和 agent；重试沿用同一 clientMessageId，并通过 status + inFlight 阻止重复发送。
  • failed 状态统一渲染“重试”“删除”；pending/inserted 移除操作，卡片使用 aria-busy，状态行使用 role=status 与 aria-live=polite。
  • 本地运行中插入不再提前增加 currentSessionMessageCount，只有收到 inserted 才提交消息索引；失败/删除不会制造普通路径的索引漂移。
  • 服务端为临时 steer 用户消息写入稳定 id，真正的 turn/steer 最终失败时先按 id 从最新会话回滚，再发 failed 状态；stale recovery 成功路径保持一次持久化。
  • 前端 MiniDOM 单测覆盖失败操作、双击保护、载荷复用、再次失败恢复、删除单项、断线/跨会话/turn 结束保护与成功索引提交。

验证结果

  • node scripts/failed-insert-card-unit.js：通过。
  • node scripts/regression.js --target runtime-image-send：通过。
  • node --check public/app.js、server.js、scripts/regression.js：通过。
  • node scripts/regression.js：因首次定向命令参数错误而实际执行，完整回归通过（约 46 秒）。

独立审查修正

  • 检查代理发现 options.emitUserMessage 的程序化 session_message 虽会显示失败操作，但缺少原始重试载荷；现已由服务端附加临时 steer 元数据，前端据此建立同样的重试记录。
  • 主线程进一步将这类 session_message 在结果未定时保持为临时项：不提前写入消息缓存、不提前占用 currentSessionMessageCount，收到 inserted 后才提交，避免失败删除后的缓存幽灵和索引漂移。