# @aid-framework/runtime 中文文档

规范地址：https://npmcn.com/package/%40aid-framework/runtime/

版本：0\.1\.98
npm 元数据更新时间：2026-11-03T07:44:41.054Z
中文译文更新时间：2026-11-06T01:14:01.367Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aid-framework/runtime
原文对照：https://npmcn.com/package/%40aid-framework/runtime/?lang=original
源码仓库：https://github.com/aid-framework/aid-framework

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.6 MB，216 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：2 个
- peer 依赖：langchain 1\.5\.19，langsmith 0\.11\.1，deepagents 1\.16\.0，@langchain/core 1\.3\.0，@langchain/langgraph 1\.5\.3，@langchain/langgraph-sdk 1\.12\.8，@langchain/langgraph-checkpoint 1\.2\.1
- 首次发布：2026-10-31T15:13:30.091Z
- 最新版本发布：2026-11-03T07:44:40.695Z
- 近 30 天下载量：10061（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

TypeScript 的 AID 运行时间:被绑定-模型网关,即时注册,工具发送,管道,结构输出,eval门和检索.

## 安装

```sh
npm install @aid-framework/runtime
```

也可以使用：`pnpm add @aid-framework/runtime`、`yarn add @aid-framework/runtime`、`bun add @aid-framework/runtime`

## README

# `@aid-framework/runtime`

类型脚本运行时间 [AID 框架](https://github.com/aid-framework/aid-framework): 图书馆 a 运行时生成应用程序调用 。 固定一个模型,运行一个快速,呼叫一个工具,追踪它, 留在预算, 并证明质量没有倒退.

生成代码为薄胶. 这就是行为存在的地方,这就是为什么它是人类的正常依赖 生成了应用程序, 不是编译器的一部分 .

## 安装

```sh
npm install @aid-framework/runtime
```

要求节点.js 24或更新. 船舶作为无害环境管理,包括类型脚本申报. `zod` 用于结构化输出和 没有别的了.

## 快开始

一个网关解决了标定模型的别名,执行预算,记录成本,并打开每个呼叫的间隔:

```ts
import {
  Budget, ModelGateway, OpenAICompatibleProvider, PinnedModel,
} from '@aid-framework/runtime';

const gateway = new ModelGateway({
  providers: {
    'openai-compatible': new OpenAICompatibleProvider({ apiKey: process.env.OPENAI_API_KEY }),
  },
  aliases: {
    small: new PinnedModel({
      alias: 'small',
      spec: {
        name: 'gpt-4o-2024-08-06',
        provider: 'openai-compatible',
        contextWindow: 128_000,
        maxOutputTokens: 4_096,
        cost: { inputPer1kUsd: 0.0025, outputPer1kUsd: 0.01 },
      },
    }),
  },
  budget: new Budget({ maxUsd: 5, scope: 'nightly' }),
});

const result = await gateway.generate('small', { prompt: 'hello' });

result.text;
result.usage;
result.costUsd;
result.attempts;  // every alias tried, in order
result.fellBack;
```

**一个别名可以解决一个精确的,被钉住的模型 ID.** 这不是化妆品:一个基线记录与 `gpt-4o` 如果别名漂浮到下一次运行的后期快照,则无意义. 因此,一个未知的别名引起 `UnknownModelAliasError` 而不是倒向提供者违约.

## 管道

控制流量为平版ASync TypeScript. 没有图形引擎和管弦乐框架:一个生成的应用程序 是普通代码,容易读取, 步入和测试.

```ts
import { Pipeline, PipelineContext } from '@aid-framework/runtime';

const pipeline = new Pipeline([
  { name: 'load', run: (ctx) => ctx.withValues({ question: ctx.require('request').question }) },
  { name: 'answer', run: async (ctx) => ({ answer: await ask(ctx.require('question')) }) },
]);

const result = await pipeline.run(new PipelineContext({ request }));
```

`PipelineContext` 不可改变 `get` 编号 : `require` 编号 : `withValues` - 所以一步不能变异 什么早先的一步 观察到,一个失败的运行状态 仍然可以检查。 每一步都在自己的跨度中运行;一个会丢出终止的跨度 与原错误连锁运行; `StopPipeline` 是支持的提前退出。 管道拒绝空的 或建筑上的重复命名步骤列表.

综合步骤 - `branch`, (中文(简体) ), `parallel`, (中文(简体) ), `mapStep`, (中文(简体) ), `reduceStep` ——作为阶地建造者提供,范围有: 筑巢(`MAX_STEP_DEPTH`) (中文(简体) ).

## 包裹里有什么

| 区域 | 出口 | 页:1 |
| --- | --- | --- |
| 类型 | `Message`, (中文(简体) ), `ModelSpec`, (中文(简体) ), `PinnedModel`, (中文(简体) ), `TokenUsage`, (中文(简体) ), `CompletionRequest`, (中文(简体) ), `CompletionResponse`, (中文(简体) ), `Capability` | 词汇表,其他的都被输入了 |
| 错误 | `AidRuntimeError` 和25个子类 | 一个基地,所以一个应用 捕捉框架拒绝在一个地方 |
| 网关 | `ModelGateway`, (中文(简体) ), `estimateUsage` | 固定化名、能力谈判、命令后退、预算飞行前 |
| 供应商 | `OpenAICompatibleProvider`, (中文(简体) ), `FakeProvider`, (中文(简体) ), `supports` | 一个HTTP适配器,一个确定性的假,加上 `Provider` 协议 |
| 决定 | `DecisionClient`, (中文(简体) ), `DecisionQuestion`, (中文(简体) ), `decisionKey` | TypeSafe AI (Jev) 键入的决定 : `choice`, (中文(简体) ), `score`,以及 `noul` 答题 |
| 费用 | `Budget`, (中文(简体) ), `CostLedger`, (中文(简体) ), `estimateCostUsd` | 预调执行、逐笔分类账分录、支出摘要 |
| 追踪 | `getTracer`, (中文(简体) ), `llmSpan`, (中文(简体) ), `recordUsage`, (中文(简体) ), `recordCost`, (中文(简体) ), `recordException` | OTel GenAI 语义公约; AID 值为空格 `aid.*` |
| 提示 | `PromptRegistry`, (中文(简体) ), `PromptTemplate`, (中文(简体) ), `Example` | 版本登记册、打字、几发装配 |
| 工具 | `Tool`, (中文(简体) ), `ToolExecutor`, (中文(简体) ), `validateArguments` | Schema - 验证了 JSON-Schema 子集的发送 |
| 结构化产出 | `buildAgent`, (中文(简体) ), `parseStructured`, (中文(简体) ), `runStructured`, (中文(简体) ), `repairPrompt` | 在 Zod 计划上进行解析/修复循环 |
| 管道 | `Pipeline`, (中文(简体) ), `PipelineContext`, (中文(简体) ), `StopPipeline`, (中文(简体) ), `branch`, (中文(简体) ), `parallel`, (中文(简体) ), `mapStep`, (中文(简体) ), `reduceStep` | 在不可改变的上下文中递减 |
| 货币 | `ConcurrencyLimiter`, (中文(简体) ), `holdsSlot` | 包括综合步骤在内的飞行中定界工作 |
| 政策 | `evaluatePolicy`, (中文(简体) ), `Principal`, (中文(简体) ), `POLICY_BUILTINS` | 工具自动表达式, 已关闭 |
| 代理循环 | `agents/*` | 原生回路:转接对代表,预算,分解,内存,HITL检查站 |
| 爱德华 | `Dataset`, (中文(简体) ), `EvalCase`, (中文(简体) ), `runEvaluation`, (中文(简体) ), `BaselineGate`, (中文(简体) ), `EvalBaseline` | N 运行的采样和统计门 |
| 计量 | `ExactMatch`, (中文(简体) ), `NormalizedContains`, (中文(简体) ), `JsonSchemaValid`, (中文(简体) ), `LlmJudge` | 加号 `defaultMetrics` 财务报告和审定财务报表 `metricNames` |
| 检索 | `Retriever`, (中文(简体) ), `RetrievalGate`, (中文(简体) ), `chunkDocument`, (中文(简体) ), `openConnector`, (中文(简体) ), `createStore`, (中文(简体) ), `fuse` | 连接器、块器、嵌入器、存储器、混合搜索、重排、引用 |

## 定型和能力检查

`gateway.require(alias, capabilities)` 检查 **两者** 侧-模型宣布的能力和 适配器的串行能力——并返回被钉住的模型. 一个支持工具调用后面的模型 不序列化工具定义的适配器不能调用工具,而且 `CapabilityMismatchError` 名称是什么 而不是后来在提供者中失败.

`generate(alias, request, { fallbacks })` 尝试别名,然后每个倒置 **顺序**退缩 命令,不附带条件,以及 `result.attempts` 报告实际尝试过的东西.

## 决定不是聊天

`DecisionClient` 拨打 Safe AI 的 Jev (`POST /v1/systemone`),它需要状态加打出的问题和 返回已键入的答案,而不是表达式。 故意不进去 `providers/`: 每个提供方都有地图 消息到文本,而Jev没有文本表面,所以管道不能选择它作为写出答案的模型.

```ts
import { DecisionClient, DecisionQuestion } from '@aid-framework/runtime';

const client = new DecisionClient();
const response = await client.decide({
  model: 'jev-1.14.0',
  state: { message },
  questions: {
    triage: new DecisionQuestion({
      type: 'choice',
      instructions: 'Which team should handle this',
      criteria: ['billing', 'technical'],
    }),
  },
});
response.answers.triage?.choice;
```

关键是 `TYPESAFE_API_KEY` (Vercel的拼写, `TYPESAFE_AI_API_KEY`(a) 接受; `TYPESAFE_BASE_URL` 覆盖主机 。 两个规则比看起来更重要:a `noul` 回答带 `noul` 财务报告和审定财务报表 **没有信心 全部字段**,因此一个信任分支必须拒绝,而不是默认为零 `decide({ ..., reproducible: true })` 拒绝移动的别名 `jev-latest` 财务报告和审定财务报表 `jev-preview`,这是什么 eval评分需要。 只有429/529被重审,荣誉 `retry-after`。 。 。 .

## Evals 统计大门,而不是平等

一个模型是 _预期_ 因此,一个衡量标准 对比两个运行 平等要么总是红色,要么 测量什么也没有。 非决定主义是大门建造来容忍的财产:

```ts
import { BaselineGate, runEvaluation, ExactMatch, defaultMetrics } from '@aid-framework/runtime';

const run = await runEvaluation(dataset, runner, defaultMetrics(), { runs: 5 });
const verdict = new BaselineGate(thresholds).evaluate(run, baseline);

verdict.passed;
verdict.metrics; // per-metric z-score, allowance and outcome
```

`runEvaluation` 运行者样本 **N倍数** 并报告每一次运行的计量手段,所以一次不幸运行不会 决定判决. `EvalBaseline.fromRun(run)` 存储样本数、平均值和分布; 门 比较单侧正常测试。 一公尺的通行证 `minMean`,通过留在内部 `maxRegression` 或只在取样噪声范围内进行回落.

`LlmJudge` 被执行而从未要求使用 CI : 取决于内部一个非决定性呼叫的门 你试图信任的门 是设计所避免的问题.

算术与 Python 运行时间完全吻合—— 相同的 z 临界表, 相同的基线比较, 相同的 同样的抽样语义——因为每个语言的门的统计不同,会让TypeScript 回归通过 Python 基线 .

## 检索

`retrieval/*` 由IR驱动 : `bindingFromSpec(retriever, { embedding, store })` 折叠IR的 `retrievers`, (中文(简体) ), `embeddings` 财务报告和审定财务报表 `stores` 输入为 1 `RetrieverBinding`,哪个a `Retriever` 然后摄入和搜索.

Chunk ids是内容散列的,所以重新摄取同一种输入产生同一种ids和没有op diff. `FakeDeterministicEmbedder` 与摇摆128和 `chunkIdFor` 与SHA-256, 这是允许检索的 门在CI运行 没有网络和密钥.

`RetrievalMetric` (单位:千美元)`RecallAtK`, (中文(简体) ), `MeanReciprocalRank`, (中文(简体) ), `CitationGrounding`)是独立于 `Metric`, (中文(简体) ), 因为检索得分 a _检索集_ 而不是单弦。 检索是通过 `RetrievalGate.sample(...)` 变成标准 `EvalRun` 以不变者判断 `BaselineGate`。 。 。 .

## 明确的限制

-   **已宣布未实施流程.** `Capability` 包括它,这样一个spec可以要求它和一个构建时间 门可以检查; 呼叫 `ModelGateway.stream` 筹集 `FeatureDeferredError`。运输是 只有请求/答复.
-   **一个HTTP供应商和一个假货.** 供应商覆盖面的宽度是后来关切的一个问题;狭义、正确的接缝是: 价值超过一个宽浅的.
-   `PgVectorStore` 需要活着 `vector` 扩展并不会由 CI 行使; 内存商店带有 存储测试,两者共享相同 `VectorStore` 礼宾和 `similarity` 语义.

## API 密码

完整的表面是包名的导出;上方的表格是地图. 蓄意的不对称 python 运行时间是 `providers/fake.ts`,其准确性来自SHA-256散列 `seed:index:prompt` 而不是CPython的Mersenne Twister, 因为弦播种有一个CPython 执行细节,无便携式等同物。 画图仍然是决定性的,每个调用都不同 索引,即闸门所依赖的属性.

## 相关软件包

-   [`aid-runtime-python`](https://pypi.org/project/aid-runtime-python/) – Python 相同的运行时间
-   [`@aid-framework/generator-ts-vercel`](https://www.npmjs.com/package/@aid-framework/generator-ts-vercel) - 那个 使用此运行时间发送应用程序的生成器
-   [`@aid-framework/cli`](https://www.npmjs.com/package/@aid-framework/cli) —— 说 `aid`

## 许可证

[阿帕奇 - 2.0](https://github.com/aid-framework/aid-framework/blob/main/LICENSE)。由 AID 框架生成的代码是 不受该许可证的限制.

## 常见问题

### @aid-framework/runtime 是什么？

TypeScript 的 AID 运行时间:被绑定-模型网关,即时注册,工具发送,管道,结构输出,eval门和检索\.

### 如何安装 @aid-framework/runtime？

在项目目录运行 npm install @aid-framework/runtime，或使用 pnpm add / yarn add / bun add。

### @aid-framework/runtime 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aid-framework/runtime 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aid-framework/runtime 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aid-framework/runtime 可以商用吗？

@aid-framework/runtime 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aid-framework/runtime 的下载量有多少？

根据 npm 官方下载统计，@aid-framework/runtime 在 2026/10/06 – 2026/11/04 这 30 天内被下载 10,061 次，日均约 335 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aid-framework/runtime 还在维护吗？

最新版本 0\.1\.98 发布于 2026/11/03（2 天前）；至今共发布 52 个版本，其中过去 12 个月发布了 52 个；首次发布于 2026/10/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。