cc-web/.planning/subagent-card-metadata/findings.md

发现记录

• 前端 collabAgentStateEntries 已读取 label/title/name 和 description/summary/message。
• 当前渲染层仅把任务提示词和结果简介写入 DOM title，卡片正文没有显示简介。
• 真实 Codex App spawnAgent 记录通常提供 prompt，但 agentsStates 在启动时为空，完成时 name 常为线程 ID。
• 当前 mergeCollabAgentTools 只保留一个全局 prompt，需要把各次 spawn 的 prompt 写入对应代理状态。
• 工作树开始时干净；已有 .planning/codex-app-worker-timeout 和根目录规划文件，不能覆盖。
• Trellis 前端规范目前大多是模板，因此实施以现有 public/app.js / public/style.css 约定和回归测试为主要依据。
• 原 Trellis 当前任务是 00-bootstrap-guidelines，本任务结束后需要恢复。
• 样式集中在 public/style.css 的 .collab-agent-* 区块；需补齐 min-width: 0 / max-width: 100% 收缩链，并为新增简介采用两行 clamp。
• 回归入口是 scripts/regression.js 的 Codex App 子代理端到端段；现有测试验证事件链但未覆盖标题/简介展示语义。
• mock 已提供两个子代理及不同 name/role/summary，可扩展为通用名称 + 不同 prompt，验证前端合并不串任务上下文。
• 计划复审通过；实现范围保持前端与回归测试，不改后端协议、不重启服务。
• 独立质量检查发现 UUID 正则仅覆盖 v1-v5，会漏掉 UUID v7；需要改为通用 UUID 形状判断。
• 静态源码契约不足以证明多 spawn 行为；需要提取并执行实际纯函数源码，覆盖独立 prompt 与 wait/close 保留。
• 后续状态会携带归一化空标题字段；合并时只有新状态含可读标题才允许覆盖旧标题。
• 归一化 entry.label 可能由 prompt 派生，必须携带 hasReadableSourceTitle 标记区分协议标题和派生标题。
• 当前真实会话持久化数据只剩一个 receiverThreadIds: [] / agentsStates: {} 的 wait 工具，说明不能只依赖同 ID 的历史工具快照。
• closedCollabAgentIds 只能标记已知 ID 的状态；需要额外缓存 ccweb_mcp_child_agent_update.child 的最后结构化状态，才能在空 wait/close 载荷中重建卡片。
• 当前工作树另有“放开图片数量限制”改动，涉及 CHANGELOG.md、README*.md、public/app.js、server.js、scripts/regression.js，本修复必须限制在不重叠代码区并避免格式化整文件。
• 独立复核确认实时缓存修复后，renderMessages() 会清空缓存；若历史只有空 close/wait，刷新仍退化为工具 ID。
• 服务端 updatePersistedCcwebMcpChildTool 只按 child.spawnToolId 查找工具；真实会话缺少该 spawn 工具时返回 null，未把 child 状态写入历史。
• 后端兜底应只选择最近的 collab_agent_tool_call，不得把 child 合并进普通工具。
• 2026-07-15 本机 PM2 ccweb 已实际重启并在线；其他机器仍显示旧样式属于发布物/部署路径问题，不是本机进程未重启。
• CentOS 7 单文件发布必须重新运行 scripts/build-single-exe.js；该流程会在打包前复制 public/ 运行时资源，源码更新不会自动进入旧 tar.gz。
• 本机 dist-exe/cc-web-bun-linux-x64-baseline.tar.gz 已包含最新静态资源：tar 内 app.js / style.css 与源码 SHA-256 完全一致，并含 collab-agent-item-description、两行 clamp 和关闭状态缓存代码。
• 单文件运行时从二进制同目录的 public/ 加载资源；只替换 cc-web 二进制、保留旧 public/，或设置 CC_WEB_APP_DIR/CC_WEB_PUBLIC_DIR 指向旧目录，都会继续显示旧样式。
• 旧历史会话本身若只保存 thread ID、没有 title/taskDescription，即使加载新前端也只能显示 ID ... 且没有简介；需要用新部署后新建的子代理验证，不能只看旧历史卡片。
• 2026-07-16 确认同一版本存在两套事件链路：完整 spawnAgent 会以 collab_agent_tool_call 进入 mergeCollabAgentTools()；原生 subAgentActivity 仅在服务端用于线程恢复，前端不会把它合并成富卡片。
• mergeCollabAgentTools() 明确过滤 toolKind(tool) === 'collab_agent_tool_call'；因此 subAgentActivity + 空 wait 会分别退化为原始折叠工具条和 ID call_... 卡片。
• 修复应在进入渲染前将 agentThreadId、agentPath、活动 kind 归一为结构化子代理状态，并避免原始活动事件重复渲染。
• 真实会话中的 subAgentActivity 输入与结果都只包含 kind/agentThreadId/agentPath，未携带 spawn prompt；因此历史数据能恢复线程 ID、状态与角色标题，但不能凭空恢复完整任务简介。
• 同一消息里随后出现的 wait 已被转换为 collab_agent_tool_call，但 receiverThreadIds 和 agentsStates 均为空，说明应将前置活动事件作为该 wait 的恢复来源。
• 扫描现有会话得到 41 条 subAgentActivity：活动类型只有 started 与 interacted，输入字段稳定为 type/id/kind/agentThreadId/agentPath，均无 prompt；interacted 应保持运行态。
• Phase 8 复审已通过；计划已明确字段映射、原始工具条与 ID call_... 去重、baseline 二进制 smoke test 和 tarball 核验。
• 前端所有历史、恢复流和实时流都通过 toolKind() 分流；让它把 raw subAgentActivity 识别为协作显示工具，可同时复用现有合并、富卡片渲染和普通工具过滤逻辑，避免在三个调用点分别硬编码。
• normalizeCollabAgentData() 是补齐活动字段的最小归一入口：从 agentThreadId 构建 receiver/state，从 agentPath basename 构建标题/角色，从活动 kind 映射状态，并按真实字段保留 prompt。
• 新事件还应在 lib/codex-app-runtime.js 的 itemKind/itemInput/itemResult 层输出 collab_agent_tool_call 结构；这样旧前端也能把新会话视为富卡片，同时保留 input.type=subAgentActivity 供服务端恢复线程路由。
• 首轮生产实现已让定向行为回归通过；人工审查仍需确认三项最小范围边界：空 wait 对整体头部状态的覆盖、agentPath 同时填充 role 导致标题/页脚重复、通用 tool_end 全量增加 name/input 的必要性。
• 独立质量检查确认首轮实现仍有高风险缺口：完成态空 wait 会覆盖整体头部为已返回但 child 仍运行；runtime completed 不带 prompt 时会直接替换 started input，刷新后简介丢失。
• 另有两个中风险边界：agentPath basename 回填 role 会导致标题/footer 重复；仅凭 name 匹配 subAgentActivity 会把无 agentThreadId 的同名普通工具误归类。
• 第二轮已改为子状态优先聚合整体状态、runtime 活动输入结构化合并、agentPath 仅提供标题、activity 匹配必须存在 threadId；新增边界回归均通过，等待原检查代理复核。
• 原检查代理复核时把 item/completed 误等同于 child completed；真实会话反证是 input.kind=started 的活动工具本身 done=true，因此 transport item 生命周期不能覆盖 activity kind 的 child 生命周期语义。
• 正确契约：completed 通知缺少新 kind 时继承 previous activity kind/status；只有活动 kind 明确为 completed/returned/failed/closed 时才改变 child 终态，同时仍保留 started prompt。
• 用户明确要求所有子代理统一成完整标题+简介卡片。上游 raw activity 无法追回真实 prompt，因此展示层需以 agentPath/task name 生成可读标题和明确标注的兜底简介，真实 prompt 仍保持最高优先级。
• 富卡片独立复核发现 collabAgentStateEntries 会重新推断并覆盖 hasReadableSourceTitle:false，导致 prompt 派生的 snake_case 标题被误翻译；该标记必须贯穿 merge、entry 与 render。
• 最终实现只美化协议/agentPath 来源的自动任务名；prompt 派生标题的 hasReadableSourceTitle:false 会贯穿 merge→entry→render，不被误翻译。
• 最终 HTTP app.js 与源码 SHA-256 均为 0b3a14a543fa819837eb4d1bf007aa4929d52844af8624696d5f74afe8b7891e，响应为 Cache-Control: no-store, max-age=0，刷新页面即可加载，无需为纯静态改动中断其他运行对话。
• 最终 baseline tar SHA-256 为 c85202fa3ee989689aef3821b6860b1a356267180aa79858140849599f8504d4，MCP initialize smoke test 成功。