Metadata-Version: 2.4
Name: hermes-wpsxiezuo
Version: 0.8.2
Summary: WPSXiezuo (WPS协作) platform adapter for Hermes Agent
Author: Kingsoft
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pycryptodome<4,>=3.20.0
Requires-Dist: aiohttp<4,>=3.14.0; python_version >= "3.10"
Requires-Dist: aiohttp<3.14,>=3.9.0; python_version < "3.10"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: publish
Requires-Dist: build>=1.0; extra == "publish"
Requires-Dist: twine>=5.0; extra == "publish"
Requires-Dist: pip-audit>=2.7; extra == "publish"

# WPSXiezuo (WPS协作) Platform Adapter for Hermes Agent

This is a WPSXiezuo messaging platform adapter for [Hermes Agent](https://github.com/NousResearch/hermes-agent). It enables bidirectional messaging between Hermes Agent and **WPS协作** (via the WPS Open Platform).

**Gateway setup（用户指南）**：[docs/user-guide/messaging/wpsxiezuo.md](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](https://github.com/NousResearch/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`](.hermes-compat.json).

## Install from PyPI (recommended)

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

```bash
# 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:

```bash
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](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](docs/user-guide/messaging/wpsxiezuo.md).

## Alternative: install.sh

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

```bash
./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)](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/developer-guide/adding-platform-adapters.md).

## 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`):

```bash
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:**
```bash
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:
```bash
hermes gateway 2>&1 | grep -i wpsxiezuo
```

Ensure the plugin is installed and enabled:
```bash
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:

```bash
./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](https://docs.pypi.org/trusted-publishers/) via `.gitlab-ci.yml` (`publish:pypi`); see [docs/publishing.md](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](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
