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