# @aseity/lyra 中文文档

规范地址：https://npmcn.com/package/%40aseity/lyra/

版本：0\.23\.0
npm 元数据更新时间：2026-11-05T07:39:52.853Z
中文译文更新时间：2026-11-08T08:44:00.916Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40aseity/lyra
原文对照：https://npmcn.com/package/%40aseity/lyra/?lang=original
项目主页：https://github.com/Ty026/max#readme
源码仓库：https://github.com/Ty026/max

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

- 包体积（解压后）：2.7 MB，26 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：12 个
- peer 依赖：zod ^4\.0\.0
- 首次发布：2026-06-24T06:19:43.864Z
- 最新版本发布：2026-11-05T07:39:52.637Z
- 近 30 天下载量：1849（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 48 个）

## 中文简介

Lyra 代理库

## 安装

```sh
npm install @aseity/lyra
```

也可以使用：`pnpm add @aseity/lyra`、`yarn add @aseity/lyra`、`bun add @aseity/lyra`

## README

# @ aseity/ lyra (帮助)

Lyra是一个TypeScript库,用于运行跨OpenAI的工具使用代理, Anthropic, 和兼容的模型提供者。 它包括流,会话, 转让、结构化产出、追踪、MCP客户端和沙盒能力.

## 更改日志

见 [释放历史](https://github.com/Ty026/max/blob/main/packages/lyra/CHANGELOG.md) 用于修改每个版本. `CHANGELOG.md` 也包含在 npm 包中.

## 安装

```sh
pnpm add @aseity/lyra zod
```

## 快开始

```ts
import { Agent, OpenAIProvider, run } from '@aseity/lyra';

const provider = new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY,
});
const model = await provider.getModel('gpt-5.4-mini');

const agent = new Agent({
  name: 'Assistant',
  instructions: 'Answer clearly and concisely.',
  model,
});

const result = await run(agent, 'Hello!');
console.log(result.finalOutput);
```

通过混凝土 `Model` 当模型选择为您所拥有时 应用。 使用 `Runner` 当您需要可重复使用的工作流程、 跟踪或会话时 配置 .

见 [工具输入计划和问题核准](https://npmcn.com/package/%40aseity/lyra/docs/tool-inputs.md) 严格 可选参数,文件系统默认,并恢复用户答案.

## 小美,小美,小美

```ts
import { MiMoProvider, MIMO_MODEL_NAMES } from '@aseity/lyra';

const provider = new MiMoProvider(); // reads MIMO_API_KEY
const pro = await provider.getModel(); // mimo-v2.6-pro
const flash = await provider.getModel('mimo-v2.6-flash');
// MIMO_MODEL_NAMES contains the two built-in model names.
```

小米莫使用 [安东尼消息 API](https://mimo.mi.com/docs/en-US/api/chat/anthropic-api) 时间 `https://api.xiaomimimo.com/anthropic`。通过 `apiKey`, (中文(简体) ), `baseURL`,或 `defaultModel` 覆盖默认值; `MIMO_DEFAULT_MODEL` 并设置 默认模式。 Token Plan用户可以提供其计划的Anthropic基础URL和密钥. 两个内置模型都有一个1M-token上下文窗口和一个131,072-token输出 限制,包含图像输入,流线,工具调用,以及思维回放.

思考跟随服务默认. 使用 `modelSettings.reasoning.effort: 'none'` 以禁用,或 `modelSettings.providerData.thinking: { type: 'enabled' }` 明确赋予它权力。 米莫没有推理努力水平. 在思维模式下, 服务将温度和上p修正为自己的默认值. 见 [模型列表](https://mimo.mi.com/docs/en-US/quick-start/summary/model) 财务报告和审定财务报表 [思维指南](https://mimo.mi.com/docs/en-US/quick-start/usage-guide/text-generation/deep-thinking)。 。 。 .

## 命令代码

```ts
import { CommandCodeProvider } from '@aseity/lyra';

const provider = new CommandCodeProvider(); // COMMAND_CODE_API_KEY
const model = await provider.getModel(); // gpt-6-luna
```

克劳德使用信件; GBT 和 `google/gemini-3.8-flash` 使用反应. 其他克洛德/GPTID可以在不继承已验证能力的情况下通过. 其他双子座模型被否决. 见 [配置、参数限制和活 接受](https://npmcn.com/package/%40aseity/lyra/docs/command-code.md),包括双子座的数值enum Schema限制.

## 深搜索 API

使用 `DeepSeekSearchClient` 从本地函数调用独立搜索 API 工具。 它独立于特工的模型提供者。 应用程序拥有 证书、共同费率限制、复审和取消期限。 见 [客户合同](https://npmcn.com/package/%40aseity/lyra/docs/deepseek-search-client.md)。 。 。 .

## 深搜索主机网络搜索

添加 `webSearch()` 从 `@aseity/lyra` 给经纪人的 `tools` 使用时 `DeepSeekProvider`。模型决定是搜索;没有参数或本地 需要执行器 。 只有 DeepSeek 信件支持此声明 . 见 [主机网页搜索](https://npmcn.com/package/%40aseity/lyra/docs/web-search.md) 常规搜索记录, 引用、流出事件和持续会话重放.

## 深搜索响应 JSON 输出

`DeepSeekProvider` 继续使用 Anthropic 信件。 JSON Schema的产出, 通过单独的导出 `DeepSeekResponsesModel` 直接对代理人:

```ts
import { Agent, DeepSeekResponsesModel, run } from '@aseity/lyra';
import { z } from 'zod';

const agent = new Agent({
  name: 'Extractor',
  model: new DeepSeekResponsesModel({
    model: 'deepseek-v4-pro',
    apiKey: process.env.DEEPSEEK_API_KEY,
  }),
  instructions: 'Extract the name and age from the input.',
  outputType: z.object({ name: z.string(), age: z.number() }),
});

const result = await run(agent, 'Alice is 30 years old.');
console.log(result.finalOutput);
```

模特儿送来了 `outputType` 作为 `text.format.type: 'json_schema'`默认 `https://api.deepseek.com` 并使用配置的深搜索键 `apiKey` 实值 省略。 内容 `baseURL` 独立于 `DEEPSEEK_BASE_URL`,属于 发心供养. 你可以提供 `fetch`, (中文(简体) ), `maxRetries`,以及 `metadata`,或注入 a 一个 `openAIClient` 而不是客户端配置 .

水流得到支持. `modelSettings.maxTokens` 超过默认的 32,768 输出符号; 推理工作支持 `low`, (中文(简体) ), `high`, (中文(简体) ), `max`,以及 `none`编号 :`null` 以禁用思维。 排除保留了服务器的思维默认. 答复是无国籍的:发送完整的历史,而不是对话或先前的答复 身份证 见 [深搜索回复参考](https://api-docs.deepseek.com/api/create-response/)。 。 。 .

运行非流式和流式 现场检查与 `DEEPSEEK_API_KEY` 设定 : `bun packages/lyra/test/manual/deepseek-responses.ts` (做两次付费API呼叫).

## 打开路透社

`OpenRouterProvider` 使用 OpenRouter 的 Chat 补全点时 保存 OpenRouter 路由元数据、成本数据、结构推理 带内流出错 :

```ts
import { OpenRouterProvider } from '@aseity/lyra';

const provider = new OpenRouterProvider({
  apiKey: process.env.OPENROUTER_API_KEY,
  httpReferer: 'https://example.com',
  appTitle: 'Example Agent',
  defaultRequest: {
    provider: { require_parameters: true },
  },
});

const model = await provider.getModel('anthropic/claude-sonnet-4.6');
```

每个请求 OpenRouter 扩展例如 `provider`, (中文(简体) ), `models`, (中文(简体) ), `plugins`, (中文(简体) ), `reasoning`,以及 `session_id` 也可以通过 `modelSettings.providerData`。 。 。 .

## 许可证

麻省理工学院

## 模型参数相容性

见 [模型参数传输](https://npmcn.com/package/%40aseity/lyra/docs/model-parameters.md) 支持现代努力, 传统思维预算、明确的产出验证和异名迁移 工作价值。 提供者/模式支助不同于运输支助.

## MCP 磁共振

连接 stdio、 流式 HTTP 或 SSE MCP 服务器并将其工具暴露于任意 Lyra工具能模型提供者. 见 [MCP客户](https://npmcn.com/package/%40aseity/lyra/docs/mcp.md) 连接 管理、认证、过滤、资源和上游相容性.

### 图像验证

`view_image` 在本地图像结果前验证内置 PNG/JPEG/WebP/GIF 字节 或视觉倒置请求,即使压缩被禁用。 它执行一个 严格的Sharp解码,包括所有动画框架; GIF 块边界为 也检查, 因为解码器可以容忍一些被截断的 GIF 。 无效的图像 返回时 `toolError` 没有图像内容的文本,所以模型可以重生 文档并在同一转弯内重试。 源文件从未被修复或重写. 供应商的后期HTTP 400仍然结束转弯; 本地验证不能保证 提供者接受,不添加模式重试。 从远程图像引用 自定义沙盒无法被本地验证并返回工具出错.

字节和尺寸限制在完全解码前检查. 主机上限为 每个输入32个米B,每边8 000像素,6 400万像素总和 框架; 也适用更严格的模型限制。 最多两个解码同时运行 每个进程。 校验使用流象素统计而不是返回 a 完整的原始像素缓冲器。 已排队的呼叫保留其限制输入字节, 所以调用者 仍然必须绑定工具调用货币。 在第一个图像上很懒散. 静态压缩双倍作为验证,而不是将图像解码两次.

离线回归 : `pnpm --filter @aseity/lyra exec vitest run test/view-image-validation.test.ts`。 。 。 . 设定 `LYRA_TEST_DOCKER_IMAGE` 转到带有 bash 的现有图像以包含真正的 Docker 跑道复苏. `bun packages/lyra/test/manual/image-validation.ts` 措施4 大约1,16和6,400万像素同时调用;可选文件参数 在不接触模型的情况下重放本地失败 。 当地6400万像素运行 6.8秒的4个呼叫,取样过程RSS,峰值接近232 MiB;这些 测量依赖于解码器,像素,运行时间,和机器,而不是内存保证.

### 可选视图 图像压缩

`view_image` 默认保存原始图像字节。 为减少内含图像有效载荷:

```ts
filesystem({ viewImageCompression: true })
```

这既适用于土著视觉,也适用于土著视觉 `viewImageCaptioner` 请求。 静态内线 图像被编码为JPEG,质量为90,为4:4:4铬,不缩放; EXIF方向被应用,而透明背景变为白色. 如果编码 将增加有效载荷,原载保留。 动画图像在验证后保留了原来的字节. 源文件从未被覆盖; 返回 MIME类型,字节大小和维度描述实际传输的图像.

验证和压缩共享已安装 `sharp` 依赖性. 现有的输入和模型图像限制仍然适用. 这降低了个人图像 有效载荷,但不限制累积对口大小或保证避免 hTTP 413的答复。 压缩失败可能影响精细文本;保留正本 用于详细收件和验证的文件.

## 多克寿命周期

Docker 启动失败在错误返回前被清除 。 如果清理也失败, 抓 `DockerSandboxStartupError`,保留执行资源预留,并重试 `error.cleanup()` 在多克恢复后。 见 [挂起和清理](https://npmcn.com/package/%40aseity/lyra/docs/docker-lifecycle.md) 错误合同 取消和关闭行为.

见 [明确的技能投入](https://npmcn.com/package/%40aseity/lyra/docs/skills.md) 手动选择 发现旗帜, 原始消息显示并冻结了模型历史.

Inline 文件引用保留其在用户消息中的位置 :

```ts
await runner.run(agent, [{
  type: 'message',
  role: 'user',
  content: [
    { type: 'input_text', text: 'Read ' },
    { type: 'input_file_ref', name: 'notes.md', path: '/workspace/notes.md' },
    { type: 'input_text', text: ' and summarize it.' },
  ],
}]);
```

主机必须在 `path` 在运行代理之前。 莱拉 参考项目 `@notes.md` 并用工作空间附加提醒 在模型和压缩输入中,路径和读取指导。 模糊的同名词 参考文献应保持其路径的内在化,最后不重复. 会议项目保留原部分。 见 [文件引用](https://npmcn.com/package/%40aseity/lyra/docs/file-references.md)。 。 。 . `userMessageText` 显示 `@notes.md`; 导出 `InputFileRef` 计划只包含 `type`, (中文(简体) ), `name`,以及 `path`,没有特定主机库标识.

见 [工作空间文件编辑](https://npmcn.com/package/%40aseity/lyra/docs/file-edits.md) 结构化 `input_file_edits` 通知、可选 diffs 和原历史保存的模型投影.

见 [每个运行的麻黄上下文](https://npmcn.com/package/%40aseity/lyra/docs/ephemeral-context.md) 用于冻结上下文 在模型请求中出现而不输入历史或收缩的快照.

见 [背景递增摘要](https://npmcn.com/package/%40aseity/lyra/docs/incremental-summary.md) 冻结 请求输入、可配置摘要模板和调用者安排的内存 用于保存模型前缀而不会阻断后续转折的更新.

见 [模式输入提醒](https://npmcn.com/package/%40aseity/lyra/docs/system-reminders.md) 公共包装和 逃离API、东道主所有权和迁移,以及 [上传](https://npmcn.com/package/%40aseity/lyra/docs/uploads.md) 页:1 只引用文件和图像投影.

## 应用程序操作跟踪

导入 `withTrace` 财务报告和审定财务报表 `withCustomSpan` 从 `@aseity/lyra` 用于跟踪应用程序 在模特儿的电话里工作 他们共享配置的处理器 `setTraceProcessors` 与尊重 `setTracingDisabled`。 。 。 . `withTrace(name, work, { groupId, metadata })` 启动单独的跟踪。 在其召回, `withCustomSpan(work, { data: { name, data } })` 增加一个计时的儿童跨度,以及 模式调用 `tracing: true` 或者说 `tracing: 'enabled_without_data'` 加入这个 追踪. `ModelTracing` 也作为类型导出.

自定义跨度数据按提供时输出 。 申请必须省略私人 敏感数据设定关闭时的有效载荷。 自定义跨度记录出错 被其回调时所抛出; 在回调内抓取并设置一个已编辑的间距错误 当原始例外包含私人数据时.

非流式生成错误和 Runner 代理错误保留例外名称 当敏感数据追踪被禁用时。 最初的例外仍然达到 打电话的人.

Anthropic 和 Anthropic 相容相通的相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 组装模型输出 `response_done`,包括文本、推理和工具 打电话 他们记录模型和最终用途,即使有效载荷捕获被关闭. 输出使用 Lyra 的常态模型项目, 并有私有重放元数据 删除, 而不是空的初始 `message_start` 载荷.

### 产品思维努力

设定 `modelSettings: { thinkingEffort: 'low' }` 选择进入Lyra的四级 `none | low | high | max` 意图。 经核实的直接提供者在请求前绘制地图; 未知的频道尝试标准协议字段 。 土著 `reasoning.effort` 仍可单独使用。 接着 `ThinkingEffortUnsupportedError` (代码) `THINKING_EFFORT_UNSUPPORTED`用于明确思维参数的拒绝. 见 [合同、供应商绘图和实例](https://npmcn.com/package/%40aseity/lyra/docs/thinking-effort.md)。 。 。 .

## 常见问题

### @aseity/lyra 是什么？

Lyra 代理库

### 如何安装 @aseity/lyra？

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

### @aseity/lyra 支持 TypeScript 吗？

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

### @aseity/lyra 支持 ESM 还是 CommonJS？

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

### @aseity/lyra 可以商用吗？

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

### @aseity/lyra 的下载量有多少？

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

### @aseity/lyra 还在维护吗？

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