PRD：统一 ccweb 消息回传接口

背景

cc-web 当前同时公开 ccweb_send_message 与 ccweb_request_reply。两者输入完全相同，后者在内部只是为发送函数开启 expectReply。真实会话已出现：任务文字明确要求“完成后汇报/最终验收”，模型仍选择 ccweb_send_message，导致来源对话拿不到自动回传。工具描述、Codex App 备用定义、目标运行提示和来源续跑提示也存在语义缺口。

目标

向新模型只公开一个 ccweb_send_message，用必填 replyMode 明确选择：

one_way：单向投递，目标本轮输出只留在目标对话。
return_and_continue：建立异步回传请求；目标完成后把结果写回来源，并触发来源续跑。

调用始终立即返回，任何模式都不表达同步阻塞等待。

功能要求

1. 公开工具契约

ccweb_send_message 的输入必须包含：
- targetConversationId: string
- content: string
- replyMode: "one_way" | "return_and_continue"
JSON Schema 必须把 replyMode 列入 required，且不得为新调用提供默认值。
工具描述必须包含强选择规则：
- 仅当来源不需要目标结果时使用 one_way。
- 分析、实现、测试、验收、完成后汇报或来源后续依赖结果时，必须使用 return_and_continue。
ccweb_request_reply 不再出现在正式 MCP 工具列表或 Codex App 备用工具列表中。

2. 兼容策略

内部 dispatcher 继续接受旧工具名 ccweb_request_reply，语义固定映射为 return_and_continue，保护已经加载旧工具定义的存量线程。
正式 MCP 的 tools/call 与 Codex App 旧 dynamic call 必须继续接受该隐藏旧名；它只从 tools/list/新 dynamic tools 中移除，不能在 dispatcher 前被 allowlist 拒绝。
内部 dispatcher 可继续把缺少 replyMode 的旧 ccweb_send_message 调用按 one_way 处理；新公开 Schema 仍必须强制该字段，以避免破坏存量线程。
现有返回字段保持兼容；自动回传模式继续返回 requestId、status: waiting、 replyDelivery 与 sourceAutoRun。

3. 单一定义来源

以 lib/ccweb-mcp-server.js 导出的正式工具定义作为单一来源：
- 集中定义并导出 reply mode 常量；
- 在正式 TOOLS 中定义公开 ccweb_send_message 的 description 与 inputSchema。
server.js 已导入 CCWEB_MCP_TOOLS；Codex App 备用工具列表必须从该数组按通信工具白名单筛选并添加 namespace，不能继续复制文案/Schema。
筛选不得把 task-board、图片显示或用户表单等非备用通信工具意外加入 dynamic tools。

4. 目标对话运行提示

one_way 模式必须明确：本轮输出不会自动回传来源。
return_and_continue 模式必须明确：
- 系统会自动回传本轮最终输出；
- 目标应在真正完成或明确阻塞后给出完整交付；
- 不要为回复本请求而手工调用跨对话发送工具，避免重复。
目标提示继续包含来源标题、来源 ID 和原消息内容。

5. 来源续跑提示

pending reply 状态需要保留原始请求文本，兼容旧状态缺少该字段。
自动续跑运行文本至少包含：
- requestId
- 目标对话标题/ID
- 原始请求
- 返回正文
提示必须要求来源先判断返回是否完整满足原始请求；不能把“已返回”直接当作“已完成”。

6. 文档

README 只把 ccweb_send_message 列为公开发送工具，并说明两个 replyMode。
README 可说明旧 ccweb_request_reply 仅为内部兼容别名，但不得继续推荐新调用使用。

非目标

不实现同步阻塞等待。
不新增第三种回传模式。
不重构跨对话 pending reply 的整体持久化机制。
不在本任务中解决所有“turn 完成是否等于任务完成”的协议问题；只通过提示与来源完整性检查降低误判。
不修改任务看板、失败插入卡片等并发任务的功能。
不重启生产 ccweb 服务。

验收标准

新工具清单中存在一个带必填 replyMode 的 ccweb_send_message，不存在公开 ccweb_request_reply。
正式 MCP 与 Codex App 备用定义引用同一个共享契约。
两种新模式均有端到端回归；自动回传行为与现状兼容。
旧 ccweb_request_reply 通过隐藏兼容入口（MCP tools/call、旧 dynamic call、内部 dispatcher）仍成功，但不出现在公开列表。
目标提示和来源续跑提示具有上述模式与关联信息。
README 与实现一致。
语法检查、相关专项测试、完整回归和 git diff --check 通过。
实施不得覆盖任务开始前已有的并发改动。

4.7 KiB Raw Permalink Blame History Unescape Escape