mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-14 02:42:04 +08:00
Add benchmark results for fast3 and fast4, implement KeepAliveLspBridge, and add tests for staged strategies
- Added new benchmark result files: compare_2026-02-09_score_fast3.json and compare_2026-02-09_score_fast4.json. - Implemented KeepAliveLspBridge to maintain a persistent LSP connection across multiple queries, improving performance. - Created unit tests for staged clustering strategies in test_staged_stage3_fast_strategies.py, ensuring correct behavior of score and dir_rr strategies.
This commit is contained in:
catlog22
232
ccw/frontend/ISSUE_BOARD_NATIVE_CLI_ORCHESTRATOR_PLAN.md
Normal file
232
ccw/frontend/ISSUE_BOARD_NATIVE_CLI_ORCHESTRATOR_PLAN.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# CCW Issue 看板 × 原生 CLI 窗口 × 队列管理 × 编排器（tmux-like）集成规划
|
||||
|
||||
日期：2026-02-09
|
||||
输入参考：`.workflow/.analysis/ANL-codemoss-issue-panel-2026-02-09/report.md`（CodeMoss 看板/会话机制）
|
||||
|
||||
## 0) 已确认的关键决策（来自本次讨论）
|
||||
|
||||
- **终端形态**：Web 内嵌终端（`xterm.js`）+ 后端 **PTY**（需要 TTY 行为）
|
||||
- **默认会话壳**：先启动 `bash`（在 Windows 下优先走 WSL bash，其次 Git-Bash；都不可用时再降级）
|
||||
- **连续性**：用 `resumeKey` 作为“逻辑会话键”（可映射到 CLI 的 `--resume/--continue/--session-id` 等）
|
||||
- **Queue 增强优先级**：先做 **执行面**（Queue item → 投递到某个 CLI 会话并执行），管理面后置
|
||||
- **resumeKey 映射**：两种策略都要支持（`nativeResume` 与 `promptConcat`，见 4.6）
|
||||
|
||||
## 1) 要做的“产品形态”（一句话）
|
||||
|
||||
把 CCW 的 `Issues + Queue + Orchestrator + CLI Viewer` 变成一个统一的 **Issue Workbench**：
|
||||
|
||||
- 中间：Issue 看板（Kanban）+ Queue 管理（可视化/可执行/可重排）
|
||||
- 右侧：可切换的 **CLI 会话窗口**（Claude/Codex/Gemini/…），Web 内嵌终端承载，能向不同会话发送消息/命令
|
||||
- 编排器：能把节点输出/指令 **路由** 到某个 CLI 会话（类似 tmux 的 send-keys 到某个 pane / session）
|
||||
|
||||
---
|
||||
|
||||
## 2) 当前 CCW 已具备的关键底座（可直接复用）
|
||||
|
||||
### 2.1 IssueHub 的“右侧抽屉”模式
|
||||
|
||||
- IssueHub tabs：`ccw/frontend/src/components/issue/hub/IssueHubTabs.tsx`（目前：issues/queue/discovery）
|
||||
- IssueDrawer（右侧抽屉 + tabs）：`ccw/frontend/src/components/issue/hub/IssueDrawer.tsx`
|
||||
- SolutionDrawer（右侧抽屉）：`ccw/frontend/src/components/issue/queue/SolutionDrawer.tsx`
|
||||
|
||||
这让“右侧弹窗/抽屉内嵌 CLI 窗口”的 UI 成本很低：新增一个 tab 或替换为更通用的 drawer 即可。
|
||||
|
||||
### 2.2 Kanban DnD 组件
|
||||
|
||||
- `ccw/frontend/src/components/shared/KanbanBoard.tsx`（@hello-pangea/dnd）
|
||||
|
||||
可以直接用于 Issue Board（以及 Queue Board）。
|
||||
|
||||
### 2.3 “原生 CLI 输出”的 L0 形态已经存在（流式 + WS）
|
||||
|
||||
- 后端：`ccw/src/core/routes/cli-routes.ts`
|
||||
- `/api/cli/execute` 支持 streaming，并 WS 广播 `CLI_EXECUTION_STARTED` + `CLI_OUTPUT`（以及 completed/error）
|
||||
- 前端：`ccw/frontend/src/pages/CliViewerPage.tsx` + `ccw/frontend/src/stores/cliStreamStore.ts`
|
||||
- 多 pane 输出、执行恢复（`/api/cli/active`）
|
||||
|
||||
这套能力仍然有价值（例如：一次性非 TTY 执行、回放、聚合输出）。但本次已确认 MVP 需要 **PTY + xterm** 的真终端体验，因此会新增一套 “CLI Session（PTY）” 的生命周期与 WS 双向通道。
|
||||
|
||||
### 2.4 编排器右侧滑出 ExecutionMonitor 可复用交互
|
||||
|
||||
- `ccw/frontend/src/pages/orchestrator/ExecutionMonitor.tsx`
|
||||
|
||||
可作为 Issue 看板右侧“CLI/执行监控”面板的交互模板（布局、滚动、自动跟随、固定宽度/可变宽度）。
|
||||
|
||||
---
|
||||
|
||||
## 3) 参考：CodeMoss 的关键设计点（值得吸收）
|
||||
|
||||
来自 `.workflow/.analysis/ANL-codemoss-issue-panel-2026-02-09/report.md`：
|
||||
|
||||
1) **Kanban task 数据里直接挂执行关联字段**（threadId/engineType/modelId/autoStart/branchName 等）
|
||||
2) **拖到 inprogress 可触发自动动作**（启动会话/执行）
|
||||
3) “原生 CLI”更像 **长驻进程/协议**（codex app-server JSON-lines），UI 只是事件的消费者
|
||||
|
||||
CCW 的“差异现实”：
|
||||
|
||||
- CCW 是 Web Dashboard，不是 Tauri/Electron；但我们仍然选择 **node-pty + xterm.js**（后端持有 PTY 会话，前端 attach 显示），以满足“原生 CLI 窗口 / tmux-like 路由”的需求。
|
||||
|
||||
---
|
||||
|
||||
## 4) 目标能力拆解（功能点清单）
|
||||
|
||||
### 4.1 Issue Board（Kanban）
|
||||
|
||||
- 新增 tab：`board`（`/issues?tab=board`）
|
||||
- 列：`open` / `in_progress` / `resolved` / `completed`（`closed` 可独立列或筛选隐藏）
|
||||
- 支持：
|
||||
- 列内排序（sortOrder）
|
||||
- 跨列拖拽（更新 issue.status）
|
||||
- 选中卡片 → 右侧 Issue Workbench Drawer
|
||||
- 自动动作（对齐 CodeMoss）：
|
||||
- 从非 `in_progress` 拖到 `in_progress`：触发 `onDragToInProgress(issue)`（可配置）
|
||||
|
||||
### 4.2 右侧 “原生 CLI 窗口”（PTY + xterm.js）
|
||||
|
||||
右侧 drawer 增加 `Terminal`/`CLI` tab（或将 IssueDrawer 升级为 “IssueWorkbenchDrawer”）：
|
||||
|
||||
- 会话列表（per issue / per queue / global）
|
||||
- 多 CLI：Claude/Codex/Gemini/…
|
||||
- 每个会话绑定：
|
||||
- `sessionKey`：后端 PTY 会话 ID（用于 attach/close/send/resize）
|
||||
- `resumeKey`：逻辑连续性（用于生成 CLI 的 resume/continue 参数，或用于生成“同一会话下的命令模板”）
|
||||
- `tool/model/workingDir/envWrapper`（与 `ENSOAI_INTEGRATION_PLAN.md` 的能力对齐）
|
||||
- 终端能力（MVP）
|
||||
- attach：打开/切换某个会话的 xterm 视图
|
||||
- send：向会话发送文本（send-keys / paste）并可选择自动回车
|
||||
- resize：前端尺寸变化时同步 PTY size
|
||||
- close：关闭会话（释放进程与资源）
|
||||
- 操作
|
||||
- `Send`：把“指令/消息”直接投递到当前 PTY 会话（tmux send-keys 语义）
|
||||
- `Open in CLI Viewer`：可选（如果保留 `/api/cli/execute` 回放/聚合，则用于打开对应 execution；否则用于打开独立 CLI Viewer 的“会话视图”）
|
||||
|
||||
### 4.3 队列管理增强（Queue Workbench）
|
||||
|
||||
队列本身已有 API 结构（多队列 index + active_queue_ids、merge/split/activate 等，见 `ccw/src/core/routes/issue-routes.ts`），但前端仍偏“展示 + 少量操作”。
|
||||
|
||||
建议增强项：
|
||||
|
||||
- 多队列：列表/切换 active queues（UI 对接 `/api/queue/history` + `/api/queue/activate`）
|
||||
- 可视化重排：
|
||||
- 列表重排（按 execution_group 分组，组内 drag reorder）
|
||||
- 将 item 拖到不同 execution_group（更新 execution_group + execution_order）
|
||||
- 依赖图/阻塞原因（depends_on / blocked）
|
||||
- 与执行联动：
|
||||
- item `Execute in Session`（把 queue item 直接投递到指定 CLI 会话并执行；本次确认优先做这个）
|
||||
- item `Send to Orchestrator`（创建/触发一个 flow 执行）
|
||||
|
||||
### 4.4 编排器（Orchestrator）与 CLI 会话的“tmux-like 路由”
|
||||
|
||||
目标：编排器不只“跑一次性 CLI”，还能“向某个会话发送消息/指令”。
|
||||
|
||||
建议抽象：`CliMux`（CLI Multiplexer）
|
||||
|
||||
- **MVP（本次确认）CliMuxPersistent**：以 PTY 会话为核心，提供 `send(sessionKey, text)` / `resize` / `close`
|
||||
- **补充（可选）CliMuxStateless**：保留 `/api/cli/execute` 作为非 TTY 执行与审计回放通道
|
||||
|
||||
编排器侧最小改动思路：
|
||||
|
||||
- 继续保持 node 数据模型统一（prompt-template），但新增可选字段：
|
||||
- `targetSessionKey?: string`（或 `issueId` + `sessionName` 组合）
|
||||
- `delivery?: 'newExecution' | 'sendToSession'`（默认 newExecution）
|
||||
- FlowExecutor 在执行节点时：
|
||||
- `delivery=newExecution`：沿用现有 executeCliTool
|
||||
- `delivery=sendToSession`：调用 CliMux.send(targetSessionKey, instruction)
|
||||
|
||||
这样就形成“像 tmux 一样把消息打到指定 pane/session”的能力。
|
||||
|
||||
### 4.5 后端 CLI Session（PTY）协议草案（用于前后端对齐）
|
||||
|
||||
目标：让前端的 xterm 以 “attach 到 sessionKey” 的方式工作；Queue/Orchestrator 以 “send 到 sessionKey” 的方式工作。
|
||||
|
||||
- REST（建议）
|
||||
- `POST /api/cli-sessions`：创建会话（入参：`tool/model/workingDir/envWrapper/resumeKey/resumeStrategy/shell=bash`；出参：`sessionKey`）
|
||||
- `GET /api/cli-sessions`：列出会话（用于切换/恢复）
|
||||
- `POST /api/cli-sessions/:sessionKey/send`：发送文本（支持 `appendNewline`）
|
||||
- `POST /api/cli-sessions/:sessionKey/execute`：按 tool + resumeStrategy 生成并发送“可执行命令”（Queue/Orchestrator 走这个更稳）
|
||||
- `POST /api/cli-sessions/:sessionKey/resize`：同步 rows/cols
|
||||
- `POST /api/cli-sessions/:sessionKey/close`：关闭并回收
|
||||
- WS 事件（建议）
|
||||
- `CLI_SESSION_CREATED` / `CLI_SESSION_CLOSED`
|
||||
- `CLI_SESSION_OUTPUT`（`sessionKey`, `data`, `stream=stdout|stderr`）
|
||||
- `CLI_SESSION_ERROR`（`sessionKey`, `message`）
|
||||
- 兼容策略
|
||||
- 现有 `/api/cli/execute` + `CLI_OUTPUT` 保留：用于非 TTY 一次性执行、可审计回放、与现有 `CliViewerPage` 兼容
|
||||
- 新增“会话视图”可先复用 `cliStreamStore` 的 pane 结构（key 从 `transactionId` 扩展到 `sessionKey`）
|
||||
|
||||
### 4.6 `resumeKey` 映射策略（两种都实现）
|
||||
|
||||
`resumeKey` 的定位：一个跨 UI/Queue/Orchestrator 的“逻辑会话键”。同一个 `resumeKey` 下可能会对应：
|
||||
|
||||
- **策略 A：`nativeResume`（优先）**
|
||||
- 由 CLI 自己保存与恢复上下文（例如：`--resume/--continue/--session-id`）
|
||||
- 优点：上下文更可靠，输出格式更稳定；适合 Claude/Codex 这类有明确 session 概念的 CLI
|
||||
- 风险：不同 CLI 旗标/行为差异较大，需要 per-tool adapter（并要跟版本兼容）
|
||||
|
||||
- **策略 B：`promptConcat`（必须支持）**
|
||||
- CCW 自己维护 `resumeKey -> transcript/context`，每次执行把“历史 + 本次指令”拼成 prompt
|
||||
- 优点：对 CLI 依赖更少；即使 CLI 不支持 resume 也能连续；适合 Gemini/其它工具
|
||||
- 风险：token 成本、上下文截断策略、以及敏感信息/审计（需要明确 retention）
|
||||
|
||||
落地建议：后端新增 `ToolAdapter`（按 `tool` 输出“命令模板 + resume 参数 + prompt 注入方式”），`/api/cli-sessions/:sessionKey/execute` 统一走 adapter，Queue/Orchestrator 不直接拼 shell 命令。
|
||||
|
||||
---
|
||||
|
||||
## 5) 数据模型建议（对齐 CodeMoss，但保持 CCW 简洁）
|
||||
|
||||
### 5.1 Issue 扩展字段（建议在后端 issue schema 中落盘）
|
||||
|
||||
在 `Issue` 增加：
|
||||
|
||||
- `sortOrder?: number`（用于 board 列内排序）
|
||||
- `sessions?: Array<{ sessionKey: string; resumeKey: string; tool: string; model?: string; workingDir?: string; envWrapper?: string; createdAt: string }>`
|
||||
|
||||
注意：
|
||||
|
||||
- 后端 `ccw/src/commands/issue.ts` 中已经出现 `status: 'queued'` 等状态迹象；前端 `Issue['status']` 需要对齐，否则 board/filters 会漏状态。
|
||||
|
||||
### 5.2 QueueItem 与 Session 的绑定（可选）
|
||||
|
||||
- `QueueItem.sessionKey?: string`（允许把某条 queue item 固定投递到某会话）
|
||||
|
||||
---
|
||||
|
||||
## 6) 分期交付（从快到慢）
|
||||
|
||||
### Phase 1（2~6 天）：PTY 会话底座 + Drawer 内嵌终端 + Queue “执行面”
|
||||
|
||||
- [BE] 新增 `CLI Session (PTY)`：create/list/attach/close/send/resize（WS 双向：output + input + resize）
|
||||
- [FE] IssueDrawer 增加 `Terminal` tab：xterm attach 会话、切换会话、发送文本、resize、close
|
||||
- [FE] QueuePanel 增加 `Execute in Session`：选/新建 sessionKey，将 queue item 渲染成可执行指令投递到会话
|
||||
- [Auto] 支持“拖到 in_progress 自动执行”：触发 `Execute in Session`（可配置开关）
|
||||
|
||||
### Phase 2（2~5 天）：Issue Board（Kanban）+ Queue 管理面（多队列/重排/分组）
|
||||
|
||||
- [UI] IssueHubTabs 增加 `board`，IssueBoard 复用 `KanbanBoard`（状态列/排序/拖拽）
|
||||
- [UI] QueuePanel 增加多队列切换、execution_group 分组与 drag reorder、blocked/depends_on 可视化
|
||||
- [API] 若缺：跨 group 更新/排序落盘所需 endpoints（与现有 `/api/queue/reorder` 区分）
|
||||
|
||||
### Phase 3（3~8 天）：编排器与 CliMux 集成（tmux-like 路由）
|
||||
|
||||
- [Core] 引入 `CliMuxPersistent`（PTY 会话：send/resize/close）
|
||||
- [Orchestrator] prompt-template 增加 `targetSessionKey/delivery`
|
||||
- [UI] ExecutionMonitor 增加“路由到会话”的快捷操作（选择 session）
|
||||
|
||||
### Phase 4（长期）：安全、隔离、可观测、远程连接
|
||||
|
||||
- 资源隔离与安全策略（命令/路径白名单、审计日志、速率限制）
|
||||
- 会话回收（空闲超时、最大并发、OOM 保护）
|
||||
- 远程连接（可选）：会话分享、只读 attach、与外部 agent/daemon 的桥接（对齐 EnsoAI 的 Hapi/Cloudflared 思路）
|
||||
|
||||
---
|
||||
|
||||
## 7) 尚未决策（下一轮需要明确）
|
||||
|
||||
1) `bash` 的落地方式（跨平台）：
|
||||
- Linux/macOS：`bash -l`（或用户配置的 default shell）
|
||||
- Windows：优先 `wsl.exe -e bash -li`，其次 Git-Bash（`bash.exe`），都不可用时是否允许降级到 `pwsh`
|
||||
2) per-tool 的“nativeResume”参数与触发方式（需要按版本验证）：
|
||||
- Claude：`--resume/--continue/--session-id` 的选择，以及在 PTY 下如何稳定触发一次“发送”（命令式 `-p` vs 交互式 send-keys）
|
||||
- Codex/Gemini：各自的 session/resume 旗标与输出格式（是否能稳定 machine-readable）
|
||||
3) 安全边界：
|
||||
- 是否需要 per-workspace 的路径白名单、命令白名单、以及审计日志（特别是 Queue/Orchestrator 自动投递）
|
||||
Reference in New Issue
Block a user