# @chen\_hu\_hu/pi-qq 中文文档

规范地址：https://npmcn.com/package/%40chen_hu_hu/pi-qq/

版本：1\.6\.0
npm 元数据更新时间：2026-11-09T09:28:51.793Z
中文译文更新时间：2026-11-09T12:04:09.223Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40chen_hu_hu/pi-qq
原文对照：https://npmcn.com/package/%40chen_hu_hu/pi-qq/?lang=original
项目主页：https://github.com/CQ-Developer/pi-qq#readme
源码仓库：https://github.com/CQ-Developer/pi-qq

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：290 kB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.19\.0
- 运行依赖：3 个
- peer 依赖：@earendil-works/pi-coding-agent \*
- 首次发布：2026-10-29T07:28:31.347Z
- 最新版本发布：2026-11-09T09:28:51.488Z
- 近 30 天下载量：3699（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

连接 pi 到 QQ 私人聊天.

## 安装

```sh
npm install @chen_hu_hu/pi-qq
```

也可以使用：`pnpm add @chen_hu_hu/pi-qq`、`yarn add @chen_hu_hu/pi-qq`、`bun add @chen_hu_hu/pi-qq`

## README

# 皮克语

[联合国](https://npmcn.com/package/%40chen_hu_hu/pi-qq/README.md) | [简体中文](https://npmcn.com/package/%40chen_hu_hu/pi-qq/README-zh.md)

连接 [毕](https://github.com/earendil-works/pi) 给一个QQ私人聊天。 从QQ发送文本,语音,图像,或文件;pi在你的机器上工作,并将结果发回.

## 所需资源

-   节点.js 22.19或更新,相匹配的pi.
-   一个带有 C2C 私人信件的QQ机器人应用程序启用.
-   一个工作设备.

## 安装

```bash
pi install npm:@chen_hu_hu/pi-qq
```

关于地方发展:

```bash
pi --extension /path/to/pi-qq
```

## 登录

1.  开始吧.
2.  运行 `/qq-login`。 。 。 .
3.  用移动QQ扫描QR代码.

全权证书不写给 `pi-qq.json`恢复派需要再次扫描. `/qq-logout` 立即清除证书.

## 使用量

向机器人发送私人信息以启动任务.

-   **文本**: 普通聊天消息.
-   **语音**:QQ内置ASR文本发至pi. 音频没有下载或保存 。 如果 ASR 不返回文本, 机器人会要求您重新发送或输入它 .
-   **图像和文件**: 保存在下面 `.pi/pi-qq/<sessionId>/uploads/`。如果信件没有指令, pi 将等待您的下一个文本或语音消息.

QQ客户端在混合消息支持上存在差异. 移动QQ通常一次发送一个消息类型;桌面QQ可以发送带有图像的文本. 当客户端包含文本或语音以及附件时,pi-qq会在同一快取中处理.

### 附录

只有附件信件才会 **没有** 启动 pi。文件和图像被保存, pi 等待下一个文本或语音指令 .

-   发送一个或多个文件或图像,然后发送文字或语音信息,描述要做什么.
-   下一个指令包括已保存的附件路径 .
-   指令前上传的多个附件合并为一个快取.
-   图片通过Pi读取 `read` 因此,当前模型必须支持图像输入才能看到它们.
-   `/new` 清除等待指示的附件.
-   上传范围为当前 pi 会话 。 相同的文件名和相同的内容重复使用现有文件; 内容不同的相同的文件名将变成 `name-1.ext`;内容相同的不同文件名单独保存.

Pi 所看到的例子 :

```text
# Attachments:
- .pi/pi-qq/<sessionId>/uploads/report.pdf

# User message:
Summarize this file.
```

### 发送媒体返回QQ

QQ 登录后, pi-qq 激活 `qq_send_media` 工具。 它在启动时和之后被注册为不活动 `/qq-logout`;重新连接不会禁用它.

比如说明确问派 `send me the screenshot` 或者说 `把截图发给我`. 模型从工具描述中决定;应首先澄清模棱两可的请求。 没有关键字匹配或额外确认步骤 .

-   图像 : `.jpg`, (中文(简体) ), `.jpeg`, (中文(简体) ), `.png`, (中文(简体) ), `.gif`, (中文(简体) ), `.webp`, (中文(简体) ), `.bmp`;最高可达30 MB.
-   视频 : `.mp4`, (中文(简体) ), `.mov`, (中文(简体) ), `.avi`, (中文(简体) ), `.mkv`, (中文(简体) ), `.webm`, (中文(简体) ), `.flv`, (中文(简体) ), `.wmv`; 最多100 MB.
-   其他文件:最多100 MB;音频作为文件发送.
-   允许任何可读的正则文件 。 共通链接、目录和设备被拒绝.
-   每条媒体信息都包含一个被动的回复;在限制后,pi-qq回复到主动的信息.
-   工具泡与任何其他工具相同: `## 📤 qq_send_media`。 。 。 .

### 语音信息

语音信息使用QQ内置ASR(`asr_refer_text`) (中文(简体) ). 笔录作为普通用户文本发送给 pi; pi 从未收到音频文件.

-   语音附件不下载或保存为 `.amr` 编号 : `.silk`。 。 。 .
-   不使用本地或外部语音对文本服务.
-   如果QQ ASR 不返回文本, 机器人会回复 `Could not transcribe this voice message; please resend or type it.` 而不启动 pi 运行.
-   语音和文本是分开的QQ消息;需要时互相发送.
-   如果客户端将文件或图像连同语音信息一起发送,则会用笔录处理.

除错日志包括原始 `asr_refer_text` 和附件元数据 `logLevel` 设置为 `debug`。 。 。 .

### 答复格式

-   **思考**:它自己的泡沫,纯文本,从 `## 💭 思考`。长时间的思维可能在新的泡沫中继续,并重复标题.
-   **工具**: 每个呼叫一个泡泡: `## <icon> <name>`· ; `bash` 命令使用一个 `bash` 代码块、 其他参数使用内行代码和结果使用 `text`, (中文(简体) ), `markdown`, (中文(简体) ), `python`, (中文(简体) ), `json`等,取决于工具和文件类型.
-   **常规消息**:没有标题的原始文本.
-   **工具图标**:qq bash,qq读取,qq写出,qq编辑,qq grep,qq搜索,qq find,qq is,qq列表,qq网络,qq取取取,qq删除,xq去除,qq待办,qq测试;未配置工具使用qq.
-   **错误恢复**:在模型出错后,60秒内自动重试运行,不断向原来的QQ聊天. `/stop` 等待活动工具和流在回复前完成 .

## 图标

在 Pi 终端运行 :

| 命令 | 说明 |
| --- | --- |
| `/qq-login` | 登录 QR 代码并绑定扫描 QQ 用户 |
| `/qq-status` | 显示登录、连接、模型、上下文和绑定用户 |
| `/qq-logout` | 清除和清空全权证书 |
| `/qq-new` | 重置本届会议(由QQ使用) `/new`(中文(简体) ) |

QQ侧命令 :

| 命令 | 说明 |
| --- | --- |
| `/new` | 开始一个新的 pi 会话 |
| `/stop` | 中止当前运行 |
| `/compact` | 压缩当前背景 |
| `/status` | 显示会话和上下文状态 |
| `/last` | 按下最后一个已完成的回覆为流, 或重新启动当前输出 |
| `/help` | 显示命令帮助 |

### 诊断

这些终端命令用于排除故障:

| 命令 | 说明 |
| --- | --- |
| `/qq-test-budget` | 显示被动预算和流泡诊断 |
| `/qq-test-md [text]` | 发送 Markdown 测试消息 |
| `/qq-test-stream` | 运行流时段诊断( R)`resume` (用于探测) |

与 `logLevel: "debug"`,日志仅在登录后QQ触发运行活动时写入;本地运行,登录,和闲置时段不登录. `scope: "media"` 覆盖这些运行过程中的媒体工具步骤,QQ中继日志只出现在QQ触发运行中.

## 设置

创建 `~/.pi/agent/pi-qq.json` 以覆盖默认值。 它只存储设置; 证书永远不会写给它 .

```json
{
  "thinkingRelay": true,
  "replyType": "full",
  "deliverAs": "steer",
  "fileMaxSize": 52428800,
  "language": "zh-cn",
  "logLevel": "silent"
}
```

| 密钥 | 默认 | 说明 |
| --- | --- | --- |
| `thinkingRelay` | `true` | 以本地化方式将文字中继 `## 💭` 标题 |
| `replyType` | `"full"` | 多少跑步被推入QQ: `full`, (中文(简体) ), `simple`, (中文(简体) ), `last` |
| `deliverAs` | `"steer"` | 忙碌时排队新消息 : `steer` 或者说 `followUp` |
| `fileMaxSize` | `52428800` | QQ附件下载限制, 以字节( 50MB) 为单位 |
| `language` | `"zh-cn"` | 用户界面和日志语言 : `zh-cn` 或者说 `en-us` |
| `logLevel` | `"silent"` | 日志阈值 : `silent`, (中文(简体) ), `error`, (中文(简体) ), `warn`, (中文(简体) ), `info`,或 `debug` |

设置在 pi 会话开始时被读取; 文件编辑后重新启动 pi 。 未知的密钥被忽略,无效的值会回落到带有警告的默认值.

### `replyType`

多少代理运行被推入QQ.

| 数值 | QQ接收 |
| --- | --- |
| `full` | 思考块、 工具呼叫、 工具结果以及每个助理消息( 默认) |
| `simple` | 仅限助理留言,每个泡泡一个 |
| `last` | 只有运行中最后一个助理消息, 当运行结束时发送 |

-   `full` 是默认并保持 pi-qq 1.5.x 的行为;这是唯一的模式 `thinkingRelay` 适用.
-   `simple` 串流每个助理消息直播,每个消息一个QQ泡.
-   `last` 任务执行时不发送任何信息; `/last` 在运行中任务回复时,任务仍在运行.
-   模型错误总是作为普通消息立即传送,在每个模式中.
-   工具输出没有在 `simple` 或者说 `last`,但文件随 `qq_send_media` 仍在交付.

### `thinkingRelay`

该模型的思维是否被转发给QQ作为自己的泡沫.

-   `true` (默认):思维在本地化下作为纯文本被转发 `## 💭` 标题.
-   `false`:思维被放弃.
-   仅适用于 `replyType: "full"`· ; `simple` 财务报告和审定财务报表 `last` 永远不要思考.

### `deliverAs`

当任务已经运行时,QQ消息是如何到达 pi 的 .

-   `steer` (默认):消息被注入到下一个安全点的运行任务中.
-   `followUp`:消息在运行任务完成后排入队列并处理.

### `fileMaxSize`

输入附件的最大大小, 以字节计( 默认) `52428800`50MB) (中文(简体) ). 较大文件被以通知方式拒绝,而不是被下载,这使得本地磁盘和下载配额受到控制.

### `language`

用户界面通知和日志消息的语言.

-   `zh-cn` (默认):简化中文.
-   `en-us`: 英语.

### `logLevel`

逻辑阈值。 记录只在QQ触发运行活动时写入 `<cwd>/.pi/pi-qq/logs/pi-qq-YYYY-MM-DD.log`· ; `PI_QQ_LOG_DIR` 覆盖目录.

-   `silent` (默认):完全没有日志文件.
-   `error`:只有失败.
-   `warn`:失败和可收回的问题.
-   `info`:也运行元数据——消息id,内容长度,代理开始和结束.
-   `debug`:一切,包括工具参数和结果,附件元数据,提示和原始语音记录.

## 发展

```bash
npm ci
npm run lint
npm run typecheck
npm test
npm run format:check
```

扩展切入点是 `index.ts`源模块按职责分类:

| 目录 | 责任 |
| --- | --- |
| `src/qq/` | QQ 机器人生命周期、登录、入境处理、答复 |
| `src/relay/` | 流式思维/工具/文本中继器 |
| `src/attachments/` | 附件下载、储存和语音记录 |
| `src/quota/` | 被动答复预算 |
| `src/infra/` | 设置、记录和显示格式 |

## 页:1

-   只支持C2C(QQ私人聊天).
-   由入境QQ消息所触发的运行被转发至QQ. 不相干的任务直接从 pi 本地开始 .
-   图像保存为文件并通过 pi 读取 `read` 工具;当前模型必须支持图像输入才能看到它们.
-   保存的附件为工作空间- 本地 `.pi/`; 添加 `.pi/` 切换到您自己的项目 `.gitignore` 如果需要的话.
-   QQ限制每个输入消息的被动回复. 使用 `/qq-test-budget` 检查地方预算.
-   读取a `SKILL.md` 显示为 `## 🧩 Skill` 有技能名的块; 文件内容不转发给QQ.

## 许可证

麻省理工学院

## 常见问题

### @chen\_hu\_hu/pi-qq 是什么？

连接 pi 到 QQ 私人聊天\.

### 如何安装 @chen\_hu\_hu/pi-qq？

在项目目录运行 npm install @chen\_hu\_hu/pi-qq，或使用 pnpm add / yarn add / bun add。

### @chen\_hu\_hu/pi-qq 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/chen\_hu\_hu\_\_pi-qq 是否存在。

### @chen\_hu\_hu/pi-qq 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @chen\_hu\_hu/pi-qq 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @chen\_hu\_hu/pi-qq 可以商用吗？

@chen\_hu\_hu/pi-qq 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @chen\_hu\_hu/pi-qq 的下载量有多少？

根据 npm 官方下载统计，@chen\_hu\_hu/pi-qq 在 2026/10/10 – 2026/11/08 这 30 天内被下载 3,699 次，日均约 123 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @chen\_hu\_hu/pi-qq 还在维护吗？

最新版本 1\.6\.0 发布于 2026/11/09（今天）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2026/10/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。