shiyue/cc-web

Fork 0

Files

shiyue 86231f0d97 feat: overhaul task board and cross-conversation workflows

2026-08-12 09:41:36 +08:00

5.3 KiB

Raw Permalink Blame History

技术设计与并行边界

共享模型

会话 JSON 新增可选字段：

{
  "taskTracking": {
    "enabled": true,
    "statusId": "in_progress",
    "baseStatus": "in_progress",
    "source": "user",
    "reason": "",
    "summary": "",
    "progress": null,
    "reportingStatus": "reported",
    "version": 1,
    "enabledAt": "ISO-8601",
    "disabledAt": null,
    "statusUpdatedAt": "ISO-8601",
    "completedAt": null,
    "archivedAt": null,
    "archivedBy": null
  }
}

状态定义：

{
  "id": "waiting_deploy",
  "label": "等待部署",
  "baseStatus": "waiting_user",
  "description": "实现完成，等待部署环境或发布窗口",
  "color": "#f59e0b",
  "order": 40,
  "system": false,
  "enabled": true
}

服务契约

MCP 对话负责产出 lib/task-board-service.js，导出：

createTaskBoardService(deps)
  .getStatusDefinitions()
  .upsertStatusDefinition(input, actor)
  .removeStatusDefinition(id, migrateTo, actor)
  .listTasks(filters)
  .setTracking(sessionId, enabled, actor)
  .updateStatus(sessionId, update, actor)
  .setArchived(sessionId, archived, actor)
  .recordLifecycleEvent(sessionId, event)

服务通过依赖注入读取/保存会话和状态配置，不直接 import server.js。所有修改使用版本号和统一校验。

WebSocket 契约

客户端请求：

task_board_query
task_tracking_set
task_status_set
task_status_definition_upsert
task_status_definition_remove
task_archive_set

服务端响应/广播：

task_board_result
task_board_event
task_tracking_result
task_status_result
task_status_definitions_result
task_archive_result

所有请求携带 requestId；所有写响应返回规范化任务、状态定义或稳定错误码。

MCP 契约

ccweb_task_status_list

无业务参数；来源会话从 MCP 上下文解析。返回 trackingEnabled、当前状态和状态定义。

ccweb_task_update

{
  "statusId": "in_progress",
  "reason": "可选，最长 2000 字符",
  "summary": "可选，最长 4000 字符",
  "progress": 0
}

progress 范围 0-100。跟踪关闭返回 task_tracking_disabled，未知状态返回 task_status_unknown。

生命周期契约

Hook 模块只接收事实事件，不自行读写文件：

{
  "type": "turn_completed",
  "turnId": "可选",
  "occurredAt": "ISO-8601",
  "outcome": "completed",
  "pendingUserInput": false,
  "hadTaskStatusUpdate": false,
  "error": null
}

规则：

未开启跟踪：忽略。
用户消息：若归档则取消归档；状态进入 in_progress。
turn started：非终态进入 in_progress。
structured user input：进入 waiting_user。
turn failed：进入 blocked 并记录错误。
turn completed 且本轮无 MCP：保持状态，设置 reportingStatus=missing。
本轮已有 MCP：不得被 Hook 覆盖。

并行文件所有权

前端对话（只允许修改）

public/task-board.js
public/task-board.css
scripts/task-board-frontend-unit.js

不得修改：public/index.html、public/app.js、public/style.css、server.js、scripts/regression.js。

MCP/状态服务对话（只允许修改）

lib/task-board-service.js
lib/task-board-mcp.js
scripts/task-board-service-unit.js

不得修改：server.js、lib/ccweb-mcp-server.js、scripts/regression.js、任何 public/* 现有文件。

Hook 对话（只允许修改）

lib/task-board-lifecycle.js
scripts/task-board-lifecycle-unit.js

不得修改：server.js、lib/codex-app-runtime.js、scripts/regression.js、任何 public/* 文件。

集成对话（前三路完成后独占）

可以修改中心文件并调整前三路模块：

server.js
lib/ccweb-mcp-server.js
lib/codex-app-runtime.js（仅必要时）
public/index.html
public/app.js
public/style.css（优先不改，使用独立 CSS）
scripts/regression.js
前三路新模块

视觉方向

视觉论点：延续 cc-web 的安静暗色操作界面，以克制的青色主强调和少量状态色构建密集、清晰的横向看板。
内容计划：顶层视图入口与工具条；横向状态工作区；归档视图；状态编辑面板。
交互论点：视图切换轻淡入、卡片悬停与状态变化使用短促位移/颜色过渡、窄屏保持流畅横向滚动。

验证命令

node --check lib/task-board-service.js
node --check lib/task-board-mcp.js
node --check lib/task-board-lifecycle.js
node --check public/task-board.js
node scripts/task-board-service-unit.js
node scripts/task-board-lifecycle-unit.js
node scripts/task-board-frontend-unit.js
node --check server.js
timeout 60s npm run regression

视觉验收使用隔离端口和临时配置目录启动测试服务，不提前重启 pm2 生产服务。

重启门禁

调用 ccweb_list_conversations(status="running")。
当前来源对话 ID 固定记录为 56bb82c6-4fa3-4cb8-bb84-6969e6547d3a；标题“设计任务看板状态机制”仅作人工交叉核验。
三个实现对话和集成对话必须全部为 idle，且 ccweb_list_pending_replies 无 waiting/delivering。
任何其他 conversation 状态为 running 都暂停重启并报告。
满足条件后执行 pm2 restart ccweb --update-env，随后检查 pm2 状态和 HTTP/WebSocket 健康。

5.3 KiB Raw Permalink Blame History Unescape Escape