第 5 部分 — Studio
HiveFlow Studio 自托管运维 UI 完整 walkthrough。
5.1 启动 Studio
Docker(最简单)
docker compose up --build
| 地址 |
用途 |
| http://localhost:3000 |
React 前端 |
| http://localhost:8000 |
FastAPI 后端 |
| http://localhost:8000/docs |
OpenAPI Swagger |
本地开发(两个终端)
# 终端 1 — 后端
cd packages/studio/backend
pip install -r requirements.txt
export HIVEFLOW_RUNTIME=agent
export HIVEFLOW_AGENT_ECHO_LLM=true
export HIVEFLOW_PLAN_HITL=true
uvicorn app.main:app --reload --port 8000
# 终端 2 — 前端
cd packages/studio/frontend
npm install && npm run dev
5.2 Golden Path — Agent 模式
- 打开 Orchestrator(编排器)。
- 在工具栏开启 Agent / real mode。
- 输入目标:Summarize three trends in AI agents(或中文目标)。
- 点击 Plan only(仅规划) — 审阅生成的 TaskGraph。
- 点击 导入到画布。
- 点击 执行 DAG。
启用 HIVEFLOW_PLAN_HITL=true 时,第 4 步会在 Approvals(人工审批) 创建 gate,执行前需审批。
深度阅读:Studio Agent 模式 Cookbook。
5.3 Studio 页面参考
| 页面 |
功能 |
| Dashboard(仪表盘) |
系统概览、近期活动 |
| Orchestrator(编排器) |
DAG 画布、Agent 抽屉、规划/执行 |
| Chatflow(对话流) |
对话式流程构建;Agent 模式通过 run_query 运行 ai_reply 节点 |
| Agents(智能体) |
注册与配置 Agent |
| Approvals(人工审批) |
HITL gate — 批准/拒绝/编辑计划 JSON |
| Blackboard(黑板) |
实时查看共享键 |
| Analytics(执行分析) |
执行指标、成功率 |
| Tracer(任务追踪) |
实时 WebSocket 追踪(intent_id、trace_id) |
| Replay(执行回放) |
按 intent_id 审计与检查点回放 |
| Events(事件) |
事件总线历史 |
| Knowledge Base(知识库) |
RAG 文档管理 |
| LLM Config(LLM 配置) |
Provider 密钥与路由 |
| Capability Market(能力市场) |
MCP 插件安装/卸载 |
| Triggers(触发器) |
定时与 Webhook 触发 |
| Variables(变量) |
环境与工作流变量 |
| Prompt Templates(Prompt 模板) |
可复用 Prompt 库 |
| A/B Testing(A/B 测试) |
对比 Prompt/模型变体 |
| Audit Log(审计日志) |
合规轨迹 |
| Settings(设置) |
Studio 配置 |
5.4 主要 HTTP API
| 端点 |
方法 |
用途 |
/api/agent/query |
POST |
NL 查询 → 规划 → 执行 |
/api/agent/plan-only |
POST |
仅生成计划 JSON |
/api/agent/execute-plan |
POST |
执行已有计划图 |
/api/agent/export-langgraph |
POST |
画布导出 LangGraph |
/api/workflows/* |
* |
Core DAG CRUD + 执行 |
/api/hitl/* |
* |
审批门 |
/api/blackboard/* |
* |
读写共享状态 |
/api/analytics/* |
* |
指标(真实模式) |
/api/replay/* |
* |
检查点回放 |
完整参考:API 手册。
5.5 环境变量
| 变量 |
效果 |
HIVEFLOW_RUNTIME=agent |
默认 Agent 运行时 |
HIVEFLOW_AGENT_ECHO_LLM=true |
Mock LLM(无需 API Key) |
HIVEFLOW_PLAN_HITL=true |
执行前计划审批 |
HIVEFLOW_LLM_PLANNING_PROVIDER |
规划阶段 LLM 路由 |
HIVEFLOW_LLM_EXECUTION_PROVIDER |
执行阶段 LLM 路由 |
OPENAI_API_KEY / ANTHROPIC_API_KEY |
真实 LLM Provider |
5.6 Chatflow vs Orchestrator
| 特性 |
Orchestrator |
Chatflow |
| 布局 |
自由 DAG 画布 |
对话导向图 |
| 适合 |
批处理流水线、ETL、多步任务 |
聊天机器人、问答流 |
| Agent 模式 |
plan-only → 画布 → execute |
拓扑排序的 ai_reply 节点 |
5.7 Studio 排障
| 现象 |
处理 |
| plan-only 后画布空白 |
查浏览器控制台;确认 /api/agent/plan-only 返回 200 |
| 执行无反应 |
确认已开启 Agent / real mode |
| 无 LLM 响应 |
设置 HIVEFLOW_AGENT_ECHO_LLM=true 或配置 API Key |
| Tracer WS 断开 |
确认后端 :8000;检查 CORS/代理 |
| Approvals 为空 |
启用 HIVEFLOW_PLAN_HITL=true 并先运行 plan-only |
见 Studio Agent 运维。
5.8 练习
- 用自定义目标完成 Golden Path 并导出 LangGraph JSON。
- 在 Approvals 拒绝计划,编辑 JSON 后重新提交。
- 执行过程中打开 Blackboard 观察键值实时更新。
下一步
→ 第 6 部分 — 生产:部署、监控、维护。