> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 工作流与运行记录

> 理解 Workflow、Run、Action 和 Wait，并按运行结果选择下一步操作。

一个 **Workflow** 定义允许执行的步骤与转移。一个 **Run** 保存某次运行的输入、状态、动作、等待和证据。同一工作流可以有多个互相独立的 Run。

## 核心对象

| 对象 | Agent 平台需要做什么 |
| - | - |
| Workflow | 定义身份、版本、入口、步骤和允许的转移 |
| Run | 保存并使用同一个 Run ID 继续运行 |
| Action | 领取当前动作，调用真实 Agent 平台能力，回传原动作的结果 |
| Wait | 展示提案，取得用户决定或所需证据，再提交当前等待 |
| Store | 原子保存运行记录，防止并发结果互相覆盖 |

修改工作流定义时使用新版本，并保留活动 Run 引用的定义。编辑说明文字、改状态 JSON 或填写“完成”不能替代合法转移。

## 定义你允许执行的路径

```js theme={null}
import { defineWorkflow, skill, approval, tool } from '@rpamis/comet/runtime';

const workflow = defineWorkflow({
  id: 'report',
  version: '1',
  entry: 'draft',
  steps: {
    draft: skill({ ref: 'draft' }),
    approve: approval({ proposalFrom: 'draft' }),
    publish: tool({ ref: 'publish' }),
  },
  transitions: [
    { from: 'draft', to: 'approve' },
    { from: 'approve', to: 'publish', on: 'approved' },
  ],
});
```

`entry` 是启动时就绪的步骤，`steps` 的键是图中步骤名称，`ref` 是执行器处理函数名称。`transitions` 声明允许的后续路径。多个步骤可以调用同一个处理函数，但各自保留独立的执行记录。

将 `workflow` 传入 `createRuntime`，使用固定 `id/version` 启动 Run。完整可运行示例见 [快速接入](/zh/sdk/quickstart.md)。

## 读取推进结果

调用 `runUntilBlocked` 后，优先读取 `reason`，再读取对应动作、等待和业务输出。

| reason | 你应做什么 |
| - | - |
| `completed` | 读取业务输出，判断所选路径的结果。 |
| `approval-required` | 展示当前提案并接收用户决定。 |
| `evidence-required` | 收集并提交当前证据等待要求的材料。 |
| `executor-required` | 注册能处理当前动作的执行器。 |
| `action-in-flight` | 查询原执行者，等待原动作回报。 |
| `execution-unknown` | 核对原操作结果，再恢复。 |
| `failed` | 查看原 Action 和错误，处理已知失败。 |
| `action-limit` | 本次动作预算已用完；读取进度后决定是否继续。 |
| `cancelled` | 停止推进，核对已经发生的操作和停止证据。 |
| `idle` | 查看就绪步骤、合流条件和子 Run，确认当前没有可执行动作的原因。 |

`inspect` 读取记录，不调用模型或工具。业务 UI 应同时显示当前 Run、待处理 Action/Wait 和最后一次错误，方便用户选择继续、审批或核对。

## 定义步骤

从 `@rpamis/comet/runtime` 导入 `defineWorkflow`，或像 [快速接入](/zh/sdk/quickstart.md) 一样使用工作流定义对象。

| 助手 | 声明的工作 |
| - | - |
| `skill` | 由 Agent 平台加载并执行 Skill |
| `tool` | 调用 Agent 平台提供的工具或本地业务函数 |
| `approval` | 等待当前提案的用户决定 |
| `evidence` | 等待声明的证据 |
| `childWorkflow` | 启动并关联子工作流 |

步骤间的依赖决定什么时候可以派发。并行步骤可以按不同顺序完成；合流条件必须明确。循环和分支沿已声明的转移执行，不能通过处理函数跳到图外。

## 执行器与结果

`createRuntimeExecutor` 按步骤 `ref` 注册具名处理函数。`defineRuntimeHandler` 先解析输入，再交给业务函数执行，避免在一个大函数中按步骤名分派。

已有平台需要自行领取和回报时，可以使用 Runtime 的 `claim`、`recordOutcome` 和 `retry` 接口。保留当前 Action 的身份、attempt、输入摘要和领取凭据，回报必须属于这一次执行。

成功结果还会经过输出 Schema 和业务验证器检查。已知失败直接记录为失败结果；已经派发、但执行器抛错或结果回传中断时，操作可能已经发生，按未知结果处理。完整恢复规则见 [恢复与未知结果](/zh/sdk/recovery.md)。

## 用户等待

审批决定绑定 Wait ID 和当前提案摘要。提案变化后，需要重新展示并确认。旧批准、另一次激活的批准或执行器伪造的批准，不能授权当前动作。

证据等待由 Agent 平台提交实际证据，Runtime 校验其归属和声明条件。步骤结束、证据通过和外部服务确实完成是不同事实，业务界面应分别显示。

## 存储与 Agent 平台职责

`createMemoryRuntimeStore` 适合不需要跨进程恢复的试验。`createFileRuntimeStore` 将 Run 保存在你指定的目录，新进程注册相同定义和执行器后可以继续运行。

Runtime 不会自动调用模型、配置 MCP、注入插件上下文或替 Agent 平台取得授权。需要固定 Skill、安装入口、业务文件保护和分发时，使用 [Workflow Application](/zh/sdk/applications.md)。

按功能继续学习：[执行器](/zh/sdk/executors.md)、[并行与合流](/zh/sdk/parallel.md)、[子工作流](/zh/sdk/subworkflows.md)、[业务状态与循环](/zh/sdk/state.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.