xincbot/readme.md

A flexible QQ bot framework based on NapCat and node-napcat-ts

# xincBot

基于 NapCat 和 node-napcat-ts 开发的 QQ 机器人框架。

- 灵感来源 `kivibot` 因 `icqq` 难以登陆且内测版本未公开，故尝试使用 `NapCat` 。

## 特性

- 🔌 插件系统 - 支持动态加载/卸载插件
- 🛡️ 权限管理 - 区分主人/管理员/普通用户权限
- 🤖 AI 功能 - 支持 AI 语音等功能
- 📝 消息处理 - 支持文本/图片/表情等多种消息类型
- 👥 群管理 - 完整的群管理功能
- ⚙️ 配置灵活 - 通过 TOML 文件简单配置

## 安装

```bash
npm install xincbot -g
```

## 快速开始

### 初始化配置

```bash
xinc init
```

按照提示完成配置。

### 启动机器人

```bash
# 直接启动
xinc start

# 或者使用 npm
npm start

# 或者使用 pm2 后台运行
pm2 start xinc
```

## 插件开发

创建一个简单的插件:

```typescript
import { definePlugin } from 'xincbot';
import { Structs } from 'node-napcat-ts';

export default definePlugin({
    name: '插件名称',
    version: '1.0.0',
    desc: '插件描述',
    
    setup(ctx) {
        ctx.handle('message', async e => {
            if (ctx.getText(e) === '你好') {
                await ctx.respond(e, ['世界，你好！']);
            }
        });
    }
});
```

将插件放在 `plugins` 目录下，然后在配置文件中启用它。

## 命令列表

- `#help` - 显示帮助信息
- `#status` - 查看框架状态
- `#seting` - 查看设置
- `#set +admin @用户` - 添加管理员
- `#set -admin @用户` - 删除管理员
- `#p ls` - 查看插件列表
- `#p reload <插件名>` - 重载指定插件
- `#p off <插件名>` - 禁用指定插件
- `#p on <插件名>` - 启用指定插件
- `#exit` - 关闭框架(仅限主人)

## API 文档

### 消息处理

- `ctx.getText(e)` - 获取消息文本
- `ctx.respond(e, messages)` - 发送回复
- `ctx.recallMsg(messageId)` - 撤回消息

### 权限管理

- `ctx.isRoot(e)` - 判断是否为主人
- `ctx.isAdmin(e)` - 判断是否为管理员

### 群管理

- `ctx.mute(groupId, userId, duration)` - 禁言成员
- `ctx.setGroupCard(groupId, userId, card)` - 设置群名片

### AI 功能

- `ctx.getAiRoleList(groupId)` - 获取 AI 角色列表
- `ctx.sendGroupAiRecord(groupId, characterId, text)` - 发送 AI 语音

## 配置说明

### xinc.config.toml

- `host` - 机器人服务器地址
- `port` - 服务器端口
- `prefix` - 命令前缀
- `root` - 主人 QQ 号列表
- `admin` - 管理员 QQ 号列表
- `plugins` - 启用的插件列表

## 许可证

[GPL-3.0](LICENSE)

## 贡献指南

1. Fork 本仓库
2. 创建新分支: `git checkout -b feature/xxxx`
3. 提交更改: `git commit -am 'feat: add xxxx'`
4. 推送分支: `git push origin feature/xxxx`
5. 提交 Pull Request

## 问题反馈

如有问题，请在 [Issues](https://github.com/wwcxin/jiuyue/issues) 中提出。

## 致谢

- [NapCat](https://github.com/NapNeko/NapCatQQ)
- [node-napcat-ts](https://github.com/huankong-team/node-napcat-ts)