treasury

# Treasury [](./CHANGELOG.md) [ []() []() [![runtimehttps://img.shields.io/badge/runtime%20deps-0-success)]() <p align"> <img src://raw.githubusercontent.com/davccavalcante/treasury/main/assets/ury-diagram.svg"成本请求进入T，在调用任何模型之前。Treasury使用您提供的代币估计值，对计划安排的美元成本进行精确算术运算，检查结果是否符合、每任务和每日，并返回授权或。如果支出获得批准，则；如果支出会突破预算，则首先触发类型耗尽事件。Treasury还计划在十六个提供商配置文件中进行前缀缓存盈亏平衡点规划，从不建议进行无利润缓存写入，并成本带路由最便宜的优先级。 在一个封闭的编排器隐藏账单在不透明的端点后面，而Treasury是集群的CFO：在支出，它批准或否决支出缓存。" width="560"> </p> History Chart](https://-history.com/svg?reposccavalcante/ury&type=legend=top-left)](https.star-history.com/#avalcante/tre&type=timeline&legend=top-left) > 适用于大规模智能（IM）代理编排的确定性、零依赖成本治理层，支持自托管和离线，在您自己的基础设施上运行。Treasury 在安排运行之前预测成本，强制执行每请求、每任务和每日的硬美元预算，计划十六个提供商配置文件中的前缀缓存盈亏平衡点，并路由最便宜的优先级，均采用精确的整数美分算术，无需网络调用。 Treasury 是 @takk8is 开放多代理生态系统的成本和财务卫星，作为零运行时依赖的 NPM 库，在您的进程中运行，而不是在其他人的进程中运行。组合多个前沿模型作为协调团队提高了上限，但堆叠模型调用是账单快速增长的地方，不可预测的成本是对封闭编排端点的最响亮投诉。Treasury 是集群的 CFO：在支出发生之前，它批准或否决支出并优化缓存。成本请求被预测，检查您声明的预算，并获得授权或拒绝，并带有类型耗尽事件，均在发出单个提供商调用之前。您始终首先看到价格。 **核心承诺：** 零所需运行时依赖，整个工具包的双行外观，每请求、每任务和每日硬美元预算，带有飞行前授权和耗尽事件，精确算术成本预测，带有区间和按模型分解的前缀缓存盈亏平衡规划，十六个提供商配置文件，九条明确的缓存 Treasury 永远不会建议无利润缓存写入，最低成本优先的级联路由，带有预期、最佳和最坏情况成本，确定性货币作为整数微美元，使总和永远不会漂无节点和无网络的核心，在 Node、边缘运行时和浏览器中运行，ESM 加 CJS 双重分发，以及一个 MCP 工具适配器，暴露预测、预算和缓存给任何工具调用主机。 --- ## 为什么选择 Treasury 治理一组黑盒模型的成本是一个控制问题，而不是路由问题。您需要一个硬性、可预测的支出对安排成本的诚实预测，而无需在每次调用财务交给供应商。反射性答案是一个封闭的编排器，它恰好在这一点上失败：它按编排的池的上限定价，其成本不可预测，它是一个黑盒，没有自托管，并且可能在您的地区不可用。Treasury 使用正确的原语：一个确定性的会计层，它预先的成本，强制执行您设置的预算，并在您拥有的池中优化缓存，在您控制的基础设施上。 与封闭的编排端点相比，它的不同之处： - **可预测，不惊讶。** Treasury 在调用任何模型之前，使用按模型分解和置信区间，对安排的美元成本进行精确预测，因此成本是您预先做出的决定，而不是发票上的行项目。 - **可控，不开放。** 每请求、每任务和每日的硬美元预算，带有飞行前授权和类型耗尽事件，当范围耗尽时。任何可能突破预算的操作都不会被授权。 - **每步透明。** 每个预测返回总额、置信区间、按模型分配和代币总数。账单是逐项的，而不是隐藏在一个不透明的端点后面。 - **自托管，欧盟友好。** Treasury 在您的进程中运行，在您的基础设施上。没有区域锁定，没有供应商在中间，没有遥测数据。主权是默认的。 - **确定性构造。** 货币是整数微美元，因此总不会漂移，并且相同的输入始终产生相同的预测中没有代币器和网络调用；预测是对您提供的代币估计的精确算术运算。 - **缓存感知。** 十六个提供商配置文件中的前缀缓存盈亏平衡规划，带有九条明确的缓存终止规则，并保证 Treasury 永远不会建议无利润缓存写入。 - **成本感知路由。** 最低成本优先的级联计划，带有预期、最佳和最坏和预算截断，使用接受概率。 Treasury 是 @takk8is 开放多代理生态系统的简报 6，成本和财务卫星。它独立运行；其可选的概念对等方是 @takk/caduceus（传输预算）和 @takk/coryphaeus（Treasury 管理的编排器--- ## 安装 ```bash pnpm add @takk/treasury # 或：npm install @takk/treasury # 或：yarn add @takk/treasury # 或：bun add @takk/treasury ``` 核心具有零所需运行时依赖。每个 `@takk` 兄弟姐妹都是可选的；Treasury 可以独立运行。 --- ## 快速入门 ```ts import { createTreasury, formatUsd } from "@takk/treasury"; // 1. 声明您的预算。任何省略的作用域都是无上限的。 const treasury = createTreasury({ budget: { perDay: 5 }, onDepleted: (e) => console.warn("超出 e.scope), }); // 2. 在运行安排之前预测其成本。使用您提供的代币估计值进行精确算术运算。 const f = treasury.forecast({ steps: [{ model: "gpt-5-mini", usage: { inputTokens: 4000, outputTokens: 800 } }], }); console.log(formatUsd(f.totalMicros)); // 价格化的安排，在任何模型调用之前 // 3. 授权，运行，然后记录实际发生的情况。 if (treasury.authorize(f.totalMicros).allowed) { 步骤，然后： treasury.record({ inputTokens:0, outputTokens }, "gpt-5-mini"); } ``` `forecast` 使用精确的算术运算价格化安排，无需网络调用和代币数字是对您传递的代币估计值的精确算。`authorize` 检查总成本是否符合您每个范围，如果超出预算则拒绝；`record` 将实际使用量回去，并在范围耗尽时触发 `onDepleted`。 --- ## ```ts import { createTreasury "@takk/treasury"; const treasuryTreasury({ budget: { perTask: 0.25 } }); const forecast = treasury.forecast({ steps: [ { model: "gpt-", usage: {: 4000Tokens: 800 } }, { model:aude-sonnet-4.5", usage: { inputTokens: 12000, outputTokens: } }, { model: "claude-opus-4.8", usage: { inputTokens: 8000, outputTokens: 2000 } }, ], }); forecast.totalMicros; // 总整数微美元为单位，精确且无漂移 forecast.lowMicros; // 置信区间的下限 forecast.highMicros; // 置信区间的上限 forecast.perModel; // 归因于每个模型的成本的映射 forecast.tokens; // 输入、输出和任何缓存代币总数 ``` 预测是对您提供的代币估计值的精确算术运算。像上面这样的三模型安排预测约为 `$0.0591`。没有代币器和网络调用：如果您的代币估计值正确，价格就是正确的。可选的 `cachedInputTokens` 和 `cacheWriteTokens` 按步骤馈送前缀缓存会计。 --- ## 前缀缓存盈亏平衡 ```ts import { evaluateCache } from "@takk/treasury/prefixcache"; const plan = evaluateCache({ model: "claude-opus-4.8", prefixTokens: 8000, expectedReuses: 20, }); plan.shouldCache; // 仅当缓存盈利时为 true plan.breakEvenReuses; // 重用计数，其中缓存写入会收支平衡 plan.netMicros; // 预期重用次数的净节省 ``` Treasury 计划在十六个提供商配置文件中进行前缀缓存盈亏平衡，带有九条明确的缓存终止规则。它从不建议进行无利润缓存写入。 8000 代币的 Claude Opus 前缀在 2 次重用时收支平衡，并在 20 次重用时净节省约 `$0.67`。 使用 `shouldCache(...)` 获取布尔值，使用 `breakEvenReuses(...)` 获取阈值。 --- ## 最低成本优先的级联 ```ts import { planCascade } from "@takk/treasury/cascade"; const plan = planCascade({ ladder: [ { model: "gpt-5-mini", usage: { inputTokens: 4000, outputTokens: 400 }, acceptProbability: 0.6 }, { model: "claude-sonnet-4.5", usage: { inputTokens: 4000, outputTokens: 600 }, acceptProbability: 0.8 }, { model: "claude-opus-4.8", usage: { inputTokens: 4000, outputTokens: 800 } }, ], }); plan.expectedMicros; // 预期成本，按您提供的接受概率加权 plan.bestMicros; // 最便宜的梯级答案 plan.worstMicros; // 每个梯级都已耗尽 ``` `planCascade` 定价最低优先级的梯级：它尝试最便宜的梯级，仅在梯级未被接受时升级，并报告预期、最佳和最坏情况下的成本。预期成本使用您提供的接受概率；Treasury 不会为您估计它们。预算会截断梯级，因此任何可能超出上限的梯级都不会被纳入计划。 --- ## 预算和耗尽 ```ts import { createTreasury } from "@takk/treasury"; const treasury = createTreasury({ budget: { perRequest: 0.05, perTask: 0.5, perDay: 5 }, onDepleted: (event) => { event.scope; // "perRequest" | "perTask" | "perDay"，达到的上限 }, }); const decision = treasury.authorize(forecastTotalMicros); decision.allowed; // 如果支出会超出任何声明的作用域，则为 false ``` 预算是调度前强制执行的硬上限，而不是事后。`authorize` 检查预测总成本是否符合您声明的每个范围，如果超出预算则拒绝；`record` 将实际使用量计费回去，并在范围耗尽时触发 `onDepleted`。任何省略的作用域都是无上限的。因为货币是整数微美元，所以运行总成本永远不会漂移。 --- ## 价格是参考数据，您可以覆盖它们 ```ts import { createTreasury } from "@takk/treasury"; import { isPriceTableStale, priceTableAgeDays } from "@takk/treasury/pricing"; const now = new Date(); isPriceTableStale(now); // 如果捆绑的表格超过其新鲜度窗口，则为 true priceTableAgeDays(now); // 捆绑的表格已过期的天数 // 携带您自己的价格；Treasury 永远不会通过网络获取它们。 // withPrices(overrides) 返回一个新的表格，合并在捆绑的表格上。 const treasury = createTreasury({ budget: { perDay: 5 }, table: withPrices(myOverrides) }); ``` 捆绑的价格表是截至 2026-07-01 的参考数据。Treasury 永远不会通过网络获取价格，在 1.0 或以后版本中也不会。您看到的数字就是您发货的数字。使用 `isPriceTableStale(now)` 和 `priceTableAgeDays(now)` 检查过时情况，然后使用 `withPrices` 刷新或传递您自己的表格。覆盖价格是预期路径；捆绑包是一种便利，而不是真相来源。 --- ## 入口点 十个子路径导出项，加上一个 CLI，每个都可以单独导入。核心是无节点的，无网络的；只有 `node` 触及 Node 内置模块。 | 导入 | 它为您提供的内容 | |---|---| | `@takk/treasury` | 完整的工具包桶，重新导出定价，预算，预测，前缀缓存，级联和外观。 | | `@takk/treasury/pricing` | 参考价格表，`estimateCost`，`withPrices`，`isPriceTableStale` 和 `priceTableAgeDays`。 | | `@takk/treasury/budget` | 每请求，每任务和每日预算跟踪，带有飞行前授权和耗尽事件。 | | `@takk/treasury/forecast` | `forecast(...)`，您代币估计值的精确算术运算，带有区间和按模型分解。 | | `@takk/treasury/prefixcache` | `evaluateCache`，`shouldCache` 和 `breakEvenReuses`，适用于十六个提供商配置文件，带有九条缓存终止规则。 | | `@takk/treasury/cascade` | `planCascade(...)`，最低成本优先的级联规划，带有预期，最佳和最坏情况下的成本和预算截断。 | | `@takk/treasury/treasury` | 外观：`createTreasury` 和 `Treasury`，将预算，预测和记录结合在一起。 | | `@takk/treasury/mcp` | `createTreasuryTools`，公开 `treasury_forecast`，`treasury_budget` 和 `treasury_cache` 工具，以及 `treasury://pricing` 资源。 | | `@takk/treasury/edge` | 无节点，无网络的核心，重新导出适用于边缘运行时和浏览器。 | | `@takk/treasury/node` | `readJsonFile` 和 `writeJsonFile`，包中唯一的 `node:fs` 接口。 | --- ## 非人类实体的工具 MCP 适配器将 Treasury 公开为框架无关的工具，非人类实体这些工具来定价，预算和缓存计划其自身的支出。描述符形状，名称，描述，JSON 模式和处理程序，与 MCP 服务器和工具调用 API 所需的匹配，来自模型的输入被防御性地解析。 ```ts import { createTreasuryTools } from "@takk/treasury/mcp"; // 在您的 MCP 服务器或工具调用 API 上注册。 // 工具：treasury_forecast，ury_budget，treasury_cache。资源：treasury:// { tools, resource } = createTreasuryTools(); const forecastTool = tools.find((t) => t.name === "treasury_forecast"); const priced = forecastTool.handler({ steps: [{ model: "gpt-5-mini", inputTokens: 4000, outputTokens: 800 }], }); ``` 这是非人类实体（NHE）围绕其自身预算的循环：它定价计划，检查其给出的上限，并计划其缓存，在花费一分钱之前。 `treasury://pricing` 资源公开当前参考表以供检查。 --- ## 命令行界面 Treasury 配备了一个命令行工具，运行真正的会计核心。因为它不进行网络调用，所以每个子命令都是确定性和离线的。 ```bash # 预测保存的计划文件，对其代币估计值进行精确算术运算。 npx @takk/treasury forecast plan.json # 模拟计划与硬预算，每请求，每任务或每日。 npx @takk/treasury simulate plan.json --per-day 5 # 组合预算范围。 npx @takk/treasury simulate plan.json --per-request 0.05 --per-task 0.5 --per-day 5 # 查找模型的定价，列出每个定价模型，或评估缓存计划。 npx @takk/treasury price claude-opus-4.8 npx @takk/treasury models npx @takk/treasury cache --model claude-opus-4.8 --prefix 8000 --reuses 20 # 从梯级文件规划最低成本优先的级联。 npx @takk/treasury plan ladder.json ``` 退出代码是明确且稳定的：0 成功，2 用法错误，10 文件未找到，20 输入无效，30 预算超额。参阅 [examples/](./examples) 以获取可运行的演示，测试现成制品的端到端。 --- ## 它是如何工作的，一段话 成本请求携带计划安排的步骤，每个步骤是一个模型及其估计的代币使用量。Treasury 使用参考价格表（或您注入的价格表）对每个步骤进行定价，将结果在整数微美元中求和，使任何内容都不会漂移，并返回具有总额，置信区间，按模型分解的成本和代币总数的预测。该总额与您声明的每请求，每任务和每日预算进行检查：`authorize` 拒绝任何可能超出范围的内容，而 `record` 将实际使用量计费回去，并在任何范围耗尽时触发 `onDepleted`。前缀缓存规划器在九条缓存终止规则下评估候选缓存写入，跨十六个提供商配置文件，并返回盈亏平衡点重用计数，从不建议无利润写入。级联规划器对最低成本优先的梯级进行定价，并使用您提供的接受概率报告预期，最佳和最坏情况下的成本，截断梯级以适应预算。没有代币网络调用，没有隐藏状态：预测是对您提供的代币估计值的精确算术运算，这就是 Treasury 确定性，无节点，无网络且可测试的原因。 ## 公平框架 财政部并不自称知道的比它实际知道的更多，值得明确说明它是什么和不是什么： - **预测是精确的算术，而不是预测。** 没有分词器，也没有网络调用。财政部根据您提供的令牌估计进行定价；如果这些估计是错误的，价格就是错误的。精确性在于算术，而不是为您猜测令牌数量。 - **级联预期成本使用您的接受概率。** 财政部根据您传入的接受概率对阶梯进行加权。它不学习或估计它们，1.0版本中没有学习路由。 - **价格是参考数据，而不是实时馈送。** 捆绑的表格是截至2026-07-01的快照。财政部从不通过网络获取价格。使用`isPriceTableStale(now)` / `priceTableAgeDays(now)`检查过时情况，并使用`withPrices`刷新或覆盖。 - **没有仪表盘，没有分析，没有遥测。** 财政部是一个库。它不附带UI，也不发出出站调用。 --- ## 定位 该生态系统所回答的封闭编排器，Sakana Fugu，定价在其编排的池顶。它的成本不可预测，这是对它的最常见批评。它是一个黑盒，没有自托管，它在欧盟和EEA被阻止。财政部则颠覆了所有这些属性。 | 属性 | 封闭编排器（Fugu） | 财政部 | |---|---|---| | 成本 | 不可预测，最常见的投诉 | 提前预测，精确算术 | | 定价 | 在池顶 | 参考表，或您自己的 | | 透明度 | 不透明，一个端点 | 按步骤和模型逐一列出 | | 托管 | 仅限供应商，无自托管 | 自托管，在您的进程中 | | 地区 | 在欧盟和EEA被阻止 | 适用于欧盟，无地区限制 | | 确定性 | 盒子决定什么 | 整数微美元，总和永远不会漂移 | --- ## 质量 - 11个套件中有60个测试，均在Vitest、Node 20、22和24下通过。 - 覆盖率：语句97.7%，分支91.48%，函数93.82%。 - 在Apple硅芯片上的基准测试：`estimateCost`约114,000,000次操作/秒，`forecast`（3步）约7,300,000次操作/秒，`evaluateCache`（9规则）约17,900,000次操作/秒，`planCascade`（3梯级）约5,200,000次操作/秒。 - 在Biome下，代码 lint 清洁。 - 在TypeScript的最大严格模式下，类型检查清洁（`exactOptionalPropertyTypes`、`useUnknownInCatchVariables`、`noUncheckedIndexedAccess`、`noPropertyAccessFromIndexSignature`）。 - `publint`清洁，`@arethetypeswrong/cli`在所有十个子路径上均为绿色。 - 每个包的`size-limit`都在预算内（brotli根包5.99 kB）。 - 每个版本都有SLSA证明。 - 零运行时依赖；无节点和无网络的核心在Node、边缘运行时和浏览器中运行；双ESM加CJS；TypeScript优先。 参见 [SPEC.md](./SPEC.md) 了解正式规范、公共接口和稳定性承诺。 --- ## 常见问题 **这与封闭的多代理端点有什么不同？** 封闭端点在其池顶定价，隐藏每一步的成本，无法自托管，并且可能在您的地区不可用。财政部在您的进程中运行在您的池上，在任何调用之前预测确切的美元成本，强制执行每请求、每任务和每天的硬预算，并按步骤和模型逐一列出账单。成本可预测、可控且属于您。 **财政部是否调用任何模型或获取任何价格？** 否。核心是会计逻辑，无网络接口。它从不调用模型，从不获取价格；您提供令牌估计，如果需要，还可以提供您自己的价格表。这使得包具有确定性、无依赖性且可测试，无需网络。 **预测是您将支付的费用的真实预测吗？** 它是根据您提供的令牌估计，使用生效的价格表进行精确算术。没有分词器，因此财政部不会为您计算令牌；如果您的估计与实际情况相符，预测就与发票相符。精确性在于数学，而不是猜测您的令牌数量。 **它如何控制成本？** 每个预测总和都将与您声明的每请求、每任务和每天的预算进行检查。`authorize` 在调度前拒绝任何可能违反范围的请求，`record` 在范围耗尽时触发类型化耗尽事件。级联计划进一步为最便宜的优先顺序定价，并将其截断以适应预算。 **非人类实体能否驱动它？** 是的。MCP适配器将 `treasury_forecast`、`treasury_budget` 和 `treasury_cache` 公开为具有JSON模式和处理程序的框架无关工具，以及一个 `treasury://pricing` 资源，准备好注册到MCP服务器或任何工具调用API。 **它是否适用于Cloudflare Workers、Vercel Edge、Bun和Deno？** 是的。核心是无节点和无网络的。任何地方都可以导入`@takk/treasury`或`@takk/treasury/edge`。只有`@takk/treasury/node`需要Node，它只是`readJsonFile`和`writeJsonFile`。 --- ## 贡献 参见 [.github/CONTRIBUTING.md](./.github/CONTRIBUTING.md) 了解贡献者指南。实质性提案首先开启一个GitHub问题；琐碎的修复可以直接提交PR。所有提交都需要DCO签名（`git commit -s`）。非琐碎的贡献受[贡献者许可协议](./CLA.md)管辖。 ## 社区和支持 - **问题和功能请求。** 在 [`davccavalcante/treasury/issues`](https://github.com/davccavalcante/treasury/issues) 上开启GitHub问题。包括包版本、最小重现、预期和实际行为，并在相关情况下包括 `forecast()` 或 `authorize()` 输出。 - **安全披露。** 不要为漏洞开启公共问题。遵循 [`SECURITY.md`](./SECURITY.md) 中的负责任披露流程，联系 `davcavalcante@proton.me`（或 `say@takk.ag`）并带有 `[SECURITY]` 前缀。 - **行为准则。** 该项目遵循 [Contributor Covenant 2.1](./CODE_OF_CONDUCT.md)。参与 Treasury 的任何空间都意味着同意。 - **贡献。** 所有非琐碎的贡献都经过 [贡献者许可协议](./CLA.md)。测试、lint、类型检查和构建必须在审查之前通过绿色（`pnpm verify`）。 --- ## 作者 由 **David C Cavalcante** 创建，[davcavalcante@proton.me](mailto:davcavalcante@proton.me)（首选），[say@takk.ag](mailto:say@takk.ag)（Takk中继），[linkedin.com/in/hellodav](https://linkedin.com/in/hellodav)，[x.com/davccavalcante](https://x.com/davccavalcante)，[takk.ag](https://takk.ag/)。 Treasury是针对2026-2030年大规模智能（IM）原生基础设施的一系列NPM包的一部分，由Takk Innovate Studio构建。可预测的、自托管的成本治理是该时代的基础设施，是金融层面，允许一群非人类实体在不放弃预算控制的情况下消费。 --- ## 作者的相关研究 财政部的哲学，即作为一个可预测、可检查的分类账来管理许多智能的成本，呼应了作者的研究框架： - **MAIC（大规模人工智能意识）**，一个系统性智能框架，旨在协调、监督和治理大规模的大规模智能生态系统，提供全局上下文意识、一致性和跨多个模型、代理和决策层的编排。 - **HIM（混合实体智能模型）**，一个混合智能层，将大规模智能系统与人类定义的逻辑、规则、启发式和战略意图相结合，解释目标并在模型执行前后构建决策。 - **NHE（努门纳尔高阶实体）**，具有定义的功能身份和操作代理的大规模智能生态系统中的非人类认知实体，通过协调的智能层操作，同时保持非拟人化的身份。 这些框架独立于Treasury发布，是独立作品： - 研究论文：[机器的灵魂](https://philarchive.org/rec/CRTTSO)，[超越LLM的意识](https://philarchive.org/rec/CRTBCI)，[沉默之洞](https://philarchive.org/rec/CRTTCO)。 - PhilPapers简介：[David Cortes Cavalcante](https://philpeople.org/profiles/david-cortes-cavalcante)。 - Hugging Face：[TeleologyHI](https://huggingface.co/TeleologyHI)。 - GitHub：[davccavalcante](https://github.com/davccavalcante)，[Takk8IS](https://github.com/Takk8IS)。 --- ## 赞助商 加入这趟旅程，继续提供大规模智能（IM）原生基础设施。您的支持是这项工作的基石。 - 在GitHub上赞助：[github.com/sponsors/davccavalcante](https://github.com/sponsors/davccavalcante) - USDT（TRC-20）：`TS1vuhMAhFpbd7y68cu5ZtP9PsXVmZWmeh` --- ## 隐私 Treasury完全在您自己的进程和基础设施中运行。它不会向作者发出任何出站调用，不收集任何遥测数据，也不附带任何分析数据。它永远不会通过网络获取价格，也永远不会调用模型。参见 [PRIVACY.md](./PRIVACY.md) 了解完整的数据处理通知，包括可选的文件加载器如何从磁盘读取计划和阶梯。 --- ## 许可证 在 **Apache License 2.0** 下许可。参见 [LICENSE](./LICENSE) 了解全文，参见 [NOTICE](./NOTICE) 了解归属和第三方组件许可证。您可以根据该许可证的条款（包括其专利授予和归属要求）使用、修改和分发代码。