# @caldrix-ai/aerix 中文文档

规范地址：https://npmcn.com/package/%40caldrix-ai/aerix/

版本：0\.1\.7
npm 元数据更新时间：2026-11-07T14:41:56.034Z
中文译文更新时间：2026-11-08T23:51:59.558Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40caldrix-ai/aerix
原文对照：https://npmcn.com/package/%40caldrix-ai/aerix/?lang=original
项目主页：https://caldrix.ai/
源码仓库：https://github.com/100xeng/caldrix

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

- 包体积（解压后）：93 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@caldrix-ai/caldrix ^0\.3\.0 \|\| ^0\.4\.0 \|\| ^0\.5\.0 \|\| ^0\.6\.0 \|\| ^0\.7\.0 \|\| ^0\.8\.0 \|\| ^0\.9\.0
- 首次发布：2026-10-30T07:38:25.284Z
- 最新版本发布：2026-11-07T14:41:55.908Z
- 近 30 天下载量：2048（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

Aerix在caldrix.js引擎上的转回回路,在浏览器中.

## 安装

```sh
npm install @caldrix-ai/aerix
```

也可以使用：`pnpm add @caldrix-ai/aerix`、`yarn add @caldrix-ai/aerix`、`bun add @caldrix-ai/aerix`

## README

# aerix.js (英语)

Aerix在浏览器中的转回回路:一个具有工具、钩子和命名限制的代理,运行在 caldrix.js发动机. 在晚上,这是 [`@caldrix-ai/aerix`](https://www.npmjs.com/package/@caldrix-ai/aerix)。 。 。 .

aerix.js 本身没有负载. 你把一个模型装入 Caldrix.js 并手拿它 `Engine` 改为: `Agent`。 。 。 . 循环要求引擎一次一个转动,运行转动调用的工具,并输入结果 返回到模型的答案达到最终或极限.

## 安装

```sh
npm install @caldrix-ai/caldrix @caldrix-ai/aerix
```

`@caldrix-ai/caldrix` 属于对等关系( e)`^0.3.0 || ^0.4.0 || ^0.5.0 || ^0.6.0 || ^0.7.0 || ^0.8.0 || ^0.9.0`读取模型的卡德利克斯 `chat_template.jinja`) (中文(简体) ).

## 示例

```ts
import { Caldrix } from "@caldrix-ai/caldrix";
import { Agent, tool } from "@caldrix-ai/aerix";

const engine = await Caldrix.load("smollm2-instruct");

const weather = tool({
  name: "weather",
  description: "Today's forecast for a city.",
  input: {
    city: { type: "string", description: "City name", required: true },
    unit: { type: "string", enum: ["c", "f"] },
  },
  run: async ({ city, unit }) => `Sunny in ${city}, 21°${unit ?? "c"}`,
});

const agent = new Agent({
  model: engine,
  instructions: "You are a travel helper. Use the tools to answer.",
  tools: [weather],
  limits: { turns: 8, retries: 2, maxTokens: 384, resultChars: 4000 },
  generation: { temperature: 0 },
  hooks: { beforeCall: (call) => (call.tool === "weather" ? undefined : { deny: "not allowed" }) },
});

const controller = new AbortController();
for await (const ev of agent.run("Should I pack an umbrella for Lisbon?", { signal: controller.signal })) {
  if (ev.type === "final") console.log(ev.text);
}
const { text } = await agent.ask("And for Porto?"); // the same conversation
console.log(text);
agent.reset();
```

## API 密码

软件包导出 `Agent`, (中文(简体) ), `tool` 财务报告和审定财务报表 `AerixError`类型 `AgentOptions`, (中文(简体) ), `Limits`, (中文(简体) ), `Hooks`, (中文(简体) ), `AgentEvent`, (中文(简体) ), `Call`, (中文(简体) ), `EndReason`, (中文(简体) ), `Model`, (中文(简体) ), `Tool`, (中文(简体) ), `ToolDef`, (中文(简体) ), `Field` 财务报告和审定财务报表 `FieldType`。 。 。 .

**`Model`** 实值 `{ chat(messages, opts?): AsyncIterable<Delta> }` 超过Caldrix.js的类型。 一个caldrix.js `Engine` 满足它.

**`tool(def)`** 定义工具 :

-   `name` 匹配 `^[a-z][a-z0-9_]{0,63}$` 在代理中是独一无二的(如果 代理已建).
-   `description` 是模型看到的文本.
-   `input` 是平地地图。 每个字段都有 `type` (单位:千美元)`string`, (中文(简体) ), `number`, (中文(简体) ), `integer` 或者说 `boolean`(中文(简体) ) 和可选 `description`, (中文(简体) ), `required` 财务报告和审定财务报表 `enum`。空地图表示没有输入.
-   `run(input, { signal, callId })` 返回一个字符串,或经过的值 `JSON.stringify`。 。 。 . 输入在字段中检查 `run`; 检查失败或丢出成为结果 `error: …`,工具错误不会结束运行.

**`new Agent(options)`** 带 `AgentOptions`数字 :

-   `model` (必须), `instructions` (默认) `""`, (中文(简体) ), `tools` (默认无;那么唯一的答案是: (a a final) (中文(简体) ).
-   `limits`,每个名称绑定: `turns` (8个,每跑几代,包括复试), `retries` (2个), 在转弯或转弯后的额外尝试), `maxTokens` (512,每代)和 `resultChars` 4000, (中文(简体) ), 将一个工具结果切入此段并加注).
-   `generation`: caldrix.js's (英语) `GenerationOptions` 无 `maxTokens` 财务报告和审定财务报表 `constraint`,哪个aerix.js 设定.
-   `constrain` (默认) `true`:把转弯的计策当作 `constraint` 和每个世代的人。 设定 `false` (单位:千美元) `Model` 而不限制解码;然后只适用剖析和重写.
-   `hooks`,每个可选和等待: `beforeCall(call)` 可能返回 `{ deny: reason }` (结果) 变成 `refused: <reason>`)或(或) `{ input }` (取代电话输入); `afterCall(call, result)` 可能返回 `{ result }`· ; `onFinal(text)` 可能返回 `{ continue: text }`,使代理人 以该文本作为用户信息在 `turns`。 。 。 .

**`agent.run(prompt, { signal })`** 产量 `AgentEvent`继续经纪人的谈话:

-   `{ type: "text", text }`:原始流出型号文本.
-   `{ type: "usage", promptTokens, completionTokens }`:每代一个.
-   `{ type: "turn", turn, thought?, calls }`,然后每个呼叫 `{ type: "call", id, tool, input }` 财务报告和审定财务报表 `{ type: "result", id, tool, text, error }`。 。 。 .
-   `{ type: "retry", turn, reason }`:再次要求剪接或坏转.
-   只有一个结局: `{ type: "final", text, thought? }`,或 `{ type: "end", reason, message? }` 地点 `reason` 实值 `"turns"`, (中文(简体) ), `"retries"`, (中文(简体) ), `"abort"` 或者说 `"error"` (引擎故障或投掷) 钩子,带有它的信息). 引擎故障就是这个事件,从不扔.

**`agent.ask(prompt, { signal })`** 运行到结尾并解析 `{ text, events }` 最终;任何 其他结尾拒绝 `AerixError` 类型 `end`,携带 `reason` 财务报告和审定财务报表 `events`。 。 。 . **`agent.reset()`** 忘记了谈话. **`agent.messages`** 这是迄今为止的对话.

一次跑一次:第二次同时跑 `run` 掷出 `AerixError` 类型 `busy`选项 类型 `options`。 。 。 .

## 转弯合同

每个转弯都是一个JSON物体 `{"calls":[{"tool":"…","input":{…}}]}` 或者说 `{"final":"…"}`,带有 选项 `thought`。系统消息说明这一合同并列出工具;这是相同的 和Aerix一样的工具渲染.

每个转弯都是受限制的(除非 `constrain: false`:发动机在从 工具,所以一个回合 结束自己是一个有效的回合 与已知的工具 和右输入 形状,但有一个例外:空 `calls` 列表通过制约,解析拒绝 并重试。 转来转去 `maxTokens` 在JSON关闭之前,再次请求,缩短,作为一个 重试。 最多一个回合的8个电话被保留,a `thought` 被切入到 600 个字符中,然后呼叫 命令,一次一个.

每个转弯的提示是系统消息加上每一个更早的转弯和结果. 发动机保持什么 上一代处理过,所以一个转动只附加到对话中预填新部分; 完成三角洲 `usage.cachedTokens` 说有多少被重新使用.

## 未构建

-   路由选择的分数( 浏览器引擎返回) `logprobs`这里没有读到它们.
-   子代理和一个验证器,收缩和上下文工具,会话保存在索引数据库中.

## 运行中

-   单位用脚本假的测试 `Model`:转弯解析,系统渲染和转弯 schema (golden),被钉入Aerix的倒转合同,输入检查,每个钩子,每个端口和每个限制.
-   在Playwright的无头铬层进行一个端到端测试:a `Agent` 一个工具 在已建成的 caldrix.js 上,从回转服务器装入一个输出为噪声的微小测试模型. 它检查引擎是否接收了每代人的转动计划 每次重试都遵循 切转,运行结束 一个命名的结果.

没有其他说法:没有真正的模型,没有其他浏览器或水平,也没有质量或速度数字.

## 许可证

aerix.js (npm 软件包) `@caldrix-ai/aerix`) 位于Apache- 2. 0 下 (`LICENSE`, (中文(简体) ), `NOTICE`) (中文(简体) ).

## 常见问题

### @caldrix-ai/aerix 是什么？

Aerix在caldrix\.js引擎上的转回回路,在浏览器中\.

### 如何安装 @caldrix-ai/aerix？

在项目目录运行 npm install @caldrix-ai/aerix，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@caldrix-ai/caldrix（^0\.3\.0 \|\| ^0\.4\.0 \|\| ^0\.5\.0 \|\| ^0\.6\.0 \|\| ^0\.7\.0 \|\| ^0\.8\.0 \|\| ^0\.9\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @caldrix-ai/aerix 支持 TypeScript 吗？

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

### @caldrix-ai/aerix 支持 ESM 还是 CommonJS？

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

### @caldrix-ai/aerix 可以商用吗？

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

### @caldrix-ai/aerix 的下载量有多少？

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

### @caldrix-ai/aerix 还在维护吗？

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