# @aid-framework/cli 中文文档

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

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

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

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

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

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

## 中文简介

这个 `aid` 命令:脚手架一个工程,验证它的光谱,生成它的代码,运行它的eval门.

## 安装

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

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

## README

# `@aid-framework/cli`

这个 `aid` 命令: 脚手架、 验证、 编译、 索引和评价来自单一声明的 AI 应用程序 光谱文件 .

你写 `app/app.spec.yaml`。 。 。 . `aid` 检查它,将其编成一个可运行的服务, 并打开它的行为. 在生成的树上,没有任何东西是手写的,你写的也从未被覆盖过.

## 安装

```sh
npm install --save-dev @aid-framework/cli
```

要求节点.js 24或更新. 或运行它而不安装:

```sh
npx @aid-framework/cli --help
```

## 快开始

```sh
npx aid init my-app
cd my-app
npx aid validate
npx aid gen
```

3个命令,生成的应用程序存在:

```text
my-app/
  README.md
  app/
    app.spec.yaml
    business/         ← yours: prompts, tool handlers, domain logic
    generated/        ← the compiler's: never hand-edit
    aid.manifest.json ← provenance and per-file hashes
```

### 为它服务

生成器拥有路径;应用程序决定挂载什么以及如何运行. 这个切入点是 你的,还有几行.. `app/main.py`数字 :

```python
from fastapi import FastAPI

from app.generated.routes.answer_ticket import answer_ticket_router

app = FastAPI(title="my-app", version="0.1.0")
app.include_router(answer_ticket_router)
```

安装运行时间和服务器,然后运行 :

```sh
pip install aid-runtime-python "fastapi>=0.115,<1" "uvicorn>=0.30,<1"
uvicorn app.main:app --reload
```

`aid gen` 从不写 `main.py` 或一个 `pyproject.toml`: 安装和包装是应用决定,a 猜到他们的发电机 会在下一场比赛中压倒你的选择.

启动光谱宣布没有管道,所以是新鲜的 `init` 生成结构,但没有路径。 添加一个管道 改为 `app/app.spec.yaml` 和再生, 以及一个路由器模块出现在HTTP服务管道上.

## 图标

| 命令 | 它会做什么 |
| --- | --- |
| `aid init [dir]` | 脚手架工程:一个启动点和一个README |
| `aid validate [spec]` | 解析光谱, 构建 IR, 运行每个建时门 |
| `aid gen [spec]` | 编译谱并调和树与它 |
| `aid ingest [spec]` | 将检索表索引到存储处 |
| `aid eval [spec]` | 运行 eval 闸门,或者记录它测量的基线 |
| `aid doctor [spec]` | 分析树与谱:漂移,出处和版本不匹配,缺失和过时生成的文件. 报告; 无文字 |

每个命令都接受 `--help` 对其本身的选择和 `--json` 用于机器可读输出.

## 退出代码

退出代码是合同,因为这是CI的意思:

| 代码 | 含义 |
| --- | --- |
| `0` | 按照要求,该项目 |
| `1` | 光谱,门,目标,或者工作树说不 |
| `2` | 援引错误,或者CLI在内部失败 |

`1` 财务报告和审定财务报表 `2` 有意的区别。 由 spec 问题引起的红色建筑在 spec 中固定; 红色建筑 由下列人员造成: `2` 在引用中被固定或是一个错误。 折叠它们会把人送到错误的文件中.

## `--json`

每个命令都回答 `--json` 与 **一个** JSON的文件在Stdout。 人能读到的文本和进展 到斯德尔,所以 `aid validate --json | jq` 工作不用过滤.

```sh
npx aid validate --json | jq -r '.diagnostics[] | select(.severity=="error") | .code'
```

## 光谱路径

没有参数,命令读取 `app/app.spec.yaml` - 路径 `aid init` 创建生成器和路径 编入. 通过一个路径来覆盖它 :

```sh
npx aid validate path/to/other.spec.yaml
```

## 目标

一个Spec宣布它的目标,和 `aid gen` 一次发出一个目标:

```yaml
project:
  name: my-app
  targets:
    - py-fastapi
    - ts-vercel
```

```sh
npx aid gen                        # the first declared target
npx aid gen --target ts-vercel     # any other declared target
```

`--target` 在宣布的光谱目标中选择;它不能发明光谱。 给目标命名时, spec 不 宣告失败 `target-unsupported` 并列出申报的内容。 这在目的上更为严格——一个例子是 并且默默生成一个它没有要求的堆栈 将使这个谱系成为谎言.

| 目标 | 输出 | 运行时间 |
| --- | --- | --- |
| `py-fastapi` | FastAPI 服务, Pydantic 模型 | [`aid-runtime-python`](https://pypi.org/project/aid-runtime-python/) |
| `ts-vercel` | Next.js / Vercel 函数, Zod 模型 | [`@aid-framework/runtime`](https://www.npmjs.com/package/@aid-framework/runtime) |

## `aid gen`: 规划,然后调和

`gen` 绝不盲目地写作。 它计划了完整的文件集 从IR, 比照该计划树 然后调和.

| 级别 | 拥有者 | 在再生时 |
| --- | --- | --- |
| `app/generated/` | 编译器 | 覆写——永远不要手写 |
| `app/business/` | 你们 | 如果缺少, 则从未触碰过 |

不写任何东西的预览 :

```sh
npx aid gen --dry-run
```

```text
py-fastapi: dry run, 16 created, 0 updated, 0 unchanged, 0 kept
created:
  app/business/prompts/__init__.py
  app/generated/deps.py
  app/generated/requests.py
  app/generated/schemas.py
  ...
```

计数是 `created` 编号 : `updated` 编号 : `unchanged` 编号 : `kept`,所以没有再生 说,而不是寻找 像进步.

### 当生成的文件被手工编辑时

`gen` 记录每个文件的 SHA-256 `aid.manifest.json`如为 `generated/` 磁盘上的文件无 更符合其记录的散列, 一个人类编辑 `gen` **拒绝覆盖** 这个 它写了新的 内容旁边是 `<path>.aid-rej` 并报告与两者的冲突.

选择权在于你明确:

```sh
npx aid gen --force     # discard the hand edit and overwrite
```

或移动文件到 `business/` 并点 商业接合它。 无论哪种方式,编辑都不沉默地丢失, 这才是最重要的故障模式:一个无条件覆盖其唯一信号的生成器 有人类不同意它.

## `aid eval`: 游戏行为,而不是字节

生成的服务因运行而异——模型不具有决定性,假想以其他方式产生测试 要么永远是红色的 要么是衡量什么. `aid eval` 因此,取样和比较分布:

```sh
npx aid eval --record     # record a baseline from the current behaviour
npx aid eval              # gate the current behaviour against it
```

## 国家领导才能不是

这不是一个运行的时间。 它读取光谱,编译它,并报告;生成的应用程序导入运行时包 在没有安装CLI的情况下运行. `@aid-framework/cli` 是一个 `devDependency` 确切地说 理由,你觉得呢.

## API 密码

CLI 也可以导入, 因此一个构建工具可以在没有子进程的情况下驱动它:

```ts
import { main, runCli } from '@aid-framework/cli';

process.exitCode = await runCli(process.argv.slice(2));
```

| 导出 | 目的 |
| --- | --- |
| `runCli(argv)` | 运行命令并返回其退出代码 |
| `main` | 命令调度器 |
| `EXIT_OK`, (中文(简体) ), `EXIT_REJECTED`, (中文(简体) ), `EXIT_USAGE` | 退出码常数( E)`0`, (中文(简体) ), `1`, (中文(简体) ), `2`(中文(简体) ) |

## 相关软件包

-   [`@aid-framework/spec`](https://www.npmjs.com/package/@aid-framework/spec) - 语种语言
-   [`@aid-framework/ir`](https://www.npmjs.com/package/@aid-framework/ir) - IR及其建造时的大门
-   [`@aid-framework/generator-py-fastapi`](https://www.npmjs.com/package/@aid-framework/generator-py-fastapi)
-   [`@aid-framework/generator-ts-vercel`](https://www.npmjs.com/package/@aid-framework/generator-ts-vercel)

## 许可证

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

## 常见问题

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

这个 aid 命令:脚手架一个工程,验证它的光谱,生成它的代码,运行它的eval门\.

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

在项目目录运行 npm install @aid-framework/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 aid，可以用 npx aid 直接运行。

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

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

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

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

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

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

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

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

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

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

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

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