# 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`；stdio `tools/call` 仍需兼容旧名 |
| `server.js` | 导入 `CCWEB_MCP_TOOLS`、共享 HTTP MCP、内部 dispatcher、跨对话发送/回传、Codex App fallback dynamic tools、pending 持久化 | 复用共享定义；`ccweb_send_message` 按 `replyMode` 归一到 `expectReply`；旧 `ccweb_request_reply` 兼容；目标/来源提示增加模式和原始请求；pending 状态新增 `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，则 Composer 会自动不再展示
  `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`，Codex App fallback dynamic tools 仍会暴露旧工具。
- 如果 `replyMode` 在 schema 必填但内部没有兼容缺省，已加载旧 schema 的
  `ccweb_send_message` 调用可能被拒绝。
- 如果来源 auto-run prompt 仍只包含“已返回”，模型可能把不完整返回误判为任务完成。
- 如果 pending 删除过早，`get_pending_reply` 对 returned 历史查询会依赖来源消息里的
  `replyToRequestId`，因此不能破坏 `processed/replyToRequestId/ccwebDisplayOnly`。