# @flink-app/anthropic-adapter 中文文档

规范地址：https://npmcn.com/package/%40flink-app/anthropic-adapter/

版本：2\.0\.0-alpha\.134
npm 元数据更新时间：2026-11-07T11:33:04.019Z
中文译文更新时间：2026-11-14T23:08:05.610Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40flink-app/anthropic-adapter
原文对照：https://npmcn.com/package/%40flink-app/anthropic-adapter/?lang=original
项目主页：https://github.com/FrostDigital/flink-framework#readme
源码仓库：https://github.com/FrostDigital/flink-framework

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

- 包体积（解压后）：78.9 kB，11 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@flink-app/flink \>=2\.0\.0-alpha\.134
- 首次发布：2026-02-10T13:29:32.371Z
- 最新版本发布：2026-11-07T11:30:23.664Z
- 近 30 天下载量：2996（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：86（近 12 个月 86 个）

## 中文简介

Flink AI 框架的 Anthropic Claude 适配器

## 安装

```sh
npm install @flink-app/anthropic-adapter
```

也可以使用：`pnpm add @flink-app/anthropic-adapter`、`yarn add @flink-app/anthropic-adapter`、`bun add @flink-app/anthropic-adapter`

## README

# @flink-app/人类适应器

Flink AI框架的Anthropic Claude适配器. 提供与Anthropic的克洛德模型的无缝融合.

## 安装

```bash
npm install @flink-app/anthropic-adapter
# or
pnpm add @flink-app/anthropic-adapter
```

这个 `@anthropic-ai/sdk` 软件包包含为依赖,所以不需要单独安装.

## 使用量

### 基本设置

```typescript
import { AnthropicAdapter } from "@flink-app/anthropic-adapter";
import { FlinkApp } from "@flink-app/flink";

const app = new FlinkApp({
  ai: {
    llms: {
      default: new AnthropicAdapter({
        apiKey: process.env.ANTHROPIC_API_KEY!,
        model: "claude-sonnet-4-5-20250929"
      }),
    },
  },
});

await app.start();
```

**遗产 API( 仍然支持 ):**

```typescript
// Backward-compatible constructor
new AnthropicAdapter(process.env.ANTHROPIC_API_KEY!, "claude-sonnet-4-5-20250929")
```

### 代理指令

使用 `instructions` 属性 :

```typescript
// src/agents/support_agent.ts
export const Agent: FlinkAgentProps = {
  name: "support_agent",
  instructions: "You are a helpful customer support agent.",
  tools: ["get_order_status"],
  model: { adapterId: "default" },
};
```

**如何运作:**

-   指令是作为系统信息准备给每个对话
-   遵循 Vercel AI SDK 一致性模式
-   在所有相互作用中提供稳定的代理行为

#### 带有系统信件的动态上下文

对于每个请求上下文,在对话中添加系统消息:

```typescript
const result = await ctx.agents.myAgent.execute({
  message: [
    { role: "system", content: "Current user tier: Premium" },
    { role: "user", content: "What can I do?" }
  ]
});
```

**发送到 Anthropic 的信件顺序 :**

1.  探员 `instructions` (作为系统消息)
2.  用户提供的系统信息(如果有的话)
3.  对话消息

这给您带来了静态代理行为和动态的每个请求上下文.

## 多个适配器

可以注册多个具有不同配置的Anthropic适配器:

```typescript
import { AnthropicAdapter } from "@flink-app/anthropic-adapter";
import { FlinkApp } from "@flink-app/flink";

const app = new FlinkApp({
  ai: {
    llms: {
      // Default Sonnet 4.5 model - best balance of intelligence, speed, and cost
      default: new AnthropicAdapter({
        apiKey: process.env.ANTHROPIC_API_KEY!,
        model: "claude-sonnet-4-5-20250929"
      }),

      // Fast Haiku 4.5 model for simple tasks - near-frontier performance at lower cost
      fast: new AnthropicAdapter({
        apiKey: process.env.ANTHROPIC_API_KEY!,
        model: "claude-haiku-4-5-20251001"
      }),

      // Opus 4.5 model for complex tasks - maximum intelligence
      smart: new AnthropicAdapter({
        apiKey: process.env.ANTHROPIC_API_KEY!,
        model: "claude-opus-4-5-20251101"
      }),
    },
  },
});
```

## 用于代理

在代理配置中引用适配器注册的ID:

```typescript
// src/agents/support_agent.ts
import { FlinkAgentProps } from "@flink-app/flink";

export const Agent: FlinkAgentProps = {
  name: "support_agent",
  description: "Customer support assistant",
  instructions: "You are a helpful customer support agent.",
  tools: ["get_order_status"],
  model: {
    adapterId: "default", // Uses the "default" adapter
    maxTokens: 1000,
    temperature: 0.7,
  },
};
```

## 支持的模式

这个适配器与所有的克洛德模型一起工作. 最新的Claude 4.5模式比前几代有重大改进:

### Claude 4.5 型号(建议)

-   **克劳德·索内 4.5**数字 : `claude-sonnet-4-5-20250929` (建议大多数使用情况)
    
    -   智能、速度和成本的最佳平衡
    -   编码和代理任务的特殊表现
    -   200K 上下文窗口 (1M 在β 有标题)
    -   定价:3美元/MTok投入,15美元/MTok产出
-   **克劳德·海库 4.5**数字 : `claude-haiku-4-5-20251001` (快讯)
    
    -   近岸业绩,成本的一小部分
    -   优化速度和成本效益
    -   200K 上下文窗口
    -   定价:1美元/MTok投入,5美元/MTok产出
-   **克劳德·奥普斯 4.5**数字 : `claude-opus-4-5-20251101` (最有能力)
    
    -   复杂任务的最大智能
    -   编码、代理和企业工作流程行业领先
    -   200K 上下文窗口
    -   定价:5美元/MTok投入,25美元/MTok产出

### 遗产模式

对于后向相容性,遗留克洛德3和4型仍然支持:

-   **克洛德·奥普斯 4.1**数字 : `claude-opus-4-1-20250805`
-   **克洛德·索内特 4**数字 : `claude-sonnet-4-20250514`
-   **克洛德·3.7 索内**数字 : `claude-3-7-sonnet-20250219`
-   **克洛德·奥普斯4**数字 : `claude-opus-4-20250514`
-   **克劳德 三海库**数字 : `claude-3-haiku-20240307`

我们建议改用克洛德4.5模式,以提高业绩和能力.

### 模型异名对特定版本

Anthropic 提供了特定的版本ID和别名:

-   **特定版本** (例如, `claude-sonnet-4-5-20250929`:永远不变的固定模型快照
    
    -   建议制作以确保行为一致
    -   快照日期表示准确的模型版本
-   **别名** (例如, `claude-sonnet-4-5`: 自动指向最新的快照
    
    -   有利于发展和实验
    -   在新发布一周内更新
    -   发布新快照时可能改变行为

示例

```typescript
// Production: Use specific version for stability
new AnthropicAdapter(apiKey, "claude-sonnet-4-5-20250929")

// Development: Use alias to always get latest improvements
new AnthropicAdapter(apiKey, "claude-sonnet-4-5")
```

## 缓存计量和成本优化

Anthropic 适配器自动捕捉到详细的缓存度量衡来帮助您优化成本并理解性能:

```typescript
const result = await ctx.agents.myAgent.execute({
  message: "Analyze this large document..."
});

console.log(result.usage);
// {
//   inputTokens: 3000,
//   outputTokens: 500,
//   cachedInputTokens: 2000,         // Tokens read from cache (10% cost)
//   cacheCreationInputTokens: 500    // Tokens written to cache (125% cost)
// }

// Calculate actual billed tokens with Anthropic's pricing
const regularTokens = result.usage.inputTokens -
  (result.usage.cachedInputTokens || 0) -
  (result.usage.cacheCreationInputTokens || 0);

const cacheReadCost = (result.usage.cachedInputTokens || 0) * 0.1;
const cacheWriteCost = (result.usage.cacheCreationInputTokens || 0) * 1.25;
const regularCost = regularTokens * 1.0;

console.log(`Cost breakdown:`);
console.log(`- Regular tokens: ${regularTokens} × 100% = ${regularCost}`);
console.log(`- Cache reads: ${result.usage.cachedInputTokens} × 10% = ${cacheReadCost}`);
console.log(`- Cache writes: ${result.usage.cacheCreationInputTokens} × 125% = ${cacheWriteCost}`);
console.log(`Total cost factor: ${regularCost + cacheReadCost + cacheWriteCost}`);
// "Total cost factor: 1325" (vs 3000 without caching) - 56% savings after initial cache write!
```

**缓存量表 :**

-   `inputTokens`: 总输入符 (包括缓存和缓存写入)
-   `outputTokens`: 总产出符号
-   `cachedInputTokens`: 从缓存读取输入符( 10% 成本)
-   `cacheCreationInputTokens`: 写入缓存的输入符 (125% 成本, 一次性)

**急速缓存 :**

-   **快取读取**:普通代币成本的10%(节省了90%!)
-   **快取写入**:125%的正常代币成本(一次性投资)
-   **最低门槛值**: 2048 个令牌(只激活于 ~2048 个令牌)
-   **缓存寿命**5分钟的不活动时间

**缓存策略 :** 对于反复出现的情况(系统提示、知识基础、少见的例子):

1.  **第一项请求**: 向缓存支付125%`cacheCreationInputTokens`(中文(简体) )
2.  **随后提出的请求** (在5分钟内):支付10%从缓存读取(`cachedInputTokens`(中文(简体) )
3.  **双向断面**: 在2个缓存读取后,你开始储蓄
4.  **长期**: 大量节省经常使用的上下文

**当缓存帮助最多时 :**

-   对请求使用长的系统提示
-   二. 大的知识基础
-   提示中少见的例子
-   具有持续背景的多回合对话
-   多次分析文件

**示例:系统提示缓存**

```typescript
// First request: Create cache
// inputTokens: 3000, cacheCreationInputTokens: 2500
// Cost: 500×1.0 + 2500×1.25 = 3625 tokens worth

// Second request: Read from cache
// inputTokens: 3000, cachedInputTokens: 2500
// Cost: 500×1.0 + 2500×0.1 = 750 tokens worth (79% savings!)

// Third+ requests: Continue reading from cache
// Same 79% savings as long as cache is active
```

## 扩展思维

Claude的思维是每个适配器的配置,然后逐字通过作为 `thinking` 请求参数,使用 `effort` 以 `output_config.effort`。两者都使用 SDK 的自有类型,因此API 支持的每一种模式都是可用的,无需修改适配器:

```typescript
const adapter = new AnthropicAdapter({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-opus-5-5",
  thinking: { type: "adaptive", display: "summarized" }, // optional
  effort: "high",                                        // optional: low | medium | high | xhigh | max
});
```

在省略时,两个参数都不发送,模型的默认适用(克洛德5代默认运行适应性思维).

**思考如何通过Flink:**

-   `thinking` 块为 `reasoning` 块并被物剂浮出水面 `reasoning_delta` 活动 `fullStream`。它们从未出现在 `textStream` 或者说 `result.message`与 `display: "omitted"` (当前模型上的默认)块以空文本到达,但仍带有签名.
-   每个 `thinking` 财务报告和审定财务报表 `redacted_thinking` 块是逐字保存的 (`providerData.anthropic.thinkingBlocks`)在助理留言和 **在文本之前重播, 工具调用后关**,Anthropic要求签名在整个工具使用中保持有效.
-   另一供应商制造的思维痕迹没有安特罗克的签名,被跳过.

## 结构化输出和工具选择

两者均由代理人每拨电话要求(`model.structuredOutput` 编号 : `model.toolChoice`,或 `execute({ model: { ... } })`; 普通案件适配器上没有配置任何内容.

**结构化产出** 以两种方式之一实现,由 `structuredOutputMode`数字 :

| 模式 | 发送什么 |
| --- | --- |
| `"native"` | `output_config.format: { type: "json_schema", schema }` ——Messages API结构化输出功能(Sonnet 4.5, Opus 4.1, Haiku 4.5等后期) |
| `"tool"` | 一个以格式命名的单一工具,其图案为 `input_schema`,强制使用 `tool_choice`。由此产生的工具调用被转换为 JSON 文本回复,所以代理将它完全看做是本地回复。 每个工具能力模型都有工作,包括Claude 3.x |
| `"auto"` (默认) | `"native"` 当配置的模型支持时, 否则 `"tool"` |

```typescript
new AnthropicAdapter({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-3-5-sonnet-20241022",
  structuredOutputMode: "tool", // optional, auto-detected from the model by default
});
```

原生路径将图案减少为结构化的输出子集:数字和长度限制(`minimum`, (中文(简体) ), `maxLength`, (中文(简体) ), `pattern`,...) 被剥去,每个物体都得到 `additionalProperties: false`。Flink 仍然根据整个计划验证答案,所以在界限之外的一个值失败 `StructuredOutputError` 而不是通过.

当代理也拥有真正的工具时,后退会发出 `tool_choice: { type: "any" }` 所以模型仍然可以先调用这些,然后用输出工具完成. 打电话的人自己的 `toolChoice` 尊重: `"none"` 只留下输出工具, 强制真实工具会被强制用于该步骤。 虽然扩展思维是活性的(已配置,或克勞德5默认),但API拒绝强制,因此倒置后方请求在系统中输出工具会被及时提示并依赖于Flink的验证.

**工具选择** 地图进入 `tool_choice`数字 : `"auto"` → `auto`, (中文(简体) ), `"none"` → `none`, (中文(简体) ), `"required"` → `any`, (中文(简体) ), `{ type: "tool", name }` → `tool`。只有当请求载有工具时才发送。 注意API拒绝强制选择(`any` 编号 : `tool`),而扩展思维是活性的,这是克洛德5代的默认;偏好 `structuredOutput` 当目标为JSON回复时.

## 特征

-   QQ 使用自动疗程调用支持的完整工具
-   \* 扩展思维通过(`thinking`, (中文(简体) ), `effort`思想流出为 `reasoning_delta` 并逐个重复播放
-   QQ 以事件为基础的更新流
-   \* 适当的消息转换和系统指令处理
-   ++ 处理有帮助的信件的全面错误
-   QQ 调用跟踪
-   用于工具呼叫的调试日志
-   支持所有Claude 4.5型号
-   200K令牌上下文窗口(1M in beta)
-   \* 扩展思维能力

### Claude 4.5 能力

所有Claude 4.5模型都支持:

-   **扩展思维**:加强复杂问题的推理
-   **愿景**: 处理和分析图像与文本
-   **多语言**: 多种语文的有力表现
-   **长背景**: 200K 令牌标准, 1M 令牌以β为单位
-   **工具的使用**: 复杂函数调用和工具集成

## API 密码

### `AnthropicAdapter`

```typescript
interface AnthropicAdapterOptions {
  apiKey: string;
  model: string;
  thinking?: Anthropic.ThinkingConfigParam;       // e.g. { type: "adaptive", display: "summarized" }
  effort?: "low" | "medium" | "high" | "xhigh" | "max";
  debug?: boolean;
}

class AnthropicAdapter implements LLMAdapter {
  constructor(options: AnthropicAdapterOptions);
  constructor(apiKey: string, model: string); // Legacy
}
```

#### 参数

-   `apiKey`: 您的 Anthropic API 密钥
-   `model`: Claude模型要使用(例如"Claude-sonnet-4-5-20250929")
-   `thinking`: 可选扩展思维配置,逐字发送为 `thinking`
-   `effort`: 可选工作级别,作为 `output_config.effort`
-   `debug`: 可选调试日志( 默认) `false`(中文(简体) )

### 处理错误

适配器以有帮助的信息提供全面的错误处理:

-   **400 坏请求**: 无效的模型名称、 错误的邮件或无效的工具计划
-   **401 未经批准**: 无效的 API 密钥 - 请检查您的 ATHROPIC API KEY
-   **403 禁止使用**: 权限不足或账户限制
-   **429项过多的请求**: 超过率限制 - 考虑重试逻辑
-   **500/529 服务器出错**: Anthropic服务器的临时问题 - 建议重试

所有错误包括模型名称和解析的具体指导.

#### 模式选择提示

-   使用 **索内 4.5** (单位:千美元)`claude-sonnet-4-5-20250929`)作为您的默认 - 它为大多数应用程序提供了最佳平衡
-   使用 **哈伊库 4.5** (单位:千美元)`claude-haiku-4-5-20251001`在速度重要的情况下,用于高数量、成本敏感的工作量
-   使用 **目标4.5** (单位:千美元)`claude-opus-4-5-20251101`)用于复杂推理,高级编码,或当需要最大智能时

您也可以使用模型化名, 如 `claude-sonnet-4-5` 它自动指向最新的快照,尽管建议制作特定的版本ID,以确保行为一致.

## 从克洛德3号搬到克洛德4.5号

如果您目前使用克洛德3型号,只需更新适配器配置中的模型ID:

```typescript
// Before (Claude 3.5 Sonnet)
new AnthropicAdapter(apiKey, "claude-3-5-sonnet-20241022")

// After (Claude Sonnet 4.5)
new AnthropicAdapter(apiKey, "claude-sonnet-4-5-20250929")
```

升级至克洛德4.5的好处:

-   **业绩更好**改进推理和编码能力
-   **扩展思维**: 支持复杂问题的解决
-   **低潜伏度**: 更快的反应时间(特别是海库4.5)
-   **提高成本效益**: Haiku 4.5 以更低的成本提供近端性能

适配器自动处理所有API差异——除型号ID外不需要代码更改.

## 所需资源

-   节点.js 18
-   @flink-app/flink >= 1.0.0
-   @humanic-ai/sdk 0.30.0 (英语)

## 许可证

麻省理工学院

## 常见问题

### @flink-app/anthropic-adapter 是什么？

Flink AI 框架的 Anthropic Claude 适配器

### 如何安装 @flink-app/anthropic-adapter？

在项目目录运行 npm install @flink-app/anthropic-adapter，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@flink-app/flink（\>=2\.0\.0-alpha\.134）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @flink-app/anthropic-adapter 支持 TypeScript 吗？

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

### @flink-app/anthropic-adapter 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @flink-app/anthropic-adapter 可以商用吗？

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

### @flink-app/anthropic-adapter 的下载量有多少？

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

### @flink-app/anthropic-adapter 还在维护吗？

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