# 企微插件 (@huo15/wecom)

**火一五企业微信插件** —— 基于 OpenClaw 的企业微信接入解决方案，集成了 Bot WebSocket、Agent API、动态 Agent 配置同步、Thinking 进度更新等核心功能。

---

## 核心特性

### 🤖 双模接入架构
- **Bot WebSocket**：低延迟实时对话，适合简单交互
- **Agent API**：复杂任务治理，支持工具调用和上下文管理

### 🔄 智能 Agent 管理

#### 动态 Agent 隔离
- **动态 Agent**：自动为每个用户/群组创建独立 Agent 实例，上下文完全隔离
- **会话隔离**：基于 `wecom-{accountId}-{type}-{peerId}` 生成独立 Agent ID
- **管理员直通**：配置 `adminUsers` 可让管理员绕过动态路由，直连主 Agent

#### 配置同步机制
- **主 Agent 配置同步**：主 Agent 的工作区配置自动同步到所有动态 Agent
- **支持的配置文件**：
  - `AGENTS.md` / `SOUL.md` / `TOOLS.md`
  - `IDENTITY.md` / `USER.md`
  - `HEARTBEAT.md` / `MEMORY.md`
- **同步规则**：配置文件始终以主 Agent 为准，覆盖更新
- **手动触发关键词**：`同步主agent` / `同步主 Agent` / `sync main agent` / `同步配置` / `更新配置`

### 💭 用户体验优化
- **Thinking 进度更新**：AI 思考超过 30 秒后，每 30 秒发送进度提示
- **配置热更新**：主 Agent 配置变更自动同步到动态 Agent

### 🏢 企业级能力
- **多账号隔离**：支持多企业微信账号同时接入
- **媒体处理**：图片、语音、文件等媒体类型全面支持
- **长任务保活**：自动处理长连接超时，确保任务不丢失
- **故障转移**：Webhook 模式支持主备切换

---

## 安装

```bash
# npm 安装
npm install @huo15/wecom

# OpenClaw 插件安装
openclaw plugins install @huo15/wecom
```

---

## 配置

在 `openclaw.json` 中添加配置：

```json
{
  "channels": {
    "wecom": {
      "enabled": true,
      "accounts": {
        "default": {
          "corpId": "YOUR_CORP_ID",
          "agentId": "YOUR_AGENT_ID",
          "agentSecret": "YOUR_AGENT_SECRET",
          "token": "YOUR_TOKEN",
          "encodingAESKey": "YOUR_KEY",
          "dynamicAgents": {
            "enabled": true,
            "dmCreateAgent": true,
            "groupEnabled": true,
            "adminUsers": ["ADMIN_USER_ID_1", "ADMIN_USER_ID_2"]
          },
          "streamPlaceholderContent": "正在思考中，请稍候..."
        }
      }
    }
  }
}
```

### 配置参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `corpId` | string | ✅ | 企业微信 CorpID |
| `agentId` | string | ✅ | 应用 AgentID |
| `agentSecret` | string | ✅ | 应用 Secret |
| `token` | string | ❌ | 回调 Token（启用加密消息时需要） |
| `encodingAESKey` | string | ❌ | 回调 EncodingAESKey |
| `dynamicAgents.enabled` | boolean | ❌ | 启用动态 Agent，默认 false |
| `dynamicAgents.dmCreateAgent` | boolean | ❌ | 私聊创建独立 Agent，默认 true |
| `dynamicAgents.groupEnabled` | boolean | ❌ | 群聊创建独立 Agent，默认 true |
| `dynamicAgents.adminUsers` | string[] | ❌ | 管理员 ID 列表，管理员使用主 Agent |
| `streamPlaceholderContent` | string | ❌ | AI 思考时占位符内容 |

---

## 启动

```bash
openclaw gateway start
```

---

## 工作流程

```
企业微信消息
    │
    ▼
┌─────────────────┐
│   消息路由       │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
Bot 消息   Agent 消息
    │         │
    ▼         ▼
Bot WebSocket  Agent API
    │         │
    └────┬────┘
         ▼
┌─────────────────┐
│ 动态 Agent 判断 │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
管理员     普通用户
    │         │
    ▼         ▼
主 Agent   动态 Agent
(独立会话)  (隔离上下文)
```

---

## 目录结构

```
wecom/
├── src/
│   ├── channel.ts              # Channel 入口
│   ├── dynamic-agent.ts        # 动态 Agent 逻辑
│   ├── runtime/                # 运行时模块
│   ├── transport/              # 传输层
│   │   ├── bot-ws/             # Bot WebSocket
│   │   ├── bot-webhook/        # Bot Webhook
│   │   └── agent-api/          # Agent API
│   └── capability/             # 业务能力
├── dist/                       # 编译输出
├── package.json
└── README.md
```

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

## 许可证

ISC

---

## 关于我们

**青岛火一五信息科技有限公司**

| 项目 | 信息 |
|------|------|
| **公司名称** | 青岛火一五信息科技有限公司 |
| **统一社会信用代码** | 91370203MA3CKRB364A |
| **联系电话** | 18554898815 |
| **邮箱** | postmaster@huo15.com |
| **官网** | https://huo15.com |

---

**Powered by 青岛火一五信息科技有限公司**
