open-index/open-npm huggingface dataset:
npm package: @onebots/adapter-dingtalk
Description: onebots 钉钉适配器
Author: 凉菜
Latest version: 1.0.7

# @onebots/adapter-dingtalk

onebots 钉钉适配器

## 安装

```bash
npm install @onebots/adapter-dingtalk
# 或
pnpm add @onebots/adapter-dingtalk
```

## 配置

### 企业内部应用模式

在 `config.yaml` 中配置：

```yaml
dingtalk.your_bot_id:
  app_key: "YOUR_APP_KEY"
  app_secret: "YOUR_APP_SECRET"
  agent_id: "YOUR_AGENT_ID"  # 可选
  encrypt_key: "YOUR_ENCRYPT_KEY"  # 可选，事件加密密钥
  token: "YOUR_TOKEN"  # 可选，事件验证 Token
```

### 自定义机器人模式（Webhook）

在 `config.yaml` 中配置：

```yaml
dingtalk.your_bot_id:
  webhook_url: "https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN"
```

## 使用

```bash
onebots -r dingtalk
```

## 功能

### 企业内部应用模式
- ✅ 单聊消息收发
- ✅ 群聊消息收发
- ✅ 文本消息
- ✅ Markdown 消息
- ✅ 卡片消息（部分支持）
- ✅ 事件订阅（Webhook）
- ✅ 用户信息获取

### 自定义机器人模式（Webhook）
- ✅ 群聊消息推送
- ✅ 文本消息
- ✅ Markdown 消息
- ✅ @用户、@所有人
- ✅ 卡片消息（部分支持）

## 获取应用凭证

### 企业内部应用

1. 访问 [钉钉开放平台](https://open.dingtalk.com/)
2. 创建企业内部应用
3. 获取 `AppKey` 和 `AppSecret`
4. 获取 `AgentId`（可选）
5. 配置事件订阅 URL（Webhook）
6. 配置应用权限（消息收发、通讯录等）

### 自定义机器人

1. 在钉钉群聊中，点击"群设置" -> "智能群助手" -> "添加机器人"
2. 选择"自定义"机器人
3. 获取 Webhook URL

## 相关链接

- [钉钉开放平台](https://open.dingtalk.com/)
- [钉钉机器人开发文档](https://open.dingtalk.com/document/robots/robot-overview)
- [onebots 文档](https://onebots.js.org/)
npm package: @onebots/adapter-email
Description: onebots 邮件适配器
Author: 凉菜
Latest version: 1.0.6

# @onebots/adapter-email

onebots 邮件适配器，支持通过 SMTP 发送邮件和 IMAP 接收邮件。

## 特性

- ✅ SMTP 发送邮件
- ✅ IMAP 接收邮件
- ✅ 支持 HTML 和纯文本邮件
- ✅ 支持附件
- ✅ 支持代理配置
- ✅ 自动轮询新邮件
- ✅ 支持回复邮件

## 安装

```bash
pnpm add @onebots/adapter-email
```

## 配置

```yaml
email.my_bot:
  # 发件人配置
  from: 'bot@example.com'
  fromName: '我的机器人'  # 可选
  
  # SMTP 配置（发送邮件）
  smtp:
    host: 'smtp.example.com'
    port: 587
    secure: false
    requireTLS: true
    user: 'bot@example.com'
    password: 'your_password'
  
  # IMAP 配置（接收邮件）
  imap:
    host: 'imap.example.com'
    port: 993
    tls: true
    user: 'bot@example.com'
    password: 'your_password'
    pollInterval: 30000  # 轮询间隔（毫秒），默认 30 秒
    mailbox: 'INBOX'    # 监听的邮箱文件夹，默认 INBOX
  
  # 协议配置
  onebot.v11:
    access_token: 'your_token'
```

## 使用示例

### 发送邮件

通过 OneBot 协议发送邮件：

```javascript
// 发送邮件到 user@example.com
await bot.sendMessage('user@example.com', {
  scene_id: bot.createId('user@example.com'),
  scene_type: 'private',
  message: [
    { type: 'text', data: { text: '这是一封测试邮件' } }
  ]
});
```

### 接收邮件

邮件适配器会自动轮询新邮件，并将邮件转换为消息事件：

```javascript
bot.on('message', (event) => {
  if (event.platform === 'email') {
    console.log('收到邮件:', event.sender.name, event.message);
  }
});
```

## 支持的邮件服务商

### Gmail

```yaml
smtp:
  host: 'smtp.gmail.com'
  port: 587
  user: 'your-email@gmail.com'
  password: 'your-app-password'  # 需要使用应用专用密码

imap:
  host: 'imap.gmail.com'
  port: 993
  user: 'your-email@gmail.com'
  password: 'your-app-password'
```

### Outlook/Hotmail

```yaml
smtp:
  host: 'smtp-mail.outlook.com'
  port: 587
  user: 'your-email@outlook.com'
  password: 'your-password'

imap:
  host: 'outlook.office365.com'
  port: 993
  user: 'your-email@outlook.com'
  password: 'your-password'
```

### QQ 邮箱

```yaml
smtp:
  host: 'smtp.qq.com'
  port: 587
  user: 'your-email@qq.com'
  password: 'your-authorization-code'  # 需要使用授权码

imap:
  host: 'imap.qq.com'
  port: 993
  user: 'your-email@qq.com'
  password: 'your-authorization-code'
```

## 注意事项

1. **应用专用密码**：某些邮件服务商（如 Gmail）需要使用应用专用密码，而不是普通密码
2. **授权码**：某些邮件服务商（如 QQ 邮箱）需要使用授权码
3. **轮询间隔**：建议设置合理的轮询间隔，避免过于频繁的请求
4. **代理配置**：如果需要通过代理访问邮件服务器，可以在配置中添加 `proxy` 字段

## 相关链接

- [适配器配置指南](/guide/adapter)
- [邮件平台文档](/platform/email)
npm package: @onebots/adapter-feishu
Description: onebots 飞书适配器
Author: 凉菜
Latest version: 1.0.7

# @onebots/adapter-feishu

onebots 飞书/Lark 适配器，同时支持飞书（国内版）和 Lark（国际版）。

## 安装

```bash
npm install @onebots/adapter-feishu
# 或
pnpm add @onebots/adapter-feishu
```

## 配置

在 `config.yaml` 中配置：

```yaml
# 飞书（国内版）- 默认
feishu.feishu_bot:
  app_id: "YOUR_APP_ID"
  app_secret: "YOUR_APP_SECRET"
  encrypt_key: "YOUR_ENCRYPT_KEY"  # 可选，事件加密密钥
  verification_token: "YOUR_VERIFICATION_TOKEN"  # 可选，事件验证 Token

# Lark（国际版）
feishu.lark_bot:
  app_id: "YOUR_APP_ID"
  app_secret: "YOUR_APP_SECRET"
  endpoint: "https://open.larksuite.com/open-apis"  # Lark 端点
```

### 端点配置

| 端点 | URL | 说明 |
|------|-----|------|
| 飞书（默认） | `https://open.feishu.cn/open-apis` | 国内版 |
| Lark | `https://open.larksuite.com/open-apis` | 国际版 |

### TypeScript 配置（推荐）

```typescript
import { FeishuEndpoint } from '@onebots/adapter-feishu';

// 飞书（国内版）
{
  account_id: 'feishu_bot',
  app_id: 'cli_xxx',
  app_secret: 'xxx',
  // endpoint 可省略，默认为 FeishuEndpoint.FEISHU
}

// Lark（国际版）
{
  account_id: 'lark_bot',
  app_id: 'cli_xxx',
  app_secret: 'xxx',
  endpoint: FeishuEndpoint.LARK,
}

// 私有化部署
{
  account_id: 'private_bot',
  app_id: 'cli_xxx',
  app_secret: 'xxx',
  endpoint: 'https://your-private-feishu.com/open-apis',
}
```

## 使用

```bash
onebots -r feishu
```

## 功能

- ✅ 单聊消息收发
- ✅ 群聊消息收发
- ✅ 文本消息
- ✅ 富文本消息（部分支持）
- ✅ 消息编辑和删除
- ✅ 群组管理（获取信息、踢出成员等）
- ✅ 事件订阅（Webhook）
- ✅ 支持飞书和 Lark 双端点

## 获取应用凭证

### 飞书（国内版）
1. 访问 [飞书开放平台](https://open.feishu.cn/)
2. 创建企业自建应用
3. 获取 `App ID` 和 `App Secret`
4. 配置事件订阅 URL（Webhook）
5. 配置应用权限（消息收发、通讯录等）

### Lark（国际版）
1. 访问 [Lark Developer](https://open.larksuite.com/)
2. 创建应用并获取凭证
3. 配置方式与飞书相同，只需设置 `endpoint` 为 Lark 端点

## 相关链接

- [飞书开放平台](https://open.feishu.cn/)
- [Lark Developer](https://open.larksuite.com/)
- [飞书 Bot 开发文档](https://open.feishu.cn/document/ukTMukTMukTM/uczM3QjL3MzN04yNzcDN)
- [onebots 文档](https://onebots.pages.dev/)
npm package: @onebots/adapter-kook
Description: onebots KOOK(开黑了)适配器
Author: 凉菜
Latest version: 1.0.7

# @onebots/adapter-kook

onebots KOOK (开黑了) 适配器

## 简介

这是一个用于 onebots 框架的 KOOK（原开黑了）平台适配器。KOOK 是一个面向游戏玩家的即时通讯平台，类似于 Discord。

## 功能特性

- ✅ WebSocket 和 Webhook 两种连接模式
- ✅ 频道消息收发
- ✅ 私聊消息收发
- ✅ 服务器（公会）管理
- ✅ 频道管理
- ✅ 成员管理
- ✅ 角色管理
- ✅ 表情回应
- ✅ 文件上传
- ✅ KMarkdown 消息格式支持
- ✅ 卡片消息支持

## 安装

```bash
npm install @onebots/adapter-kook
# 或
pnpm add @onebots/adapter-kook
```

## 配置

在配置文件中添加 KOOK 账号：

```yaml
accounts:
  - platform: kook
    account_id: your_bot_id
    token: your_bot_token
    mode: websocket  # 或 webhook
    verifyToken: your_verify_token  # Webhook 模式需要
    encryptKey: your_encrypt_key  # 可选，消息加密密钥
```

### 配置项说明

| 配置项 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| account_id | string | 是 | 机器人账号 ID |
| token | string | 是 | 机器人 Token |
| mode | string | 否 | 连接模式：`websocket`（默认）或 `webhook` |
| verifyToken | string | 否 | Webhook 验证 Token |
| encryptKey | string | 否 | 消息加密密钥 |

## 获取 Token

1. 访问 [KOOK 开发者平台](https://developer.kookapp.cn/)
2. 创建应用并添加机器人
3. 在机器人设置中获取 Token

## 消息类型支持

### 发送消息

支持的消息段类型：
- `text` - 文本消息
- `at` - @用户/全体成员/在线成员
- `image` - 图片消息
- `face` - 表情

### 接收消息

支持的消息类型：
- 文字消息
- KMarkdown 消息
- 图片消息
- 视频消息
- 文件消息
- 音频消息
- 卡片消息

## API 支持

### 消息相关
- `sendMessage` - 发送消息
- `deleteMessage` - 删除消息
- `getMessage` - 获取消息
- `updateMessage` - 更新消息

### 用户相关
- `getLoginInfo` - 获取机器人信息
- `getUserInfo` - 获取用户信息
- `getFriendList` - 获取私聊会话列表
- `getFriendInfo` - 获取好友信息

### 服务器相关
- `getGroupList` - 获取服务器列表
- `getGroupInfo` - 获取服务器信息
- `leaveGroup` - 退出服务器
- `getGroupMemberList` - 获取服务器成员列表
- `getGroupMemberInfo` - 获取成员信息
- `kickGroupMember` - 踢出成员
- `setGroupCard` - 设置成员昵称

### 频道相关
- `getChannelList` - 获取频道列表
- `getChannelInfo` - 获取频道信息
- `createChannel` - 创建频道
- `updateChannel` - 更新频道
- `deleteChannel` - 删除频道
- `getChannelMemberList` - 获取频道成员列表

### 公会相关
- `getGuildList` - 获取服务器列表
- `getGuildInfo` - 获取服务器信息
- `getGuildMemberInfo` - 获取成员信息

## 事件支持

### 消息事件
- 频道消息
- 私聊消息

### 通知事件
- 成员加入服务器
- 成员离开服务器
- 表情回应添加
- 消息更新
- 消息删除

## 许可证

MIT
npm package: @onebots/adapter-slack
Description: onebots Slack适配器
Author: 凉菜
Latest version: 1.0.7

# @onebots/adapter-slack

onebots Slack 适配器

## 安装

```bash
npm install @onebots/adapter-slack @slack/web-api
# 或
pnpm add @onebots/adapter-slack @slack/web-api
```

## 配置

在 `config.yaml` 中配置：

```yaml
slack.your_bot_id:
  token: "xoxb-YOUR-BOT-TOKEN"
  signing_secret: "YOUR_SIGNING_SECRET"  # 可选，用于验证请求
  app_token: "xapp-YOUR-APP-TOKEN"  # 可选，用于 Socket Mode
  socket_mode: false  # 是否使用 Socket Mode
```

## 使用

```bash
onebots -r slack
```

## 功能

- ✅ 频道消息收发
- ✅ 私聊消息收发
- ✅ 文本消息
- ✅ 富文本消息（Blocks）
- ✅ 消息编辑和删除
- ✅ 频道管理（获取信息、离开频道等）
- ✅ 事件订阅（Events API）
- ✅ 应用命令（Slash Commands，需要额外配置）
- ✅ 交互式组件（需要额外配置）

## 获取 Bot Token

1. 访问 [Slack API](https://api.slack.com/)
2. 创建应用（Create New App）
3. 在 "OAuth & Permissions" 中配置权限
4. 安装应用到工作区
5. 获取 Bot User OAuth Token（xoxb-...）
6. 在 "Event Subscriptions" 中配置 Webhook URL
7. 获取 Signing Secret（用于验证请求）

## 相关链接

- [Slack API 文档](https://api.slack.com/)
- [Slack Bot 开发文档](https://api.slack.com/bot-users)
- [@slack/web-api 文档](https://slack.dev/node-slack-sdk/web-api)
- [onebots 文档](https://onebots.js.org/)
npm package: @onebots/adapter-teams
Description: onebots Microsoft Teams适配器
Author: 凉菜
Latest version: 1.0.7

# @onebots/adapter-teams

onebots Microsoft Teams 适配器 - 支持 Microsoft Teams Bot Framework 的机器人适配器

## 简介

`@onebots/adapter-teams` 是 onebots 框架的官方 Microsoft Teams 适配器，用于连接 Microsoft Teams 平台，将 Teams 的消息和事件转换为 onebots 的通用格式。

## 特性

- 🔐 **Bot Framework 支持** - 基于 Microsoft Bot Framework SDK
- 📨 **消息处理** - 完整的消息接收和发送支持
- 🎯 **事件处理** - 支持消息、成员加入/离开等事件
- 🔄 **自动转换** - 自动将 Teams 消息转换为通用格式
- 📡 **Webhook** - 支持 Teams Webhook 回调
- 🎨 **自适应卡片** - 支持发送 Teams 自适应卡片

## 安装

```bash
npm install @onebots/adapter-teams
# 或
pnpm add @onebots/adapter-teams
```

## 使用方法

> **重要：** 适配器必须先注册才能使用。即使在配置文件中配置了 Teams 账号，如果没有注册该适配器，配置也不会生效。

### 1. 命令行注册（推荐）

使用 `onebots` 命令行工具时，通过 `-r` 参数注册适配器：

```bash
# 注册 Teams 适配器
onebots -r teams

# 同时注册多个适配器
onebots -r teams -r telegram -r slack
```

### 2. 配置文件方式

在 `config.yaml` 中配置：

```yaml
accounts:
  - platform: teams
    account_id: my_teams_bot
    protocol: onebot.v11
    
    # Microsoft Teams 配置
    app_id: your_app_id
    app_password: your_app_password
    webhook:
      url: https://your-domain.com/teams/my_teams_bot/webhook
      port: 8080
```

### 3. 代码方式

```typescript
import { App } from 'onebots';
import { TeamsAdapter } from '@onebots/adapter-teams';

// 注册适配器
await App.registerAdapter('teams', TeamsAdapter);

// 创建应用
const app = new App({
  accounts: [{
    platform: 'teams',
    account_id: 'my_teams_bot',
    protocol: 'onebot.v11',
    app_id: 'your_app_id',
    app_password: 'your_app_password',
  }],
});

// 启动应用
await app.start();
```

## 配置说明

### 必需配置

- `app_id`: Microsoft App ID（从 Azure Portal 获取）
- `app_password`: Microsoft App Password（从 Azure Portal 获取）

### 可选配置

- `webhook.url`: Webhook URL（如果使用自定义域名）
- `webhook.port`: Webhook 端口（默认使用全局配置）
- `channel_service`: Channel Service URL（用于政府云等特殊环境）
- `open_id_metadata`: OpenID Metadata URL（用于自定义认证）

## Microsoft Teams 配置

1. 登录 [Azure Portal](https://portal.azure.com)
2. 创建 Azure Bot 资源
3. 获取 **App ID** 和 **App Password**
4. 配置 **Messaging endpoint** 为：`https://your-domain.com/teams/{account_id}/webhook`
5. 在 Teams 中测试 Bot

## 功能支持

### ✅ 已实现功能

- 私聊消息收发
- 群聊消息收发
- 消息编辑
- 消息删除
- 成员加入/离开事件
- 自适应卡片发送

### ❌ 不支持的功能

- 获取消息（Bot Framework 不提供此 API）
- 获取用户信息（需从消息事件中获取）
- 获取群信息（Bot Framework 不提供此 API）
- 群成员管理（Bot Framework 不提供此 API）

## 注意事项

1. **Webhook 模式**：Teams Bot 必须使用 Webhook 模式，不支持轮询
2. **HTTPS 要求**：Webhook URL 必须是 HTTPS（生产环境）
3. **消息限制**：Teams 对消息频率有限制
4. **自适应卡片**：Teams 支持丰富的自适应卡片格式

## 许可证

与 onebots 主项目保持一致。

## 相关链接

- [Microsoft Bot Framework 文档](https://dev.botframework.com/)
- [Teams Bot 开发文档](https://docs.microsoft.com/en-us/microsoftteams/platform/bots/what-are-bots)
- [Bot Framework SDK for Node.js](https://github.com/Microsoft/botbuilder-js)
npm package: @onebots/adapter-telegram
Description: onebots Telegram适配器
Author: 凉菜
Latest version: 1.0.7

# @onebots/adapter-telegram

onebots Telegram 适配器，支持代理访问。

## 安装

```bash
npm install @onebots/adapter-telegram grammy
# 或
pnpm add @onebots/adapter-telegram grammy
```

## 配置

在 `config.yaml` 中配置：

```yaml
telegram.your_bot_id:
  token: "YOUR_BOT_TOKEN"
  
  # 代理配置（可选，用于访问 Telegram API）
  proxy:
    url: "http://127.0.0.1:7890"  # 或 socks5://127.0.0.1:1080
    # username: "user"  # 可选
    # password: "pass"  # 可选
  
  # 轮询模式（默认）
  polling:
    enabled: true
    timeout: 30
    limit: 100
  # 或 Webhook 模式
  # webhook:
  #   url: "https://your-domain.com/webhook"
  #   secret_token: "your_secret_token"
  #   allowed_updates: ["message", "callback_query"]
```

### 代理配置说明

| 配置项 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `proxy.url` | string | 是 | 代理服务器地址 |
| `proxy.username` | string | 否 | 代理用户名 |
| `proxy.password` | string | 否 | 代理密码 |

支持的代理类型：
- HTTP 代理：`http://host:port`
- HTTPS 代理：`https://host:port`

## 使用

```bash
onebots -r telegram
```

## 功能

- ✅ 私聊消息收发
- ✅ 群组消息收发
- ✅ 频道消息收发
- ✅ 图片、视频、音频、文件发送
- ✅ 消息编辑和删除
- ✅ 群组管理（获取信息、踢出成员等）
- ✅ Inline Keyboard 支持（通过 Callback Query）
- ✅ 命令处理（/command）
- ✅ **代理支持**（HTTP/HTTPS）

## 获取 Bot Token

1. 在 Telegram 中搜索 [@BotFather](https://t.me/BotFather)
2. 发送 `/newbot` 创建新机器人
3. 按照提示设置机器人名称和用户名
4. 获取 Bot Token

## 依赖说明

| 依赖 | 何时需要 | 安装命令 |
|------|----------|----------|
| `grammy` | 必需 | `npm install grammy` |
| `https-proxy-agent` | 使用代理时 | `npm install https-proxy-agent` |

### 常见问题

#### 1. 连接超时 / Network request failed

如果你在中国大陆等需要代理的地区访问 Telegram API，请配置代理：

```yaml
telegram.your_bot:
  token: 'xxx'
  proxy:
    url: "http://127.0.0.1:7890"  # 你的代理地址
```

并安装代理依赖：

```bash
npm install https-proxy-agent
```

#### 2. 代理配置后仍然超时

1. 确认代理服务正常运行
2. 检查代理地址和端口是否正确
3. 确认代理服务允许访问 `api.telegram.org`

可以用以下命令测试代理：

```bash
curl -x http://127.0.0.1:7890 https://api.telegram.org/bot<TOKEN>/getMe
```

#### 3. 缺少 https-proxy-agent 警告

如果看到 `https-proxy-agent 未安装` 警告但你需要代理：

```bash
npm install https-proxy-agent
```

## 相关链接

- [Telegram Bot API 文档](https://core.telegram.org/bots/api)
- [grammy 文档](https://grammy.dev/)
- [onebots 文档](https://onebots.pages.dev/)
npm package: @onebots/adapter-wechat-clawbot
Description: OneBots 微信扩展 ClawBot（iLink Bot HTTP）适配器：扫码登录、长轮询、会话持久化与媒体收发
Author: 凉菜
Latest version: 1.1.1

# @onebots/adapter-wechat-clawbot

OneBots 适配器：**微信 ClawBot / iLink Bot HTTP**。

- 平台标识 / `-r`：**`wechat-clawbot`**

与 **微信公众号**（`adapter-wechat`）、**企业微信**（`wecom`）、**微信客服**（`wecom-kf`）均为不同通道。

## 约定摘要

| 项目 | 说明 |
|------|------|
| API 根 | `https://ilinkai.weixin.qq.com`（适配器固定） |
| CDN 根 | `https://novac2c.cdn.weixin.qq.com/c2c` |
| 会话文件 | `{工作目录}/data/wechat-clawbot/<account_id>.json` |
| context_token | 主库 SQLite 表 **`wechat_clawbot_context_token`**（按 `account_id` + peer） |

YAML 通常只需账号键与可选超时，见文档站 [平台说明](https://github.com/lc-cn/onebots/tree/master/docs/src/platform/wechat-clawbot.md)。

## 安装与启动

```bash
pnpm add @onebots/adapter-wechat-clawbot
```

```yaml
wechat-clawbot.my_bot: {}
```

```bash
onebots -r wechat-clawbot -c config.yaml
```

## 本地构建

```bash
pnpm --filter @onebots/adapter-wechat-clawbot build
```
npm package: @onebots/adapter-wecom
Description: onebots 企业微信适配器
Author: 凉菜
Latest version: 1.0.7

# @onebots/adapter-wecom

onebots 企业微信适配器

## 安装

```bash
npm install @onebots/adapter-wecom
# 或
pnpm add @onebots/adapter-wecom
```

## 配置

在 `config.yaml` 中配置：

```yaml
wecom.your_bot_id:
  corp_id: "YOUR_CORP_ID"
  corp_secret: "YOUR_CORP_SECRET"
  agent_id: "YOUR_AGENT_ID"
  token: "YOUR_TOKEN"  # 可选，回调验证 Token
  encoding_aes_key: "YOUR_ENCODING_AES_KEY"  # 可选，消息加解密密钥
```

## 使用

```bash
onebots -r wecom
```

## 功能

- ✅ 应用消息推送
  - 文本消息
  - 图片消息
  - 视频消息
  - 文件消息
  - 文本卡片
  - Markdown 消息
- ✅ 通讯录管理
  - 获取用户信息
  - 获取部门列表
  - 获取部门成员列表
- ✅ 事件订阅
  - 通讯录变更事件
  - 应用消息回调

## 获取应用凭证

1. 访问 [企业微信管理后台](https://work.weixin.qq.com/)
2. 应用管理 → 创建应用
3. 获取 `企业ID`（CorpID）
4. 获取 `应用Secret`（CorpSecret）
5. 获取 `应用ID`（AgentID）
6. 配置回调 URL：`http://your-server:port/wecom/{account_id}/webhook`
7. 获取 `Token` 和 `EncodingAESKey`（如果启用加密）

## 相关链接

- [企业微信开放平台](https://developer.work.weixin.qq.com/)
- [企业微信应用开发文档](https://developer.work.weixin.qq.com/document/path/90488)
- [onebots 文档](https://onebots.js.org/)
npm package: @onebots/adapter-wecom-kf
Description: onebots 企业微信「微信客服」适配器（API 会话与消息）
Author: 凉菜
Latest version: 0.2.3

# @onebots/adapter-wecom-kf

OneBots 适配 **企业微信 · 微信客服**（[官方文档概述](https://developer.work.weixin.qq.com/document/path/94638)）：通过回调 `kf_msg_or_event` 触发 **`sync_msg` 拉取消息**，使用 **`send_msg`** 主动回复。

与 `@onebots/adapter-wecom`（自建应用 `/cgi-bin/message/send`）**不是**同一套 API，请勿混用。

## 前置条件

1. 企业已开通 **微信客服**，并在 **应用管理 → 微信客服 → API** 中为 **自建应用** 勾选「可调用接口的应用」。
2. 在 **通过 API 管理微信客服账号** 中，将需要机器人托管的客服号改为 API 管理（原生接待规则将暂停，需自行 `sync_msg` / `send_msg`）。
3. 客服账号的 **接待人员** 必须在自建应用 **可见范围** 内，否则常见错误 **`60030`**。

## 安装

```bash
pnpm add @onebots/adapter-wecom-kf
# 依赖主包 onebots
```

## 启动

```bash
npx onebots -r wecom-kf -p onebot-v11 -c config.yaml
```

## 配置示例 `config.yaml`

```yaml
wecom-kf.mykf:
  corp_id: 'wwxxxxxxxx'
  corp_secret: '应用Secret'
  token: '回调Token'
  encoding_aes_key: 'EncodingAESKey'
  open_kfid: 'wkxxxx'   # 默认客服账号，回调中的 OpenKfId 优先
  agent_id: '1000001'   # 发送图片/文件等需先上传临时素材时填写
  cursor_store_path: './data/wecom-kf-cursor.json'  # 可选，持久化 sync_msg 游标
  enable_sync_poll: false   #  true：无 token 定时 sync_msg（易触发频次限制）
  sync_poll_interval_ms: 30000
  onebot.v11:
    access_token: 'your_token'
```

## 回调 URL

在微信客服 / 接收消息 中填写（将 `account_id` 换成配置键名，如 `mykf`）：

```text
https://你的域名/wecom-kf/mykf/webhook
```

需同时支持 **GET**（URL 校验）与 **POST**（`Encrypt` 密文）。

### 可信域名校验文件（如 `WW_verify_xxx.txt`）

企业微信要求校验文件能通过 **站点根路径** 下载。在 OneBots 全局配置中设置 `public_static_dir`（例如 `static`），将 txt 放在该目录下即可由网关对外提供；Docker 可将文件放入挂载卷内的 `/data/static`。

## 消息流说明

1. 企业微信 POST 密文事件，解密后若为 `kf_msg_or_event`，从 XML 取 `Token`、`OpenKfId`。
2. 使用 `sync_msg`（带 `token` + `open_kfid` + 本地 `cursor`）分页拉取 **`msg_list`**。
3. 将 **客户消息**（`origin === 3`）与 **接待人员消息**（`origin === 5`）转为 OneBots `message`；`msgtype === event` 转为 `notice`（`notice_type: custom`）。
4. 回复：协议层 `sendMessage` → `send_msg`（`touser` 为 `external_userid`）。

受限于微信客服规则：用户发消息后 **48 小时内**、最多 **5 条** 等限制以官方最新文档为准。

## Bot 进阶 API

`Account` 的 `client` 为 `WeComKfBot`，还可调用：

- `serviceStateGet` / `serviceStateTrans`（[会话分配](https://developer.work.weixin.qq.com/document/path/94669)）
- `customerBatchGet`（[客户基础信息](https://developer.work.weixin.qq.com/document/path/95159)）

## 相关链接

- [接收消息和事件 / sync_msg](https://developer.work.weixin.qq.com/document/path/94670)
- [发送消息 send_msg](https://developer.work.weixin.qq.com/document/path/94677)
npm package: @onebots/adapter-whatsapp
Description: onebots WhatsApp 适配器
Author: 凉菜
Latest version: 1.0.6

# @onebots/adapter-whatsapp

onebots WhatsApp 适配器，基于 WhatsApp Business API (Meta Graph API)。

参考 [Satori WhatsApp 适配器](https://github.com/satorijs/satori/tree/main/adapters/whatsapp) 实现。

## 特性

- ✅ 消息发送与接收
- ✅ 支持文本、图片、视频、音频、文档、位置等消息类型
- ✅ Webhook 事件处理
- ✅ 消息状态跟踪
- ✅ 媒体文件下载
- ✅ 代理配置支持

## 安装

```bash
pnpm add @onebots/adapter-whatsapp
```

## 配置

### 前置要求

1. **创建 Meta 应用**
   - 访问 [Meta for Developers](https://developers.facebook.com/)
   - 创建应用并添加 WhatsApp 产品

2. **获取凭证**
   - Business Account ID
   - Phone Number ID
   - Access Token（永久令牌或临时令牌）
   - Webhook Verify Token

3. **配置 Webhook**
   - 设置 Webhook URL: `https://your-domain.com/whatsapp/{account_id}/webhook`
   - 订阅字段: `messages`, `message_status`

### 配置示例

```yaml
whatsapp.my_bot:
  # WhatsApp Business API 配置
  businessAccountId: 'your_business_account_id'
  phoneNumberId: 'your_phone_number_id'
  accessToken: 'your_access_token'
  webhookVerifyToken: 'your_verify_token'
  apiVersion: 'v21.0'  # 可选，默认 v21.0
  
  # Webhook 配置
  webhook:
    url: 'https://your-domain.com/whatsapp/my_bot/webhook'
    fields: ['messages', 'message_status']
  
  # 代理配置（可选）
  proxy:
    url: 'http://127.0.0.1:7890'
  
  # 协议配置
  onebot.v11:
    access_token: 'your_token'
```

## 使用示例

### 发送消息

通过 OneBot 协议发送消息：

```javascript
// 发送文本消息
await bot.sendMessage('8613800138000', {
  scene_id: bot.createId('8613800138000'),
  scene_type: 'private',
  message: [
    { type: 'text', data: { text: 'Hello from WhatsApp!' } }
  ]
});

// 发送图片
await bot.sendMessage('8613800138000', {
  scene_id: bot.createId('8613800138000'),
  scene_type: 'private',
  message: [
    { 
      type: 'image', 
      data: { 
        url: 'https://example.com/image.jpg',
        caption: 'Image caption'
      } 
    }
  ]
});
```

### 接收消息

适配器会自动接收 Webhook 事件并转换为消息事件：

```javascript
bot.on('message', (event) => {
  if (event.platform === 'whatsapp') {
    console.log('收到 WhatsApp 消息:', event.sender.name, event.message);
  }
});
```

## 消息类型支持

| 消息类型 | 支持 | 说明 |
|---------|------|------|
| 文本 | ✅ | 支持纯文本消息 |
| 图片 | ✅ | 支持图片和图片说明 |
| 视频 | ✅ | 支持视频和视频说明 |
| 音频 | ✅ | 支持音频消息 |
| 文档 | ✅ | 支持文档和文档说明 |
| 位置 | ✅ | 支持位置信息 |
| 联系人 | ✅ | 支持联系人卡片 |
| 模板消息 | ✅ | 支持 WhatsApp 模板消息 |

## 注意事项

1. **电话号码格式**：必须包含国家代码，例如 `8613800138000`（中国）
2. **消息模板**：业务发起的消息需要使用预审核的模板
3. **24小时窗口**：用户主动发送消息后，24小时内可以自由回复
4. **Webhook 验证**：必须正确配置 Webhook 验证令牌
5. **API 限制**：注意 WhatsApp API 的速率限制和配额

## 相关链接

- [WhatsApp Business API 文档](https://developers.facebook.com/docs/whatsapp)
- [Meta Graph API 文档](https://developers.facebook.com/docs/graph-api)
- [适配器配置指南](/guide/adapter)
- [WhatsApp 平台文档](/platform/whatsapp)
npm package: @onebots/adapter-zulip
Description: onebots Zulip 适配器
Author: 凉菜
Latest version: 1.0.6

# @onebots/adapter-zulip

onebots Zulip 适配器，基于 Zulip REST API 和 WebSocket API。

## 特性

- ✅ 流消息（Stream）和私聊消息（Private）支持
- ✅ REST API 消息发送
- ✅ WebSocket 实时事件接收
- ✅ 消息编辑和删除
- ✅ 流管理
- ✅ 用户信息获取
- ✅ 自动重连支持
- ✅ 代理配置支持

## 安装

```bash
pnpm add @onebots/adapter-zulip
```

## 配置

### 前置要求

1. **Zulip 服务器**
   - 自托管 Zulip 服务器或使用 Zulip Cloud
   - 获取服务器地址，如 `https://chat.zulip.org`

2. **获取 API Key**
   - 登录 Zulip 服务器
   - 访问 Settings → Your bots → Add a new bot
   - 创建 Bot 并获取 API Key

### 配置示例

```yaml
zulip.my_bot:
  # Zulip 服务器配置
  serverUrl: 'https://chat.zulip.org'
  email: 'bot@example.com'
  apiKey: 'your_api_key'
  
  # WebSocket 配置（可选）
  websocket:
    enabled: true  # 是否启用 WebSocket，默认 true
    reconnectInterval: 3000  # 重连间隔（毫秒），默认 3000
    maxReconnectAttempts: 10  # 最大重连次数，默认 10
  
  # 代理配置（可选）
  proxy:
    url: 'http://127.0.0.1:7890'
  
  # 协议配置
  onebot.v11:
    access_token: 'your_token'
```

## 使用示例

### 发送流消息

```javascript
// 发送到流 "general" 的话题 "test"
await bot.sendMessage('general/test', {
  scene_id: bot.createId('general/test'),
  scene_type: 'group',
  message: [
    { type: 'text', data: { text: 'Hello from Zulip!' } }
  ]
});
```

### 发送私聊消息

```javascript
// 发送给用户
await bot.sendMessage('user@example.com', {
  scene_id: bot.createId('user@example.com'),
  scene_type: 'private',
  message: [
    { type: 'text', data: { text: 'Hello!' } }
  ]
});
```

### 接收消息

适配器会自动接收 WebSocket 事件并转换为消息事件：

```javascript
bot.on('message', (event) => {
  if (event.platform === 'zulip') {
    console.log('收到 Zulip 消息:', event.sender.name, event.message);
  }
});
```

## 消息类型支持

| 消息类型 | 支持 | 说明 |
|---------|------|------|
| 文本 | ✅ | 支持 Markdown 格式 |
| 图片 | ✅ | 通过 Markdown 图片语法 |
| 文件 | ✅ | 通过 Markdown 链接语法 |

## 注意事项

1. **流消息格式**：`scene_id` 格式为 `stream_name` 或 `stream_name/topic`
2. **私聊消息格式**：`scene_id` 格式为邮箱地址或逗号分隔的邮箱列表
3. **Markdown 支持**：Zulip 支持 Markdown 格式，可以在消息中使用
4. **WebSocket 重连**：自动重连机制，可配置重连间隔和最大次数

## 相关链接

- [Zulip API 文档](https://zulip.com/api)
- [适配器配置指南](/guide/adapter)
- [Zulip 平台文档](/platform/zulip)
npm package: @onebots/core
Description: IMHelper 核心抽象层，提供适配器、协议、账号等基础接口和类型
Author: 凉菜
Latest version: 1.0.6

# @onebots/core

onebots 核心库 - 提供多平台多协议机器人应用的基础架构。

## 简介

`@onebots/core` 是 onebots 框架的核心包，提供了构建多平台多协议机器人应用所需的基础类和工具。它包含：

- **BaseApp**: 应用基类，提供核心功能
- **Adapter**: 适配器基类，用于连接不同平台
- **Protocol**: 协议基类，用于实现不同的通信协议
- **Account**: 账号管理
- **Registry**: 注册中心（适配器注册、协议注册）
- **Types**: 通用类型定义

## 特性

- 🎯 **纯库设计** - 只包含基础类和类型，不包含应用逻辑
- 📦 **模块化架构** - 清晰的模块划分，易于扩展
- 🔌 **插件系统** - 支持动态注册适配器和协议
- 🏗️ **TypeScript** - 完整的类型支持
- 🔄 **事件驱动** - 基于事件的通信机制

## 安装

```bash
npm install @onebots/core
# 或
pnpm add @onebots/core
```

## 核心概念

### BaseApp

应用基类，提供：
- 配置管理
- 适配器管理
- 账号管理
- HTTP 服务器
- 事件系统

### Adapter

适配器基类，用于：
- 连接特定平台（微信、QQ、钉钉等）
- 管理账号
- 转换平台事件为通用格式

### Protocol

协议基类，用于：
- 实现通信协议（OneBot v11/v12、Satori、Milky 等）
- 处理 API 调用
- 分发事件

### Registry

注册中心：
- `AdapterRegistry`: 管理适配器注册
- `ProtocolRegistry`: 管理协议注册

## 使用示例

```typescript
import { BaseApp, Adapter, Protocol } from '@onebots/core';

// 创建自定义适配器
class MyAdapter extends Adapter {
  async start() {
    // 实现适配器启动逻辑
  }
}

// 创建自定义协议
class MyProtocol extends Protocol {
  async apply(action: string, params: any) {
    // 实现 API 调用逻辑
  }
  
  dispatch(event: any) {
    // 实现事件分发逻辑
  }
}

// 使用基类
class MyApp extends BaseApp {
  constructor(config) {
    super(config);
  }
}
```

## API 文档

### BaseApp

```typescript
class BaseApp {
  constructor(config: BaseApp.Config);
  start(): Promise<void>;
  stop(force?: boolean): Promise<void>;
  // ... 更多方法
}
```

### Adapter

```typescript
abstract class Adapter {
  constructor(app: BaseApp, platform: string, config: any);
  abstract start(): Promise<void>;
  stop(force?: boolean): Promise<void>;
  // ... 更多方法
}
```

### Protocol

```typescript
abstract class Protocol {
  constructor(adapter: Adapter, account: Account, config: any);
  abstract apply(action: string, params?: any): Promise<any>;
  abstract dispatch(event: any): void;
  // ... 更多方法
}
```

## 类型系统

核心包提供了完整的类型定义：

```typescript
import type { 
  Dict, 
  CommonEvent, 
  CommonTypes 
} from '@onebots/core';
```

## 开发

```bash
# 构建
pnpm build

# 测试
pnpm test

# 运行测试（单次）
pnpm test:run
```

## 相关包

- [onebots](../onebots) - 主应用包
- [@onebots/adapter-wechat](../adapter-wechat) - 微信适配器
- [@onebots/protocol-onebot-v11](../protocol-onebot-v11) - OneBot V11 协议
- [@onebots/protocol-onebot-v12](../protocol-onebot-v12) - OneBot V12 协议
- [@onebots/protocol-satori-v1](../protocol-satori) - Satori 协议
- [@onebots/protocol-milky-v1](../protocol-milky-v1) - Milky V1 协议

## 许可证

MIT License - 查看 [LICENSE](../../LICENSE) 文件了解详情

## 作者

凉菜