npm package: @jgg0sbp66/koishi-plugin-askai
Description: AI chat assistant plugin with context memory and user-level API configuration
Latest version: 0.0.1

# @jgg0sbp66/koishi-plugin-askai

[![npm](https://img.shields.io/npm/v/@jgg0sbp66/koishi-plugin-askai?style=flat-square)](https://www.npmjs.com/package/@jgg0sbp66/koishi-plugin-askai)

# koishi-plugin-askai

[![npm](https://img.shields.io/npm/v/@jgg0sbp66/koishi-plugin-askai?style=flat-square)](https://www.npmjs.com/package/@jgg0sbp66/koishi-plugin-askai)

一个功能完整的 Koishi AI 聊天插件，支持用户自定义 API Key 和 URL，并具有上下文记忆功能。

## 功能特性

- ✅ **用户级配置**：每个用户可以绑定自己的 API Key 和 API URL
- 🧠 **上下文记忆**：支持多轮对话，自动保存聊天历史
- 🔒 **会话隔离**：不同频道、不同用户的对话完全独立
- ⚙️ **灵活配置**：支持自定义模型、历史长度、超时时间等
- 🎯 **系统提示词**：可自定义 AI 角色和行为
- 📊 **会话管理**：查看历史、清空会话等管理功能

## 安装

```bash
npm install @jgg0sbp66/koishi-plugin-askai
```

## 快速开始

### 1. 配置插件

在 Koishi 配置文件中启用插件，或在控制台插件市场中安装。

插件配置项：

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `maxHistoryLength` | number | 10 | 每个会话保留的最大历史消息数 |
| `defaultModel` | string | gpt-3.5-turbo | 默认使用的 AI 模型 |
| `timeout` | number | 60000 | 请求超时时间（毫秒） |

### 2. 绑定 API Key

用户首次使用前需要绑定自己的 API Key 和 URL：

```
askai.bind sk-xxxxxxxxxxxxxxxx
askai.seturl https://api.openai.com/v1/chat/completions
```

### 3. 开始聊天

```
askai 你好，请介绍一下自己
ai 今天天气怎么样？
```

## 命令列表

### 基础命令

- `askai <message>` / `ai <message>` - 向 AI 提问
- `askai.bind <apiKey>` - 绑定 API Key
- `askai.seturl <url>` - 设置 API URL
- `askai.model [model]` - 设置或查看使用的模型

### 管理命令

- `askai.config` - 查看当前配置信息
- `askai.clear` - 清空当前会话的聊天历史
- `askai.history` - 查看当前会话的聊天历史
- `askai.system <prompt>` - 设置系统提示词

## 使用示例

### 基础对话

```
用户: askai 你好
AI: 你好！我是一个 AI 助手，很高兴为你服务。有什么我可以帮助你的吗？

用户: ai 刚才我说了什么？
AI: 你刚才说"你好"。
```

### 自定义 AI 角色

```
用户: askai.system 你是一个专业的 Python 程序员，擅长解答编程问题
系统: ✅ 系统提示词已设置

用户: askai 如何在 Python 中读取 JSON 文件？
AI: 在 Python 中读取 JSON 文件很简单，可以使用内置的 json 模块...
```

### 会话管理

```
用户: askai.history
系统: 📜 聊天历史：

👤 user:
你好

🤖 assistant:
你好！我是一个 AI 助手...

用户: askai.clear
系统: ✅ 聊天历史已清空
```

### 配置不同的 AI 服务

```
# 使用 OpenAI
askai.seturl https://api.openai.com/v1/chat/completions
askai.model gpt-4

# 使用兼容的第三方服务
askai.seturl https://your-api-endpoint.com/v1/chat/completions
askai.model your-model-name
```

## 会话机制

- 每个会话基于 `平台:频道:用户` 唯一标识
- 会话自动保存最近的对话历史
- 1小时未活动的会话会自动清理
- 可通过 `askai.clear` 手动清空会话

## API 兼容性

本插件兼容 OpenAI Chat Completions API 格式，支持：

- OpenAI 官方 API
- Azure OpenAI Service
- 其他兼容 OpenAI API 格式的服务（如 Anthropic、Together AI 等）

请求格式：
```json
{
  "model": "gpt-3.5-turbo",
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ]
}
```

## 数据存储

- **API 配置**：存储在 Koishi 数据库的 `user` 表中
- **聊天历史**：存储在内存中，重启后清空
- API Key 在数据库中以明文存储，请确保数据库安全

## 安全建议

1. 不要在公共场合分享你的 API Key
2. 定期更换 API Key
3. 使用 `askai.config` 查看配置时，API Key 会自动脱敏显示
4. 建议使用有额度限制的 API Key

## 故障排除

### API 调用失败

```
❌ AI 调用失败：...
```

可能的原因：
- API Key 错误或已过期
- API URL 不正确
- 网络连接问题
- API 服务端问题
- 请求超时

解决方法：
1. 检查 API Key：`askai.config`
2. 验证 URL 格式是否正确
3. 测试网络连接
4. 增加超时时间配置

### 无法保存配置

确保 Koishi 已正确配置数据库插件（如 `@koishijs/plugin-database-sqlite`）

## 开发

```bash
# 安装依赖
npm install

# 构建
npm run build

# 发布
npm publish
```

## 许可证

MIT License

## 更新日志

### 0.0.1

- 初始版本发布
- 支持基础的 AI 聊天功能
- 支持用户级 API 配置
- 支持上下文记忆
- 支持会话管理