catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-12 02:37:45 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
d0cdee2e6839d23463917dabed37355dbb42e5f9
Claude-Code-Workflow/ccw/frontend/ISSUE_BOARD_NATIVE_CLI_ORCHESTRATOR_PLAN.md
catlog22 4344e79e68 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.
2026-02-09 20:45:29 +08:00

12 KiB
Raw Blame History

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 View Git Blame Copy Permalink