kefu/wechat_rpa/BACKEND.md

配置管理后台

项目内置了一个零额外依赖的配置后台，用于统一管理登录账号、角色、AI 模型和 MCP 配置。

1. 启动后台

在项目目录运行：

python admin_backend.py

后台会优先使用 8765。如果该端口已被其他程序占用，会自动尝试 8766、8767……，并在控制台打印最终地址。桌面端会读取 backend_runtime.json 自动跟随实际端口，无需手工修改。

浏览器打开控制台打印的地址。首次创建数据库时使用：

• 用户名：admin
• 初始密码：Admin@123456

首次登录必须修改密码。也可以在第一次启动前通过环境变量 WECOM_ADMIN_INITIAL_PASSWORD 设置不同的初始密码。

数据库默认保存在 backend.db，已加入 .gitignore。首次建库会优先读取本机 ai_settings.local.json，不存在时才读取无密钥的 ai_settings.json 模板。

2. 用户与角色

• 管理员（admin）：管理用户、角色并发布模型配置。
• 配置员（operator）：查看和发布模型配置，不能管理用户。
• 只读用户（viewer）：查看后台并登录桌面端同步配置，不能修改配置。

“只读”表示不能修改后台，不表示看不到运行密钥：桌面端需要直接调用模型，因此所有 获准同步桌面配置的账号都会收到 API Key。viewer 只应发放给可信终端用户；若要做到 用户永远接触不到模型密钥，需要另行部署由后台代发请求的模型代理。

管理员创建的新用户第一次登录网页时也必须修改初始密码，之后才能从桌面端登录。

3. 桌面端自动配置

启动 wechat_gui.py，进入“AI 人格与能力”页：

1. 点击“登录后台”。
2. 填写后台地址、用户名和密码。
3. 登录成功后，后台配置立即写入已忽略 Git 的本机 ai_settings.local.json 并生效。
4. 桌面端以后会在启动时及每 5 分钟自动同步，也可以点击“立即同步”。

本机只保存 30 天有效的访问令牌，不保存后台密码。登录后台并启用自动同步后，本地 AI 配置字段会变成只读，以后台配置为准；退出后台后可恢复本地编辑。

后台发生端口冲突并自动更换端口时，同一项目目录中的桌面端会自动发现新地址；已有登录令牌可以继续使用。

同一台电脑上启动后台与桌面端时，后台会在 backend_runtime.json 发布一个仅限回环地址使用的临时只读同步凭证。桌面软件启动时会先检测该服务并拉取最新配置，所以即使没有保存后台账号登录，也会立即刷新“能力开关”“模型与身份”和“MCP 服务器”中的内容。该凭证不能管理用户或修改后台配置，后台停止后即失效。

桌面端主“AI 客服”页也是本地功能页：Qt 不再创建 WebEngine，经典 Tk 不再 启动或嵌入 Edge。Qt 页提供类似 Codex 的原生多轮 Agent 对话，可新建会话、续聊 和停止执行，并显示安装、自有模型、隔离状态和受控工具边界。

Grok Build 本地客服 Agent

企业微信文字客服现在是项目内置功能，不再通过外部 Chat 网址、游客身份或专用 账号接入。桌面端把客户消息交给本机 Grok Build Agent；Agent 只能调用项目内置的 受控客服 MCP 获取本地上下文、客服档案和业务资料，再由模型直接生成回复草稿。 该受控运行环境不提供 Shell、文件、Web 或消息发送工具，最终发送仍由现有企业 微信流程控制。宿主还会核对一次性、无客户原文的工具审计：模型必须实际读取 当前会话、分析本轮消息，并校验与最终输出完全一致的回复；明确预约时还必须 完成“待人工确认”登记，否则该轮草稿不会发送。

后台可统一下发：

字段	默认值	范围 / 用途
GROK_CUSTOMER_SERVICE_ENABLED	true	启用本地客服 Agent
GROK_CUSTOMER_SERVICE_TIMEOUT	180	单次回复超时，30..600 秒
GROK_CUSTOMER_SERVICE_MAX_TURNS	8	单次最多 Agent 轮数，2..30
GROK_CUSTOMER_SERVICE_EFFORT	low	low、medium 或 high

桌面软件启动、保存本地配置或完成后台同步后，会在后台线程检查本机 Grok Build 安装状态，并对后台自有模型执行不含业务数据的最小流式端点预检；不会探测旧客服 HTTP 地址或 xAI 登录。旧版 CHAT_API_* 字段即使仍存在于 ai_settings.local.json，也会被忽略，且下一次 保存或后台发布时不会再导出。

Grok Agent 自有模型

后台“模型配置中心”包含独立的 Grok Agent 自有模型。Grok Build 只负责 Agent 调度，不提供本项目的推理模型。启用后，桌面端会把 GROK_API_BASE、GROK_MODEL、接口协议、认证方式、上下文窗口、最大输出和 温度自动写入 LocalAppData 项目专属 Grok 状态目录内 config.toml 的自动配置 区块。密钥不写入 TOML，仅在受管模型确实已同步，且启动可能使用该模型的 Grok 进程时通过 WECOM_GROK_API_KEY 环境变量注入。启动门禁会解析完整 TOML， 精确核对模型、端点、协议、认证方式和生成参数；注释或多行字符串不能伪造通过。 主对话、搜索、总结、图片理解、分叉、子代理、Goal、自动分类器和压缩摘要等 Agent 模型角色也全部固定到 wecom-backend；额外建议模型与没有自有接口的 xAI Imagine 图片/视频能力关闭。项目使用独立的 custom-agent-only-v1 运行目录， 不迁入旧的 xAI 登录凭据或旧 Grok 模型会话，并禁用 Grok/xAI 登录入口。

自有模型可使用 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages， 也可在“接口协议”中选择 Dify Chat Messages。Dify 地址既可填写 /v1，也可填写 完整 /v1/chat-messages；桌面端会用随机本地端口启动 loopback 适配器，将 Dify 的结构化决策转换为 Grok Build 标准工具调用。启动预检会强制执行一次随机挑战 工具调用，只有 Dify 应用确实支持 Agent 工具协议时才显示“已就绪”。Dify Key 不会写入 Grok 配置或交给 Grok 子进程。缺失、不兼容、认证失败、工具协议不合格 或端点返回错误时 Agent 会直接停止，绝不会回退到 Grok/xAI 模型。 本地端口由操作系统自动分配；每次启动 Agent 都会刷新，配置更新时新旧任务使用 不同版本的本地端点，互不覆盖。 若 Dify 应用定义了必填输入变量，可在后台“Dify inputs JSON”中填写固定对象； 默认 {}。 GROK_AUTH_SCHEME=auto 对 Anthropic 官方 域名使用 x-api-key，其他兼容服务使用 Bearer；也可按服务端要求显式选择。 完整说明见 GROK_BUILD.md。

4. 局域网部署

如需让其他电脑连接，可在后台所在电脑运行：

python admin_backend.py --host 0.0.0.0 --port 8765

桌面端后台地址填写服务器的局域网地址，例如 http://192.168.1.20:8765。需要在 Windows 防火墙中仅对可信局域网放行该端口。

跨公网使用时不要直接暴露此 HTTP 服务，应使用 Nginx、Caddy 等反向代理配置 HTTPS，再把桌面端地址改为 HTTPS 地址。

5. 管理员密码恢复

停止后台后运行：

python admin_backend.py --reset-admin-password

按提示输入新密码。重置后已有 admin 登录令牌会失效，下次登录仍需再修改一次密码。

API

• POST /api/v1/auth/login：桌面端登录并取得令牌。
• POST /api/v1/auth/logout：注销令牌。
• GET /api/v1/me：读取当前用户及角色。
• GET /api/v1/config：读取当前版本的模型配置。
• GET /health：健康检查。