196 lines
5.3 KiB
Markdown
196 lines
5.3 KiB
Markdown
# 技术设计与并行边界
|
||
|
||
## 共享模型
|
||
|
||
会话 JSON 新增可选字段：
|
||
|
||
```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
|
||
}
|
||
}
|
||
```
|
||
|
||
状态定义：
|
||
|
||
```json
|
||
{
|
||
"id": "waiting_deploy",
|
||
"label": "等待部署",
|
||
"baseStatus": "waiting_user",
|
||
"description": "实现完成，等待部署环境或发布窗口",
|
||
"color": "#f59e0b",
|
||
"order": 40,
|
||
"system": false,
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
## 服务契约
|
||
|
||
MCP 对话负责产出 `lib/task-board-service.js`，导出：
|
||
|
||
```text
|
||
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
|
||
|
||
```json
|
||
{
|
||
"statusId": "in_progress",
|
||
"reason": "可选，最长 2000 字符",
|
||
"summary": "可选，最长 4000 字符",
|
||
"progress": 0
|
||
}
|
||
```
|
||
|
||
`progress` 范围 0-100。跟踪关闭返回 `task_tracking_disabled`，未知状态返回 `task_status_unknown`。
|
||
|
||
## 生命周期契约
|
||
|
||
Hook 模块只接收事实事件，不自行读写文件：
|
||
|
||
```json
|
||
{
|
||
"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 的安静暗色操作界面，以克制的青色主强调和少量状态色构建密集、清晰的横向看板。
|
||
- 内容计划：顶层视图入口与工具条；横向状态工作区；归档视图；状态编辑面板。
|
||
- 交互论点：视图切换轻淡入、卡片悬停与状态变化使用短促位移/颜色过渡、窄屏保持流畅横向滚动。
|
||
|
||
## 验证命令
|
||
|
||
```bash
|
||
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 生产服务。
|
||
|
||
## 重启门禁
|
||
|
||
1. 调用 `ccweb_list_conversations(status="running")`。
|
||
2. 当前来源对话 ID 固定记录为 `56bb82c6-4fa3-4cb8-bb84-6969e6547d3a`；标题“设计任务看板状态机制”仅作人工交叉核验。
|
||
3. 三个实现对话和集成对话必须全部为 idle，且 `ccweb_list_pending_replies` 无 waiting/delivering。
|
||
4. 任何其他 conversation 状态为 running 都暂停重启并报告。
|
||
5. 满足条件后执行 `pm2 restart ccweb --update-env`，随后检查 pm2 状态和 HTTP/WebSocket 健康。
|