cc-web/.trellis/tasks/08-11-task-board/research/integration-contract.md

并行实现共享契约

本文件是三个实现对话与最终集成对话的唯一共享协议摘要。实现前必须同时阅读 prd.md 和 info.md。

核心不变量

1. 普通会话默认不跟踪；taskTracking.enabled 是进入任务池的唯一开关。
2. archivedAt 与 statusId 分离；归档绝不删除或移动会话。
3. 系统状态 ID 稳定；自定义状态必须映射到系统 baseStatus。
4. 用户写入优先于 MCP，MCP 优先于 Hook，Hook 不覆盖同轮 MCP。
5. turn_completed 绝不自动等价为 completed。
6. 三个并行对话不得修改中心接线文件；第四个对话统一接线。

系统状态

ID	默认标签	语义
unassigned	待认领	已加入看板但尚未开始
in_progress	处理中	任务仍在推进
waiting_user	等待确认	等待用户输入、验收或外部条件
blocked	遇到阻碍	发生错误或无法继续
completed	已完成	任务业务目标已经完成

错误码

• task_tracking_disabled
• task_status_unknown
• task_status_invalid
• task_status_in_use
• task_version_conflict
• task_session_not_found

集成原则

• 公共服务模块不依赖 server.js，由集成层注入 IO。
• 前端模块通过适配器接收 send、openSession 和初始数据，不直接依赖现有全局变量。
• 所有新增消息和工具使用 task_ / ccweb_task_ 前缀，避免覆盖现有协议。
• 单元测试可独立运行，不启动生产 cc-web。