125 lines
7.2 KiB
Markdown
125 lines
7.2 KiB
Markdown
# 子代理标题与简介展示计划
|
||
|
||
## 目标
|
||
|
||
在协作子代理卡片中稳定展示可读标题和任务简介，并确保多子代理合并、运行中与完成态都不丢失各自的任务上下文。
|
||
|
||
## 视觉与交互方向
|
||
|
||
- 视觉主张：延续现有深色紧凑工具卡，以清晰文字层级替代额外装饰。
|
||
- 内容计划：第一行标题与状态，第二层展示两行任务简介，角色作为低权重辅助信息，结果继续保留在悬浮详情中。
|
||
- 交互主张：保留卡片点击复制线程 ID、关闭按钮状态反馈和现有折叠行为，不新增装饰性动效。
|
||
|
||
## 当前阶段
|
||
|
||
已完成
|
||
|
||
## 阶段
|
||
|
||
### Phase 1: 建立实施计划并完成独立审查
|
||
|
||
- **Status:** complete
|
||
|
||
### Phase 2: 补充标题与简介的数据归一化回归断言
|
||
|
||
- **Status:** complete
|
||
|
||
### Phase 3: 实现每个子代理独立的标题与简介合并
|
||
|
||
- **Status:** complete
|
||
|
||
### Phase 4: 实现紧凑双层卡片渲染与样式
|
||
|
||
- **Status:** complete
|
||
|
||
### Phase 5: 运行语法检查与自动化回归测试
|
||
|
||
- **Status:** complete
|
||
|
||
### Phase 6: 检查真实页面效果并完成交付清理
|
||
|
||
- **Status:** complete
|
||
|
||
### Phase 7: 修复关闭后子代理卡片消失
|
||
|
||
- [x] 覆盖关闭更新缺失结构化状态的回归场景
|
||
- [x] 缓存子代理最后一次结构化状态
|
||
- [x] 用已关闭 ID 和状态缓存重建关闭卡片
|
||
- [x] 保留已关闭子代理的标题、简介与线程 ID
|
||
- [x] 验证关闭状态、数量和卡片持续可见
|
||
- [x] 验证普通工具调用不进入子代理合并路径
|
||
- [x] 找不到原 spawn 工具时，将 child 状态合并到最近的协作工具历史记录
|
||
- [x] 刷新/历史重渲染后仍保留标题、简介、线程 ID 和关闭状态
|
||
- [x] 实施前后核对工作树，只改子代理相关代码与测试
|
||
- **Status:** complete
|
||
|
||
### Phase 8: 统一 subAgentActivity 与原生协作工具卡片
|
||
|
||
- [x] 复现并定位两套子代理事件链路
|
||
- [x] 为活动归一空 wait 复用及去重写失败回归
|
||
- [x] 实现 agentThreadId agentPath 状态及 prompt 字段归一
|
||
- [x] 合并活动与协作工具并隐藏原始工具条及 call ID
|
||
- [x] 运行语法检查和完整自动化回归
|
||
- [x] 重建 CentOS 7 发布包并完成二进制与 tar 核验
|
||
- [x] 为无 prompt 子代理生成可读标题与兜底简介
|
||
- [x] 重新回归并重建最终发布包
|
||
- **Status:** complete
|
||
|
||
## 完成标准
|
||
|
||
- 按 `label → title → nickname → name` 选择第一个非通用、非线程 ID 的协议标题。
|
||
- 仅有线程 ID 或 `子代理` / `子代理 N` 等通用名称时，从该子代理自己的任务提示词生成稳定标题。
|
||
- 每个子代理保留自己的简介，多子代理合并不会共用第一个提示词。
|
||
- 无 prompt 但有 agentPath/task name 时生成可读标题和明确的兜底简介；两者都没有时才回退短线程 ID。
|
||
- 简介最多显示两行，完整简介挂在简介 DOM 的悬浮提示；运行结果保留在卡片容器的独立悬浮详情，两者不互相覆盖。
|
||
- 现有状态、关闭、复制线程 ID 功能不回退。
|
||
- 窄屏下标题、状态和关闭按钮不横向溢出。
|
||
- 相关回归测试通过。
|
||
|
||
## 回归场景
|
||
|
||
1. 可读协议标题按字段优先级展示。
|
||
2. 通用标题从各自 prompt 提炼。
|
||
3. 多代理不同 prompt 的标题和简介不串联。
|
||
4. 无 prompt 时回退短线程 ID。
|
||
5. 关闭更新即使不携带 `receiverThreadIds/agentsStates`，也保留原子代理卡片并显示“已关闭”。
|
||
6. 仅有 `subAgentActivity` 与空 `wait` 的历史会话也显示统一富卡片，不再显示原始活动工具条或 `ID call_...`。
|
||
7. `agentThreadId` 写入 `receiverThreadIds` 并作为 `agentsStates` 键；`agentPath` 的 basename 写入可读标题/角色。
|
||
8. `started/interacted` 映射为运行态，`completed/returned` 映射为完成态，失败/关闭类活动映射到对应终态。
|
||
9. 活动或同线程事件能提供 prompt 时写入 `taskDescription`；完全没有 prompt 时显示明确标注的兜底任务说明，不冒充真实 prompt。
|
||
10. 回归分别覆盖完整 `spawnAgent`、仅 `subAgentActivity + 空 wait`、刷新历史、原始工具条去重、无 `ID call_...` 与 prompt 保留。
|
||
11. 发布包保持 `bun-linux-x64-baseline` 目标，完成 MCP JSON-RPC 初始化 smoke test，并核对 tarball 内运行文件与静态资源。
|
||
12. 无 prompt 的 `subAgentActivity` 也必须使用与完整 spawnAgent 相同的标题+简介卡片结构，不再显示裸 snake_case 名称。
|
||
|
||
## 范围约束
|
||
|
||
- 不新增依赖。
|
||
- 不改变后端协议。
|
||
- 不重启服务。
|
||
- 不覆盖当前工作树中 `CHANGELOG.md`、`README*.md`、图片附件数量相关 `public/app.js` / `server.js` / `scripts/regression.js` 改动。
|
||
- 允许定点修改 `server.js` 的子代理工具持久化函数，但不得触碰图片附件处理区。
|
||
|
||
## 错误记录
|
||
|
||
| 错误 | 尝试 | 处理 |
|
||
|---|---:|---|
|
||
| 暂无 | 0 | - |
|
||
| UUID v7 未被识别为线程式标题 | 1 | 扩展为通用 UUID 形状判断并补行为测试 |
|
||
| 回归仅验证源码字符串契约 | 1 | 提取实际纯函数源码执行多 spawn / wait / close 用例 |
|
||
| 新增集成契约按单行字符串匹配多行调用 | 1 | 改为允许空白与换行的正则匹配 |
|
||
| 后续空标题字段覆盖首次可读协议标题 | 1 | 合并时无可读新标题则保留旧标题字段，并补行为回归 |
|
||
| 多文件补丁缺少合法 hunk 边界 | 1 | 拆分为独立小补丁应用 |
|
||
| prompt 派生 label 被误判为协议标题 | 1 | 归一化阶段携带标题来源标记并补行为回归 |
|
||
| 规划文档阶段格式未被完成检查器识别 | 1 | 改为标准 Phase 三级标题与完成状态字段格式 |
|
||
| 空 wait/close 工具缺少可渲染的子代理状态 | 1 | 缓存 `msg.child` 状态，并用已关闭 ID 重建关闭卡片 |
|
||
| 测试先行缺少 `rememberCollabAgentState` | 1 | 实现按 threadId 缓存 helper 后回归通过 |
|
||
| 实时缓存无法覆盖刷新后的历史重渲染 | 1 | 原 spawn 工具缺失时把 child 合并进最近协作工具并持久化 |
|
||
| 收尾时临时 TODO CSV 已被外部流程移除 | 1 | 确认根目录无 TODO CSV 后不重建，直接闭合持久化计划 |
|
||
| `task.py list-context` 误传 action 参数 | 1 | 查看 `--help`，确认该命令只接收任务目录，后续按正确形状调用 |
|
||
| Phase 8 首次计划审查发现字段、去重和发布核验契约不够具体 | 1 | 补充字段级映射、逐项行为断言与 CentOS 7 二进制/tar 验证标准后复审 |
|
||
| 首轮实现通过定向回归但独立检查发现空 wait 状态冲突与 completed 丢 prompt | 1 | 补充四类边界行为断言，改为子状态聚合整体状态并结构化合并 runtime 活动输入 |
|
||
| `timeout` 后直接放环境变量导致命令被当成可执行文件 | 1 | 改用 npm `--registry` 单次参数，代理查询与临时 Bun 安装成功 |
|
||
| 临时 TODO CSV 被外部流程移除 | 1 | 按现有计划状态重建 CSV，并追加新的展示兜底与最终重建步骤 |
|
||
| 富卡片首轮复核发现 prompt 派生自动名被误翻译 | 1 | 在状态条目归一时保留显式标题来源标记，并补真实 merge→render 回归 |
|
||
| 最终重启前发现另一个对话仍在运行 | 1 | 按项目规则不重启；确认静态 app.js 由磁盘直接提供且 HTTP 哈希一致、Cache-Control 为 no-store |
|