@@ -0,0 +1,361 @@
# ccweb 消息回传统一影响面映射
## 结论
本任务的核心影响面集中在 3 条链路：
1. 公开工具契约：`lib/ccweb-mcp-server.js` 的 `TOOLS` 当前同时公开
`ccweb_send_message` 与 `ccweb_request_reply` ， `server.js` 的 Codex App
fallback dynamic tools 又复制了一份定义。
2. 内部兼容分发：`server.js` 的 `callInternalMcpTool()` 已经把两个工具名分别
分发到 `sendCrossConversationMessage()` 和 `requestCrossConversationReply()` ；
旧别名兼容应保留在这里。
3. 自动回传状态机：`sendCrossConversationMessage()` 通过 `expectReply` 创建
pending reply； `completeCrossConversationReply()` 、`deliverCrossConversationReply()`
写回来源并触发来源自动续跑。
`ccweb_request_reply` 不能简单从 `TOOLS` 删除后收工，因为当前正式 MCP 的
`tools/call` 白名单也复用 `TOOLS` 。如果公开列表不再包含旧名，就必须把
“公开 tools/list” 与 “tools/call 内部兼容旧名” 分离。
## 代码索引状态
- `codebase-memory-mcp` 项目：`home-cc-web`
- 索引状态：`ready`
- 代码图节点/边：`5941` / `13063`
## 文件影响清单
| 文件 | 当前职责 | 本任务影响 |
|---|---|---|
| `lib/ccweb-mcp-server.js` | 正式 MCP stdio 服务器、正式 `TOOLS` 定义、`tools/list` 和 stdio `tools/call` 白名单 | 新增/调整共享契约导出；`ccweb_send_message` 必填 `replyMode` ；公开列表移除 `ccweb_request_reply` ； `tools/call` 仍需兼容旧名 |
| `server.js` | 导入 `CCWEB_MCP_TOOLS` 、共享 HTTP MCP、内部 dispatcher、跨对话发送/回传、Codex App fallback dynamic tools、pending 持久化 | 复用共享定义；`ccweb_send_message` 按 `replyMode` 归一到 `expectReply` ；旧 `ccweb_request_reply` 兼容；目标/来源提示增加模式和原始请求； `originalRequest` |
| `README.md` | MCP 工具用户文档 | 公开工具表只推荐 `ccweb_send_message` ，说明 `replyMode=one_way/return_and_continue` ；旧 `ccweb_request_reply` 只标内部兼容别名 |
| `scripts/regression.js` | 端到端回归覆盖 MCP 发送、回传、busy source 队列、Codex App running target | 现有 `ccweb_request_reply` 测试改为兼容测试；新增 `replyMode` 双模式、公开列表、正式 MCP/dynamic tools 定义一致性、提示内容断言 |
| `public/app.js` | 跨对话 reply 展示、折叠状态、ready count 前端消费 | 本任务通常不改；但回归会间接受到 returned reply metadata 影响 |
## 正式 MCP 定义链路
### 当前位置
- `lib/ccweb-mcp-server.js:15` 定义 `const TOOLS = [...]` 。
- `lib/ccweb-mcp-server.js:110` 定义公开 `ccweb_send_message` 。
- `lib/ccweb-mcp-server.js:159` 定义公开 `ccweb_request_reply` 。
- `lib/ccweb-mcp-server.js:445` 在 stdio `tools/list` 返回 `{ tools: TOOLS }` 。
- `lib/ccweb-mcp-server.js:450` 在 stdio `tools/call` 用 `TOOLS.some(...)` 做白名单。
- `lib/ccweb-mcp-server.js:503` 导出 `{ TOOLS, prepareImagePayload, runStdioServer }` 。
### 需要调整
- 新建或拆出无副作用共享契约：
- reply mode 常量：`one_way` 、`return_and_continue` 。
- 校验集合或归一函数。
- `ccweb_send_message` 的 description 与 inputSchema。
- `ccweb_send_message.inputSchema.required` 必须包含：
- `targetConversationId`
- `content`
- `replyMode`
- `replyMode` schema 必须是 enum：
- `one_way`
- `return_and_continue`
- `ccweb_request_reply` 不再出现在正式 `tools/list` 。
- `tools/call` 兼容旧名时不要再依赖公开 `TOOLS` 作为唯一白名单。可选策略：
- `PUBLIC_TOOLS` 用于 `tools/list` 。
- `CALLABLE_TOOL_NAMES` 或 `isCallableMcpTool(name)` 用于 `tools/call` ，包含旧
`ccweb_request_reply` 。
## Codex App fallback dynamic tools 链路
### 当前位置
- `server.js:15` 导入 `TOOLS: CCWEB_MCP_TOOLS` 。
- `server.js:10221` 定义 `codexAppCommunicationDynamicTools()` 。
- `server.js:10273` 复制定义 `ccweb_send_message` ，当前无 `replyMode` 。
- `server.js:10358` 复制定义 `ccweb_request_reply` 。
- `server.js:10391` 定义 `handleCodexAppDynamicToolCall()` 。
- `server.js:10395-10402` Codex App dynamic tool 白名单仍包含 `ccweb_request_reply` 。
- `server.js:10407` 调用 `callInternalMcpTool()` 。
### 需要调整
- `codexAppCommunicationDynamicTools()` 不应再复制 send 的 description/schema。
- 建议从共享正式定义派生 Codex App fallback 定义：
- 保留 `namespace: 'ccweb'` 。
- 复用同一 `description` 和 `inputSchema` 。
- 不包含 `ccweb_request_reply` 。
- `handleCodexAppDynamicToolCall()` 要区分“公开 fallback tool”与“旧线程动态调用兼容”：
- 新公开列表不含 `ccweb_request_reply` 。
- 已加载旧 dynamic tool 的线程调用 `ccweb_request_reply` 时，内部仍可接受并映射到
`return_and_continue` 。
## Composer MCP 候选链路
### 当前位置
- `server.js:2536` 定义 `listComposerMcpItems()` 。
- `server.js:2555` 遍历 `CCWEB_MCP_TOOLS` 生成 `/` 里的 `mcp:ccweb/<tool>` 候选。
### 需要调整
- 如果 `CCWEB_MCP_TOOLS` 改为公开 tools/list，
`mcp:ccweb/ccweb_request_reply` 。
- 必须确认 `/` 候选里 `mcp:ccweb/ccweb_send_message` 的描述与 schema 语义一致。
- 不要从内部兼容白名单反推 Composer 候选，否则会重新暴露旧工具。
## 内部 dispatcher 链路
### 当前位置
- `server.js:6084` 定义 `callInternalMcpTool(tool, args, sourceSessionId, sourceHopCount)` 。
- `server.js:6094-6095` ： `ccweb_send_message` 直接调用
`sendCrossConversationMessage(args, sourceSessionId, sourceHopCount)` 。
- `server.js:6100-6101` ： `ccweb_request_reply` 调用
`requestCrossConversationReply(args, sourceSessionId, sourceHopCount)` 。
- `server.js:5915-5917` ： `requestCrossConversationReply()` 只是
`sendCrossConversationMessage(..., { expectReply: true })` 。
### 需要调整
- `callInternalMcpTool()` 是兼容旧工具名的最佳位置。
- 新逻辑建议：
- `ccweb_request_reply` 固定归一为 `replyMode=return_and_continue` 。
- `ccweb_send_message` 读取 `args.replyMode` 。
- 缺少 `replyMode` 的旧 `ccweb_send_message` 内部按 `one_way` 处理。
- 非法 `replyMode` 返回 `mcpToolError('invalid_reply_mode', ...)` 。
- 保持返回字段兼容：
- `one_way` 返回现有 `messageId` 、`deliveryStatus` 等。
- `return_and_continue` 继续返回 `requestId` 、`status: waiting` 、
`replyDelivery` 、`sourceAutoRun` 。
## 正式 MCP HTTP 与 stdio 入口
### 共享 HTTP MCP
- `server.js:6145` 定义 `handleMcpJsonRpcMessage()` 。
- `server.js:6161` 在 `tools/list` 返回 `CCWEB_MCP_TOOLS` 。
- `server.js:6165` 在 `tools/call` 用 `CCWEB_MCP_TOOLS.some(...)` 做白名单。
- `server.js:6168-6174` 调用 `callInternalMcpTool()` 。
- `server.js:6188-6227` 定义 `handleSharedMcpHttpApi()` ，从 URL query 读取
`sourceSessionId` 、`sourceHopCount` 后调用 `handleMcpJsonRpcMessage()` 。
### 旧内部 HTTP API
- `server.js:6230` 定义 `handleInternalMcpApi()` 。
- `server.js:6243-6247` 从 body 读取 `tool/args/sourceSessionId/sourceHopCount`
并直接调用 `callInternalMcpTool()` 。
- `scripts/regression.js` 当前大量通过该内部 API 调用工具。
### stdio MCP 桥
- `lib/ccweb-mcp-server.js:327` 定义 `callCcweb(tool, args)` 。
- `lib/ccweb-mcp-server.js:352-357` 将 `tool/args/sourceSessionId/sourceHopCount`
POST 到内部 API。
- `lib/ccweb-mcp-server.js:425` 定义 stdio `handleRequest()` 。
- `lib/ccweb-mcp-server.js:445` 返回 `TOOLS` 。
- `lib/ccweb-mcp-server.js:450` 当前用 `TOOLS` 做 stdio call 白名单。
### 关键风险
正式 `tools/list` 删除旧工具后：
- `handleMcpJsonRpcMessage()` 的 `tools/call` 会拒绝旧 `ccweb_request_reply` 。
- stdio `handleRequest()` 的 `tools/call` 也会拒绝旧 `ccweb_request_reply` 。
因此兼容旧工具名必须覆盖两个 `tools/call` 白名单，而不是只改
`callInternalMcpTool()` 。
## 发送与回传状态机
### 单向发送 / 创建 pending
- `server.js:5808` 定义 `sendCrossConversationMessage()` 。
- `server.js:5814-5815` 由 `options.expectReply` 推导 `expectReply/sourceAutoRun` 。
- `server.js:5849` `expectReply` 为真时生成 `requestId` 。
- `server.js:5857-5874` 写入目标 user message 的 `crossConversation` metadata，
并通过 `setPendingCrossConversationReply()` 创建 pending。
- `server.js:5883-5887` 调用 `handleMessage()` ，目标 runtimeText 来自
`buildCrossConversationRuntimeText()` 。
- `server.js:5906-5911` 仅在 `requestId` 存在时返回 `status/replyDelivery/sourceAutoRun` 。
### pending 持久化
- `server.js:222` pending 文件是 `config/cross-conversation-replies.json` 。
- `server.js:4376-4402` `normalizeCrossConversationReplyState()` 归一状态，当前字段包括：
`requestId/messageId/sourceConversationId/sourceTitle/targetConversationId/targetTitle/status/createdAt/hopCount/sourceAutoRun/replyText/completedAt/returnedAt/replyMessageId/lastError` 。
- `server.js:4419-4422` `saveCrossConversationReplies()` 写入文件。
- `server.js:4430-4439` `loadCrossConversationReplies()` 启动加载未 returned 的 pending。
- `server.js:4447-4452` `setPendingCrossConversationReply()` 创建 pending。
- `server.js:4455-4468` `updatePendingCrossConversationReply()` 更新 pending。
- `server.js:4471-4475` `deletePendingCrossConversationReply()` 删除 pending。
### 需要新增字段
- PRD 要求 pending reply 状态保留原始请求文本，建议字段名使用
`originalRequest` 。
- 写入点：`sendCrossConversationMessage()` 创建 pending 的对象。
- 归一点：`normalizeCrossConversationReplyState()` ，旧状态缺失时填 `''` 或明确占位。
- 输出点：
- `crossConversationReplySummary()`
- `getPendingCrossConversationReply()`
- `buildCrossConversationReplyAutoRunText()`
### 目标完成与来源写回
- `server.js:9257` 普通 Codex 运行 entry 记录 `crossConversationReplyRequestId` 。
- `server.js:6796-6799` 普通 Codex 完成后调用
`completeCrossConversationReply()` ，再 flush 来源 pending。
- `server.js:11158` Codex App 运行 entry 记录 `crossConversationReplyRequestId` 。
- `server.js:11322-11326` Codex App 完成后调用
`completeCrossConversationReply()` ，再 flush 来源 pending。
- `server.js:6060-6081` `completeCrossConversationReply()` 提取目标输出，更新
pending 为 `ready` ，随后调用 `deliverCrossConversationReply()` 。
- `server.js:5969-6048` `deliverCrossConversationReply()` ：
- 来源不存在或目标不存在时改为 `failed` 。
- 来源仍 running 时保持 `ready` ，稍后 flush。
- 已处理过则标记 returned 并删除 pending。
- 追加 `ccwebDisplayOnly` assistant 消息到来源。
- metadata 写入 `replyToRequestId/processed/autoRun` 。
- `sourceAutoRun` 为真时调用 `startCrossConversationReplyAutoRun()` 。
- `server.js:6050-6057` `flushPendingCrossConversationReplies()` 在来源空闲后投递 ready reply。
## 目标运行提示
### 当前位置
- `server.js:5733-5737` `buildCrossConversationRuntimeText(sourceSession, content)` 。
- 当前只包含来源标题、来源 ID、消息正文。
- `server.js:5886` `sendCrossConversationMessage()` 发送目标运行时使用该提示。
### 需要调整
`buildCrossConversationRuntimeText()` 需要知道模式，建议参数扩展为：
- `sourceSession`
- `content`
- `replyMode` 或 `{ replyMode, requestId }`
提示必须覆盖：
- `one_way` ：明确本轮输出不会自动回传来源。
- `return_and_continue` ：
- 系统会自动回传本轮最终输出。
- 目标应在真正完成或明确阻塞后给出完整交付。
- 不要为回复本请求而手工调用跨对话发送工具，避免重复。
- 继续保留来源标题、来源 ID、原消息正文。
## 来源自动续跑提示
### 当前位置
- `server.js:5744-5748` `buildCrossConversationReplyAutoRunText(targetSession, replyText)` 。
- `server.js:5750-5777` `startCrossConversationReplyAutoRun()` 使用该 runtimeText 触发来源隐藏续跑。
- 当前提示只包含目标标题和返回正文。
### 需要调整
`buildCrossConversationReplyAutoRunText()` 需要额外输入 pending 或关联上下文，至少包含：
- `requestId`
- 目标对话标题/ID
- 原始请求 `originalRequest`
- 返回正文 `replyText`
- 明确要求来源先判断返回是否完整满足原始请求，不能把“已返回”直接当作“已完成”。
建议让 `deliverCrossConversationReply()` 把 `pending` 或 `{ requestId, originalRequest }`
传给 `startCrossConversationReplyAutoRun()` ，再传给
`buildCrossConversationReplyAutoRunText()` 。
## `ccweb_create_conversation` 间接受影响
### 当前位置
- `server.js:5646` 定义 `createMcpConversation()` 。
- `server.js:5664` 兼容 `args.requestReply === true || args.waitForReply === true` 。
- `server.js:5694-5697` 创建后首条消息调用
`sendCrossConversationMessage(..., { expectReply: requestReply })` 。
- `server.js:5723-5728` 如果有 `requestId` ，返回 `replyStatus/replyDelivery/sourceAutoRun` 。
- `lib/ccweb-mcp-server.js:101` 正式 `ccweb_create_conversation` schema 公开 `requestReply` 。
- `server.js:10349` Codex App fallback schema 也公开 `requestReply` 。
### 需要保持
PRD 不要求修改 `ccweb_create_conversation` 的参数语义。实现 `replyMode` 时必须确保：
- `requestReply=true` 仍创建 pending reply。
- 返回字段仍兼容现有断言。
- 目标提示也应按 `return_and_continue` 模式生成，因为底层仍是跨对话发送。
## 前端展示影响
前端不参与工具契约选择，但会消费返回消息 metadata：
- `public/app.js:1481-1489` `getCrossConversationReplyCollapseKey()` 使用
`replyToRequestId/messageId` 作为折叠 key。
- `public/app.js:7135-7144` 收到 `session_message` 时，如果是
`replyToRequestId` ，会减少 ready reply count。
- `public/app.js:7968-7974` `createMsgElement()` 用 `reply/replyToRequestId`
标记跨对话回复气泡。
本任务如果只新增 `originalRequest/replyMode` metadata， ；
`replyToRequestId/processed/ccwebDisplayOnly` 字段，则会影响展示和 ready count。
## 回归测试影响面
### 现有相关断言
- `scripts/regression.js:6348-6386` 覆盖 `ccweb_create_conversation` +
`requestReply=true` 自动回传。
- `scripts/regression.js:6392-6415` 覆盖 `ccweb_send_message` 单向发送与目标 runtime prompt。
- `scripts/regression.js:6417-6434` 覆盖跨对话 hop count。
- `scripts/regression.js:6440-6490` 覆盖旧 `ccweb_request_reply` 自动回传。
- `scripts/regression.js:6503-6578` 覆盖来源 busy 时 ready reply 排队、pending list/detail、
来源空闲后 flush 和 auto-run。
- `scripts/regression.js:7348-7357` 覆盖目标 Codex App running 时拒绝发送。
### 需要新增/调整断言
- `tools/list` 中：
- 存在 `ccweb_send_message` 。
- `ccweb_send_message.inputSchema.required` 包含 `replyMode` 。
- `replyMode.enum` 为 `['one_way', 'return_and_continue']` 。
- 不存在公开 `ccweb_request_reply` 。
- 正式 MCP 与 Codex App fallback：
- send definition 共用同一 schema/description。
- Codex App fallback 不公开 `ccweb_request_reply` 。
- `ccweb_send_message(replyMode='one_way')` ：
- 不返回 `requestId` 。
- 不创建 pending。
- 目标 runtime prompt 明确不会自动回传。
- `ccweb_send_message(replyMode='return_and_continue')` ：
- 返回 `requestId/status/replyDelivery/sourceAutoRun` 。
- 目标消息 metadata 有 `expectsReply/replyRequestId` 。
- pending 文件有 `originalRequest` 。
- 目标 runtime prompt 明确会自动回传并禁止手工重复发送。
- 来源 auto-run prompt 包含 `requestId` 、目标标题/ID、原始请求、返回正文、完整性判断指令。
- 兼容：
- 内部 `ccweb_request_reply` 仍成功并等价于 `return_and_continue` 。
- 旧 `ccweb_send_message` 缺少 `replyMode` 仍按 `one_way` 成功。
- stdio/shared HTTP `tools/call` 对旧 `ccweb_request_reply` 仍可执行，即使 `tools/list`
不再公开它。
## 建议实现顺序
1. 抽出共享契约，定义 reply modes 和公开 `ccweb_send_message` definition。
2. 让正式 MCP `tools/list` 和 Codex App fallback 复用共享 send definition。
3. 分离公开工具列表与内部可调用工具白名单，保证旧 `ccweb_request_reply` 可 call 不可 list。
4. 在 dispatcher 或发送函数中归一 `replyMode -> expectReply` 。
5. pending 增加 `originalRequest` ，归一、保存、查询和旧数据兼容。
6. 改目标 runtime prompt 和来源 auto-run prompt。
7. 更新 README。
8. 更新回归断言，覆盖正式 MCP、dynamic fallback、旧兼容和 busy source 队列。
## 主要风险
- 如果只删除 `TOOLS` 中的 `ccweb_request_reply` ，旧线程的正式 MCP 调用会被
`tools/call` 白名单挡住，达不到 PRD 的内部兼容要求。
- 如果只改 `lib/ccweb-mcp-server.js` ，
- 如果 `replyMode` 在 schema 必填但内部没有兼容缺省，已加载旧 schema 的
`ccweb_send_message` 调用可能被拒绝。
- 如果来源 auto-run prompt 仍只包含“已返回”，模型可能把不完整返回误判为任务完成。
- 如果 pending 删除过早，`get_pending_reply` 对 returned 历史查询会依赖来源消息里的
`replyToRequestId` ，因此不能破坏 `processed/replyToRequestId/ccwebDisplayOnly` 。
shiyue