@wps365/openclaw-wpsxiezuo 1.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 WPS Xiezuo Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,335 @@
+# @wps365/openclaw-wpsxiezuo
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
+
+> 中文文档：[README_ZH-CN.md](README_ZH-CN.md)
+
+An [OpenClaw](https://openclaw.dev) native plugin that connects your AI agent to the **WPS Open Platform enterprise robot** — enabling AI-powered conversations in WPS group chats and direct messages.
+
+> This is an **OpenClaw plugin**. Install [OpenClaw](https://openclaw.dev) first, then use this package to add the WPS channel.
+
+---
+
+## Features
+
+- **Native integration** — follows the OpenClaw plugin spec; automatically hooks into `register` / `gateway.startAccount` lifecycle
+- **Full WPS platform support** — enterprise robot Webhook / WebSocket dual-channel + full `openapi.wps.cn` OAPI coverage
+- **Event-driven** — handles messages, files, @mentions, image attachment pre-fetch, and automatic OAuth token refresh
+- **Smart sessions** — WPS ↔ OpenClaw session mapping, deduplication & idempotency, cross-turn context retention
+- **Image understanding** — integrates with OpenClaw `tools.media.image` (host selects the model; plugin handles attachment download)
+- **Cross-platform install** — a single `npx` command handles registration, config injection, and plugin allowlisting
+
+---
+
+## Architecture
+
+```
+WPS Open Platform ──► This plugin (Webhook / WebSocket)
+                         │   Decrypt + verify signature + idempotency
+                         │   Session mapping + media pre-fetch
+                         ▼
+                       OpenClaw channelRuntime
+                         │   Route agent + orchestrate reply
+                         ▼
+                     OpenClaw Agent (your AI)
+                         │   Reply text / call tools
+                         ▼
+                       This plugin outbound ──► WPS Open Platform
+```
+
+---
+
+## Requirements
+
+| Item | Version |
+|------|---------|
+| Node.js | >= 22 (24 LTS recommended) |
+| pnpm | >= 10 (dev only, not needed for end users) |
+| OpenClaw CLI | >= 2026.3.28 |
+| WPS Open Platform | App ID + App Secret |
+
+---
+
+## Quick Start
+
+### Option 1: Install via npm (recommended)
+
+```bash
+# 1. Install OpenClaw (skip if already installed)
+npm install -g openclaw
+
+# 2. Run the built-in CLI with npx
+npx -y @wps365/openclaw-wpsxiezuo install
+```
+
+The CLI automatically:
+
+1. Checks that the OpenClaw CLI is available
+2. Prompts for `APP_ID` / `APP_SECRET` interactively
+3. Removes stale `wps` / `wps-xiezuo` config remnants
+4. Registers this npm package as an OpenClaw plugin
+5. Writes `channels.wps-xiezuo` / `plugins.allow` / `bindings` into `~/.openclaw/openclaw.json`
+6. Verifies the installation result
+
+**Unattended / CI mode:**
+
+```bash
+# Pass as flags
+npx -y @wps365/openclaw-wpsxiezuo install --app-id <ID> --app-secret <SECRET> --yes
+
+# Or via environment variables
+WPS_APP_ID=xxx WPS_APP_SECRET=yyy \
+  npx -y @wps365/openclaw-wpsxiezuo install --yes
+```
+
+**Upgrade / Update:**
+
+```bash
+# Upgrade to latest version
+npx -y @wps365/openclaw-wpsxiezuo@latest install --yes
+
+# Or reinstall (install command cleans old config first)
+npx -y @wps365/openclaw-wpsxiezuo install --yes
+```
+
+**Install a specific version:**
+
+```bash
+# Install version 1.6.0
+npx -y @wps365/openclaw-wpsxiezuo@1.6.0 install --yes
+
+# Install version 1.5.0
+npx -y @wps365/openclaw-wpsxiezuo@1.5.0 install --yes
+```
+
+**Uninstall:**
+
+```bash
+npx -y @wps365/openclaw-wpsxiezuo uninstall
+```
+
+After installation, **restart the OpenClaw gateway** and @ the bot in WPS to start chatting:
+
+```bash
+openclaw gateway restart   # or: openclaw serve
+```
+
+> Works on macOS, Linux, and Windows. The CLI is pure Node.js — no bash dependency.
+
+### Option 2: Offline bundle (air-gapped / no npm access)
+
+```bash
+# 1. Download openclaw-wps-xiezuo-bundle-vX.Y.Z.zip from the releases page
+unzip openclaw-wps-xiezuo-bundle-vX.Y.Z.zip
+cd openclaw-wps-xiezuo-bundle
+
+# 2. Edit config/plugin.env with your APP_ID / APP_SECRET
+$EDITOR config/plugin.env
+
+# 3. Install (macOS / Linux)
+bash scripts/install.sh
+```
+
+The offline bundle ships with a `.tgz` identical to the npm public package.
+
+---
+
+## Configuration
+
+### Channel config
+
+The plugin reads `channels.wps-xiezuo` from `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "channels": {
+    "wps-xiezuo": {
+      "enabled": true,
+      "appId": "YOUR_APP_ID",
+      "appSecret": "YOUR_APP_SECRET",
+      "baseUrl": "https://openapi.wps.cn",
+      "dmPolicy": "open",
+      "groupPolicy": "open",
+      "requireMention": true,
+      "instantAck": {
+        "enabled": true,
+        "text": "Processing, please wait..."
+      }
+    }
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `appId` / `appSecret` | WPS Open Platform app credentials (required) |
+| `baseUrl` | OAPI base URL, default `https://openapi.wps.cn` |
+| `dmPolicy` | Direct-message policy: `open` / `pairing` / `allowlist` |
+| `groupPolicy` | Group-chat policy: `open` / `allowlist` |
+| `requireMention` | Whether the bot must be @mentioned in group chats |
+| `instantAck` | Immediate acknowledgement message (prevents perceived timeout) |
+
+Full schema: [`openclaw.plugin.json`](openclaw.plugin.json) → `channelConfigs.wps-xiezuo.schema`.
+
+### Custom AI gateway
+
+This plugin is **model-agnostic** — the model is controlled by the OpenClaw host's `models.providers`. Example:
+
+```json
+{
+  "models": {
+    "mode": "merge",
+    "providers": {
+      "my-provider": {
+        "baseUrl": "<your gateway URL>",
+        "apiKey": "<your key>",
+        "api": "openai-completions"
+      }
+    }
+  },
+  "agents": {
+    "defaults": { "model": { "primary": "my-provider/<model-id>" } }
+  }
+}
+```
+
+Merge this into `~/.openclaw/openclaw.json`.
+
+### Image understanding (inbound image attachments)
+
+The plugin downloads WPS cloud attachments to local disk and exposes `MediaPath` / `MediaPaths` / `MediaType` / `MediaTypes` on the inbound context. The actual image understanding capability is provided by the OpenClaw host's `tools.media.image`; the model / gateway choice is up to the deployer.
+
+To enable image understanding, three conditions must be met in `openclaw.json`:
+
+```json
+{
+  "models": {
+    "providers": {
+      "<your-provider>": {
+        "models": [
+          { "id": "<model-id>", "input": ["text", "image"] }
+        ]
+      }
+    }
+  },
+  "agents": {
+    "defaults": { "model": "<your-provider>/<model-id>" }
+  },
+  "tools": {
+    "media": {
+      "image": {
+        "enabled": true,
+        "models": [
+          { "provider": "<your-provider>", "model": "<vision-model-id>" }
+        ]
+      }
+    }
+  }
+}
+```
+
+- `input: ["text", "image"]` tells the host that the provider supports image input
+- `tools.media.image.enabled` defaults to `false`; must be explicitly set to `true`
+- `tools.media.image.models[]` can specify a lightweight vision model; omit to use the agent default
+
+For details on image-native multimodal pass-through vs. `[Image]` description block, see the OpenClaw docs: `nodes/media-understanding`.
+
+**Common issues:**
+- Bot replies "no image found" → check `tools.media.image.enabled` and the provider's `input` declaration
+- New image receives old answer → session cross-contamination; clear `~/.openclaw/agents/<id>/sessions/sessions.json`
+
+---
+
+## Usage
+
+### Start and verify
+
+```bash
+openclaw gateway start                         # Start the gateway
+openclaw gateway logs                          # View logs
+openclaw plugins list                          # List installed plugins
+openclaw config get channels.wps-xiezuo        # Inspect WPS channel config
+openclaw doctor                                # Health check
+```
+
+### Upgrade and uninstall
+
+```bash
+# Upgrade (npm)
+npx -y @wps365/openclaw-wpsxiezuo install --yes   # Overwrites with latest
+
+# Uninstall (npm)
+npx -y @wps365/openclaw-wpsxiezuo uninstall
+
+# Uninstall (offline bundle)
+cd openclaw-wps-xiezuo-bundle && bash scripts/uninstall.sh
+```
+
+---
+
+## Troubleshooting
+
+**1. Plugin not loaded after install**
+
+```bash
+openclaw gateway restart
+ls ~/.openclaw/extensions/wps-xiezuo    # Confirm the plugin directory exists
+```
+
+**2. Channel config not taking effect**
+
+```bash
+openclaw config get channels.wps-xiezuo
+openclaw doctor --fix
+```
+
+**3. Tool call rejected**
+
+```bash
+openclaw config get tools.allow
+openclaw config set tools.allow '["wps_im_message_send"]'
+```
+
+**4. View logs**
+
+```bash
+openclaw gateway logs                               # Gateway log
+tail -f ~/.openclaw/logs/plugins/wps-xiezuo.log     # Plugin log
+```
+
+---
+
+## Compatibility
+
+| Item | Support |
+|------|---------|
+| OpenClaw | Stable channel, `>= 2026.3.28` |
+| Node.js | 22 LTS, 24 (recommended) |
+| OS | macOS, Linux, Windows (WSL recommended) |
+
+---
+
+## Contributors
+
+- [@wangdong](https://github.com/wangdong)
+- [@hezhijian](https://github.com/hezhijian-wps)
+- [@liuxin21](https://github.com/kso-lx21)
+- [@huangluyang](https://www.npmjs.com/~lukeqqi)
+- [@duwei1](https://github.com/duwei1)
+- [@wangzhengrui](https://github.com/wangzhengrui)
+- [@liuzhifei](https://github.com/dacuotecuo)
+- [@chensi](https://github.com/chensi06lj)
+- [@zhangyong](https://github.com/ZhYong10)
+
+---
+
+## License
+
+[MIT License](LICENSE)
+
+## Acknowledgements
+
+- [OpenClaw](https://openclaw.dev) — AI agent framework
+- [WPS Open Platform](https://open.wps.cn) — Enterprise collaboration platform
+- [TypeScript](https://www.typescriptlang.org/) — Type-safe JavaScript

package/README_ZH-CN.md

@@ -0,0 +1,318 @@
+# @wps365/openclaw-wpsxiezuo
+
+[License: MIT](https://opensource.org/licenses/MIT)
+[Node](https://nodejs.org/)
+
+> English version: [README.md](../blob/main/README.md)
+
+WPS 协作 Openclaw 原生插件——把 OpenClaw AI agent 接入 WPS 开放平台企业机器人，实现群聊 / 私聊中的 AI 对话与自动化。
+
+> 本项目是一个 **OpenClaw 插件**。先安装 [OpenClaw](https://openclaw.dev)，再通过本包把 WPS 通道接入其中。
+
+## 功能特性
+
+- **原生集成**：遵循 OpenClaw 插件规范，在 `register` / `gateway.startAccount` 生命周期里自动接管 WPS 通道
+- **WPS 平台完整对接**：企业机器人 Webhook / WebSocket 双通道 + `openapi.wps.cn` 全量 OAPI
+- **事件驱动**：消息、文件、@ 提及、图片附件预取、OAuth token 自动刷新
+- **智能会话**：WPS 会话与 OpenClaw 会话映射、去重幂等、跨轮上下文保持
+- **图片识别**：与 OpenClaw `tools.media.image` 联动（宿主选模型，插件负责附件下载）
+- **跨平台安装**：一条 `npx` 命令完成注册、配置注入、插件白名单
+
+## 架构速览
+
+```
+WPS 开放平台 ──► 本插件（webhook/WebSocket）
+                  │   解密 + 验签 + 幂等
+                  │   会话映射 + 媒体预取
+                  ▼
+                OpenClaw channelRuntime
+                  │   路由 agent + 编排回复
+                  ▼
+              OpenClaw Agent（你的 AI）
+                  │   回复文本 / 调用工具
+                  ▼
+                本插件 outbound ──► WPS 开放平台
+```
+
+## 环境要求
+
+- Node.js **>= 22**（推荐 24 LTS）
+- pnpm **>= 10**（仅本地开发需要，用户安装无需）
+- OpenClaw CLI **>= 2026.3.28**
+- WPS 开放平台应用的 `App ID` 与 `App Secret`
+
+## 快速开始
+
+### 方式一：通过 npm 一键安装（推荐）
+
+```bash
+# 1. 安装 OpenClaw（已装过可跳过）
+npm install -g openclaw
+
+# 2. 用 npx 运行本包内置的 CLI
+npx -y @wps365/openclaw-wpsxiezuo install
+```
+
+CLI 会自动完成：
+
+1. 检查 OpenClaw CLI 是否可用
+2. 交互式输入 `APP_ID` / `APP_SECRET`
+3. 清理旧的 `wps` / `wps-xiezuo` 残留配置
+4. 将本 npm 包作为插件注册到 OpenClaw
+5. 写入 `~/.openclaw/openclaw.json` 的 `channels.wps-xiezuo` / `plugins.allow` / `bindings`
+6. 验证安装结果
+
+无人值守/CI 场景：
+
+```bash
+# 参数方式
+npx -y @wps365/openclaw-wpsxiezuo install --app-id <ID> --app-secret <SECRET> --yes
+
+# 环境变量方式
+WPS_APP_ID=xxx WPS_APP_SECRET=yyy \
+  npx -y @wps365/openclaw-wpsxiezuo install --yes
+```
+
+**升级 / 更新：**
+
+```bash
+# 升级到最新版本
+npx -y @wps365/openclaw-wpsxiezuo@latest install --yes
+
+# 或重新安装（install 命令会先清理旧配置）
+npx -y @wps365/openclaw-wpsxiezuo install --yes
+```
+
+**安装指定版本：**
+
+```bash
+# 安装 1.6.0 版本
+npx -y @wps365/openclaw-wpsxiezuo@1.6.0 install --yes
+
+# 安装 1.5.0 版本
+npx -y @wps365/openclaw-wpsxiezuo@1.5.0 install --yes
+```
+
+**卸载：**
+
+```bash
+npx -y @wps365/openclaw-wpsxiezuo uninstall
+```
+
+安装完成后**手动重启 OpenClaw gateway** 即可在 WPS 客户端 @ 机器人对话：
+
+```bash
+openclaw gateway restart   # 或：openclaw serve
+```
+
+> 全平台支持（macOS / Linux / Windows）。CLI 纯 Node.js 实现，不依赖 bash。
+
+### 方式二：离线 bundle 安装（内网/无 npm 环境）
+
+```bash
+# 1. 从发布页获取 openclaw-wps-xiezuo-bundle-vX.Y.Z.zip
+unzip openclaw-wps-xiezuo-bundle-vX.Y.Z.zip
+cd openclaw-wps-xiezuo-bundle
+
+# 2. 编辑 config/plugin.env，填写 APP_ID / APP_SECRET
+$EDITOR config/plugin.env
+
+# 3. 安装（macOS / Linux）
+bash scripts/install.sh
+```
+
+离线 bundle 内置 `.tgz` 与 npm 公网包同名同内容。
+
+## 配置说明
+
+### Channel 配置
+
+插件读取 `~/.openclaw/openclaw.json` 中的 `channels.wps-xiezuo`：
+
+```json
+{
+  "channels": {
+    "wps-xiezuo": {
+      "enabled": true,
+      "appId": "YOUR_APP_ID",
+      "appSecret": "YOUR_APP_SECRET",
+      "baseUrl": "https://openapi.wps.cn",
+      "dmPolicy": "open",
+      "groupPolicy": "open",
+      "requireMention": true,
+      "instantAck": {
+        "enabled": true,
+        "text": "内容处理中，请稍候..."
+      }
+    }
+  }
+}
+```
+
+
+| 字段                    | 说明                                    |
+| --------------------- | ------------------------------------- |
+| `appId` / `appSecret` | WPS 开放平台应用凭据（必填）                      |
+| `baseUrl`             | OAPI 基础地址，默认 `https://openapi.wps.cn` |
+| `dmPolicy`            | 私聊策略：`open` / `pairing` / `allowlist` |
+| `groupPolicy`         | 群聊策略：`open` / `allowlist`             |
+| `requireMention`      | 群聊是否需要 @机器人才响应                        |
+| `instantAck`          | 即时确认消息（避免长时间无响应感知）                    |
+
+
+完整 schema 见 [openclaw.plugin.json](openclaw.plugin.json) 中的 `channelConfigs.wps-xiezuo.schema`。
+
+### 自定义 AI 网关
+
+本插件**不绑定特定模型**——模型由 OpenClaw 宿主的 `models.providers` 决定。常见做法：
+
+```json
+{
+  "models": {
+    "mode": "merge",
+    "providers": {
+      "my-provider": {
+        "baseUrl": "<你的网关地址>",
+        "apiKey": "<你的 key>",
+        "api": "openai-completions"
+      }
+    }
+  },
+  "agents": {
+    "defaults": { "model": { "primary": "my-provider/<model-id>" } }
+  }
+}
+```
+
+合并进 `~/.openclaw/openclaw.json` 即可。
+
+### 图片识别（入站图片附件）
+
+插件只负责把 WPS 云端附件**下载到本地**并在入站 ctx 暴露 `MediaPath` / `MediaPaths` / `MediaType` / `MediaTypes`。识图能力由 OpenClaw 宿主的 `tools.media.image` 提供，模型/网关选择由部署方配置。
+
+要启用图片识别，`openclaw.json` 需同时满足三点：
+
+```json
+{
+  "models": {
+    "providers": {
+      "<your-provider>": {
+        "models": [
+          { "id": "<model-id>", "input": ["text", "image"] }
+        ]
+      }
+    }
+  },
+  "agents": {
+    "defaults": { "model": "<your-provider>/<model-id>" }
+  },
+  "tools": {
+    "media": {
+      "image": {
+        "enabled": true,
+        "models": [
+          { "provider": "<your-provider>", "model": "<vision-model-id>" }
+        ]
+      }
+    }
+  }
+}
+```
+
+- `input: ["text", "image"]` 让宿主识别该 provider 具备图像能力
+- `tools.media.image.enabled` 默认关闭，必须显式 `true`
+- `tools.media.image.models[]` 可另行指定轻量识图模型；省略时用 agent 默认
+
+详细识图行为（image-native 直传 multimodal vs 生成 `[Image]` 描述块）见 OpenClaw 官方文档 `nodes/media-understanding`。
+
+**常见故障：**
+
+- 机器人回"没看到图" → 检查 `tools.media.image.enabled` 与 provider 的 `input` 声明
+- 新图被旧答案回复 → session 串线，清理 `~/.openclaw/agents/<id>/sessions/sessions.json` 索引
+
+## 使用说明
+
+### 启动与验证
+
+```bash
+openclaw gateway start                         # 启动网关
+openclaw gateway logs                          # 查看日志
+openclaw plugins list                          # 查看已安装插件
+openclaw config get channels.wps-xiezuo        # 查看 WPS 通道配置
+openclaw doctor                                # 健康检查
+```
+
+### 升级与卸载
+
+```bash
+# 升级（npm 方式）
+npx -y @wps365/openclaw-wpsxiezuo install --yes   # 会覆盖安装最新版
+
+# 卸载（npm 方式）
+npx -y @wps365/openclaw-wpsxiezuo uninstall
+
+# 卸载（离线 bundle 方式）
+cd openclaw-wps-xiezuo-bundle && bash scripts/uninstall.sh
+```
+
+## 故障排查
+
+**1. 安装后插件未加载**
+
+```bash
+openclaw gateway restart
+ls ~/.openclaw/extensions/wps-xiezuo    # 确认插件目录存在
+```
+
+**2. Channel 配置未生效**
+
+```bash
+openclaw config get channels.wps-xiezuo
+openclaw doctor --fix
+```
+
+**3. 工具调用被拒绝**
+
+```bash
+openclaw config get tools.allow
+openclaw config set tools.allow '["wps_im_message_send"]'
+```
+
+**4. 查日志**
+
+```bash
+openclaw gateway logs                               # 网关日志
+tail -f ~/.openclaw/logs/plugins/wps-xiezuo.log     # 插件日志
+```
+
+## 兼容性
+
+
+| 项        | 支持                                 |
+| -------- | ---------------------------------- |
+| OpenClaw | 稳定版（Stable channel），`>= 2026.3.28` |
+| Node.js  | 22 LTS，24（推荐）                      |
+| 操作系统     | macOS、Linux、Windows（WSL 推荐）        |
+
+
+## 贡献者
+- [@wangdong](https://github.com/wangdong)
+- [@hezhijian](https://github.com/hezhijian-wps)
+- [@liuxin21](https://github.com/kso-lx21)
+- [@huangluyang](https://www.npmjs.com/~lukeqqi)
+- [@duwei1](https://github.com/duwei1)
+- [@wangzhengrui](https://github.com/wangzhengrui)
+- [@liuzhifei](https://github.com/dacuotecuo)
+- [@chensi](https://github.com/chensi06lj)
+- [@zhangyong](https://github.com/ZhYong10)
+
+## 许可证
+
+MIT License - 详见 [LICENSE](LICENSE)。
+
+## 致谢
+
+- [OpenClaw](https://openclaw.dev) — AI agent 框架
+- [WPS 开放平台](https://open.wps.cn) — 企业协作平台
+- [TypeScript](https://www.typescriptlang.org/) — 类型安全的 JavaScript
+