Hypha 智能体框架
用 DomainPack 声明业务,用事件溯源运行时把 LLM 智能体变成可控、可恢复、可审计的生产系统。
- Star 数
- ★ 452
- 最近更新
- 5 天前
- License
- Apache-2.0
- 主语言
- TypeScript
- FA 评分
- 55/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台OpenAI API
- 费用
- 软件免费,模型调用费用自付
- 上手难度
- 高 · 需要较重的基础设施
- 开始前需要
- 典型场景
- 需要把内部业务智能体(如财务对账、法务审查)做成可审计、可重放系统的平台团队
- 不适合
- 希望开箱即用、不搭建 MongoDB 与 Redis 的个人开发者
- 只需要简单脚本调用 LLM、不关心事件溯源与恢复的团队
- 不愿维护策略、审批与缓存一致性等运行时基础设施的小团队
- 官网
- codesoul-co.github.io/Hypha ↗ 来自 GitHub 仓库设置
- 维护状态
- 近 30 天有提交最近提交 2026-11-15最新版本 v1.0.1(2026-08-14)
- 源码审查
- 55/100 · 缺口较多
这个 Agent 能做什么,适合哪些场景?
Hypha 是一个用 TypeScript 编写的开源 Agent 框架,由 Agent Core 与 Production Harness 两层组成。Core 负责 ReAct 推理、规划、工具选择、Memory 访问和模型/上下文编排;Harness 用 FSM 把这些决策变成有边界、事件支撑的执行,包含策略与审批、检查点、恢复、重放和审计。产品差异通过 DomainPack(YAML/JSON/TypeScript)声明,而非写死进运行时,同一个 Core+Harness 可以装配成编码、财务、法律或研究等不同智能体。所有状态来自 Event 与内容寻址 Artifact,缓存是可丢弃的投影,命中缓存不能授权副作用、跳过策略或推进 FSM。项目以 15 个版本对齐的 @codesoul-co/hypha-* npm 包发布,并附带 Express API 服务和示例 CLI,Apache-2.0 许可(品牌资产除外)。
启动后服务端在 config.yaml、configs/tools.yaml 和 configs/memory-profiles.yaml 的配置下组合事件权威与持久执行图,Session 命令、ReAct 续跑、定时器、恢复与对账 worker 在工作就绪前先做一次清扫。DomainPack 由 LocalDomainPackLoader 加载进 DomainPackRegistry,再经 compileDomainPackToHarnessedSystem 编译出 fsmProcess、harnessedSystem、agentPatch、bindings、sessionInitialization、dependencySnapshot 与 processHash;应用组合层必须显式注册 Skill、把 Tool 契约绑定到本地/HTTP/插件/MCP 适配器、批准 MCP 能力版本并持久化依赖快照。运行时按 DomainPack→绑定校验→Harness FSM→有界 ReAct 量子→受治理的 Tool/MCP/Memory/执行活动→Event+回执+Artifact 证据→投影与恢复的路径推进。HTTP 层提供 /api/v1/chat 与 /chat/stream、/runtime/runs/:runId 的 events/replay/audit/regression 投影、/tools、/tool-approvals、/mcp、/memory、/skills、/workflows 以及由 Express 路由生成的 OpenAPI 3.1 文档;CLI 支持 login、chat --stream、tools、skills、workflows。缓存分为 Serving Cache、Thinking Cache、WorkCache、Tool/Execution、Memory/Context 与 Prefix/KV 多层,按 HYPHA_SERVING_CACHE 与 HYPHA_WORKCACHE 选择 memory、sqlite 或 redis 存储。
- 需要把内部业务智能体(如财务对账、法务审查)做成可审计、可重放系统的平台团队
- 要在同一运行时上运行多个垂直领域智能体、只替换 DomainPack 的 SaaS 厂商
- 对工具调用有审批与策略要求、必须留下 Event 与 Artifact 证据的合规敏感团队
- 需要长任务断点续跑、失败恢复和人工复核环节的自动化流程负责人
- 想通过 DomainPack 而非改内核来定制提示词、技能与工作流的应用开发者
- 在本地或私有环境中部署 LLM 智能体、同时希望复用 Redis/SQLite 缓存降低成本的基础设施团队
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 安装 / 启动命令
docker run -d --name hypha-mongodb -p 27017:27017 mongo:8docker run -d --name hypha-redis -p 6379:6379 redis:7-alpine
- 环境变量
HYPHA_OWNER_PASSWORDJWT_SECRETHYPHA_LLM_DEFAULT_MODELOPENAI_API_KEYHYPHA_MEMORY_CONFIG_PATH- 配置文件
.env.example.envconfig.yaml- 运行环境
- Node.js 22+
- 安装说明涉及
- Docker
如何安装或部署这个 Agent?
需要 Node.js 22 及以上、npm、MongoDB 与 Redis,以及至少一个可用的模型提供商或本地模型端点。
git clone https://github.com/CodeSoul-co/Hypha.git
cd Hypha
npm ci
cp .env.example .env可选用容器启动本地 MongoDB 与 Redis:
docker run -d --name hypha-mongodb -p 27017:27017 mongo:8
docker run -d --name hypha-redis -p 6379:6379 redis:7-alpine在 .env 中设置身份与模型提供商,凭据不要写入 config.yaml 或提交到版本库:
[email protected]
HYPHA_OWNER_PASSWORD=replace-with-a-private-password
JWT_SECRET=replace-with-at-least-32-random-characters
HYPHA_LLM_DEFAULT_PROVIDER=openai
HYPHA_LLM_DEFAULT_MODEL=gpt-4o-mini
OPENAI_API_KEY=your-provider-key生产环境构建并启动:
npm run lint
npm run typecheck
npm run build
npm test
NODE_ENV=production npm start注意 npm run test:release 在缺少真实 Memory 或 Execution 服务与凭据时会按设计失败。
如何使用这个 Agent?
启动开发服务并验证存活与流量门禁:
npm run dev
curl -fsS http://127.0.0.1:3000/api/v1/health
curl -fsS http://127.0.0.1:3000/api/v1/ready用示例 CLI 登录并发起一次流式对话:
npm run cli -- login --email [email protected]
npm run cli -- chat "Explain the active runtime" --stream
npm run cli -- tools
npm run cli -- skills
npm run cli -- workflows以库的方式加载并编译一个 DomainPack,再将其注册进应用组合层:
import {
applyDomainAgentPatch,
compileDomainPackToHarnessedSystem,
DomainPackRegistry,
LocalDomainPackLoader,
} from '@codesoul-co/hypha-domain';
const registry = new DomainPackRegistry();
await new LocalDomainPackLoader({
directories: ['configs/domain-packs'],
}).loadInto(registry);
const domainPack = registry.get('domain.minimal', '0.0.0');
if (!domainPack) throw new Error('DomainPack not found');
const compiled = compileDomainPackToHarnessedSystem(domainPack, {
agentRef: { id: 'agent.default', version: '1.0.0' },
taskSchemaId: 'task.minimal',
workflowId: 'workflow.minimal',
sessionProfileId: 'session.local',
memoryProfileId: 'memory.local',
});
const agent = applyDomainAgentPatch(
{
id: 'agent.default',
version: '1.0.0',
name: 'Default Agent',
modelAlias: 'default-chat',
},
compiled.agentPatch
);在 DomainPack 的工作流状态中收紧能力上限,例如只允许只读工具与指定技能:
states:
- id: Research
goal: Collect bounded evidence.
allowedTools: [common.search]
allowedSkills: [skill.context-enrichment]
requiredSkills: [skill.context-enrichment]
allowedMCPProfiles: [mcp.local]
permissionScopes: [search.query]
policyRefs: [policy.readonly]
timeoutPolicy:
timeoutMs: 30000
onTimeout: fail
retryPolicy:
maxAttempts: 2需要开启缓存时设置 HYPHA_SERVING_CACHE=memory|sqlite|redis 与 HYPHA_WORKCACHE=off|memory|sqlite|redis,并通过 HYPHA_MEMORY_CONFIG_PATH 指向自定义 Memory 配置。
这个 Agent 有哪些优点和局限?
- Agent Core 与 Production Harness 分层明确,FSM 执行、检查点、恢复、重放与审计都有组件对应,而非仅靠提示词约束
- 以 DomainPack 作为产品集成边界,同一运行时通过编译生成 fsmProcess、bindings 与 dependencySnapshot 支撑多领域智能体
- 缓存被设计为多层可丢弃投影,并明确“命中不授权”的不变量,缓存开关不应改变事实来源语义
- 工具调用与 MCP 能力需通过策略、审批与版本批准,工作流状态可进一步收紧 allowedTools 与 requiredSkills
- 以 15 个版本对齐的 @codesoul-co/hypha-* npm 包发布,并提供 Express HTTP API、OpenAPI 3.1 与示例 CLI
- 必须自备 MongoDB 与 Redis 等基础设施,按 README 的生产清单还需 TLS、备份与保留策略,部署门槛明显高于单体库
- 配置面广:DomainPack、config.yaml、tools.yaml、memory-profiles.yaml 与多个环境变量需协同,误配可能导致启动或就绪门禁失败
- 尚需针对真实 Memory 与 Execution 提供方运行 test:release,且缺少凭据时该套件会刻意失败,验证成本较高
- 品牌资产不在 Apache-2.0 范围内,改造后的分支产品必须使用自己的主品牌
- README 中仅给出 OpenAI 的 gpt-4o-mini 示例配置,其他提供商的接入需自行确认
这个 Agent 与同类方案有什么区别?
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Hypha 智能体框架 当前 | 55 · 缺口较多 | 自托管服务免费 + 模型费 | ★ 452 | 5 天前 | TypeScript | OpenAI API |
| RocketRide | 84 · 表现良好 | — | ★ 20k | 今天 | Python | — |
| Swarm | 47 · 缺口较多 | Agent 插件 / 技能免费 | ★ 754 | 6 个月前 | TypeScript | Claude Code |
| Kun 工作台 | 57 · 缺口较多 | 桌面应用免费 + 模型费 | ★ 6.4k | 5 天前 | TypeScript | ChatGPT · Codex · OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
least_privilege:README 与 tool-mcp-security.md 明确要求工具/MCP/文件/执行写入经过 policy、审批、幂等与 harness 边界,DomainPack 需显式注册才获得运行时权限,属于有据可依的最小权限设计(2)。user_confirmation:文档声明 write/irreversible 能力需显式策略并可能需审批,但样本中未见具体审批 UI 或默认拒绝逻辑,仅文档断言(2)。data_flow_transparency:README 描述 Event/Artifact/receipt 作为事实来源,缓存不得成为权威,数据流有清晰分层(2)。sensitive_data_handling:安全指南要求凭据放在 ToolSpec/DomainPack 之外、事件中不得含授权头或敏感路径、需配置 auditPolicy.redactPaths,且测试验证 DLQ 记录已脱敏;但框架不自带密钥管理器,属部署责任(2)。dependency_security:package.json 有 npm audit 脚本与 CI 中的 npm run audit、test:audit-policy,并锁定部分依赖版本;但依赖数量庞大且未提供审计结果,无法确认无已知漏洞(2)。external_effects:安全指南区分 none/read/write/external_effect/irreversible,要求幂等或 receipt 对账,已知限制说明无 reconciler 时中断写入变为 conflict(2)。rollback:存在 checkpoint、recovery、replay、legacy 迁移回滚模块与恢复树,但样本未展示端到端回滚演练(2)。source_attribution:README 引用 benchmark 结果但未给出可复现脚本或数据链接,Skill 要求保留来源但框架层面溯源证据有限(1)。
self_consistency:README 架构描述与 core/adapters 导出、CLI 薄客户端定位、测试断言(/ready 失败关闭)相互一致(2)。dependency_availability:engines 要求 Node>=22,README 列出 MongoDB/Redis 与模型 provider 前置条件,CI 使用 mongo:7/redis:7 服务;但本地适配器依赖 better-sqlite3 原生模块,跨平台可用性未在样本中验证(2)。failure_messages:CLI 统一捕获错误并打印 code: message,/ready 返回结构化组件状态;但样本中未见运行时错误分类或用户可读的恢复指引(1)。
audience_and_scenarios:README 明确面向生产级 LLM agent 应用开发者,给出 DomainPack 集成路径与 release-agent 示例(2)。capability_boundaries:文档明确 DomainPack 是产品集成边界,产品逻辑不得进入 core/kernel,缓存不得授权副作用(2)。trigger_precision:Skill 示例仅使用 always 触发器,未见条件触发或冲突消解规则(1)。environment_fit:支持本地 SQLite/文件、Docker、远程 HTTP、PostgreSQL、S3 等多种适配器,环境适配面广(2)。
information_architecture:README 分层清晰,docs 下有 guides/adr/reference,结构良好(2)。install_notes:Quick start 给出 Node 版本、npm ci、.env 配置、docker 启动 Mongo/Redis、健康检查命令(2)。naming_stability:包名 @codesoul-co/hypha-* 与版本 1.0.1 一致,CLI 版本固定(2)。examples_and_faq:仅有一个 release-agent 示例与 Skill 样例,缺少 FAQ 与更多场景示例(1)。known_limitations:docs/reference/tool-mcp-known-limitations.md 列出存储、缓存、取消、密钥管理、API Key 认证等具体限制(2)。license:仓库根目录含完整 Apache-2.0 LICENSE,package.json 声明一致(3)。versioning_changelog:README 链接 v1.0.1 release 与 UPGRADING.md,但样本中无 CHANGELOG 内容(1)。maintenance_responsibility:发布者为未验证身份,README 未给出维护者、支持渠道或 SLA(1)。
output_usability:框架提供 CLI、REST API、DomainPack 编译输出与结构化输出契约,可直接用于构建 agent 产品(2)。marginal_value:与通用 agent 框架相比,其差异化在于 harness/缓存/恢复,但 README 的 benchmark 仅比直接调用高约 1 个百分点,边际价值证据薄弱(1)。cost_benefit:缓存与复用平面声称节省 API 成本,但样本未给出可核验的成本数据,且部署需 MongoDB/Redis 增加运维成本(1)。
claim_traceability:README 的 benchmark 表引用 main@ef33263 但未提供数据集、脚本或原始结果,无法追溯(1)。cross_source_corroboration:测试文件与 CI 工作流部分佐证了 /ready、命令幂等、MCP 测试零跳过等声明,但 benchmark 与缓存收益无交叉证据(1)。fact_inference_separation:文档中架构描述与性能声明混排,未明确区分事实与推断(1)。
- 发布者身份未经 FollowAgents 验证,维护责任与支持渠道不明确,生产采用前应自行评估。
- README 中的 benchmark 结果缺少可复现脚本与原始数据,不应作为选型依据。
- 框架不自带密钥管理器,凭据与审计脱敏需由部署方自行配置。
- 本地适配器依赖 better-sqlite3 原生模块,跨平台可用性未在样本中验证。
- API Key 认证路径尚未启用,部署方不得对外宣称支持 X-API-Key 认证。
最近版本
来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。
-
v1.0.1 Hypha npm release 1.0.1
发布说明摘录
Patch release of the @codesoul-co/hypha-* npm line. Fixes since the 1.0.0 publication: - @codesoul-co/hypha-skills now ships the framework built-in skills (context-enrichment, intent-classification) in its tarball and exposes resolveBuiltinSkillsDirectory() (#22). The 1.0.0 tarball could not load built-in skills for npm consumers. - Repository gates: npm audit findings (js-yaml, nanoid) resolved (#23). All 15 packages are published at 1.0.1 with exact-version internal dependencies.在 GitHub 查看 ↗ -
v1.0.0 Hypha v1.0.0
发布说明摘录
Hypha v1.0.0 is the initial stable release of the ReAct + FSM agent-system framework. Highlights: - Application-defined FSM runs from validated FSMProcessSpec values or compiled DomainPack workflows. - FSM topology analysis and governed manual state transitions with policy, revision, lease, fencing, idempotency, terminal events, and replay evidence. - Production harness, DomainPack, provider-neutral memory, storage, tools, skills, MCP, inference, local adapters, serving cache, and testing packages. - OpenAPI 3.1 route inventory and a standalone release consumer example. …在 GitHub 查看 ↗
常见问题
缓存命中会让我绕过审批或直接执行写操作吗?
DomainPack 文件放到磁盘上就会生效吗?
自建 FSM 拓扑会不会绕开框架的安全阶段?
运行需要哪些外部服务?
能否商用?
Hypha 智能体框架 官网是什么?
Hypha 智能体框架 免费吗?
Hypha 智能体框架 开源吗?
Hypha 智能体框架 还在维护吗?
Hypha 智能体框架 是谁开发的?
谢谢反馈,我们会据此改进页面。