cc-web/.trellis/tasks/08-11-task-board/prd.md

独立任务看板 PRD

目标

为 cc-web 增加一个与现有聊天功能解耦的任务看板。只有显式开启“加入任务看板”的会话才参与状态跟踪；Agent 可通过 MCP 主动上报，cc-web 生命周期 Hook 在缺少上报时提供保守兜底。完成状态与软归档分离。

用户场景

1. 用户从普通聊天页开启“加入任务看板”，该会话立即出现在看板。
2. 用户从任务看板创建会话，新会话默认开启任务跟踪。
3. 用户查看系统固定状态列，并新增、编辑、排序或停用自定义状态。
4. Agent 调用状态 MCP 上报处理中、等待用户、阻碍、完成或自定义状态。
5. Agent 没有上报时，cc-web 根据 turn 生命周期和结构化事件更新基础状态或标记“未上报”。
6. 用户手动归档已完成任务；以后可取消归档。归档不删除会话。

功能要求

任务跟踪开关

• 普通新对话默认 taskTracking.enabled=false。
• 从任务看板创建的会话默认 true。
• 关闭开关后不进入看板、不运行自动分类；保留已有状态用于审计。
• Agent 不能通过状态 MCP 偷偷开启、关闭或归档任务。

状态

• 系统固定状态 ID：unassigned、in_progress、waiting_user、blocked、completed。
• 系统 ID 和语义不可删除；展示名称、颜色、顺序允许配置。
• 自定义状态必须映射到一个系统 baseStatus，并包含名称、说明、颜色、顺序和启用状态。
• 删除仍被任务引用的自定义状态前必须指定迁移目标。
• 状态优先级：用户操作 > MCP 明确上报 > 生命周期 Hook > 默认状态。

MCP

• ccweb_task_status_list：读取当前会话是否启用跟踪及可用状态定义。
• ccweb_task_update：当前来源会话上报 statusId、reason、summary、progress。
• 跟踪关闭时 ccweb_task_update 返回 task_tracking_disabled，不得自动加入看板。
• 不提供 Agent 归档 MCP。

生命周期 Hook

• 使用 cc-web 内部事件，不修改用户 .codex/hooks.json。
• 处理 turn_started、user_input_requested、turn_completed、turn_failed、user_message_received。
• turn_started 可进入处理中；结构化用户输入进入等待用户；失败进入阻碍。
• turn_completed 不等于任务完成。若本轮没有 MCP 上报，保留业务状态并标记 reportingStatus=missing。
• 已归档会话收到新用户消息时自动取消归档并进入处理中。

看板

• 提供独立任务看板视图，不替换现有聊天页与会话列表。
• 支持搜索、会话/Agent 筛选、优先级筛选、横向状态列、归档视图和状态管理面板。
• 卡片点击打开原会话；运行态和任务态分开显示。
• 支持桌面横向看板和窄屏横向滚动，不破坏现有响应式布局。

归档

• 归档使用 archivedAt/archivedBy 软标记，不移动或删除会话文件。
• 用户可手动归档/取消归档。
• 自动归档策略保留扩展点，本期不默认启用定时归档。

非目标

• 不修改 Codex Hook 配置。
• 不把所有历史对话自动加入任务池。
• 不从自由文本强行推断任务完成。
• 不删除、移动或迁移现有会话文件。
• 不在三个并行实现对话中修改中心接线文件。

验收标准

1. 现有普通会话默认不出现在任务看板。
2. 开关启用后会话可进入看板，关闭后立即退出但状态保留。
3. 系统状态存在，自定义状态可创建、编辑、排序、停用并安全迁移。
4. 两个 MCP 工具可发现、可调用，并遵守来源会话和开关边界。
5. cc-web 生命周期事件正确驱动基础状态，且不会把 turn 完成误判为任务完成。
6. 归档不删除会话，重新发消息可恢复。
7. 前端视图与现有 cc-web 风格一致，桌面和窄屏可用。
8. node --check、新模块单元测试和 timeout 60s npm run regression 全部通过。
9. 隔离测试服务完成真实浏览器验收；生产服务仅在重启门禁通过后重启。