shiyue/cc-web

Fork 0

Files

shiyue 86231f0d97 feat: overhaul task board and cross-conversation workflows

2026-08-12 09:41:36 +08:00

17 KiB

Raw Permalink Blame History

ccweb 消息回传统一影响面映射

结论

本任务的核心影响面集中在 3 条链路：

公开工具契约：lib/ccweb-mcp-server.js 的 TOOLS 当前同时公开 ccweb_send_message 与 ccweb_request_reply，server.js 的 Codex App fallback dynamic tools 又复制了一份定义。
内部兼容分发：server.js 的 callInternalMcpTool() 已经把两个工具名分别分发到 sendCrossConversationMessage() 和 requestCrossConversationReply()；旧别名兼容应保留在这里。
自动回传状态机：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 不再公开它。

建议实现顺序

抽出共享契约，定义 reply modes 和公开 ccweb_send_message definition。
让正式 MCP tools/list 和 Codex App fallback 复用共享 send definition。
分离公开工具列表与内部可调用工具白名单，保证旧 ccweb_request_reply 可 call 不可 list。
在 dispatcher 或发送函数中归一 replyMode -> expectReply。
pending 增加 originalRequest，归一、保存、查询和旧数据兼容。
改目标 runtime prompt 和来源 auto-run prompt。
更新 README。
更新回归断言，覆盖正式 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。

17 KiB Raw Permalink Blame History Unescape Escape

ccweb 消息回传统一影响面映射

结论

代码索引状态

文件影响清单

正式 MCP 定义链路

当前位置

需要调整

Codex App fallback dynamic tools 链路

当前位置

需要调整

Composer MCP 候选链路

当前位置

需要调整

内部 dispatcher 链路

当前位置

需要调整

正式 MCP HTTP 与 stdio 入口

共享 HTTP MCP

旧内部 HTTP API

stdio MCP 桥

关键风险

发送与回传状态机

单向发送 / 创建 pending

pending 持久化

需要新增字段

目标完成与来源写回

目标运行提示

当前位置

需要调整

来源自动续跑提示

当前位置

需要调整

ccweb_create_conversation 间接受影响

当前位置

需要保持

前端展示影响

回归测试影响面

现有相关断言

需要新增/调整断言

建议实现顺序

主要风险

17 KiB

Raw Permalink Blame History

`ccweb_create_conversation` 间接受影响