架构总览

大多数 AI 编码工具不过是一个聊天框加一个模型。Helix 不是。

Helix 是一个 以 workspace 为中心的多 agent 工程系统——它把代码库、终端、模型、工具链与多 agent 编排统一在单一工作流中，让 AI 能端到端地完成真实软件工程任务，而不只是回答问题。

系统总览

┌─────────────────────────────────────────────────────┐
│  Helix UI (helix · Flutter Desktop / Web)         │
│  ├─ Workspace 与会话管理                              │
│  ├─ SubAgent 并行状态面板                             │
│  ├─ MCP 工具执行实时视图                              │
│  └─ 模型选择器与 Dual Agent 模式                      │
│                    │ REST + WebSocket                │
└────────────────────┼────────────────────────────────┘
                     ▼
┌─────────────────────────────────────────────────────┐
│  Helix Backend (helix-agent · Go)                       │
│  ├─ Workspace Manager — 隔离与生命周期管理              │
│  ├─ Session Engine — 流式输出 + 工具调用 + 重试          │
│  ├─ Multi-Agent — Manager / Execution / SubAgent     │
│  ├─ Context Engine — KV Cache + Compact 压缩          │
│  ├─ 12 个内置 MCP server — Shell / FS / LSP / …        │
│  └─ Provider 适配 — DeepSeek / Claude / OpenAI         │
└─────────────────────────────────────────────────────┘

四大设计原则

1. 在长任务中保持用户意图稳定

单个 Agent 在 30 多次连续工具调用后往往会忘掉初始目标。Helix 用分层编排解决这个问题：Manager Agent 锁定目标，Execution Agent 推进实现，SubAgent 处理深度子任务。每一层职责单一，目标在执行链上的每个节点都受到保护。

2. 让并行执行可观察

许多产品让 AI 在后台"默默思考"，用户只能盯着加载动画。Helix 把子任务的创建、执行状态与中间结果都暴露在 UI 中——你能实时看到哪个 agent 在做什么、进度如何、发现了什么。

3. 让长会话保持健康

工具密集的会话会以惊人的速度消耗上下文。Helix 采用 Cache + Compact 双重策略：大体量工具输出存入 KV cache，按需召回；旧对话被压缩为结构化摘要。这样单个会话可以连续运行数小时甚至跨天，不必"开新对话"。

4. 严格隔离项目

每个 Workspace 都拥有独立的会话历史、工具配置、模型选择和 MCP server 实例。你可以同时在前端仓库、后端服务和基础设施项目中工作——它们的上下文绝不会交叉污染。

多 Agent 执行模型

Helix 使用三种执行角色协同完成任务：

角色	职责	执行模式
Manager Agent	守护用户目标，校验完成质量	贯穿整个任务生命周期
Execution Agent	推进主要的编码与工具流程	在主会话中顺序执行
SubAgent	在隔离上下文中处理聚焦的子任务	并行执行，返回精炼摘要

SubAgent 的关键设计细节（来自后端实现）：

每个 SubAgent 创建一个独立子会话（ID 形如 sub_{parentSessionID}_{timestamp}），上下文完全隔离
为防止递归创建，SubAgent 会自动过滤三个工具：run_subagent、create_worktree_binding 与 start_code_review，并排除整个 builtin_subagent MCP server
当 SubAgent 结果超过 2,000 字符 时，AI 会自动生成 ≤ 500 字符 的精炼摘要；若摘要失败则截断
多个 SubAgent 真正并行运行、互不干扰——总耗时等于最慢的那一个

数据与交互流

用户提交任务
    │
    ▼
后端通过 WebSocket 流式输出模型结果
    │
    ├─ 工具调用执行（filesystem / LSP / Git / 终端 / MCP）
    │
    ├─ 必要时并行启动 SubAgent
    │   ├─ SubAgent A：搜索多个模块 ──→ 返回摘要
    │   └─ SubAgent B：分析安全模式 ──→ 返回摘要
    │
    ├─ 结果合并回主会话
    │
    └─ Cache / Compact 策略持续维护上下文健康

Workspace：基本执行单元

Workspace 不只是"打开一个目录"。在 Helix 中，它是状态隔离的基本边界：

独立的会话历史——每个 Workspace 维护自己的对话与上下文
独立的工具配置——Shell、文件系统、LSP 等 MCP server 按 Workspace 实例化
独立的模型与 Profile——不同项目可使用不同模型与系统 prompt
本地与远程目标——本地目录与远程服务器都可以作为 workspace
生命周期管理——创建 → 连接 → 懒加载 → 断开 → 空闲超时（默认 30 分钟） → 自动关闭

典型用法：

Workspace A：前端迭代（Claude + Serena LSP）
Workspace B：后端迁移（DeepSeek + 远程 SSH）
Workspace C：基础设施巡检（GPT-4o + Tmux 终端）

运行时组件

前端：helix

基于 Flutter 的跨平台客户端，支持 macOS 桌面端 App（推荐）与 Web 部署。

三栏布局：会话列表 + 聊天区 + 工具面板
桌面端原生多窗口支持（聊天、SubAgent、Workspace 选择器窗口）
默认 WebSocket 流式，SSE 兜底
实时工具调用展示（MCP 工具名、参数、结果）
Dual Agent 模式分阶段展示（Think → Discuss → Synthesize → Execute）

后端：helix-agent

基于 Go 的服务，围绕 Workspace → Session → Agent → MCP Tools 四层架构构建。

每个 Workspace 拥有独立的 Session Manager 与内置 MCP manager
Session Engine 支持流式输出、工具调用循环（最多 100 轮）与自动重试
内置 KV cache（Pebble 存储引擎，SHA256 内容寻址去重）
Worktree 绑定：写操作在隔离的 git worktree 分支中执行，保护主分支

模型适配层

统一的 Provider 抽象，适配四类模型 provider：

Anthropic Claude——支持 extended thinking（默认 32K token thinking budget）
DeepSeek——透传 reasoning_content，性价比高，适合编码
OpenAI——标准 Chat Completions API
OpenAI Responses API——面向 GPT-5.x 系列的下一代接口

模型路由同时支持 providerId:modelId 精确指定与基于前缀的自动推断。

部署方式

方式	适用场景	亮点
桌面端 App	日常开发（推荐）	上手最快，本地文件/终端/Workspace 集成完整
Web + 后端	远程环境、团队共享、快速评估	后端可本地或远程部署，Web 支持 PWA
自托管后端	企业内网、合规需求	数据与网络完全自控

安全与隐私

Provider API key 由用户掌控——Helix 永不持有
Workspace 数据存放在本地或自托管后端的数据目录
不强制依赖任何第三方数据存储
严格合规环境可选择自托管路径

继续阅读

功能总览——核心能力的完整概览
多 Agent 架构——深入理解三层协作
上下文管理——Cache + Compact 双重策略详解
Workspace 架构——Workspace 隔离与生命周期
多模型支持——模型选择与切换策略

系统总览​

四大设计原则​

1. 在长任务中保持用户意图稳定​

2. 让并行执行可观察​

3. 让长会话保持健康​

4. 严格隔离项目​

多 Agent 执行模型​

数据与交互流​

Workspace：基本执行单元​

运行时组件​

前端：helix​

后端：helix-agent​

模型适配层​

部署方式​

安全与隐私​

继续阅读​