npm package: @qiwenxie/simple-xiezuo
Description: WPS协作（WPS365）聊天机器人插件，支持 Clawdbot/Moltbot 框架
Author: xieqiwen
Latest version: 1.2.0

# simple-xiezuo

<div align="center">

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

用于 Clawdbot/Moltbot 框架

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)

[English](#english) | [中文](#chinese)

</div>

---

<a name="chinese"></a>

## 📖 简介

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

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

## 🚀 快速开始

### 安装

**方式 1：Git 克隆（推荐）**

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

**方式 2：直接复制**

```bash
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 开放平台](https://open.wps.cn/)
   - 创建应用，获取 AppId、SecretKey、EncryptKey

2. **配置 Moltbot**

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

```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**

```bash
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` 忽略，克隆后需要：

```bash
cd simple-xiezuo
npm install
```

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

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

**A**: 确保已安装依赖：

```bash
npm install
```

### Q3: 收不到消息回调？

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

### Q4: 如何更新插件？

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

### Q5: 如何发布到 NPM？

```bash
# 登录 NPM
npm login

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

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

## 🛠️ 开发指南

### 本地开发

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

# 安装依赖
npm install

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

### 调试技巧

```bash
# 前台运行查看日志
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](./LICENSE)

## 👤 作者

**xieqiwen** <xieqiwen@kingsoft.com>

## 🔗 相关链接

- [GitHub 仓库](https://github.com/xieqiwen/simple-xiezuo)
- [WPS 开放平台](https://open.wps.cn/)
- [Moltbot 文档](https://moltbot.ai/)

---

<a name="english"></a>

## 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

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

```bash
npm install
```

This installs all dependencies specified in `package.json`.

### License

MIT

---

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