# 独立任务看板 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. 隔离测试服务完成真实浏览器验收；生产服务仅在重启门禁通过后重启。