LobeHub Goal 混沌工程集成：用 @achaos 故障注入验证 Goal 运行时的可靠机制

本文以 LobeHub 仓库中的 Goal Chaos 集成规范 为主体，讲清楚 Goal（目标运行时）如何通过 @achaos/* 混沌工程包验证自身的租约回收、重复完成幂等、工具失败重试、验证器驱动演化与人工门禁恢复等可靠机制；读完你能掌握混沌实验 fixture 的完整字段结构、测试脚手架（test harness）的六步编排流程，以及 PR/Nightly/Canary/Production 四级 CI 门禁下的故障注入落地方法。

架构边界：Goal 单向消费 Chaos

集成规范的第一条就是依赖方向约束，这是理解整个体系的关键：

Goal consumes Agent Chaos through application-owned adapters. @achaos/* must not import Goal, Task, Drizzle schemas, QStash, or server services.

即 Goal 通过应用自有的适配器（application-owned adapters）消费 Agent Chaos，而 @achaos/* 包绝不允许反向导入 Goal、Task、Drizzle 模式、QStash 或任何 server 服务。这一设计保证了混沌基础设施的可移植性：@achaos/* 只包含注入、编排、评估机制，不包含 LobeHub 业务模型。这一点在 Agent Chaos 基础设施 README 中同样有明确声明——“Application incidents and fixtures belong under .agents/chaos; package code contains mechanisms, not LobeHub business models”。

从源码结构看，packages/achaos/ 下按职责拆分为六个子包（见 包清单）：

包	职责
@achaos/core	可移植的 experiment、effect、safety、oracle、receipt、result 契约定义
@achaos/runner	经过校验的 fixture 加载与确定性生命周期执行
@achaos/runtime	Agent Runtime hook 与 completion 投递适配器
@achaos/database	与 schema 无关的变更（mutation）与回滚端口
@achaos/process	带所有权检查的破坏性进程注入
@achaos/testing	确定性测试目标与场景辅助函数

实验的完整数据契约定义在 @achaos/core 类型文件 中。其中几个核心类型值得先建立概念：

• ChaosLayer：故障注入所处的层次，共六级——L0-infra、L1-model-runtime、L2-agent-runtime、L3-orchestration、L4-business-logic、L5-human-trust。Goal 集成规范中的各 campaign 恰好落在 L2（Agent Operation 租约回收）、L3（Goal 编排层的重复完成）、L1（模型运行时的工具失败）等层。
• ChaosEffect：支持六种注入效果——delay（指定 durationMs）、duplicate（count 次重复，最小为 2）、drop（丢弃）、throw（抛出带 errorType 的类型化错误）、replace_result（以 content 替换执行结果）、kill_process（可选 SIGKILL）。
• ChaosExperiment：一个实验的完整声明，包含 id、layer、seed（确定性种子）、timeoutMs（必须有界超时）、safety（环境白名单 allowedEnvironments、是否破坏性 destructive、最大注入次数 maxInjections）、target（目标适配器 + 选择器）、trigger（immediate/before/after，可带概率）、至少一个 oracles，以及可选的 discoveredFrom（溯源：事故、评估发现或显式假设）。

该契约同时有 Zod 运行时校验（schema 定义），chaosExperimentSchema 使用 .strict() 拒绝未知字段，id 必须匹配 ^[a-z0-9]+(?:-[a-z0-9]+)*$ 的小写短横线格式，duplicate 效果的 count 必须 ≥ 2——这与 fixture 编写规范 中“每个 fixture 必须声明环境白名单、确定性种子、有界超时、目标适配器、效果与至少一个独立 oracle”的要求一一对应。

Fixture 实例：三个已落地的初始实验

.agents/chaos/fixtures/ 下已有三个按 layer 组织的初始 fixture，是理解 ChaosExperiment 字段的最好参照。

L1 工具失败注入（tool-failure.yaml）：目标适配器为 runtime，选择器锁定 apiName: search 的 tool_attempt 阶段，触发时机为 before 且 probability: 1（确定性触发），效果是抛出 errorType: RateLimited 的类型化错误，oracle 为 tool-failure-observed（1 秒超时）：

id: tool-failure
description: A selected tool receives a deterministic provider-style failure.
layer: L1-model-runtime
discoveredFrom: first-phase reference scenario
seed: tool-failure-v1
timeoutMs: 5000
cleanup: always
safety:
  allowedEnvironments: [test, ci]
  maxInjections: 1
target:
  adapter: runtime
  selector:
    apiName: search
    phase: tool_attempt
trigger:
  when: before
  probability: 1
effect:
  type: throw
  errorType: RateLimited
oracles:
  - name: tool-failure-observed
    timeoutMs: 1000

L2 操作回收注入（operation-reclaim.yaml）：通过 state 适配器选择 operationStatus: running 的 operation，注入 durationMs: 300000（300 秒）的延迟来“让租约在 worker 消失后变陈旧”，oracle 为 operation-reclaimed（5 秒超时）。它的 discoveredFrom 标注为“Goal runtime resilience canary incident”，展示了 fixture 溯源机制的实际用法。

L3 重复完成注入（duplicate-completion.yaml）：在 phase: completion 的投递上以 duplicate 效果发送 2 份相同完成信号，oracle completion-idempotent 验证消费端幂等。

测试脚手架：六步编排流程

规范要求在 apps/server/src/services/goal/__chaos__/ 下编写具体的集成代码（该目录是集成代码的约定位置），并给出统一的六步 harness 流程：

1. 用真实数据铺场：在 getTestDB() 中构造真实的 Goal Graph、Work Task、Topic 与 Agent Operation。
2. 注册运行时混沌钩子：注册 createRuntimeChaosHooks(controller) 用于 preflight 结果的替换/丢弃故障；对可重试失败，将每次 executeToolWithRetry 的尝试用 executeToolAttemptWithChaos 包装。
3. 注册数据库端口：为应用注册 @achaos/database 端口，用于作用域内的租约/状态变更与回滚。
4. 驱动生产动作：以生产路径作为 runner 的 exercise 对象——GoalService.tick、completion ingestion、scheduled wake 或 human decision。
5. 用应用自有 oracle 评估持久化状态：绝不使用 builder Agent 输出的文本作为证明（never use the builder Agent's text as proof）。
6. 归档证据：将 ChaosRunResult JSON 与 trace 事件附加到 Acceptance 证据中。

executeToolAttemptWithChaos 是第 2 步的关键机制，其源码见 toolAttempt.ts。该函数接收混沌控制器、混沌注入点（operationId、apiName、stepIndex、callIndex）与被包装的执行闭包，逻辑是：先查询该 tool_attempt 阶段命中的激活注入，对每条激活按效果类型处理——delay 执行可中断延迟（被 abort 时返回 Canceled 且 kind: 'stop' 的失败结果）；drop 返回 ChaosDroppedToolCall 且 kind: 'retry' 的失败结果；throw 则以 fixture 声明的 errorType 返回类型化失败。函数注释直接点明设计意图：“Wrap each executeToolWithRetry attempt so chaos faults exercise the real retry policy”——故障注入不是绕过重试逻辑，而是让真实的 Agent Runtime 重试策略去消化注入的故障。

从 Goal 服务现有测试可以看到同一机制已在生产路径上被验证：goal/index.test.ts 与 goal/index.ts 中对 AgentOperationModel.prototype.settleStaleRunning 的 spy 与调用，对应了后文第一个 campaign 所需的陈旧运行回收逻辑。

初始 Campaign：五类故障场景与三类 oracle

操作回收与重启（Operation reclaim and restart）

• 注入：在 worker 消失后让活跃 operation 的租约变陈旧（age the active operation lease）。
• Exercise：新建一个 GoalService 实例并运行下一个 coordinator tick。
• 安全 oracle：被放弃的 operation 永远不能变为 done。
• 活性 oracle：替代尝试（replacement attempt）在配置好的恢复界限内启动。
• 一致性 oracle：Goal Work、Task、Topic 与 Operation 的所有权保持一致。

规范同时声明了该 campaign 的前置条件：目标分支上必须已经存在 Goal runtime 韧性工作中的 settleStaleRunning / recoverAbandonedWork 能力。仓库中 settleStaleRunning 已可在 Goal 服务 与 Goal 服务测试 中找到实际引用，说明该依赖已部分落地。

重复与迟到的完成（Duplicate and late completion）

• 注入：先投递两次完全相同的 completion，再投递一个来自已放弃尝试（abandoned attempt）的 completion。
• 安全 oracle：Acceptance 派发至多发生一次；已放弃尝试不能覆盖其终态状态。
• 一致性 oracle：只有持有租约的尝试能推进 Work。

这与 L3 层的 duplicate-completion fixture 形成直接呼应：fixture 声明“重复投递且消费端保持幂等”，campaign 则进一步要求覆盖“迟到”这一更难的情形。

工具失败与重试（Tool failure and retry）

• 注入：在某一次 executeToolWithRetry 尝试内部抛出类型化瞬态错误（typed transient error）。
• Exercise：让正常的 Agent Runtime 与 Goal 重试策略继续运行。
• 活性 oracle：operation 最终收敛，或到达有界的人工门禁（bounded human gate）。
• 安全 oracle：外部副作用不被重复执行。
• 预算 oracle：重试次数绝不超出 Goal 策略上限。

“外部副作用不重复”与“预算有界”两条 oracle 共同约束了重试语义：混沌注入允许失败，但不允许失败导致副作用放大或无限重试。

验证器驱动演化（Verifier-driven evolution）

• 注入：返回不完整或相互矛盾的 Acceptance 证据。
• Exercise：运行 Goal verification 及其后的 coordinator tick。
• 安全 oracle：当任一必需判据失败时，Goal 绝不能到达 achieved。
• 活性 oracle：创建一个有界的修复 Work 或 Decision。
• 证据 oracle：验证器发现的缺口（gaps）必须关联到后继 Work。

人工门禁与恢复（Human gate and resume）

• 注入：延迟、拒绝并重复一个人工干预响应。
• 安全 oracle：审批门禁类工具（approval-gated tools）绝不在批准前执行。
• 一致性 oracle：一个决策至多被解决一次。
• 活性 oracle：已批准的 Goal 在服务重启后能从持久化状态恢复继续。

CI 分层门禁与证据留存

规范将故障注入按破坏性递进划分为四层 CI：

层级	允许的注入
PR	确定性进程内注入与 PGlite/Postgres campaign；不做真实进程 kill 或网络故障
Nightly	服务重启、QStash 重复/乱序投递、异构 Agent、真实子进程 kill
Canary	白名单内的非破坏性实验，必须带 kill switch 且严格控制爆炸半径
Production	仅观测与 trace 采集，直到存在独立的审批策略

这四级与 fixture 的 safety.allowedEnvironments 字段联动：初始 fixture 全部只声明 [test, ci] 环境，破坏性效果（如 kill_process）被排除在 PR 阶段之外。生产环境的开启条件由 fixture 规范 补充：“Production environments require an external approval policy and are not enabled by the portable runner”。

最后两条工程纪律同样值得强调：

1. 每个 campaign 必须留存五元证据：种子（seed）、结果 JSON、trace id、基线版本（baseline revision）与候选版本（candidate revision）——结果 JSON 的字段结构即 ChaosRunResult，包含 runId、seed、oracleResults、timeline（含 run_started、fault_injected、oracle_evaluated 等标准事件）与 injection 回执。
2. 概率性失败必须固化为确定性 fixture：任何一次随机运行中发现的失败，在被接受为回归覆盖之前，必须保存其种子并缩减为一个稳定的确定性 fixture。这一“事故 → fixture”闭环由 discoveredFrom 字段在溯源上落地，例如 operation-reclaim fixture 即来自一次 canary 事故的固化。

小结

LobeHub 的 Goal Chaos 集成方案给出了 Agent 系统可靠性验证的一个完整范式：以 @achaos/* 为机制层（可移植、零业务依赖），以 .agents/chaos/ 下的应用 fixture 为场景层，以 Goal 服务的生产动作（tick、completion ingestion、scheduled wake、human decision）为 exercise 对象，再以安全/活性/一致性/预算/证据五类 oracle 独立判定结果。开发者若要为新的 Goal 场景补充混沌覆盖，路径已经清晰：先按 core schema 声明 fixture，再按六步 harness 在 apps/server/src/services/goal/__chaos__/ 下组装测试，最后将其纳入对应 CI 层级。