qiweimanager-master/USAGE.md

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

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

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. 项目整体架构

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. 进入发布目录：

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

2. 启动主程序：

.\qiweimanager.exe

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

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

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

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

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

5. 配置文件

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

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	最后保存时间戳。

账号状态文件：

build/bin/config/client_status.json

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

6. 本地 HTTP API

helper 启动后默认监听：

http://localhost:10001

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

健康检查

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

成功时返回：

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

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

接口：

POST /api/send-wxwork-data

示例：

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

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

特殊类型：

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

第三方请求模板接口

接口：

POST /api/third-party-request

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

示例：发送文本消息

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

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

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

7. Wails 前端绑定方法

Wails 生成的前端绑定在：

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 ...。

前端单独开发：

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

Wails 开发模式：

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

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

%USERPROFILE%\go\bin

11. 重新构建发布包

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

1. 构建前端

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

2. 构建 Wails 主程序

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

成功后主程序位于：

build/bin/qiweimanager.exe

3. 构建 helper.exe

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. 复制运行时资源

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 会报：

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

13. 验证记录

已经通过的验证命令：

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 被拦截

现象：

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

处理方式：

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

wails 命令找不到

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

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

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

启动后 helper 无法工作

检查 qiweimanager.exe 同级是否有：

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 中的端口：

{
  "callbackConfig": {
    "httpPort": "10001"
  }
}

然后测试：

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

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

语音消息转换失败

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

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

日志在哪里

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

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

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