cc-web/.planning/2026-08-27-javascript-conversation-events/task_plan.md

JavaScript 会话状态与 idle 事件

目标

为 @ccweb/session 增加会话状态查询、直接子对话 ID 查询，以及指定会话从活动状态转为 idle 时的事件监听与注销能力；脚本不需要自行编写轮询。

已确认语义

• getConversationStatus(conversationId) 返回 Promise<'running' | 'waiting_for_children' | 'idle'>，优先级为 running > waiting_for_children > idle。
• getChildConversationIds(conversationId) 返回该对话通过 MCP 创建的直接持久子对话 ID，不递归返回孙对话。
• onConversationEvent(conversationId, 'idle', listener) 监听 running/waiting_for_children → idle 边沿，不因注册时已是 idle 而立即触发。
• onConversationEvent 返回注销函数；注销后不再产生新回调。
• 第一版只公开 idle 事件，但协议应便于后续扩展。
• 回调错误不应破坏底层监听；由脚本自己的未捕获异常规则处理。

阶段

1. [complete] 梳理现有会话状态与脚本包调用链
2. [complete] 确定状态查询、idle 等待、取消注销和 manifest 的协议语义
3. [complete] 补充失败测试覆盖状态查询和 idle 监听
4. [complete] 实现服务端状态查询与事件等待能力
5. [complete] 实现 @ccweb/session 监听、注销和状态 API
6. [complete] 更新 manifest 并运行单元与回归测试
7. [complete] 检查运行对话后重启并验证 idle 后未完成则继续发送的闭环
8. [complete] 清理临时计划并交付使用示例

风险

• 长时间监听必须能让脚本进程保持运行，又不能在注销后遗留服务端等待器。
• idle 必须是活动状态到 idle 的边沿事件，不能把“注册时已经 idle”误判为新完成。
• 当前来源对话允许 steer；事件监听必须与现有状态判定保持一致。
• 重启前必须确认除当前对话外不存在其他 running 会话；否则不重启并记录阻塞。

协议验收清单

• 状态查询：按 conversationId 返回 running、waiting_for_children 或 idle。
• 子对话查询：按 conversationId 返回直接子对话 ID 数组，不递归。
• 事件等待：只支持 idle，且只响应 running/waiting_for_children → idle。
• 注销取消：注销后停止包内监听，不再回调，也不遗留活动资源。
• manifest：三个新函数的参数、返回值、状态值、触发/注销语义和错误码与实现一致，总计 8 个函数。
• 场景闭环：idle 回调中判断任务未完成后调用 sendMessage 继续，随后再次进入 idle。

错误记录

错误	尝试	处理
运行时单测 5 !== 8	1	预期的红灯，证明新增 manifest/API 测试在旧实现上失败；进入实现阶段。