heymrun/heym · 上手攻略

仓库：heymrun/heym
链接：https://github.com/heymrun/heym
分类：agent / rag（Python + TypeScript，MIT + Commons Clause）
作者：spark
更新：2026-10-23

资料核验：README 于 2026-10-22 UTC 通过 raw.githubusercontent.com 实抓（main 分支），取 What Is / Lifecycle 表 / Key Capabilities / Product Demos / Quick Start / Deployment 段。文中命令、端口、环境变量逐字取自该版本。⚠️ 本次未运行任何代码、未 clone，仅只读公开内容。仓库卡片记录许可为 NOASSERTION，但 README 徽章明示 MIT + Commons Clause，两者不一致，见坑 7。

一、是什么

Heym 是一个自托管（self-hosted）的 agent 运行时与平台，定位一句话是 README 的标题："Build agentic systems. Run them with confidence." 它把 agentic 系统的完整生命周期收在一处：Build → Orchestrate → Run → Observe → Evaluate → Control → Expose。

核心概念只有一个：workflow。一个 workflow 定义 agent、确定性步骤、工具和数据如何协作；runtime 执行这张图，协调依赖与并行工作，记录执行历史，并支持人工审阅检查点。

README 里有一句很重要的自我界定："The canvas is one interface into Heym. It is not Heym itself." 画布只是入口，真正的运行时可以通过 API、计划任务、事件触发、MCP 客户端和 Portal 会话驱动同一批 workflow——所以你可以画着建、用代码跑。

技术栈（README 徽章）：Python 3.11+ / FastAPI 0.100+ 后端、Vue.js 3.x + TypeScript strict 前端、Bun 运行时、Docker、PostgreSQL。

二、解决什么问题

把 agent 从 demo 推到生产，中间有几道一直没人帮你补的门：

看得见吗？ 出错了不知道为什么、每步花了多少钱、哪个 prompt 在悄悄退化。
管得住吗？ agent 要不要钱就能发邮件、删数据、改配置？
能改吗？ 改一句 prompt 之后，怎么知道整体是变好还是变坏？
能被用吗？ 团队里非工程同学怎么用上这套流程？

Heym 的答案是把这四件事做成 runtime 的一等能力，而不是让你自己在外面拼 LangSmith + 网关 + 审批流。

生命周期各阶段的对应能力（README 原表）：

阶段	在 Heym 里做什么
Build	视觉化组合 agent 与确定性 workflow，用 AI 生成，或从模板与 skill 起步
Orchestrate	协调 agent、子 agent、子 workflow、工具，显式数据流、分支与并行执行
Run	从 API、计划任务、事件触发或交互界面执行，可配重试、错误路径、浏览器自动化
Observe	检查执行历史、实时状态、trace、工具调用、token、延迟、错误与模型成本；支持分析与告警、导出 OpenTelemetry
Evaluate	用期望输出测试 prompt 与模型响应，跨模型对比，查看保存的评测运行
Control	在审阅检查点暂停 agent 执行，人工决策后从保存状态恢复；配置 guardrail、凭证、认证与团队访问
Expose	通过 REST、SSE 流式、MCP 工具、Portal chat 对外服务，或接到 dashboard widget

三、快速安装

前置依赖：Bun、Python 3.11+、UV、Docker。

git clone https://github.com/heymrun/heym.git
cd heym
./run.sh

# 或者用 .env 文件（run.sh 会自动生成 SECRET_KEY 和 ENCRYPTION_KEY）
cp .env.example .env
./run.sh

run.sh 会启动 PostgreSQL、后端和前端，缺密钥时自动生成。打开 http://localhost:4017 注册账号开始用。

生产部署（Docker Compose）：

cp .env.example .env
./deploy.sh              # 构建并部署（密钥为空时自动生成）
./deploy.sh --down       # 停止服务
./deploy.sh --logs       # 查看日志
./deploy.sh --restart    # 重启服务

README 特别提示：先注册管理员账号，再把 .env 里 ALLOW_REGISTER=false 并重启，以在生产环境关闭注册。

预构建镜像（ghcr.io/heymrun/heym:latest，前后端已打包，连接宿主机上已有的 PostgreSQL）：

docker run \
  -e ENCRYPTION_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))") \
  -e SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))") \
  -e DATABASE_URL=postgresql+asyncpg://postgres:postgres@host.docker.internal:6543/heym \
  -e FILE_STORAGE_DIR=/app/data/files \
  -e HEYM_PLUGINS_DIR=/app/data/plugins \
  -p 4017:4017 \
  --shm-size 2g \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd)/data/files:/app/data/files" \
  -v "$(pwd)/data/plugins:/app/data/plugins" \
  -v heym-codex-workspaces:/app/data/codex-workspaces \
  -v heym-opencode-workspaces:/app/data/opencode-workspaces \
  ghcr.io/heymrun/heym:latest

Linux 上用 host.docker.internal 这个主机名时要加 --add-host=host.docker.internal:host-gateway。密钥要就地替换 .env.example 里的占位行——README 特别警告用 >> 追加会造成重复条目。各挂载与环境变量的用途：--shm-size 2g 给 Chromium 留空间跑 Playwright；FILE_STORAGE_DIR 指向挂载目录让上传与生成文件跨重启保留（Heym Drive）；HEYM_PLUGINS_DIR 保住已装插件包；两个 *-workspaces 卷留给 Codex / OpenCode 的代码 agent 工作区。

⚠️ 注意那个 -v /var/run/docker.sock:/var/run/docker.sock——它把宿主机 Docker socket 挂进容器，等价于宿主机 root 权限。见坑 5。

四、核心用法

4.1 用自然语言生成 workflow

README 的示例 prompt（Orchestrator + 两个并行 sub-agent）：

Create a workflow for me that includes a Roadmap Agent and a Best Food Agent. When the Orchestrator Agent receives a request, it will invoke these subagents in parallel and return the result to the user.

AI Assistant 会在画布上把图生成出来，之后你可以直接改。同一张图随后可以被 API、计划任务、触发器和 MCP 调用。

4.2 建 skill 并挂给 agent

Create a skill for me and add it to the agent. The Orchestrator Agent will call this skill after receiving information from the subagents, and the skill will create a simple execution plan explaining what can actually be done in the destination city.

skill 就是可复用的 SKILL.md 指令，可附可选的 Python 工具；也支持用 AI 创建或改写、安装插件，或用带类型化配置与执行 handler 的方式实现自定义节点。

4.3 把 workflow 变成 chat

I live in Berlin and am planning to go to Frankfurt. How many kilometers is it on the Autobahn? Also, where can I find the best doner in Frankfurt?

workflow 可以发布成带流式输出、上传与会话历史的 chat 界面。

4.4 能力清单（按需查阅）

Build：视觉化 + AI 辅助创作；LLM/Agent 节点与条件、switch、循环、merge、数据变换、子 workflow 调用混排；部分节点字段支持表达式（Expression DSL）；多 agent 编排（给 orchestrator 具名 sub-agent 与 sub-workflow，独立调用可并发）；RAG 走 Qdrant 或 PostgreSQL + pgvector，可开 per-agent 知识图谱跨运行记忆并配置 agent 间共享；工具接入覆盖通信服务、开发者工具、效率应用、数据库、队列、存储，支持 MCP Call 节点做确定性调用。
Run：并行执行 + Merge 同步、重试/退避/错误路径/模型 fallback；触发方式有 cron、webhook、消息集成、inbox 事件、WebSocket 消息、平台事件；浏览器与编码 agent——Playwright 自动化浏览器任务并有 AI 辅助选择器恢复，Codex 或 OpenCode Go 可作为 workflow 步骤跑仓库，输出 diff 与 PR；Agentic Kanban Board——卡片即持久化 agentic job，把卡片拖进某列就跑它的有序 workflow 链（带卡片内容、评论、历史与上一步输出），再把结果写回卡片；多实例通过 PostgreSQL 共享后台运行，权重在 Settings → Instances 配置。
Observe：从 History 或 Board 卡片打开生产运行、查看保存状态、跟踪实时节点进度、Debug 日志与最终输出；trace 层可看模型请求/响应、工具调用、输入输出 token、延迟与错误，按维护中的模型价格表 + 自定义覆盖算 USD 成本，并按模型与时间范围看历史花费；分析、日志与告警覆盖执行量、成功率、时长，可对错误、时长、token 或 USD 花费、运行次数设告警，并导出 workflow / 节点 / Agent 工具 span 到 OpenTelemetry。
Evaluate & Control：可重复的 prompt 评测，跨模型对比期望与实际输出，查看历史评测运行；Workflow Analyzer 用执行上下文生成一份共享可编辑的 Markdown 报告，讲 purpose、步骤行为与可改进点；人工审阅——agent 检查点暂停执行等待接受/编辑/拒绝，然后从保存的执行快照继续，审阅分支可经现有集成通知人；安全侧有输入 guardrail、加密凭证、团队共享、执行令牌与 workflow 认证，支持 JWT 或 OIDC SSO（Keycloak、Okta、Entra ID、Auth0、Google）。
Expose：REST、SSE 流式、MCP 工具；Portal 与 Chat 发布 workflow 支撑的对话界面；自定义 dashboard widget、结构化 Data Tables、Heym Drive 文件（团队共享与分享链接）。

五、典型适用场景

企业内网 agent 平台：数据不出网，自托管 + OIDC SSO + 加密凭证 + 团队访问控制。
需要人工审批的自动化：agent 检查点暂停、人工决策后从快照恢复，适合对外发信、改配置这类不可逆动作。
成本与稳定性要交代清楚：trace 层带 token、延迟、USD 成本与按模型的花费历史，再配花费告警。
业务人员自助：把 workflow 发布成 chat 界面或 dashboard widget，非工程同学直接用。
Agentic 看板驱动的工作：Kanban Board 把"拖卡片进列"变成触发 agentic job 的动作。

不适合：只想在 notebook 里跑一个单 agent 脚本——这套东西的重量（PostgreSQL、Bun、UV、Docker、前后端）远超需求。

六、坑与注意（7 条）

坑 1 · 现象：只 clone 下来就以为能跑。影响：一执行 ./run.sh 就失败。修复：前置依赖四个都要有——Bun、Python 3.11+、UV、Docker。缺 Bun 或 UV 是最容易漏的（README 把它们排在 Python 和 Docker 前面，但很多人只盯着 Python）。

坑 2 · 现象：生产环境忘了关注册。影响：任何人都能注册进你的实例。修复：README 的顺序是先注册管理员账号，再把 .env 里 ALLOW_REGISTER=false 并重启。顺序反了就把自己关在门外。

坑 3 · 现象：直接 docker run 而漏掉 --shm-size 2g。影响：Playwright / Chromium 因共享内存不足而崩溃，表现为浏览器任务随机失败而非明确报错。修复：加上 --shm-size 2g；另外注意 step-based Playwright 跑在 Heym 容器内，而自定义 playwrightCode 跑在有自己共享内存设置的兄弟容器里——两者行为不同，调试时别混。

坑 4 · 现象：用 >> 往 .env 追加密钥。影响：出现重复的 SECRET_KEY / ENCRYPTION_KEY 条目，实际生效值不确定。修复：README 明确要求就地替换 .env.example 里的占位行，用 sed -i 改，而不是追加。

坑 5 · 现象：把宿主机 Docker socket 挂进容器。影响：容器内代码获得近似宿主机 root 权限。修复：README 的官方示例确实挂了这个 socket（Playwright 与代码 agent 需要），所以这是设计取舍不是配置错误——但你必须清楚这一点，务必让容器跑在与数据敏感度匹配的隔离环境里，并在生产中收紧网络与卷挂载范围。

坑 6 · 现象：把画布当成 Heym 本身。影响：架构设计走偏——以为所有逻辑都锁在画布里。修复：README 专门澄清画布只是入口；同一批 workflow 还能从 API、cron、webhook、消息集成、MCP、Portal chat 触发。设计集成时按"workflow 是资产、画布是编辑器"来划分。

坑 7 · 现象：假设许可证就是纯 MIT。影响：商用条款判断可能出错。修复：README 同时挂 MIT 与 Commons Clause 两块徽章（后者条件性附加限制，通常约束"作为托管服务转售"），而组织内卡片记录的是 NOASSERTION。⚠️ 本次未 fetch LICENSE 与 COMMONS-CLAUSE.md 正文，商用前必须读原文。

坑 8 · 现象：以为版本号稳定。影响：照旧文档抄 deploy.sh 参数或环境变量名可能对不上。修复：README 的版本徽章是从 frontend/package.json 动态读取的，说明迭代很活跃；本文内容取自 2026-10-22 实抓的 main 分支，无 release tag 锚点（⚠️ 未确认是否有已发布 release），全量环境变量以仓库 ENVIRONMENT-VARIABLES.md 为准（本次未 fetch）。

七、与同类对比

vs n8n / Zapier（带 AI 节点）：n8n 是通用集成自动化平台，agent 能力是后加的；Heym 的重心是 agent 运行时——多 agent 编排、检查点、trace 与成本、评测都是一等的。代价是更重、更吃资源。
vs LangGraph / CrewAI（框架）：那些是库，你写代码定义图、控制持久化与部署；Heym 是带 UI、数据库、鉴权、告警、OTel 导出的完整平台，非工程同学能上手。代价是灵活性受平台抽象约束，深度定制要走自定义节点。
vs Dify / Flowise（开源 LLM 应用平台）：同属"可视化搭 agent"赛道。Dify 偏应用编排与对外发布，Heym 在执行可观测性（trace + token + USD 成本 + 花费告警）和human-in-the-loop 检查点上写得更重。
vs 自建 LangSmith / Helicone 观测层：那些是加在流程外面的观测，Heym 把观测做进运行时，能从执行现场一路点到花费告警。缺点还是那句话——引入了一个必须自己运维的平台。
vs 直接在 Kubernetes 上跑裸 agent 服务：Heym 给你的是完整产品面（画布、门户、看板、评测）。如果你只需要编排，LangGraph 更轻。

八、一句话推荐结论

推荐：想把 agent 从 demo 推到生产、又要求数据不出网、并且需要给非工程同事提供自助入口的团队——Heym 把可观测性、成本核算、人工审批、自托管鉴权这四件难事一次性给全，值得花一天 ./run.sh 试一遍。

不推荐：只跑单 agent 实验、或团队更愿意维护轻量代码而非运维平台的人——四个前置依赖 + PostgreSQL + 前后端是实打实的重量，此时 LangGraph 或裸脚本更划算。

来源： - 仓库 README（raw.githubusercontent.com/heymrun/heym/main/README.md，2026-10-22 UTC 实抓，取 What Is Heym / Lifecycle 表 / Platform Overview / Key Capabilities / Product Demos / Screenshots / Quick Start / Deployment 段） - README 内引用但未 fetch：ENVIRONMENT-VARIABLES.md、SECURITY.md、LICENSE、COMMONS-CLAUSE.md、README 后半的 "Deploy & Call Workflows" 与 "Extending Heym" 段、YouTube 演示与教程播放列表 - README 引用的外部站点：heym.run - 组织内卡片：organized/repo_cards/4561-heymrun-heym.md

⚠️ 未确认清单：具体 release 版本号（徽章为动态读取）；LICENSE 与 COMMONS-CLAUSE.md 正文条款；README "Deploy & Call Workflows" 段中的 REST/SSE/MCP 调用示例（本次抓取截断，未取到）；自定义节点与插件的具体 API；YouTube 演示中呈现的实际配置。