npm package: @hopemyl619/deepseek
Description: DeepSeek provider for the Vercel AI SDK with automatic finish_reason fix for tool calls
Latest version: 0.3.4

# @hopemyl619/deepseek

DeepSeek 模型服务提供商，专为 Vercel AI SDK 设计。

## 核心特性

- ✅ 完整支持 DeepSeek 系列聊天模型
- ✅ 自动修复工具调用的 `finish_reason` 字段
- ✅ 中文参数预处理（城市名称自动转换）
- ✅ 流式输出支持
- ✅ 工具调用支持
- ✅ 完整的 TypeScript 类型定义

## 快速开始

### 安装依赖

```bash
npm install @hopemyl619/deepseek ai
```

### 基本用法

```typescript
import { deepseek } from '@hopemyl619/deepseek';
import { generateText } from 'ai';

async function main() {
  const { text } = await generateText({
    model: deepseek('deepseek-chat'),
    prompt: '你好，请介绍一下你自己',
  });

  console.log(text);
}

main();
```

## 使用示例

### 流式文本生成

```typescript
import { deepseek } from '@hopemyl619/deepseek';
import { streamText } from 'ai';

async function main() {
  const result = await streamText({
    model: deepseek('deepseek-chat'),
    prompt: '请写一首关于春天的诗',
  });

  for await (const chunk of result.textStream) {
    process.stdout.write(chunk);
  }
}

main();
```

### 工具调用

```typescript
import { deepseek } from '@hopemyl619/deepseek';
import { generateText, tool } from 'ai';
import { z } from 'zod';

async function main() {
  const { toolCalls } = await generateText({
    model: deepseek('deepseek-chat'),
    tools: {
      getWeather: tool({
        description: '获取指定城市的天气信息',
        parameters: z.object({
          location: z.string().describe('城市名称'),
        }),
        execute: async ({ location }) => {
          // 调用天气 API
          return { temperature: 22, condition: '晴天' };
        },
      }),
    },
    prompt: '北京今天的天气怎么样？',
  });

  console.log('工具调用结果：', toolCalls);
}

main();
```

### 自定义 API 地址

```typescript
import { createDeepSeek } from '@hopemyl619/deepseek';

const customDeepSeek = createDeepSeek({
  baseURL: 'http://your-custom-endpoint/v1',
  apiKey: 'your-api-key',
});

const { text } = await generateText({
  model: customDeepSeek('deepseek-chat'),
  prompt: '你好',
});
```

## 高级功能

### 自动修复 finish_reason

DeepSeek API 在某些情况下会返回 `finish_reason: 'stop'` 而非预期的 `finish_reason: 'tool-calls'`。本提供商会自动检测并修复此问题，确保工具调用流程正常执行。

### 中文参数预处理

工具调用参数中的中文城市名称会自动转换为英文：

| 中文 | 英文 |
|------|------|
| 北京 | Beijing |
| 上海 | Shanghai |
| 广州 | Guangzhou |
| 深圳 | Shenzhen |

添加自定义映射：

```typescript
import { ChineseParamsPreprocessor } from '@hopemyl619/deepseek';

const preprocessor = new ChineseParamsPreprocessor();
preprocessor.addCityMapping('成都', 'Chengdu');
```

## 在 iFlow CLI 中配置

在 `~/.iflow/settings.json` 中添加配置：

```json
{
  "modelName": "DeepSeek-V3.2-671B",
  "baseUrl": "https://api.deepseek.com/v1",
  "apiKey": "${DEEPSEEK_API_KEY}"
}
```

设置环境变量：

```bash
export DEEPSEEK_API_KEY=your-api-key
```

## 支持的模型

- `deepseek-chat` - 通用聊天模型
- `deepseek-coder` - 代码专用模型
- `DeepSeek-V3.2-671B` - 超大规模模型

## 测试

```bash
# 运行单元测试
npm test

# 类型检查
npm run typecheck

# 构建项目
npm run build
```

## 项目结构

```
@hopemyl619/deepseek/
├── src/
│   ├── deepseek-provider.ts    # 提供商主文件
│   ├── deepseek-chat-language-model.ts
│   ├── deepseek-chat-settings.ts
│   ├── types.ts                # 类型定义
│   └── utils/
│       ├── request-transformer.ts    # 请求转换
│       ├── response-transformer.ts   # 响应转换
│       ├── stream-parser.ts          # 流式解析
│       └── chinese-params-preprocessor.ts  # 中文预处理
├── test/
│   ├── stream-parser.test.ts   # 流式解析测试
│   └── integration.test.ts     # 集成测试
└── examples/
    └── basic-usage.ts          # 使用示例
```

## 常见问题

### Q: 工具调用没有触发执行？
A: 检查 DeepSeek API 返回的 `finish_reason`，本提供商已自动修复 `stop` → `tool-calls` 的转换。

### Q: 中文参数没有转换？
A: 确保使用 `ChineseParamsPreprocessor` 类处理参数，或检查映射配置是否正确。

### Q: 流式输出不完整？
A: StreamParser 已支持 JSON in content 格式，确保使用最新版本。

## 版本历史

### v0.1.0
- 初始版本发布
- 支持基础聊天功能
- 支持流式输出
- 支持工具调用
- 自动 finish_reason 修复
- 中文参数预处理

## 许可证

MIT