🔥 赫菲斯托斯：一种半结构化的智能体框架

---

🎥 观看赫菲斯托斯的实际运行

---

新功能：Hephaestus Dev

准备好将赫菲斯托斯用作开发工具了吗？ 我们打造了 Hephaestus Dev——一个预配置的环境，内含5个可用于软件开发的生产级工作流：

工作流	功能描述
从PRD到软件构建	根据产品需求文档构建完整的软件
Bug修复	系统性地分析、修复并验证Bug
索引代码库	扫描并索引代码库，构建内存中的知识库
功能开发	按照既定模式为现有代码库添加新功能
文档生成	为现有代码库生成全面的文档

python run_hephaestus_dev.py --path /path/to/project

立即开始使用 Hephaestus Dev →

---

我一直遇到的问题

我试图构建一个系统，让AI智能体能够处理复杂的软件项目。比如：“帮我构建一个包含OAuth、JWT、限流机制和全面测试的认证系统。”

传统的智能体框架可以进行分支和循环，但有一个局限性：每个分支都需要预先定义好的指令。 你必须提前为每一个可能的情景写好任务描述。

可是，那些未曾预料到的新发现又该怎么办呢？当测试智能体发现优化机会、安全问题，或者更好的架构模式时？

于是，我尝试了一种新的方法：定义解决问题所需的逻辑阶段类型——例如“规划→实现→测试”——并让智能体根据自己的发现，在任何阶段创建任务。

实际发生的情况：一棵自我生长的分支树

我没有采用僵化的顺序，而是设置了以下阶段类型：

• 阶段1（分析）：理解、规划、调查
• 阶段2（实现）：构建、修复、优化
• 阶段3（验证）：测试、验证、质量检查

关键的洞察是：智能体可以在任意阶段创建任务。

例如，一个正在测试你的认证系统的验证智能体，可能会发现一种优雅的缓存模式。它不会被卡住（也不会受限于你事先编写的分支逻辑），而是：

1. 创建一个阶段1的调查任务：“分析认证缓存模式——可能适用于其他12条API路由，使性能提升40%”
2. 继续执行其验证任务
3. 另一个智能体接收到这个调查任务并展开探索

就这样，工作流自动进行了分支。这并不是因为你预测到了“如果发现优化点，就创建调查任务”，而是因为智能体发现了值得探索的内容，并且有自由去为此创建新的任务。

这种方式形成了一棵基于实际发现而非预设场景而不断生长的任务分支树。

让我通过一个例子来展示它的实际运作：

示例：从PRD构建应用

我给赫菲斯托斯提供了一份产品需求文档：“构建一个带有认证、REST API和React前端的Web应用。”

阶段1的智能体读取了PRD，识别出5个主要组件：

1. 认证系统
2. REST API层
3. React前端
4. 数据库模式
5. 后台任务处理器

它随即创建了5个阶段2的任务——每个组件对应一个任务。现在，我有5个智能体在并行工作，各自专注于一个部分。

其中一个阶段2的智能体完成了REST API的构建，并创建了一个阶段3的验证任务：“测试REST API端点。”

阶段3的智能体开始测试。一切顺利通过。然而，它注意到一件事：

“认证端点使用了一种缓存模式，能将数据库查询次数减少60%。这有可能显著提升所有API路由的性能。”

有趣的地方就在这里。

阶段3的智能体并没有仅仅记录下这一观察结果就继续前进，也没有因为工作流计划中没有“调查优化方案”而陷入僵局。

相反，它创建了一个新的阶段1的调查任务：“分析认证缓存模式——可能适用于其他API路由，带来巨大的性能提升。”

一个新的阶段1智能体诞生，对缓存模式进行了深入研究，确认其可行性后，又创建了一个阶段2的实施任务：“将缓存模式应用到所有API路由上。”

另一个智能体负责实施，随后再由另一个智能体进行验证。

工作流就这样自动分支了。 这一优化方案并非事先规划好的，而是由智能体在测试过程中发现，并主动创建了新的任务来进一步探索。

与此同时，另一个阶段3的智能体正在测试认证组件。测试却失败了。于是，它创建了一个阶段2的Bug修复任务：“修复认证令牌过期验证——当前实现允许过期的令牌通过。”

修复智能体完成了修改，并创建了阶段3的复测任务：“验证认证修复是否成功。”

刚才发生了什么？

让我们看看最终生成的结果：

graph TB
    P1[阶段1：分析PRD<br/>创建5个任务] --> P2A[阶段2：构建认证]
    P1 --> P2B[阶段2：构建API]
    P1 --> P2C[阶段2：构建前端]

    P2B --> P3B[阶段3：测试API]
    P3B -->|发现优化| P1New[阶段1：调研缓存<br/>新分支]
    P3B -->|测试继续| P3Done[API验证通过]

    P1New --> P2New[阶段2：实现缓存]
    P2New --> P3New[阶段3：验证优化]

    P2A --> P3A[阶段3：测试认证]
    P3A -->|测试失败| P2Fix[阶段2：修复认证缺陷]
    P2Fix --> P3Retest[阶段3：重新测试认证]

    style P3B fill:#fff3e0
    style P1New fill:#e1f5fe
    style P2Fix fill:#ffebee

这个工作流是自动生成的：

• 从1个分析任务开始
• 分支出5个并行的实现任务
• 其中一个测试阶段发现了优化需求，于是衍生出一个包含3个阶段的调研分支
• 另一个测试阶段发现了缺陷，触发了修复和重新测试的循环
• 所有这些步骤都通过看板任务卡进行协调，并设置了阻塞关系。

为什么这将改变一切

传统工作流： 需要提前预测所有场景，制定严格的计划，但一旦实际情况与预期不符，计划就会失效。

赫菲斯托斯方法： 定义工作类型，由智能体自主发现，工作流能够实时自适应。

工作流会根据智能体实际发现的内容实时调整，而不是基于我们事先的预测。

半结构化的最佳平衡点

以下是为什么这种方法被称为“半结构化”以及它的重要性：

完全结构化的工作流（传统框架）：

• ❌ 需要为每种情况都预先定义好提示
• ❌ 虽然可以分支或循环，但每条路径都需要固定的指令
• ❌ 必须在一开始就预见所有可能的发现

完全非结构化的智能体（混乱状态）：

• ❌ 缺乏协调
• ❌ 工作重复
• ❌ 变更相互矛盾
• ❌ 没有明确的成功标准

半结构化（赫菲斯托斯）：

• ✅ 阶段定义提供了工作类型和指导方针的结构
• ✅ 智能体根据发现动态编写任务描述
• ✅ 看板任务卡通过阻塞关系协调工作
• ✅ 守护者监控确保智能体始终符合阶段目标
• ✅ 工作流会根据智能体的实际发现进行调整，而非你预想的内容

这样既能在关键环节提供结构：

• 阶段类型定义了正在进行的工作类型
• 完成标准设定了清晰的完成条件
• 守护者会验证是否符合阶段要求
• 任务卡追踪依赖关系，防止混乱

又能在需要灵活的地方保持灵活性：

• 智能体可以即时创建详细的任务描述
• 无需预先定义所有可能的分支
• 发现会实时推动工作流扩展
• 新的工作类型会在智能体探索过程中自然产生

🚀 快速入门

前置条件

• Python 3.10及以上
• tmux - 用于隔离智能体的终端多路复用器
• Git - 你的项目必须是一个Git仓库
• Docker - 用于运行Qdrant向量数据库
• Node.js 和 npm - 用于前端UI
• Claude Code、OpenCode、Droid 或 Codex - 智能体运行的CLI AI工具
• API密钥：OpenAI、OpenRouter、Anthropic（也支持：Azure OpenAI、Google AI Studio - 详见 LLM配置）

验证你的环境（macOS）

在开始之前，请先验证所有工具和配置是否正确安装：

python check_setup_macos.py

该脚本会检查：

• ✅ 所有必需的CLI工具（tmux、git、docker、node、npm、Claude Code）
• ✅ .env 文件中的API密钥
• ✅ MCP服务器是否已配置
• ✅ 配置文件和工作目录
• ✅ 是否正在运行的服务（Docker、Qdrant）
• ✅ Python和前端依赖项

脚本会以彩色报告的形式显示哪些部分已经设置好，哪些还需要注意。

10分钟内上手

构建你的第一个自适应工作流：

👉 快速入门指南

该指南将引导你完成以下步骤：

• 设置API密钥和LLM配置
• 配置MCP服务器（赫菲斯托斯 + Qdrant）
• 设置工作目录
• 定义阶段并实现动态任务生成
• 运行一个能够实时自适应的工作流
• 观察智能体如何协调工作，并自动发现新的任务

---

想了解更多？ 请查看完整文档，内容包括：

• 完整的架构和技术细节
• API参考和SDK指南
• 示例工作流和模板
• 最佳实践和高级功能

---

🤝 获取帮助

• 📖 文档 - 完整指南、API参考和教程
• 💬 GitHub讨论区 - 提问和分享想法
• 🐛 问题跟踪器 - 报告Bug和请求功能
• 📧 电子邮件 - 如需支持或合作，请随时联系我们

---

Hephaestus 快速上手指南

Hephaestus 是一个半结构化智能体框架。与传统框架需要预定义所有分支指令不同，Hephaestus 允许 AI 智能体在发现新问题时，动态创建新的任务阶段（如分析、实现、验证），从而让工作流像树木一样自然生长和适应。

环境准备

在开始之前，请确保您的系统满足以下要求：

系统要求

• 操作系统: 推荐 macOS 或 Linux (Windows 需通过 WSL2)
• Python: 3.10 或更高版本
• Git: 项目必须初始化为 git 仓库

前置依赖

您需要安装以下工具和服务：

• tmux: 用于隔离智能体会话的终端复用器
• Docker: 用于运行 Qdrant 向量数据库
• Node.js & npm: 用于前端可视化界面
• CLI AI 工具: 需安装以下任一工具作为智能体运行环境：
  • Claude Code
  • OpenCode
  • Droid
  • Codex
• API Keys: 准备至少一个 LLM 服务的密钥 (OpenAI, Anthropic, OpenRouter, Azure OpenAI, 或 Google AI Studio)

提示: 国内用户若无法直接访问 Docker Hub 或 npm，建议配置相应的国内镜像源以加速安装。

安装步骤

1. 克隆项目

git clone https://github.com/Ido-Levi/Hephaestus.git
cd Hephaestus

2. 安装 Python 依赖

pip install -r requirements.txt

3. 启动向量数据库 (Docker)

Hephaestus 使用 Qdrant 存储记忆和上下文：

docker run -d -p 6333:6333 -p 6334:6334 --name qdrant qdrant/qdrant

4. 配置环境变量

在项目根目录创建 .env 文件，填入您的 API 密钥：

cp .env.example .env
# 编辑 .env 文件，填入 OPENAI_API_KEY 或 ANTHROPIC_API_KEY 等

5. 验证环境 (仅限 macOS)

如果您使用的是 macOS，运行官方提供的检查脚本以确保所有工具链就绪：

python check_setup_macos.py

该脚本将检查 tmux、git、docker、node、API 密钥及 MCP 服务器配置状态，并生成彩色报告。

基本使用

模式一：使用预设工作流 (Hephaestus Dev)

这是最快的方式，内置了 5 个生产级软件开发工作流（如 PRD 转软件、Bug 修复、文档生成等）。

假设您有一个想要开发或重构的项目目录，运行以下命令：

python run_hephaestus_dev.py --path /path/to/your/project

它将自动执行：

1. 扫描代码库建立索引。
2. 根据您的需求（如修复 Bug 或新增功能）动态规划任务。
3. 启动多个智能体并行工作（分析、编码、测试），并在发现问题时自动创建新的分支任务。

模式二：自定义工作流

如果您想从零开始定义自己的阶段逻辑：

1. 定义阶段: 在配置文件中定义逻辑阶段类型（例如：Phase 1: 分析，Phase 2: 实现，Phase 3: 验证）。
2. 启动框架: 运行主程序并指向您的工作目录。
3. 观察演化: 智能体会读取初始指令，并在执行过程中根据发现自动创建新的 Kanban 任务票证（Tickets）。

示例场景： 当您让智能体“构建一个带认证的系统”时，测试阶段的智能体若发现某个缓存模式能提升性能，它会自动创建一个全新的“分析任务”来研究该模式，随后触发“实现任务”应用该优化，无需您预先编写此分支逻辑。

监控与交互

启动后，您可以通过以下方式实时监控：

• 终端: 观察 tmux 中各个智能体的独立会话输出。
• Web UI: 访问本地前端界面（通常由 Node.js 启动），查看实时生成的 Kanban 看板和任务依赖图。

---

更多高级配置、API 参考及详细架构说明，请访问 官方文档。