接入运行治理

运行治理解决三件事：把每次 Provider Attempt 归入一次 Run；在 Project 日预算之外执行 Run 生命周期预算；由独立验收方上报结构化 Outcome，让报表计算覆盖率、成功率和单位成功成本。

Halro 不拆任务、不编排 Agent，也不替业务判断成功。业务应用负责生命周期，Halro 保存费用与归属权威；验收系统负责 Outcome，Halro 在查询时按 Work Unit 合并两边。

对象怎么划分

对象怎么划分
对象	业务含义	例子
Work Unit	最终只应计算一次业务结果的工作对象	工单 `8472`
Run	完成该 Work Unit 的一次执行	第一次 Agent 执行、失败后的第二次执行
Outcome Definition	允许什么结果、哪些值算成功的版本化定义	`ticket_result v1`
Outcome	验收系统对 Work Unit 的一次声明或修订	`accepted`

一个 Run 可以包含多个请求、Provider 重试和 fallback。整个 Agent 执行重新开始时，关闭旧 Run，在同一 Work Unit 下创建新 Run；最终结果只计一次，成本包含所有 Run。

三种常见 Work Unit 划分

三种常见 Work Unit 划分
业务场景	Work Unit	Run	Outcome Definition	不应怎么划分
客服工单	一张需要最终解决的工单	一次 Agent 处理，人工退回后重跑是新 Run	`ticket_result = accepted/rejected`	每次模型请求一个 Work Unit
文档抽取	文件 ID + 不可变文件版本	一次完整抽取流水线	`extraction_result = accepted/rejected`	文件被替换后仍沿用旧 Work Unit
代码修复	Issue + 目标代码基线	一次 Agent 修复执行	`review_result = mergeable/changes_requested`	每次 Provider fallback 创建新 Run

判断标准是“最终业务结果应该计算几次”。应该计算一次的对象放在同一个 Work Unit；完整执行重新开始时创建新 Run；Halro 内部 Provider retry/fallback 仍属于原 Run。

准备权限和 Project

在 Admin Console → Projects 编辑 Project，启用“运行治理”，设置默认/最大预算、默认/最大 TTL、active Run 上限和 open Work Unit 上限。控制台显示 USD 与小时；API 使用 micros USD 与秒，其中 1 USD = 1,000,000 micros USD。

建议创建两把 Key：

准备权限和 Project
调用方	Scope
Agent 编排	`inference`、`work_unit:create`、`run:create`、`run:attach`，按需加 `governance:read`
业务验收	`outcome:write`，按需加 `governance:read`

旧 Key 只保留 inference，不会自动得到治理权限。创建 Run 的 Key 也不会自动拥有 outcome:write。

创建结果定义

在 Admin Console → 运行治理 选择 Project，创建 Definition：

{
  "name": "ticket_result",
  "data_type": "CATEGORICAL",
  "allowed_values": ["accepted", "rejected"],
  "success_values": ["accepted"],
  "description": "工单最终验收结果",
  "enabled": true
}

第一版只接受 BOOLEAN 和 2–16 项的 CATEGORICAL。Definition 名称和历史版本不可变；修改会创建新版本。Work Unit 创建时冻结当时启用的版本，之后升级 Definition 不追溯改变旧任务。

完整调用流程

创建 Work Unit

curl https://halro.example.com/halro/v1/work-units \
  -H "Authorization: Bearer $HALRO_ORCHESTRATOR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8472-work-unit-v1" \
  -d '{"outcome_definition_ids":["odef_xxx"]}'

保存响应中的 wku_...。每个写操作都要使用稳定且属于该逻辑操作的 Idempotency-Key；超时后用相同 Key 和相同请求体重试。

创建 Run

curl https://halro.example.com/halro/v1/runs \
  -H "Authorization: Bearer $HALRO_ORCHESTRATOR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8472-run-1-v1" \
  -d '{"work_unit_id":"wku_xxx","budget_micros_usd":500000,"ttl_seconds":3600}'

省略预算或 TTL 时使用 Project 默认值。保存响应中的 run_...。

把模型调用归入 Run
Terminal window
```
curl https://halro.example.com/v1/chat/completions \
  -H "Authorization: Bearer $HALRO_ORCHESTRATOR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Halro-Run-ID: run_xxx" \
  -d '{"model":"chat","messages":[{"role":"user","content":"处理工单 8472"}]}'
```
不需要传 Work Unit ID，Run 已经绑定它。Halro 在 Provider I/O 前原子检查 Project 日预算和 Run 的 committed + reserved + pending。预算不足返回 403 run_budget_exceeded，不会调用 Provider。OpenAI、Anthropic 和延迟 Responses 使用同一个 Run 请求头。

结束执行和工作对象

curl https://halro.example.com/halro/v1/runs/run_xxx/close \
  -H "Authorization: Bearer $HALRO_ORCHESTRATOR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8472-run-1-close" \
  -d '{"reason":"completed"}'

curl https://halro.example.com/halro/v1/work-units/wku_xxx/close \
  -H "Authorization: Bearer $HALRO_ORCHESTRATOR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8472-work-unit-close" \
  -d '{}'

关闭全部 Run，并确定不再重启整项工作后再关闭 Work Unit。

由验收系统上报 Outcome

curl https://halro.example.com/halro/v1/work-units/wku_xxx/outcomes \
  -H "Authorization: Bearer $HALRO_ACCEPTANCE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8472-outcome-v1" \
  -d '{
    "definition_id":"odef_xxx",
    "value":"accepted",
    "observed_at":"2026-09-04T08:30:00Z",
    "evidence_ref":"ticket_8472_acceptance_3",
    "evidence_sha256":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }'

Outcome 只发送 Definition ID、结构化值、观察时间和可选的脱敏证据引用/摘要。不要发送 Prompt、 Response、验收意见全文、URL、Token 或密码。evidence_ref 是最长 128 字符的不透明内部编号，不能包含 URL 或凭据形状；SHA-256 必须是 64 位小写十六进制。

修订与成熟度

修订结果时重新 POST，并增加：

{
  "definition_id": "odef_xxx",
  "value": "rejected",
  "observed_at": "2026-09-04T09:00:00Z",
  "supersedes_outcome_id": "out_previous"
}

必须指向当前 Outcome 并使用新的 Idempotency-Key。每个结果最多 20 个 revision；Work Unit 关闭 30 天后停止写入。Work Unit 仍开放或仍有 pending/inflight Attempt 时，Outcome 标记为 provisional，不能当作已经成熟的最终结果。

怎么读控制台报表

Admin Console → 运行治理 可以从 Work Unit 下钻到 Run 和 Attempt，并查看 Outcome、覆盖率、成功率、已知/估算/进行中/未知费用以及单位成功成本。

Outcome coverage = 有结果的 Work Unit / eligible Work Unit；
Success rate = 成功结果 / 已评估结果；
Cost per success = 成熟 Work Unit 的已知模型成本 / 成功 Work Unit；
partial 或 unknown 不是零，表示结果缺失、工作仍在进行或成本不完整。

内置 cohort 最多 90 天或 100,000 个 Work Unit；更大的分析使用 Governance Export。导出在 Halro 数据目录生成规范化 NDJSON 和带双 watermark、SHA-256、记录数的 manifest，不会主动上传到外部 FinOps 服务。当前触发权限、本地目录、Usage 交接和水位边界见 Usage 与 Governance 数据交接 FinOps。

上线前

首次打开新版本会迁移 metadata schema，并启用新的 Ledger feature epoch。上线前必须创建并验证升级前备份；升级后如需回退，应恢复这份备份，不能让旧二进制直接打开已经升级的数据目录。

当前阶段仍需完成真实业务试点，验证 Work Unit 边界、Definition、验收方、观察窗口和决策用途。

更多跨功能组合方式见最佳实践案例库。