Hexis:用Git理念管理AI Agent技能与上下文,实现工程化协作
如果你正在尝试让 AI Agent 完成一个稍微复杂的任务,比如分析代码库、生成报告或者自动化部署,你很可能已经遇到了这三个核心痛点:
- 技能(Skills)难以复用:每次新开一个对话,Agent 都像一张白纸,你需要重新“教”它怎么调用 API、怎么处理特定格式的数据。那些精心调试好的工具链,无法像代码库一样被版本化管理和团队共享。
- 上下文(Context)管理混乱:为了让 Agent 理解当前任务,你需要把项目文档、API 说明、历史对话记录一股脑塞进提示词。这不仅消耗宝贵的 Token,还经常因为信息过载或丢失关键背景,导致 Agent 输出偏离预期。
- 协作与审计如同“黑盒”:Agent 执行任务的过程和决策依据散落在各个对话中,没有清晰的变更记录。当任务出错或需要复盘时,你很难像
git log一样追溯“到底哪一步的指令或数据导致了问题”。
这三个问题,本质上是因为当前大多数 AI Agent 的工作流缺乏软件工程中最核心的基石:版本控制、模块化和可观测性。我们习惯于用 Git 管理代码,用 CI/CD 管理流程,但到了 AI 驱动的自动化领域,却又回到了手工拼接提示词和一次性对话的原始阶段。
今天要介绍的开源项目 Hexis,正是瞄准了这一空白。它的核心主张非常清晰:用 Git 的理念和工具链,来管理 AI Agent 的 Skills(技能)、Tools(工具)和 Context(上下文)。这不是一个全新的 Agent 框架,而是一个“赋能层”,旨在将软件工程的最佳实践引入 AI Agent 的开发与运维流程。
简单来说,Hexis 想让你的 AI Agent 工作流变得像管理代码库一样清晰、可协作、可追溯。接下来,我们将深入拆解 Hexis 是什么、如何工作,并通过一个完整的实战示例,展示如何用它来构建一个可版本化、可共享的自动化数据分析 Agent。
1. Hexis 要解决的根本问题:从“对话”到“工程”
在深入技术细节前,我们首先要理解 Hexis 诞生的背景。当前 AI Agent 的开发,尤其是基于大语言模型(LLM)的 Agent,存在几个典型的工程化困境:
- 技能孤岛:你为客服 Agent 编写的“查询订单状态”技能,无法直接被数据分析 Agent 复用,尽管它们底层都调用同一个订单 API。技能缺乏标准的封装、描述和存储方式。
- 上下文脆弱:任务的背景信息(如项目目标、数据模式、约束条件)要么冗余地写在提示词里,要么在长对话中逐渐被遗忘或扭曲。没有一种可靠的方式将任务上下文持久化并与特定工作流关联。
- 缺乏生命周期管理:一个技能的迭代(比如优化了 API 调用参数)无法像代码一样通过 Pull Request 进行评审、测试和合并。技能的启用、禁用、回滚没有可靠机制。
Hexis 的解决方案是引入三个核心概念,并与 Git 仓库的结构一一对应:
- Skills:类比于函数或类。一个 Skill 是完成特定任务的能力单元,例如“读取数据库”、“调用天气 API”、“生成图表”。在 Hexis 中,一个 Skill 对应 Git 仓库里的一个目录,包含其实现代码(如 Python 脚本)、描述文件(如
skill.yaml)和测试用例。 - Tools:类比于库或依赖。Tools 是 Skill 执行时所需的具体工具或 API 封装。Hexis 鼓励将 Tools 也版本化管理,确保 Skill 运行环境的一致性。
- Context:类比于配置文件或环境变量。Context 提供了 Skill 运行所需的背景信息、配置参数和会话记忆。它被结构化地存储在仓库中,可以被不同的 Skill 或工作流引用。
通过将这三者置于 Git 管理之下,Hexis 带来了以下根本性改变:
- 版本化:每个 Skill 的修改都有提交历史,可以轻松回滚到稳定版本。
- 可协作:团队成员可以通过 Fork、Branch、Pull Request 的方式来共同开发和完善 Agent 技能集。
- 可复用:通过 Git 子模块或包管理,可以跨项目引用共享的技能库。
- 可审计:Agent 的每一次任务执行,都可以关联到特定版本的 Skill 和 Context,实现完整的溯源。
2. 核心概念与架构拆解
2.1 核心组件映射
让我们将 Hexis 的概念映射到具体的 Git 仓库结构和运行时组件:
| Hexis 概念 | Git 仓库中的体现 | 运行时角色 | 示例 |
|---|---|---|---|
| Skill | 一个独立的目录,包含 skill.yaml 和实现文件。 |
执行单元。被 Agent 调用来完成具体操作。 | skills/fetch_github_issues/ |
| Tool | 可能是一个独立的库项目,或被封装在 Skill 目录下的 tools/ 子目录中。 |
提供底层能力,如 HTTP 客户端、数据库驱动。 | tools/sqlite_client.py |
| Context | 仓库根目录或特定工作流目录下的 YAML/JSON 文件(如 context.yaml)。 |
提供运行时的配置、知识和会话状态。 | contexts/project_alpha.yaml |
| Agent | 不直接存储。是一个运行时实体,通过加载特定仓库(或分支)的 Skills 和 Context 来构建。 | 协调者。根据目标,选择并组合 Skills 来解决问题。 | 一个配置了“数据分析”技能集的 Python 脚本。 |
2.2 工作流程
一个典型的 Hexis 工作流如下:
- 开发阶段:
- 在 Git 仓库中创建或修改 Skill(编写代码、定义描述)。
- 定义或更新 Context 文件,描述任务领域、约束和偏好。
- 提交更改,并通过 Git 进行版本控制。
- 部署阶段:
- Agent 运行时(如一个 Python 程序)会克隆或拉取指定的 Hexis 仓库(或某个标签/提交)。
- 运行时解析仓库结构,加载所有有效的 Skills 和指定的 Context。
- 将 Skills 作为可调用工具暴露给 LLM(例如,符合 OpenAI Function Calling 或 ReAct 格式)。
- 执行阶段:
- LLM 根据用户请求和当前的 Context,决定调用哪个 Skill。
- Hexis 运行时执行对应的 Skill 代码,并可能更新 Context(如记录中间结果)。
- 结果返回给 LLM 以生成最终回复或决定下一步行动。
2.3 与常见 Agent 框架的对比
Hexis 并非要取代 LangChain、LlamaIndex 或 AutoGen 等现有框架。相反,它更像是这些框架的“供应链”或“资产管理系统”。
- LangChain:提供了构建链(Chain)和代理(Agent)的丰富组件。Hexis 可以管理这些组件的“配方”(即 Skills),确保使用的工具链是经过验证和版本化的。
- LlamaIndex:擅长数据索引和检索。Hexis 可以版本化管理不同的索引结构(作为 Context 的一部分)以及与之交互的查询 Skills。
- AutoGen:专注于多智能体协作。Hexis 可以为每个智能体定义专属的 Skill 集和 Context,并通过 Git 来同步和协调多智能体间的知识与能力。
简单理解:Hexis 管“做什么”和“用什么做”(Skills/Tools/Context),而传统框架管“怎么做”(执行逻辑、推理流程)。
3. 环境准备与安装
在开始实战前,你需要准备好基础环境。Hexis 目前主要面向 Python 生态。
3.1 系统与 Python 环境
- 操作系统:Linux, macOS, 或 Windows (WSL2 推荐)。
- Python 版本:>= 3.8。
- Git:确保已安装并能正常使用。
3.2 安装 Hexis
Hexis 可以通过 pip 从 PyPI 安装。建议使用虚拟环境。
3.3 准备 LLM 访问权限
Hexis 本身不提供 LLM,你需要配置一个后端的 API 密钥。本文以 OpenAI 为例,但你也可以配置支持 OpenAI 兼容接口的其他模型(如 DeepSeek、Ollama 本地模型)。
4. 实战:构建一个版本化的 GitHub 数据分析 Agent
我们将构建一个 Agent,其 Skill 是“获取指定仓库的最近 Issues”,并通过 Hexis 进行管理。
4.1 初始化 Hexis 技能仓库
首先,我们创建一个 Git 仓库来存放我们的技能。
4.2 创建第一个 Skill:fetch_github_issues
一个 Hexis Skill 的核心是一个 skill.yaml 描述文件和一个实现文件(如 .py 文件)。
1. 创建 Skill 描述文件 (skill.yaml):
这个文件定义了 Skill 的元数据、输入输出参数,以及如何被 LLM 理解。
2. 创建 Skill 实现文件 (fetch.py):
这个文件包含实际的执行逻辑。
3. 创建 Skill 的依赖文件 (requirements.txt):
虽然不是必须,但显式声明依赖是好习惯。
4. 将 Skill 添加到 Git 版本控制:
4.3 创建任务上下文 (Context)
Context 用于设定 Agent 的任务背景和约束。我们创建一个针对“开源项目健康度分析”的上下文。
同样,提交这个 Context 文件。
4.4 编写 Agent 主程序
现在,我们编写一个 Python 脚本,作为 Agent 的运行时。它将加载 Hexis 仓库中的 Skills 和 Context,并与 LLM 协同工作。
4.5 运行与验证
在运行前,确保你在项目根目录,并且 OPENAI_API_KEY 环境变量已设置。
预期输出示例:
5. 进阶:Skill 的迭代与团队协作
Hexis 的真正威力体现在协作和迭代上。假设我们发现 fetch_github_issues 技能缺少对“过滤特定标签”的支持。
1. 创建功能分支:
2. 修改 Skill 定义和实现:
更新 skill.yaml,增加新的输入参数:
更新 fetch.py 的执行逻辑:
3. 提交更改并创建 Pull Request:
然后,在 GitHub/GitLab 上创建 Pull Request (PR)。团队成员可以在 PR 中评审代码变更、测试 Skill 功能,讨论这个修改是否会影响其他依赖此 Skill 的 Agent。通过合并 PR 到主分支,就完成了一次安全的 Skill 升级。
4. Agent 使用新版本: Agent 运行时只需拉取最新的主分支代码,即可自动获得增强后的 Skill,无需修改 Agent 主程序代码。
6. 常见问题与排查思路
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
SkillLoader 加载不到 Skill |
1. skill.yaml 文件格式错误。2. Skill 目录结构不符合规范。 3. 仓库路径 ( repo_path) 设置错误。 |
1. 使用 yamllint 或在线校验器检查 skill.yaml。2. 确认目录为 skills/<skill_name>/skill.yaml。3. 打印 repo_path 的绝对路径,确认是否正确。 |
1. 修正 YAML 语法。 2. 遵循标准目录结构。 3. 使用 os.path.abspath 确保路径正确。 |
| LLM 不调用 Skill | 1. Skill 的 description 不够清晰,LLM 不理解其用途。2. 用户查询与 Skill 的输入参数不匹配。 3. 系统提示词 ( system_message) 未引导 LLM 使用工具。 |
1. 检查 skill.yaml 中的 description 和每个 input 的 description,确保它们准确、易懂。2. 在系统提示词中明确说明“你可以使用以下工具”。 |
1. 用自然语言重写描述,明确适用场景。 2. 优化系统提示词,设定明确的 Agent 角色和目标。 3. 在开发阶段,可以暂时设置 tool_choice={"type": "function", "function": {"name": "your_skill_name"}} 进行强制测试。 |
| Skill 执行时报错 (如 API 错误) | 1. Skill 代码逻辑错误。 2. 网络或依赖问题。 3. 缺少环境变量(如 API Key)。 |
1. 在 Skill 代码中添加详细的日志和异常捕获。 2. 单独运行 Skill 的 execute 函数进行测试。3. 检查环境变量是否在 Agent 运行时环境中正确设置。 |
1. 在 Skill 实现中加强错误处理,返回结构化的错误信息。 2. 为 Skill 编写单元测试。 3. 使用 .env 文件管理环境变量,并在运行前加载。 |
| Context 似乎没起作用 | 1. Context 文件未被正确加载。 2. 系统提示词中未注入或未正确格式化 Context 内容。 |
1. 检查 ContextManager.load_context 的返回值是否为 None。2. 打印加载后的 context.to_dict() 查看内容。 |
1. 确保 contexts/ 目录下的 YAML 文件名与加载时指定的名称一致。2. 在构建系统提示词时,将 Context 内容以清晰的方式(如 JSON、Markdown)嵌入。 |
7. 最佳实践与工程建议
-
Skill 设计原则:
- 单一职责:一个 Skill 只做一件事,并做好。避免创建“瑞士军刀”式的巨型 Skill。
- 明确接口:输入输出参数定义清晰,类型准确。良好的描述 (
description) 是 LLM 能否正确使用的关键。 - 幂等与安全:尽可能让 Skill 的执行是幂等的(多次调用结果相同)。对于有副作用的操作(如写入数据库、发送邮件),要在 Skill 描述中明确警告,并在 Context 中设定约束。
-
Context 管理策略:
- 分层 Context:可以创建全局 Context(公司规范)、项目级 Context(项目目标)、任务级 Context(具体任务参数)。Agent 运行时可以合并或按优先级加载。
- 动态 Context:考虑让 Skill 能够更新 Context(例如,记录对话历史或中间结论)。Hexis 的
ContextManager应提供更新和持久化 Context 的方法。 - 敏感信息隔离:切勿将 API 密钥、密码等硬编码在 Context 或 Skill 中。使用环境变量或安全的配置管理服务。
-
版本控制与协作:
- 语义化版本:对 Skill 使用语义化版本控制(如
major.minor.patch),并在skill.yaml中体现。破坏性更新升级主版本号。 - 分支策略:为 Skill 开发使用功能分支 (
feat/)、修复分支 (fix/)。通过 PR 和代码评审来保证质量。 - 技能仓库目录:可以建立组织的“官方技能仓库”,作为子模块引入各个项目。鼓励团队共享和贡献通用技能。
- 语义化版本:对 Skill 使用语义化版本控制(如
-
测试与监控:
- 单元测试:为每个 Skill 编写单元测试,模拟各种输入和边界情况。
- 集成测试:创建测试 Agent,模拟真实工作流,测试多个 Skill 的协同。
- 执行日志:在 Agent 运行时和 Skill 执行处添加结构化日志,记录 Skill 调用、参数、结果和耗时,便于调试和性能分析。
-
生产环境部署:
- 依赖锁定:为整个技能仓库或每个 Skill 提供
requirements.txt或Pipfile.lock,确保部署环境的一致性。 - 健康检查:部署后,应有定期任务验证所有 Skill 的基础依赖(如网络连通性、API 配额)是否正常。
- 回滚机制:利用 Git 的标签 (
git tag) 标记稳定版本。当新 Skill 版本出现问题,能快速将仓库回滚到上一个稳定标签。
- 依赖锁定:为整个技能仓库或每个 Skill 提供
Hexis 代表了一种重要的范式转变:将 AI Agent 从临时的、脆弱的提示词工程,转向可维护、可协作的软件工程实践。它目前可能还是一个早期项目,但其理念——用 Git 管理 AI 能力——直击了 Agent 规模化应用的核心痛点。
对于开发者而言,现在开始用 Hexis 的思路来组织你的 Agent 技能,即使不使用其全部功能,也能极大改善项目的可维护性。你可以从将一个常用的、稳定的 API 调用封装成一个版本化的 Skill 开始,体验这种“代码化”管理带来的清晰和安心感。随着技能库的积累,你会发现构建复杂、可靠的 Agent 系统,不再是一个从零开始的魔术,而是一个可以有序推进的工程项目。