OpenSeal 智能体架构解析：持久化编排与审批治理

开源 AI 智能体平台层出不穷，但真正能把「任务可恢复、动作可审批、状态可追溯」做扎实的并不多。OpenSeal 用一套显式的持久化执行模型回答了一个核心问题：当一个智能体准备好草稿、需要人工批准后才能发送时，这个任务究竟存在哪里，worker 如何领取下一步，而人在审核期间系统又发生了什么？

本文沿着一个真实任务的生命周期，拆解 OpenSeal 的架构设计，看它如何在模型推理之外构建起一套可靠的编排与治理层。

持久化执行路径：从提示到技能调用

OpenSeal 的主序列是一条清晰的链路：提示或事件 → Agent 或 Team → Objective → Run → Turn → Skill action。

理解这条链路要抓住几个层级的职责划分。Agent 或 Team 拥有一个 Objective，Objective 描述一个期望达成的结果；Objective 产生一个 Run，Run 则以 Turn 为单位逐步推进；当需要调用模型推理之外的能力时，某个 Turn 会触发一个 Skill 动作。

以草稿任务为例：草稿的目标始终保存在 Objective 中，而 Run 记录的是「尝试达成目标」这件事本身。关键价值在于——如果工作必须等待（比如等人审批），你可以随时读取这个 Run 的状态，而不必保持最初那个 API 请求一直挂着。这正是「持久化」的意义：任务脱离了请求连接的生命周期而独立存在。

用租约（Lease）恢复中断的工作

分布式系统最棘手的问题之一是 worker 中途挂掉。OpenSeal 的解法是租约机制。

一个 worker 会在设定时间内「认领」一个 Turn，这个认领就叫做租约（lease）。如果 worker 停止续租，租约到期，该 Turn 就重新变为可领取状态。当某个 worker 任务执行到一半停下时，检查这条租约记录就能定位问题。

每一个阶段在被执行之前都会先行保存，审批等待状态同样被保存，这让「执行」和「审核」拥有了一个跨进程重启也能共存的统一存储位置。

不过 OpenSeal 的文档特别提醒了一个容易被误读的点：不要把它当成对外部工具的 exactly-once 保证。每个 Skill 的副作用和它所调用的服务都需要单独评估。一次合格的重启测试，应当同时检查保存的 Run 状态和外部真实结果——两者都对了，才算真正恢复成功。

租约机制源自分布式系统中的经典问题：如何判断一个工作节点是「正在慢速执行」还是「已经崩溃」。由于无法从外部直接区分这两种情况，租约用时间窗口来代替确定性判断——worker 必须在规定时间内主动续约，否则系统推定其已失效。这与 Kubernetes 中 Pod 的 liveness probe、Zookeeper 的临时节点（ephemeral node）以及数据库行级锁的超时机制在原理上一脉相承。

值得注意的是，租约到期并不意味着任务一定没有被执行——原 worker 可能已完成了部分操作但在写回状态前崩溃。这正是 OpenSeal 特别警示「不对外部工具提供 exactly-once 保证」的根本原因：租约只能保证任务会被再次尝试，无法回滚已产生的副作用。对于发送邮件、扣款等不可逆操作，业务层需要自行实现幂等性检查。

调用路由前先检查能力（Capabilities）

一个很实用的设计细节：两个版本号相同的 OpenSeal 服务，可能暴露完全不同的操作集合。可用的 API 面取决于存储契约、已连接的组件以及完整的配置。

curl http://127.0.0.1:8080/api/v1/capabilities

具体来说，创建 Run 需要 dispatcher；解决审批需要 authorizer；编写 Workforce 则需要完整的模型端点、凭证和模型名称。这里有个重要原则：缺失的能力并非只是在客户端被隐藏，而是对应的操作根本不被服务。

这种设计让一个「瘦客户端」既能对接本地服务，也能对接更大的嵌入宿主。终端客户端只读取服务端声明的能力，并不拥有权威状态——所以关闭客户端，持久化的工作依然在后台运行。

相比之下，health 端点是个更弱的检查手段。它返回固定响应，并不能证明数据库、worker 或模型提供方真的能完成你的任务。

让编排状态保持显式

OpenSeal 刻意把等待状态区分得很细。一个 Run 可能在等待依赖、等待另一个 agent、等待审批，或等待入站事件——这些被设计成不同的状态，因为它们需要不同的响应。等另一个 Run 完成，和等一个人做决定，根本不是一回事。

Agent 之间可以通过保存的请求互相索取工作。这种交换经历创建、响应、完成以及可选的完成审核几个阶段。因为这些记录都被存储，请求甚至可以比发起它的 Run 活得更久。

Agent 和 Team 的定义拥有不可变的保存版本，部署时可以切换版本，因此支持回滚到更早的版本。一次变更提议要经过提议、审核、决策、激活等独立步骤——注意，保存一个决策并不等于激活这个变更。这种显式分步的治理方式，在生产环境中极大降低了误操作风险。

在 Skill 边界上治理动作

Skill 边界是 OpenSeal 的治理核心。注册一个 Skill 让它的定义为系统所知，而绑定（binding）则把它授予某个 Agent 或 Team 部署。Team 层级的授权和成员层级的授权是分开的。

当策略要求审核时，动作调用会停在一个持久化的审批检查点。这里又有一条安全底线：缺失审批 authorizer 不会退化成自动批准权限。在本地模式下，standalone operator 标志才能启用本地决策，并且要求回环地址。

活动事件与它们所描述的状态变更在同一个事务中保存。凭证值在动作运行时才解析，并被排除在保存状态、提示词和终端客户端之外。

宿主边界的责任同样不可忽视：standalone API 本身既不提供认证、也不提供请求授权或 TLS，必须由宿主或代理来补齐。本地审批记录使用 user:local，因此它无法告诉你究竟是哪个人点了批准——这在需要审计追责的场景中值得特别注意。

「活动事件与状态变更在同一事务中保存」这一设计解决了分布式系统中的经典一致性难题：若先写状态再发事件，崩溃会导致状态已变但观察者无感知；若先发事件再写状态，则事件描述了一个尚未成真的变更。OpenSeal 选择将两者绑定在同一个数据库事务中，确保「已记录的事件」与「已持久化的状态」严格对应，下游消费者或审计日志看到的事件必然反映真实状态。这种设计在事件溯源（Event Sourcing）架构中被称为「事务性发件箱（Transactional Outbox）」模式的变体，是构建可审计系统的重要基础。

把模型路由放在正确的层

Workforce 编写接受一个 OpenAI 兼容端点，它可以指向一个暴露多个模型的兼容 LLM 网关。路径是 OpenSeal authoring → gateway → model provider。

文档描述的编写设置选定了一个端点、一个凭证和一个模型名称。这并不意味着核心会自动为每个任务挑选不同的模型——网关的路由和回退规则必须单独配置和测试。

这条边界把「提供方访问」与「持久化工作模型」隔开。想测试另一个受支持的模型，就改动模型设置并对比结果，同时确认提议依然走完整的审核与应用流程。

分清你正在使用哪条执行路径

这是最容易踩坑的地方。Standalone 服务使用 SQLite；PostgreSQL 要通过 Go 嵌入层才能用，并非 standalone 支持的存储选项。Projects 用于把 objectives 归组做来源监控和外联，而 Run 命令让团队可以暂停、恢复、取消或介入。

更关键的是，OpenSeal 还有一条独立的 HCL runbook 路径，通过 openseal run 执行。它在单个进程里运行一个带类型的图，不共享持久化的 Run 生命周期、审批或活动流。千万不要以为 runbook 命令继承了持久化核心所描述的那些保证。

HCL（HashiCorp Configuration Language）是由 HashiCorp 设计的结构化配置语言，广泛用于 Terraform、Packer 等工具。OpenSeal 的 runbook 路径借用这一格式来描述一个有向图（DAG）中的步骤依赖关系，并在单进程内按拓扑顺序执行。这与持久化核心的根本区别在于执行模型：runbook 是「一次性、同步、进程内」的任务运行器，类似 CI/CD pipeline；而持久化核心是「异步、跨进程、可中断恢复」的状态机。两者在功能上并无高下之分，但针对的场景截然不同——前者适合脚本化的批处理任务，后者才是需要人工审批和长期追踪的智能体工作流的正确选择。混淆两条路径会导致对系统保证的严重误判。

一个小型评估计划

想真正验证 OpenSeal，可以照着一个最小闭环来跑：

1. 读取 capabilities，连接所需 worker，创建一个小 objective；
2. 观察它的 Run 和各个 Turn；
3. 先尝试一个允许的动作，再尝试一个需要审核的动作；
4. 在审核挂起期间重启服务；
5. 同时检查保存的审批状态和动作在 OpenSeal 之外改变的东西。

记录重启前后的状态并作对比，这个比较会告诉你任务是否按预期恢复，以及哪里还需要补测试。

对于把智能体用于生产环境的团队来说，OpenSeal 的价值不在于「智能体能做什么」，而在于它把任务的持久化、恢复、审批与审计这些工程硬骨头显式地建模出来——这恰恰是多数快速原型框架省略掉的部分。