cc-connect/docs/wps-xiezuo.md

WPS Xiezuo Platform Setup Guide

This guide explains how to connect cc-connect to WPS Xiezuo (WPS 365 collaboration) so users can talk to an AI coding agent from WPS chats.

Prerequisites

• A WPS Open Platform application with app chat events enabled
• app_id and app_secret for the application
• A machine running cc-connect; no public IP is required
• An agent such as Claude Code, Codex, or Gemini CLI configured in cc-connect

Connection Model

The platform uses WPS event WebSocket delivery and WPS REST APIs:

• Incoming events: WebSocket at wss://openapi.wps.cn/v7/event/ws
• Authentication: KSO-1 HMAC-SHA256 headers
• Event payloads: encrypted with AES-256-CBC and verified with HMAC-SHA256 signatures
• Outgoing replies: REST API with a cached client_credentials access token

cc-connect sends ACK frames on the WebSocket writer loop, so no public callback URL is needed.

Configure WPS

In the WPS Open Platform console:

1. Create or select an application.
2. Enable app chat/message capabilities for the application.
3. Enable event WebSocket delivery.
4. Subscribe to message events:
   • kso.app_chat.message
   • kso.app_chat.message.recall if recall notifications are needed
5. Grant the permissions needed to send app chat messages and reactions.
6. Grant kso.chat_message.readwrite so cc-connect can download images and local files attached to chat messages.
7. Grant kso.file.read (or kso.file.readwrite) so cc-connect can resolve shared cloud-document links and extract their content.
8. Copy the application app_id and app_secret.

The exact console names may vary by WPS tenant and app type. If the connection fails with authorization errors, verify that the app is published/enabled for the target organization and has the required app chat permissions.

Configure cc-connect

Add wps-xiezuo to a project in config.toml:

[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"

[projects.agent.options]
work_dir = "/path/to/your/project"

[[projects.platforms]]
type = "wps-xiezuo"

[projects.platforms.options]
app_id = "your-wps-xiezuo-app-id"
app_secret = "your-wps-xiezuo-app-secret"
allow_from = "*"        # optional; set to WPS user IDs in production
clean_reply = false     # optional; strip thinking/tool progress lines
max_attachment_bytes = 2147483648 # optional; default 2 GiB, maximum 5 GiB

Options

Option	Required	Default	Description
app_id	yes	-	WPS Open Platform application ID
app_secret	yes	-	WPS Open Platform application secret
allow_from	no	all users	Comma-separated WPS user IDs allowed to use the bot; set this in production
clean_reply	no	false	Removes common thinking/tool progress lines from replies before sending
base_url	no	https://openapi.wps.cn	Override WPS REST API base URL for private or test environments
max_attachment_bytes	no	2147483648 (2 GiB)	Per-attachment limit used by the WPS adapter. Must be greater than zero and no more than 5368709120 (5 GiB).

The public WPS chat-resource upload documentation does not specify a maximum file size. cc-connect therefore uses a 2 GiB default and allows deployments to raise it up to 5 GiB, based on the 5 GB limit documented for WPS document-attachment uploads. This is an adapter-side bound, not a claim that the chat-resource API guarantees 5 GiB. The top-level max_attachment_size_mb setting still limits files loaded by the cc-connect send command before they reach a platform; raise that setting as well when sending larger generated files through the CLI.

Start and Verify

Start cc-connect:

cc-connect -config /path/to/config.toml

Expected logs include:

level=INFO msg="wps-xiezuo: connecting" endpoint=wss://openapi.wps.cn/v7/event/ws
level=INFO msg="wps-xiezuo: connected"
level=INFO msg="platform started" project=my-project platform=wps-xiezuo

Send a message to the WPS app chat. cc-connect should receive the encrypted event, ACK it, forward the text to the configured agent, and send the reply back through the WPS message API.

Incoming files and images

Images and local files sent in WPS chats are downloaded through the WPS message-resource API and forwarded to the configured agent as attachments. Images embedded in rich-text messages are handled the same way. A single attachment is limited to 50 MiB to avoid unbounded memory use.

WPS cloud-document messages are different from local attachments. With kso.file.read (or kso.file.readwrite) application permission, cc-connect resolves the link_id and attempts to extract Markdown正文 using the Drive content API. The document title, link, and extracted content are forwarded to the agent under an explicit marker stating that the content was read with application authorization; the agent should use that body directly instead of trying to open the login-protected web link. If the application cannot access a document, cc-connect falls back to forwarding only the title and link_url.

Security Notes

• Always set allow_from for production deployments.
• Keep app_secret out of source control. Environment variable substitution is supported in config.toml, for example app_secret = "${WPS_XIEZUO_APP_SECRET}".
• Debug logs avoid printing decrypted WPS message payloads by default.

Troubleshooting

Connection fails immediately

• Confirm app_id and app_secret are correct.
• Confirm the app has WebSocket event delivery enabled.
• Confirm the app is available to the organization where you are testing.

Messages arrive but replies fail

• Confirm the app has message send permissions.
• Check whether the tenant requires the /oauth2/token or /openapi/oauth2/token token endpoint; cc-connect tries both.
• Verify the target chat allows app messages.

Images or local files are ignored

• Confirm the app has kso.chat_message.readwrite permission.
• Confirm the permission is enabled for the organization where the file was sent.
• Check for wps-xiezuo: image download failed or wps-xiezuo: file download failed in the logs.

Bot responds to unexpected users

• Set allow_from to a comma-separated list of WPS user IDs.
• Users can send /whoami to discover the ID used by cc-connect.