@zhin.js/adapter-icqq 2.0.23 → 2.0.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/package.json +8 -8
  3. package/skills/icqq/SKILL.md +26 -29
  4. package/skills/icqq/references/friends.md +8 -8
  5. package/skills/icqq/references/general.md +92 -7
  6. package/skills/icqq/references/gfs.md +2 -2
  7. package/skills/icqq/references/groups.md +3 -3
  8. package/skills/icqq/references/messaging.md +1 -3
package/CHANGELOG.md CHANGED
@@ -1,5 +1,21 @@
1
1
  # @zhin.js/adapter-icqq
2
2
 
3
+ ## 2.0.25
4
+
5
+ ### Patch Changes
6
+
7
+ - 3b3e49b: fix: ask 工具修复,icqq skill 优化
8
+ - zhin.js@1.0.80
9
+ - @zhin.js/console@2.0.23
10
+ - @zhin.js/http@1.0.73
11
+ - @zhin.js/core@1.1.22
12
+
13
+ ## 2.0.24
14
+
15
+ ### Patch Changes
16
+
17
+ - dc04e4a: fix: skill 优化
18
+
3
19
  ## 2.0.23
4
20
 
5
21
  ### Patch Changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zhin.js/adapter-icqq",
3
- "version": "2.0.23",
3
+ "version": "2.0.25",
4
4
  "description": "Zhin.js adapter for ICQQ (QQ Bot)",
5
5
  "type": "module",
6
6
  "main": "./lib/index.js",
@@ -51,16 +51,16 @@
51
51
  "lucide-react": "^1.14.0",
52
52
  "radix-ui": "^1.4.3",
53
53
  "typescript": "^6.0.3",
54
- "@zhin.js/cli": "1.0.75",
55
- "@zhin.js/console": "2.0.22",
56
- "zhin.js": "1.0.79"
54
+ "@zhin.js/cli": "1.0.76",
55
+ "@zhin.js/console": "2.0.23",
56
+ "zhin.js": "1.0.80"
57
57
  },
58
58
  "peerDependencies": {
59
59
  "@zhin.js/client": "1.0.18",
60
- "@zhin.js/console": "2.0.22",
61
- "@zhin.js/core": "1.1.21",
62
- "@zhin.js/http": "1.0.72",
63
- "zhin.js": "1.0.79"
60
+ "@zhin.js/console": "2.0.23",
61
+ "@zhin.js/core": "1.1.22",
62
+ "@zhin.js/http": "1.0.73",
63
+ "zhin.js": "1.0.80"
64
64
  },
65
65
  "peerDependenciesMeta": {
66
66
  "@zhin.js/client": {
package/skills/icqq/SKILL.md CHANGED
@@ -2,43 +2,40 @@
2
2
  name: icqq
3
3
  platforms:
4
4
  - icqq
5
- description: 'Operate QQ account via icqq CLI. Use when asked to: send QQ message, manage QQ groups, check QQ friends, poke friend, like friend, mute member, kick member, set nickname, view QQ profile, handle friend/group requests, manage group files, set group announcement, QQ签到, 发消息, 管群, 好友操作, 群文件.'
6
- argument-hint: 'Describe what QQ operation to perform, e.g. "send hello to friend 12345" or "mute user 67890 in group 11111"'
5
+ description: '通过 icqq 命令行操作 QQ 账号。适用于：发私聊或群消息、撤回、查聊天记录；好友（列表、资料、备注、戳一戳、点赞、删好友、分组）；群（禁言、踢人、公告、签到、精华、成员、邀请、全体禁言）；好友/群验证与入群请求；群文件；昵称头像签名、在线状态；黑名单、OCR、Webhook、通知；登录与守护进程。用户提到 QQ、企鹅、好友、群聊、@、撤回、禁言、踢人、加群、好友请求、群文件、签到等时使用本技能。'
6
+ argument-hint: '用一句话说明要对 QQ 执行的操作，例如「给好友 12345 发一条你好」或「把群 11111 里的用户 67890 禁言 10 分钟」'
7
7
  disable-model-invocation: true
8
8
  ---
9
9
 
10
- # icqq — QQ Account Operations via CLI
10
+ # icqq — 用命令行操作 QQ
11
11
 
12
- Operate a QQ account through the `icqq` command-line tool. The daemon must be running first (`icqq login`).
12
+ 通过 **`icqq`** 命令行工具操作 QQ。需先 **`icqq login`** 启动守护进程后再执行其它命令。
13
13
 
14
- ## Procedure
14
+ ## 使用流程
15
15
 
16
- 1. **Identify the module** — Match the user's intent to one of the modules below
17
- 2. **Load the reference** — Read ONLY the relevant module reference file(s)
18
- 3. **Check daemon** — Run `icqq status` if unsure whether the account is online
19
- 4. **Execute** — Run the command in terminal and report results
16
+ 1. **判断模块** — 对照下方「模块表」，匹配用户意图属于哪一类
17
+ 2. **只读对应参考** — 仅打开与意图相关的 `references/*.md`，不要凭记忆猜命令
18
+ 3. **执行命令** — 在终端运行 `icqq …`，把结果回报给用户；未登录或守护未起时命令失败即如实说明
20
19
 
21
- ## Modules
20
+ ## 模块表
22
21
 
23
- Load the corresponding reference file based on what the user wants:
22
+ 按用户想做的事，打开对应参考文件：
24
23
 
25
- | Intent | Module | Reference |
26
- |--------|--------|-----------|
27
- | 发消息、撤回、聊天记录、消息详情、合并转发 | Messaging | [messaging.md](./references/messaging.md) |
28
- | 好友列表、查看、发消息、戳一戳、点赞、删除、备注、文件、好友分组 | Friends | [friends.md](./references/friends.md) |
29
- | 群管理：发消息、禁言、踢人、公告、邀请、签到、精华、成员、表态 | Groups | [groups.md](./references/groups.md) |
30
- | 设置：昵称、头像、签名、群名片、群头衔、加群方式、匿名 | Settings | [settings.md](./references/settings.md) |
31
- | 好友/群请求处理 | Requests | [requests.md](./references/requests.md) |
32
- | 群文件：目录管理、上传下载、转发 | Group Files | [gfs.md](./references/gfs.md) |
33
- | 登录、状态、配置、OCR、黑名单、Webhook、通知、UID转换、陌生人、漫游表情、缓存、重载、频道与子频道（Guild & Channel）、补全 | General | [general.md](./references/general.md) |
24
+ | 用户意图 | 模块 | 参考文档 |
25
+ |----------|------|----------|
26
+ | 发消息、撤回、聊天记录、消息详情、合并转发 | 消息 | [messaging.md](./references/messaging.md) |
27
+ | 好友列表、查看、发消息、戳一戳、点赞、删除、备注、文件、好友分组 | 好友 | [friends.md](./references/friends.md) |
28
+ | 群：发消息、禁言、踢人、公告、邀请、签到、精华、成员、表态 | 群管理 | [groups.md](./references/groups.md) |
29
+ | 昵称、头像、签名、群名片、群头衔、加群方式、匿名等设置 | 设置 | [settings.md](./references/settings.md) |
30
+ | 好友请求、群请求、入群验证 | 请求 | [requests.md](./references/requests.md) |
31
+ | 群文件：目录、上传下载、转发 | 群文件 | [gfs.md](./references/gfs.md) |
32
+ | 登录、服务/守护、配置、OCR、黑名单、Webhook、通知、UID 转换、陌生人、漫游表情、缓存、重载、频道、RPC、补全 | 通用 | [general.md](./references/general.md) |
34
33
 
35
- ## Global Notes
34
+ ## 全局约定
36
35
 
37
- - All `<uid>` = QQ number (integer), `<gid>` = group number (integer)
38
- - Daemon must run first: `icqq login`
39
- - Multi-instance: use `-u <uin>` or `ICQQ_CURRENT_UIN` env to specify account; defaults to `config.currentUin`
40
- - **Use `icqq friend send` / `icqq group send` for non-interactive messaging** (agent-friendly); `icqq friend chat` / `icqq group chat` are interactive
41
- - CQ code syntax in messages: `[face:id]` `[image:path]` `[at:uid]` `[at:all]` `[dice]` `[rps]`
42
- - Quote strings with spaces: `icqq friend send 12345 "hello world"`
43
- - Chain batch ops with `&&`
44
- - **Agent / bash**：`icqq …` 多由 `bash` 执行；`execSecurity: allowlist` 下非敏感子命令通常直接放行，敏感操作与 Owner `approve rule` / `approve always bash` 等见框架文档 [docs/advanced/ai.md](../../../../../docs/advanced/ai.md)（`#icqq-bash-exec`、`#owner-approve-commands`）。
36
+ - `<uid>` = QQ 号（数字），`<gid>` = 群号（数字）
37
+ - 多账号：全局参数 `-u <uin>` 或环境变量 `ICQQ_CURRENT_UIN`；默认用配置里的 `currentUin`
38
+ - **自动执行发消息** 优先用 **`icqq friend send` / `icqq group send`**（非交互）；`icqq friend chat` / `icqq group chat` 为交互式，不适合代理串行跑
39
+ - CQ 码片段：`[face:id]` `[image:路径或URL]` `[at:uid]` `[at:all]` `[dice]` `[rps]`
40
+ - 含空格的内容用英文双引号包起来：`icqq friend send 12345 "你好 世界"`
41
+ - 批量操作用 `&&` 串联多条命令
package/skills/icqq/references/friends.md CHANGED
@@ -12,20 +12,20 @@ icqq friend avatar-url <uid> # Get avatar URL
12
12
 
13
13
  ```
14
14
  icqq friend send <uid> <message> # Send private message
15
- icqq friend poke <uid> # Poke a friend
16
- icqq friend like <uid> [-t times] # Like (1-20 times, default 1)
17
- icqq friend delete <uid> [-b] # Delete friend (-b: also block)
18
- icqq friend remark <uid> <remark> # Set friend remark/alias
19
- icqq friend add <uid> # Add friend (optionally via group)
15
+ icqq friend poke <uid> # Poke a friend
16
+ icqq friend like <uid> [-t times] # Like (1-20 times, default 1)
17
+ icqq friend delete <uid> [-b] # Delete friend (-b: also block)
18
+ icqq friend remark <uid> <remark> # Set friend remark/alias
19
+ icqq friend add <uid> # Add friend (optionally via group)
20
20
  ```
21
21
 
22
22
  ## Files
23
23
 
24
24
  ```
25
25
  icqq friend send-file <uid> <file> # Send file to friend
26
- icqq friend file-info <uid> <fid> # Get file info
27
- icqq friend file-url <uid> <fid> # Get file download URL
28
- icqq friend recall-file <uid> <fid> # Recall a sent file
26
+ icqq friend file-info <uid> <fid> # Get file info
27
+ icqq friend file-url <uid> <fid> # Get file download URL
28
+ icqq friend recall-file <uid> <fid> # Recall a sent file
29
29
  ```
30
30
 
31
31
  ## Friend Classes (Groups)
package/skills/icqq/references/general.md CHANGED
@@ -2,19 +2,38 @@
2
2
 
3
3
  ## Account
4
4
 
5
+ > Use **`icqq service status`** for service/daemon state, or **`icqq profile`** / **`icqq friend list`** to verify the daemon answers over IPC.
6
+
5
7
  ```
6
8
  icqq login # Login QQ and start daemon (interactive wizard)
7
9
  icqq login -r # Quick reconnect using saved token
8
10
  icqq login -q <uid> -r # Quick reconnect specific account
9
- icqq status # Check all daemon/account statuses
10
- icqq stop # Stop the daemon
11
- icqq stop <uin> # Stop specific daemon
11
+ icqq logout # Logout and stop daemon (token invalidated)
12
+ icqq logout -k # Disconnect only, keep token (login -r still works)
13
+ icqq logout <uin> # Logout specific account
12
14
  icqq switch # Switch current account (interactive)
13
15
  icqq switch <uin> # Switch to specific account
14
16
  icqq profile # View current account profile
15
17
  icqq requests # View pending friend/group requests
16
18
  ```
17
19
 
20
+ ## System Service (auto-restart on crash, start on boot)
21
+
22
+ ```
23
+ icqq service install # Register daemon as system service (launchd/systemd)
24
+ icqq service install -a # Install service for all configured accounts
25
+ icqq service uninstall # Remove system service
26
+ icqq service uninstall -a # Uninstall all
27
+ icqq service start # Start installed service
28
+ icqq service start -a # Start all
29
+ icqq service stop # Stop service (keeps service file, no restart until start)
30
+ icqq service stop -a # Stop all
31
+ icqq service status # Show service install/running state
32
+ icqq service status -a # Show status for all accounts
33
+ ```
34
+
35
+ Note: `icqq logout` does NOT prevent service auto-restart. To permanently stop, uninstall the service first.
36
+
18
37
  ## Config
19
38
 
20
39
  ```
@@ -79,9 +98,9 @@ icqq get video-url <vid> # Get video download URL
79
98
  ## Stranger
80
99
 
81
100
  ```
82
- icqq stranger view <uid> # View stranger profile
83
- icqq stranger status <uid> # Check online status
84
- icqq stranger add-setting <uid> # Check add-friend settings
101
+ icqq stranger view <uid> # View stranger profile
102
+ icqq stranger status <uid> # Check online status
103
+ icqq stranger add-setting <uid> # Check add-friend settings
85
104
  ```
86
105
 
87
106
  ## Roaming Emoji (Stamps)
@@ -122,10 +141,76 @@ icqq guild channel forum-url <guild_id> <channel_id> <forum_id> # Get forum URL
122
141
  icqq completion [shell] # Generate shell completion script (bash/zsh/fish)
123
142
  ```
124
143
 
144
+ ## RPC (TCP Remote Connection)
145
+
146
+ The daemon supports optional TCP remote access for cross-machine QQ account control.
147
+
148
+ ### Configuration
149
+
150
+ In `~/.icqq/config.json`:
151
+
152
+ ```json
153
+ {
154
+ "rpc": {
155
+ "enabled": true,
156
+ "host": "127.0.0.1",
157
+ "port": 0
158
+ }
159
+ }
160
+ ```
161
+
162
+ Or via CLI:
163
+
164
+ ```
165
+ icqq config set rpc.enabled true # Enable RPC TCP listener
166
+ icqq config set rpc.host 0.0.0.0 # Listen on all interfaces (for remote access)
167
+ icqq config set rpc.port 9100 # Set listen port (0 = auto-assign)
168
+ ```
169
+
170
+ | Field | Description | Default |
171
+ |-------|-------------|---------|
172
+ | `enabled` | Enable RPC TCP listener | `false` |
173
+ | `host` | Listen address, `"0.0.0.0"` for remote | `"127.0.0.1"` |
174
+ | `port` | Listen port, `0` = auto-assign | `0` |
175
+
176
+ ### Security
177
+
178
+ - **HMAC-SHA256 challenge-response auth** — token never transmitted over network
179
+ - **IP rate limiting** — 5 failures in 5 minutes → auto-block
180
+ - **Default localhost only** — must explicitly set `host: "0.0.0.0"` for remote access
181
+ - **4KB unauthenticated buffer limit** — prevents memory exhaustion
182
+
183
+ ### Programmatic Access
184
+
185
+ ```typescript
186
+ import { IpcClient } from "@icqqjs/cli/lib/ipc-client";
187
+
188
+ // Option 1: Specify host/port/token directly
189
+ const client = await IpcClient.connectRpc({
190
+ host: "192.168.1.100",
191
+ port: 9100,
192
+ token: "your-token-here",
193
+ });
194
+
195
+ // Option 2: Auto-read from daemon.rpc file (local only)
196
+ const client = await IpcClient.connectRpcByUin(12345);
197
+
198
+ const resp = await client.request("list_friends");
199
+ client.close();
200
+ ```
201
+
202
+ ### Auth Flow
203
+
204
+ 1. Client connects to TCP port
205
+ 2. Server sends `{ "challenge": "<random-hex>" }`
206
+ 3. Client computes `HMAC-SHA256(token, challenge)` → digest
207
+ 4. Client sends `{ "action": "auth", "params": { "digest": "<hex>" } }`
208
+ 5. Server verifies → authenticated
209
+
125
210
  ## Examples
126
211
 
127
212
  ```bash
128
- icqq status
213
+ icqq service status
129
214
  icqq profile
130
215
  icqq requests
131
216
  icqq login -r
package/skills/icqq/references/gfs.md CHANGED
@@ -3,7 +3,7 @@
3
3
  ## List Files
4
4
 
5
5
  ```
6
- icqq group fs list <gid> # List root directory
6
+ icqq group fs list <gid> # List root directory
7
7
  icqq group fs list <gid> -p <pid> # List subdirectory by parent ID
8
8
  ```
9
9
 
@@ -27,7 +27,7 @@ icqq group fs move <gid> <fid> <pid> # Move file to directory
27
27
 
28
28
  ```
29
29
  icqq group fs upload <gid> <file> # Upload file to group
30
- icqq group fs download <gid> <fid> # Get download URL
30
+ icqq group fs download <gid> <fid> # Get download URL
31
31
  icqq group fs forward <gid> <fid> <target_gid> # Forward file to another group
32
32
  icqq group fs forward-offline <gid> <fid> # Convert to offline file
33
33
  ```
package/skills/icqq/references/groups.md CHANGED
@@ -35,9 +35,9 @@ icqq group screen-member <gid> <uid> # Block/unblock member messages
35
35
 
36
36
  ```
37
37
  icqq group send <gid> <message> # Send group message
38
- icqq group poke <gid> <uid> # Poke group member
39
- icqq group invite <gid> <uid> # Invite friend to group
40
- icqq group sign <gid> # Group check-in
38
+ icqq group poke <gid> <uid> # Poke group member
39
+ icqq group invite <gid> <uid> # Invite friend to group
40
+ icqq group sign <gid> # Group check-in
41
41
  ```
42
42
 
43
43
  ## Reactions
package/skills/icqq/references/messaging.md CHANGED
@@ -22,7 +22,7 @@ Messages support inline CQ codes for rich content:
22
22
  [rps] # Rock-paper-scissors
23
23
  ```
24
24
 
25
- Mixed example: `icqq group send 67890 "你好[face:178]看看[image:/tmp/pic.jpg]"`
25
+ Mixed example: `icqq send group 67890 "你好[face:178]看看[image:/tmp/pic.jpg]"`
26
26
 
27
27
  ## Recall
28
28
 
@@ -52,8 +52,6 @@ icqq friend chat <uid> # Enter private chat mode
52
52
  icqq group chat <gid> # Enter group chat mode
53
53
  ```
54
54
 
55
- > **Do NOT use interactive chat commands for agent operations.** Use `icqq friend send` / `icqq group send` instead.
56
-
57
55
  ## Examples
58
56
 
59
57
  ```bash