kefu/wechat_rpa/GROK_BUILD.md

Grok Build 集成说明

本项目通过“受管 sidecar 运行时”的方式接入 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 认证与旧会话不会迁入或加载；二进制、下载缓存和市场缓存仍留在项目的忽略 目录中。

图形界面

运行：

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 界面；无论使用哪种界面，都可以使用下面的命令行入口。

命令行入口

# 查看状态
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 冒充图片模型。

例如后台模型地址若为：

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，防止端点被覆盖。

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

[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。固定版本可用：

python .\grok_build_bridge.py install --version 0.2.111

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

测试

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 商标当作本项目商标。