5.6 KiB
5.6 KiB
发现与决策：统一 ccweb 消息回传接口
需求
- 将
ccweb_send_message与ccweb_request_reply合并为一个公开工具。 - 使用显式参数选择单向投递或自动回传。
- 优化工具描述、目标对话提示和来源续跑提示。
- 保留旧调用的兼容能力，但不让新模型继续在两个公开工具间选错。
- 本次需要实际落地并通过回归。
已确认事实
requestCrossConversationReply()当前只是sendCrossConversationMessage(..., { expectReply: true })的薄包装。- 正式 MCP 定义位于
lib/ccweb-mcp-server.js，Codex App 备用定义位于server.js，两处描述已出现漂移。 ccweb_create_conversation已经使用requestReply参数，现有公开 API 风格不一致。buildCrossConversationRuntimeText()当前只标注来源标题和 ID，不携带是否自动回传。buildCrossConversationReplyAutoRunText()当前只包含目标标题和返回正文，缺少requestId、原始请求和完整性检查指令。- 真实会话中曾对明确要求“完成后汇报/最终验收”的任务误用
ccweb_send_message；同一会话此前使用过ccweb_request_reply，说明问题不是工具 不可发现，而是选择语义不够强。 - 真实会话还出现过目标返回“完成定位、准备修改”后仍继续工作的情况；提示词可降低 概率，但“turn 完成是否等于任务完成”仍是协议级风险。
并发与工作树基线
- 当前另有两个非本对话的
running对话：任务看板、失败插入卡片。 server.js、lib/ccweb-mcp-server.js、scripts/regression.js已有未提交改动，均与本任务重叠。.planning/.active_plan指向2026-08-11-help，.trellis/.current-task指向.trellis/tasks/08-11-task-board；不得覆盖。- 本任务使用
.planning/2026-08-11-unify-ccweb-message-reply/保存独立上下文。 - 已创建 Trellis 任务
.trellis/tasks/08-11-unify-ccweb-message-reply/，但不会执行task.py start：全局.trellis/.current-task正被另一个运行中对话使用。后续实施与 审查子代理必须显式读取本任务路径，不能依赖全局 current-task。
技术决策
| 决策 | 理由 |
|---|---|
replyMode 必填、无默认值 |
避免模型省略参数后静默失去回传 |
值为 one_way、return_and_continue |
名称直接表达真实副作用，不暗示同步等待 |
| 公开列表移除旧工具，内部 dispatcher 保留别名 | 兼顾新调用清晰度与存量线程兼容 |
| 共享工具定义为单一来源 | 防止 MCP 与备用 dynamic tools 文案/Schema 漂移 |
| 回传模式目标提示禁止手工回复 | 防止同一结果重复投递或形成环路 |
| 来源续跑先判断完整性 | 防止把“已返回”误判成“已完成” |
直接复用 CCWEB_MCP_TOOLS 生成 Codex App 备用定义 |
server.js 已导入正式工具清单，无需新增第三个契约模块 |
最新代码基线
server.js顶部已导入{ TOOLS: CCWEB_MCP_TOOLS }，但codexAppCommunicationDynamicTools()仍手写重复定义。- 最小单一来源方案：正式定义继续留在
lib/ccweb-mcp-server.js；该模块同时导出 reply mode 常量；server.js从CCWEB_MCP_TOOLS按通信工具白名单筛选并添加namespace: 'ccweb'。 - 此方案同时统一所有既有通信工具描述，且不会把 task-board 工具意外加入备用列表。
- 公开 TOOLS 不能兼作唯一调用 allowlist；需要单独的 hidden legacy name 集合，避免
已缓存
ccweb_request_reply的旧线程在到达 dispatcher 前失败。 scripts/regression.js现有assertCcwebListConversationsScopeContract()会从server.js的手写 dynamic tool 源码中截取ccweb_list_conversationsschema；改成 单一来源后该断言也必须改为调用codexAppCommunicationTools()并比较正式定义， 否则正确的去重实现会被旧静态断言误报。- 当前任务看板对话不是陈旧运行标记：其
codexapp-state.json持续更新，正在做隔离 浏览器验收并已发现新增列description契约缺陷。它后续可能修改server.js与scripts/regression.js，本任务必须继续等待其生产改动闭环。
待验证
- 现有测试是否直接断言公开工具数量或旧工具名称。
- Codex App 备用 dynamic tool 路径是否仍有实际回归覆盖。
- 旧线程调用已不在工具列表中的旧名称时，内部 MCP dispatcher 是否仍可接收。
- 原始请求内容加入 pending 状态是否涉及持久化格式兼容。
- 正式 MCP 的
tools/call是否在公开 TOOLS 之外保留隐藏旧名（必须保留）。
Trellis 规范结论
- 仓库只声明 backend/frontend 两层；本任务属于 backend + 跨层协议，不需要加载前端组件规范。
- backend error handling 基本为空，现有
mcpToolError行为应作为事实规范保留。 - backend quality 的已填内容仅针对部分 JSON 预览，与本任务无直接约束。
cross-layer-thinking-guide.md要求显式定义工具 Schema → dispatcher → pending 状态 → 目标运行提示 → 来源续跑提示的完整数据流，并在入口集中校验。code-reuse-thinking-guide.md明确要求相同常量/定义单一来源；支持让 Codex App 备用工具列表直接派生自正式 MCP 定义。
资源
server.js：跨对话发送、回传、运行提示、dynamic tool 定义。lib/ccweb-mcp-server.js：正式 MCP 工具清单与输入 Schema。scripts/regression.js：跨对话 MCP 端到端回归。README.md：公开工具说明。