# opencode-qqbot

**Repository Path**: nczyhcy/opencode-qqbot

## Basic Information

- **Project Name**: opencode-qqbot
- **Description**: OpenCode QQ 机器人插件，通过 QQ 与 AI 编程助手对话。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-20
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenCode QQ 插件

> 本项目使用 [OpenCode](https://opencode.ai) 开发

通过 QQ 机器人与 OpenCode AI 编程助手对话。

## 功能特性

- **QQ 群聊 + 私聊** - @机器人 或直接私信，两种方式都支持
- **会话管理** - 每用户独立会话，支持新建、切换、重命名
- **模型切换** - 随时切换 AI 模型和 Agent 模式
- **命令系统** - 10 个内置命令覆盖常用操作
- **自动启动** - 配合 OpenCode 桌面版自动启动

## 安装

### 前置条件

1. OpenCode 桌面版
2. QQ 开放平台开发者账号（创建机器人获取 AppID 和 AppSecret）

### 一键安装

**Windows (PowerShell)**
```powershell
irm https://gitee.com/nczyhcy/opencode-qqbot/raw/master/install.ps1 | iex
```

**Windows (CMD)**
```cmd
curl -L -o install.ps1 https://gitee.com/nczyhcy/opencode-qqbot/raw/master/install.ps1 && powershell -ExecutionPolicy Bypass -File install.ps1
```

**Linux / Mac**
```bash
curl -sL https://gitee.com/nczyhcy/opencode-qqbot/raw/master/install.sh -o install.sh && bash install.sh
```

### 方式 1：放置到全局插件目录

将项目复制到 OpenCode 全局插件目录：

```
~/.config/opencode/plugins/opencode-qqbot/
```

确保目录结构如下：

```
~/.config/opencode/plugins/opencode-qqbot/
├── src/
│   ├── index.ts
│   ├── bridge.ts
│   ├── commands.ts
│   ├── config.ts
│   ├── qq/
│   │   ├── api.ts
│   │   ├── gateway.ts
│   │   ├── sender.ts
│   │   └── types.ts
│   └── opencode/
│       └── client.ts
├── package.json
└── tsconfig.json
```

### 方式 2：放置到项目插件目录

```
.your-project/
├── .opencode/
│   └── plugins/
│       └── opencode-qqbot/
```

## 配置

### 1. 创建 QQ 机器人

1. 前往 [QQ 开放平台](https://q.qq.com) 注册/登录
2. 创建机器人，获取 `AppID` 和 `AppSecret`
3. 在沙箱配置中添加测试成员

### 2. 配置本插件

在一键安装后，创建 `.openqq/config.json`：

```json
{
  "qq": {
    "appId": "你的AppID",
    "appSecret": "你的AppSecret",
    "sandbox": true
  },
  "opencode": {
    "baseUrl": "http://localhost:4096"
  },
  "allowedUsers": [],
  "maxReplyLength": 3000
}
```

- `appId`: QQ 机器人 AppID
- `appSecret`: QQ 机器人 AppSecret
- `sandbox`: 是否使用沙箱环境（开发时设为 true）
- `allowedUsers`: 可选，允许使用机器人的 QQ 号数组
- `maxReplyLength`: 单条回复最大字符数

### 3. 配置 OpenCode 桌面版

打开 OpenCode 桌面版，它会自动启动 opencode serve（默认端口 4096）。

## 使用方法

### 启动

1. 确保配置好 QQ 机器人的 AppID 和 AppSecret
2. 打开 OpenCode 桌面版
3. 插件会自动连接 QQ 机器人

### QQ 命令

| 命令 | 功能 |
|------|------|
| `/new [名称]` | 创建新会话 |
| `/stop` | 停止当前 AI 运行 |
| `/status` | 查看服务器状态 |
| `/sessions` | 列出所有会话 |
| `/help` | 查看帮助信息 |
| `/model` | 列出可用模型 |
| `/model <模型>` | 切换模型 |
| `/rename <名称>` | 重命名当前会话 |

### 在群聊中使用

```
@机器人 /sessions   // 查看会话列表
@机器人 /new      // 创建新会话
@机器人 你好      // 发送对话
```

### 在私聊中直接使用

```
/sessions
/new
你好
```

## 项目结构

```
opencode-qqbot/
├── src/
│   ├── index.ts           # 插件入口
│   ├── bridge.ts         # 核心桥接
│   ├── commands.ts      # 命令系统
│   ├── config.ts       # 配置加载
│   ├── qq/
│   │   ├── api.ts      # QQ REST API
│   │   ├── gateway.ts # WebSocket 网关
│   │   ├── sender.ts  # 消息发送
│   │   └── types.ts   # 类型定义
│   └── opencode/
│       └── client.ts   # OpenCode 客户端
├── .openqq/
│   └── config.example.json
├── package.json
├── tsconfig.json
└── README.md
```

## 注意事项

1. 开发阶段 `sandbox` 设为 `true`，正式发布后改为 `false`
2. 确保 OpenCode 桌面版正常运行
3. 首次使用需要将机器人添加为好友或拉入群聊

## 许可证

MIT