# AgentLab · 可视化 Agent 编排实验台

在画布上拖节点、连线，编出一条 agent 工作流，然后**看着它跑**——哪个节点在执行、
模型正在吐什么字、调了什么工具、沙箱里的代码返回了什么、在哪一步停下来等你拍板。

不是 demo，是一套能真用的本地实验环境：多模型接入、隔离沙箱、工具链与 MCP、
长期记忆与知识库、人工介入、断点续跑、结构化校验、运行追踪与成本核算。

```
┌──────────┬──────────────────────────────────┬─────────────────┐
│ 节点库    │            画布                   │  运行 / 属性     │
│          │   ┌────┐   ┌────┐   ┌────┐        │  ▸ 输入表单      │
│ 模型      │   │输入│──▶│Agent│──▶│成果│       │  ▸ 实时时间线    │
│ 执行      │   └────┘   └─┬──┘   └────┘        │  ▸ 人工审批      │
│ 控制      │             ▼ 工具调用             │  ▸ 成果 / 用量   │
│ 上下文    │                                   │                 │
│ 把关      │                                   │                 │
└──────────┴──────────────────────────────────┴─────────────────┘
```

## 快速开始

需要 Python 3.12+（`uv` 会自动装）、Node 20+、pnpm。**不需要 Docker** —— 代码沙箱用操作系统自带的隔离原语。

```bash
./scripts/dev.sh
```

打开 http://localhost:5273 。

**不配任何 API Key 也能直接玩**——内置了一个 Mock provider，会产出假的流式回复、
假的工具调用、符合 schema 的假结构化数据，整条编排链路（包括画布高亮、审批中断、
沙箱执行）都会真实走一遍。想要真结果，去「设置 → 模型接入」填 Key 即可。

启动时如果环境里已有 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` / `OPENAI_API_KEY`，
会自动导入成 provider，不用手填。

内置 7 个模板，从「最小问答」到「多 Agent 协作」，既是能直接跑的例子，也是各类节点用法的活文档。

## 能做什么

| 能力 | 怎么体现 |
|---|---|
| **可视化编排** | 15 种节点拖拽连线；运行时节点实时高亮、边上数据流动画、卡片里直接看到流式 token |
| **多模型接入** | Anthropic / OpenAI / 任意 OpenAI 兼容服务（DeepSeek、Kimi、通义、智谱、硅基流动、Ollama…）+ Mock |
| **工具链** | 15 个内置工具 + 自定义工具（HTTP 模板 / 沙箱 Python）+ MCP server 接入 |
| **代码沙箱** | macOS 用 Seatbelt、Linux 用 bubblewrap：断网、家目录不可读、只有工作区可写、超时强杀，冷启动 ~25ms |
| **人工介入** | 图暂停并落盘，人在界面上批准/驳回/改稿，从断点继续——进程重启也不丢 |
| **记忆与知识库** | 跨运行的长期记忆（自动去重）+ 文档知识库（向量 + BM25 混合检索，可调配比） |
| **Skill 管理** | 把「怎么做事」抽成可复用的方法论，挂到节点上注入 system prompt |
| **自然语言编排** | Copilot：一句话生成或改写整张图，自动排版 + 校验 |
| **结构化成果** | JSON Schema 校验，不合格把错误喂回模型自动返工 |
| **追踪与成本** | 每步事件全量落库，可回放；逐节点耗时、token、按目录价折算的美元成本 |
| **三档出具** | 口径卡（受控指标集）+ 出具契约：叙述里每个数字回指指标集，formal / degraded / withheld 三档判定，缺数据声明与口径版本随成果印出 |
| **正式 / 探索分级** | 正式运行只从已发布的不可变版本发起（按图哈希钉死），画布试跑自动标探索性；受管（governed）发布过治理 lint |
| **模板生长** | 探索性运行可一键提取为草稿模板（只保留实际走过的路径）；探索问题聚类提示"该晋升为固定节了"；工具白名单衰减报表 |

## 受限动态编排：模板定骨架、agent 填关节

工业场景的大多数任务步骤是已知的（接单报价、周报、体检），让模型每次现场重新规划
是在重复发明已知答案，而且不可复现就不可验收。AgentLab 的引擎是编译式的——运行时
模型改不了图，它的自由被结构性地关在 agent 节点内部和 branch 决策里。在此之上：

- **模板层**：正式运行只认已发布的不可变版本（`WorkflowVersion` + 图哈希）。
  发布后改画布不影响它。governed 级发布要过治理 lint：禁 supervisor（全动态属于
  探索层）、方法卡必须钉版本、agent 不得关闭全部审批、output 必须有出具契约。
- **关节层**：agent 的工具白名单、分支的语义分类、缺数据时降档——有边界的自由。
  白名单衰减报表（`/api/governance/tool-usage`）把"授了权没用过"的工具摆上台面。
- **探索层**：画布试跑、临时图、追问，结果自动标探索性、不进正式归档。跑通的路径
  用「提取模板」沉淀为草稿（只保留实际执行的节点，剪掉没走的分支），人审后发布。
  探索问题聚类提示哪些追问该长成模板里的固定一节。

**出具链路**（模板⑧就是完整示范）：取数（固定，快照落工件库）→ 口径卡（metrics
节点，所有算术在这里确定性发生，带口径名和版本）→ 叙述（LLM，只许引用指标清单）
→ 出具契约（从叙述抽出所有数字逐个回指指标集，支持千分位/百分数↔比率/万亿后缀/
按书写精度的舍入容差；日期、枚举序号、引用标记不参与）。三档判定印在成果上。
实测：Opus 5 写的正文数字全部回指，但结尾"（约 100 字）"里的 100 被抓住降档——
修的是 prompt 而不是白名单，这正是校验器该有的行为。

钉住的方法卡出现新版本时，正式运行会被拒绝启动，直到模板声明升版处置：
`recompute`（回算历史）/ `dual`（双印）/ `incomparable`（标注不可比），没有默认值
——口径变更最容易静默翻车的地方是"数看起来都对，只是和上周不可比"。

每次运行的完整证据在内容寻址的工件库里（`data/artifacts/`，sha256 即地址，取回
复验哈希）；运行终态的事件清单哈希存在 Run 上，事后改流水会对不上。

## 节点类型

| 分类 | 节点 | 说明 |
|---|---|---|
| 起止 | `input` `output` | 声明输入字段 / 收集结构化成果 |
| 模型 | `llm` `agent` `supervisor` | 单次调用 / 带工具循环 / 多 agent 协作 |
| 执行 | `tool` `code` | 直接调工具 / 沙箱里跑代码 |
| 控制 | `branch` `loop` `subgraph` | 条件或语义分支 / 遍历与条件循环 / 嵌套工作流 |
| 上下文 | `memory` `retrieve` `transform` | 长期记忆读写 / 知识检索 / 数据整形 |
| 把关 | `human` `validate` `metrics` | 人工介入 / Schema 校验与自动返工 / 口径卡（受控指标集） |

节点之间用模板语法传数据：

```
{{ input.question }}        入口输入
{{ vars.answer }}           某节点 assign_to 写入的变量
{{ nodes.n1.text }}         指定节点的输出
{{ vars.items | json }}     过滤器：json / compact / upper / length / first …
```

连线即并行：一个节点连出多条边就是 fan-out，多条边汇入同一节点会自动等待汇聚。

## 架构

```
backend/                  FastAPI + LangGraph
  app/engine/             画布 JSON → StateGraph 的编译与执行
    schema.py             图定义与静态校验
    compiler.py           编译：节点包装、事件、重试、条件路由
    runner.py             执行调度、事件总线、中断与恢复
    expressions.py        模板插值 + AST 白名单表达式求值
    nodes/                各类节点的执行器
  app/providers/          多模型接入与成本估算
  app/sandbox/            Seatbelt / bubblewrap / 裸子进程三后端
  app/tools/              工具注册表、内置工具、MCP、自定义工具
  app/memory/             记忆、知识库、混合检索
  app/api/                REST + WebSocket
frontend/                 React 19 + React Flow + Zustand
  src/canvas/nodeDefs.ts  节点元数据——属性面板、节点库、连接桩全由它驱动
  src/store/studio.ts     画布状态 + 事件流到高亮的映射
scripts/dev.sh            一键启动
scripts/e2e-check.mjs     浏览器冒烟测试
```

### 几个值得说明的决定

**为什么用 LangGraph。** 可视化编排真正难的不是画框连线，是暂停、恢复、回放。
LangGraph 的 checkpointer 和 `interrupt()` 正好把这几件事做在了底层：人工介入是
一次中断 + 一次 `Command(resume=...)`，进程重启后仍能从断点继续；`aget_state_history()`
直接给出每一步的状态快照。自己实现这套语义的成本远高于接一个框架。

**Agent 内部的工具审批不会重复计费。** `interrupt()` 会让整个节点重放，
朴素实现会把之前的模型调用再跑一遍。Agent 节点里的模型调用和工具执行都包在
LangGraph 的 `@task` 里，结果进 checkpoint，重放时直接取缓存。

**事件流是唯一的可视化数据源。** 节点通过 `get_stream_writer()` 发事件，runner 转成
`RunEvent` 落库并广播。画布高亮、token 流、工具卡片、时间线全部由同一份事件驱动，
所以刷新页面或中途接入都能拿到完整过程（WebSocket 先补历史再接实时）。

**沙箱不用容器。** 跑一段不可信代码不需要一整套容器运行时——操作系统自己就有
内核级的强制访问控制。macOS 用 Seatbelt（`sandbox-exec`，系统自带），Linux 用
bubblewrap（几百 KB 的二进制）。冷启动 ~25ms，对比容器方案的 ~250ms，且不用装任何东西。

守住的是三件事：**默认断网**、**家目录不可读**、**只有工作区可写**。策略由内核强制且
对子进程继承——沙箱里 `subprocess` 出来的 `cat` 读家目录一样是 `Operation not permitted`。
解释器刻意用 `sys.base_prefix` 下那个干净的 Python，而不是后端自己的 venv，
所以沙箱代码 import 不到 FastAPI、SQLAlchemy 和凭据处理相关的任何东西。

**和容器比，少了什么要说清楚**：Seatbelt 做的是访问控制而非虚拟化——进程表是共享的
（能看到宿主机进程列表），代码以当前用户身份运行（不像容器会降到 nobody），
而且 **macOS 不强制 `RLIMIT_AS`，内存用量限不住**（实测设 256MB 仍能分配 900MB）。
CPU 时间、单文件大小、墙钟超时这三项有效。bubblewrap 那边多隔离了 PID/IPC/挂载视图，
内存限额也真实生效。要更强的隔离（内存配额、完整虚拟化），该上的是 gVisor 或 microVM，
而不是回到容器。

写 SBPL 策略有个坑：`(deny default)` 会让 Python 直接 SIGABRT 起不来——要枚举的路径和
syscall 太多，漏一个就崩。所以用的是「默认允许 + 精确拒绝」，只把那三件事收紧。

**检索为什么是混合的。** 默认 embedding 是本地特征哈希，不联网不下模型，零配置可用，
但语义泛化弱；BM25 补上精确关键词匹配这一半。两者各自归一化后加权，权重在界面上可调，
命中结果会分别显示语义分和关键词分，方便调参。配了 OpenAI Key 可切换成真 embedding。

**安全边界。** 分支条件用 AST 白名单求值器而不是 `eval`；HTTP 工具解析域名后逐个 IP
检查，拦截内网、回环和云元数据地址，且不跟随重定向（逐跳重新校验）；文件工具的路径
`resolve()` 后必须仍在工作区内；API Key 用 Fernet 加密落库，只回掩码给前端。

## 常见问题

**沙箱用的是哪个后端？** 设置页「运行环境」会列出所有候选及其可用性，并标出当前选中的那个。
macOS 上应该是 `seatbelt`；Linux 上装了 `bwrap`（`apt install bubblewrap`）就是 `bubblewrap`，
没装则降级到 `local`——**那条路径没有任何访问控制**，界面上会明确标红。
可以用 `AGENTLAB_SANDBOX_BACKEND` 强制指定。

**模型返回空内容？** Claude 4.6 之后的模型默认开着 thinking，`max_tokens` 给小了会出现
「思考完就没额度写正文」。节点里把 max_tokens 调大，或把思考模式设为关闭。时间线里会有提示。

**中转网关报 401？** 有的网关只认 `Authorization: Bearer`，且多带一个 `x-api-key` 就会拒。
在 provider 设置里勾上「用 Authorization: Bearer 认证」。

**端口冲突？** 前端默认 5273、后端 8000，用 `AGENTLAB_WEB_PORT` / `AGENTLAB_PORT` 改。

**数据在哪？** 全在 `data/`：`agentlab.db` 业务数据、`checkpoints.db` 执行断点、
`workspace/` 沙箱文件、`.secret_key` 加密密钥。删掉 `data/` 就是恢复出厂设置。

## 冒烟测试

```bash
node scripts/e2e-check.mjs      # 开浏览器跑一遍：打开画布 → 选模板 → 运行 → 看高亮
```