@icqqjs/cli

基于 icqq 的命令行 QQ 客户端，使用 React Ink 构建交互式终端 UI。

安装

npm install -g @icqqjs/cli

安装 icqq 核心依赖

CLI 的核心协议库 @icqqjs/icqq 托管在 GitHub Packages，首次使用需要额外安装：

# 一键安装（自动配置 .npmrc + 安装 icqq）
icqq setup

手动安装

1. 配置 npm scope：

echo '@icqqjs:registry=https://npm.pkg.github.com' >> ~/.npmrc

2. 登录 GitHub Packages（需要具有 read:packages 权限的 Personal Access Token）：

npm login --scope=@icqqjs --auth-type=legacy --registry=https://npm.pkg.github.com

3. 安装：

npm install -g @icqqjs/icqq

快速开始

# 交互式登录
icqq login

# 快速重连（使用已保存的 token）
icqq login -r

# 指定账号快速重连
icqq login -q 12345 -r

多实例支持

通过 -u 全局参数或 ICQQ_CURRENT_UIN 环境变量指定操作的账号，默认使用 currentUin。

icqq -u 12345 profile
ICQQ_CURRENT_UIN=12345 icqq friend list

命令一览

账号

命令	说明
icqq login	登录 QQ 账号并启动守护进程
icqq login -r	使用已保存 token 快速重连
icqq logout	退出登录并停止守护进程（token 作废）
icqq logout -k	仅断开连接，保留 token（可 login -r 重连）
icqq logout <uin>	退出指定账号
icqq switch [uin]	切换当前操作的账号
icqq profile	查看个人资料
icqq requests	查看待处理的好友/群请求

系统服务（崩溃自动重启、开机自启）

命令	说明
icqq service install [-a]	将守护进程注册为系统服务（macOS: launchd / Linux: systemd）
icqq service uninstall [-a]	卸载系统服务
icqq service start [-a]	启动已安装的服务
icqq service stop [-a]	停止服务（保留文件，不删除）
icqq service status [-a]	查看服务安装/运行状态

-a 参数对所有已配置账号批量执行。注意：icqq logout 不会阻止服务自动重启，如需永久停止请先 icqq service uninstall。

配置

命令	说明
icqq config get	查看所有配置
icqq config get <key>	查看指定配置项
icqq config set <key> <value>	设置配置项

消息

命令	说明
icqq friend send <qq> <message>	发送私聊消息
icqq group send <gid> <message>	发送群消息
icqq friend chat <qq>	进入好友交互聊天
icqq group chat <gid>	进入群交互聊天
icqq friend chat history <qq>	查看好友聊天记录
icqq group chat history <gid>	查看群聊天记录
icqq recall <msgid>	撤回消息
icqq msg get <msgid>	查看消息详情
icqq msg mark-read <msgid>	标记消息已读
icqq forward get <msgid>	查看合并转发消息

消息支持 CQ 码语法：

[face:id]    表情
[image:path] 图片
[at:uid]     @某人
[at:all]     @全体成员
[dice]       骰子
[rps]        猜拳

好友

命令	说明
icqq friend list	好友列表
icqq friend view <qq>	查看好友资料
icqq friend add <qq>	添加好友（可通过群）
icqq friend delete <qq>	删除好友
icqq friend like <qq>	点赞
icqq friend poke <qq>	戳一戳
icqq friend remark <qq> <name>	设置好友备注
icqq friend avatar-url <qq>	获取好友头像 URL
icqq friend send-file <qq> <file>	发送文件给好友
icqq friend file-info <qq> <fid>	获取私聊文件信息
icqq friend file-url <qq> <fid>	获取私聊文件下载链接
icqq friend recall-file <qq> <fid>	撤回发送给好友的文件

好友分组

命令	说明
icqq friend class list	查看好友分组
icqq friend class add <name>	创建好友分组
icqq friend class delete <id>	删除好友分组
icqq friend class rename <id> <name>	重命名好友分组
icqq friend class set <qq> <id>	移动好友到分组

群

命令	说明
icqq group list	群列表
icqq group view <gid>	查看群信息
icqq group member list <gid>	群成员列表
icqq group member view <gid> <qq>	查看群成员资料
icqq group invite <gid> <qq>	邀请入群
icqq group kick <gid> <qq>	踢出群成员
icqq group mute <gid> <qq> [duration]	禁言
icqq group mute-all <gid>	全体禁言
icqq group mute-anon <gid> <flag>	禁言匿名成员
icqq group muted-list <gid>	查看禁言列表
icqq group poke <gid> <qq>	戳一戳
icqq group quit <gid>	退群
icqq group sign <gid>	群签到
icqq group announce <gid> <content>	发群公告
icqq group avatar-url <gid>	获取群头像 URL
icqq group anon-info <gid>	查看群匿名信息
icqq group at-all-remain <gid>	查看 @全体 剩余次数
icqq group share <gid>	获取群分享链接
icqq group screen-member <gid> <qq>	屏蔽/取消屏蔽群成员消息
icqq group reaction add <msgid> <emoji>	消息表态
icqq group reaction remove <msgid> <emoji>	取消表态

群设置

命令	说明
icqq group set name <gid> <name>	修改群名
icqq group set avatar <gid> <file>	修改群头像
icqq group set card <gid> <qq> <card>	修改群名片
icqq group set title <gid> <qq> <title>	设置群头衔
icqq group set admin <gid> <qq>	设置/取消管理员
icqq group set remark <gid> <name>	修改群备注
icqq group set anonymous <gid>	开关匿名
icqq group set join-type <gid> <type>	设置加群方式
icqq group set rate-limit <gid> <limit>	设置发言频率限制

群精华 / 群文件

命令	说明
icqq group essence add <msgid>	添加精华消息
icqq group essence remove <msgid>	移除精华消息
icqq group fs list <gid>	群文件列表
icqq group fs info <gid>	查看群文件系统信息
icqq group fs stat <gid> <fid>	查看文件/目录详情
icqq group fs mkdir <gid> <name>	创建文件夹
icqq group fs delete <gid> <fid>	删除文件
icqq group fs rename <gid> <fid> <name>	重命名文件
icqq group fs upload <gid> <file>	上传文件
icqq group fs download <gid> <fid>	获取下载链接
icqq group fs move <gid> <fid> <pid>	移动文件
icqq group fs forward <gid> <fid> <target_gid>	转发到其他群
icqq group fs forward-offline <gid> <fid>	转为离线文件

个人设置

命令	说明
icqq set nickname <name>	修改昵称
icqq set avatar <file>	修改头像
icqq set signature <text>	修改签名
icqq set gender <gender>	修改性别
icqq set birthday <date>	修改生日
icqq set description <text>	修改简介
icqq set online-status <status>	修改在线状态

其他

命令	说明
icqq blacklist	黑名单列表
icqq ocr <file>	图片文字识别
icqq request accept <flag>	接受请求
icqq request reject <flag>	拒绝请求
icqq webhook	查看 Webhook 配置
icqq webhook set <url>	设置 Webhook 推送地址
icqq webhook off	关闭 Webhook 推送
icqq notify	查看通知状态
icqq notify on	开启系统通知
icqq notify off	关闭系统通知
icqq config set rpc.enabled true	启用 RPC TCP 远程连接
icqq config set rpc.host 0.0.0.0	设置 RPC 监听地址
icqq config set rpc.port 9100	设置 RPC 监听端口
icqq convert uid <qq>	QQ 号转 UID
icqq convert uin <uid>	UID 转 QQ 号
icqq get client-key	获取 ClientKey
icqq get pskey	获取 PSKey
icqq get video-url <vid>	获取短视频下载链接
icqq stranger view <qq>	查看陌生人资料
icqq stranger status <qq>	查看陌生人在线状态
icqq stranger add-setting <qq>	查看加好友设置
icqq stamp list	查看漫游表情列表
icqq stamp delete	删除漫游表情
icqq cache clean	清理缓存
icqq reload friends	重载好友列表
icqq reload groups	重载群列表
icqq reload blacklist	重载黑名单
icqq reload guilds	重载频道列表
icqq reload strangers	重载陌生人列表
icqq completion [shell]	生成 Shell 自动补全脚本

频道（Guild）

命令	说明
icqq guild list	频道列表
icqq guild info <guild_id>	查看频道信息
icqq guild members <guild_id>	频道成员列表
icqq guild channel list <guild_id>	子频道列表
icqq guild channel send <guild_id> <channel_id> <message>	发送子频道消息
icqq guild channel chat <guild_id> <channel_id>	进入子频道聊天模式
icqq guild channel recall <guild_id> <channel_id> <seq>	撤回子频道消息
icqq guild channel share <guild_id> <channel_id> <url> <title>	发送互联分享
icqq guild channel forum-url <guild_id> <channel_id> <forum_id>	获取帖子 URL

架构

┌──────────────────────────────────────────────────────┐
│                     icqq CLI                         │
│  ┌────────────┐  ┌────────────┐  ┌───────────────┐  │
│  │  Pastel     │  │  React Ink │  │  IPC Client   │  │
│  │  文件路由   │─▸│  终端 UI   │  │  (ipc-client) │  │
│  └────────────┘  └────────────┘  └───────┬───────┘  │
└──────────────────────────────────────────┬───────────┘
                                  IPC │         │ RPC
                           Unix Socket │         │ TCP
                           Token 直传  │         │ HMAC 挑战-响应
┌──────────────────────────────────────┴─────────┴─────┐
│                   守护进程 (Daemon)                    │
│  ┌────────────┐  ┌─────────┐ ┌──────┐ ┌──────────┐  │
│  │  icqq      │  │  IPC    │ │ RPC  │ │ Webhook  │  │
│  │  Client    │◂─│  Server │ │Server│ │  推送     │  │
│  │  (QQ协议)  │  │  (sock) │ │(TCP) │ │(HTTP POST)│  │
│  └─────┬──────┘  └─────────┘ └──────┘ └──────────┘  │
└────────┼─────────────────────────────────────────────┘
         │
         ▼
   腾讯 QQ 服务器

• CLI 层：基于 Pastel 文件系统路由，src/commands/ 目录结构即命令结构；React Ink 渲染终端 UI
• IPC 通信：CLI 与守护进程通过 ~/.icqq/<uin>/daemon.sock Unix Socket 通信，首次连接需 Token 认证
• RPC 通信：可选的 TCP 远程连接，使用 HMAC-SHA256 挑战-响应认证（token 不经过网络传输），支持 IP 限速防暴力破解
• 守护进程：登录后在后台运行，管理 icqq 客户端实例，自动断线重连（指数退避，最多 5 次）
• Webhook：可选配置，守护进程将消息事件 POST 到指定 URL
• 日志轮转：守护进程日志 > 5MB 自动轮转

RPC 远程连接

守护进程支持通过 TCP 远程访问，适用于跨机器控制 QQ 账号的场景。

启用 RPC：

在 ~/.icqq/config.json 中配置：

{
  "rpc": {
    "enabled": true,
    "host": "127.0.0.1",
    "port": 0
  }
}

字段	说明	默认值
enabled	是否启用 RPC TCP 监听	false
host	监听地址，"0.0.0.0" = 对外开放	"127.0.0.1"
port	监听端口，0 = 系统自动分配	0

安全机制：

1. HMAC-SHA256 挑战-响应认证 — 连接后服务端发送随机 challenge，客户端用 HMAC(token, challenge) 回复，token 永不经过网络传输
2. IP 限速 — 同一 IP 在 5 分钟内认证失败 5 次后自动封锁
3. 默认仅本机 — 必须显式配置 host: "0.0.0.0" 才对外暴露
4. 未认证缓冲区限制 — 4KB 防止未认证连接的内存耗尽攻击

编程接入：

import { IpcClient } from "@icqqjs/cli/lib/ipc-client";

// 方式一：指定地址和 token
const client = await IpcClient.connectRpc({
  host: "192.168.1.100",
  port: 9100,
  token: "your-token-here",
});

// 方式二：自动从 daemon.rpc 文件读取（本机）
const client = await IpcClient.connectRpcByUin(12345);

const resp = await client.request("list_friends");
client.close();

开发

pnpm install
pnpm build
npm link         # 本地全局注册 icqq 命令

发版流程

使用 Changesets 管理版本：

pnpm changeset        # 添加变更描述
git add . && git commit
git push              # 推送后 GitHub Actions 自动创建 Version PR
                      # 合并 Version PR 后自动发布到 GitHub Packages

License

ISC