# @alvin0/ai-agent-sdk-core 中文文档

规范地址：https://npmcn.com/package/%40alvin0/ai-agent-sdk-core/

版本：0\.1\.16
npm 元数据更新时间：2026-11-06T06:35:21.066Z
中文译文更新时间：2026-11-06T15:51:05.144Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40alvin0/ai-agent-sdk-core
原文对照：https://npmcn.com/package/%40alvin0/ai-agent-sdk-core/?lang=original
项目主页：https://github.com/alvin0/ai-agent-sdk/tree/main/packages/core#readme
源码仓库：https://github.com/alvin0/ai-agent-sdk

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

- 包体积（解压后）：4.6 MB，1165 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-09-09T16:36:17.515Z
- 最新版本发布：2026-11-06T06:35:20.697Z
- 近 30 天下载量：2829（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

Ai-agent-sdk的通用合同和运行时间原始

## 安装

```sh
npm install @alvin0/ai-agent-sdk-core
```

也可以使用：`pnpm add @alvin0/ai-agent-sdk-core`、`yarn add @alvin0/ai-agent-sdk-core`、`bun add @alvin0/ai-agent-sdk-core`

## README

# `@alvin0/ai-agent-sdk-core`

提供商中立合同和运行时间原始,用于构建模型适配器和流式AI应用.

运行时间 : **通用**。发布代码使用 ECMAScript、 获取兼容类型、 Web Streams、 中止控制器、 性能计时器和 Web Crypto 。 它不使用节点内置, `process`, (中文(简体) ), `Buffer`,本地路径,文件系统访问,儿童过程,或 stdio.

```sh
pnpm add @alvin0/ai-agent-sdk-core
```

`createAgentRuntime()` 是推荐成分根. `defineAgent()` 抓取可重复使用的代理定义,每次运行时间都会显示 `SdkLogger` 其记录共享运行时间/运行相关性和隐私政策:

```ts
import {
  createAgentRuntime,
  defineAgent,
  type SdkLogger,
} from '@alvin0/ai-agent-sdk-core'

const runtime = await createAgentRuntime({ providers: [provider] })
const definition = defineAgent({ id: 'assistant', instructions: 'Be concise.' })
const logger: SdkLogger = runtime.logger({ fields: { component: 'assistant' } })
const agent = runtime.agent({ ...definition, model: { provider: 'openai', id: 'gpt-6-luna' } })
logger.info('agent ready')
```

```ts
import { ModelAdapter, ModelRegistry } from '@alvin0/ai-agent-sdk-core'

const registry = new ModelRegistry()
registry.registerAdapter(['example'], new YourAdapter())

const call = registry.stream({
  provider: 'example',
  model: 'model-id',
  messages: [],
})

for await (const chunk of call) {
  // Consume normalized chunks.
}

const report = await call.report
```

该套件包括电文和流合同、示范登记和再试验原始数据、正常错误、使用会计、明确的观察/联系端口以及交易提供者-插件登记。 供应商HTTP/SSE运输、混凝土出口商、文件系统技能、环境证书和协议执行属于单独的成套能力.

文档根加 `/agent`, (中文(简体) ), `/memory`, (中文(简体) ), `/observability`, (中文(简体) ), `/provider`, (中文(简体) ), `/skills`, (中文(简体) ), `/tools`, (中文(简体) ), `/embedding`,以及 `./package.json` 是公开的。 内部源路径为 不符合合同.

会议 `hooks.beforeCompletion` 可能返回 `{ kind: 'continue', messages: [...] }` 在模型自愿停止后完成待处理的应用工作。 使用 `createUserMessage` 与 `source: { kind: 'app', producer: 'your-workflow' }`。 。 。 . SDK在同一转弯和运行中消耗了这个上下文,保留了用法, 剩余预算、注销和原始历史。 继续被忽略 能力已经用尽。 这个钩子在空答恢复前运行 所以可以 继续采用在评论后停止、没有最后答复的模式. 每条信息都必须是应用源;混合或 人类来源的批次在解剖学上被否决. 空批次本身不是 继续转弯。 主机应绑定重复的完成异议并停止 当工作流程不再取得进展时. `{ kind: 'yield' }` 仍然暂停 没有最终完成或深入投票. `onTurnEnd` 保留其回收结果语义学并接受续作 裁决; 应用程序完成门应更可取 `beforeCompletion`。 。 。 .

`validateJsonFileContent` 从 `/tools` 或者说 `/agent` 验证完成 `.json` 在主机写之前写/编辑内容。 验证默认值 : 字节和报告可恢复的语法错误。 见 [jSON 写的工作空间](https://npmcn.com/package/docs/workspace-json-writes.md) 用于主机选择退出和集成实例.

`createManagedAgentTeam` 从 `/agent` 支持牵头授权和选择共享板 协作。 见 [多代理主机指南](https://npmcn.com/package/docs/multi-agent.md) 工具, 从0.1.12开始的预算和移徙 [离线示例](https://npmcn.com/package/samples/multi-agent-offline/README.md) 没有提供者证书的两种模式.

在0.1.5中添加的 Opt-in优化帮助包括 `defineActionFusion` 财务报告和审定财务报表 `createModelEvidenceReducer` 从 `/tools`,以及 `createContextOptimizer` 从 `/memory`应用选择管道步骤、里程碑摘要、日志存储、, 和减少模型。 见 [应用程序指南](https://github.com/alvin0/ai-agent-sdk/blob/main/docs/context-optimization.md) 用于配置、精确证据倒置和可运行验证.

现有代理、工具和会话进口仍然可用。 评议 [升级指南](https://github.com/alvin0/ai-agent-sdk/blob/main/docs/upgrading-from-0.1.4.md) 用于描述默认、已排队的引导收件以及管理团队验证 发布0.1.4版后的变化. 还需要程序工具 届会 `experimentalPrograms` 赠款;普通工具没有.

关于0.1.7完成,待输入、流替换和停止行为,见 页:1 [升级指南](https://github.com/alvin0/ai-agent-sdk/blob/main/docs/upgrading-from-0.1.6.md)。 。 。 . `RuntimeAgentSession.hasUnansweredInput()` 财务报告和审定财务报表 `runPending()` 曝光左边的工作 经过一个终端回合。 使用 `response.completed` 目标完成.

在0.1.8中,精确的重复后卫可以重用刚刚成功过的 工具结果并允许一个限定模式重新规划. `EmbeddingError.failure` 保留 可用的提供者 HTTP 状态,通过正常化重试延迟和请求 ID . 见 [从0.1.7升级](https://github.com/alvin0/ai-agent-sdk/blob/main/docs/upgrading-from-0.1.7.md) 对于排除,取消和预算行为.

## 常见问题

### @alvin0/ai-agent-sdk-core 是什么？

Ai-agent-sdk的通用合同和运行时间原始

### 如何安装 @alvin0/ai-agent-sdk-core？

在项目目录运行 npm install @alvin0/ai-agent-sdk-core，或使用 pnpm add / yarn add / bun add。

### @alvin0/ai-agent-sdk-core 支持 TypeScript 吗？

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

### @alvin0/ai-agent-sdk-core 支持 ESM 还是 CommonJS？

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

### @alvin0/ai-agent-sdk-core 可以商用吗？

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

### @alvin0/ai-agent-sdk-core 的下载量有多少？

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

### @alvin0/ai-agent-sdk-core 还在维护吗？

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