From f4c7bdd9e252e9c5f2a809c319fde7abd5d4cd4d Mon Sep 17 00:00:00 2001 From: Jack Chen Date: Thu, 9 Jul 2026 17:16:03 +0800 Subject: [PATCH] docs: document orchestrator cost budget and refresh cost example model (#361) - README_zh.md: add the "Cap estimated cost" section and production-checklist row that #358 added only to the English package README, keeping EN/ZH in sync - consensus.md: extend the budget invariant so maxCostBudget is documented at the same verify-hook boundary as maxTokenBudget; standalone runConsensus tracks tokens only - README EN/ZH: switch the cost example to gpt-5.4-mini, pricing matching the repo's existing cost-tiered-pipeline example Follow-up documentation for #358. --- docs/consensus.md | 2 +- packages/core/README.md | 2 +- packages/core/README_zh.md | 20 +++++++++++++++++++- 3 files changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/consensus.md b/docs/consensus.md index e5d2f36..f4e17c4 100644 --- a/docs/consensus.md +++ b/docs/consensus.md @@ -56,7 +56,7 @@ After the task completes, its result is fed into the same consensus loop. If con ## Budget invariant -Consensus token usage counts against the parent budget exactly like delegation does. Proposer, judge, and revision usage all accumulate into the running total and are checked against `OrchestratorConfig.maxTokenBudget`. Once the cumulative total crosses the budget, consensus **stops issuing further judge calls** — no separate budget knob, no escape hatch. For the per-task `verify` hook, judge usage rolls into the same run-level budget as the rest of the pipeline and trips the same gate. +Consensus token usage counts against the parent budget exactly like delegation does. Proposer, judge, and revision usage all accumulate into the running total and are checked against `OrchestratorConfig.maxTokenBudget`. Once the cumulative total crosses the budget, consensus **stops issuing further judge calls** — no separate budget knob, no escape hatch. For the per-task `verify` hook, judge usage rolls into the same run-level budget as the rest of the pipeline and trips the same gate. The same holds for cost: when `estimateCost` and `maxCostBudget` are configured, verify-hook usage is priced into the run's cumulative estimated cost and stops further judge calls at the same boundary once the cap is crossed. Because `maxCostBudget` is a run-level cap, the standalone `runConsensus` primitive tracks tokens only. ## Observability diff --git a/packages/core/README.md b/packages/core/README.md index c46bb69..59598ac 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -198,7 +198,7 @@ const orchestrator = new OpenMultiAgent({ ```ts const prices = { - 'gpt-4.1-mini': { input: 0.40, output: 1.60 }, // USD per 1M tokens + 'gpt-5.4-mini': { input: 0.75, output: 4.5 }, // USD per 1M tokens } const orchestrator = new OpenMultiAgent({ diff --git a/packages/core/README_zh.md b/packages/core/README_zh.md index f6503b6..0100b0e 100644 --- a/packages/core/README_zh.md +++ b/packages/core/README_zh.md @@ -194,6 +194,23 @@ const orchestrator = new OpenMultiAgent({ }) ``` +**封顶预估成本。** 价格表由应用侧维护，并提供估价函数；OMA 会将生效的 `model`、`provider`、执行阶段与 `taskId`（若有）一并传入，以便按模型计价。成本上限在与 `maxTokenBudget` 相同的轮次/任务边界处校验，单次运行至多可能超出一个模型轮次，并非精确到分的即时中止。 + +```ts +const prices = { + 'gpt-5.4-mini': { input: 0.75, output: 4.5 }, // 美元，每百万 tokens +} + +const orchestrator = new OpenMultiAgent({ + maxCostBudget: 0.25, + estimateCost: (usage, { model }) => { + const price = prices[model] ?? { input: 0, output: 0 } + return (usage.input_tokens / 1_000_000) * price.input + + (usage.output_tokens / 1_000_000) * price.output + }, +}) +``` + **取消运行。** 传入 `AbortSignal`；触发 abort 即中止运行。 ```ts @@ -402,7 +419,8 @@ await oma.runAgent( | 限制工具输出 | `maxToolOutputChars`（或单工具 `maxOutputChars`）+ `compressToolResults: true` | `AgentConfig` 和 `defineTool()` | | 失败重试 | 任务级 `maxRetries`、`retryDelayMs`、`retryBackoff`（指数退避倍率） | 通过 `runTasks()` 用的任务配置 | | 崩溃/重启后恢复 | `checkpoint`（给 `runId`，或内置 `FileStore` 等持久化 `MemoryStore`）+ `restore()` 恢复运行，跳过已完成任务 | `OrchestratorConfig` / 运行选项 | -| 总额封顶 | orchestrator 上设 `maxTokenBudget` | `OrchestratorConfig` | +| token 用量封顶 | orchestrator 上设 `maxTokenBudget` | `OrchestratorConfig` | +| 预估成本封顶 | `maxCostBudget` + `estimateCost`；每个模型的价格表由应用侧维护，校验发生在轮次/任务边界，而非精确到分的调用中途中止 | `OrchestratorConfig` | | 卡死检测 | `loopDetection` + `onLoopDetected: 'terminate'`（或自定义 handler） | `AgentConfig` | | 追踪与审计 | `onTrace` 接你的 tracing 后端；落盘 `renderTeamRunDashboard(result)` | `OrchestratorConfig` | | 脱敏密钥 | 自动：API key、token、Authorization header 从 trace、bash 输出、dashboard payload 中剥除 | 内置（默认开启） |