# qiweimanager 项目解析与使用说明

更新时间：2026-05-18

## 1. 当前环境与部署结果

本项目是一个 Windows 桌面端企业微信辅助管理工具，界面使用 Wails + Vue 3，主程序由 Go 编写，另有一个 `helper.exe` 辅助进程通过本地 HTTP 服务、DLL 调用和回调模板与企业微信交互。

本机环境已经部署并验证：

| 项目 | 当前状态 |
| --- | --- |
| Go | `go1.26.2 windows/amd64`，项目 `go.mod` 要求 `go 1.23` |
| Node.js | `v23.8.0` |
| npm | `10.9.2` |
| Wails CLI | `v2.10.2`，已安装在 `%USERPROFILE%\go\bin\wails.exe` |
| WebView2 | Wails Doctor 检测已安装，版本 `148.0.3967.70` |
| 前端依赖 | 已执行 `npm install`，依赖在 `frontend/node_modules` |
| 前端产物 | 已生成 `frontend/dist` |
| 主程序构建 | 已通过 `go build ./...` 和 `wails build` |
| 发布目录 | 已生成并补齐 `build/bin` |

当前可直接运行的发布目录：

```text
build/bin/
  qiweimanager.exe
  helper.exe
  Helper_4.1.33.6009.dll
  Loader_4.1.33.6009.dll
  config/
    config.json
    client_status.json
  requestdata/
    *.json
  eventdata/
    *.json
```

推荐从 `build/bin/qiweimanager.exe` 启动；当前项目根目录的 `qiweimanager.exe` 也已同步为 Wails 正式构建版本，可以直接双击运行。根目录原本自带的旧 exe 已备份为 `qiweimanager.old-invalid-build.exe`。

## 2. 项目整体架构

```text
Wails 主程序 qiweimanager.exe
  ├─ 嵌入 frontend/dist，展示 Vue 桌面界面
  ├─ 读取/保存 config/config.json
  ├─ 管理日志和操作记录
  ├─ 启动同级目录 helper.exe
  └─ 通过 http://localhost:<httpPort> 调用 helper

helper.exe
  ├─ 启动本地 HTTP REST 服务，默认端口 10001
  ├─ 加载 Helper_4.1.33.6009.dll 和 Loader_4.1.33.6009.dll
  ├─ 注入/连接企业微信 WXWork.exe
  ├─ 将请求模板 requestdata/*.json 转换成底层消息 type
  ├─ 将企业微信事件 eventdata/*.json 转换成回调格式
  └─ 将事件回调到 config.json 中配置的 callbackUrl
```

主要运行链路：

1. 启动 `qiweimanager.exe`。
2. 主程序初始化日志、配置、WebView2，并启动 `helper.exe`。
3. `helper.exe` 加载 DLL，启动本地 HTTP 服务。
4. 前端调用 Wails 绑定方法，例如 `SendWxWorkData`、`GetCallbackConfig`。
5. 主程序把指令转发到 `helper.exe` 的 `/api/send-wxwork-data`。
6. `helper.exe` 根据消息类型调用 DLL 或转换模板。
7. 企业微信回调数据进入 `MyRecvCallback` 后，经 `eventdata` 模板转换，再按配置推送到第三方回调地址。

## 3. 目录和文件说明

| 路径 | 作用 |
| --- | --- |
| `main.go` | Wails 主入口。初始化日志、配置、WebView2、单实例锁，启动/关闭 `helper.exe`。 |
| `app.go` | 暴露给前端的 Wails 方法，包含配置保存、发送企微数据、系统内存、账号列表、操作记录等。 |
| `http_client.go` | 主程序访问 helper 本地 HTTP 服务的客户端。 |
| `operation_record.go` | 操作日志 JSON 文件读写、分页、清理。 |
| `go.mod` / `go.sum` | Go 模块依赖，核心依赖是 `github.com/wailsapp/wails/v2 v2.10.2`。 |
| `wails.json` | Wails 项目配置，定义前端安装、构建和开发命令。 |
| `build_helper.bat` | 构建 32 位 `helper.exe` 并复制 DLL 的脚本。脚本末尾有 `pause`，命令行自动化时可改用本文的 PowerShell 命令。 |
| `Helper_4.1.33.6009.dll` | 企业微信辅助 DLL，运行时必须与 `helper.exe` 同级。 |
| `Loader_4.1.33.6009.dll` | 企业微信 Loader DLL，运行时必须与 `helper.exe` 同级。 |
| `qiweimanager.exe` | 仓库自带的旧可执行文件。当前构建产物在 `build/bin/qiweimanager.exe`。 |
| `config/` | 主程序默认配置结构与仓库内初始 `config.json`。运行时会读取 exe 同级的 `config/config.json`。 |
| `logger/` | 日志器，按日期写入 `Log/YYYY-MM-DD/*.txt`，最大文件约 5 MB，定期清理旧日志。 |
| `helper/` | 辅助进程源码，负责 DLL 加载、HTTP 服务、企业微信注入、事件转换和回调。 |
| `helper/config/client_status.json` | 示例账号状态文件。发布时已复制到 `build/bin/config/client_status.json`。 |
| `requestdata/` | 第三方请求模板。文件名对应 `/api/third-party-request` 的 `type`。 |
| `eventdata/` | 企业微信事件转换模板。文件名对应企业微信回调原始 `type`。 |
| `frontend/` | Vue 3 + Vite + Element Plus 前端工程。 |
| `frontend/src/App.vue` | 主界面：登录、系统首页、企微账号、操作记录、回调配置。 |
| `frontend/src/components/LoginModal.vue` | 登录弹窗，调用远程登录接口并保存 token 到本地配置。 |
| `frontend/src/components/WxWorkAccount.vue` | 企微账号列表，读取 `client_status.json`，支持下线/删除。 |
| `frontend/src/components/OperationLogs.vue` | 操作日志列表，读取本地操作记录。 |
| `frontend/wailsjs/` | Wails 自动生成的 JS/TS 绑定文件，不要手动改。 |
| `frontend/clear_storage.html` | 清空浏览器 localStorage 的小工具页面。 |
| `frontend/css` / `frontend/js` | 早期静态资源目录；当前入口是 `frontend/src/main.js`。 |
| `build/` | Wails 构建资源和输出目录。当前发布文件在 `build/bin`。 |
| `Log/` | 构建/运行时生成的日志目录。正式运行时会在 exe 同级目录生成日志。 |

## 4. 首次运行

1. 进入发布目录：

```powershell
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master\build\bin"
```

2. 启动主程序：

```powershell
.\qiweimanager.exe
```

3. 登录界面会要求输入账号、密码、验证码，并勾选测试学习用途声明。登录接口在前端代码中为：

```text
https://crm.yelangjiang.com/admin-api/system/auth/work-pw-login
```

4. 登录成功后进入主界面，可使用：

| 页面 | 功能 |
| --- | --- |
| 系统首页 | 查看消息累计、系统占用、活跃账号，点击“启动企微”。 |
| 企微账号 | 查看 `config/client_status.json` 中的账号状态，支持下线/删除。 |
| 操作记录 | 展示最新操作日志。 |
| 回调配置 | 配置回调地址、文件上传地址、HTTP 端口、设备编码、回调开关、云授权开关。 |

注意：企业微信相关功能依赖本机安装 `WXWork.exe`，并依赖项目自带 DLL 与目标企业微信版本兼容。

## 5. 配置文件

运行时配置位于发布目录：

```text
build/bin/config/config.json
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `callbackConfig.callbackUrl` | helper 收到事件后推送到第三方系统的 HTTP 回调地址。 |
| `callbackConfig.callbackToken` | 登录后会写入 accessToken，也可作为第三方接口鉴权 token 使用。 |
| `callbackConfig.httpPort` | helper 本地 HTTP 服务端口，默认 `10001`。 |
| `callbackConfig.enableCallback` | 是否开启事件回调。 |
| `callbackConfig.enableCloudAuth` | 是否开启云管理端授权。 |
| `callbackConfig.fileUploadUrl` | 媒体/文件上传地址。 |
| `callbackConfig.deviceCode` | 设备编码。 |
| `lastUpdated` | 最后保存时间戳。 |

账号状态文件：

```text
build/bin/config/client_status.json
```

它保存企业微信账号信息和在线状态，`GetWxWorkAccountList`、`DeleteWxWorkAccount`、机器人列表接口都会读取该文件。

## 6. 本地 HTTP API

helper 启动后默认监听：

```text
http://localhost:10001
```

如果修改了 `config.json` 的 `httpPort`，端口会随之变化。

### 健康检查

```powershell
Invoke-RestMethod "http://localhost:10001/api/health"
```

成功时返回：

```json
{
  "status": "ok",
  "time": "2026-05-18 15:00:00"
}
```

### 直接发送企业微信底层指令

接口：

```text
POST /api/send-wxwork-data
```

示例：

```json
{
  "clientId": "1688858204634393",
  "data": {
    "type": 11029,
    "data": {
      "conversation_id": "S:xxx",
      "content": "hello"
    }
  }
}
```

`data` 可以是 JSON 对象，也可以是 JSON 字符串。部分类型会直接返回结果，部分类型会等待企业微信回调，超时时间约 10 秒。

特殊类型：

| type | 说明 |
| --- | --- |
| `10000` | 启动/注入企业微信。前端“启动企微”按钮使用该类型。 |
| `10002` | 获取当前活跃客户端数量。 |
| `10003` | 获取机器人列表，来自 `getVWorkAccountListRequest.json`。 |
| `11036` | 在主程序里也被用于操作日志分页读取；在模板中也表示获取内部好友列表，注意调用上下文。 |
| `99999` | 主程序调试类型，用于测试操作日志读取。 |

### 第三方请求模板接口

接口：

```text
POST /api/third-party-request
```

第三方只需要传模板名称和参数，helper 会从 `requestdata/<type>.json` 找模板并替换 `{{params.xxx}}`。

示例：发送文本消息

```json
{
  "type": "sendVWorkTextMessage",
  "params": {
    "robotId": "1688858204634393",
    "conversationId": "S:1688xxxx_1688xxxx",
    "message": "hello"
  }
}
```

模板文件一般包含两个 JSON 对象：

1. 第一个对象是第三方请求格式说明。
2. 第二个对象是转换后的企业微信底层请求。

## 7. Wails 前端绑定方法

Wails 生成的前端绑定在：

```text
frontend/wailsjs/go/main/App.js
```

当前可从前端调用的方法：

| 方法 | 作用 |
| --- | --- |
| `AddLogEntry(source, type, content, duration)` | 写入一条操作日志。 |
| `DebugLoadLogEntries()` | 加载当天最新操作日志，主要供操作记录页面使用。 |
| `DeleteWxWorkAccount(userId)` | 从 `client_status.json` 删除账号。 |
| `GetActiveClientCount()` | 查询 helper 当前活跃客户端数量。 |
| `GetCallbackConfig()` | 获取当前配置。 |
| `GetSystemMemoryUsage()` | 获取 Windows 系统内存使用率。 |
| `GetWxWorkAccountList()` | 读取企微账号列表。 |
| `Greet(name)` | Wails 模板保留的示例方法。 |
| `LogFrontend(level, message)` | 前端日志写入 Go 日志文件。 |
| `SaveCallbackConfig(jsonData)` | 保存回调配置。 |
| `SendWxWorkData(clientId, jsonData)` | 发送企业微信底层指令到 helper。 |

## 8. requestdata 模板清单

`requestdata` 目录共 44 个模板。第三方调用 `/api/third-party-request` 时，`type` 填第二列名称。

| 文件 | 第三方 type | 底层 type |
| --- | --- | --- |
| `addVWorkCardUser.json` | `addVWorkCardUser` | `11121` |
| `addVWorkDeletedUser.json` | `addVWorkDeletedUser` | `11152` |
| `addVWorkFriendRequestFromGroup.json` | `addVWorkFriendRequestFromGroup` | `11071` |
| `addVWorkSearchUser.json` | `addVWorkSearchUser` | `11053` |
| `addVWorkSearchVWorkUser.json` | `addVWorkSearchVWorkUser` | `11088` |
| `agreeVWorkUser.json` | `agreeVWorkUser` | `11064` |
| `c2cCdnDown.json` | `c2cCdnDown` | `11170` |
| `c2cCdnUpload.json` | `c2cCdnUpload` | `11115` |
| `changeVWorkGroupNameRequest.json` | `changeVWorkGroupNameRequest` | `11059` |
| `changeVWorkUserCompany.json` | `changeVWorkUserCompany` | `11057` |
| `changeVWorkUserDesc.json` | `changeVWorkUserDesc` | `11055` |
| `changeVWorkUserPhone.json` | `changeVWorkUserPhone` | `11056` |
| `changeVWorkUserRemark.json` | `changeVWorkUserRemark` | `11054` |
| `createVWorkEmptyGroupRequest.json` | `createVWorkEmptyGroupRequest` | `11125` |
| `createVWorkGroupRequest.json` | `createVWorkGroupRequest` | `11058` |
| `deleteVWorkUser.json` | `deleteVWorkUser` | `11111` |
| `delVWorkMembersRequest.json` | `delVWorkMembersRequest` | `11061` |
| `dissolveGroupVWork.json` | `dissolveGroupVWork` | `11130` |
| `getCurrentAccountInfo.json` | `getCurrentAccountInfo` | `11035` |
| `getVWorkAccountListRequest.json` | `getVWorkAccountListRequest` | `10003` |
| `getVWorkExternalFriendList.json` | `getVWorkExternalFriendList` | `11037` |
| `getVWorkFriendInfo.json` | `getVWorkFriendInfo` | `11039` |
| `getVWorkGroupList.json` | `getVWorkGroupList` | `11038` |
| `getVWorkGroupMemberList.json` | `getVWorkGroupMemberList` | `11040` |
| `getVWorkInternalFriendList.json` | `getVWorkInternalFriendList` | `11036` |
| `groupInvitationVWorkConfirmationStatus.json` | `groupInvitationVWorkConfirmationStatus` | `11089` |
| `groupNameVWorkChangeStatus.json` | `groupNameVWorkChangeStatus` | `11108` |
| `inviteVWorkMembersRequest.json` | `inviteVWorkMembersRequest` | `11060` |
| `pushVWorkGroupNotice.json` | `pushVWorkGroupNotice` | `11082` |
| `quitGroupVWork.json` | `quitGroupVWork` | `11105` |
| `searchVWorkUserInfo.json` | `searchVWorkUserInfo` | `11052` |
| `sendVWorkAppletMessage.json` | `sendVWorkAppletMessage` | `11162` |
| `sendVWorkCardMessage.json` | `sendVWorkCardMessage` | `11161` |
| `sendVWorkFileMessage.json` | `sendVWorkFileMessage` | `11031` |
| `sendVWorkGifMessage.json` | `sendVWorkGifMessage` | `11070` |
| `sendVWorkGroupAtMessage.json` | `sendVWorkGroupAtMessage` | `11069` |
| `sendVWorkImageMessage.json` | `sendVWorkImageMessage` | `11030` |
| `sendVWorkTextMessage.json` | `sendVWorkTextMessage` | `11029` |
| `sendVWorkUrlMessage.json` | `sendVWorkUrlMessage` | `11159` |
| `sendVWorkVideoMessage.json` | `sendVWorkVideoMessage` | `11067` |
| `sendVWorkVideoNumberLiveMessage.json` | `sendVWorkVideoNumberLiveMessage` | `11196` |
| `sendVWorkVideoNumberMessage.json` | `sendVWorkVideoNumberMessage` | `11172` |
| `transferVWorkGroupOwner.json` | `transferVWorkGroupOwner` | `11090` |
| `wxCdnDown.json` | `wxCdnDown` | `11171` |

## 9. eventdata 事件模板清单

`eventdata` 目录共 28 个模板。helper 接收企业微信原始事件后，会按原始 `type` 找同名文件进行转换。

| 文件 | 原始 type | 回调 event | 描述 |
| --- | --- | --- | --- |
| `11026.json` | `11026` | `20001` | 用户登录成功通知事件 |
| `11027.json` | `11027` | `20009` | 用户退出通知事件 |
| `11028.json` | `11028` | `20025` | 登录二维码通知事件 |
| `11041.json` | `11041` | `20002` | 文本消息事件 |
| `11042.json` | `11042` | `20003` | 图片消息事件 |
| `11043.json` | `11043` | `20004` | 视频消息事件 |
| `11044.json` | `11044` | `20012` | 语音消息事件 |
| `11045.json` | `11045` | `20005` | 文件消息事件 |
| `11046.json` | `11046` | `20013` | 位置消息事件 |
| `11047.json` | `11047` | `20007` | 链接消息事件 |
| `11048.json` | `11048` | `20006` | 表情消息事件 |
| `11049.json` | `11049` | `20011` | 红包消息事件 |
| `11050.json` | `11050` | `20008` | 名片消息事件 |
| `11063.json` | `11063` | `20017` | 好友申请通知事件 |
| `11066.json` | `11066` | `20059` | 小程序消息事件 |
| `11068.json` | `11068` | `20014` | 图文消息事件 |
| `11072.json` | `11072` | `20030` | 新增群成员通知事件 |
| `11073.json` | `11073` | `20022` | 群成员减少通知事件 |
| `11074.json` | `11074` | `20020` | 新增群通知事件 |
| `11075.json` | `11075` | `20023` | 主动退群通知事件 |
| `11076.json` | `11076` | `20027` | 好友新增通知事件 |
| `11077.json` | `11077` | `20018` | 好友删除通知事件 |
| `11078.json` | `11078` | `20024` | 群名称变化通知事件 |
| `11123.json` | `11123` | `20015` | 撤回消息事件 |
| `11124.json` | `11124` | `20010` | 视频号消息事件 |
| `11173.json` | `11173` | `20019` | 被删除通知事件 |
| `11174.json` | `11174` | `20026` | 登录二维码状态通知事件 |
| `11195.json` | `11195` | `20016` | 视频号直播消息事件 |

## 10. 开发环境启动

PowerShell 当前执行策略会拦截 `npm.ps1`，所以建议用 `cmd /c npm ...` 或 `npm.cmd ...`。

前端单独开发：

```powershell
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master\frontend"
cmd /c npm install --cache .npm-cache
cmd /c npm run dev
```

Wails 开发模式：

```powershell
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master"
& "$env:USERPROFILE\go\bin\wails.exe" dev
```

如果希望直接使用 `wails` 命令，把下面路径加入用户 PATH：

```text
%USERPROFILE%\go\bin
```

## 11. 重新构建发布包

完整发布建议按下面顺序执行。

### 1. 构建前端

```powershell
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master\frontend"
cmd /c npm install --cache .npm-cache
cmd /c npm run build
```

### 2. 构建 Wails 主程序

```powershell
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master"
& "$env:USERPROFILE\go\bin\wails.exe" build
```

成功后主程序位于：

```text
build/bin/qiweimanager.exe
```

### 3. 构建 helper.exe

```powershell
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master\helper"
$env:GOARCH='386'
go build -ldflags='-H windowsgui -s -w' -o ..\build\bin\helper.exe .
Remove-Item Env:GOARCH
```

### 4. 复制运行时资源

```powershell
cd "C:\Users\12138\Desktop\企业微信\qiweimanager-master"
New-Item -ItemType Directory -Force -Path build\bin\config, build\bin\requestdata, build\bin\eventdata
Copy-Item -Force Helper_4.1.33.6009.dll build\bin\Helper_4.1.33.6009.dll
Copy-Item -Force Loader_4.1.33.6009.dll build\bin\Loader_4.1.33.6009.dll
Copy-Item -Force config\config.json build\bin\config\config.json
Copy-Item -Force helper\config\client_status.json build\bin\config\client_status.json
Copy-Item -Recurse -Force requestdata\* build\bin\requestdata\
Copy-Item -Recurse -Force eventdata\* build\bin\eventdata\
```

最终把整个 `build/bin` 目录作为发布包使用。

## 12. 已做的修正

本次环境部署中修正了一个前端构建问题：

| 文件 | 修正 |
| --- | --- |
| `frontend/vite.config.js` | 将 `@` 别名从 `'/src'` 改为基于 `import.meta.url` 的 `frontend/src` 绝对路径，避免 Windows/esbuild 在沙箱或受限目录下错误访问磁盘根目录。 |

如果不做该修正，`npm run build` 会报：

```text
Cannot read directory "../../../..": Access is denied.
```

## 13. 验证记录

已经通过的验证命令：

```powershell
go list ./...
go build ./...
cmd /c npm run build
& "$env:USERPROFILE\go\bin\wails.exe" doctor
& "$env:USERPROFILE\go\bin\wails.exe" build
```

验证结果：

| 项目 | 结果 |
| --- | --- |
| Go 包解析 | 通过，识别 `qiweimanager`、`qiweimanager/config`、`qiweimanager/helper`、`qiweimanager/logger`。 |
| Go 编译 | 通过。 |
| Vite 构建 | 通过，生成 `frontend/dist`。有 chunk 超过 500 KiB 的提醒，不影响运行。 |
| Wails Doctor | 通过，系统可用于 Wails 开发。 |
| Wails Build | 通过，生成 `build/bin/qiweimanager.exe`。 |
| helper 构建 | 通过，生成 `build/bin/helper.exe`。 |
| 发布资源 | 已复制 DLL、配置、请求模板、事件模板到 `build/bin`。 |

## 14. 常见问题

### PowerShell 执行 `npm` 被拦截

现象：

```text
npm.ps1，因为在此系统上禁止运行脚本
```

处理方式：

```powershell
cmd /c npm -v
cmd /c npm install
cmd /c npm run build
```

### `wails` 命令找不到

Wails 已安装，但可能不在 PATH。使用完整路径：

```powershell
& "$env:USERPROFILE\go\bin\wails.exe" version
```

或者把 `%USERPROFILE%\go\bin` 加入 PATH。

### 启动后 helper 无法工作

检查 `qiweimanager.exe` 同级是否有：

```text
helper.exe
Helper_4.1.33.6009.dll
Loader_4.1.33.6009.dll
config/config.json
config/client_status.json
requestdata/
eventdata/
```

还要确认企业微信 `WXWork.exe` 已安装，DLL 与企业微信版本兼容。

### 本地 HTTP 接口不通

检查 `config/config.json` 中的端口：

```json
{
  "callbackConfig": {
    "httpPort": "10001"
  }
}
```

然后测试：

```powershell
Invoke-RestMethod "http://localhost:10001/api/health"
```

如果端口被占用，改 `httpPort` 后重启应用。

### 语音消息转换失败

`helper/client_id_handler.go` 中语音转换会查找 `ffmpeg`。处理方式：

1. 将 `ffmpeg.exe` 放到 `build/bin`。
2. 或者把 ffmpeg 加入系统 PATH。

### 日志在哪里

正式运行后通常在 exe 同级目录生成：

```text
Log/YYYY-MM-DD/*.txt
operations/YYYY-MM-DD_operations.json
```

主程序日志、前端日志、helper 日志、操作记录都会写入本地文件，排查问题优先看这些目录。