simple-xiezuo

WPS协作（WPS365）聊天机器人插件

用于 Clawdbot/Moltbot 框架

English | 中文

📖 简介

simple-xiezuo 是一个为 WPS协作（WPS365）平台开发的智能聊天机器人插件，支持：

• 🤖 AI 智能对话助手
• 💬 单聊和群聊消息处理
• 🔐 AES-256-CBC 消息加密解密
• 🔄 OAuth 2.0 身份认证
• 📦 开箱即用，快速部署

🚀 快速开始

安装

方式 1：Git 克隆（推荐）

cd /path/to/moltbot/extensions/
git clone https://github.com/xieqiwen/simple-xiezuo.git
cd simple-xiezuo
npm install

方式 2：直接复制

cp -r simple-xiezuo /path/to/moltbot/extensions/
cd /path/to/moltbot/extensions/simple-xiezuo
npm install

💡 重要：node_modules 不会被提交到 Git，克隆后必须运行 npm install 安装依赖。

配置

1. 获取 WPS 凭证

   • 访问 WPS 开放平台
   • 创建应用，获取 AppId、SecretKey、EncryptKey

2. 配置 Moltbot

在 /path/to/moltbot/moltbot.json 中添加：

{
  "channels": {
    "simple-xiezuo": {
      "enabled": true,
      "appId": "YOUR_WPS_APP_ID",
      "secretKey": "YOUR_WPS_SECRET_KEY",
      "encryptKey": "YOUR_ENCRYPT_KEY",
      "apiUrl": "https://openapi.wps.cn"
    }
  },
  "plugins": {
    "entries": {
      "simple-xiezuo": {
        "enabled": true
      }
    }
  }
}

3. 启动 Gateway

cd /path/to/moltbot
node /root/moltbot-main/dist/entry.js gateway

# 或后台运行
nohup node /root/moltbot-main/dist/entry.js gateway > gateway.log 2>&1 &

4. 配置 WPS 回调 URL

在 WPS 开放平台设置：

http://YOUR_SERVER_IP:9912/simple-xiezuo/callback

验证

启动成功后，日志应显示：

=== 注册 WPS协作 插件 ===
[gateway] listening on ws://0.0.0.0:9912

📁 项目结构

simple-xiezuo/
├── src/
│   ├── channel.ts        # 频道插件主逻辑
│   ├── gateway.ts        # HTTP 回调处理
│   ├── crypto.ts         # 加密解密工具
│   ├── oauth-token.ts    # OAuth 令牌管理
│   ├── wps-api.ts        # WPS API 客户端
│   └── message-parser.ts # 消息解析器
├── skills/
│   └── xiezuo-helper/    # AI 助手技能定义
├── index.ts              # 插件入口
├── package.json          # 项目配置
└── README.md             # 本文档

🔧 技术特性

认证方式

• WPS-3 签名：SHA1 HMAC（旧版 API）
• KSO-1 签名：SHA256 HMAC（新版 API）
• OAuth 2.0：client_credentials 授权流程

消息加密

• 算法：AES-256-CBC
• 密钥来源：MD5(SecretKey)
• 填充方式：PKCS7

API 版本

• ✅ /v7/messages/create（推荐，统一 ID）
• 🔄 /v2/dev/app/messages（旧版，已弃用）

🔒 安全说明

敏感信息保护

项目已配置 .gitignore 忽略以下文件：

• node_modules/ - 依赖目录（必须）
• dist/ - 编译输出（TypeScript 自动生成）
• .env* - 环境变量文件
• moltbot.json - 包含真实凭证
• *-config.json - 配置文件（除 config-example.json）
• *.key, *.pem - 密钥文件

Git 提交前检查

项目包含 pre-commit 钩子，自动检测：

• 硬编码的 AppId、SecretKey
• 配置文件泄露
• API Key 泄露

最佳实践

1. ✅ 使用环境变量存储敏感信息
2. ✅ 定期轮换密钥
3. ✅ 提交前检查 git diff
4. ❌ 永远不要提交真实凭证到 Git

❓ 常见问题

Q1: 别人克隆后无法运行？

A: 因为 node_modules 被 .gitignore 忽略，克隆后需要：

cd simple-xiezuo
npm install

这会根据 package.json 重新安装所有依赖。

Q2: 启动失败，提示 "找不到模块"？

A: 确保已安装依赖：

npm install

Q3: 收不到消息回调？

A: 检查：

1. WPS 平台回调 URL 配置正确
2. 防火墙已开放 9912 端口
3. Gateway 正常运行（ps aux | grep gateway）

Q4: 如何更新插件？

cd simple-xiezuo
git pull origin main
npm install  # 安装新增依赖

Q5: 如何发布到 NPM？

# 登录 NPM
npm login

# 发布（首次需要 --access public）
npm publish --access public

发布后，他人可通过 npm install @xieqiwen/simple-xiezuo 安装。

🛠️ 开发指南

本地开发

# 克隆项目
git clone https://github.com/xieqiwen/simple-xiezuo.git
cd simple-xiezuo

# 安装依赖
npm install

# 修改代码后重启 Gateway
# Moltbot 支持 TypeScript，无需编译

调试技巧

# 前台运行查看日志
node /root/moltbot-main/dist/entry.js gateway

# 查看实时日志
tail -f /path/to/moltbot/gateway.log

📦 依赖说明

为什么不提交 node_modules？

1. 体积过大：node_modules 通常数十 MB 甚至上百 MB
2. 平台差异：不同操作系统的二进制依赖不同
3. 版本管理：package.json 和 package-lock.json 已足够
4. 最佳实践：所有 Node.js 项目都应忽略 node_modules

为什么不提交 dist？

dist 是 TypeScript 编译输出，但 Moltbot 直接运行 .ts 文件，无需编译。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License - 详见 LICENSE

👤 作者

xieqiwen [email protected]

🔗 相关链接

• GitHub 仓库
• WPS 开放平台
• Moltbot 文档

English

Introduction

WPS Collaboration (WPS365) chatbot plugin for Clawdbot/Moltbot framework.

Features

• 🤖 AI-powered conversation
• 💬 Single & group chat support
• 🔐 AES-256-CBC encryption
• 🔄 OAuth 2.0 authentication
• 📦 Ready to deploy

Quick Start

# Clone
git clone https://github.com/xieqiwen/simple-xiezuo.git
cd simple-xiezuo

# Install dependencies (Required!)
npm install

# Configure in moltbot.json
# Start gateway
node /path/to/moltbot/dist/entry.js gateway

Why no node_modules in Git?

node_modules is ignored by design. After cloning, always run:

npm install

This installs all dependencies specified in package.json.

License

MIT

现在就开始使用 WPS 协作机器人！ 🎉