Add QQ gateway runtime support

README.md

@@ -9,9 +9,12 @@ Requires Node.js 20+.
 ```bash
 npm install
 npm run build
-npx gori-agent setup
+./install.sh
+gori-agent setup
 ```
 
+`install.sh` installs the command wrapper under `~/.gori-agent/bin`, stores runtime PID/log files under `~/.gori-agent/state` and `~/.gori-agent/logs`, and adds the command to `~/.bashrc`. Open a new terminal or run `source ~/.bashrc` before using `gori-agent` directly.
+
 If the package bin has not been linked, use the no-link fallback:
 
 ```bash
@@ -32,6 +35,25 @@ Fallback:
 npm run gori-agent -- start --config ./config.json
 ```
 
+Convenience executable:
+
+```bash
+gori-agent setup
+gori-agent start
+gori-agent start-daemon
+gori-agent status
+gori-agent logs
+gori-agent stop
+```
+
+If the command is not linked into PATH, run the project-local wrapper:
+
+```bash
+./gori-agent.sh status
+```
+
+Use `--config path` after the command to override the config path.
+
 ## CLI commands
 
 ```bash
@@ -85,7 +107,7 @@ Discovery never sends an actual prompt to an agent. Probes use `child_process.sp
 | Feishu/Lark | Implemented | Implemented | Replies to `im.message.receive_v1` via `/im/v1/messages/{message_id}/reply`. |
 | WeCom | 501 scaffold | Implemented | Uses `gettoken` and `message/send`; inbound callback verification/encryption is not in v1. |
 | personal WeChat | External webhook scaffold | Synchronous webhook response | Native iLink/personal WeChat integration is not included in v1. |
-| QQ | Implemented | Implemented | Supports QQ official Bot HTTP callback validation and message events. |
+| QQ | Implemented | Implemented | Supports QQ official Bot WebSocket gateway mode and optional HTTP callback mode. |
 | Generic webhook | Implemented | Synchronous JSON | HMAC-SHA256 signed JSON endpoint for local bridges and tests. |
 
 ## Hermes reference
@@ -162,17 +184,26 @@ The adapter accepts Feishu URL verification challenges and returns `{ "challenge
 
 ## QQ setup
 
-The wizard can collect QQ Bot values for the official HTTP callback mode.
+QQ has two connection modes:
 
-Manual steps:
+- `websocket` (default/recommended): the gateway actively connects to QQ with OAuth access token and WebSocket. No public domain or callback URL is needed.
+- `webhook`: QQ posts events to a public HTTPS callback URL.
 
-1. Create a QQ official Bot and enable HTTP callback/event subscription.
+Manual WebSocket steps:
+
+1. Create a QQ official Bot.
+2. Put `appId` and `clientSecret` into your config.
+3. Keep `platforms.qq.connectionMode` as `"websocket"`.
+4. Keep the default `intents` value `33554432` (`1 << 25`, `GROUP_AND_C2C_EVENT`) to receive `GROUP_AT_MESSAGE_CREATE` and `C2C_MESSAGE_CREATE`.
+5. Run `gori-agent start --config ./config.json`; the process should log `QQ websocket ready` after successful authentication.
+
+Manual HTTP callback steps:
+
+1. Set `platforms.qq.connectionMode` to `"webhook"`.
 2. Configure the callback URL to `https://<host>/webhook/qq`. QQ callback URLs must use an allowed public HTTPS port such as 443, 8443, 8080, or 80.
-3. Subscribe to message events you need, commonly `GROUP_AT_MESSAGE_CREATE` and `C2C_MESSAGE_CREATE`.
-4. Put `appId`, `clientSecret`, and `botSecret` into your config.
-5. Keep `verifySignature` enabled in production so `X-Signature-Ed25519` callbacks are verified.
+3. Put `botSecret` into your config and keep `verifySignature` enabled so `X-Signature-Ed25519` callbacks are verified.
 
-The adapter handles QQ `op: 13` callback URL validation and returns `{ "plain_token": "...", "signature": "..." }`. `GROUP_AT_MESSAGE_CREATE` and `C2C_MESSAGE_CREATE` callbacks return QQ HTTP callback ACK `{ "op": 12 }` immediately, then reply through the QQ Bot group/C2C message APIs.
+The webhook adapter handles QQ `op: 13` callback URL validation and returns `{ "plain_token": "...", "signature": "..." }`. `GROUP_AT_MESSAGE_CREATE` and `C2C_MESSAGE_CREATE` callbacks return QQ HTTP callback ACK `{ "op": 12 }` immediately, then reply through the QQ Bot group/C2C message APIs.
 
 ## Generic webhook