69 lines
3.7 KiB
Markdown
69 lines
3.7 KiB
Markdown
# 标准 JavaScript 会话编排实施计划
|
||
|
||
## Goal
|
||
|
||
为 cc-web 增加受控的 JavaScript 脚本编排能力：通过 MCP 创建、写入、异步启动和停止脚本，并注入 `@ccweb/session` 标准包，让脚本 Promise 化调用现有 ccweb 会话。
|
||
|
||
## Current Phase
|
||
|
||
Phase 5：交付收尾
|
||
|
||
## Phases
|
||
|
||
### Phase 1：需求与代码链路确认
|
||
- [x] 汇总已确认的 API、脚本生命周期、异常通知和错误协议
|
||
- [x] 使用 codebase-memory 确认现有 MCP、会话创建、消息发送和 steer 入口
|
||
- **Status:** complete
|
||
|
||
### Phase 2：MCP 契约与脚本运行基础
|
||
- [x] 新增脚本 MCP 工具定义和 API manifest；验收：tools/list 能发现 create/write/run/get_run/stop/api 工具，工具输入 schema 和 manifest 可 JSON 序列化
|
||
- [x] 新增脚本目录、ESM 标准包注入和路径校验；验收：只能访问当前 cwd/.ccweb/scripts 下的 .js，包可被裸名 import
|
||
- [x] 新增异步脚本运行注册表、日志落盘、停止和重启恢复；验收：runId 查询、stdout/stderr 分段读取、stop 吊销凭据、重启标记 killed
|
||
- **Status:** complete
|
||
|
||
### Phase 3：会话标准包与服务端编排
|
||
- [x] 实现 Promise 化的当前会话、创建、发送、最后消息和语义分支能力；验收：每个 API 返回约定字符串/ID，错误携带稳定 code/details
|
||
- [x] 接入现有 ccweb 会话状态、Codex App steer 和异常来源会话通知；验收：同对话复用 steer，不重复运行同脚本，异常才插入来源通知
|
||
- **Status:** complete
|
||
|
||
### Phase 4：测试与回归
|
||
- [x] 编写脚本 MCP、标准包和异常通知回归测试
|
||
- [x] 运行语法检查、单元回归和项目 regression
|
||
- [x] 修复发现的问题并记录验证结果
|
||
- **Status:** complete
|
||
|
||
### Phase 5：交付
|
||
- [x] 清理临时 TODO CSV 和本计划状态
|
||
- [x] 汇总变更、测试结果、风险和未覆盖边界
|
||
- **Status:** complete
|
||
|
||
## Key Questions
|
||
|
||
1. 如何在不让脚本轮询的情况下等待现有会话完成？——由服务端等待会话状态和持久化消息变化。
|
||
2. 如何让同对话消息复用现有 steer，且不重复启动同一脚本？——调用现有 handleMessage/steer，并按来源+脚本路径拒绝并发重复运行。
|
||
3. 如何在脚本异常结束时通知来源对话，同时区分主动 stop？——运行注册表记录 stopRequested，只有非主动失败插入通知。
|
||
|
||
## Decisions Made
|
||
|
||
| Decision | Rationale |
|
||
|----------|-----------|
|
||
| 独立 Node 子进程运行脚本 | 隔离脚本异常并支持异步执行 |
|
||
| `.js` + `type=module`，注入 `@ccweb/session` | 保持用户示例并支持显式 ESM import/顶层 await |
|
||
| 服务端实现 Promise 等待 | 脚本不实现监听、轮询和等待封装 |
|
||
| 同对话发送复用现有 steer/插入 | 避免并行 turn 和递归死锁 |
|
||
| 运行记录和 stdout/stderr 持久化 | 支持异步 runId 查询、重启标记和长输出分段读取 |
|
||
| 主动 stop 不插入来源对话 | MCP 成功/失败结果已经是调用反馈 |
|
||
| 非正常结束插入来源对话通知 | 让启动脚本的 Agent 感知异常并继续处理 |
|
||
|
||
## Errors Encountered
|
||
|
||
| Error | Attempt | Resolution |
|
||
|-------|---------|------------|
|
||
| 用户级 planning-with-files 技能路径不存在 | 1 | 改用项目内 `.codex/skills/planning-with-files/` 版本 |
|
||
|
||
## Notes
|
||
|
||
- 不覆盖根目录已有的旧 `task_plan.md`、`findings.md`、`progress.md`，本任务使用 scoped planning 目录。
|
||
- 按已确认需求不设置运行时长、输出和并发硬上限；完整日志落盘，单次 get_run 只返回尾部或显式范围，避免无限响应。
|
||
- 脚本按受信代码执行，不伪造 JavaScript 沙箱；仍限制脚本路径、MCP 凭据生命周期和运行记录归属。
|