mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-15 00:21:58 +00:00
ThearchyHelios
2714890d0d
README.zh-CN.md / README.md 只留：这是什么、为什么用它、主要功能（按领域一行一条，链到文档）、快速开始、部署、文档索引、 开发与测试、许可（原文不动）。原来的每一节按读者和任务分到 17 篇主题文档：ask-data、workflows、evidence、 data-sources（新增：接入数据库、只读保证、上传表格、跨库合并、遮罩列）、data-catalog、tools（新增：工具、审批档位、 能力登记、端点、网络规则——它们管所有工作流，不只应用）、apps、evaluation-and-ledger、schedules（含通知）、deployment、 configuration、postgresql-and-scaling、identity-and-security、architecture、development、upgrade-notes（按时间倒序， 每波先写要做的事）、faq。删掉的只有模块名（api/copilot_gen.py、chat/drive.py、data/schema_view.py）、重复的话和 「以前…现在…」的叙述；操作步骤、命令、配置名、限制、权限边界都有归宿。中文是原文，英文按新的中文写；英文里界面文字 只写英文名，开头注明界面目前只有简体中文，中文占位符换成英文占位符，中文数字的例子改成不依赖中文的说法。 数据剖析可以同时剖析 2–3 张表（baf23998）收进 data-catalog。 新增 scripts/check-docs.py：英文文档（README.md、docs/en/**）不许有中日韩字符和全角符号（代码块也算）， README、docs/**、deploy/README.md 的相对链接和锚点都要通，docs/zh-CN 与 docs/en 文件一一对应、标题层级相同。 中文提示里指向 README 章节的地方改指新文档：cluster/guard.py、cluster/version.py、db/base.py 两处报错， data/schema_view.py 文档串，.env.example 三处，scripts/prod.sh、scripts/test-postgres.sh，terms.ts 两处、 DataSourcesTab.tsx、check-manage.mjs 注释，deploy/README.md 三处链接。deploy/agentlab.env 未动。 验收：check-docs 0 问题（英文文档 18 个 0 处中文，相对链接 369 条 0 断链，18 对标题层级一致）；相关后端测试 117 通过、7 跳过；tsc -b、check-copy 通过。
239 lines
16 KiB
Markdown
239 lines
16 KiB
Markdown
[English](../en/workflows.md) | 简体中文
|
||
|
||
# 工作流
|
||
|
||
这篇讲在画布上搭工作流：节点怎么连、数据怎么传、人工节点和 agent 的规则、怎么发布，以及运行和断点续跑。给搭建者看。
|
||
|
||
## 画布
|
||
|
||
在画布上拖拽节点、连线。运行时：
|
||
|
||
- 节点实时高亮，边上的光点表示数据流向，卡片里直接显示流式 token。
|
||
- 底部的航迹把各节点的起止和并行度排在一条时间轴上，实时和回放共用。
|
||
- 右栏是运行步骤，和画布读同一份事件流。
|
||
- 多 agent 节点在卡片里展开协作矩阵：谁在跑、几个人并行、省下多少时间。
|
||
- 分支节点跑完会点亮命中的出口、压暗其余。实际走过的边留在画布上，就是这一次的执行路径。
|
||
|
||
### 动效表示什么
|
||
|
||
画布上每个会动的东西都对应一件真实发生的事：
|
||
|
||
| 动效 | 表示 |
|
||
|---|---|
|
||
| 边框上转一圈光弧 | 节点正在跑 |
|
||
| 扫描线扫过 | 正在产出 |
|
||
| 绿色扫一遍 | 刚跑完 |
|
||
| 抖动 | 刚失败 |
|
||
| 琥珀色呼吸 | 在等人 |
|
||
| 边上的光点 | 数据正从这边流向那边 |
|
||
|
||
协作矩阵的花名册固定不重排；被派出去的人亮起来并显示当前任务；条形长度按「这一轮里最慢的那个人」归一化，所以墙钟时间等于最长那条；页脚给出并行一共省下多少。
|
||
|
||
系统关掉动效时（`prefers-reduced-motion`），光效整体不绘制。这时「谁在跑」由实心圆点和「进行中」三个字表示。
|
||
|
||
### 自动排版
|
||
|
||
- 按拓扑分层：并行的支路落在同一列，层内按中位数启发式排序，减少交叉。
|
||
- 分支节点的出口按 yes/no 的声明顺序自上而下排。
|
||
- 循环的回边不参与分层，否则循环体会被压到循环节点左边。
|
||
- 每条线有自己的竖直车道：扇出、汇聚的线不叠在同一段上，跨层的长边从没有节点的空档绕过去（做法见[架构](architecture.md#连线走线)）。
|
||
|
||
### 内置模板
|
||
|
||
内置 9 个模板，从「最小问答」到「可追溯周报」。它们可以直接运行，也是各类节点用法的可执行文档。
|
||
|
||
## 节点类型
|
||
|
||
| 分类 | 节点 | 说明 |
|
||
|---|---|---|
|
||
| 起止 | `input` `output` | 声明输入字段 / 收集结构化成果 |
|
||
| 模型 | `llm` `agent` `supervisor` `report` | 单次调用 / 带工具循环 / 多 agent 协作 / 报告撰写（只写引用标记，数字由系统填） |
|
||
| 执行 | `tool` `code` `merge` | 直接调用工具 / 沙箱内执行代码 / 合并几次查询的结果（跨库按键对齐） |
|
||
| 控制 | `branch` `loop` `subgraph` | 条件或语义分支 / 遍历与条件循环 / 嵌套工作流 |
|
||
| 上下文 | `memory` `retrieve` `transform` | 长期记忆读写 / 知识检索 / 数据整形 |
|
||
| 把关 | `human` `validate` `metrics` | 人工介入 / Schema 校验与自动返工 / 口径卡 |
|
||
|
||
`output` 节点按 JSON Schema 校验结构化成果，不合格时把错误交回模型自动返工。`metrics`（口径卡）和 `report`（报告撰写）见[证据与出具](evidence.md)；`merge`（合并查询）见[数据源](data-sources.md#跨库合并)。
|
||
|
||
## 节点之间怎么传数据
|
||
|
||
用模板语法引用别的节点的产出：
|
||
|
||
```
|
||
{{ input.question }} 入口输入
|
||
{{ vars.answer }} 某节点 assign_to 写入的变量
|
||
{{ nodes.n1.text }} 指定节点的输出
|
||
{{ vars.items | json }} 过滤器：json / compact / upper / length / first …
|
||
```
|
||
|
||
### 条件和表达式不是模板
|
||
|
||
分支条件、while 循环条件、整形表达式、口径卡指标、跳过条件这几处直接求值，变量直接写：`vars.gate != 'ok'`、`len(vars.items) > 0`。
|
||
|
||
- 多套了 `{{ }}` 时意思没有歧义，照 `vars.gate` 理解，只给一条提示。
|
||
- 下面这些写法在校验阶段就拦下，不会等跑到那一步才报错：`| length` 这类过滤器（改写成 `len(x)`）、`{'a', 'b'}` 集合（改用列表）、不认识的函数、把 `==` 写成 `=`、引号里的 `{{ }}`（它不会被渲染，条件永远不成立）。
|
||
- 校验、助手自查和运行时用同一个解析器，不会出现「校验说能跑、跑起来报错」。
|
||
- 求值器只认 AST 白名单里的写法，不用 `eval`。
|
||
|
||
### 代码节点的结果要 print 出来
|
||
|
||
`assign_to` 拿到的是 stdout。脚本最后一行写个裸表达式不会输出（自动显示是 notebook 的行为），变量会是空的。
|
||
|
||
- 要交给下游一个对象，写 `print(json.dumps(结果))`。stdout 是 JSON 时自动解析成对象。
|
||
- 设了 `assign_to`、却找不到任何输出的 Python 代码，校验直接拦下。
|
||
- 代码在沙箱里执行。每个代码节点可以单独选隔离档位：strict 是 microVM，fast 是系统沙箱（见[身份、权限与安全](identity-and-security.md#代码沙箱)）。
|
||
- bubblewrap 沙箱不继承后端的环境变量，代码里读不到模型的 API Key、数据库地址这类变量。代码要用的值请显式传进去。
|
||
- `evidence_role` 区分 `source`（取数）和 `compute`（计算，默认）。沙箱算出来的数不能被报告直接引用，要进口径卡（见[证据与出具](evidence.md#取数链路)）。
|
||
|
||
## 并行与汇合
|
||
|
||
- 一个节点连出多条边就是扇出，几条支路并行执行。
|
||
- 多条边汇入同一个节点时自动等待汇聚：汇合节点等图里其余待执行的任务都跑完，再执行一次。支路一长一短也不会触发两遍。
|
||
- 分支之后的二选一汇合，不会去等没走的那条。
|
||
- 代价：汇合节点也会等图里和它无关、恰好还在跑的支路。
|
||
|
||
## 人工节点
|
||
|
||
`human` 节点让执行暂停并落盘，人做出决定后沿对应出口继续。
|
||
|
||
|
||
|
||
- 人可以批准、驳回或改稿，之后从断点继续。进程重启不丢状态。
|
||
- 可以派给岗位、发起人或按表达式算出的人。岗位是图里写的名字，在应用里绑定到人或组（见[应用](apps.md#流程与待办)）。
|
||
- 会签：任一人同意、全体同意（一票否决），或至少 m 人同意。
|
||
- 可以设时限，超时提醒、升级或按驳回处理。
|
||
- 表单可以由上游 Agent 拟定。
|
||
- 永远不会自动批准。只认明确的批准（`true` / 同意 / approve），看不懂的回复一律按拒绝处理。
|
||
|
||
除了审批，人工步骤还有：补充输入、编辑稿件、动作确认、代码和工具审批、双盲裁决。
|
||
|
||
### 驳回
|
||
|
||
驳回是人的决定，不是故障：
|
||
|
||
- 运行记为「已取消 · 被驳回」，不算失败、不重试，也不能继续运行。通知走「实例结束」，定时任务推「未出具（被驳回）」。
|
||
- 配了失败重试或「出错时继续」的关卡，驳回后不重问，也不接着往下走。
|
||
- 被驳回的那一步，`node.failed` 事件带 `reason: "rejected"`（和 `run.cancelled` 同一个字段）。画布、航迹、时间线、问数据过程都画成「被驳回」。读事件的外部系统按 `reason` 区分。
|
||
|
||
审批、补充输入、编辑稿件、动作确认、代码和工具审批、双盲裁决都可以多接一个「驳回」出口：
|
||
|
||
- 驳回（包括超时驳回）后，这一步正常结束，沿驳回出口往下走。运行照路径结束，`run.finished` 带 `rejected_via`。
|
||
- 动作确认走驳回出口时，什么都不发出去。
|
||
- 实例页和通知写「被驳回，转到 X」。待办、通知、Webhook 里照实写驳回的去向（「被驳回，转到 X」「这一路到此为止」），子工作流里的写「子工作流 › x」。
|
||
- 不接驳回出口时，照旧记「已取消 · 被驳回」。
|
||
- 发布检查拦下走不到结束的驳回路径。
|
||
|
||
## Agent 节点
|
||
|
||
`agent` 节点是一个带工具的模型循环，能用哪些工具由节点上的白名单决定（见[工具](tools.md)）。配了 `output_schema` 的 agent 可以打开 `cite_fields`，让每个字段标出取自哪次查询的哪一格（见[证据与出具](evidence.md#取数链路)）。
|
||
|
||
### 护栏
|
||
|
||
护栏代替固定步数，防四件事：
|
||
|
||
- **循环不收敛**：同一个工具、同样的参数第二次不再执行，把上次的结果交还给它；连续 3 步拿不到新信息就收尾。
|
||
- **花费越滚越大**：每个节点记令牌预算（默认 200 万）和金额预算（默认不限），都可以在「设置」里改成不限。
|
||
- **上下文会满**：用到窗口的 60% 先压缩早期的工具结果，到 85% 就收尾。
|
||
- **真正失控**：步数只留兜底，默认 100，在设置里改，`AGENTLAB_MAX_AGENT_STEPS` 封顶。
|
||
|
||
临近任何一个上限，先提醒模型一次。上限在运行发起时快照，恢复和接着跑沿用同一份：审批恢复时节点整个重放，上限一变，循环停的位置就和断点对不上。
|
||
|
||
下游结构化校验失败时，报错写明是上游哪个 agent 提前收了尾。agent 提前收尾时，时间线里也有一条提示写明原因。
|
||
|
||
agent 内部的工具审批不重复计费：审批恢复时节点重放，之前的模型调用和工具执行直接读断点里的结果（见[架构](architecture.md#选用-langgraph)）。
|
||
|
||
### 多 Agent 协作
|
||
|
||
`supervisor` 节点里，调度者按进展把任务分派给多个专家。它属于探索层能力，受管级发布禁用。
|
||
|
||
|
||
|
||
协作团队的成员停不下来等人：需要确认的调用不执行，并告诉成员换一种做法。
|
||
|
||
## 子工作流
|
||
|
||
`subgraph` 节点嵌套另一个工作流。
|
||
|
||
- 子工作流固定的版本须已发布且未退役。
|
||
- 子工作流里的每一步进同一个运行的事件流：时间线、记录页会出现「子工作流 › 那一步」；封存也包含子工作流查过的数。
|
||
- 子工作流出口的字段带着出处回到父图，父图的口径卡和报告能一路追到子工作流里的那一格，最多 3 层。子工作流里有追不到原始数据的，父图照样降档。
|
||
- 子工作流里的报告按带前缀的节点 id 记，父图只认自己的报告。
|
||
- 放在循环里多次执行时，每次的步骤接着编号。写外部系统的幂等键用父运行里的全局 id，所以循环每一轮的写入都照常发送。
|
||
|
||
## 知识库、记忆与 Skill
|
||
|
||
- **知识库**：向量 + BM25 混合检索、倒排索引、可选模型重排；能解析 PDF / Word / PowerPoint / HTML / Markdown。两种得分各自归一化后加权，权重在界面上可调，命中结果分别显示语义分和关键词分。为什么要混合、实测效果见[架构](architecture.md#为什么检索是混合的)。
|
||
- **向量模型**：默认是本地特征哈希，不联网、不下载模型、零配置，但语义泛化弱。可以接任意 OpenAI 兼容端点（LM Studio、Ollama、vLLM、TEI）。维度靠实际探测，不按模型名推断。
|
||
- **长期记忆**：跨运行读写，自动去重；助手建图时主动记录应当记住的事实。
|
||
- **Skill**：把方法论做成可复用的单元，挂到节点上，注入 system prompt。
|
||
|
||
Excel / CSV 作为数据源上传，会变成可以用 SQL 查的表；放进知识库只能被切块检索（见[数据源](data-sources.md#上传表格)）。
|
||
|
||
## 发布与版本
|
||
|
||
### 发布级别
|
||
|
||
工作流有两个发布级别：已发布和受管。
|
||
|
||
- 发布出去的是不可变版本，按图哈希固定。发布后再改画布，不影响已发布版本。
|
||
- 以已发布级发布：搭建者以上。以受管级发布、把受管工作流降为已发布、让版本退役：只有管理员。
|
||
- 子工作流、口径卡固定的版本，须已发布且未退役。
|
||
- 受管级发布要通过治理检查：禁用 `supervisor`（全动态的协作属于探索层）；方法卡必须钉版本；agent 不得关闭全部审批；`output` 必须配置出具契约；另有证据门禁 G1–G5。
|
||
|
||
### 证据门禁
|
||
|
||
受管级别在治理检查之外加了证据门禁。门禁只看图和配置，让「每个数都点得开」在结构上成立：
|
||
|
||
- **G1** 带契约的出口，成果字段的文字只能来自报告撰写节点。
|
||
- **G2** 模型写的文字不绕过报告撰写节点直接流进出口。
|
||
- **G3** 报告撰写节点写明 `numbers: strict`、`on_violation: fail`、`claims: require_citation`（或 `judge`，并写预算）。
|
||
- **G4** 口径卡的输入不来自计算角色的沙箱代码。
|
||
- **G5** 给口径卡供数的 agent 配 `output_schema` 并开 `cite_fields`。
|
||
|
||
受管级别下这些是错误，挡住发布；已发布级别只给警告。已经发布的版本照常运行，下次发布时按新规则检查。
|
||
|
||
### 发布前检查与修复
|
||
|
||
- 打开发布弹窗就先跑一遍发布前检查（`POST /api/workflows/{id}/publish-check`，和真正发布同一套标准）。问题面板里平时也看得到。
|
||
- 修复（`/autofix`）分三类：答案唯一的，一键修复；要人拿主意的，给选项，不替人选；结构性的，交给助手。
|
||
- 一律先预览，不自动保存，也不自动发布。
|
||
- 降低要求的改动一律拒绝：删节点、删契约、放宽审批、关掉 strict、改级别。助手的方案也要过这一关。应用修复后重跑检查，错误必须变少，不能冒出新的。
|
||
- 老工作流一键升级为可追溯结构（`POST /api/copilot/upgrade-evidence`），过的也是这道检查（见[证据与出具](evidence.md#旧运行与一键升级)）。
|
||
- 发布检查还会拦下：走不到结束的驳回路径；工具清单里有写入能力的 Agent 和多 Agent 协作。停在 Agent 半路审批的实例升级后无法继续，所以发布时 `process.wait_mid_agent` 会提醒。
|
||
|
||
### 从探索到模板
|
||
|
||
- 画布试跑自动标记为探索运行，结果不进正式归档。
|
||
- 「提取模板」把跑通的路径沉淀为草稿：只保留实际执行的节点，剪掉没走的分支。人工审核后再发布。
|
||
- 探索问题聚类提示哪些追问应当固化为模板里的一节。
|
||
- 工具白名单衰减报表（`/api/governance/tool-usage`）列出「已授权但从未使用」的工具，作为收缩权限的依据。
|
||
|
||
## 运行
|
||
|
||
### 正式运行与探索运行
|
||
|
||
- 正式运行只从已发布、未退役的版本发起，进正式归档；画布试跑是探索运行。
|
||
- 每次运行记下来源（问数据、画布、定时任务、应用入口、外部系统……），写在 `run.origin` 事件里，在封存范围内。用访问密钥发起的，记下是哪把密钥。
|
||
- 写外部系统时，正式运行走生产环境，探索运行走测试环境（见[应用](apps.md#写外部系统)）。
|
||
|
||
### 断点续跑
|
||
|
||
- 失败的运行可以从失败节点继续，已完成的节点不重复执行。
|
||
- 探索运行允许修改节点配置后继续，但拓扑必须一致；正式运行固定在发布的版本上，不能改配置后继续。
|
||
- 继续运行不改发起人。
|
||
- 服务重启后（包括开发时改后端代码触发的热重载），正在跑的运行显示中断、断点完好：在运行详情页点「接着跑」，跑完的节点不会重跑，后面的人工审批照常停下来等人。
|
||
|
||
### 时限与步数
|
||
|
||
- 单次执行（两次人工介入之间的那一段）默认最多 600 秒（`AGENTLAB_MAX_RUN_SECONDS`）。
|
||
- 单次模型调用默认 300 秒没有输出即超时（`AGENTLAB_MODEL_TIMEOUT_SECONDS`）。
|
||
- 图的步数上限是 `AGENTLAB_MAX_GRAPH_STEPS`（默认 200）。循环按自己 `max_iterations` 声明的轮数另算步数预算，不受这个上限约束。
|
||
- 当前值在「设置 → 运行环境」里看得到。
|
||
|
||
### 运行记录与成本
|
||
|
||
- 全部事件落库，可以回放。
|
||
- 逐节点记耗时、token 用量和按目录价折算的成本。被取消、超时的模型调用也记一次调用，标「未完成」。
|
||
- 评测、口径对账、口径召回是系统代为发起的运行：证据照常可查，但不进使用统计（探索问题聚类、工具白名单、目录使用次数）。记录页默认不列它们，并写明有几次没列出。
|
||
- 运行详情页可以一键核对封存（见[证据与出具](evidence.md#封存与核对)）。
|