# Grok Build 集成说明

本项目通过“受管 sidecar 运行时”的方式接入
[`xai-org/grok-build`](https://github.com/xai-org/grok-build)。上游 Rust
运行时保持原样，Python/Qt 负责安装、后台模型同步、进程生命周期和图形入口。
这样可以保留 TUI、Headless、ACP、工具、会话、MCP、技能、插件、Hooks、记忆、
计划、子代理、工作树和后台任务，而不把约百万行 Rust 代码降级重写为 Python。

## 文件与数据位置

| 路径 | 说明 | 是否提交 Git |
|---|---|---|
| `grok_build_bridge.py` | 安装、配置转换、TUI/Headless/ACP 启动器 | 是 |
| `grok_build_settings.json` | 不含密钥的集成默认值 | 是 |
| `grok_customer_service_mcp.py` | Grok 专用的受限客服工具 Server | 是 |
| `ai_settings.json` | 不含密钥的 AI 配置模板 | 是 |
| `ai_settings.local.json` | 后台/GUI 写入的本机私密 AI 配置 | 否 |
| `wechat_gui_qt.py` 的“Grok Build”页 | 图形控制台 | 是 |
| `.grok-build/bin/grok.exe` | 官方签名运行时二进制缓存 | 否 |
| `.grok-build/install.json` | 版本、来源、签名发布者与 SHA-256 安装记录 | 否 |
| `%LOCALAPPDATA%\ZhenYangTang\WeChatRPA\GrokBuild\<项目名-哈希>\custom-agent-only-v1\config.toml` | 仅自有模型的 Grok 正式配置；带标记区块由后台维护 | 否 |
| 同一隔离目录下的 `sessions/` | 仅自有模型会话、工具记录、计划和回退点 | 否 |
| 同一状态目录下的插件、技能和市场数据 | 原版运行时扩展状态 | 否 |
| 同一状态目录下的 `integration_settings.json` | 当前电脑的工作目录、模型与集成选项 | 否 |

`GROK_HOME` 每次启动都固定到上述 LocalAppData 项目专属隔离目录，不会覆盖用户
全局 `%USERPROFILE%\.grok`，也不会把认证和会话写进源码工作区。旧版桥接器的
xAI 认证与旧会话不会迁入或加载；二进制、下载缓存和市场缓存仍留在项目的忽略
目录中。

## 图形界面

运行：

```powershell
python .\wechat_gui.py
```

进入左侧“AI 客服”：

- 页面完全由本项目 Qt/Tk 控件实现，不创建 iframe、WebEngine、Edge 或外部浏览器。
- Qt 页面提供类似 Codex 的本地原生多轮对话，首次消息创建独立 UUID 会话，后续
  消息只恢复该精确会话；可新建对话或停止当前 Agent。
- 页面显示运行时、自有模型和专用隔离状态，并固定展示客服 MCP 的允许能力与
  Shell、文件、Web、发送等禁止能力。

进入左侧“Grok Build”：

- “安装运行时”从上游官方版本化地址下载稳定版，校验 PE 文件与 Authenticode
  签名发布者，计算并记录 SHA-256，再写入项目二进制缓存。后续启动会按安装记录
  重新计算并比对 SHA-256；外部自定义二进制会重新执行 Authenticode 校验。
- “同步后台模型”把管理后台已下发的 Agent 自有模型映射到
  LocalAppData 状态目录的 `config.toml` 自动配置区块。API Key 只在该受管模型
  已成功同步，且启动可能使用该模型的 Grok 进程时通过环境变量注入；主题、市场
  等其他 Grok 设置会被保留。
- 同步时会默认注册项目内置的 `wecom-rpa-customer-service` MCP。企业微信客服
  由本机 Grok Build Agent 直接生成回复，Agent 只通过该 MCP 获取受控的本地客服
  上下文和业务资料；不登录或探测外部 Chat 服务。该 Server 没有 Shell、文件、
  Web 或企业微信发送能力，也不能读取模型密钥。
- “打开完整 TUI”启动原版全屏界面，是全部上游功能的主入口。
- “插件与技能”“MCP 管理”直接进入原版对应功能；会话续聊使用“AI 客服”页的
  精确会话 ID，或在完整 TUI 中管理当前隔离目录内的自有模型会话。
- “图形化无头任务”使用 `streaming-json` 实时显示回答、思考、错误、轮数和会话
  ID，支持取消、只读审查和最大轮数；每次创建安全新会话，不会继续未知历史会话。
- “运行时检查”执行 `grok inspect --json`。

经典 Tk 界面只保留原 RPA 功能。完整 Grok Build 图形入口位于默认 PySide6
界面；无论使用哪种界面，都可以使用下面的命令行入口。

## 命令行入口

```powershell
# 查看状态
python .\grok_build_bridge.py status

# 安装最新 stable 官方运行时
python .\grok_build_bridge.py install

# 安装固定版本
python .\grok_build_bridge.py install --version 0.2.111

# 从后台已同步的 ai_settings.local.json 生成 Grok 模型配置
python .\grok_build_bridge.py sync

# 显式导入现有 MCP 配置；默认不导入，避免扩大业务数据权限
python .\grok_build_bridge.py sync --include-mcp

# 完整 TUI
python .\grok_build_bridge.py tui --cwd D:\web\age\wechat_rpa

# 只读无头审查
python .\grok_build_bridge.py run "审查启动流程并列出风险" --read-only

# 自动修改和运行命令；仅用于可信工作区
python .\grok_build_bridge.py run "修复测试并验证" --yolo

# 恢复指定会话
python .\grok_build_bridge.py run "继续修复" --resume <session-uuid>

# 启动 ACP JSON-RPC stdio 服务，供 IDE 或自定义客户端使用
python .\grok_build_bridge.py acp --cwd D:\web\age\wechat_rpa

# 原样访问上游全部 CLI 子命令
python .\grok_build_bridge.py exec -- models
python .\grok_build_bridge.py exec -- inspect --json

# 新版上游出现尚未识别的管理命令时：允许执行，但不注入受管密钥
python .\grok_build_bridge.py exec --allow-unknown -- future-command

# 只有确认未知命令需要模型能力时才显式注入；wrap 始终禁止注入
python .\grok_build_bridge.py exec --with-managed-secrets -- future-agent-command
```

`exec` 会先识别顶层命令：元数据/管理命令不带业务密钥，代理命令才带受管模型与
MCP 密钥，且代理命令会被强制指定为 `wecom-backend`；未知命令默认拒绝。Grok/xAI
的 `login`、`logout` 和 `setup` 被禁用。即使 `wrap` 前面混入 `-p`、
`--prompt-file` 等代理
参数，它仍按任意子进程入口处理，绝不会获得受管密钥。`agent --plugin-dir` 和
`agent --agent-profile` 可直接加载本地扩展配置，也按无密钥入口处理且不能用
`--with-managed-secrets` 绕过。

## 本地客服 Agent

后台和 Qt 的“AI 人格与能力”页只配置本地调度参数：

| 字段 | 默认值 | 范围 |
|---|---:|---|
| `GROK_CUSTOMER_SERVICE_ENABLED` | `true` | 开关 |
| `GROK_CUSTOMER_SERVICE_TIMEOUT` | `180` | `30..600` 秒 |
| `GROK_CUSTOMER_SERVICE_MAX_TURNS` | `8` | `2..30` |
| `GROK_CUSTOMER_SERVICE_EFFORT` | `low` | `low` / `medium` / `high` |

这些字段不包含服务网址或认证信息。旧版 `CHAT_API_*` 字段会在读取时被忽略，
保存与后台同步响应也不会再包含它们。Qt 启动或保存后会在后台线程读取本机
Grok Build 安装状态，并向所选自有模型协议发送一条不含业务数据的最小流式预检；
不会探测旧客服 HTTP 地址，也不读取 xAI 登录状态。

## 后台 Agent 自有模型

管理后台有独立的“Grok Agent 自有模型”配置：

| 字段 | 用途 |
|---|---|
| `GROK_MODEL_ENABLED` | 启用 Agent 唯一允许使用的自有模型 |
| `GROK_API_BASE` | OpenAI/Anthropic 兼容 API 基址 |
| `GROK_API_KEY` | 自有模型密钥，不在网页回显 |
| `GROK_MODEL` | 发送给服务端的模型 ID |
| `GROK_API_BACKEND` | `chat_completions`、`responses`、`messages` 或 `dify` |
| `GROK_AUTH_SCHEME` | `auto`、`bearer` 或 `x_api_key` |
| `GROK_DIFY_INPUTS` | 可选 Dify 应用固定输入 JSON 对象；其他协议忽略 |
| `GROK_CONTEXT_WINDOW` | 模型真实上下文窗口 |
| `GROK_MAX_TOKENS` | 单轮最大输出 |
| `GROK_TEMPERATURE` | 自有模型温度 |

桌面端启动后先同步管理后台配置，再更新 Grok 自动配置区块。启用且兼容的后台
模型是 Grok Build Agent 唯一允许使用的模型。未配置或不兼容时 Agent 直接停止，
不会读取 `auth.json`，也不会回退到 Grok/xAI 模型。主对话、网页搜索、会话总结、
图片理解、提示建议、分叉模型、子代理、Goal、自动模式分类器和压缩摘要全部固定为
同一个 `wecom-backend`；两套提示建议的额外模型调用默认关闭。文件式
role/persona/agent 若显式指定其他模型，启动门禁会拒绝注入密钥。当前后台只配置
Chat Agent 模型，因此 xAI Imagine 图片/编辑/视频模型功能会被禁用；以后应增加
独立的自有多媒体接口，而不是把文本模型 ID 冒充图片模型。

例如后台模型地址若为：

```text
http://host/v1/chat-messages
```

它属于 Dify `chat-messages` 协议。后台把“接口协议”选为
`Dify Chat Messages（本地工具调用适配）` 后，桌面端会启动一个仅监听
`127.0.0.1` 随机空闲端口的适配器，把 Grok Build 的消息、动态工具定义和工具
结果封装给 Dify，再把 Dify 的结构化决策转换成标准 OpenAI `tool_calls` 流。
Grok Build 仍负责执行和审计工具，Dify 只负责选择下一步动作。

后台支持以下自有模型协议：

- OpenAI Chat Completions：基址或 `/v1/chat/completions`
- OpenAI Responses：基址或 `/v1/responses`
- Anthropic Messages：基址或 `/v1/messages`
- Dify Chat Messages：基址或 `/v1/chat-messages`

即使后台只填写到 `/v1`，启动预检也会请求 Grok Build 真正使用的操作路径。
若原生协议选错且服务实际暴露 `/v1/chat-messages`，界面会提示切换为 Dify
协议。Dify 启动预检会强制模型调用一个带随机挑战值的临时工具；只有返回合法
工具调用并准确带回挑战值，界面才显示“Agent 已就绪”。预检同时核验认证、
模型名、流式请求和工具协议；结果会短暂缓存，正式发送前仍会复核，且错误信息
绝不包含 API Key。

Dify API Key 只保留在桌面宿主进程内存中。Grok 配置实际写入的是 loopback
Chat Completions 地址，Grok 子进程只获得随机生成的本地 Bearer 令牌。适配器使用
端口 `0` 让操作系统原子分配空闲端口，因此固定端口被占用不会阻止启动。Dify
应用应关闭其自身具有副作用的工具；项目工具仍由 Grok Build 的 allow/disallow
规则和客服工具审计控制。

远程 Dify 应使用 HTTPS。为兼容现有内网部署，系统不会直接拒绝远程 HTTP，但
界面会显示风险警告：HTTP 会让 Dify API Key、会话内容和工具结果以明文传输。

每次 `tui`、`run`、`acp` 或需要模型能力的 `exec` 启动前都会重新同步当前进程
持有的动态端点并执行工具调用预检，不能依赖另一进程先前 `sync` 留下的端口。
配置热更新采用版本化适配端点：新任务获得新端口和新令牌，已经运行的任务继续
使用原版本，避免下一轮突然出现 401。Dify `message_end.metadata.usage` 会转换
为 Chat Completions usage，供 Grok 的上下文窗口与自动压缩逻辑使用；上游没有
返回 usage 时才使用保守估算。

Grok 工具结果中的 `data:image/...;base64,...` 图片会先通过 Dify
`/files/upload` 上传，再作为 `local_file` 视觉附件随 `/chat-messages` 请求发送；
远程图片 URL 不由适配器二次抓取，以避免把不可信 URL 变成服务器端请求。

本地客服不再配置单独的网址、认证账号或远端会话。它作为 Grok Build Agent 的
内置调度场景，通过 `wecom-rpa-customer-service` MCP 读取受控本地上下文；原生
工具协议或 Dify 本地适配协议均通过同一套 Agent 门禁，不能通过普通客服 HTTP
接口绕过。

宿主会为每轮 Agent 生成一次性工具审计标识。只有模型实际调用了当前会话的
`scoped_get_context`、`analyze_customer_message`，并使用
`validate_final_reply` 校验了与最终输出完全一致的文本，本轮回复才允许进入发送
流程；客户明确要求挂号时，还必须由模型成功调用
`record_registration_request`。审计只记录工具名、会话指纹和文本哈希，不记录
客户原文，并在本轮结束后删除。仅在提示词里要求模型调用工具而没有审计证明，
不会被视为成功调度。

`auto` 认证仅对 `api.anthropic.com` 的 Messages 接口使用 `x-api-key` 并附加
`anthropic-version: 2023-06-01`，其他兼容代理默认使用 Bearer；特殊代理可在
后台显式选择认证方式。自定义端点必须配置独立 API Key。Agent 启动时会清除
xAI/Grok 凭据环境变量，并把 `GROK_AUTH_PATH` 指向一个不存在的隔离文件；若后台
非密钥配置与已同步区块不完全一致，桥接器会 fail-closed 阻止启动，
要求先重新同步，避免上游把 xAI 会话凭据回退发送到旧第三方端点。为避免上游在
拼接操作路径时改变语义，模型地址不能包含 query、fragment 或 URL 内嵌账号密码。
凭据门禁解析完整 TOML 后按有效配置值精确比较，不使用容易被注释或多行字符串
伪造的文本匹配；受管环境变量若在目标模型/MCP 之外再次被引用，也会拒绝注入。
注入前还会用不带业务密钥的 `inspect --json` 核验 Grok 实际配置层。只允许当前
LocalAppData 状态目录的 `config.toml` 用户层；`requirements.toml`、系统策略、
MDM、项目配置或任何未知高优先级层出现时均 fail-closed，防止端点被覆盖。

一个可用的生成结果如下：

```toml
[models]
default = "wecom-backend"
allowed_models = ["wecom-backend"]
web_search = "wecom-backend"
session_summary = "wecom-backend"
image_description = "wecom-backend"
prompt_suggestion = "wecom-backend"

[ui]
prompt_suggestions = false
fork_secondary_model = "wecom-backend"

[suggestions]
enabled = false
ai_enabled = false
ai_model = "wecom-backend"

[subagents]
enabled = true

[subagents.models]
general-purpose = "wecom-backend"
explore = "wecom-backend"
plan = "wecom-backend"

[goal]
use_current_model_only = true

[auto_mode]
classifier_model = "wecom-backend"

[compaction.memory_flush]
flush_model = "wecom-backend"

[model.wecom-backend]
model = "qwen-coder"
base_url = "https://model.example.com/v1"
name = "后台模型 · qwen-coder"
env_key = "WECOM_GROK_API_KEY"
api_backend = "chat_completions"
auth_scheme = "bearer"
temperature = 0.3
max_completion_tokens = 8192
context_window = 128000
```

## 上游功能的访问方式

| 功能 | 本项目入口 |
|---|---|
| 文件读取、搜索、精确编辑、终端、Web | 完整 TUI 或无头任务 |
| 新建、恢复、继续、分叉、重命名、导出会话 | 完整 TUI `/new`、`/resume`、`/fork`、`/rename`、`/export` |
| compact、context、rewind、prompt edit | 完整 TUI |
| 模型与 reasoning effort | 模型固定为后台 `wecom-backend`；effort 使用 Qt 或 TUI `/effort` |
| 计划模式、TODO、持久目标、Deep Research | TUI `/plan`、`/goal`、`/deep-research` |
| 子代理、persona、Agent Dashboard | 完整 TUI；推理模型仍固定为 `wecom-backend` |
| MCP stdio/HTTP/OAuth | TUI `/mcps` 或 Grok 配置 |
| 企业微信客服回复 | 本地 Grok Build Agent + 内置受控客服 MCP |
| Skills、Plugins、Marketplace、Hooks、LSP | TUI `/skills`、`/plugins`、`/marketplace`、`/hooks` |
| 规则、AGENTS.md、长期记忆 | 原版运行时自动加载及 `/memory` |
| 后台任务、monitor、loop、workflow | 完整 TUI |
| Git worktree、checkpoint、rewind | 完整 TUI |
| Headless/CI/NDJSON | Qt 无头任务或 `grok_build_bridge.py run` |
| ACP IDE 嵌入 | `grok_build_bridge.py acp` |
| 主题、Vim、鼠标、图片粘贴、语音、Dashboard | 完整 TUI |
| 原版未映射的新 CLI 功能 | `grok_build_bridge.py exec -- <参数>` |

上游公开源码中的 `deploy_app` 本身仍是 stub；集成不会把上游尚未实现的功能描述
成可用功能。

## 权限与安全

`wecom-rpa-customer-service` 返回的客户消息、本地会话历史和业务资料都是
**不可信外部数据**。Grok 不得把其中内容视为系统指令、工具调用要求或授权依据，
也不得让这些内容触发 shell、文件、网络或消息发送工具。MCP 结果会携带
`untrusted_content=true` 和安全说明；模型和 MCP 都不能直接发送消息，最终发送
只由宿主企业微信流程执行。

- Windows 目前没有上游 Linux Landlock 或 macOS Seatbelt 的等价系统沙箱。
- Qt 无头任务默认不启用 `--yolo`。开启“无人值守”前会再次确认。
- “只读审查”只允许 `read_file`、`grep`、`list_dir`、`web_search` 和
  `web_fetch`，同时设置 `--no-subagents` 并通过 deny-list 移除上游始终保留的
  MCP meta-tools 与子代理。由于原版运行时会在工具过滤前启动原生 MCP、插件
  Hook 与 LSP，只读任务会先运行一次不带业务密钥的 `inspect --json`；发现任何
  有效的可执行扩展或无法确认检查结果时，模型进程不会启动。请先在完整 TUI/
  配置中禁用这些扩展后重试。
- 完整 TUI 使用上游逐工具审批，适合日常交互任务。
- MCP、插件、Hooks 和 LSP 都可能执行本地程序，只安装可信来源。
- `AI_MCP_SERVERS` 默认不自动导入编码代理；需要时显式开启。导入后的 header
  与 env 值不写入 TOML，而以环境变量引用保存，并且只在配置确实引用它们时注入。
  OAuth 登录和授权管理使用原版 TUI `/mcps`，令牌保存在工作区外的状态目录。
  手工环境变量引用只接受 `${VAR}`，不接受带默认值的表达式。
  `WECOM_GROK_API_KEY` 与 `WECOM_GROK_MCP_*` 是桥接器保留变量，不能在后台
  MCP 配置中手工交叉引用。
  只有 `env` 和 `headers` 的值会转换；若把秘密直接写进 URL、command 或 args，
  它仍会明文出现在 TOML 中，因此这些字段只能保存非秘密参数。桥接器会拒绝常见
  的 token query 和密钥命令行参数，但无法识别任意路径片段中的秘密。
- 项目内置客服 MCP 与 `AI_MCP_SERVERS` 相互独立，默认由
  `grok_build_settings.json` 的 `customer_service_tools=true` 自动注册。MCP
  只负责读取受控的本地客服上下文和业务资料，不再调用第二个回复模型，从而避免
  Agent 递归；它也没有企业微信发送、Shell、文件或 Web 能力。
- 后台模型 Key 与 MCP 的 env/header 值不写入 Grok TOML，但在使用对应受管配置
  的 Grok 进程期间会存在于进程环境中，本地工具或终端子进程可能读取它们。只在
  可信任务中启用终端、插件、Hooks、LSP 与第三方 MCP；Grok/xAI 登录入口已禁用，
  版本检测、Qt/CLI `inspect` 和 `doctor` 元数据命令不会携带这些业务密钥。
- 管理后台同步下来的 `ai_settings.local.json` 是明文本地配置，已加入
  `.gitignore`；已跟踪的 `ai_settings.json` 现在只是不含密钥的模板。应限制本地
  文件 ACL，并只向可信桌面账号发放后台读取权限。旧版本源码或 Git 历史中曾保存
  的密钥必须在服务端轮换，清空当前文件并不能撤销历史泄漏。
- 当前项目包含客服会话、挂号数据和模型密钥。不要要求编码代理读取或上传这些
  运行数据；发布前应把运行数据迁出源码目录并轮换已经进入 Git 历史的密钥。
- 公网模型地址应使用 HTTPS。HTTP 会明文传输 Bearer API Key 和提示内容。
- rewind、工作树应用和自动编辑可能改变未提交文件，执行前先检查 Git 状态。

## 更新与回滚

桥接器禁用上游进程内自动更新，避免绕过本项目的下载与签名校验。图形页
“安装 / 更新”或命令行 `install` 会显式覆盖项目内 `grok.exe`。安装记录包含
版本、平台、时间、SHA-256 和签名发布者，保存在
`.grok-build/install.json`。固定版本可用：

```powershell
python .\grok_build_bridge.py install --version 0.2.111
```

项目运行时不会写入用户 PATH，也不会修改用户全局 Grok 配置。
启动时的哈希复核用于发现二进制意外变化；它不防御一个已经拥有项目写权限、能
同时替换 Python 集成代码、二进制和安装记录的本地恶意进程。

## 测试

```powershell
python -B -m unittest discover -v
python -B -c "import ast,pathlib; [ast.parse(pathlib.Path(p).read_text(encoding='utf-8'), filename=p) for p in ('grok_build_bridge.py','grok_customer_agent.py','grok_customer_service_mcp.py','wechat_gui_qt.py','admin_backend.py','ai_config.py')]"
```

测试使用临时目录和 mock，不需要 xAI 账号，也不会下载真实运行时。

## 许可证与来源

上游 `xai-org/grok-build` 首方代码采用 Apache License 2.0，并包含大量第三方
依赖声明。当前仓库不提交或再分发 `grok.exe`，而是在用户明确安装时直接从 xAI
官方地址下载。若制作包含二进制的离线安装包，必须同时携带对应版本的：

- `LICENSE`
- `THIRD-PARTY-NOTICES`
- `crates/codegen/xai-grok-tools/THIRD_PARTY_NOTICES.md`
- `third_party/NOTICE`

不得暗示本项目是 xAI 官方产品，也不得把 Grok/xAI 商标当作本项目商标。