工作流与扩展

Helix 设计用于承载真实的工程工作，这意味着它需要：用于代码改动的结构化工作流、按项目自定义 Agent 行为的方式，以及干净的扩展点，让你能在不修改核心系统的前提下教它新能力。

本页覆盖四个支柱：用于隔离代码改动的 Git Worktree 工作流、控制 Agent 行为的 Agent Profile 体系、注入领域知识的 Skills 体系，以及用于扩展工具集的自定义 MCP server 配置。

Git Worktree 工作流

当 Agent 需要修改代码时，Helix 会创建一个隔离的 Git worktree，让改动发生在一个独立分支上。这样既能保护你的工作树免受半成品改动的影响，也能让多个 sub agent 并发修改代码而不互相影响。

工作原理

创建绑定 —— Agent 调用 create_worktree_binding，传入项目目录与任务描述
设置分支 —— Helix 解析 Git 根目录，以当前分支为基准，创建一个名为 aiagent/{sessionID}/{task-description}-{hash} 的新分支
创建 worktree —— 在 Helix 数据目录下创建一个独立的工作目录，并检出到新分支
执行工作 —— Agent（或 sub agent）在 worktree 中读取、编辑并提交文件，原工作目录不受影响
合并回主线 —— 任务完成后，Helix 提交剩余改动，切换回基础分支，拉取最新代码，执行 --no-ff merge，并清理 worktree 与临时分支

这为什么重要

安全 —— 主工作树永远不会被直接修改。如果 Agent 的改动不符合你的预期，你可以在合并之前检查分支。
并行性 —— 多个 sub agent 可以各自拥有自己的 worktree 与分支，同时修改代码库的不同部分，执行期间不会出现合并冲突。
代码审查 —— 系统提示词会要求 Agent 在合并前运行 start_code_review，为 AI 产出的改动提供内建的质量门。
干净的历史 —— --no-ff merge 保留了清晰记录，能看出 Agent 改了什么、何时改的。

示例流程

用户："重构鉴权模块并更新其测试"

Agent 思考：
  → 为鉴权模块创建 worktree binding
  → 启动 sub agent A：在 worktree A 中重构鉴权模块
  → 启动 sub agent B：在 worktree B 中更新鉴权测试
  → 两者在隔离分支上并发工作
  → 各自在完成前运行代码审查
  → 改动依次合并回主分支

提示

你不需要手动创建 worktree。Agent 会根据任务自行判断何时需要隔离。对于代码审查、架构分析这类只读任务，不会创建 worktree。

Agent Profiles

Agent Profile 让你可以创建可复用的配置，控制 Agent 的行为。每个 profile 定义了模型、可用工具、思考行为与运行参数。你可以为不同任务创建不同的 profile：一个快速审查者、一个深思熟虑的架构师、一个对成本敏感的日常助手。

Profile 配置

Profile 以 YAML 文件形式存储于 ~/.aiagent/agent/{id}.yaml。每个 profile 可配置：

字段	控制内容
Model	使用哪个 LLM，格式为 `providerId:modelId`
MCP Servers	Agent 可访问的 MCP server（限制工具集）
Thinking Mode	是否启用 extended thinking 以及 token 预算
Language	Agent 的回答语言（如 `zh`、`en`）
Timeout	最大会话时长（支持超过 5 小时的会话）
Cache and Compaction	上下文缓存与对话压缩策略

Profile 与 Workspace 的关联

Profile 与 Workspace 绑定。当你在某个 Workspace 中创建新的对话会话时，Workspace 的 profile 配置会自动应用。这意味着你可以这样组织：

一个 代码 Workspace，使用 Claude + 完整的 Serena LSP + 启用 thinking，用于深度工程工作
一个 审查 Workspace，使用 DeepSeek + 只读工具，用于高性价比的代码审查
一个 运维 Workspace，使用 Remote SSH + Shell 工具，用于服务器管理

每个 Workspace 都保留自己的 profile 配置，因此切换项目也意味着切换 Agent 的行为与能力。

按 Profile 限制工具

Profile 中最有用的特性之一是 MCP server 过滤。在 profile 中只列出特定的 MCP server，就能创建聚焦且安全的 Agent：

# 示例：只读审查 Agent
mcp_servers:
  - builtin_serena  # 代码智能（可设置为 planning 模式）
  - builtin_skills  # 访问审查 skill

这个 profile 无法执行 shell 命令，无法修改 Serena 控制范围之外的文件，也无法访问远程服务器。它仅能阅读、分析与汇报。

Skills 体系

Skill 是 Helix 向 Agent 注入领域知识与工作流的机制。一个 skill 是一个带结构化提示的 Markdown 文件，Agent 在遇到与该 skill 描述匹配的任务时按需加载。

Skill 工作原理

发现 —— 会话启动时，Helix 读取所有可用 skill 的元数据（名称与描述）并将其包含在系统提示中
匹配 —— Agent 看到 skill 列表，决定是否有 skill 与当前任务相关
加载 —— Agent 调用 read_skill(name) 把完整的 skill 内容载入对话
执行 —— skill 的指令引导 Agent 按特定的工作流或约定执行

这种两阶段方式让系统提示保持紧凑。Agent 不需要预先加载所有可能的指令，而是按需取用。

Skill 文件格式

每个 skill 是一个目录，包含一个 SKILL.md 文件。该文件用 YAML frontmatter 存放元数据，用 Markdown 写实际指令：

---
name: commit
description: Smart commit assistant that checks incremental code changes,
  filters large files and binary artifacts, and safely executes git commit.
version: "1.0"
author: your-name
tags: [git, commit, safety]
---

# Smart Commit Assistant

You are a smart Git commit assistant that helps users safely commit code changes.
Before executing `git add`, you check whether new files contain large files
or binary artifacts, and stop immediately if problems are found.

## Workflow

### Step 1: Check current Git status

(detailed instructions follow...)

内置 Skill

Helix 自带三个内置 skill：

Skill	用途
commit	智能提交助手——在提交前检查大文件与二进制产物，并生成清晰的提交信息
serena	Serena LSP 编码助手——提供使用符号级代码分析与编辑工具的详细指引
code-reviewer	代码审查助手——分析本地仓库或远程 MR 的代码质量、安全问题与最佳实践

创建你自己的 Skill

自定义 skill 放在 ~/.aiagent/skills/。创建一个目录并放入 SKILL.md：

~/.aiagent/skills/
  my-deploy-skill/
    SKILL.md          # 必需：skill 定义
    checklist.md      # 可选：附属资源
    config-template/  # 可选：模板文件

Agent 可以通过 read_skill_file(skill, file) 访问附属文件，并用 list_skill_files(skill) 列出可用文件。

实用的 skill 想法：

部署工作流 —— 针对你基础设施的逐步部署指引
API 约定 —— 团队的 API 设计规范与模式
测试策略 —— 项目特定的测试方法与覆盖率要求
PR 审查清单 —— 针对你代码库的自定义审查标准
故障响应 —— 处理常见生产问题的 runbook 式指引

信息

如果自定义 skill 与内置 skill 同名，自定义版本优先生效。这让你可以在需要时覆盖内置行为。

把所有要素组合起来

Helix 的扩展点彼此协同。一个典型的进阶配置可能是这样的：

Agent Profile 定义一个启用 thinking 的 Claude 模型与一组精心挑选的 MCP server
Workspace 把 profile 与具体项目目录绑定
Skills 注入团队在提交、审查与部署上的约定
自定义 MCP server 提供数据库访问与工单系统集成
Git Worktree 隔离代码改动，让 Agent 可以无风险地自由工作

Agent 启动一个任务、加载相关 skill、使用可用工具、为代码改动创建 worktree、执行审查并合并结果——一切都在你只配置一次、跨会话复用的结构化工作流中完成。

接下来

开发工具 —— Helix 70+ 个内置工具的完整参考
创建 Skill —— 自定义 skill 的详细构建指南
多 Agent 架构 —— Manager、Execution 与 Sub Agent 如何协调
API 与配置 —— 后端配置与设置参考

Git Worktree 工作流​

工作原理​

这为什么重要​

示例流程​

Agent Profiles​

Profile 配置​

Profile 与 Workspace 的关联​

按 Profile 限制工具​

Skills 体系​

Skill 工作原理​

Skill 文件格式​

内置 Skill​

创建你自己的 Skill​

把所有要素组合起来​

接下来​