Hypha 智能体框架

用 DomainPack 声明业务,用事件溯源运行时把 LLM 智能体变成可控、可恢复、可审计的生产系统。

Star 数
★ 452
最近更新
5 天前
License
Apache-2.0
主语言
TypeScript

30 秒速览

运行形态
自托管服务开发框架代码库 / SDK
可在哪里用
通用 · 跨平台OpenAI API
费用
软件免费,模型调用费用自付
上手难度
高 · 需要较重的基础设施
开始前需要
Node.js 22npmMongoDBRedisOpenAI API 密钥(或其他模型提供商)Shell / 命令行网络访问本地文件系统MCP Server
典型场景
需要把内部业务智能体(如财务对账、法务审查)做成可审计、可重放系统的平台团队
不适合
  • 希望开箱即用、不搭建 MongoDB 与 Redis 的个人开发者
  • 只需要简单脚本调用 LLM、不关心事件溯源与恢复的团队
  • 不愿维护策略、审批与缓存一致性等运行时基础设施的小团队
官网
codesoul-co.github.io/Hypha ↗ 来自 GitHub 仓库设置
维护状态
近 30 天有提交最近提交 2026-11-15最新版本 v1.0.1(2026-08-14)

这个 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 存储。

  1. 需要把内部业务智能体(如财务对账、法务审查)做成可审计、可重放系统的平台团队
  2. 要在同一运行时上运行多个垂直领域智能体、只替换 DomainPack 的 SaaS 厂商
  3. 对工具调用有审批与策略要求、必须留下 Event 与 Artifact 证据的合规敏感团队
  4. 需要长任务断点续跑、失败恢复和人工复核环节的自动化流程负责人
  5. 想通过 DomainPack 而非改内核来定制提示词、技能与工作流的应用开发者
  6. 在本地或私有环境中部署 LLM 智能体、同时希望复用 Redis/SQLite 缓存降低成本的基础设施团队

安装与配置要点

摘自下方的安装和使用说明,以项目 README 的最新说明为准。

安装 / 启动命令
  • docker run -d --name hypha-mongodb -p 27017:27017 mongo:8
  • docker run -d --name hypha-redis -p 6379:6379 redis:7-alpine
环境变量
HYPHA_OWNER_PASSWORD JWT_SECRET HYPHA_LLM_DEFAULT_MODEL OPENAI_API_KEY HYPHA_MEMORY_CONFIG_PATH
配置文件
.env.example .env config.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?

FollowAgents 源码审查 · FARS-2.1
缺口较多
55/ 100 五分制 2.8 / 5
信任安全 18/29
可靠稳定 8/14
适用触发 10/18
规范维护 10/18
有效结果 6/13
证据核验 3/8
查看各维度的扣分理由
信任安全18 / 29 · 3.1/5

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)。

可靠稳定8 / 14 · 2.9/5

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)。

适用触发10 / 18 · 2.8/5

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)。

规范维护10 / 18 · 2.8/5

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)。

有效结果6 / 13 · 2.3/5

output_usability:框架提供 CLI、REST API、DomainPack 编译输出与结构化输出契约,可直接用于构建 agent 产品(2)。marginal_value:与通用 agent 框架相比,其差异化在于 harness/缓存/恢复,但 README 的 benchmark 仅比直接调用高约 1 个百分点,边际价值证据薄弱(1)。cost_benefit:缓存与复用平面声称节省 API 成本,但样本未给出可核验的成本数据,且部署需 MongoDB/Redis 增加运维成本(1)。

证据核验3 / 8 · 1.9/5

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 认证。
证据充分度:低 评估于 2026年11月17日 审查版本 a28e190d4037
查看完整评分方法 →
你是这个项目的维护者?把 FARS 徽章加到 README

徽章显示当前的评审分数和结论,点击回到本页。重新评审后约一小时内更新。

FARS

[![FARS 评测](https://followagents.com/badge/hypha.svg?lang=zh)](https://followagents.com/zh/agents/hypha)
<a href="https://followagents.com/zh/agents/hypha"><img src="https://followagents.com/badge/hypha.svg?lang=zh" alt="FARS 评测"></a>

最近版本

来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。

  1. 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 查看 ↗
  2. 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 查看 ↗

常见问题

缓存命中会让我绕过审批或直接执行写操作吗?
不会。README 把缓存定义为可丢弃投影,命中不能授权副作用、跳过 Policy 或 Approval、伪造回执、推进 FSM 或替代 Event 与 Artifact 证据;开启与关闭缓存的执行必须保持相同的事实来源语义。
DomainPack 文件放到磁盘上就会生效吗?
不会。编译后仍需由受信任的应用组合层显式加载注册、解析模型别名与提示词引用、注册技能、绑定工具适配器、批准 MCP 能力版本,并把 processHash 与 dependencySnapshot 随 Run 的事件证据一起持久化。
自建 FSM 拓扑会不会绕开框架的安全阶段?
Workflow-only 的 Run 可以执行经过校验的应用自有 FSMProcessSpec,但 ReAct Run 保留框架拥有的 Harness FSM,产品图不能跳过推理、策略、活动、观察、验证、记忆或恢复阶段;手工迁移还要求精确的进程身份、期望状态与 Run 修订号、幂等键和原因。
运行需要哪些外部服务?
Node.js 22 及以上、npm、MongoDB 与 Redis,以及至少一个模型提供商或本地模型端点;/api/v1/ready 会在存储、模型提供商、Memory、规范运行时图和必需 worker 就绪前返回失败。
能否商用?
源代码采用 Apache-2.0,允许商业使用、修改、分发与私有使用;但 Hypha 名称、Logo、字标等品牌资产不在该许可内,第三方产品需使用自己的主品牌。
Hypha 智能体框架 官网是什么?
Hypha 智能体框架 的 GitHub 仓库填写的官网是 https://codesoul-co.github.io/Hypha/。这个链接由仓库作者设置;源码在 GitHub(CodeSoul-co/Hypha)。
Hypha 智能体框架 免费吗?
软件本身免费,但 Hypha 智能体框架 要调用 AI 模型,模型的调用费用由你向模型服务商支付(也可以接本地模型)。
Hypha 智能体框架 开源吗?
开源。源码在 GitHub(CodeSoul-co/Hypha),许可证是 Apache-2.0。
Hypha 智能体框架 还在维护吗?
在维护。GitHub 上最近一次提交是 2026-11-15,在最近 30 天内。最新版本是 v1.0.1(2026-08-14)。
Hypha 智能体框架 是谁开发的?
Hypha 智能体框架 由 GitHub 账号 CodeSoul-co 发布。FollowAgents 没有核实这个账号背后是哪个人或公司。
这页内容对你有帮助吗?
在 GitHub 查看 ↗ 安装 ↓

对比同类 Agent

用同一套 FARS 评审,横向比较这个 Agent 所属的短名单。

相关核心概念