# @aaac/toolchain 中文文档

规范地址：https://npmcn.com/package/%40aaac/toolchain/

版本：0\.3\.0
npm 元数据更新时间：2026-10-20T05:53:27.321Z
中文译文更新时间：2026-11-06T02:25:48.057Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40aaac/toolchain
原文对照：https://npmcn.com/package/%40aaac/toolchain/?lang=original
项目主页：https://github.com/foo-log-inc/aaac#readme
源码仓库：https://github.com/foo-log-inc/aaac

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

- 包体积（解压后）：65 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：3 个
- 首次发布：2026-06-08T13:23:39.840Z
- 最新版本发布：2026-10-20T05:53:27.122Z
- 近 30 天下载量：6439（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

用于装有文物的工具申报的工具链合同定义

## 安装

```sh
npm install @aaac/toolchain
```

也可以使用：`pnpm add @aaac/toolchain`、`yarn add @aaac/toolchain`、`bun add @aaac/toolchain`

## README

# @aaac/工具链

受人工活性约束的工具链声明——定义了哪些工具可以操作哪些文物.

## 安装

```bash
npm install @aaac/toolchain
```

## 它会做什么

`toolchain-contracts` 是一个声明式合同层, 绑定 **工具 文物**. 每一个工具链条目都宣布其消费和生产的内容,从而能够进行静态验证和数据流动,跨越文物合同、代理合同和工具链合同.

## 快速启动

创建 `toolchain-contracts.yaml`数字 :

```yaml
schema: aaac/toolchain/0.1

system:
  id: my-project

toolchains:
  prettier:
    kind: library
    module: prettier
    artifacts:
      consumes: [source-code]
      produces: [source-code]
    operations: [format]

  eslint:
    kind: cli
    command: npx eslint --fix
    artifacts:
      consumes: [source-code]
      produces: [source-code]

  speckeeper:
    kind: component
    component_contract: ./speckeeper.component.yaml
    artifacts:
      consumes: [spec-md, codebase]
      produces: [conformance-report]
```

验证它:

```bash
npx aaac-toolchain validate toolchain-contracts.yaml
```

## DSL 示马

| 外地 | 说明 |
| --- | --- |
| `schema` | Schema版本(例如:. `aaac/toolchain/0.1`(中文(简体) ) |
| `system` | 项目身份`id`选项 `name`(中文(简体) ) |
| `toolchains` | 工具链 ID-工具链定义地图 |

每个工具链条目 :

| 外地 | 说明 |
| --- | --- |
| `kind` | 装订类型 : `library`, (中文(简体) ), `cli`,或 `component` |
| `module` | npm 软件包名称( 需要 `library`(中文(简体) ) |
| `command` | 贝壳命令(用于 `cli` 否时 `cli_contract`(中文(简体) ) |
| `cli_contract` | Cli-contracts YAML 路径( 用于 `cli`(中文(简体) ) |
| `component_contract` | 此工具链包含的组件合同路径( 需要 `component`(中文(简体) ) |
| `artifacts` | `consumes` 财务报告和审定财务报表 `produces` 文物标识 |
| `operations` | 操作名称, 在命名空间 `component_contract` 名称——该组件设定时的操作,工具自己的动词(`format`, (中文(简体) ), `lint`当它不是 |

## 类型

| 仁爱 | 含义 | 需要的字段 |
| --- | --- | --- |
| `library` | 在程序上引用 npm 软件包 | `module` |
| `cli` | 外部 CLI 工具 | `command` 或者说 `cli_contract` |
| `component` | AaaC部分有自己的合同 | `component_contract` |

## `$refs`

使用工具链定义分割文件 `$refs`数字 :

```yaml
schema: aaac/toolchain/0.1

system:
  id: my-project

toolchains:
  inline-tool:
    kind: library
    module: inline-lib
    artifacts:
      consumes: [source-code]

$refs:
  - ./formatting.yaml
  - ./linting.yaml
```

参考文件包含额外的 `toolchains` 合并到根文档中的条目。 跨文件的复制工具链ID被拒绝 .

## CLI 命令

### `aaac-toolchain validate`

验证工具链-合同文件的图案和语义规则.

```bash
npx aaac-toolchain validate toolchain-contracts.yaml

# Optional: check artifact IDs against a known set
npx aaac-toolchain validate toolchain-contracts.yaml \
  --artifact-ids source-code spec-md codebase conformance-report
```

### `aaac-toolchain lint`

检查合同层的数据流完整性.

```bash
npx aaac-toolchain lint toolchain-contracts.yaml \
  --artifact-contracts artifact-contracts.yaml \
  --agent-contracts agent-contracts.yaml
```

### 退出代码

| 代码 | 含义 |
| --- | --- |
| 0 个 | 所有支票通行证 |
| 1个 | B. 发现的验证或提示问题 |
| 2个 | 文件读取或计划出错 |

## 图书馆 API

```typescript
import {
  loadToolchainContracts,
  parseToolchainFile,
  validateToolchainContracts,
  lintDataflow,
} from "@aaac/toolchain";

// Load and parse (resolves $refs)
const doc = await loadToolchainContracts("./toolchain-contracts.yaml");

// Validate
const issues = validateToolchainContracts(doc, {
  artifactIds: ["source-code", "spec-md"],
});

// Lint dataflow against other contract layers
const lintIssues = lintDataflow(doc, {
  artifacts: [{ id: "source-code", derived_from: [] }],
  agents: [{ id: "reviewer", consumes: ["source-code"], produces: ["review-report"] }],
});
```

| 函数 | 说明 |
| --- | --- |
| `loadToolchainContracts` | 装入 YAML 文件, 解析 `$refs`,验证计划 |
| `parseToolchainFile` | 解析文件没有 `$ref` 决议 |
| `validateToolchainContracts` | 语义验证(艺术标识、复制件) |
| `lintDataflow` | 跨合同数据流程完整性检查 |

## 相关软件包

-   [`@aaac/contracts`](https://npmcn.com/package/%40aaac/contracts/) • 构成部分合同汇编器和代码生成器
-   [`@aaac/runtime`](https://npmcn.com/package/%40aaac/runtime/) 执行AaaC工作流程的运行时间 SDK

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 常见问题

### @aaac/toolchain 是什么？

用于装有文物的工具申报的工具链合同定义

### 如何安装 @aaac/toolchain？

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

### @aaac/toolchain 支持 TypeScript 吗？

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

### @aaac/toolchain 支持 ESM 还是 CommonJS？

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

### @aaac/toolchain 需要什么版本的 Node\.js？

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

### @aaac/toolchain 可以商用吗？

@aaac/toolchain 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aaac/toolchain 的下载量有多少？

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

### @aaac/toolchain 还在维护吗？

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