hermes-wpsxiezuo 0.8.2

WPSXiezuo (WPS协作) platform adapter for Hermes Agent

WPSXiezuo (WPS协作) Platform Adapter for Hermes Agent

This is a WPSXiezuo messaging platform adapter for Hermes Agent. It enables bidirectional messaging between Hermes Agent and WPS协作 (via the WPS Open Platform).

Gateway setup（用户指南）：docs/user-guide/messaging/wpsxiezuo.md（WebSocket、环境变量、排错等）。

Features

• Inbound Messages: Receive and process messages from WPS协作 via WebSocket long-connection (HTTP Webhook 暂时移除，后续版本恢复)
• Outbound Messages: Send messages to WPS协作 chats
• Encryption Support: AES-256-CBC decryption for incoming event payloads
• WPS3 Authentication: Proper request signing with AppId + AppKey
• Group Chat Support: @mention handling in group conversations
• Message Types: Text, rich text, images, and files

Prerequisites

1. Hermes Agent >= 0.12.0 — Installed and on your PATH as the hermes CLI (platform plugin support). Tested with Hermes 0.14.0. See Hermes Agent for installation; you do not need to clone the Hermes source repository to use this adapter.
2. WPS Open Platform account — Register at https://open.wps.cn/ and create an application
3. Python — 3.9+; runtime dependencies (pycryptodome, aiohttp) are installed automatically with pip install hermes-wpsxiezuo

Compatibility matrix: .hermes-compat.json.

Install from PyPI (recommended)

Official package name: hermes-wpsxiezuo — https://pypi.org/project/hermes-wpsxiezuo/

# 1. Install package (dependencies included)
pip install hermes-wpsxiezuo

# 2. Deploy plugin to ~/.hermes/plugins/
hermes-wpsxiezuo install --enable

# 3. Configure via Hermes CLI
hermes gateway setup   # choose "WPSXiezuo (WPS协作)"

# 4. Start gateway
hermes gateway run

From a source checkout:

pip install .
hermes-wpsxiezuo install --enable
hermes gateway setup
hermes gateway run

Maintainers — publishing: MR/主干 CI 自动跑 ./scripts/publish.sh --dry（含 pip-audit）；发版打 v*.*.* tag 后在 GitLab 手动跑 publish:pypi（PyPI Trusted Publishing）。详见 docs/publishing.md。

WPS Open Platform

1. Go to https://open.wps.cn/
2. Open your application → Event Subscription
3. Enable kso.app_chat.message (message events)
4. The adapter uses WebSocket long-connection — no public callback URL required

Env var reference: docs/user-guide/messaging/wpsxiezuo.md.

Alternative: install.sh

If you prefer a shell-based install from a git checkout (symlink into ~/.hermes/plugins/):

./install.sh --enable --env-template
pip install pycryptodome aiohttp   # only if not using pip install hermes-wpsxiezuo
hermes gateway setup
hermes gateway run

No changes to the Hermes source tree are required. The plugin registers via ctx.register_platform(); Hermes platform_registry handles adapter creation, auth, cron delivery, toolsets, and setup wizard integration.

Repository layout

Path	Description
docs/user-guide/messaging/wpsxiezuo.md	Gateway 接入说明（用户指南）
plugins/platforms/wpsxiezuo/	Platform plugin（plugin.yaml + adapter.py + register()）
src/wpsxiezuo.py	Deprecated shim — re-exports plugin adapter
tools/test_sign.py / tools/debug_crypto.py	本地签名/解密调试（仅读环境变量）
pyproject.toml	打包元数据；pip install . / PyPI hermes-wpsxiezuo
scripts/publish.sh	发布门禁（--dry）与上传（--ci / 交互）
docs/publishing.md	CI、Trusted Publishing、发版步骤
.gitlab-ci.yml	测试、release:check、PyPI 发布 job
scripts/install.sh	Shell 安装备选（./install.sh 为薄包装）
scripts/rollback.sh	卸载已安装的插件
.env.example	环境变量模板（勿提交含真实密钥的文件）

Hermes integration

This adapter ships as a platform plugin under plugins/platforms/wpsxiezuo/. Hermes >= 0.12 discovers it via PluginManager and ctx.register_platform() — no edits to gateway/run.py, toolsets.py, cron/scheduler.py, etc.

See Hermes: adding platform adapters (plugin path).

Testing

Use tools/test_sign.py / tools/debug_crypto.py for local signing and decryption debugging. Do not put credentials in source — use environment variables (same names as Hermes / .env.example):

export WPSXIEZUO_APP_ID="your-app-id"
export WPSXIEZUO_APP_KEY="your-app-key"

python3 tools/test_sign.py

Troubleshooting

Issue: "pycryptodome is required for WPSXiezuo decryption"

Solution:

pip install hermes-wpsxiezuo
# or: pip install pycryptodome

Issue: Cannot decrypt event payload

Solution: The decryption key is derived from MD5(APP_KEY).hexdigest(). Ensure your WPSXIEZUO_APP_KEY is correct (same field as OAuth client_secret and KSO-1).

Issue: Adapter not loading

Solution: Check Hermes Agent logs for import errors:

hermes gateway 2>&1 | grep -i wpsxiezuo

Ensure the plugin is installed and enabled:

hermes-wpsxiezuo install --enable
hermes plugins list

Issue: failed to obtain access_token with nodename nor servname provided, or not known

This is DNS resolution failure for the configured API host (default openapi.wps.cn), not SSL: the machine running hermes gateway cannot resolve that hostname (offline network, corporate DNS, or container without DNS).

1. From the same host, run ping / nslookup against the host in your WPSXIEZUO_API_BASE (or the default openapi.wps.cn) and fix network/DNS until it resolves.
2. WPSXIEZUO_API_BASE must match the REST/OAuth base URL shown in the WPS Open Platform console or official docs for your app. If you point at the wrong host, OAuth may return invalid_client / client ... not exists even when WPSXIEZUO_APP_KEY is correct.
3. After changing env vars, restart hermes gateway run.

Run tools/test_sign.py with the same WPSXIEZUO_API_BASE as Hermes to verify token on the same machine.

Rollback

Remove the plugin from Hermes home:

./scripts/rollback.sh --plugin-only

Security notes

Credentials and PyPI package contents

1. Never commit secrets — Do not commit .env, .env.wpsxiezuo, or any file with real WPSXIEZUO_APP_* values. Debug scripts read credentials only from the environment.
2. Official PyPI name — Install only hermes-wpsxiezuo from https://pypi.org/project/hermes-wpsxiezuo/ (avoid similarly named third-party packages).
3. What ships on PyPI — The published wheel contains only the plugin Python modules and plugin.yaml; it does not include tests, tools, .env files, or repository scripts. No AppId/AppKey are embedded in the package.
4. Runtime injection — Credentials are loaded at runtime from environment variables or Hermes gateway config (hermes gateway setup); the adapter does not write secrets to disk.

Protocol and operations

5. KSO-1 signing — WebSocket handshake and selected v7 APIs use KSO-1 HMAC-SHA256; WPSXIEZUO_APP_KEY is the platform AppKey (also used for OAuth and inbound AES decryption per WPS spec).
6. Logging — Message and chat IDs are partially redacted in logs; avoid enabling verbose logging that prints full OAuth error bodies in production.
7. Outbound media URLs — When sending images/videos/files via http(s):// URLs, the adapter downloads from that URL server-side. Only pass URLs you trust (e.g. WPS-signed download links), especially if the Agent can supply arbitrary URLs.
8. Temp files — Downloads are stored under the system temp directory (wpsxiezuo_downloads); ensure appropriate filesystem permissions on shared hosts.

Publishing (maintainers)

• Always run ./scripts/publish.sh --dry before any upload (also enforced in GitLab release:check).
• Prefer Trusted Publishing via .gitlab-ci.yml (publish:pypi); see docs/publishing.md.
• Keep pyproject.toml and plugins/platforms/wpsxiezuo/__init__.py versions in sync; tag as vX.Y.Z to trigger release jobs.

License

This adapter follows the same license as Hermes Agent (MIT).

Support

For issues related to:

• This adapter: See docs/user-guide/messaging/wpsxiezuo.md and troubleshooting above
• Hermes Agent: https://github.com/NousResearch/hermes-agent/issues
• WPS Open Platform: https://open.wps.cn/ documentation