# AstrWeChat agent 部署指南

本文指导能够操作用户本机的 agent 安装并配置 AstrWeChat 最新正式版本的 Windows 软件版。默认在每次部署时查询 GitHub Releases，确定最新正式版本后再安装，不固定版本号。阅读后，请直接开始下方问答；收集必要信息后，执行环境检查、软件安装、配置写入和结果验证。微信首次登录及首次连接由用户在软件中自行完成。

用户只需要发送：

> 请阅读 https://github.com/CMKH1337/Astrwechat/blob/main/agent_deploy.md。

## 向用户询问配置

使用简短中文，一次只询问当前需要填写的信息。用户已经提供的内容直接沿用。环境信息由 agent 检测，安装目录、本地服务端口等采用现有值或默认值。

第一句使用：

> 你希望 AstrWeChat **连接 AstrBot**，还是**直接使用模型 API**？

根据回答，只继续对应分支的问答。

### 连接 AstrBot

> 请填写 AstrBot 的连接信息：
>
> - **连接地址**：例如 `ws://127.0.0.1:11229/ws`
> - **Token**：没有设置就留空。
>
> 不清楚的项目可以写“不知道”。

这里需要的是 AstrBot OneBot v11 反向 WebSocket 连接地址。示例仅用于说明格式，以用户实际配置为准。用户提供了网页管理地址时，协助找到对应的 OneBot 地址；仅在确定 AstrBot 运行位置和端口后才填写。

本流程接入已有 AstrBot。如果用户还没有部署 AstrBot，说明还需要先准备 AstrBot，并向用户询问如何继续，不擅自改为 API 模式。

### 直接使用模型 API

> 请填写模型服务的配置：
>
> - **API 地址**：服务商提供的 API 基础地址。
> - **API Key**：模型服务的密钥。
> - **模型名称**：希望使用的模型。
>
> 不清楚的项目可以写“不知道”；也可以提供模型服务商名称或网站，我会协助查找。

根据服务商说明确定接口格式。当前支持 `chat_completions`、`responses` 和 `anthropic_messages`；用户无需理解这些名称。API 地址填写基础地址，不包含 `/chat/completions`、`/responses` 或 `/messages` 等完整接口路径。远程服务使用 HTTPS，本机服务可以使用 HTTP。

模型名称未知时，按服务商支持的方式查询可用模型，再让用户选择。API Key 尚未提供时，保留待填写状态，不宣称模型配置已经完成。用户希望直接在软件中填写密钥时，完成其余配置并明确剩余步骤。

可以继续询问可选的机器人说话风格，将回答用于系统提示词；留空采用软件默认设置。

### 通用设置

将以下可选项合并为一次询问：

> 还有几个可选设置，不填写就使用默认值：
>
> - **群聊回复方式**：默认仅响应 @；需要响应所有消息时请说明。
> - **机器人昵称**：填写微信中实际使用的昵称，可留空。
> - **开机启动 AstrWeChat 软件**：默认关闭，需要时请说明。

这里只控制软件开机启动，不承诺开机后已经登录微信或自动启动 Bridge。保留已有会话过滤和发送设置，除非用户明确要求修改。

## 检查和安装软件

1. 检测 Windows 版本、架构、已有安装位置、当前用户的数据目录和 Python。本文面向 Windows 软件版；根据最新正式版本的发行说明核实系统要求，并选择与本机架构匹配的安装包。
2. 打开 [最新正式版本](https://github.com/CMKH1337/Astrwechat/releases/latest)，核实 GitHub 当前标记的最新正式发行，读取版本号、发行标签、发行说明及 Windows 安装资产。草稿和预发布版本不作为默认安装目标；不要根据旧文档、记忆或源码中的版本号推断最新版本。记录本次实际选定的版本和安装资产，后续安装、依赖准备和配置均使用同一版本。已安装相同版本时复用，旧版先备份配置再更新；本机已有更新版本时不自动降级。无法核实最新正式版本或缺少匹配安装包时，说明原因，不猜测下载地址或自动改装旧版。
3. 下载软件安装包。发行资产提供 SHA256 时核对哈希；核对实际安装版本，不以文件名作为唯一依据。安装版包含 Electron 和原生运行文件，用户不需要安装 Node.js 或编译源码。
4. 使用 PowerShell 7 执行安装及配置操作。当前安装器要求管理员权限，并包含运行库提示框；按实际情况处理安装提示和系统权限确认。安装进程退出后检查结果，不能仅因传入静默参数就认定安装成功。
5. 找到安装目录中的 `AstrWeChat.exe` 和 `resources\bridge`。从卸载登记或现有快捷方式确定路径，不假设安装在固定目录。
6. 检查 Bridge 实际会使用的 Python 和依赖。现有查找顺序为内置 `resources\bridge\python\python.exe`、`WEFLOW_BRIDGE_PYTHON` 或 `PYTHON` 指定路径、当前用户的 Python310 默认安装路径，最后为 `python` 命令。使用该解释器安装软件包中 `resources\bridge\requirements.txt` 的依赖，并检查模块能否导入。

Python 版本及随包模型依赖的兼容范围，以本次选定的正式版本为准；先检查发行说明和安装包，不固定使用某个 Python 版本。需要补充 Python 时使用与软件包兼容的解释器。若通过环境变量指定解释器，确保用户日后正常启动软件时也能使用相同设置；不能只在 agent 的临时终端中配置。复用现有环境时避免升级其他项目的依赖。

安装和写入配置使用对应用户的目录。管理员安装账户与日常微信使用账户不同时，以日常使用账户的数据目录为准。

## 写入软件配置

优先使用本次选定版本实际提供的配置导入或命令入口；没有这类入口时，再使用软件界面和本机配置文件。以下配置路径和字段需对照同版本实现核实，不假设旧版本行为始终不变。

### 找到配置并备份

Windows 用户配置位于：

| 文件 | 用途 |
| --- | --- |
| `%APPDATA%\weflow\WeFlow-config.json` | 软件设置、微信连接及本地 API 设置 |
| `%APPDATA%\weflow\bridge\config.json` | AstrBot 或模型 API 配置、群聊回复设置 |

`%APPDATA%` 对应实际使用软件的用户。安装目录下的 `resources\bridge` 存放程序文件，不是正常使用时的用户配置目录。

写入前正常退出 AstrWeChat，确认其 Bridge 也已退出，防止程序缓存覆盖刚修改的文件。已有配置先创建带时间的备份，再读取并合并本次变更。配置损坏时保留原文件，检查有效备份；无法恢复时说明需要重新填写的内容。

第一次部署没有 Bridge 配置时，优先由软件生成默认配置；需要模板时，从本次发行标签对应的源码中找到 `shared/bridge-default-config.json` 或该版本实际使用的模板，保留其中所有默认字段。不要使用旧版本或默认分支上与安装包版本不同的模板。首次没有主配置时，由软件初始化，或通过软件设置界面保存需要变更的项目。

写入使用 UTF-8 编码，先在同目录写临时文件，确认 JSON 有效后替换目标文件。配置备份同样包含用户密钥，不上传仓库，也不在日志或对话中打印密钥内容。

### 按回答更新字段

| 用户选择或回答 | Bridge 配置字段 | 写入规则 |
| --- | --- | --- |
| 连接 AstrBot | `bot_backend` | `astrbot` |
| AstrBot 连接地址 | `astrbot_ob_url` | 已确认的完整 `ws://` 或 `wss://` 地址 |
| AstrBot Token | `astrbot_ob_token` | 用户填写的 Token；明确未设置时为空字符串 |
| 直接使用模型 API | `bot_backend` | `builtin` |
| 模型接口格式 | `builtin_protocol` | 根据服务商说明确定 |
| API 基础地址 | `builtin_base_url` | 用户确认的基础地址 |
| API Key | `builtin_api_key` | 用户填写的密钥 |
| 模型名称 | `builtin_model` | 用户选择的模型标识 |
| 可选的说话风格 | `builtin_system_prompt` | 用户填写的提示词 |
| 群聊回复方式 | `group_reply_mode` | 仅响应 @ 为 `mention`，响应所有消息为 `all` |
| 机器人昵称 | `bot_nicknames` | 字符串数组；填写多个昵称时分别保存 |

已有安装中，用户未要求变更的可选项保留原值；首次部署使用默认值。开机启动写入主配置的 `launchAtStartup`，按用户回答保存；首次默认关闭。

保留主配置中的微信数据库密钥和已加密字段。首次登录和获取密钥交给用户，不在问卷中收集微信密码、数据库密钥或微信数据目录。

Bridge 的 `weflow_base_url`、`access_token` 和 `bot_wxid` 由软件根据微信连接及本地服务设置同步。沿用程序管理方式，不自行编造微信 ID、复制主配置中的加密 Token 或独立改动这三个字段。微信连接后启动 Bridge，软件会准备本地 API、Token 和消息推送。

## 验证并告诉用户下一步

安装配置完成后检查：

- 已确认实际安装版本与本次查到的最新正式版本一致，记录软件安装位置和主程序，正常启动时没有安装错误。
- Bridge 实际使用的 Python 可用，必要依赖可以导入。
- JSON 可解析，所选接入方式和用户填写的字段已保存；重新打开软件后设置能正确显示。
- AstrBot 地址格式正确，或模型 API 必填项及接口格式符合软件要求。网络连接检查的结果单独说明，不把地址格式正确当成已连接成功。

仅在微信已经连接且用户要求启动时，再检查本地 API、消息推送和 Bridge 状态。`/health` 仅代表本地 HTTP 服务存活，不能证明微信已连接或机器人已经能回复。真实微信收发由用户决定是否测试，不自动向联系人或群聊发消息。

最终用简短中文报告实际安装的版本号和配置结果，并区分以下状态：

| 实际结果 | 告知用户 |
| --- | --- |
| 安装和必要配置均完成，微信尚未连接 | AstrWeChat 已安装，AstrBot／模型 API 配置已保存。请打开软件，按提示完成微信首次登录和连接。 |
| 部分必填配置尚未提供 | 说明已完成的项目和仍需填写的项目，不宣称配置完成。 |
| 用户已连接微信，并且已检查 Bridge 或模型状态 | 分别报告已验证的连接状态和仍未验证的部分。 |
| 安装或配置失败 | 说明失败步骤、已保留的配置及可以继续采取的操作。 |

## 配置依据

先根据本次选定的发行标签获取同版本源码，再查找下列文件；仓库目录或文件名发生变化时，以该版本实际结构为准。不要固定使用旧版本目录，也不要将默认分支上的新代码当作已安装版本的配置依据。

| 同版本源码中的文件 | 需要核实的行为 | 对应部署步骤 |
| --- | --- | --- |
| `package.json`、`installer.nsh` 或该版本的安装入口 | 安装资产、系统要求、权限及运行库处理 | 检测安装环境并检查真实安装结果 |
| `electron/main.ts`、`electron/services/config.ts` | 用户数据目录及敏感字段保存方式 | 按实际用户找到配置并保留已有字段 |
| `electron/services/bridgeConfigStore.ts`、`electron/services/bridgeWechatSource.ts` | 用户配置、备份及微信侧字段同步 | 合并配置并让软件管理微信连接信息 |
| `shared/bridge-connection.ts`、`electron/services/bridgeManager.ts` | 接入字段规则和实际使用的解释器 | 验证表单内容及 Bridge 依赖 |
| `bridge/builtin_model.py`、`electron/services/httpService.ts` | Python 兼容范围及健康检查范围 | 区分安装配置完成和运行连接成功 |