pi-qq-integration

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# pi-qq-integration — pi 扩展

在 **QQ 中操控 pi**。安装此扩展后，pi 启动时会自动加载扩展并**默认自动连接** QQ Bot（可在配置中关闭）。连接后即可通过 QQ 向 pi 发消息、查看 session 列表、浏览历史对话；也可随时用 `/qq-connect`、`/qq-disconnect` 手动控制连接。

## 安装

```bash
pi install npm:pi-qq-integration
```

---

## 快速开始

### 1. 注册 QQ Bot

在 [QQ 开放平台](https://q.qq.com) 创建一个机器人应用，获取 **AppID** 和 **AppSecret**。

### 2. 创建配置文件

```json
# /home/nullsky/.pi/agent/qq-integration-config.json
{
  "appId": "你的 AppID",
  "appSecret": "你的 AppSecret"
}
```

### 3. 启动 pi

```bash
pi
```

扩展加载后会**自动连接** QQ Bot（默认行为）。如需关闭自动连接，在配置文件加 `"autoConnect": false` 后重启 pi，再用 `/qq-connect` 手动连接；断开用 `/qq-disconnect`。

现在在 QQ 中给机器人发消息，就能和 pi 对话了。

---

## 配置项（qq-integration-config.json）

配置文件路径：`/home/nullsky/.pi/agent/qq-integration-config.json`（位于 pi 的 agent 数据目录，与扩展代码目录无关）。以下**所有**可配置项均在此文件中：

### 顶层字段

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `appId` | string | ✅ | — | QQ 开放平台机器人应用的 AppID |
| `appSecret` | string | ✅ | — | QQ 开放平台机器人应用的 AppSecret（**敏感，勿提交 git**） |
| `instanceId` | string | ❌ | `hostname-pid` | 多实例下本实例的唯一 ID，用于注册表区分各实例 |
| `role` | `"auto" \| "leader" \| "follower"` | ❌ | `"auto"` | 多实例角色：`auto` 由文件锁自动选举；`leader` 强制本实例持有 QQ 连接；`follower` 强制本实例经 IPC 接入其他 leader |
| `autoConnect` | boolean | ❌ | `true` | pi 启动时是否自动连接 QQ Bot；设为 `false` 则需手动 `/qq-connect` |

### `settings` 字段（转发设置）

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `forwardDesktopMessages` | boolean | `false` | 桌面端（pi 终端）输入的消息是否转发到 QQ |
| `forwardToolCalls` | boolean | `false` | 工具调用是否转发到 QQ（与 `lastMessageOnly` 互斥，开启其一会关闭另一个） |
| `lastMessageOnly` | boolean | `false` | 只转发整次 agent 运行的**最后一条** assistant 回复（而非每条逐步回复）；与 `forwardToolCalls` 互斥 |
| `defaultSession` | object \| undefined | `undefined` | 默认 QQ 转发目标（QBSession），桌面端/工具转发未明确来源会话时使用；由 `/qq-target` 或 QQ 内 `#target` 写入 |

> `settings` 内的字段既可在配置文件里静态写死，也可在 QQ 内用 `#settings` 命令动态调整并持久化（见下文「QQ 命令」）。注意 `#settings` 命令对前两个开关使用了简写别名：`forwardMessages` 对应配置键 `forwardDesktopMessages`，`forwardTools` 对应 `forwardToolCalls`。

### 完整示例

```json
{
  "appId": "你的 AppID",
  "appSecret": "你的 AppSecret",
  "autoConnect": true,
  "role": "auto",
  "settings": {
    "forwardDesktopMessages": false,
    "forwardToolCalls": false,
    "lastMessageOnly": false
  }
}
```

### 多实例

同时运行多个 pi 实例时，用文件锁选举唯一的 leader 持有 QQ 连接；其余实例作为 follower 经本地 Unix socket 把 QQ 收发委托给 leader。`autoConnect` 对**所有**实例生效——启动即各自参与选举，最终只有抢到锁的 leader 真正连接 QQ，其余 follower 经 IPC 接入，不会冲突。相关配置：

- `role: "auto"`（默认）：谁先抢到锁谁是 leader，其余自动成为 follower。
- `role: "leader"` / `"follower"`：强制角色（例如固定某台机器做 leader）。
- `instanceId`：一般无需修改；仅在需要固定 ID（如日志/注册表排查）时设置。

---

## 架构

```
QQ 用户
  │
  ├─ 发消息 → QQ Bot 服务器 → WebSocket
  │                                │
  │                     ┌──────────▼──────────┐
  │                     │  pi-qq-integration 扩展  │
  │                     │                      │
  │                     │  ws-client.ts        │
  │                     │    ↕ WebSocket       │
  │                     │  command-handler.ts  │
  │                     │    ↕ /cmd 解析       │
  │                     │  index.ts            │
  │                     │    ↕ sendUserMessage │
  │                     └──────────┬──────────┘
  │                                │
  │                     ┌──────────▼──────────┐
  │                     │      pi 引擎         │
  │                     │   处理 prompt 并回复  │
  │                     └──────────┬──────────┘
  │                                │
  └─────── REST API ←──── 回复内容
```

两个独立通道：
- **WebSocket** — 接收 QQ 消息（长连接，带心跳和断线重连）
- **REST API** — 发送回复到 QQ（`POST /v2/users/{openid}/messages`）

---

## pi Slash 命令

在 pi 终端中使用的命令：

| 命令 | 说明 |
|------|------|
| `/qq-connect` | 手动连接 QQ Bot |
| `/qq-disconnect` | 断开 QQ Bot 连接 |
| `/qq-status` | 查看连接状态概览（锁、WebSocket、Token） |
| `/qq-diagnose` | 查看详细诊断信息（session_id、心跳、重连次数等） |
| `/qq-logs` | 查看最近 30 条日志 |
| `/qq-logs-path` | 查看日志文件路径 |
| `/qq-target` | 设置/查看默认 QQ 转发目标 |

### `/qq-status` 示例

```
🔒 锁: 持有中
🟢 WebSocket: 已连接
⏱ 已运行: 2分35秒
✅ Token: 有效
```

### `/qq-diagnose` 示例

```
🔒 锁状态
  - 持有锁: ✅ 是
  - 锁文件 PID: 12345
  - 本进程 PID: 12345

🌐 WebSocket 连接
  - 状态: 已连接
  - Session ID: xxxx
  - 重连次数: 0

🔑 Access Token
  - 过期时间: 2026-07-21 17:30
  - 剩余时间: 1时58分

⚙️ 配置
  - AppID: 你的 AppID
```

---

## QQ 命令

在 QQ 中给机器人发送的消息，如果不以 `/` 开头，会直接作为 prompt 发给 pi。

| 命令 | 说明 |
|------|------|
| `#help` | 显示帮助 |
| `#sessions` | 列出所有 pi session |
| `#resume <序号/名称>` | 切换到指定 session（在终端中操作） |
| `#new` | 创建新 session（在终端中操作） |
| `#history [N]` | 查看当前 session 最近 N 条消息（默认 5） |
| `#clear` | 清空当前 session（在终端中操作） |
| `#target` | 将当前 QQ 会话设为默认转发目标 |
| `#settings lastMessageOnly on|off` | 只转发整次回复的最后一条 assistant 回复 |

### 示例

```
你: #sessions
Bot: 📋 Pi Sessions
     1. **extensions 07:03** — 2小时前
     2. **learn 05:29** — 2小时前
     ...

你: #history 5
Bot: 📝 最近消息 (extensions 07:03)
     👤 今天天气怎么样？
     🤖 今天天气晴朗...
```

### 桌面端消息转发

开启桌面端转发（`#settings forwardMessages on`）后，桌面端输入的消息会同步转发到 QQ。扩展需要知道“发到哪个 QQ 会话”，目标按以下优先级选择：

1. 最近一条 QQ 消息来源的会话
2. 手动设置的默认目标（`/qq-target` 或 QQ 里的 `#target`）

因此，如果你**先**在桌面端发消息、**后**才收到 QQ 消息，需要预先指定默认目标：

```bash
# 在 pi 终端设置默认目标（以私聊为例）
/qq-target c2c <用户openid>

# 或设置群聊
/qq-target group <群openid>

# 查看当前默认目标
/qq-target

# 清除
/qq-target clear
```

也可以在 QQ 里发送 `#target`，把当前会话设为默认目标。

### `#settings`

转发设置在 `/reload` 后永久保存：

```
你: #settings
Bot: ⚙️ QQ Bot 设置
     | 选项 | 状态 | 说明 |
     | forwardMessages | ❌ 关 | 桌面端消息转发到 QQ |
     | forwardTools | ✅ 开 | 工具调用转发到 QQ |
     | lastMessageOnly | ❌ 关 | 只转发整次回复的最后一条 assistant 回复 |

你: #settings forwardTools on
Bot: ✅ 工具调用转发已开启

你: #settings forwardMessages off
Bot: ❌ 桌面消息转发已关闭

你: #settings lastMessageOnly on
Bot: ✅ 只转发最后一条回复已开启，assistant 整次运行仅发送一条最终回复；forwardTools 已自动关闭。
```

---

## 文件结构

```
pi-qq-integration/
├── index.ts              # 入口：初始化、事件注册、slash 命令
├── config.ts             # 读取 qq-integration-config.json
├── auth.ts               # QQ Bot Access Token 获取 + 自动刷新
├── lock.ts               # 文件锁（多实例防冲突）
├── ws-client.ts          # WebSocket 客户端（连接、鉴权、心跳、重连）
├── api-client.ts         # REST API 客户端（发送消息）
├── session-manager.ts    # Pi session 浏览
├── command-handler.ts    # QQ 消息中的 /cmd 命令解析
├── types.ts              # 类型定义
├── package.json          # 依赖（ws）
└── README.md
```

---

## 多实例处理

如果同时启动多个 pi 实例，扩展使用**文件锁**机制确保只有一个实例连接 QQ Bot：

```
~/.pi/agent/qq-integration.lock
  ├── PID: 持有者进程 ID
  ├── 获取时间
  └── 心跳时间（每 30 秒更新）
```

- 第一个启动的 pi 获取锁并连接 Bot
- 后续实例检测到锁被持有，跳过连接
- 持有锁的实例崩溃后，锁文件中的 PID 失效，后续实例自动接管

---

## 日志

所有调试日志写入文件：

```
/home/nullsky/.pi/agent/qq-integration.log
```

在 pi 中可用 `/qq-logs` 查看最近 30 条，用 `/qq-logs-path` 查看文件路径。
日志文件达到 5MB 会自动截断。

## 注意事项

1. **Token 安全** — `access_token` 有效期 2 小时，扩展会自动提前刷新
2. **消息频率** — QQ Bot 主动消息每月每用户/群限 4 条，被动回复较宽松
3. **Session 管理** — session 切换（`/new`、`/resume`）需在 pi 终端中操作
4. **`#settings` 持久化** — 设置保存在 `qq-integration-config.json` 中，`/reload` 不丢失
4. **群聊消息** — 仅接收 @机器人的群消息（`GROUP_AT_MESSAGE_CREATE`）
5. **配置文件** — 含 AppSecret，注意不要提交到 git

---

## 开发

```bash
cd ~/.pi/agent/extensions/qq-integration
npm install          # 安装依赖
# 编辑代码后 /reload 即可热重载
```

pi-qq-integration — pi 扩展

在 QQ 中操控 pi。安装此扩展后，pi 启动时会自动加载扩展并默认自动连接 QQ Bot（可在配置中关闭）。连接后即可通过 QQ 向 pi 发消息、查看 session 列表、浏览历史对话；也可随时用 /qq-connect、/qq-disconnect 手动控制连接。

安装

pi install npm:pi-qq-integration

快速开始

1. 注册 QQ Bot

在 QQ 开放平台创建一个机器人应用，获取 AppID 和 AppSecret。

2. 创建配置文件

# /home/nullsky/.pi/agent/qq-integration-config.json
{
  "appId": "你的 AppID",
  "appSecret": "你的 AppSecret"
}

3. 启动 pi

pi

扩展加载后会自动连接 QQ Bot（默认行为）。如需关闭自动连接，在配置文件加 "autoConnect": false 后重启 pi，再用 /qq-connect 手动连接；断开用 /qq-disconnect。

现在在 QQ 中给机器人发消息，就能和 pi 对话了。

配置项（qq-integration-config.json）

配置文件路径：/home/nullsky/.pi/agent/qq-integration-config.json（位于 pi 的 agent 数据目录，与扩展代码目录无关）。以下所有可配置项均在此文件中：

顶层字段

字段	类型	必填	默认值	说明
`appId`	string	✅	—	QQ 开放平台机器人应用的 AppID
`appSecret`	string	✅	—	QQ 开放平台机器人应用的 AppSecret（敏感，勿提交 git）
`instanceId`	string	❌	`hostname-pid`	多实例下本实例的唯一 ID，用于注册表区分各实例
`role`	`"auto" \| "leader" \| "follower"`	❌	`"auto"`	多实例角色：`auto` 由文件锁自动选举；`leader` 强制本实例持有 QQ 连接；`follower` 强制本实例经 IPC 接入其他 leader
`autoConnect`	boolean	❌	`true`	pi 启动时是否自动连接 QQ Bot；设为 `false` 则需手动 `/qq-connect`

`settings` 字段（转发设置）

字段	类型	默认值	说明
`forwardDesktopMessages`	boolean	`false`	桌面端（pi 终端）输入的消息是否转发到 QQ
`forwardToolCalls`	boolean	`false`	工具调用是否转发到 QQ（与 `lastMessageOnly` 互斥，开启其一会关闭另一个）
`lastMessageOnly`	boolean	`false`	只转发整次 agent 运行的最后一条 assistant 回复（而非每条逐步回复）；与 `forwardToolCalls` 互斥
`defaultSession`	object \| undefined	`undefined`	默认 QQ 转发目标（QBSession），桌面端/工具转发未明确来源会话时使用；由 `/qq-target` 或 QQ 内 `#target` 写入

settings 内的字段既可在配置文件里静态写死，也可在 QQ 内用 #settings 命令动态调整并持久化（见下文「QQ 命令」）。注意 #settings 命令对前两个开关使用了简写别名：forwardMessages 对应配置键 forwardDesktopMessages，forwardTools 对应 forwardToolCalls。

完整示例

{
  "appId": "你的 AppID",
  "appSecret": "你的 AppSecret",
  "autoConnect": true,
  "role": "auto",
  "settings": {
    "forwardDesktopMessages": false,
    "forwardToolCalls": false,
    "lastMessageOnly": false
  }
}

多实例

同时运行多个 pi 实例时，用文件锁选举唯一的 leader 持有 QQ 连接；其余实例作为 follower 经本地 Unix socket 把 QQ 收发委托给 leader。autoConnect 对所有实例生效——启动即各自参与选举，最终只有抢到锁的 leader 真正连接 QQ，其余 follower 经 IPC 接入，不会冲突。相关配置：

role: "auto"（默认）：谁先抢到锁谁是 leader，其余自动成为 follower。
role: "leader" / "follower"：强制角色（例如固定某台机器做 leader）。
instanceId：一般无需修改；仅在需要固定 ID（如日志/注册表排查）时设置。

架构

QQ 用户
  │
  ├─ 发消息 → QQ Bot 服务器 → WebSocket
  │                                │
  │                     ┌──────────▼──────────┐
  │                     │  pi-qq-integration 扩展  │
  │                     │                      │
  │                     │  ws-client.ts        │
  │                     │    ↕ WebSocket       │
  │                     │  command-handler.ts  │
  │                     │    ↕ /cmd 解析       │
  │                     │  index.ts            │
  │                     │    ↕ sendUserMessage │
  │                     └──────────┬──────────┘
  │                                │
  │                     ┌──────────▼──────────┐
  │                     │      pi 引擎         │
  │                     │   处理 prompt 并回复  │
  │                     └──────────┬──────────┘
  │                                │
  └─────── REST API ←──── 回复内容

两个独立通道：

WebSocket — 接收 QQ 消息（长连接，带心跳和断线重连）
REST API — 发送回复到 QQ（POST /v2/users/{openid}/messages）

pi Slash 命令

在 pi 终端中使用的命令：

命令	说明
`/qq-connect`	手动连接 QQ Bot
`/qq-disconnect`	断开 QQ Bot 连接
`/qq-status`	查看连接状态概览（锁、WebSocket、Token）
`/qq-diagnose`	查看详细诊断信息（session_id、心跳、重连次数等）
`/qq-logs`	查看最近 30 条日志
`/qq-logs-path`	查看日志文件路径
`/qq-target`	设置/查看默认 QQ 转发目标

`/qq-status` 示例

🔒 锁: 持有中
🟢 WebSocket: 已连接
⏱ 已运行: 2分35秒
✅ Token: 有效

`/qq-diagnose` 示例

🔒 锁状态
  - 持有锁: ✅ 是
  - 锁文件 PID: 12345
  - 本进程 PID: 12345

🌐 WebSocket 连接
  - 状态: 已连接
  - Session ID: xxxx
  - 重连次数: 0

🔑 Access Token
  - 过期时间: 2026-07-21 17:30
  - 剩余时间: 1时58分

⚙️ 配置
  - AppID: 你的 AppID

QQ 命令

在 QQ 中给机器人发送的消息，如果不以 / 开头，会直接作为 prompt 发给 pi。

命令	说明
`#help`	显示帮助
`#sessions`	列出所有 pi session
`#resume <序号/名称>`	切换到指定 session（在终端中操作）
`#new`	创建新 session（在终端中操作）
`#history [N]`	查看当前 session 最近 N 条消息（默认 5）
`#clear`	清空当前 session（在终端中操作）
`#target`	将当前 QQ 会话设为默认转发目标
`#settings lastMessageOnly on	off`

示例

你: #sessions
Bot: 📋 Pi Sessions
     1. **extensions 07:03** — 2小时前
     2. **learn 05:29** — 2小时前
     ...

你: #history 5
Bot: 📝 最近消息 (extensions 07:03)
     👤 今天天气怎么样？
     🤖 今天天气晴朗...

桌面端消息转发

开启桌面端转发（#settings forwardMessages on）后，桌面端输入的消息会同步转发到 QQ。扩展需要知道“发到哪个 QQ 会话”，目标按以下优先级选择：

最近一条 QQ 消息来源的会话
手动设置的默认目标（/qq-target 或 QQ 里的 #target）

因此，如果你先在桌面端发消息、后才收到 QQ 消息，需要预先指定默认目标：

# 在 pi 终端设置默认目标（以私聊为例）
/qq-target c2c <用户openid>

# 或设置群聊
/qq-target group <群openid>

# 查看当前默认目标
/qq-target

# 清除
/qq-target clear

也可以在 QQ 里发送 #target，把当前会话设为默认目标。

`#settings`

转发设置在 /reload 后永久保存：

你: #settings
Bot: ⚙️ QQ Bot 设置
     | 选项 | 状态 | 说明 |
     | forwardMessages | ❌ 关 | 桌面端消息转发到 QQ |
     | forwardTools | ✅ 开 | 工具调用转发到 QQ |
     | lastMessageOnly | ❌ 关 | 只转发整次回复的最后一条 assistant 回复 |

你: #settings forwardTools on
Bot: ✅ 工具调用转发已开启

你: #settings forwardMessages off
Bot: ❌ 桌面消息转发已关闭

你: #settings lastMessageOnly on
Bot: ✅ 只转发最后一条回复已开启，assistant 整次运行仅发送一条最终回复；forwardTools 已自动关闭。

文件结构

pi-qq-integration/
├── index.ts              # 入口：初始化、事件注册、slash 命令
├── config.ts             # 读取 qq-integration-config.json
├── auth.ts               # QQ Bot Access Token 获取 + 自动刷新
├── lock.ts               # 文件锁（多实例防冲突）
├── ws-client.ts          # WebSocket 客户端（连接、鉴权、心跳、重连）
├── api-client.ts         # REST API 客户端（发送消息）
├── session-manager.ts    # Pi session 浏览
├── command-handler.ts    # QQ 消息中的 /cmd 命令解析
├── types.ts              # 类型定义
├── package.json          # 依赖（ws）
└── README.md

多实例处理

如果同时启动多个 pi 实例，扩展使用文件锁机制确保只有一个实例连接 QQ Bot：

~/.pi/agent/qq-integration.lock
  ├── PID: 持有者进程 ID
  ├── 获取时间
  └── 心跳时间（每 30 秒更新）

第一个启动的 pi 获取锁并连接 Bot
后续实例检测到锁被持有，跳过连接
持有锁的实例崩溃后，锁文件中的 PID 失效，后续实例自动接管

日志

所有调试日志写入文件：

/home/nullsky/.pi/agent/qq-integration.log

在 pi 中可用 /qq-logs 查看最近 30 条，用 /qq-logs-path 查看文件路径。日志文件达到 5MB 会自动截断。

注意事项

Token 安全 — access_token 有效期 2 小时，扩展会自动提前刷新
消息频率 — QQ Bot 主动消息每月每用户/群限 4 条，被动回复较宽松
Session 管理 — session 切换（/new、/resume）需在 pi 终端中操作
#settings 持久化 — 设置保存在 qq-integration-config.json 中，/reload 不丢失
群聊消息 — 仅接收 @机器人的群消息（GROUP_AT_MESSAGE_CREATE）
配置文件 — 含 AppSecret，注意不要提交到 git

开发

cd ~/.pi/agent/extensions/qq-integration
npm install          # 安装依赖
# 编辑代码后 /reload 即可热重载