mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-10 02:24:35 +08:00
4344e79e68
- 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.
314 lines
14 KiB
Markdown
314 lines
14 KiB
Markdown
# EnsoAI → CCW Frontend 集成计划（架构识别 / 多 CLI / 远程连接 / 功能盘点）
|
||
|
||
日期：2026-02-09
|
||
目标：把 `G:\github_lib\EnsoAI` 的“多路智能并行工作流”核心体验，按 CCW 现有能力边界，规划性集成到 `D:\Claude_dms3\ccw\frontend`（Web Dashboard）。
|
||
|
||
> 注：由于本环境 `read_file` 工具仅允许读取 `D:\Claude_dms3`，EnsoAI 代码引用路径来自本地检索结果与 PowerShell 阅读，不影响结论准确性。
|
||
|
||
---
|
||
|
||
## 1) EnsoAI 架构速览（你要找的“架构骨架”）
|
||
|
||
EnsoAI 是一个 Electron 桌面应用，典型三段式：
|
||
|
||
- **Main Process（主进程）**：`G:\github_lib\EnsoAI\src\main`
|
||
- IPC handlers、系统服务集成、Git/PTY/远程共享/代理、Claude 生态集成（Provider、MCP、IDE Bridge）
|
||
- **Preload（桥接层）**：`G:\github_lib\EnsoAI\src\preload`
|
||
- `window.electronAPI.*` 暴露给渲染进程（settings、hapi、cloudflared、mcp、git、terminal 等）
|
||
- **Renderer（UI）**：`G:\github_lib\EnsoAI\src\renderer`
|
||
- React UI：Worktree/Git、Monaco 编辑器、xterm 终端、多 Agent Chat、设置面板等
|
||
- **Shared（共享）**：`G:\github_lib\EnsoAI\src\shared`
|
||
- types/i18n/ipc channel 等
|
||
|
||
核心思路：**把“多 Agent 并行”落到“多 worktree + 多终端会话 + 可恢复的 AI session”上**，并提供一揽子系统集成（Claude IDE Bridge / MCP / 远程共享 / proxy）。
|
||
|
||
---
|
||
|
||
## 2) EnsoAI 如何调用多 CLI（重点：两条路径）
|
||
|
||
### 2.1 非交互任务调用（更像“工具/能力调用”）
|
||
|
||
入口：`G:\github_lib\EnsoAI\src\main\services\ai\providers.ts`
|
||
|
||
- 按 provider 选择 CLI：
|
||
- Claude：`claude -p --output-format ... --model ... [--session-id] [--no-session-persistence]`
|
||
- Codex：`codex exec -m <model> ...`（prompt 走 stdin）
|
||
- Gemini：`gemini -o ... -m ... --yolo`（prompt 走 stdin）
|
||
- Cursor：`agent -p --output-format ... --model ...`（不支持部分 claude flags）
|
||
- 统一策略：**通过用户 shell 包装 spawn**，prompt 统一写 stdin；实现了 kill 逻辑与输出解析（尤其 Claude JSON 输出的版本兼容）。
|
||
|
||
适用场景：commit message 生成、code review、分支命名等“非交互式一次性任务”。
|
||
|
||
### 2.2 交互终端调用（更像“人机对话/操作台”）
|
||
|
||
入口：`G:\github_lib\EnsoAI\src\renderer\components\chat\AgentTerminal.tsx`
|
||
|
||
关键点：
|
||
|
||
- **会话恢复**：`--resume <id>` / `--session-id <id>`（并对 Cursor/Claude initialized 的差异做了兼容）
|
||
- **IDE 集成**：Claude 追加 `--ide`
|
||
- **环境包装（environment wrapper）**：
|
||
- `native`：直接执行 `<agentCommand> ...`
|
||
- `hapi`：`hapi <agent> ...` 或 `npx -y @twsxtd/hapi <agent> ...`，并注入 `CLI_API_TOKEN`
|
||
- `happy`：`happy <agent> ...`（同理）
|
||
- **跨平台兼容**：
|
||
- WSL：用 `wsl.exe -e sh -lc ...` 进入登录 shell
|
||
- PowerShell：用 `& { <command> }` 避免 `--session-id` 被 PowerShell 当成自身参数
|
||
- **tmux 支持（非 Windows + Claude）**：把会话包进 tmux，保证“断开 UI 也能续接”一类体验
|
||
|
||
适用场景：多 Agent 终端式并行对话、跨会话恢复、长任务驻留。
|
||
|
||
### 2.3 CLI 探测/安装（多 CLI 的“可用性治理”）
|
||
|
||
- 探测：`G:\github_lib\EnsoAI\src\main\services\cli\CliDetector.ts`
|
||
- 内置：`claude/codex/droid/gemini/auggie/cursor-agent/opencode`
|
||
- 通过 PTY 执行 `<cmd> --version`，Windows 放宽超时
|
||
- 安装（EnsoAI 自身 CLI，用于打开目录等）：`G:\github_lib\EnsoAI\src\main\services\cli\CliInstaller.ts`
|
||
- 跨平台脚本生成（macOS/Windows/Linux），以及可能的管理员权限处理
|
||
|
||
---
|
||
|
||
## 3) EnsoAI 的“远程连接 / 系统集成”到底做了什么
|
||
|
||
### 3.1 Claude IDE Bridge（Claude Code CLI 的 IDE 集成）
|
||
|
||
入口：`G:\github_lib\EnsoAI\src\main\services\claude\ClaudeIdeBridge.ts`
|
||
|
||
机制要点：
|
||
|
||
- 本机启动 WebSocket server（绑定 127.0.0.1，随机端口）
|
||
- 写 lock file 到：
|
||
- `~/.claude/ide/<port>.lock`（或 `CLAUDE_CONFIG_DIR/ide/<port>.lock`）
|
||
- payload 含：`pid/workspaceFolders/ideName/transport/ws/runningInWindows/authToken`
|
||
- Claude Code 客户端连接时需 header：
|
||
- `x-claude-code-ide-authorization: <authToken>`
|
||
- 可选 `x-claude-code-workspace` 辅助路由
|
||
- 可向 Claude Code 广播通知：
|
||
- `selection_changed`
|
||
- `at_mentioned`
|
||
- 为“运行 Claude CLI 子进程”注入 env：
|
||
- `ENABLE_IDE_INTEGRATION=true`
|
||
- `CLAUDE_CODE_SSE_PORT=<port>`（配合 `claude --ide`）
|
||
|
||
这属于“系统集成层”，不是普通 API 配置；它解决的是：**Claude Code CLI 与 IDE/宿主之间的状态互通**。
|
||
|
||
### 3.2 MCP Servers 管理（与 Claude 生态配置打通）
|
||
|
||
入口：`G:\github_lib\EnsoAI\src\main\services\claude\McpManager.ts`
|
||
|
||
- 读写 `~/.claude.json` 的 `mcpServers`
|
||
- 支持：
|
||
- stdio MCP：`command/args/env`（UI 可编辑）
|
||
- HTTP/SSE MCP：`type/url/headers`（一般保留原配置，避免破坏）
|
||
|
||
### 3.3 远程共享（Hapi）与公网暴露（Cloudflared）
|
||
|
||
- Hapi：`G:\github_lib\EnsoAI\src\main\services\hapi\HapiServerManager.ts` + `src/main/ipc/hapi.ts`
|
||
- `hapi server` 或 fallback `npx -y @twsxtd/hapi server`
|
||
- env：`WEBAPP_PORT/CLI_API_TOKEN/TELEGRAM_BOT_TOKEN/WEBAPP_URL/ALLOWED_CHAT_IDS`
|
||
- UI 文案明确：**Web + Telegram 远程共享 agent sessions**
|
||
- Cloudflared：`G:\github_lib\EnsoAI\src\main\services\hapi\CloudflaredManager.ts`
|
||
- 安装到 userData/bin（避开 asar 只读）
|
||
- 支持 quick tunnel / token auth tunnel，可选 `--protocol http2`
|
||
|
||
### 3.4 Proxy（代理）
|
||
|
||
入口：`G:\github_lib\EnsoAI\src\main\services\proxy\ProxyConfig.ts`
|
||
|
||
- Electron session 级代理 + 子进程环境变量注入（HTTP(S)_PROXY / NO_PROXY）
|
||
- 内置代理联通性测试（HEAD 请求多个探测 URL）
|
||
|
||
---
|
||
|
||
## 4) EnsoAI 功能点全量清单（按模块）
|
||
|
||
> 这里是“罗列所有功能点”的汇总视图；后续集成计划会用它做映射。
|
||
|
||
### 4.1 多 Agent / 多 CLI（核心卖点）
|
||
|
||
- 多 Agent 终端会话并行（Claude/Codex/Gemini + 额外探测 Droid/Auggie/Cursor/OpenCode）
|
||
- 会话持久化与恢复（session-id / resume）
|
||
- CLI 可用性探测（installed/version/timeout）
|
||
- 环境包装：native +（hapi/happy）+ tmux + WSL/PowerShell 兼容
|
||
|
||
### 4.2 Git / Worktree 工作流（核心载体）
|
||
|
||
- Worktree 创建/切换/删除；分支为“一等公民”
|
||
- Source Control 面板：
|
||
- 文件变更列表、stage/unstage、commit、history、branch 切换
|
||
- diff viewer / diff review modal
|
||
- 三栏 Merge Editor（冲突解决）
|
||
- 远端同步：fetch/pull/push 等
|
||
|
||
### 4.3 编辑器与文件系统
|
||
|
||
- Monaco 编辑器、多标签、拖拽排序
|
||
- 文件树 CRUD（新建/重命名/删除）
|
||
- 预览：Markdown / PDF / Image
|
||
- 未保存变更保护、冲突提示
|
||
|
||
### 4.4 AI 辅助开发
|
||
|
||
- AI commit message 生成
|
||
- AI code review（围绕 diff 的审查/优化）
|
||
- 分支命名辅助（推测）
|
||
|
||
### 4.5 Claude 生态集成
|
||
|
||
- Claude Provider 管理（监听/应用 `~/.claude/settings.json`）
|
||
- MCP servers 管理（`~/.claude.json`，stdio + HTTP/SSE）
|
||
- Prompts / Plugins 管理
|
||
- Claude IDE Bridge（WS + lock file + selection/@ 通知）
|
||
|
||
### 4.6 远程与网络
|
||
|
||
- Hapi remote sharing（Web + Telegram）
|
||
- Cloudflared tunnel 暴露本地服务
|
||
- 代理设置与测试
|
||
|
||
### 4.7 通用体验
|
||
|
||
- 多窗口、多工作空间
|
||
- 主题同步（终端主题）
|
||
- 快捷键/命令面板
|
||
- 设置 JSON 持久化
|
||
- Web Inspector、更新通知
|
||
|
||
---
|
||
|
||
## 5) CCW Frontend 基线（与 EnsoAI 的可复用对齐点）
|
||
|
||
CCW 前端已具备的关键“载体/底座”：
|
||
|
||
- **CLI Viewer（多 pane）**：`ccw/frontend/src/pages/CliViewerPage.tsx`
|
||
- 已支持 split/grid 布局、聚焦 pane、执行恢复与 WebSocket 输出接入
|
||
- **CLI Endpoints / Installations**：
|
||
- `ccw/frontend/src/pages/EndpointsPage.tsx`（litellm/custom/wrapper）
|
||
- `ccw/frontend/src/pages/InstallationsPage.tsx`（install/upgrade/uninstall）
|
||
- **MCP Manager（含 Cross-CLI）**：`ccw/frontend/src/pages/McpManagerPage.tsx`
|
||
- **后端 CLI executor 体系**：`ccw/src/tools/cli-executor-core.ts` + `ccw/src/core/routes/cli-routes.ts`
|
||
- 已有 active executions 恢复、history/sqlite、tool availability、wrapper/tools 路由等能力
|
||
|
||
CCW 与 EnsoAI 的主要差异（决定“集成方式”）：
|
||
|
||
- EnsoAI 是“桌面 IDE/工作台”，CCW 是“Web Dashboard + Orchestrator”
|
||
- EnsoAI 的 Worktree/Git/Editor/PTY 属于重资产 IDE 能力；CCW 目前不承担这些（除非明确要扩域）
|
||
- EnsoAI 的 IDE Bridge / Hapi/Cloudflared 属于系统集成层；CCW 当前需要新增后端能力才能对齐
|
||
|
||
---
|
||
|
||
## 6) 集成策略（把 EnsoAI 优势带到 CCW，但不把 CCW 变成 IDE）
|
||
|
||
优先级建议：
|
||
|
||
1) **先移植“多 Agent 并行调度 + 可恢复输出体验”**（与 CCW 现有 CLI viewer/cli executor 高度匹配）
|
||
2) 再做 **“多 CLI 治理与配置同步”体验收敛**（Installations/Endpoints/MCP 的信息架构对齐）
|
||
3) 最后才考虑 **系统集成层**（Claude IDE Bridge、远程共享、tunnel/proxy 等）
|
||
|
||
---
|
||
|
||
## 7) Roadmap（集成到 `ccw/frontend` 的分期落地）
|
||
|
||
### Phase 0 — 对齐与设计（1~2 天）
|
||
|
||
- 产出：统一术语与信息架构
|
||
- Agent / Tool / Endpoint / Wrapper 的定义
|
||
- “并行会话”= 多 execution 并发 + CLI viewer 多 pane 展示
|
||
- 产出：UI 草图（Agent Matrix + 单 Agent Details + 快捷动作）
|
||
|
||
### Phase 1（MVP）— Agent Matrix（最接近 EnsoAI 卖点，且最可落地）
|
||
|
||
目标：在 CCW 中“一屏管理多 Agent 并行执行”，并可一键把多个 execution 打开到 CLI Viewer 的多个 pane。
|
||
|
||
前端交付（建议）：
|
||
|
||
- 新页面：`/agents`（或并入 `/cli-viewer` 的“Matrix 模式”）
|
||
- 卡片：每个 Agent（claude/codex/gemini/...）展示 installed/version/status
|
||
- 快捷动作：
|
||
- Run prompt（选择 mode：analysis/plan/review…）
|
||
- Open in CLI Viewer（自动分配 pane）
|
||
- Resume / View history（打开对应 conversation/execution）
|
||
- 并行启动：一次选多个 Agent → 并发触发多次执行 → 同步创建 viewer tabs
|
||
- 复用：`cliStreamStore` + `viewerStore`
|
||
|
||
后端依赖（最小化）：
|
||
|
||
- 若现有 `/api/cli/*` 已满足执行与 active 恢复：仅需补一个 “agents list/status” 聚合接口（可由现有 installations/status 拼装）
|
||
|
||
验收标准：
|
||
|
||
- 同一 prompt 可对多个 agent 并行执行，输出稳定落到 CLI Viewer 多 pane
|
||
- 刷新页面后仍可恢复 running executions（复用 `/api/cli/active`）
|
||
- 每个 execution 可追溯到 history（已有 sqlite/history 体系）
|
||
|
||
### Phase 2 — Wrapper/Endpoint 体验收敛（对齐 EnsoAI 的 environment wrapper 思路）
|
||
|
||
目标：把 EnsoAI 的 `native/hapi/happy/tmux/wsl` 思路映射成 CCW 的 endpoint/wrapper 配置，形成一致的“运行环境选择”体验。
|
||
|
||
前端交付（建议）：
|
||
|
||
- 在 Agent Matrix 卡片中加入：
|
||
- “运行环境”下拉（native / wrapper endpoints）
|
||
- “会话策略”选项（new / resume / no-persistence 等，取决于后端 executor 支持）
|
||
- 在 EndpointsPage 中标注 “可用于哪些 agent/tool” 的适配关系（避免用户创建了 wrapper 但不知道生效范围）
|
||
|
||
后端依赖：
|
||
|
||
- wrapper endpoints 的能力需要明确：是否等价于 EnsoAI 的 `hapi/happy` 前缀包装？（如果是，需在 cli executor 的 command builder 支持这一类 wrapper）
|
||
|
||
### Phase 3 — Claude IDE Bridge（可选，大改动，系统集成层）
|
||
|
||
目标：在 CCW（Node 服务）侧实现类似 EnsoAI 的 IDE Bridge，并在前端提供状态面板。
|
||
|
||
前端交付（建议）：
|
||
|
||
- Settings 新增 “IDE Integration（Claude Code）”：
|
||
- Bridge enable/disable
|
||
- 当前端口、lock file 路径、连接状态、最近一次 selection/@ 通知
|
||
- “复制 token / 复制诊断信息”按钮
|
||
|
||
后端依赖：
|
||
|
||
- 需要在 CCW server 里增加 WS server + lock file 写入逻辑（参考 EnsoAI 的 `ClaudeIdeBridge.ts`）
|
||
- 需要明确 Claude Code CLI 的兼容要求（协议版本、headers、env key）
|
||
|
||
### Phase 4 — 远程共享与公网暴露（可选，偏产品功能）
|
||
|
||
目标：把 EnsoAI 的 Hapi + Cloudflared 能力变成 CCW 的“远程访问/协作”能力。
|
||
|
||
前端交付（建议）：
|
||
|
||
- Settings 新增 “Remote Sharing”：
|
||
- 启停服务、端口、token、允许列表
|
||
- Cloudflared 安装/启停、URL 展示、一键复制
|
||
|
||
后端依赖：
|
||
|
||
- 需要引入 hapi/cloudflared 管理模块（或选择更贴近 CCW 的方案，例如仅 cloudflared 暴露 CCW server）
|
||
- 需要明确安全边界（认证、token 轮换、日志脱敏、默认不开放）
|
||
|
||
---
|
||
|
||
## 8) EnsoAI 功能 → CCW 现状 → 集成建议（映射表）
|
||
|
||
| EnsoAI 功能 | CCW 现状 | 建议集成方式（优先级） |
|
||
|---|---|---|
|
||
| 多 Agent 并行会话 | 有 CLI viewer + executor，但缺“一屏矩阵” | Phase 1：新增 Agent Matrix + 自动 pane 分配 |
|
||
| CLI 探测/安装 | 有 InstallationsPage | Phase 1：把 Installations 信息在 Matrix 中复用展示 |
|
||
| environment wrapper（hapi/happy/tmux/wsl） | 有 wrapper endpoints 概念 | Phase 2：把 wrapper endpoints 显式接到 Agent 执行选择 |
|
||
| Claude MCP servers 管理 | 有 MCP Manager（含 Cross-CLI） | 现有功能可继续增强（模板/同步策略） |
|
||
| Claude IDE Bridge | 暂无 | Phase 3（可选）系统集成层模块 + Settings 面板 |
|
||
| Hapi remote sharing + Cloudflared | 暂无 | Phase 4（可选） |
|
||
| Worktree/Git/Editor/Merge | 暂无（且是 IDE 域） | 默认不集成；若要做需单独立项 |
|
||
|
||
---
|
||
|
||
## 9) 下一步（如果你要我继续落地）
|
||
|
||
你可以选择一个切入点，我可以直接在 `ccw/frontend` 开工实现：
|
||
|
||
1) **Phase 1（推荐）**：新增 `/agents` 页面（Agent Matrix），复用现有 `/api/cli/*` 与 CLI viewer
|
||
2) **Phase 2**：把 wrapper endpoints 打通到“Agent 运行环境选择”
|
||
3) **Phase 3/4**：需要先确认产品边界与安全策略，再做后端设计
|
||
|