helixent

v1.3.1

Published

14 days ago

Helixent is a blue rabbit that writes code. It includes an Agent Loop, a Coding Agent, and a nice CLI.

0High
0Medium
0Low

magiccube

agent agent-loop coding-agent cli

English Version — 中文版本

Helixent

Helixent 是一只写代码的蓝色兔子。它包含一个 Agent Loop（智能体循环）、一个 Coding Agent（编码智能体），以及一个简洁的 CLI。

Demo

https://github.com/user-attachments/assets/4ad89f14-e338-43e4-82ce-91cb83d58be2

快速开始

主要特性

模型基础层
- 稳定的核心 Model 抽象以及面向提供商的接口，旨在让模型集成保持整洁和可复用。
- 支持多种模型。
智能体循环（中间件就绪）
- 可复用的 ReAct 风格智能体循环。
- 中间件支持，用于扩展行为（状态、工具编排、技能等）。
- 支持 Human-in-the-loop 逐一或批量对工具调用进行赋权。
- 详见中间件
Skills 支持
- 支持Agent Skills格式。
- 技能从以下路径发现和加载：
  - ~/.agents/skills
  - ~/.helixent/skills
  - ${current_project}/.agents/skills
  - ${current_project}/.helixent/skills
- 不同文件夹中允许存在同名的 Skill。
长期记忆
- 项目根目录 AGENTS.md 支持：如果仓库根目录存在 AGENTS.md，会自动加载作为项目指导。
编码智能体
- 专注于编码的智能体层，配备实用的工具（例如 bash、read_file、write_file、str_replace、list_files、glob_search、grep_search、apply_patch、file_info、mkdir、move_path 等），用于开发者工作流。
- 支持基于任务列表的计划模式。
CLI
- 提供 CLI（支持 TUI），用于交互式运行智能体并快速迭代。

Helixent 现已发布在 npm 上，因此你可以全局安装后运行，也可以选择通过 npx 无需安装直接运行：

安装与运行

方案一：安装后运行

npm install -g helixent@latest
cd path/to/your/project
helixent
helixent --help

方案二：无需安装直接运行

cd path/to/your/project
npx helixent@latest
npx helixent --help

模型配置

Helixent 将你的 CLI 配置存储在：

~/.helixent/config.yaml

列出已配置的模型

helixent config model list

添加新模型

helixent config model add

删除模型

helixent config model remove <model_name>

或者从已配置的模型列表中选择：

helixent config model remove

设置默认模型

helixent config model set-default <model_name>

或者从已配置的模型列表中选择：

helixent config model set-default

如何贡献

从源码开发与构建

本节介绍如何在 macOS 上从源码构建 Helixent，并将 helixent CLI 链接到全局 PATH。

1. 安装依赖

bun install

所有的推送和拉取请求都会在 GitHub Actions 中运行 bun run check。本地提交也会被 pre-commit 钩子拦截，直到相同检查通过为止。

2. 以开发模式运行

bun run dev

3. 构建二进制文件

bun run build:bin

构建完成后，你应该会得到：

dist/bin/helixent

4. 提交前检查

确保你的修改通过了所有的 lint 检查、类型检查和测试：

bun run check

或者仅运行测试：

bun run test

这也会由 pre-commit 钩子自动执行。这会让提交过程稍微慢一点，但我们认为这是值得的。毕竟，在一个 AI 主导的 GitHub 宇宙中，我们至少应该能处理好代码质量的"最后一公里"。

架构

Helixent 分为三个层次，外加一个用于第三方集成的 community 区域。

src/
├── foundation/    # 第一层 – 核心基础组件
├── agent/         # 第二层 – 智能体循环
├── coding/        # 第三层 – 编码智能体（领域特定）
└── community/     # 第三方集成（例如 OpenAI）

第一层：Foundation（基础层）

一切构建于其上的核心基础组件：

Model — 对 LLM 提供商的统一抽象。一次定义模型，无需修改智能体代码即可切换提供商。
Message — 单一的对话记录类型，端到端地在系统中流转——是对话的唯一真实来源。
Tool — 工具定义和执行机制（智能体可以调用的"动作"）。

第二层：Agent Loop（智能体循环层）

可复用的 ReAct 风格智能体循环：

维护整个对话记录的状态。
在循环中编排"思考 → 行动 → 观察"步骤。
并行调用工具，并将观察结果反馈到下一步推理中。
支持中间件以扩展行为（详见下文）。

这一层仅依赖于 Foundation，保持通用性——不绑定到任何特定领域。

第三层：Coding Agent（编码智能体层）

构建在通用智能体循环之上的领域特定智能体，预配置了面向编码的工具（read_file、write_file、str_replace、bash、list_files、glob_search、grep_search、apply_patch、file_info、mkdir、move_path 等）和技能中间件。

社区集成

可选的、解耦的适配器，为特定提供商实现 Foundation 接口：

community/openai — 基于 openai SDK 的 OpenAIModelProvider，兼容任何 OpenAI 兼容的端点。

如何从零构建一个编码智能体

以下是一个完整示例，展示如何使用 OpenAI 兼容的提供商创建一个编码智能体：

import { createCodingAgent } from "helixent/coding";
import { OpenAIModelProvider } from "helixent/community/openai";
import { Model } from "helixent/foundation";

// 1. 设置一个模型提供商（任何 OpenAI 兼容端点均可）
const provider = new OpenAIModelProvider({
  baseURL: "https://api.openai.com/v1",
  apiKey: process.env.OPENAI_API_KEY,
});

// 2. 使用你偏好的选项创建一个模型实例
const model = new Model("gpt-4o", provider, {
  max_tokens: 16 * 1024,
  thinking: { type: "enabled" },
});

// 3. 创建智能体——工具和技能会自动连接
const agent = await createCodingAgent({ model });

// 4. 流式获取智能体的响应
const stream = await agent.stream({
  role: "user",
  content: [{ type: "text", text: "在当前目录创建一个 hello world Web 服务器。" }],
});

for await (const message of stream) {
  for (const content of message.content) {
    if (content.type === "thinking" && content.thinking) {
      console.info("💡", content.thinking);
    } else if (content.type === "text" && content.text) {
      console.info(content.text);
    } else if (content.type === "tool_use") {
      console.info("🔧", content.name, content.input.description ?? "");
    }
  }
}

中间件

Helixent 提供了中间件系统，让你可以在循环的每个阶段观察和改变智能体的行为。中间件钩子按数组顺序依次执行。

可用钩子

| 钩子 | 触发时机 | |---|---| | beforeAgentRun | 用户消息追加后、第一步执行前，执行一次 | | afterAgentRun | 智能体即将停止时（无工具调用），执行一次 | | beforeAgentStep | 每一步开始时、调用模型之前执行 | | afterAgentStep | 每一步结束时、所有工具调用完成后执行 | | beforeModel | 模型上下文发送给提供商之前执行 | | afterModel | 收到模型响应后执行 | | beforeToolUse | 工具即将被调用时执行 | | afterToolUse | 工具调用完成后立即执行 |

每个钩子都会接收当前上下文，可以返回部分更新以合并回去，或返回 void 保持原样。

为什么选择 Bun？

智能体循环本质上是异步的——模型思考、工具执行、结果流式返回，往往并行发生。JavaScript/TypeScript 将原生 async/await 内置于语言和运行时中，使得并发编排变得直接，无需 Python 中回调的繁琐或 asyncio 的样板代码。

在各种 JS 运行时中，我们选择 Bun 的具体原因如下：

与 Claude Code 相同的运行时 — Bun 驱动着 Claude Code 和越来越多 TypeScript 优先的工具。它天生为速度而生，编译后的产物是一个单一的原生可执行文件。
性能 — HTTP、文件系统 I/O 和冷启动都比 Node 明显更快，这对于智能体循环每次运行可能发出数十次工具调用的场景来说，差异显著。
独立可执行文件 — bun build --compile 输出一个自包含的二进制文件。分发 CLI 就像给用户一个单一文件一样简单——无需单独安装运行时。
开箱即用 — 测试运行器、打包器和 TypeScript 支持都随 Bun 一起提供，无需额外配置工具链。

路线图

子智能体（Sub-agent） — 在一次运行中派生子智能体来独立处理子任务，每个子智能体拥有自己的上下文和工具集。
智能体团队（Agent Team） — 多智能体协作，智能体之间可以协调、委派和共享结果，以协作解决复杂问题。
打印模式（Print Mode） — 类似 Claude Code 的渲染模式，以丰富、友好的终端 UI 流式展示智能体的思考过程、工具调用和输出。
会话管理（Sessioning） — 基于本地文件的会话存储，保存智能体的上下文和历史记录。