# 任务计划：统一 ccweb 消息回传接口

## 目标

将公开跨对话发送能力统一为一个 `ccweb_send_message`，通过必填 `replyMode`
显式选择单向投递或自动回传；旧 `ccweb_request_reply` 仅保留内部兼容，并补齐
目标提示、来源续跑上下文、文档与回归覆盖。

## 当前阶段

已完成：专项与完整回归、独立审查及交付清理均已闭环

## 可验收步骤

1. [x] 建立隔离规划并审查并发改动基线（DONE）
2. [x] 固化统一消息接口契约与兼容策略（DONE）
3. [x] 补充统一接口与提示语义的失败回归测试（DONE）
4. [x] 实现单一公开工具与共享工具定义（DONE）
5. [x] 实现模式化目标提示与来源续跑上下文（DONE）
6. [x] 更新文档并保留旧工具内部兼容（DONE）
7. [x] 运行专项与完整回归并修复问题（DONE）
8. [x] 复核变更并清理临时规划清单（DONE）

## 阶段

### 阶段 1：隔离规划与并发基线

- [x] 记录现有脏工作树与重叠文件
- [x] 确认并发对话边界，不覆盖全局活动计划
- [x] 完成计划文档审查
- **状态：** complete

### 阶段 2：契约与失败测试

- [x] 定义必填 `replyMode`、返回结构与兼容行为
- [x] 先补覆盖正式 MCP/备用工具列表、参数校验、内部旧别名和提示语义的失败测试
- **状态：** complete

### 阶段 3：实现与文档

- [x] 统一正式 MCP 与 Codex App 备用定义
- [x] 接入模式化目标提示和带关联信息的来源续跑提示
- [x] pending reply 保存原始请求，并兼容旧状态缺失该字段
- [x] 保留旧工具内部路由兼容但不再公开
- [x] 更新 README
- **状态：** complete

### 阶段 4：验证与交付

- [x] 运行语法、专项测试和完整回归
- [x] 审查仅本任务引入的差异，确认未覆盖并发改动
- [x] 清理 TODO CSV 并闭环计划
- **状态：** complete

## 关键问题

1. 如何在不破坏现有持久对话的前提下停止公开 `ccweb_request_reply`？
2. `replyMode` 如何强制模型在每次调用时明确选择，而不是依赖危险默认值？
3. 如何让目标对话知道是否自动回传，并防止重复手工回传？
4. 来源自动续跑时需要携带哪些关联信息，才能判断返回是否完整？
5. 如何复用单一工具定义，避免正式 MCP 与备用定义再次漂移？

## 已作决定

| 决定 | 理由 |
|---|---|
| 公开接口只保留 `ccweb_send_message` | 真实会话已出现两个相似工具选错的情况 |
| `replyMode` 为必填枚举且无默认值 | 强制调用者显式判断是否需要结果 |
| 初始值采用 `one_way` / `return_and_continue` | 对应当前真实能力，避免虚假的同步等待语义 |
| 旧 `ccweb_request_reply` 仅内部兼容 | 保护已经加载旧工具定义的存量线程 |
| 目标提示按模式生成 | 自动回传模式必须禁止手工重复回传 |
| 来源续跑提示携带 requestId、原请求与完整性检查规则 | 降低多请求混淆和把中间结果当完成的风险 |
| 不修改 `.planning/.active_plan` 与 `.trellis/.current-task` | 它们正被其他运行中对话使用，覆盖会造成并发污染 |

## 错误与风险记录

| 错误或风险 | 次数 | 处理 |
|---|---:|---|
| 工作树已有大量他人改动，且目标文件重叠 | 1 | 先记录基线，等待/协调重叠对话，采用精确补丁 |
| 全局 planning/Trellis 活动指针属于其他任务 | 1 | 使用独立规划目录和显式任务路径，不覆盖指针 |
| 使用 full-history fork 同时指定 explorer 角色被拒绝 | 1 | 改为 `fork_turns: none` 并显式提供完整研究上下文 |
| 一次跨多文件补丁因上下文不精确失败 | 1 | 拆成小型精确补丁，不重复原调用 |

## 完成标准

- 新工具清单不再公开 `ccweb_request_reply`。
- `ccweb_send_message.replyMode` 必填，并覆盖两种模式。
- 旧工具名仍可经内部路由执行自动回传。
- 目标运行提示明确模式，自动回传模式禁止手工重复回传。
- 来源续跑提示包含关联信息和完整性判断要求。
- 正式 MCP、Codex App 备用定义与 README 一致。
- 相关专项测试和完整回归通过，`git diff --check` 通过。
- 不执行生产 `ccweb` 服务重启。