# 术语表（TERMINOLOGY.md）

本表是《Loop Workflow 企业应用指南》全书的**唯一术语来源**。术语优先级高于 `STYLE.md` 与单章约定。作者在正文使用任何核心名词前，必须先查本表；本表未覆盖的概念，先在此补条目并通过 Review，再用于正文。

权威依据：`specs/workflow/agentteam-workflow-platform.md`（living-spec）与主仓 `internal/workflow/**`、`internal/store/workflow/run/**`、`web/src/agentteam/workflow/**` 的当前代码。

## 如何使用本表

- 面向读者的正文统一使用“规范中文 / 规范英文”两列的写法；二者等价，一章内择一并保持一致。
- 涉及代码与原理时，在首次出现处用括注标出代码名，例如“工作流（Workflow，代码名 `Plan`）”。
- 凡列于“禁用 / 旧称变体”的写法，全书不得用于正文（仅可在解释“为什么不用它”时引用）。
- 代码标识符（结构体、字段、枚举值、YAML 键、API 路径）保留源码原样的英文大小写，不翻译、不重排。
- 本表与正文可交叉校验：见文末“可检查”。

---

## 0. 命名双轨制（最重要的约定）

Loop Workflow 存在有意的“代码名 / 用户名”双轨。同一对象在代码原理章用代码名，在操作案例章用用户名，二者指同一个东西。

| 规范中文 | 规范英文（UI） | 代码名 | 禁用 / 旧称变体 |
| --- | --- | --- | --- |
| 工作流 | Workflow | `Plan` | 把用户面的 Workflow 与代码面的 Plan 视作两个对象；使用“流程定义/Flow/App”等自造词 |
| 触发器 | Trigger | `Binding` | 把 Trigger 与 Binding 视作两个对象；称“调度器/Scheduler/监听器” |
| 调用 | Invocation | `Invocation` | 称“执行实例/Execution（作运行对象时）” |
| 运行 | Run | `Run`（读模型 `WorkflowRunRecord`） | 称“执行/Execution/RunRecord（作对象名时）” |

> 全书规则：面向读者一律用“工作流 / Workflow”“触发器 / Trigger”“调用 / Invocation”“运行 / Run”；讲到持久化、版本、编译时再括注代码名 `Plan`/`Binding`。

---

## 1. 四个一等对象（first-class objects）

Workflow 领域有且仅有四个一等对象，链路为 `Plan → Binding → Invocation → Run`。

| 规范中文 | 规范英文 | 代码符号 | 禁用 / 旧称变体 | 释义 |
| --- | --- | --- | --- | --- |
| 工作流 | Plan（UI: Workflow） | `planmanage.Plan` | “流程/Flow”作对象名 | 可复用的编排逻辑及其版本历史。含一个可变 `Draft` 与若干不可变 `PlanVersion` |
| 触发器 | Binding（UI: Trigger） | `bindingmanage.Binding` | “调度器/Scheduler”作对象名 | 可选的持久化部署，用于按计划产生 Invocation |
| 调用 | Invocation | `invocation.Invocation` | “执行实例” | 一次被接受的、不可变的发生记录 |
| 运行 | Run | `runstore.Run`；TS `WorkflowRunRecord` | “Execution”作运行对象 | 执行某次 Invocation 快照的运行实例 |

辅助快照（非一等对象，正文按需引用）：`Draft`（Plan 的唯一可变服务端草稿）、`PlanVersion`（不可变发布版本）、`BindingRevision`（不可变触发器版本）。

---

## 2. 图与运行结构

| 规范中文 | 规范英文 | 代码符号 | 禁用 / 旧称变体 | 释义 |
| --- | --- | --- | --- | --- |
| 节点 | Node | `plan.Node` | “步骤/Step”作类型名 | 图中的一个编排单元，恰好属于一种节点类型 |
| 激活 | Activation | `runstore.Activation`；`run.Activation` | “步骤/Step/执行步” | 运行时对某个节点的一次访问（一个节点可被激活多次） |
| 边 | Edge | `plan.Edge` | “连线/Transition（作图边时）” | 图中连接两个节点端点的有向边 |
| 入口 | Entry | `plan.Entry` | “起点/Trigger 节点” | 把输入注入到某节点端口的有类型入口 |
| 迁移 | Transition | `run.Transition` | 与图边 Edge 混用 | 归约器输出：`State + Intents + Events` |
| 意图 | Intent | `run.IntentKind` | “动作/Action” | 运行时希望产生的副作用类型 |
| 效果 | Effect | `runstore.Effect` | “动作/Action” | 持久化的外部工作项（出箱），由分发器投递 |

> 关键：**没有“Step / Action”类型**。运行时访问节点叫 Activation；运行时要做的外部工作叫 Intent（意图），落库的副作用项叫 Effect（效果）。全书不得把节点叫“步骤”，也不得用“Action”指代节点或效果。

---

## 3. 节点类型（NodeType，共 10 种）

节点类型枚举见 `plan.NodeType`。**全书出现的任何节点都必须是下表之一**，不得自造。

| 代码值 | UI 英文 | UI 中文 | 类别 | 禁用变体 |
| --- | --- | --- | --- | --- |
| `send_message` | Send Message | 发送消息 | 动作 | “LLM 节点/Agent 节点/HTTP 节点/消息动作” |
| `set_variable` | Set Variable | 设置变量 | 动作 | “赋值节点” |
| `wait` | Wait / Timer | 等待 / 计时器 | 等待 | “延迟/Delay 节点” |
| `request_approval` | Request Approval | 请求审批 | 等待 | “审批节点/Approval 节点/human 节点” |
| `switch` | Switch | 条件路由 | 控制 | “条件分支/Condition/If 节点” |
| `fork` | Fork | 并行分叉 | 控制 | “并行/Parallel 节点” |
| `fan_out` | Work item fan-out | WorkItem 扇出 | 控制 | “循环分发/ForEach 节点” |
| `join` | Join | 并行汇合 | 控制 | “合并/Merge 节点” |
| `loop` | Loop | 循环 | 控制 | “迭代器/Iterator 节点” |
| `end` | End | 结束 | 终止 | “终止/Terminate 节点” |

> 关键：**没有“LLM/Agent 调用”节点、没有“HTTP 请求”节点、没有“子工作流”节点**。需要让 Agent 做事时，用 `send_message` 且 `completion: callback`，向 Agent 发消息并等待回调；见 §6。

节点子枚举（写配置时引用，值须完全一致）：

- `send_message.completion`：`sent` / `callback`
- `switch.mode`：`first_match` / `all_match`
- `join.mode`：`all` / `any`
- `fan_out.failureMode`：`collect`
- `loop.mode`：`counted`（v1 仅支持计数循环）
- `end.outcome`：`succeeded` / `failed`（`failed` 可带 `code`）

---

## 4. 触发与调用来源（Source）

工作流的调用来源有且仅有两种（`invocation.SourceKind`）：

| 规范中文 | 规范英文 | 代码值 | 释义 |
| --- | --- | --- | --- |
| 手动 | Manual | `manual` | 直接对 Plan 发起一次 Invocation，不经过 Binding |
| 计划 | Schedule | `schedule` | 由 Binding 按计划自动产生 Invocation |

Binding 的计划模式（`binding.ScheduleMode`）：

| 规范中文 | 规范英文 | 代码值 |
| --- | --- | --- |
| 定时表达式 | Cron | `cron` |
| 间隔 | Interval | `interval` |
| 绝对时间 | Absolute | `absolute` |
| 相对延时 | Relative | `relative` |

> 关键：**不存在 webhook、消息、GitHub/Gitea、Task board 等事件触发**。这些来源在规范中被显式判为非法，不是别名。案例若涉及“代码托管有新提交时触发”，必须改写为“由外部系统/Agent 发起一次手动调用”，不得写成事件触发器。

调用来源的执行者类型（`invocation.ActorType`）：`human`、`agent`。

---

## 5. 状态枚举（拼写以代码为准）

Run 状态（`run.Status`）。**注意 `canceled` 为单 L 拼写**。

| 规范中文 | 规范英文 | 代码值 |
| --- | --- | --- |
| 已入队 | Queued | `queued` |
| 运行中 | Running | `running` |
| 等待中 | Waiting | `waiting` |
| 成功 | Succeeded | `succeeded` |
| 失败 | Failed | `failed` |
| 已取消 | Canceled | `canceled` |

终态：`succeeded` / `failed` / `canceled`。

> 关键：**没有 `timed_out`、没有 `waiting_approval` 状态**。等待审批、等待回调、等待计时器，统一表现为 `waiting`。

<!-- checker-forbid: timed_out -->
<!-- checker-forbid: waiting_approval -->

其余层级状态（正文按需引用，值须一致）：

- 激活状态 Activation：`ready` / `waiting` / `succeeded` / `failed` / `canceled`
- 效果状态 Effect：`pending` / `dispatching` / `delivered` / `awaiting` / `queued_for_agent` / `completed` / `failed` / `canceled`
- WorkItem 状态：`pending` / `running` / `succeeded` / `failed` / `blocked` / `canceled`
- 审批决定：`approved` / `rejected`

> 拼写规则（两套，按域区分，均以代码为准）：
> - **Run / Activation / Effect / WorkItem 状态**用单 L 的 `canceled`。
> - **审批域**用双 L 的 `cancelled`：通用审批 `approval.StateCancelled`（即 `Instance.State`）与团队工作流发布审批的 `ApprovalOutcomeCancelled` 均为双 L。
> - `TeamWorkflowApprovalState`（双 L）只是前端 TS 类型（`web/src/agentteam/workflow/api/workflowPlanTypes.ts`），**不是后端符号**；后端审批状态走通用 `approval.State*`。

---

## 6. 外部系统与“调用 Agent”的正确模型

这是全书最容易写错的地方，单独成节。

- **没有 HTTP 节点、没有外部系统节点、没有 Extension 节点。** 不得出现 `type: http`、`type: llm`、`type: extension` 等。
- 工作流与外部世界的唯一边界是 **Effect 出箱**，由分发器投递到两种适配器：**发消息**（`send_message`）与**请求审批**（`request_approval`）。`wait` 是纯计时器。
- 需要让 Agent 执行判断/调用外部系统时：用 `send_message` 且 `completion: callback`，把任务交给 Agent；Agent 完成后以 `callbackOutput` 结构回传，工作流继续。**回传内容必须匹配声明的 `callbackOutput` schema**；不匹配时这次完成请求被拒绝（`ErrCallbackOutputInvalid`），Effect 仍处于 `awaiting`，Agent 可修正后重新提交——**不是**按节点 `retry` 自动重跑。`retry` 只管 Effect 投递失败的重试，不校验回调内容。
- 因此“对接代码托管 / IM / 表格 / 邮件”等外部能力，**由 Agent 承担集成**，工作流只负责编排与审批。案例的“外部系统”槽位应这样描述，不得写成工作流直接调用 HTTP。

| 规范中文 | 规范英文 | 代码符号 | 禁用 / 旧称变体 |
| --- | --- | --- | --- |
| 回调 | Callback | `CompletionCallback` | “HTTP 回传/webhook 回调”作节点机制 |
| 回调输出 | Callback output | `SendMessageConfig.CallbackOutput` | “节点返回值” |
| 响应者 | Responder | `SendMessageConfig.Responder` | “目标 Agent 字段”作正式名 |

---

## 7. 变量、上下文与模板

- **模板语法**：字符串插值用 Mustache 风格 `{{ ... }}`（正则见 `plan/validate.go`）。**不存在 `${ }` 语法**。
- **表达式字段**：`when`、`expr:`、`ref:` 用裸表达式，不加花括号。
- **值表达式 ValueExpr** 三种形态：`ref:`（点分引用，如 `ref: plan.input.channel`）、`value:`（字面量）、`expr:`（表达式语言字符串）。
- **表达式运算符**（`when:`/`expr:` 内）：逻辑 `||` `&&` `!`，比较 `== != < <= > >=`，成员 `in`，函数 `contains` / `startsWith` / `endsWith` / `length`，字面量 `true` / `false` / `null`。**不支持单词形式 `and` / `or` / `not`**——必须用 `&&` / `||` / `!`；写 `or` 会触发 `expression.invalid_condition: unexpected trailing token "or"`。
- **命名空间根**（表达式上下文，基础七根）：`input` / `output` / `state` / `plan` / `loop` / `branches` / `winner`。这七根可用于 `when:`/`expr:` 表达式与 `ref:` 引用。
- **两个作用域限定的直接引用根**（**仅作 `ref:`**，不能出现在 `when:`/`expr:` 表达式中）：`fan_out` 的 item 边绑定里用 `item` 指当前工作项；配对 `join` 的 merge 绑定里用 `items` 指汇总结果（见 `internal/workflow/plan/fan_out_scope.go`、`validate.go`）。

| 根 | 释义 |
| --- | --- |
| `input.*` | 本次 Run 经校验的调用输入 |
| `state.*` | 已声明、有类型的运行态，由 `set_variable` 修改 |
| `plan.*` | Plan 级引用（如图入口 `plan.input.channel`） |
| `output.*` | 节点 / Plan 输出，完成前不可用 |
| `loop.*` | 循环体内可见的迭代状态 |
| `branches` / `winner` | 并行 fork / switch 分支结果，在 `join` 处可见 |
| `item.*` | 仅在 `fan_out` 的 item 分支体内可见，指当前工作项 |
| `items` | 仅在配对 `join` 的 merge 处可见，指 fan_out 的汇总结果 |

> 关键：**不得用节点 id 作为变量命名空间**（如 `{{ classify.severity }}` 是错的）。跨节点传值用 `state` 或边 `bindings`。

类型契约词汇（`plan.ValueType`）：`channel`、`string`、`enum`、`number`、`boolean`、`member`、`duration`、`datetime`、`object`、`array`、`agent`、`scope`，以及编译器拥有的 `work_items`。

- `scope`（对象 `{kind, scopeId}`，kind ∈ `channel|thread|dm|task`）是**现代的可移植身份类型**，新书示例优先使用。
- `channel`（字符串形态）是**兼容旧类型**，仅在与既有fixture对齐时出现。

---

## 8. 审批与人在回路

| 规范中文 | 规范英文 | 代码符号 | 释义 |
| --- | --- | --- | --- |
| 请求审批 | Request Approval | `request_approval`（节点 / Intent / Effect） | 向一个人类成员请求审批；输出端口 `approved` / `rejected` |
| 审批请求 | Approval Request | `orchestrator.ApprovalRequest` | 运行时渲染好的不可变审批单 |
| 审批决定 | Approval Decision | `ApprovalDecision` | `approved` / `rejected`，首决定生效 |

- 节点配置：`requestApproval: {assignee, summary, retry}`。`assignee` 是创作期别名，运行时解析为唯一在岗人类成员。`request_approval` **没有创作期 timeout**——不得写“审批超时升级”；只有 `wait` 节点有 `timeout`。
- 运行时审批状态走通用 `approval` 包：`Instance.State` ∈ `approval.StatePending / StateApproved / StateRejected / StateCancelled`（双 L）；审批决定 `approved` / `rejected`，首决定生效。
- 另有**更高层级的团队工作流发布审批**（独立域，用于发布可复用的团队 Plan）：其关系记录一个 `Outcome`，取值 `ApprovalOutcomeApproved / ApprovalOutcomeRejected / ApprovalOutcomeCancelled`（均双 L），投递到团队所有者的审批收件箱。**不要与运行时 `request_approval` 节点混为一谈**。`TeamWorkflowApprovalState` 只是前端 TS 类型，非后端符号。

---

## 9. 创作面（Authoring）

- **同一份 `loop.plan/v1` 源**，两个等价编辑视图：YAML 编辑器与 ReactFlow 可视化画布，二者经 `workflowSync` 同步。
- YAML 根键（`plan.Document`）：`apiVersion: loop.plan/v1`、`kind: PlanVersion`、`input` / `output` / `state`（均为 `字段 → Schema`）、`graph`（`entry` / `nodes` / `edges`）。
- 顶层 `input` / `output` / `state` 的 Schema 与边的 `bindings` 为 YAML 专属；可视化视图保留并展示，不翻译、不丢弃。
- Plan 生命周期：一个可变 `Draft`（带 ETag/revision 的 CAS 保存）→ `publish` 追加不可变 `PlanVersion` → `current` / `default` 版本角色指针 → `archive` 归档（v1 无硬删除）。`validate` 不改状态；`publish` 总是重新解析与编译。

---

## 10. CLI 与传输（仅澄清命名）

- Loop 提供 `loop exec` 等 CLI 与 Agent CLI 传输（`run.manage` 中的 “Agent CLI transports”），指**运行如何被 CLI / 浏览器调用与取消**的传输方式，**不是**“工作流里调用 CLI 的节点”。
- Loop 存在通用的 Extension Catalog（如 gitea 扩展动作），属于平台级扩展，**不属于 Workflow 领域对象**。第四篇若标题含“Extension”，指的是平台扩展与外部系统能力，而非工作流节点；写正文时以此界定，避免与 §6 混淆。

---

## 11. 版本与编译标记（背景知识）

- `ArtifactVersion` / `CompilerVersion` 默认 `v1`；启用 scope 值编译为 `v2`，Agent workScope/relatedScopes 编译为 `v3`，选定 responders / 数组 relatedScopes / WorkItems / fan_out 编译为 `v4`。
- 旧书示例如无 scope / workScope 特性，保持 `v1` 即可。

---

## 可检查（与 STYLE.md §15.11 对齐）

- 正文出现的核心名词必须能在本表找到规范写法；脚本可基于本表的“规范中文 / 规范英文 / 代码值”列构建白名单做交叉校验。
- 节点类型白名单即 §3 的 10 个代码值；出现其他 `type:` 值即不通过。
- Run 状态白名单即 §5 的 6 个值（`canceled` 单 L）；出现 `timed_out`、`waiting_approval` 即不通过。审批域的双 L `cancelled` 只在审批上下文出现，不得用作 Run 状态。
- 模板插值必须为 `{{ }}`；出现 `${ }` 即不通过。
- 变量命名空间根限定 §7 的基础七根，外加 `fan_out` 体内的 `item.*` 与配对 `join` 处的 `items`（按作用域）；出现以节点 id 为根的引用即不通过。

变更本表时，请在同一提交的 commit message 列出“新增 / 改写 / 新增禁用变体”的条目，并同步 STYLE.md §15.11 的检查器契约。