# @aid-framework/spec 中文文档

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

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

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

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

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

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

## 中文简介

AID框架规格语言: spec v0.1 JSON Schema,一种能意识到位置的YAML分解器,以及结构验证.

## 安装

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

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

## README

# `@aid-framework/spec`

语言 [AID 框架](https://github.com/aid-framework/aid-framework)JSON斯克马,一个 位置意识 YAML 解析器和结构验证器。 此软件包决定文档是否 是一个 **结构良好** AID谱.

一个 AID 应用程序从一个声明的 YAML 文件开始 。 那个文件是真相的来源:模型,提示, 工具、检索、代理、输油管和电压被宣布一次,下游的一切——IR、代码 发电机,运行时间——就是从它衍生出来的.

```yaml
specVersion: "0.1"
project:
  name: support-copilot

models:
  fast:
    provider: openai-compatible
    model: gpt-4o-2024-08-06
    capabilities: [tool-calling, json-schema]

prompts:
  answer:
    template: |
      Answer the customer's question.
      Question: {{ question }}

pipelines:
  answer:
    steps:
      - generate:
          model: fast
          prompt: answer
          input:
            question: "{{ request.question }}"
```

## 安装

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

要求节点.js 24或更新. 与类型脚本申报一起作为无害环境管理运输.

## 它会做什么

-   **参数** YAML 输入一个键入文档,可以记住每个节点来自何处,因此一个诊断可以指向 `file:line:column` 而不是只命名一个密钥.
-   **验证** 用于编辑器自动完成的 Spec v0.1 JSON Schema 文档 和CI验证.
-   **讲述版本的真相.** 定义语言的构造,但无法使用此构造报告为 `spec/not-supported` 命名可以使用的版本——绝不是像打字一样读取的通用图案失败.

## 快开始

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

const { ok, diagnostics } = checkSpecText(source, { file: 'app/app.spec.yaml' });

if (!ok) {
  process.stderr.write(formatDiagnostics(diagnostics));
  process.exit(1);
}
```

`checkSpecText` 一步一步分析并验证. 故意短路:当YAML本身不能 解析、语义验证被跳过, 因为关于半解析文档的语义信息是噪音 .

向下工作一层 :

```ts
import { parseSpecDocument, validateSpec, formatDiagnostics } from '@aid-framework/spec';

const parsed = parseSpecDocument(source, { file: 'app/app.spec.yaml' });
const diagnostics = [
  ...parsed.diagnostics,
  ...validateSpec(parsed.value, { file: 'app/app.spec.yaml' }),
];
```

## 文件

| 节次 | 自兹 | 声明 |
| --- | --- | --- |
| `specVersion` | 0.1 数据 | 文件的语言版本 |
| `project` | 0.1 数据 | 应用程序的名称和元数据 |
| `types` | 0.1 数据 | 由提示、工具和管道共享的已命名的记录类型 |
| `models` | 0.1 数据 | 型号别名:提供者、被钉住的型号标识、能力、限度、成本 |
| `prompts` | 0.1 数据 | 已版本的快速模板及其输入的变量 |
| `tools` | 0.1 数据 | 工具合同、处理者、副作用和认证政策 |
| `stores` | 0.1 数据 | 向量储存申报 |
| `retrievers` | 0.1 数据 | 检索来源、分块、嵌入和排名 |
| `evals` | 0.1 数据 | 数据集、指标和门 |
| `pipelines` | 0.1 数据 | 可执行步骤图 |
| `agents` | 0.2 (韩语) | 代理环路、成套工具、转移/授权和预算 |
| `guardrails` | 0.2 (韩语) | 投入/产出政策及其执行 |
| `decisions` | 0.6 (中文(简体) ) | TypeSafe AI Jev 决定点:一个打出的问题,而不是聊天模式 |
| `memory` | 0.2 (韩语) | 对话、用户和全球内存范围 |
| `deployments` | 0.2 (韩语) | 触发声明、货币声明和流出声明 |

构建读取 spec 版本 `0.1` 结束 `0.9`。列出为 `0.2` 在一个0.1文件中被拒绝, 并有一个诊断 命名接受它的版本. `deployments[].image` 是一个0.4的构造和需求 `target: container`两种规则均在 `deployments.<id>.image`。 。 。 . `guardrails[].decision` 为 0.7 构造:它用 `choice` 决定而不是探测器政策,被拒绝 在较早的文件中。 A 类 `decision` eval 度量衡是一个0.8的构造:它用一个 已声明 `score` ,并在先前的文件中被驳回。 这个 `route` 步骤是一个0.9的构造: 从一个 `choice` 裁决的答复,并在先前的文件中被驳回.

## 管道步骤类型

管道步骤包含完全一种步骤。 验证人执行十二:

`generate`, (中文(简体) ), `retrieve`, (中文(简体) ), `tool`, (中文(简体) ), `emit`, (中文(简体) ), `branch`, (中文(简体) ), `route`, (中文(简体) ), `parallel`, (中文(简体) ), `map`, (中文(简体) ), `reduce`, (中文(简体) ), `rerank`, (中文(简体) ), `guard`, (中文(简体) ), `agent`。 。 。 .

`branch`, (中文(简体) ), `route`, (中文(简体) ), `parallel`, (中文(简体) ), `map` 财务报告和审定财务报表 `reduce` 它们是复合型——唯一可能搭起另一步骤的种类——和 入巢为界. `emit` 可能不会出现在复合步骤中,因为它会终止管道. `branch` 在认证的呼叫器上选择; `route` 通过询问 a 选择数据 `choice` 决定和决定 将答案匹配到 `on`。 。 。 .

本建筑中不推迟任何步骤类型. `human` 曾经 **退休人员** 而不是推迟: 人行即止是 代理人的财产(`agents[].humanInTheLoop`)),故旧拼法产生诊断性命名 替换“未知密钥”.

## 诊断

诊断是公共合同,而不是执行细节。 每个代码在 `DIAGNOSTIC_CODES` 被指称为 测试套件,由 `aid validate`,所以它是安全的匹配 在CI。 改头换面是一个突破性的变化.

```ts
import {
  countBySeverity, formatDiagnostics, hasErrors, sortDiagnostics,
} from '@aid-framework/spec';

const { ok, diagnostics } = checkSpecText(source, { file: 'app/app.spec.yaml' });
const failing = hasErrors(diagnostics); // only error severity fails a check; warnings do not
const counts = countBySeverity(diagnostics);
```

代码被命名为空格 `spec/*`有两个值得召唤,因为它们很容易交错:

-   `spec/not-supported` ——语言定义了这个构造,但这个构造还没有服务它. 讯息 命名该版本.
-   `spec/unknown-key` - 这把钥匙没有定义 几乎总是一个打字.

让他们保持区别是刻意的:一个“不支持”关于拼错的密钥的信息会让读者知道 寻找不存在的缺失特性.

## 杰森·斯克马

Schema是包导出,所以编辑器和外部工具使用验证器使用的同一种:

```json
{
  "yaml.schemas": {
    "./node_modules/@aid-framework/spec/dist/schema/spec.schema.json": "app.spec.yaml"
  }
}
```

```ts
import schema from '@aid-framework/spec/spec.schema.json' with { type: 'json' };
```

## 此软件包没有做什么

它孤立地验证了一份文件。 它执行 **没有** 跨部门分析:无优惠完整性,无 能力谈判,没有费用 理智,没有安全检查。 他们需要看整个节目 所以他们住在 建造时的大门 [`@aid-framework/ir`](https://www.npmjs.com/package/@aid-framework/ir)。 。 。 .

层为单向 : `spec ← ir ← generator-sdk ← generators ← cli`。这里没有导入以上包 这个.

## API 密码

| 导出 | 目的 |
| --- | --- |
| `checkSpecText(text, options?)` | 分步解析并验证; 返回 `{ ok, value, diagnostics }` |
| `parseSpecDocument(text, options?)` | YAML – 键入文档外加定位诊断 |
| `validateSpec(value, options?)` | 已分解文档的结构验证 |
| `specJsonSchema` | 光谱 v0. 1 JSON Schema 作为对象 |
| `SPEC_VERSION`, (中文(简体) ), `SPEC_VERSION_LATEST` | 版本 `aid init` 写入,最新版本读取 |
| `SUPPORTED_SPEC_VERSIONS`, (中文(简体) ), `SUPPORTED_SECTIONS` | 版本和章节词汇 |
| `SUPPORTED_STEP_KINDS`, (中文(简体) ), `COMPOSITE_STEP_KINDS`, (中文(简体) ), `RETIRED_STEP_KINDS` | 步骤类词汇 |
| `SECTION_MIN_VERSION` | 哪个版本先接受后面各节 |
| `DIAGNOSTIC_CODES`, (中文(简体) ), `SEVERITIES` | 诊断词汇 |
| `formatDiagnostic`, (中文(简体) ), `formatDiagnostics`, (中文(简体) ), `sortDiagnostics` | 渲染 |
| `countBySeverity`, (中文(简体) ), `hasErrors` | 检查 |
| `SourceDocument` | 带有节点位置的解析文档 |

## 许可证

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

## 常见问题

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

AID框架规格语言: spec v0\.1 JSON Schema,一种能意识到位置的YAML分解器,以及结构验证\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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