qqbot-elysia 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sibuxiangx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+<p align="center">
+  <h1 align="center">🦊 qqbot-elysia</h1>
+  <p align="center">
+    <strong>基于 Bun + Elysia 的 QQ 开放平台 Bot SDK</strong>
+  </p>
+  <p align="center">
+    装饰器路由 · 依赖注入 · 模块化开发
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://github.com/Sibuxiangx/qqbot-elysia/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
+  <a href="https://www.npmjs.com/package/qqbot-elysia"><img src="https://img.shields.io/npm/v/qqbot-elysia.svg" alt="npm version" /></a>
+  <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun" /></a>
+</p>
+
+---
+
+## ✨ 特性
+
+- **🚀 极速** — 基于 [Bun](https://bun.sh) 运行时 + [Elysia](https://elysiajs.com) Web 框架
+- **🎨 装饰器路由** — 用 `@OnCommand("ping")` 声明式地注册消息处理器
+- **💉 依赖注入** — 在处理器参数中直接声明你需要的数据（`Content`, `AttachmentList`, `AuthorInfo`…）
+- **📦 模块化** — 继承 `BotModule` 即可创建可插拔的功能模块
+- **🔐 Webhook** — 原生支持 QQ 开放平台 Webhook 验签（Ed25519）
+- **🌐 多场景** — 群聊、私聊 (C2C)、频道、频道私信全覆盖
+- **📋 日志** — 内置漂亮的结构化日志输出
+
+## 📦 安装
+
+```bash
+bun add qqbot-elysia
+```
+
+> **前置要求**: [Bun](https://bun.sh) >= 1.0, TypeScript >= 5
+
+## 🚀 快速开始
+
+```typescript
+import { Bot, BotModule, OnCommand, Content } from "qqbot-elysia";
+import type { MessageContext } from "qqbot-elysia";
+
+class PingModule extends BotModule {
+  @OnCommand("ping")
+  async onPing(ctx: MessageContext) {
+    await ctx.reply("pong! 🏓");
+  }
+
+  @OnCommand("echo")
+  async onEcho(ctx: MessageContext, content: Content) {
+    await ctx.reply(content || "你没有输入任何内容");
+  }
+}
+
+const bot = new Bot({
+  appId: process.env.APP_ID!,
+  clientSecret: process.env.CLIENT_SECRET!,
+  port: 2099,
+  isSandbox: true,
+  debug: true,
+});
+
+await bot.use(new PingModule());
+await bot.start();
+```
+
+## 📖 核心概念
+
+### 模块 (Module)
+
+所有功能都封装在 `BotModule` 子类中：
+
+```typescript
+class MyModule extends BotModule {
+  override async onLoad() {
+    // 模块加载时触发
+  }
+
+  override async onUnload() {
+    // 模块卸载时触发
+  }
+}
+```
+
+### 装饰器 (Decorators)
+
+| 装饰器 | 说明 |
+| :--- | :--- |
+| `@OnCommand("cmd")` | 匹配指定命令（群 + 私聊） |
+| `@OnPrefix("前缀")` | 匹配消息前缀 |
+| `@OnSuffix("后缀")` | 匹配消息后缀 |
+| `@OnKeyword("关键词")` | 匹配消息关键词 |
+| `@OnGroup` | 仅匹配群消息 |
+| `@OnC2C` | 仅匹配私聊消息 |
+| `@OnChannel` | 仅匹配频道消息 |
+| `@OnDirect` | 仅匹配频道私信 |
+| `@OnEvent(EventType.xxx)` | 匹配指定事件类型 |
+
+装饰器可以**组合使用**：
+
+```typescript
+@OnGroup                    // 仅群聊
+@OnCommand("admin-only")    // 匹配 "admin-only" 命令
+async onAdminCmd(ctx: GroupMessageContext) {
+  await ctx.reply("仅群聊可用的管理命令");
+}
+```
+
+### 依赖注入 (DI)
+
+处理器参数会根据类型标记自动注入对应的数据：
+
+| 类型 | 说明 | 备注 |
+| :--- | :--- | :--- |
+| `Content` | 匹配后的消息内容 | 去除了触发词后的剩余文本 |
+| `RawContent` | 原始完整消息内容 | 用户输入的全部文本 |
+| `AttachmentList` | 附件列表 | 若无附件则**跳过执行** |
+| `AuthorInfo` | 发送者信息 | 包含 openid、用户名等 |
+| `GroupInfo` | 群信息 | 仅群聊有效 |
+| `MemberInfo` | 群成员信息 | 仅群聊有效 |
+
+```typescript
+import { Content, AttachmentList, AuthorInfo } from "qqbot-elysia";
+
+@OnCommand("save-image")
+async onSaveImage(ctx: MessageContext, attachments: AttachmentList) {
+  // attachments 保证不为空
+  // 若消息无附件，本处理器会被自动跳过
+  await ctx.reply(`收到 ${attachments.length} 张图片！`);
+}
+```
+
+> **⚠️ 重要**：DI 标记类（`Content`, `AttachmentList` 等）必须用普通 `import` 导入，**不要**使用 `import type`，否则运行时元数据会丢失。
+
+#### 自定义注入器
+
+你可以注册自己的注入器来扩展系统：
+
+```typescript
+// 定义标记类
+class Database {}
+
+// 注册注入逻辑
+bot.registerInjector("Database", (ctx) => myDatabaseInstance);
+
+// 在处理器中使用
+@OnCommand("db-test")
+async test(ctx: MessageContext, db: Database) {
+  // db === myDatabaseInstance
+}
+```
+
+### 消息发送
+
+```typescript
+// 纯文本
+await ctx.reply("Hello!");
+
+// 图片
+await ctx.reply("看看这张图", {
+  image: "https://example.com/image.png",
+});
+
+// Markdown (模板)
+await ctx.reply("", {
+  markdown: {
+    custom_template_id: "your_template_id",
+    params: [{ key: "title", values: ["Hello"] }],
+  },
+});
+
+// 主动消息
+await bot.sendGroupMessage(groupOpenid, "主动推送消息");
+await bot.sendC2CMessage(userOpenid, "主动私聊消息");
+```
+
+### 事件监听
+
+```typescript
+import { OnEvent, EventType } from "qqbot-elysia";
+
+@OnEvent(EventType.GROUP_ADD_ROBOT)
+async onBotAdded(ctx: GroupRobotEventContext) {
+  console.log(`Bot 被添加到群: ${ctx.groupOpenid}`);
+}
+
+@OnEvent(EventType.FRIEND_ADD)
+async onFriendAdd(ctx: FriendEventContext) {
+  console.log(`新好友: ${ctx.userOpenid}`);
+}
+```
+
+## 🔧 配置
+
+```typescript
+const bot = new Bot({
+  appId: "你的 AppID",
+  clientSecret: "你的 ClientSecret",
+  port: 2099,              // Webhook 监听端口 (默认 2099)
+  host: "0.0.0.0",         // 监听地址 (默认 0.0.0.0)
+  postEventPath: "/postevent", // Webhook 路径
+  isSandbox: false,        // 沙箱模式
+  randomMsgSeq: true,      // 随机 msg_seq
+  debug: false,            // 调试日志
+});
+```
+
+## 📁 项目结构
+
+```
+qqbot-elysia/
+├── src/
+│   ├── index.ts          # 统一导出
+│   ├── bot.ts            # Bot 核心类
+│   ├── module.ts         # BotModule 基类
+│   ├── decorators.ts     # 装饰器定义
+│   ├── matchers.ts       # 消息匹配器
+│   ├── events.ts         # 事件系统
+│   ├── api.ts            # QQ OpenAPI 客户端
+│   ├── auth.ts           # Token 管理
+│   ├── sign.ts           # Ed25519 验签
+│   ├── logger.ts         # 日志系统
+│   ├── di/
+│   │   ├── markers.ts    # DI 标记类
+│   │   └── registry.ts   # 注入器注册表
+│   └── types/
+│       └── types.ts      # TypeScript 类型定义
+├── docs/
+│   └── di.md             # DI 系统详细文档
+├── package.json
+├── tsconfig.json
+├── LICENSE
+└── README.md
+```
+
+## 📝 TypeScript 配置
+
+你的 `tsconfig.json` **必须**包含以下设置：
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+## 📄 License
+
+[MIT](LICENSE) © Sibuxiangx

package/docs/di.md

@@ -0,0 +1,69 @@
+# 依赖注入 (DI) 系统指南
+
+本 SDK 提供了一套基于装饰器和 `reflect-metadata` 的依赖注入系统，允许你在事件处理器中声明式地获取参数。
+
+## 1. 核心概念
+
+在模块化的处理器中，你可以直接通过参数类型声明来注入你需要的对象，而不需要从完整的 `ctx` 中手动提取。
+
+```typescript
+@OnCommand("echo")
+async onEcho(ctx: MessageContext, content: Content) {
+    // content 会被自动注入为匹配后的文本内容
+    await ctx.reply(content);
+}
+```
+
+## 2. 内置注入类型
+
+你可以从 `@src` (或项目根目录的 `./src`) 导入以下标记类：
+
+| 类型 | 说明 | 注入内容 | 备注 |
+| :--- | :--- | :--- | :--- |
+| `Content` | 匹配后的内容 | `string` (包装类) | 去除了触发指令/前缀后的剩余文本 |
+| `RawContent` | 原始完整内容 | `string` (包装类) | 原始用户输入的完整字符串 |
+| `AttachmentList` | 消息附件列表 | `Attachment[]` | 若消息中无附件，且参数非可选，将**跳过**逻辑执行 |
+| `AuthorInfo` | 发送者信息 | `Author` | 包含 `username`, `avatar`, `openid` 等 |
+| `GroupInfo` | 群信息 | `GroupInfo` | 仅在群聊事件中有效 |
+| `MemberInfo` | 群成员信息 | `GroupMember` | 仅在群聊事件中有效 (openid) |
+| `MessageContext` | 原始上下文 | `Context` 对象 | 完整的事件上下文 |
+
+## 3. 运行逻辑与 "Skip Logic"
+
+- **参数顺序**：注入器会扫描你的方法签名，根据参数的类型 (Type) 进行匹配，顺序不限。
+- **Skip Logic (跳过逻辑)**：对于部分类型 (如 `AttachmentList`)，如果当前事件中不包含这些数据，SDK 会认为该处理器不满足执行条件，**自动跳过**该处理器的调用。这可以让你免去 `if (!ctx.attachments) return` 之类的样板代码。
+
+## 4. 自定义注入器
+
+你可以通过 `bot.registerInjector` 扩展系统，注入自己的服务或对象：
+
+### 示例：注入数据库连接
+
+1. **定义标识类 (Markers)**:
+```typescript
+class Database { } // 仅作为标识，不需要实现
+```
+
+2. **注册注入器**:
+```typescript
+bot.registerInjector("Database", (ctx) => {
+    return myDbInstance; // 返回你想注入的实际对象
+});
+```
+
+3. **在处理器中使用**:
+```typescript
+class MyModule extends BotModule {
+    @OnCommand("db-test")
+    async test(ctx: MessageContext, db: Database) {
+        // db 将会是 myDbInstance
+        const data = await db.query(...);
+        await ctx.reply("查询成功");
+    }
+}
+```
+
+## 5. 提示
+
+- 确保你的 `tsconfig.json` 开启了 `emitDecoratorMetadata` 和 `experimentalDecorators`。
+- 自定义注入时的名称字符串必须与你在参数中声明的**类名**完全一致。

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "qqbot-elysia",
+  "version": "0.1.0",
+  "description": "⚡ 基于 Bun + Elysia 的 QQ 开放平台 Bot SDK，支持装饰器路由、依赖注入与模块化开发",
+  "type": "module",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "docs",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "bun run index.ts",
+    "check": "bun x tsc --noEmit"
+  },
+  "keywords": [
+    "qq",
+    "qqbot",
+    "qq-bot",
+    "bot",
+    "elysia",
+    "bun",
+    "sdk",
+    "webhook",
+    "decorator",
+    "dependency-injection"
+  ],
+  "author": "Sibuxiangx",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sibuxiangx/qqbot-elysia.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Sibuxiangx/qqbot-elysia/issues"
+  },
+  "homepage": "https://github.com/Sibuxiangx/qqbot-elysia#readme",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^3.0.0",
+    "elysia": "^1.4.25",
+    "log4js": "^6.9.1",
+    "reflect-metadata": "^0.2.2"
+  }
+}