Add CLI setup and QQ webhook integration
This commit is contained in:
zenord
@@ -1,10 +1,82 @@
|
||||
# gori-agent-gateway
|
||||
|
||||
Hermes-gateway-style multi-IM Agent Gateway for routing instant-message webhooks to configurable CLI agents. It is intentionally standalone and not tied to Pi.
|
||||
Hermes-gateway-style multi-IM Agent Gateway for routing instant-message webhooks to configurable CLI agents. The primary product flow is `gori-agent setup`: discover local agents first, pick one, then choose the IM platform to connect.
|
||||
|
||||
## Hermes reference
|
||||
## Quick start
|
||||
|
||||
This project follows the Hermes gateway pattern: platform adapters normalize inbound messages, a central gateway applies policy/session/concurrency handling, then replies are sent through the originating adapter. The Feishu adapter ports the key Hermes behavior for tenant token caching, URL challenge handling, token verification, `im.message.receive_v1` parsing, mention cleanup, and message replies.
|
||||
Requires Node.js 20+.
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run build
|
||||
npx gori-agent setup
|
||||
```
|
||||
|
||||
If the package bin has not been linked, use the no-link fallback:
|
||||
|
||||
```bash
|
||||
npm run gori-agent -- setup
|
||||
```
|
||||
|
||||
The setup wizard writes `config.json` only after confirmation. `config.json` is ignored by git and should hold local secrets.
|
||||
|
||||
Start the gateway after setup:
|
||||
|
||||
```bash
|
||||
gori-agent start --config ./config.json
|
||||
```
|
||||
|
||||
Fallback:
|
||||
|
||||
```bash
|
||||
npm run gori-agent -- start --config ./config.json
|
||||
```
|
||||
|
||||
## CLI commands
|
||||
|
||||
```bash
|
||||
gori-agent setup
|
||||
gori-agent discover-agents [--json]
|
||||
gori-agent start [--config path]
|
||||
gori-agent status [--config path]
|
||||
gori-agent doctor [--config path]
|
||||
gori-agent print feishu [--config path]
|
||||
gori-agent --help
|
||||
```
|
||||
|
||||
Package scripts mirror common commands:
|
||||
|
||||
```bash
|
||||
npm run setup
|
||||
npm run discover-agents
|
||||
npm run doctor
|
||||
```
|
||||
|
||||
## Agent-first setup flow
|
||||
|
||||
`gori-agent setup` does the following:
|
||||
|
||||
1. Discovers local CLI agents on `PATH` and always includes the built-in `echo` fallback.
|
||||
2. Lets you pick one agent.
|
||||
3. Lets you choose an IM platform: Feishu/Lark, WeChat external webhook, WeCom scaffold, QQ Bot webhook, or Generic webhook.
|
||||
4. Builds a focused `config.json` containing the chosen default agent, the chosen agent plus `echo`, and the chosen platform enabled.
|
||||
5. Asks before writing.
|
||||
|
||||
Detected ready agents with known safe prompt modes:
|
||||
|
||||
| Agent | Command | Args | Input mode | Permission mode |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Kimi | `kimi` | `-p` | final argv | `kimi -p` already runs non-interactively under Kimi Code's auto permission policy. `--yolo` cannot be combined with `-p`. |
|
||||
| OpenCode | `opencode` | `run` | final argv | setup can append `--auto`. |
|
||||
| Codex | `codex` | `exec` | final argv | default; add manual args if needed. |
|
||||
| Claude | `claude` | `-p` | final argv | default; add manual args if needed. |
|
||||
| Built-in echo | `node` | `scripts/echo-agent.js` | stdin | n/a |
|
||||
|
||||
When you pick Kimi, setup asks which Kimi Code model to use. It reads your local Kimi model aliases at setup time with `kimi provider list --json`, so custom providers from your actual Kimi config appear in the menu. Choosing the default keeps Kimi Code's configured `default_model`; choosing a model writes `-m <model> -p` into that agent's args. You can also enter a custom model alias.
|
||||
|
||||
Gemini, Qwen/Qwen Code, Copilot, Pi, and Hermes are probed with `--version` then `--help` only. If found, they are shown as `needs-config` unless a safe prompt mode is known; the wizard asks you to confirm command, args, input mode, extra auto/yolo permission args, and working directory before enabling them.
|
||||
|
||||
Discovery never sends an actual prompt to an agent. Probes use `child_process.spawn(..., { shell: false })`, a 2s timeout, and a 4KB output cap.
|
||||
|
||||
## Platform status
|
||||
|
||||
@@ -13,28 +85,14 @@ This project follows the Hermes gateway pattern: platform adapters normalize inb
|
||||
| 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 | 501 scaffold | Implemented | Uses QQ Bot access token and user/group text-message heuristics. |
|
||||
| QQ | Implemented | Implemented | Supports QQ official Bot HTTP callback validation and message events. |
|
||||
| Generic webhook | Implemented | Synchronous JSON | HMAC-SHA256 signed JSON endpoint for local bridges and tests. |
|
||||
|
||||
## Install and run
|
||||
## Hermes reference
|
||||
|
||||
Requires Node.js 20+.
|
||||
This project follows the Hermes gateway pattern: platform adapters normalize inbound messages, a central gateway applies policy/session/concurrency handling, then replies are sent through the originating adapter. The Feishu adapter ports the key Hermes behavior for tenant token caching, URL challenge handling, token verification, `im.message.receive_v1` parsing, mention cleanup, and message replies.
|
||||
|
||||
```bash
|
||||
npm install
|
||||
cp config.example.json config.json
|
||||
GORI_GATEWAY_CONFIG=./config.json npm run dev
|
||||
```
|
||||
|
||||
Build and run compiled output:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
npm run build
|
||||
GORI_GATEWAY_CONFIG=./config.json npm start
|
||||
```
|
||||
|
||||
Endpoints:
|
||||
## Endpoints
|
||||
|
||||
- `GET /health`
|
||||
- `GET /platforms`
|
||||
@@ -46,10 +104,24 @@ Endpoints:
|
||||
|
||||
## Configuration
|
||||
|
||||
Config is loaded from `GORI_GATEWAY_CONFIG`. If the variable is not set, the gateway loads `config.example.json` from the current working directory.
|
||||
Server execution still supports the existing environment variable:
|
||||
|
||||
```bash
|
||||
GORI_GATEWAY_CONFIG=./config.json npm start
|
||||
```
|
||||
|
||||
The CLI resolves config in this order:
|
||||
|
||||
1. `--config path`
|
||||
2. `GORI_GATEWAY_CONFIG`
|
||||
3. `./config.json`
|
||||
4. seed from `config.example.json` and write to `./config.json` if confirmed
|
||||
|
||||
Important sections:
|
||||
|
||||
- `server.host`: bind address, default `0.0.0.0`.
|
||||
- `server.port`: gateway port, default `3000`.
|
||||
- `server.publicBaseUrl`: public HTTPS base URL used by print/setup hints, for example `https://agent.example.com`.
|
||||
- `policy.allowedUsers`: allow only listed normalized user IDs when non-empty.
|
||||
- `policy.allowedChats`: allow only listed normalized chat IDs when non-empty.
|
||||
- `policy.requireMentionInGroup`: if true, group messages are ignored unless the adapter reports a bot mention.
|
||||
@@ -64,7 +136,7 @@ CLI agent options:
|
||||
- `outputMaxBytes`: caps captured stdout/stderr.
|
||||
- `cwd`: optional working directory for the agent process.
|
||||
|
||||
## Commands
|
||||
## Chat commands
|
||||
|
||||
The gateway handles these commands per chat before invoking an agent:
|
||||
|
||||
@@ -76,6 +148,10 @@ The gateway handles these commands per chat before invoking an agent:
|
||||
|
||||
## Feishu setup
|
||||
|
||||
The wizard can collect Feishu values and `gori-agent print feishu --config ./config.json` prints the webhook URL and checklist.
|
||||
|
||||
Manual steps:
|
||||
|
||||
1. Create a Feishu/Lark custom app and enable bot messaging.
|
||||
2. Configure event subscription for `im.message.receive_v1`.
|
||||
3. Set the request URL to `https://<host>/webhook/feishu`.
|
||||
@@ -84,6 +160,20 @@ The gateway handles these commands per chat before invoking an agent:
|
||||
|
||||
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.
|
||||
|
||||
Manual steps:
|
||||
|
||||
1. Create a QQ official Bot and enable HTTP callback/event subscription.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Generic webhook
|
||||
|
||||
Payload:
|
||||
|
||||
Reference in New Issue
Block a user