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