# @rowan-agent/models 中文文档

规范地址：https://npmcn.com/package/%40rowan-agent/models/

版本：0\.14\.0
npm 元数据更新时间：2026-11-02T08:07:38.217Z
中文译文更新时间：2026-11-02T08:54:34.247Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40rowan-agent/models
原文对照：https://npmcn.com/package/%40rowan-agent/models/?lang=original
项目主页：https://github.com/aiirobyte/rowan-agent#readme
源码仓库：https://github.com/aiirobyte/rowan-agent

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

- 包体积（解压后）：1.6 MB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-06-09T13:03:42.141Z
- 最新版本发布：2026-11-02T08:07:37.854Z
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

模型描述符、协议提供程序调度、SSE流和成本计算。代理运行时通过 `ModelConfig` 或者 `ModelRef + StreamFn`;它不依赖于代理生命周期状态。

## 安装

```sh
npm install @rowan-agent/models
```

也可以使用：`pnpm add @rowan-agent/models`、`yarn add @rowan-agent/models`、`bun add @rowan-agent/models`

## README

# @rowan-agent /模型

模型描述符、协议提供程序调度、SSE流和成本 计算。代理运行时通过 `ModelConfig` 或者 `ModelRef + StreamFn`;它不依赖于代理生命周期状态。

## 模型注册

```ts
import { registerModel, resolveModel, stream } from "@rowan-agent/models";

registerModel({
  id: "gpt-4o",
  provider: "openai",
  protocol: "openai-responses",
  baseUrl: "https://api.openai.com/v1",
  apiKey: process.env.OPENAI_API_KEY!,
  reasoning: false,
  thinkingLevel: "off",
  input: ["text"],
  headers: { "X-Model-Route": "default" },
  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
  contextWindow: 128_000,
  maxTokens: 4096,
});

const model = resolveModel("openai/gpt-4o");
for await (const event of stream(model!, request, ctx)) {
  // consume LlmStreamEvent
}
```

`resolveModel()` 解析 `provider/model`； `registerModel()` 注册自定义 模型。 `streamByRef()` 处理注册模型，而 `createModelStream()` 返回与运行时兼容的 `StreamFn`。两者都只通过模型调度 `protocol` 并且不保留旧的Provider工厂。

## 供应商注册表

```ts
import { registerApiProvider } from "@rowan-agent/models";

registerApiProvider({ protocol: "my-api", stream: myStream });
```

内置协议包括 `openai-completions`， `openai-responses`， `openai-codex-responses`, `anthropic-messages`。提供程序传输句柄 标头、超时、中止、结构化错误和重试一致。

## 供应商认证

`ModelConfig` 和 `ProviderConfig` 接受一个可选的、可序列化的 `auth` 模式。它的缺席保持了现有的静态 `apiKey` 行为:

```ts
// Absent: Authorization: Bearer <apiKey> (or x-api-key for Anthropic).
{ provider: "openai", apiKey: process.env.OPENAI_API_KEY! }

// Keyless local server: no Authorization or x-api-key header.
{ provider: "ollama", baseUrl: "http://127.0.0.1:11434/v1", auth: "none" }

// Subscription login. The provider id keys the stored credential.
{ provider: "xai", baseUrl: "https://cli-chat-proxy.grok.com/v1", auth: "xai" }
```

命名流是 `"xai"`， `"github-copilot"`, `"openai-codex"`。他们从来没有 在配置中放入令牌。主机提供所有者控制的凭据 存储到流：

```ts
const streamModel = createModelStream(config, {
  oauthCredentialStore: {
    async load(providerId) {
      // Return OAuthCredential | undefined.
    },
    async save(providerId, credential) {
      // Persist the rotated credential before returning.
    },
  },
});
```

在每次HTTP尝试之前，OAuth流加载提供者的凭据， 当它在60秒内过期时刷新它，保存一个旋转的凭据 在使用之前，单航班刷新每个提供商id。刷新失败 请求而不是重用陈旧的令牌。缺少证书加薪 `OAuthSignInRequiredError` 与 `code: "sign_in_required"`.

开始登录 `startOAuthLogin(flow, options)`。浏览器流公开 `url`； 设备流暴露 `userCode` 和 `verificationUri`。保存已解析的文件 与模型配置使用的提供者id相同的凭据：

```ts
const session = await startOAuthLogin("xai");
console.log(session.url ?? `${session.verificationUri} (${session.userCode})`);
const credential = await session.credential;
await store.save("xai", credential);
// session.cancel() aborts an unfinished login and closes any listener.
```

`refreshOAuthCredential(flow, credential, options?)` 刷新路径是否相同 由请求身份验证使用。

## 协议类型

这个包定义了模型请求和响应、内容块、工具调用、 和流事件。代理身份、运行、持久事件和工具生命周期 合同属于 `@rowan-agent/agent`.

```ts
type StreamFn = (
  request: LlmRequest,
  ctx: ProviderCallContext,
) => AsyncIterable<LlmStreamEvent>;
```

### ProviderCallContext

流函数接收 `ProviderCallContext` :

-   `signal: AbortSignal` -运行级取消信号。
-   `run: { id, agentId, scope, cwd }` -活动的执行元数据。
-   `internal?: boolean` - - - - - - `true` 当调用在会话的副本上工作时（内部模型循环）。它的消息不会写入历史记录，因此在调用之间保持会话状态的提供者不能推进它。缺席意味着正常通话。
-   `interact(request): Promise<JsonValue>` -请求用户实时交互。
-   `tools.list(): readonly LlmToolDefinition[]` -使用元数据注册工具定义。
-   `tools.call(name, args, options?): Promise<ToolResult>` —调用已注册的工具。
    -   `options.signal?: AbortSignal` -在不取消运行的情况下终止单个工具调用。
    -   `options.onUpdate?(toolCall: ToolCall, progress?: ToolProgress): void` -接收合并的ToolCall，每次它在执行期间发生变化（开始，每个进度驱动） `present` 更新最后一个)。原始的 `progress` 对象在由进度报告触发更新时传递。
-   `tools.report(update: ToolCall | ToolCallUpdate): void` -报告外部工具执行情况。

### ToolProgress

进度报告使用标准的MCP `notifications/progress` 形状:

```ts
type ToolProgress = {
  progress: number;
  total?: number;
  message?: string;
  _meta?: JsonObject;
};
```

-   形状验证（有限数）；无效报告将被丢弃，并伴有警告，而不会导致工具调用失败。
-   工具私有进度数据消失 `_meta` 钥匙。
-   连续的输出必须累加地报告（例如，尾部），因为瞬态更新每次合并 `toolCallId`.

## 源结构

```
src/
├── protocol.ts       # Model/LLM request and response types
├── auth.ts           # Auth modes, credentials, and the credential-store seam
├── models.ts         # Model registry
├── registry.ts       # Protocol dispatch
├── sse.ts            # SSE parser
├── oauth/            # Login, refresh, polling, and provider request auth
└── providers/        # Built-in HTTP providers and shared transport
```

## 常见问题

### @rowan-agent/models 是什么？

模型描述符、协议提供程序调度、SSE流和成本计算。代理运行时通过 ModelConfig 或者 ModelRef \+ StreamFn;它不依赖于代理生命周期状态。

### 如何安装 @rowan-agent/models？

在项目目录运行 npm install @rowan-agent/models，或使用 pnpm add / yarn add / bun add。

### @rowan-agent/models 支持 TypeScript 吗？

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

### @rowan-agent/models 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @rowan-agent/models 可以商用吗？

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

### @rowan-agent/models 还在维护吗？

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