feat: overhaul task board and cross-conversation workflows

.planning/2026-08-11-unify-ccweb-message-reply/findings.md

@@ -0,0 +1,91 @@
+# 发现与决策：统一 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_conversations` schema；改成
+  单一来源后该断言也必须改为调用 `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`：公开工具说明。

.planning/2026-08-11-unify-ccweb-message-reply/progress.md

@@ -0,0 +1,104 @@
+# 进度日志：统一 ccweb 消息回传接口
+
+## 2026-08-11
+
+### 阶段 1：隔离规划与并发基线
+
+- **状态：** complete
+- **开始时间：** 2026-08-11 23:34 CST
+- 已执行：
+  - 读取 `planning-with-files`、`todo-list-csv` 与 Trellis 工作流。
+  - 运行 planning session catchup。
+  - 检查工作树、全局 planning/Trellis 指针和运行中对话。
+  - 确认目标文件存在并发重叠，决定不覆盖全局活动指针。
+  - 建立 8 步 `update_plan`。
+  - 创建独立 Trellis 任务 `08-11-unify-ccweb-message-reply`，保留现有全局 current-task。
+  - 写入 PRD、技术设计、研究基线和 implement/check 上下文；Trellis validate 通过。
+  - 并行派发计划审查、影响面研究、测试研究和并发基线研究。
+  - 计划审查已通过；采纳“不重启、旧 pending 兼容、双公开列表测试”建议。
+  - 确认 `server.js` 已导入正式 `CCWEB_MCP_TOOLS`，决定直接复用而非新增契约文件。
+  - 并发审计确认核心安全范围：只改跨对话提示/发送/回传、dynamic tools、工具定义、
+    README 和对应回归；保留 task-board、children scope 与 failed-insert 改动。
+
+### 阶段 2：契约与失败测试
+
+- **状态：** complete
+- **开始时间：** 2026-08-11 23:45 CST
+- 已执行：
+  - 固化 `replyMode`、公开工具、旧调用兼容和单一来源方向。
+  - 影响面与测试研究已汇总，Trellis context 再次校验通过。
+  - 测试审计确认正式 MCP tools/call 需要隐藏旧名 allowlist，已补入 PRD 与测试设计。
+  - 契约固化完成，新增 `scripts/ccweb-message-reply-unit.js` 静态契约测试。
+  - `node --check scripts/ccweb-message-reply-unit.js` 通过。
+  - `node scripts/ccweb-message-reply-unit.js` 以退出码 1 按预期红灯；首个失败为
+    公开 `TOOLS` 仍暴露 `ccweb_request_reply`。
+  - 复核四个核心文件 SHA-256，均与隔离基线一致。
+- 已创建/修改：
+  - `.planning/2026-08-11-unify-ccweb-message-reply/task_plan.md`
+  - `.planning/2026-08-11-unify-ccweb-message-reply/findings.md`
+  - `.planning/2026-08-11-unify-ccweb-message-reply/progress.md`
+  - `.trellis/tasks/08-11-unify-ccweb-message-reply/`（由 Trellis 脚本创建）
+
+## 测试结果
+
+| 测试 | 预期 | 实际 | 状态 |
+|---|---|---|---|
+| 尚未执行 | 先完成失败测试设计 | 待执行 | pending |
+| `node --check scripts/ccweb-message-reply-unit.js` | 语法通过 | 退出码 0 | passed |
+| `node scripts/ccweb-message-reply-unit.js` | 当前实现红灯 | 退出码 1，旧工具仍公开 | expected-fail |
+| `node --check lib/ccweb-mcp-server.js` | 语法通过 | 退出码 0 | passed |
+| `node --check server.js` | 语法通过 | 退出码 0 | passed |
+| `node scripts/ccweb-message-reply-unit.js`（实现后） | 契约转绿 | 退出码 0 | passed |
+| `node scripts/regression.js --target session-preview-metadata` | 共享定义定向回归通过 | 退出码 0 | passed |
+| `npm run regression`（第 1 次） | 暴露兼容提示缺口 | 缺少“子对话”措辞，退出码 1 | fixed |
+| `npm run regression`（第 2 次） | 暴露提示强度缺口 | 缺少连续“自动回传”措辞，退出码 1 | fixed |
+| `npm run regression`（第 3 次） | 完整回归通过 | 退出码 0，约 49 秒 | passed |
+| `git diff --check` | 无空白错误 | 退出码 0 | passed |
+
+### 阶段 3：实现与文档
+
+- **状态：** complete
+- **开始时间：** 2026-08-12 00:00 CST
+- 当前约束：任务看板对话仍在运行且与四个核心文件重叠；进入生产修改前继续等待其退出，
+  避免覆盖并发改动。
+- 并发收敛后已完成：
+  - 正式 MCP 只公开带必填 `replyMode` 的 `ccweb_send_message`。
+  - Codex App fallback 从正式定义派生，旧名只保留隐藏调用兼容。
+  - 发送运行时、pending `originalRequest`、两类目标提示和来源续跑提示已实现。
+  - README 与新接口一致。
+  - 专项契约测试已转绿。
+
+### 阶段 4：验证与交付
+
+- **状态：** complete
+- **开始时间：** 2026-08-12 00:26 CST
+- **完成时间：** 2026-08-12 00:34 CST
+- 已完成：
+  - `node --check lib/ccweb-mcp-server.js` 与 `node --check server.js` 均通过。
+  - 专项契约测试与 `session-preview-metadata` 定向回归均通过。
+  - 完整 `npm run regression` 在 60 秒门禁内通过，耗时约 49 秒。
+  - `git diff --check` 通过。
+  - 独立 Trellis 验收通过，无阻塞、重大或中等问题，且未修改文件。
+  - 确认未覆盖任务看板、children scope、failed-insert-card 与移动端按钮既有改动。
+  - 按约束未重启生产 `ccweb` 服务，未修改全局 planning/Trellis 指针。
+
+## 错误日志
+
+| 时间 | 问题 | 次数 | 处理 |
+|---|---|---:|---|
+| 2026-08-11 23:34 CST | 目标文件存在并发未提交修改 | 1 | 记录基线，先研究后精确合并 |
+| 2026-08-11 23:39 CST | full-history fork 不能同时覆盖 agent_type | 1 | 改用无历史 fork 并显式传入路径和目标 |
+| 2026-08-11 23:43 CST | 跨多文件补丁上下文不精确 | 1 | 拆成小型精确补丁完成同步 |
+| 2026-08-11 23:47 CST | 第二次跨多文件补丁仍因上下文漂移失败 | 2 | 后续坚持单文件或稳定锚点补丁 |
+| 2026-08-12 00:27 CST | 完整回归发现来源续跑缺少旧“子对话”标识 | 1 | 恢复兼容措辞后专项通过 |
+| 2026-08-12 00:28 CST | 完整回归发现目标提示“自动把结果回传”不够直接 | 1 | 收紧为连续短语“自动回传结果” |
+
+## 5 问重启检查
+
+| 问题 | 回答 |
+|---|---|
+| 当前在哪？ | 任务已完成并进入交付状态 |
+| 接下来去哪？ | 无剩余实施步骤 |
+| 目标是什么？ | 统一公开发送工具并可靠区分是否自动回传 |
+| 已了解什么？ | 见 `findings.md` |
+| 已完成什么？ | 隔离规划、契约、失败测试、生产实现、文档、完整回归与独立验收均已闭环 |

.planning/2026-08-11-unify-ccweb-message-reply/task_plan.md

@@ -0,0 +1,93 @@
+# 任务计划：统一 ccweb 消息回传接口
+
+## 目标
+
+将公开跨对话发送能力统一为一个 `ccweb_send_message`，通过必填 `replyMode`
+显式选择单向投递或自动回传；旧 `ccweb_request_reply` 仅保留内部兼容，并补齐
+目标提示、来源续跑上下文、文档与回归覆盖。
+
+## 当前阶段
+
+已完成：专项与完整回归、独立审查及交付清理均已闭环
+
+## 可验收步骤
+
+1. [x] 建立隔离规划并审查并发改动基线（DONE）
+2. [x] 固化统一消息接口契约与兼容策略（DONE）
+3. [x] 补充统一接口与提示语义的失败回归测试（DONE）
+4. [x] 实现单一公开工具与共享工具定义（DONE）
+5. [x] 实现模式化目标提示与来源续跑上下文（DONE）
+6. [x] 更新文档并保留旧工具内部兼容（DONE）
+7. [x] 运行专项与完整回归并修复问题（DONE）
+8. [x] 复核变更并清理临时规划清单（DONE）
+
+## 阶段
+
+### 阶段 1：隔离规划与并发基线
+
+- [x] 记录现有脏工作树与重叠文件
+- [x] 确认并发对话边界，不覆盖全局活动计划
+- [x] 完成计划文档审查
+- **状态：** complete
+
+### 阶段 2：契约与失败测试
+
+- [x] 定义必填 `replyMode`、返回结构与兼容行为
+- [x] 先补覆盖正式 MCP/备用工具列表、参数校验、内部旧别名和提示语义的失败测试
+- **状态：** complete
+
+### 阶段 3：实现与文档
+
+- [x] 统一正式 MCP 与 Codex App 备用定义
+- [x] 接入模式化目标提示和带关联信息的来源续跑提示
+- [x] pending reply 保存原始请求，并兼容旧状态缺失该字段
+- [x] 保留旧工具内部路由兼容但不再公开
+- [x] 更新 README
+- **状态：** complete
+
+### 阶段 4：验证与交付
+
+- [x] 运行语法、专项测试和完整回归
+- [x] 审查仅本任务引入的差异，确认未覆盖并发改动
+- [x] 清理 TODO CSV 并闭环计划
+- **状态：** complete
+
+## 关键问题
+
+1. 如何在不破坏现有持久对话的前提下停止公开 `ccweb_request_reply`？
+2. `replyMode` 如何强制模型在每次调用时明确选择，而不是依赖危险默认值？
+3. 如何让目标对话知道是否自动回传，并防止重复手工回传？
+4. 来源自动续跑时需要携带哪些关联信息，才能判断返回是否完整？
+5. 如何复用单一工具定义，避免正式 MCP 与备用定义再次漂移？
+
+## 已作决定
+
+| 决定 | 理由 |
+|---|---|
+| 公开接口只保留 `ccweb_send_message` | 真实会话已出现两个相似工具选错的情况 |
+| `replyMode` 为必填枚举且无默认值 | 强制调用者显式判断是否需要结果 |
+| 初始值采用 `one_way` / `return_and_continue` | 对应当前真实能力，避免虚假的同步等待语义 |
+| 旧 `ccweb_request_reply` 仅内部兼容 | 保护已经加载旧工具定义的存量线程 |
+| 目标提示按模式生成 | 自动回传模式必须禁止手工重复回传 |
+| 来源续跑提示携带 requestId、原请求与完整性检查规则 | 降低多请求混淆和把中间结果当完成的风险 |
+| 不修改 `.planning/.active_plan` 与 `.trellis/.current-task` | 它们正被其他运行中对话使用，覆盖会造成并发污染 |
+
+## 错误与风险记录
+
+| 错误或风险 | 次数 | 处理 |
+|---|---:|---|
+| 工作树已有大量他人改动，且目标文件重叠 | 1 | 先记录基线，等待/协调重叠对话，采用精确补丁 |
+| 全局 planning/Trellis 活动指针属于其他任务 | 1 | 使用独立规划目录和显式任务路径，不覆盖指针 |
+| 使用 full-history fork 同时指定 explorer 角色被拒绝 | 1 | 改为 `fork_turns: none` 并显式提供完整研究上下文 |
+| 一次跨多文件补丁因上下文不精确失败 | 1 | 拆成小型精确补丁，不重复原调用 |
+
+## 完成标准
+
+- 新工具清单不再公开 `ccweb_request_reply`。
+- `ccweb_send_message.replyMode` 必填，并覆盖两种模式。
+- 旧工具名仍可经内部路由执行自动回传。
+- 目标运行提示明确模式，自动回传模式禁止手工重复回传。
+- 来源续跑提示包含关联信息和完整性判断要求。
+- 正式 MCP、Codex App 备用定义与 README 一致。
+- 相关专项测试和完整回归通过，`git diff --check` 通过。
+- 不执行生产 `ccweb` 服务重启。