# 万相大师微信小程序开发器使用指引

可以先了解能力、设计页面，再按下面顺序开通真实接入。已经有账号、工程和有效连接时，直接继续原任务。

## 先了解能做什么

开发器帮助你用 WorkBuddy 制作微信原生小程序，接入绑定 XApp 的万相账号、逻辑表、文本智能体，以及服务号的商品、会员查询和授权文件下载。支持预约报名、门店咨询、会员服务和业务记录等页面。万相私有 OSS 保存小程序源码版本，微信保存并分发上传后的运行包。

XApp 页面使用浏览器 Bridge，小程序页面使用原生万相 SDK。两端共用业务账号和后端权限。小程序顾客第一次使用万相能力时验证手机号，后续用当前小程序的微信身份登录。

## 第一步，在万相准备账号和开发密钥

1. 打开 [万相大师](https://x.wanxiangdashi.com/)，用本人手机号注册或登录。已有服务号绑定可以继续沿用。
2. 打开 [开发中心](https://x.wanxiangdashi.com/page/developer/developer.html?tab=connect)，进入「开发秘钥」。创建或选择有效密钥，开启「允许管理运营中心」，保留 XApp 开发所需的读取、写入、发布和逻辑表权限。
3. 下载密钥 TXT，在 WorkBuddy 中拖入文件，并发送「请连接这个万相开发密钥，然后继续我的小程序需求」。插件会通过固定脚本读取文件、验证权限并保存连接。用户自行粘贴也可以，宿主通过标准输入配置。
4. 已连接 XApp 开发器或微信智能体分身设计器时，可复用本机同一万相连接。插件通过实际接口确认权限。连接失败时核对密钥、当前账号和运营中心权限。

## 第二步，在微信注册自己的小程序

1. 打开 [微信公众平台](https://mp.weixin.qq.com/)，在注册入口选择「小程序」，按实际主体完成邮箱、管理员和主体信息登记。已有长期使用的小程序账号直接登录。
2. 管理员在目标小程序后台的「开发 → 开发管理 → 开发设置」取得小程序 AppID 和 AppSecret。新版后台也可从开发者平台进入目标小程序的开发设置，以实际界面为准。
3. AppSecret 由管理员在万相运营中心填写。已有其他系统使用时，重置前先了解影响。微信代码上传密钥在使用官方 CI 时由开发者保存在本机。
4. WorkBuddy 临时试用版适合看页面效果。其官方说明注明试用版没有 AppSecret，接入本开发器的万相运行能力需使用自己的小程序账号。 [微信开发起步](https://developers.weixin.qq.com/miniprogram/dev/framework/quickstart/getstart.html) · [WorkBuddy 小程序说明](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/App-Publishing/Mini-Program)

## 第三步，在万相运营中心登记并绑定

1. 打开 [运营中心 → 微信小程序](https://x.wanxiangdashi.com/page/admin/tenant_center.html?tab=miniprograms)，选择已经接入万相的服务号，点击「添加已有小程序」。
2. 在「登记凭证」填写名称、小程序 AppID 和 AppSecret，点击「验证并登记」。可以先登记，稍后再选 XApp。
3. 按「放行域名」显示的地址，在微信小程序后台设置 `request` 合法域名。生产环境通常是 `https://x.wanxiangdashi.com`。需要下载私有文件或公开素材时，把向导显示的实际域名分别添加到 `downloadFile`。微信要求 API IP 白名单时添加向导显示的服务器出口 IP。
4. 在「绑定 XApp」选择同一服务号下，或同租户尚未挂载且有权管理的已发布 XApp。按需开启数据库、智能体、商品和会员、私有文件，再启用并保存。
5. 缺少合适的 XApp 时，先在开发中心使用 XApp 开发器准备、发布一个可管理的应用，再回到向导选择。现有接入保留一个 XApp 对应一个小程序的约束。

普通服务号可以继续使用既有登录。小程序顾客首次通过手机号验证码关联本人万相账号，数据和权限按该账号处理。服务号 OpenID 和小程序 OpenID 各自存在，平台用手机号关联万相账号。

## 第四步，在 WorkBuddy 开发

1. 在 [开发中心 → 微信小程序](https://x.wanxiangdashi.com/page/developer/developer.html?tab=miniprograms) 下载开发器 ZIP。在 WorkBuddy 左侧打开「专家·技能·连接器 → 技能 → 添加技能 → 上传技能」导入。
2. 在 WorkBuddy「代码开发 → 小程序」提出需求，或从开发中心复制目标小程序的任务。已有工程继续使用原工程。
3. 宿主读取工程 `project.config.json` 的 AppID，调用 `miniprogram_project_get` 核对实际服务号、XApp、能力、域名和云端版本。接入前先读 SDK 指引和工具参数。
4. 将万相原生 SDK 和 XAUI 样式写入本次小程序工程。使用 SDK 完成微信登录、首次手机号验证、逻辑表读写、智能体会话以及已启用的商品和文件能力。
5. 保存工程到万相私有 OSS。跨设备接续时拉取指定版本到新目录，核对后再编辑。开发器会记录本机源码基准，遇到冲突先比较再合并。

## 第五步，体验和发布

1. 固定一份云端源码和微信版本号，导出可导入的工程目录。
2. 使用已登录的微信开发者工具打开目录，核对 AppID，关闭「不校验合法域名」调试选项，再做真机验证。特别检查手机号登录、数据库权限、智能体响应和私有文件下载。
3. 用户要求上传时，可在微信开发者工具上传，或由 WorkBuddy 使用本机已登录的官方 CLI 上传。之后在微信公众平台「版本管理」设置体验成员、提审和发布。认证、备案、类目、隐私指引及其他行业条件以微信提示为准。
4. 想用 WorkBuddy 的分享面板时，在小程序卡片右侧预览的「分享 → 绑定已有小程序账号」用管理员微信扫码，并核对代发布渠道中实际生效的万相合法域名。
5. 完成时核对「源码已保存」「源码已固定」「微信已上传」「已提审」「已发布」各阶段记录。 [微信发布流程](https://developers.weixin.qq.com/miniprogram/dev/framework/quickstart/release.html) · [官方 CLI](https://developers.weixin.qq.com/miniprogram/dev/devtools/cli.html)

## 后续更新

在 WorkBuddy 发送「请更新万相大师微信小程序开发器的提示词和工具说明」。插件会检查、校验并保存最新指南、案例、工具 schema 和工程模板，再读取新规则。宿主按目标工程应用新的 SDK 源码。固定本地脚本保留权限边界，网络受限时继续使用已校验缓存或随包指引。