# 配置管理后台

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

## 1. 启动后台

在项目目录运行：

```powershell
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. 局域网部署

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

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

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

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

## 5. 管理员密码恢复

停止后台后运行：

```powershell
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`：健康检查。