内容
<div align="center">
# 搭建一个完整的智能代理托管系统
**在画布上构建完整的智能代理托管系统。编译为任意编排器。 使用 Langfuse 进行观察。**
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/3IVIS/buildaharness/releases)
[](https://github.com/3IVIS/buildaharness)
[](#)
[](https://github.com/3IVIS/buildaharness/stargazers)
[](CONTRIBUTING.md)
[](https://www.python.org/)
[](https://nodejs.org/)
[](https://www.docker.com/)
[English](README.md) · [中文](README_CN.md)
</div>
---
工作流将提示从一个节点路由到另一个节点。**托管系统** 控制智能代理的**认知**、**允许**的操作、如何捕获自己的错误以及学习内容。 Build A Harness 提供完整的 11 层架构 — 在画布上绘制，编译为任意框架，跟踪每个决策。
```
画布 → flow.json → LangGraph · CrewAI · Mastra · MS Agent Framework → Langfuse
```
> 规范是合同。画布是编辑器。适配器是编译器。
---
## 为什么是托管系统，而不仅仅是工作流
| 简单智能代理循环 | 完整的托管系统 — 已实现 |
|:--|:--|
| 输入 / 调用者 | **调用者状态** — 约束 · 澄清 |
| ↓ | **世界模型** — 信念 · 矛盾 · generation_id |
| LLM 调用 | **推理** — 证据 · 假设（4 个来源） · VOI |
| ↓ | **控制** ← *关键* — 5 级解析器 · NORMAL / CAUTIOUS / BLOCKED |
| 工具调用 ↺ 循环 | **规划** — 任务图（6 状态） · 并行并发 |
| ↓ | **执行** + **验证** — VOI 门 · 9 层 |
| 输出 | **恢复** + **记忆** — 6 种策略 · 压缩 |
| | **学习** — 经验存储 · 热启动 *(可选)* |
| | **输出和审查员通过** — 合同 · 3 镜头审查 |
| *提示输入 → 答案输出* | *22 个节点 · 11 层 · 379 个测试通过* |
---
## 已实现的功能
<table>
<tr valign="top">
<td width="50%">
**画布和执行层**
- ✅ 包含 27 种节点类型的画布（14 种执行 + 13 种托管）
- ✅ 4 种框架适配器 — LangGraph, CrewAI, Mastra, MAF
- ✅ Langfuse 可观察性 — 跨所有运行时的托管跟踪
- ✅ HITL 暂停/恢复 · REST / MCP / A2A 部署
- ✅ FlowSpec v0.2.0 — 开放的，可移植的 JSON 格式
- ✅ 流程概念 — 预先配置的任务图脚手架
</td>
<td width="50%">
**推理和控制层**
- ✅ 世界模型 · 类型化信念 · 矛盾检测
- ✅ 5 级控制状态解析器 · 死锁检测
- ✅ 预执行审查门 · 9 层验证
- ✅ 6 种命名恢复策略 · 类型化故障库
- ✅ 经验存储 — 跨运行的结构化重用
- ✅ 对抗性审查员通过 · 输出合同验证
</td>
</tr>
</table>
---
## 节点调色板
托管系统由 **14 个核心节点** 和 **13 个托管层节点** 构建 — 每个节点都编译为所有四个运行时。 将鼠标悬停在节点名称上以查看其描述。
<table>
<thead><tr><th colspan="4" align="left">核心节点</th></tr></thead>
<tbody>
<tr>
<td nowrap><abbr title="工作流入口点 — 接收初始请求和状态">⤵ <code>输入</code></abbr></td>
<td nowrap><abbr title="工作流出口点 — 将最终结果返回给调用者">⤴ <code>输出</code></abbr></td>
<td nowrap><abbr title="LLM 调用 — 结构化输出，验证器，失败分支，托管 Langfuse 提示">✨ <code>LLM 调用</code></abbr></td>
<td nowrap><abbr title="来自工作流的工具注册表的命名工具">🔧 <code>工具调用</code></abbr></td>
</tr>
<tr>
<td nowrap><abbr title="分支 — JSONPath 或 fn_ref 表达式评估为命名分支目标">⎇ <code>条件</code></abbr></td>
<td nowrap><abbr title="分叉到 N 个并发分支">⑂ <code>并行分叉</code></abbr></td>
<td nowrap><abbr title="聚合 — 合并 / 追加 / fn_ref 缩减器等待所有分支完成">⊖ <code>并行连接</code></abbr></td>
<td nowrap><abbr title="暂停并等待类型化的人类恢复有效载荷 — 跨所有运行时的顺序 HITL">⏸ <code>HITL 断点</code></abbr></td>
</tr>
<tr>
<td nowrap><abbr title="从键值或语义内存存储中读取">📖 <code>内存读取</code></abbr></td>
<td nowrap><abbr title="写入命名内存存储">🔖 <code>内存写入</code></abbr></td>
<td nowrap><abbr title="将另一个流程作为可重用节点嵌入 — LangGraph/Mastra：完全支持；CrewAI：部分支持">📦 <code>子图</code></abbr></td>
<td nowrap><abbr title="状态转换 — 字段映射或 fn_ref 函数应用于流程状态">⇌ <code>转换</code></abbr></td>
</tr>
<tr>
<td nowrap><abbr title="从流程的 agents[] 注册表中执行智能代理角色 — 在 CrewAI 中原生，在其他框架中合成">🤖 <code>智能代理角色</code></abbr></td>
<td nowrap><abbr title="具有可配置终止条件的智能代理循环 — 在 MS Agent Framework 中原生，在其他框架中合成">👥 <code>智能代理辩论</code></abbr></td>
<td></td><td></td>
</tr>
</tbody>
</table>
<table>
<thead><tr><th colspan="4" align="left">托管节点 — 实现 11 层控制架构</th></tr></thead>
<tbody>
<tr>
<td nowrap><abbr title="观察，信念，假设，矛盾 — generation_id 每次显著更新时递增">🧠 <code>世界模型</code></abbr></td>
<td nowrap><abbr title="四个生成来源；多样性强制（0.7 阈值）；K-保留消除策略">💡 <code>假设集</code></abbr></td>
<td nowrap><abbr title="收集类型化证据（观察，可靠性，来源，类型，新鲜度） — 观察永远不会自动提升为结论">🗄️ <code>收集证据</code></abbr></td>
<td nowrap><abbr title="按工具限制范围内的作用域限制最大结论可靠性；更新 verification_health.feasibility">⚙️ <code>应用工具可靠性</code></abbr></td>
</tr>
<tr>
<td nowrap><abbr title="可靠性加权信念整合；信念依赖图传播；更新 completeness_flags">🔄 <code>更新世界模型</code></abbr></td>
<td nowrap><abbr title="五级解析器 → NORMAL / CAUTIOUS / BLOCKED；死锁检测；generation_id 门控断言">🛡️ <code>控制状态</code></abbr></td>
<td nowrap><abbr title="六状态任务分解；循环检测；根据变化重新计算抽象拟合度">🕸️ <code>任务图</code></abbr></td>
<td nowrap><abbr title="9 个验证层因工具可用性清单而被修剪；对 HIGH 风险进行对抗性检查">✅ <code>验证门控</code></abbr></td>
</tr>
<tr>
<td nowrap><abbr title="回滚（）→ 记录失败（）→ 策略切换：DIRECT_EDIT，TRACE_EXEC，BROADER_SEARCH，REIMPLEMENT，MINIMAL_FIX，ESCALATE">♻️ <code>恢复</code></abbr></td>
<td nowrap><abbr title="证据存储，包含工具可靠性信封和工具可用性清单">📋 <code>证据存储</code></abbr></td>
<td nowrap><abbr title="可选的跨运行结构化重用分解，工具工作流，验证计划，恢复序列">📊 <code>经验存储</code></abbr></td>
<td nowrap><abbr title="三镜头审查：实施者 · 审查者 · 对抗者 — 对抗者先验种子化为因果邻近性">👁️ <code>审查员通过</code></abbr></td>
</tr>
<tr>
<td nowrap><abbr title="预先配置的常见任务模式的概念脚手架">🧭 <code>过程概念</code></abbr></td>
<td></td><td></td><td></td>
</tr>
</tbody>
</table>
完整架构，伪代码和状态模型：[plan/harness_architecture.html](plan/harness_architecture.html)
---
## 框架
所有四个运行时都从相同的 `flow.json` 编译而成 — 无需重写。
| 运行时 | 语言 | HITL | 关键集成 |
|:--|:--|:--|:--|
| **LangGraph** | Python | `interrupt()` | `@observe` · 托管子跨度 |
| **CrewAI** | Python | — | `context_from → Task.context` · 分层内存 |
| **Mastra** | TypeScript | `suspend()/resume()` | Node.js 边车 |
| **MS Agent Framework** | Python | `_HitlPause` | `AgentGroupChat` 原生 · OTel → Langfuse |
编译：`POST /compile?runtime=langgraph` — 相同的规范，任意运行时。
部署为 **REST 端点**，**MCP 工具** 或 **A2A 智能代理**，一步完成。
---
## 可观察性
自托管 **Langfuse** 从 `docker compose up` 开始 — 无需额外配置。
- 跨所有四个运行时的每个节点子跨度（世界模型，控制状态，验证，恢复）
- 通过 LiteLLM 的每个节点 token 计数，延迟和成本
- 每次运行后在画布中点击 **查看跟踪 →** 链接
- 通过 Langfuse 提示 API（任何 `llm_call` 节点上的 `prompt_ref`）进行托管提示
---
## 快速开始
```bash
./scripts/setup-env.sh # 生成密钥，写入 .env
docker compose up # 启动所有 9 个服务
```
| 服务 | URL |
|:--|:--|
| 画布 | http://localhost:3000 |
| 适配器 API | http://localhost:8000/health |
| Langfuse | http://localhost:3001 |
<details>
<summary>无需 Docker</summary>
```bash
./scripts/setup-env.sh && source adapter/.venv/bin/activate
npm install && npm run dev # 画布 → localhost:3000
cd adapter && python main.py # 适配器 → localhost:8000
```
</details>
<details>
<summary>运行测试</summary>
```bash
npm test # Vitest — 验证 5 个参考流程
pytest adapter/tests/ -v # 适配器单元 + 集成
pytest adapter/tests/test_maf_adapter.py -v # MAF 套件（742 个测试）
```
</details>
> **新手？** 从 [docs/getting-started.md](docs/getting-started.md) 开始 · **启动错误？** [docs/troubleshooting.md](docs/troubleshooting.md) · 实时协作： [docs/collab.md](docs/collab.md) · 本地部署 / Kubernetes： [docs/deployment.md](docs/deployment.md)
---
## LLM 提供商
所有调用都通过 **LiteLLM** 路由 — 将密钥添加到 `.env`。
| 提供商 | 环境变量 | 示例模型 |
|:--|:--|:--|
| OpenAI | `OPENAI_API_KEY` | `gpt-4o`，`gpt-4o-mini` |
| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet`，`claude-opus` |
| Ollama (本地) | — | `mistral`，`qwen3`，`qwen2.5-coder` |
> **没有 API 密钥？** 安装 [Ollama](https://ollama.com)，运行 `ollama pull mistral`，然后 `./scripts/setup-ollama.sh` — 使用无付费账户测试所有四个框架。
完整设置： [docs/llm-setup.md](docs/llm-setup.md)
---
## 嵌入画布
```bash
npm install @buildaharness/canvas
```
```tsx
import { BuildAHarnessCanvas } from '@buildaharness/canvas'
import '@buildaharness/canvas/styles.css'
<BuildAHarnessCanvas
initialSpec={mySpec}
onSpecChange={(updated) => save(updated)}
execStats={runState.nodeStats}
theme="dark"
/>
```
完整道具参考： [`packages/canvas/README.md`](packages/canvas/README.md)
---
## 文档
| | |
|:--|:--|
| [docs/getting-started.md](docs/getting-started.md) | 逐步指南：克隆 → 密钥 → LLM → 首次运行 |
| [docs/flowspec.md](docs/flowspec.md) | FlowSpec v1.0.0 — 所有 26 种节点类型，边，字段 |
| [docs/architecture.md](docs/architecture.md) | 系统设计，服务交互，数据流 |
| [docs/api.md](docs/api.md) | REST API 参考 — 编译，执行，部署，HITL 恢复 |
| [docs/llm-setup.md](docs/llm-setup.md) | LLM 提供商设置 — OpenAI，Anthropic，Ollama，自定义 |
| [docs/qdrant.md](docs/qdrant.md) | Qdrant 向量存储 — 种子，集合，生产 |
| [docs/env-vars.md](docs/env-vars.md) | 所有服务的所有环境变量 |
| [docs/collab.md](docs/collab.md) | 实时协作 — Yjs 设置和内部实现 |
| [docs/deployment.md](docs/deployment.md) | Docker，Helm，SSO/OIDC |
| [docs/troubleshooting.md](docs/troubleshooting.md) | 常见的启动错误 |
| [plan/harness_architecture.html](plan/harness_architecture.html) | 完整的托管系统 — 伪代码，22 个节点，11 层，状态模型 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 如何贡献 |
---
<div align="center">
Apache 2.0 — 见 [LICENSE](LICENSE).
</div>
连接信息
猜你喜欢
暂无推荐服务器