仓库: huginn/huginn
语言: Ruby (Rails)
License: MIT
定位: 自托管的 IFTTT/Zapier 替代品,通过 Agent 有向图实现事件驱动的自动化任务
一、项目定位与核心理念
Huginn 是一个构建在 Ruby on Rails 之上的自动化代理系统,其核心理念可以用一句话概括:Agent 创建和消费 Event,沿有向图传播。与 IFTTT/Zapier 等 SaaS 平台不同,Huginn 强调自托管(self-hosted),用户始终拥有自己的数据。
项目名源自北欧神话中奥丁的两只渡鸦——Huginn(思想)和 Muninn(记忆),象征着”替你思考和记忆的代理”。系统的设计哲学是 “hackable”:用户可以在自己的服务器上运行、修改和扩展每一个组件。
从架构视角看,Huginn 本质上是一个 事件流处理引擎 + Agent 生命周期管理框架。它不依赖 LLM,而是基于确定性的规则和调度机制工作,这使其在可靠性方面优于许多现代 AI Agent 框架。
二、核心数据模型
Huginn 的数据模型围绕 6 个核心实体构建,形成一个清晰的有向图结构:
2.1 Agent(代理)
Agent 是整个系统的核心基类,继承自 ActiveRecord::Base,是一个典型的 单表继承(STI) 模型。所有具体的 Agent 类型(如 WebsiteAgent、WebhookAgent)都通过 type 字段存储在同一个 agents 表中。
class Agent < ActiveRecord::Base
include AssignableTypes
include LiquidInterpolatable
include DryRunnable
include SortableEvents
# ...
end
Agent 的关键属性包括:
- options:JSON 序列化的配置参数,每个 Agent 子类定义自己的
default_options - memory:JSON 序列化的持久化记忆,Agent 可在多次运行间保持状态
- schedule:调度策略,支持从
every_1m到every_7d以及定点时间(如midnight、8am) - keep_events_for:事件保留时长策略
Agent 通过 Mixin 模式集成了大量能力,包括 LiquidInterpolatable(Liquid 模板引擎)、DryRunnable(干运行模式)、WorkingHelpers(健康检查辅助)等。
2.2 Event(事件)
Event 是 Agent 之间通信的载体,包含一个 JSON 格式的 payload,以及可选的地理位置信息(lat、lng)和过期时间。
class Event < ActiveRecord::Base
json_serialize :payload
acts_as_mappable
belongs_to :agent, counter_cache: true
after_create :possibly_propagate
end
关键设计:Event 创建后会触发 possibly_propagate 回调,检查是否有下游 Agent 设置了 propagate_immediately,如果有则立即触发事件传播。这是一种 推拉结合 的传播机制。
2.3 Link(连接)
Link 是连接两个 Agent 的有向边,定义了事件的流动方向:
class Link < ActiveRecord::Base
belongs_to :source, class_name: "Agent"
belongs_to :receiver, class_name: "Agent"
end
源 Agent 产生的 Event 会通过 Link 传递给接收方 Agent。这是一种经典的 发布-订阅 模式。
2.4 ControlLink(控制连接)
除了数据流的 Link,Huginn 还有 ControlLink,允许一个 Agent 控制另一个 Agent 的启用/禁用状态。这实现了 Agent 之间的 控制流 分离。
2.5 Scenario(场景)
Scenario 是 Agent 的逻辑分组,类似于文件夹或工作流容器:
class Scenario < ActiveRecord::Base
has_many :agents, through: :scenario_memberships
end
用户可以将相关的 Agent 归入同一个 Scenario,便于管理和可视化。Scenario 还支持导入导出,方便分享 Agent 组合。
2.6 其他辅助模型
- AgentLog:Agent 运行日志,记录每次执行的详细信息
- Service:第三方服务认证(如 Twitter OAuth)
- UserCredential:用户凭证管理,Agent 通过
credential(name)方法安全访问 - User:多用户支持,每个用户拥有独立的 Agent 和 Event 空间
三、Agent 生命周期与执行模型
3.1 调度机制
Huginn 使用 bin/schedule.rb 作为调度入口,按照预定义的调度频率(SCHEDULES 数组)定期触发 Agent 的 check 方法:
SCHEDULES = %w[
every_1m every_2m every_5m every_10m every_30m
every_1h every_2h every_5h every_12h
every_1d every_2d every_7d
midnight 1am 2am ... 11pm
never
]
调度流程:
Agent.run_schedule(schedule)被调用- 按 Agent 类型分组,调用各子类的
bulk_check(schedule) bulk_check为每个活跃 Agent 创建AgentCheckJob(异步队列任务)- Job 中执行 Agent 的
check方法
3.2 事件传播机制
事件传播是 Huginn 的核心流程,通过 Agent.receive! 实现:
def self.receive!(options = {})
# 通过 SQL JOIN 查询找到所有需要处理的 (receiver, event) 对
agents_to_events = Hash.new { |h, k| h[k] = [] }
all.joins("JOIN links ON ...")
.joins("JOIN events ON ...")
.where("NOT agents.disabled AND NOT agents.deactivated ...")
.pluck("agents.id", "sources.type", "agents.type", "events.id")
.each do |receiver_agent_id, source_agent_type, receiver_agent_type, event_id|
agents_to_events[receiver_agent_id] << event_id
end
# 为每个 Agent 创建异步接收 Job
Agent.where(id: agents_to_events.keys).each do |agent|
event_ids = agents_to_events[agent.id].uniq
if agent.no_bulk_receive?
event_ids.each { |event_id| Agent.async_receive(agent.id, [event_id]) }
else
Agent.async_receive(agent.id, event_ids)
end
end
end
这个设计有几个值得注意的点:
- 批量处理:默认情况下 Event 是批量传递给 Agent 的,但 Agent 可以声明
no_bulk_receive!来逐个处理 - 乐观并发控制:通过
last_checked_event_id跟踪已处理的事件,避免重复处理 - 执行锁:使用
with_advisory_lock确保同一 Agent 不会并发执行
3.3 Agent 能力声明
Agent 子类通过类方法声明自身的能力:
cannot_be_scheduled! # 不可调度,只能被动接收事件
cannot_receive_events! # 不可接收事件,只能主动检查
cannot_create_events! # 不可创建事件
can_control_other_agents! # 可以控制其他 Agent
can_dry_run! # 支持干运行
no_bulk_receive! # 不批量接收,逐个处理
这种声明式设计使得框架可以在调度和传播时进行优化,同时也让 Agent 的行为对用户透明。
四、Agent 插件体系
4.1 内置 Agent 类型
Huginn 内置了大量 Agent,覆盖常见的自动化场景:
| Agent | 功能 |
|---|
|——-|——|
WebsiteAgent |
网页抓取,支持 HTML/XML/JSON/Text |
|---|---|
WebhookAgent |
接收 WebHook |
EmailAgent |
发送邮件 |
TriggerAgent |
条件触发 |
DeDuplicationAgent |
去重 |
EventFormattingAgent |
事件格式转换 |
JavaScriptAgent |
自定义 JS 函数 |
HumanTaskAgent |
Amazon Mechanical Turk 集成 |
WeatherAgent |
天气查询 |
4.2 WebsiteAgent 深度解析
WebsiteAgent 是最复杂的内置 Agent 之一,展示了 Huginn 的插件能力:
class WebsiteAgent < Agent
include WebRequestConcern
can_dry_run!
can_order_created_events!
no_bulk_receive!
default_schedule "every_12h"
end
它支持:
- 多种解析方式:CSS 选择器、XPath、JSONPath、正则表达式
- Liquid 模板:在
template选项中使用 Liquid 语法组合提取结果 - 变化检测:
on_change模式只在内容变化时创建事件 - 合并模式:
merge模式保留旧 payload 并更新新值 - 编码处理:自动检测或强制指定字符编码
4.3 WebhookAgent 设计模式
WebhookAgent 展示了 Agent 如何处理外部 HTTP 请求:
class WebhookAgent < Agent
cannot_be_scheduled!
cannot_receive_events!
def receive_web_request(request)
# 验证 secret
# 验证 HTTP 方法
# 可选 reCAPTCHA 验证
# 创建事件
# 返回响应
end
end
Agent 通过 receive_web_request 方法处理 HTTP 请求,框架负责路由和锁管理。
4.4 外部 Agent Gem
Huginn 支持通过 ADDITIONAL_GEMS 环境变量加载外部 Agent gem,使用 huginn_agent gem 作为开发模板。这种设计使得社区可以独立于主仓库开发和发布新 Agent。
五、模板引擎:Liquid
Huginn 深度集成了 Liquid 模板引擎,几乎所有支持动态配置的地方都使用 Liquid 语法:
include LiquidInterpolatable
Agent 可以在 options 中使用 {{ variable }} 语法引用:
- 上游 Event 的 payload 字段
- Agent 自身的属性
- Liquid 过滤器和标签
这种设计使得非程序员也能通过 Web UI 配置复杂的数据流,而无需编写代码。
六、并发与可靠性
6.1 执行锁
Huginn 使用数据库级别的 advisory lock 防止 Agent 并发执行:
EXECUTION_LOCK_PREFIX = "huginn:agent:execution:".freeze
PROPAGATION_LOCK_NAME = "huginn:agent:propagation".freeze
def with_execution_lock
self.class.with_advisory_lock!("#{EXECUTION_LOCK_PREFIX}#{id}") do
reload
yield self
end
end
6.2 异步队列
Agent 的 check 和 receive 操作通过 Active Job 异步执行:
AgentCheckJob:执行 Agent 的check方法AgentReceiveJob:执行 Agent 的receive方法,接收事件列表
这使得 Huginn 可以使用 Sidekiq、Delayed Job 等后端进行水平扩展。
6.3 健康检查
每个 Agent 实现 working? 方法,框架通过 event_created_within? 和 recent_error_logs? 辅助方法判断 Agent 是否正常工作。异常 Agent 会在 UI 中标记为警告。
七、Web 架构与 API
Huginn 是一个标准的 Rails MVC 应用:
- Web UI:Bootstrap 风格的管理界面,支持 Agent 创建、编辑、拖拽连线
- WebHook 端点:每个 Agent 都有独立的 WebHook URL,格式为
/users/:user_id/web_requests/:agent_id/:secret - API:支持通过 API 创建和管理 Agent
Agent 的 WebHook 端点设计很有特色:URL 中包含 secret token 作为认证机制,同时支持 reCAPTCHA 验证。
八、部署架构
Huginn 支持多种部署方式:
- Docker:官方镜像,最简单的方式
- Heroku:一键部署
- OpenShift:模板部署
- 手动安装:支持 MySQL/PostgreSQL
架构组件:
- Rails 应用服务器
- 数据库(MySQL 或 PostgreSQL)
- 后台任务队列(Sidekiq/Delayed Job)
- 调度进程(bin/schedule.rb)
九、与现代 Agent 框架的对比
| 维度 | Huginn | LangChain/AutoGen | n8n |
|---|
|——|——–|——————-|—–|
| LLM 集成 | 无原生支持 | 核心能力 | 可选 |
|---|---|---|---|
| 可靠性 | 高(确定性规则) | 中(LLM 不确定性) | 高 |
| 自托管 | ✅ | ✅ | ✅ |
| 扩展性 | Gem 插件 | Tool/Plugin | 节点插件 |
| 学习曲线 | 中 | 高 | 低 |
| 适用场景 | 监控、抓取、通知 | 对话、推理 | 通用集成 |
Huginn 的优势在于其 确定性和可靠性:没有 LLM 的不确定性,每个 Agent 的行为都是可预测的。这使其特别适合需要 7×24 运行的监控和自动化任务。
十、架构启示与局限性
启示
- 事件驱动 + 有向图:这是自动化系统的经典架构模式,经过验证且高效
- STI + Mixin:Ruby 的单表继承和 Mixin 模式非常适合插件化架构
- 声明式能力:Agent 通过类方法声明自身能力,框架据此优化调度
- Liquid 模板:将编程能力以低代码方式暴露给用户
- 自托管优先:用户数据主权的设计理念
局限性
- 无 LLM 集成:在 AI Agent 时代,缺少 LLM 能力是一个显著短板
- Ruby on Rails 性能:对于高吞吐场景,Ruby 的性能可能成为瓶颈
- 单体架构:虽然是 Rails 应用,但没有微服务拆分,大规模部署可能受限
- 社区活跃度:项目维护频率较低,最新代码更新有限
- UI 现代化:前端技术栈相对陈旧,缺乏实时协作能力
对 OpenMate 的借鉴
- 事件传播机制:
possibly_propagate的推拉结合模式值得借鉴 - Agent 能力声明:声明式设计让框架可以做更多优化
- 执行锁设计:advisory lock 方案在分布式场景下依然有效
- Liquid 模板:低代码配置能力可以降低 Agent 使用门槛
总结
Huginn 是一个设计精良的事件驱动自动化代理平台。它的核心架构——Agent 有向图 + Event 传播 + 调度系统——经过十余年验证,证明了其在监控、抓取、通知等场景下的可靠性。虽然缺少 LLM 集成,但其确定性的执行模型和丰富的内置 Agent 使其在特定场景下仍然是最佳选择。对于构建现代 Agent 系统的开发者来说,Huginn 的架构设计模式和工程实践具有很高的参考价值。