新增功能

wechat_rpa/BACKEND.md

@@ -19,7 +19,8 @@ python admin_backend.py
 
 首次登录必须修改密码。也可以在第一次启动前通过环境变量 `WECOM_ADMIN_INITIAL_PASSWORD` 设置不同的初始密码。
 
-数据库默认保存在 `backend.db`，已加入 `.gitignore`。首次建库会读取当前 `ai_settings.json` 作为第一版模型配置。
+数据库默认保存在 `backend.db`，已加入 `.gitignore`。首次建库会优先读取本机
+`ai_settings.local.json`，不存在时才读取无密钥的 `ai_settings.json` 模板。
 
 ## 2. 用户与角色
 
@@ -27,6 +28,10 @@ python admin_backend.py
 - 配置员（operator）：查看和发布模型配置，不能管理用户。
 - 只读用户（viewer）：查看后台并登录桌面端同步配置，不能修改配置。
 
+“只读”表示不能修改后台，不表示看不到运行密钥：桌面端需要直接调用模型，因此所有
+获准同步桌面配置的账号都会收到 API Key。viewer 只应发放给可信终端用户；若要做到
+用户永远接触不到模型密钥，需要另行部署由后台代发请求的模型代理。
+
 管理员创建的新用户第一次登录网页时也必须修改初始密码，之后才能从桌面端登录。
 
 ## 3. 桌面端自动配置
@@ -35,7 +40,8 @@ python admin_backend.py
 
 1. 点击“登录后台”。
 2. 填写后台地址、用户名和密码。
-3. 登录成功后，后台配置立即写入本机 `ai_settings.json` 并生效。
+3. 登录成功后，后台配置立即写入已忽略 Git 的本机
+   `ai_settings.local.json` 并生效。
 4. 桌面端以后会在启动时及每 5 分钟自动同步，也可以点击“立即同步”。
 
 本机只保存 30 天有效的访问令牌，不保存后台密码。登录后台并启用自动同步后，本地 AI 配置字段会变成只读，以后台配置为准；退出后台后可恢复本地编辑。
@@ -44,6 +50,64 @@ python admin_backend.py
 
 同一台电脑上启动后台与桌面端时，后台会在 `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. 局域网部署
 
 如需让其他电脑连接，可在后台所在电脑运行：