# @aid-framework/ir 中文文档

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

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

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

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

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

- 包体积（解压后）：749 kB，130 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：1 个
- 首次发布：2026-10-31T15:13:33.633Z
- 最新版本发布：2026-11-03T07:44:46.542Z
- 近 30 天下载量：12232（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

AID框架中间代表: IR v0.1形状, spec-to-IR 构建器, 6个构建时门, PolicyExpr 剖析器, 和 Canonical JSON 序列化.

## 安装

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

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

## README

# `@aid-framework/ir`

中间代表 [AID 框架](https://github.com/aid-framework/aid-framework): 一个 规范化,堆栈独立,版本化的应用程序形式,每个代码生成器都使用.

发电机从不读字 此软件包解决 spec **一次** 进入一个IR, 所以一个Python目标和一个 TypeScript 目标正在查看相同的程序——相同的名称,相同的默认,相同的解析 参考文献.

```text
spec.yaml ──buildIR──▶ IR ──runGates──▶ buildable ──▶ generator plan ──▶ code
```

## 安装

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

要求节点.js 24或更新. 仅取决于 `@aid-framework/spec`。 。 。 .

## 快开始

```ts
import { checkSpecText, formatDiagnostics } from '@aid-framework/spec';
import { buildIR, runGates, serializeIR } from '@aid-framework/ir';

const checked = checkSpecText(source, { file: 'app/app.spec.yaml' });
if (!checked.ok) throw new Error(formatDiagnostics(checked.diagnostics));

const built = buildIR(checked.value, { file: 'app/app.spec.yaml' });
if (built.diagnostics.some((d) => d.severity === 'error')) {
  throw new Error(formatDiagnostics(built.diagnostics));
}

const gates = runGates(built.ir, { file: 'app/app.spec.yaml' });
if (!gates.ok) throw new Error(formatDiagnostics(gates.diagnostics));

const canonical = serializeIR(built.ir);
```

`buildIR` 急切地解决每一个类型、模型、迅速和工具参考,实现每一个默认,并产生 每一个稳定的身份都来自身份而不是内容——所以编辑一个提示不会重新编号一个无关的 输油管.

## 爱尔兰

`IR_VERSION` 实值 `"0.1.0"`。 。 。 . `specVersion` 所以消费者总是能分辨 光谱修正产生了IR. 两者是独立的:两者都不意味着另一方.

一个IR总是携带所有20个顶级密钥,即使一个收藏是空的:

```text
irVersion, specVersion, project, types, models, prompts, tools, retrievers, embeddings,
stores, memory, agents, pipelines, evals, guardrails, decisions, deployments,
observability, runtime, requiredCapabilities
```

### 空藏是契约

这里的空数组不是“ 丢失” —— 而是声明 。 藏品是现成的,是计划要求的 即使是空的,所以以后的版本也可以在不碰一个消费者的情况下填写一个:

-   `agents`, (中文(简体) ), `guardrails`, (中文(简体) ), `memory`, (中文(简体) ), `deployments`, (中文(简体) ), `decisions` ——由 spec 语言声明但被本文件未使用.
-   `embeddings` - 完全没有谱分 一个 spec 宣告嵌入能力通过给出模型 `embeddings` 能力,并指向一个检索器 它,所以这个收藏 **来源** 从内容。 空意味着 应用程序没有嵌入.

`observability` 财务报告和审定财务报表 `runtime` 是带有默认而非数组的物体: 跟踪和运行时间描述符 命名纯同步控制流.

## 建造时间的大门

盖茨在发出单一字节代码之前,决定一个IR是否可以被构建. 有十六个,一个跑 报告 `runGates`。它们都发出诊断,而不是扔出, 以同样的编译器风格形状 `@aid-framework/spec`,所以一个用户会得到一个报告,无论哪个层拒绝输入.

| 门 | 拒绝 |
| --- | --- |
| `referential` | 无法解析的类型或参考文献,错误类型的参考文献,与模板不匹配的快捷变量,未定义或重复的步骤绑定,错误的eval目标,倒置周期 |
| `normalize` | 用于生成器发明的所隐含的值, 此构件的提供者不服务, 参数高于模型的极限 |
| `capability` | 目标宣布没有能力,目标不明,词汇之外的能力,目标不宣布的必要能力 |
| `cost` | 预算被宣布为无价模式。 预算之上的估计数和未定价、未编入预算的模型的警告 |
| `security` | 一个没有认证策略的写入或破坏性工具,一个没有确认的破坏性工具,一个未编辑的痕量配置,一个HTTP路径到达一个没有认证的写入 |
| `eval-coverage` | 无 —— 当一个HTTP 服务的管道没有CI-gate eval时警告 |
| `agents/refs-resolve` | 指定不存在的工具、 即时工具或模型的代理 |
| `agents/handoff-cycles` | 可再进入代理人的转让或授权图表 |
| `agents/budgets` | 无法兑现的代理预算 |
| `agents/budget-degrade` | `onBudgetExhausted: degrade` 没有严格便宜的别名可以下到 |
| `guardrails/coverage` | 一个不附在输入或输出上的护栏,它可以对 |
| `guardrails/policies` | 不解析或命名未知内置的护卫策略 |
| `hitl/side-effects` | 人类在跳伞中暂停 守护它实际上无法承受的副作用 |
| `memory/refs` | 无法解决已宣布范围的内存参考 |
| `deploy/streaming` | 宣布目标流的部署无法发射 |
| `orchestration/deepagents` | 代理引擎声明运行时间无法遵守 |

**禁忌是明确的.** 检查此建筑是否真的无法执行 `suppressed` 有说明的 而不是被悄悄地跳过,因为跳出支票和过路支票看起来都是一样的 外边.

能力设置闸门检查来自IR本身的内容并写回到 `requiredCapabilities`,所以生成器读取的值是实际检查的值:

```ts
const result = runGates(ir, {
  targetCapabilities: {
    'py-fastapi': ['http-trigger', 'json-schema', 'otel'],
  },
});

result.ok;         // false when any gate emitted an error
result.byGate;     // per-gate diagnostics
result.suppressed; // what was not enforced, and why
```

## 政策Expr

工具认证策略以小表达式语言写出. 这个包裹把他们分为一个简单的JSON AST,所以 aST可以活在IR中,序列化地将神话化,并被任何目标用任何语言评价.

```text
or         := and ('or' and)*
and        := comparison ('and' comparison)*
comparison := unary (('==' | '!=' | '<' | '<=' | '>' | '>=') unary)?
unary      := 'not' unary | primary
primary    := 'true' | 'false' | builtin '(' args ')' | '(' or ')'
builtin    := hasRole | hasScope | isAuthenticated
```

```ts
import { parsePolicyExpr, formatPolicyExpr } from '@aid-framework/ir';

const parsed = parsePolicyExpr("hasRole('admin') or hasScope('tickets:write')");
if (parsed.ok) console.log(formatPolicyExpr(parsed.value));
```

解析是一个总函数:它返回 AST 或定位诊断,从不丢弃例外. 此语法之外的任何事物都是验证错误,包括未知的内建. 这是失败的封闭规则—— 无法评估的运行时间政策绝不能被视为 `true`。 。 。 .

Eval上游使用具有相同属性的伴生语法(`parsePredicateExpr`, (中文(简体) ), `PREDICATE_BUILTINS`),这样 大门条件与认证政策一样严格.

## 条形序列化

`serializeIR` 所以再生是可复制的 金色文件是稳定的:

-   对象键排序, LF 结尾, 双相距缩进, 正好是一条正后方的新行;
-   没有 `NaN`, (中文(简体) ), `Infinity` 或者说 `undefined`; 缺漏字段而不是写入为 `null`· ;
-   保留了数组顺序,因为数组的顺序是有意义的,对象的顺序不是.

两种仅以按键顺序或白空相差的文档因此产生字节-等同的IR.

## 模型目录

该目录是模型定价和限值的构建时间的真理来源,用于 `cost` 财务报告和审定财务报表 `normalize` 大门.

```ts
import {
  CATALOG_VERSION, catalogCostProfile, catalogCostProfiles, catalogModel,
} from '@aid-framework/ir';
```

目录 JSON 也导出为 `@aid-framework/ir/catalog/models.json`,而IR计划作为 `@aid-framework/ir/ir.schema.json`。 。 。 .

## 能力

```ts
import {
  DEFERRED_CAPABILITIES, MODEL_CAPABILITIES, REQUIRED_CAPABILITIES,
  deriveRequiredCapabilities, isRequiredCapability,
} from '@aid-framework/ir';
```

`deriveRequiredCapabilities(ir)` 返回IR本身内容所需的能力,按词汇顺序排列. `runGates` 所以闸门和发电机 从来不会对需要什么有异议.

## API 密码

| 导出 | 目的 |
| --- | --- |
| `buildIR(value, options?)` | 标本值 `{ ir, diagnostics }` |
| `runGates(ir, options?)` | 运行所有门; 返回 `{ ok, diagnostics, suppressed, byGate }` |
| `GATES` | 大门登记,按执行顺序 |
| `serializeIR(ir)`, (中文(简体) ), `canonicalJson(value)` | 巨型 JSON 渲染 |
| `IR_VERSION` | IR 形状版本 (`0.1.0`(中文(简体) ) |
| `IR_COLLECTIONS`, (中文(简体) ), `IR_ONLY_COLLECTIONS` | 收藏词汇 |
| `deriveRequiredCapabilities(ir)` | 内容需要的能力 |
| `REQUIRED_CAPABILITIES`, (中文(简体) ), `MODEL_CAPABILITIES`, (中文(简体) ), `DEFERRED_CAPABILITIES` | 能力词汇表 |
| `parsePolicyExpr`, (中文(简体) ), `formatPolicyExpr`, (中文(简体) ), `POLICY_BUILTINS` | 工具自动政策语言 |
| `parsePredicateExpr`, (中文(简体) ), `formatPredicateExpr`, (中文(简体) ), `PREDICATE_BUILTINS` | Eval 上游语言 |
| `catalogModel`, (中文(简体) ), `catalogCostProfile`, (中文(简体) ), `catalogCostProfiles`, (中文(简体) ), `CATALOG_VERSION` | 示范定价和限额 |

## 许可证

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

## 常见问题

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

AID框架中间代表: IR v0\.1形状, spec-to-IR 构建器, 6个构建时门, PolicyExpr 剖析器, 和 Canonical JSON 序列化\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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