npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0 - Mend

better-dsh 0.2.5 → 0.3.0

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 (999) hide show

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/wecom-callback.md DELETED Viewed

@@ -1,179 +0,0 @@
----
-sidebar_position: 15
----
-# WeCom Callback (Self-Built App)
-Connect Hermes to WeCom (Enterprise WeChat) as a self-built enterprise application using the callback/webhook model.
-:::info WeCom Bot vs WeCom Callback
-Hermes supports two WeCom integration modes:
-- **[WeCom Bot](wecom.md)** — bot-style, connects via WebSocket. Simpler setup, works in group chats.
-- **WeCom Callback** (this page) — self-built app, receives encrypted XML callbacks. Shows as a first-class app in users' WeCom sidebar. Supports multi-corp routing.
-:::
-See also: [WeCom Bot](./wecom.md) for the bot-style integration.
-> Run `hermes gateway setup` and pick **WeCom Callback** for a guided walk-through.
-## How It Works
-1. You register a self-built application in the WeCom Admin Console
-2. WeCom pushes encrypted XML to your HTTP callback endpoint
-3. Hermes decrypts the message, queues it for the agent
-4. Immediately acknowledges (silent — nothing displayed to the user)
-5. The agent processes the request (typically 3–30 minutes)
-6. The reply is delivered proactively via the WeCom `message/send` API
-## Prerequisites
-- A WeCom enterprise account with admin access
-- `aiohttp` and `httpx` Python packages (included in the default install)
-- A publicly reachable server for the callback URL (or a tunnel like ngrok)
-## Setup
-### 1. Create a Self-Built App in WeCom
-1. Go to [WeCom Admin Console](https://work.weixin.qq.com/) → **Applications** → **Create App**
-2. Note your **Corp ID** (shown at the top of the admin console)
-3. In the app settings, create a **Corp Secret**
-4. Note the **Agent ID** from the app's overview page
-5. Under **Receive Messages**, configure the callback URL:
-   - URL: `http://YOUR_PUBLIC_IP:8645/wecom/callback`
-   - Token: Generate a random token (WeCom provides one)
-   - EncodingAESKey: Generate a key (WeCom provides one)
-### 2. Configure Environment Variables
-Add to your `.env` file:
-```bash
-WECOM_CALLBACK_CORP_ID=your-corp-id
-WECOM_CALLBACK_CORP_SECRET=your-corp-secret
-WECOM_CALLBACK_AGENT_ID=1000002
-WECOM_CALLBACK_TOKEN=your-callback-token
-WECOM_CALLBACK_ENCODING_AES_KEY=your-43-char-aes-key
-# Optional
-# WECOM_CALLBACK_HOST=  # optional pin; unset = dual-stack (all interfaces, IPv4+IPv6)
-WECOM_CALLBACK_PORT=8645
-WECOM_CALLBACK_ALLOWED_USERS=user1,user2
-```
-### 3. Start the Gateway
-```bash
-hermes gateway
-```
-(Use `hermes gateway start` only after `hermes gateway install` has registered the systemd/launchd service.)
-The callback adapter starts an HTTP server on the configured port. WeCom will verify the callback URL via a GET request, then begin sending messages via POST.
-## Configuration Reference
-Set these in `config.yaml` under `platforms.wecom_callback.extra`, or use environment variables:
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `corp_id` | — | WeCom enterprise Corp ID (required) |
-| `corp_secret` | — | Corp secret for the self-built app (required) |
-| `agent_id` | — | Agent ID of the self-built app (required) |
-| `token` | — | Callback verification token (required) |
-| `encoding_aes_key` | — | 43-character AES key for callback encryption (required) |
-| `host` | unset (dual-stack: all interfaces, IPv4+IPv6) | Bind address for the HTTP callback server |
-| `port` | `8645` | Port for the HTTP callback server |
-| `path` | `/wecom/callback` | URL path for the callback endpoint |
-## Multi-App Routing
-For enterprises running multiple self-built apps (e.g., across different departments or subsidiaries), configure the `apps` list in `config.yaml`:
-```yaml
-platforms:
-  wecom_callback:
-    enabled: true
-    extra:
-      host: "0.0.0.0"
-      port: 8645
-      apps:
-        - name: "dept-a"
-          corp_id: "ww_corp_a"
-          corp_secret: "secret-a"
-          agent_id: "1000002"
-          token: "token-a"
-          encoding_aes_key: "key-a-43-chars..."
-        - name: "dept-b"
-          corp_id: "ww_corp_b"
-          corp_secret: "secret-b"
-          agent_id: "1000003"
-          token: "token-b"
-          encoding_aes_key: "key-b-43-chars..."
-```
-Users are scoped by `corp_id:user_id` to prevent cross-corp collisions. When a user sends a message, the adapter records which app (corp) they belong to and routes replies through the correct app's access token.
-## Access Control
-Restrict which users can interact with the app:
-```bash
-# Allowlist specific users
-WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu
-# Or allow all users
-WECOM_CALLBACK_ALLOW_ALL_USERS=true
-```
-## Endpoints
-The adapter exposes:
-| Method | Path | Purpose |
-|--------|------|---------|
-| GET | `/wecom/callback` | URL verification handshake (WeCom sends this during setup) |
-| POST | `/wecom/callback` | Encrypted message callback (WeCom sends user messages here) |
-| GET | `/health` | Health check — returns `{"status": "ok"}` |
-## Encryption
-All callback payloads are encrypted with AES-CBC using the EncodingAESKey. The adapter handles:
-- **Inbound**: Decrypt XML payload, verify SHA1 signature
-- **Outbound**: Replies sent via proactive API (not encrypted callback response)
-The crypto implementation is compatible with Tencent's official WXBizMsgCrypt SDK.
-## Limitations
-- **No streaming** — replies arrive as complete messages after the agent finishes
-- **No typing indicators** — the callback model doesn't support typing status
-- **Text only** — currently supports text messages for input; image/file/voice input not yet implemented. The agent is aware of outbound media capabilities via the WeCom platform hint (images, documents, video, voice).
-- **Response latency** — agent sessions take 3–30 minutes; users see the reply when processing completes
-## Troubleshooting
-**Signature verification failing.**
-WeCom signs every request with the **Token** you registered in the admin
-console. A mismatch between the token configured in Hermes and the token the
-admin console expects is the most common cause. Re-copy both the **Token** and
-**EncodingAESKey** from the admin console — they're easy to truncate. Whitespace
-in `~/.hermes/.env` values around `=` will also break signature checks. After
-fixing, restart `hermes gateway run`.
-**Callback URL not reachable / verification step fails.**
-WeCom hits the public URL you registered. Confirm:
-1. Your reverse proxy / tunnel forwards `/wecom/callback` to the gateway's port.
-2. The URL in the admin console is HTTPS (WeCom rejects plain HTTP).
-3. From outside your network, `curl -i https://<your-domain>/wecom/callback`
-   returns something other than a timeout (a 4xx without query params is fine —
-   it just means the listener is reachable).
-**Port not reachable / listener not bound.**
-Check `hermes gateway run` logs for the bound host/port. If the adapter bound to
-`127.0.0.1` you must front it with a reverse proxy or tunnel — WeCom's servers
-can't reach loopback. Leave `extra.host` unset so the default dual-stack
-bind (all interfaces, IPv4+IPv6) applies, or pin an interface in `config.yaml` (plus
-`allowed_source_cidrs` if exposing directly) or keep loopback and use a tunnel
-such as Cloudflare Tunnel / nginx.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/wecom.md DELETED Viewed

@@ -1,306 +0,0 @@
----
-sidebar_position: 14
-title: "WeCom (Enterprise WeChat)"
-description: "Connect Hermes Agent to WeCom via the AI Bot WebSocket gateway"
----
-# WeCom (Enterprise WeChat)
-Connect Hermes to [WeCom](https://work.weixin.qq.com/) (企业微信), Tencent's enterprise messaging platform. The adapter uses WeCom's AI Bot WebSocket gateway for real-time bidirectional communication — no public endpoint or webhook needed.
-See also: [WeCom Callback](./wecom-callback.md) for inbound webhook setup.
-## Prerequisites
-- A WeCom organization account
-- An AI Bot created in the WeCom Admin Console
-- The Bot ID and Secret from the bot's credentials page
-- Python packages: `aiohttp` and `httpx`
-## Setup
-### Step 1: Create an AI Bot
-#### Recommended: Scan-to-Create (one command)
-```bash
-hermes gateway setup
-```
-Select **WeCom** and scan the QR code with your WeCom mobile app. Hermes will automatically create a bot application with the correct permissions and save the credentials.
-The setup wizard will:
-1. Display a QR code in your terminal
-2. Wait for you to scan it with the WeCom mobile app
-3. Automatically retrieve the Bot ID and Secret
-4. Guide you through access control configuration
-#### Alternative: Manual Setup
-If scan-to-create is not available, the wizard falls back to manual input:
-1. Log in to the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame)
-2. Navigate to **Applications** → **Create Application** → **AI Bot**
-3. Configure the bot name and description
-4. Copy the **Bot ID** and **Secret** from the credentials page
-5. Run `hermes gateway setup`, select **WeCom**, and enter the credentials when prompted
-:::warning
-Keep the Bot Secret private. Anyone with it can impersonate your bot.
-:::
-### Step 2: Configure Hermes
-#### Option A: Interactive Setup (Recommended)
-```bash
-hermes gateway setup
-```
-Select **WeCom** and follow the prompts. The wizard will guide you through:
-- Bot credentials (via QR scan or manual entry)
-- Access control settings (allowlist, pairing mode, or open access)
-- Home channel for notifications
-#### Option B: Manual Configuration
-Add the following to `~/.hermes/.env`:
-```bash
-WECOM_BOT_ID=your-bot-id
-WECOM_SECRET=your-secret
-# Optional: restrict access
-WECOM_ALLOWED_USERS=user_id_1,user_id_2
-# Optional: home channel for cron/notifications
-WECOM_HOME_CHANNEL=chat_id
-```
-### Step 3: Start the gateway
-```bash
-hermes gateway
-```
-## Features
-- **WebSocket transport** — persistent connection, no public endpoint needed
-- **DM and group messaging** — configurable access policies
-- **Per-group sender allowlists** — fine-grained control over who can interact in each group
-- **Media support** — images, files, voice, video upload and download
-- **AES-encrypted media** — automatic decryption for inbound attachments
-- **Quote context** — preserves reply threading
-- **Markdown rendering** — rich text responses
-- **Reply correlation** — responses are correlated to the inbound message context
-- **Auto-reconnect** — exponential backoff on connection drops
-:::note Streaming and typing indicators
-The WeCom adapter streams responses natively over WeCom's `msgtype: "stream"`
-protocol: the client shows a thinking/typing bubble as soon as a turn starts,
-and the reply renders token-by-token in a single bubble as the model
-generates it. Tool-call progress is folded into the same bubble. Native
-streaming is enabled by default (`display.platforms.wecom.streaming: true` in
-`config.yaml`); set it to `false` to restore single-shot delivery.
-:::
-## Configuration Options
-Set these in `config.yaml` under `platforms.wecom.extra`:
-| Key | Default | Description |
-|-----|---------|-------------|
-| `bot_id` | — | WeCom AI Bot ID (required) |
-| `secret` | — | WeCom AI Bot Secret (required) |
-| `websocket_url` | `wss://openws.work.weixin.qq.com` | WebSocket gateway URL |
-| `dm_policy` | `open` | DM access: `open`, `allowlist`, `disabled`, `pairing` |
-| `group_policy` | `open` | Group access: `open`, `allowlist`, `disabled` |
-| `allow_from` | `[]` | User IDs allowed for DMs (when dm_policy=allowlist) |
-| `group_allow_from` | `[]` | Group IDs allowed (when group_policy=allowlist) |
-| `groups` | `{}` | Per-group configuration (see below) |
-| `stream_keepalive_enabled` | `false` | Send periodic keepalive frames to refresh WeCom's ~6-minute reply-stream window on long turns |
-| `stream_keepalive_interval_seconds` | `120` | Keepalive frame cadence when enabled |
-| `stream_safe_duration_seconds` | `330` | Stream age after which finalize prefers the reliable proactive send |
-## Access Policies
-### DM Policy
-Controls who can send direct messages to the bot:
-| Value | Behavior |
-|-------|----------|
-| `open` | Anyone can DM the bot (default) |
-| `allowlist` | Only user IDs in `allow_from` can DM |
-| `disabled` | All DMs are ignored |
-| `pairing` | Pairing mode (for initial setup) |
-```bash
-WECOM_DM_POLICY=allowlist
-```
-### Group Policy
-Controls which groups the bot responds in:
-| Value | Behavior |
-|-------|----------|
-| `open` | Bot responds in all groups (default) |
-| `allowlist` | Bot only responds in group IDs listed in `group_allow_from` |
-| `disabled` | All group messages are ignored |
-```bash
-WECOM_GROUP_POLICY=allowlist
-```
-### Per-Group Sender Allowlists
-For fine-grained control, you can restrict which users are allowed to interact with the bot within specific groups. This is configured in `config.yaml`:
-```yaml
-platforms:
-  wecom:
-    enabled: true
-    extra:
-      bot_id: "your-bot-id"
-      secret: "your-secret"
-      group_policy: "allowlist"
-      group_allow_from:
-        - "group_id_1"
-        - "group_id_2"
-      groups:
-        group_id_1:
-          allow_from:
-            - "user_alice"
-            - "user_bob"
-        group_id_2:
-          allow_from:
-            - "user_charlie"
-        "*":
-          allow_from:
-            - "user_admin"
-```
-**How it works:**
-1. The `group_policy` and `group_allow_from` controls determine whether a group is allowed at all.
-2. If a group passes the top-level check, the `groups.<group_id>.allow_from` list (if present) further restricts which senders within that group can interact with the bot.
-3. A wildcard `"*"` group entry serves as a default for groups not explicitly listed.
-4. Allowlist entries support the `*` wildcard to allow all users, and entries are case-insensitive.
-5. Entries can optionally use the `wecom:user:` or `wecom:group:` prefix format — the prefix is stripped automatically.
-If no `allow_from` is configured for a group, all users in that group are allowed (assuming the group itself passes the top-level policy check).
-## Media Support
-### Inbound (receiving)
-The adapter receives media attachments from users and caches them locally for agent processing:
-| Type | How it's handled |
-|------|-----------------|
-| **Images** | Downloaded and cached locally. Supports both URL-based and base64-encoded images. |
-| **Files** | Downloaded and cached. Filename is preserved from the original message. |
-| **Voice** | Voice message text transcription is extracted if available. |
-| **Mixed messages** | WeCom mixed-type messages (text + images) are parsed and all components extracted. |
-**Quoted messages:** Media from quoted (replied-to) messages is also extracted, so the agent has context about what the user is replying to.
-### AES-Encrypted Media Decryption
-WeCom encrypts some inbound media attachments with AES-256-CBC. The adapter handles this automatically:
-- When an inbound media item includes an `aeskey` field, the adapter downloads the encrypted bytes and decrypts them using AES-256-CBC with PKCS#7 padding.
-- The AES key is the base64-decoded value of the `aeskey` field (must be exactly 32 bytes).
-- The IV is derived from the first 16 bytes of the key.
-- This requires the `cryptography` Python package (`pip install cryptography`).
-No configuration is needed — decryption happens transparently when encrypted media is received.
-### Outbound (sending)
-| Method | What it sends | Size limit |
-|--------|--------------|------------|
-| `send` | Markdown text messages | 4000 chars |
-| `send_image` / `send_image_file` | Native image messages | 10 MB |
-| `send_document` | File attachments | 20 MB |
-| `send_voice` | Voice messages (AMR format only for native voice) | 2 MB |
-| `send_video` | Video messages | 10 MB |
-**Chunked upload:** Files are uploaded in 512 KB chunks through a three-step protocol (init → chunks → finish). The adapter handles this automatically.
-**Automatic downgrade:** When media exceeds the native type's size limit but is under the absolute 20 MB file limit, it is automatically sent as a generic file attachment instead:
-- Images > 10 MB → sent as file
-- Videos > 10 MB → sent as file
-- Voice > 2 MB → sent as file
-- Non-AMR audio → sent as file (WeCom only supports AMR for native voice)
-Files exceeding the absolute 20 MB limit are rejected with an informational message sent to the chat.
-## Reply-Mode Responses
-When the bot receives a message via the WeCom callback, the adapter remembers the inbound request ID. If a response is sent while the request context is still active, the adapter uses WeCom's reply-mode (`aibot_respond_msg`) to correlate the response directly to the inbound message. This provides a more natural conversation experience in the WeCom client.
-When a native reply stream is active, the response streams incrementally through reply-mode `msgtype: "stream"` frames. If the inbound request context has expired or is unavailable (or a stream frame fails), the adapter falls back to proactive message sending via `aibot_send_msg`.
-Reply-mode also works for media: uploaded media can be sent as a reply to the originating message.
-## Connection and Reconnection
-The adapter maintains a persistent WebSocket connection to WeCom's gateway at `wss://openws.work.weixin.qq.com`.
-### Connection Lifecycle
-1. **Connect:** Opens a WebSocket connection and sends an `aibot_subscribe` authentication frame with the bot_id and secret.
-2. **Heartbeat:** Sends application-level ping frames every 30 seconds to keep the connection alive.
-3. **Listen:** Continuously reads inbound frames and dispatches message callbacks.
-### Reconnection Behavior
-On connection loss, the adapter uses exponential backoff to reconnect:
-| Attempt | Delay |
-|---------|-------|
-| 1st retry | 2 seconds |
-| 2nd retry | 5 seconds |
-| 3rd retry | 10 seconds |
-| 4th retry | 30 seconds |
-| 5th+ retry | 60 seconds |
-After each successful reconnection, the backoff counter resets to zero. All pending request futures are failed on disconnect so callers don't hang indefinitely.
-### Deduplication
-Inbound messages are deduplicated using message IDs with a 5-minute window and a maximum cache of 1000 entries. This prevents double-processing of messages during reconnection or network hiccups.
-## All Environment Variables
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `WECOM_BOT_ID` | ✅ | — | WeCom AI Bot ID |
-| `WECOM_SECRET` | ✅ | — | WeCom AI Bot Secret |
-| `WECOM_ALLOWED_USERS` | — | _(empty)_ | Comma-separated user IDs for the gateway-level allowlist |
-| `WECOM_HOME_CHANNEL` | — | — | Chat ID for cron/notification output |
-| `WECOM_WEBSOCKET_URL` | — | `wss://openws.work.weixin.qq.com` | WebSocket gateway URL |
-| `WECOM_DM_POLICY` | — | `open` | DM access policy |
-| `WECOM_GROUP_POLICY` | — | `open` | Group access policy |
-## Troubleshooting
-| Problem | Fix |
-|---------|-----|
-| `WECOM_BOT_ID and WECOM_SECRET are required` | Set both env vars or configure in setup wizard |
-| `WeCom startup failed: aiohttp not installed` | Install aiohttp: `pip install aiohttp` |
-| `WeCom startup failed: httpx not installed` | Install httpx: `pip install httpx` |
-| `invalid secret (errcode=40013)` | Verify the secret matches your bot's credentials |
-| `Timed out waiting for subscribe acknowledgement` | Check network connectivity to `openws.work.weixin.qq.com` |
-| Bot doesn't respond in groups | Check `group_policy` setting and ensure the group ID is in `group_allow_from` |
-| Bot ignores certain users in a group | Check per-group `allow_from` lists in the `groups` config section |
-| Media decryption fails | Install `cryptography`: `pip install cryptography` |
-| `cryptography is required for WeCom media decryption` | The inbound media is AES-encrypted. Install: `pip install cryptography` |
-| Voice messages sent as files | WeCom only supports AMR format for native voice. Other formats are auto-downgraded to file. |
-| `File too large` error | WeCom has a 20 MB absolute limit on all file uploads. Compress or split the file. |
-| Images sent as files | Images > 10 MB exceed the native image limit and are auto-downgraded to file attachments. |
-| `Timeout sending message to WeCom` | The WebSocket may have disconnected. Check logs for reconnection messages. |
-| `WeCom websocket closed during authentication` | Network issue or incorrect credentials. Verify bot_id and secret. |