V1 小程序对接指南

更新时间：2026/08/24

本小程序为设备管理、对话、语音、绑定等能力的客户端，通过调用外部 API 实现。按本说明可在全新环境中完成小程序的配置与发布。

版本：2026-08-24。

源码构成

组件	说明	调用地址
小程序端	设备管理 / 对话 / 语音 / 绑定 / 登录	微信开发者工具 + 微信公众平台
设备中枢API	设备授权、绑定/解绑/列表	api.jimitu.top/lg/mac-auth
用户登录API	微信登录换取用户 JWT（自维护用户 ID）	api.jimitu.top/lg/wx-mini/user
开放平台API	角色、会话、消息、TTS	开放平台接口文档

                    ┌──────────────────┐
                    │   微信小程序      │
                    │  (设备/对话/语音) │
                    └────────┬─────────┘
                             │ HTTPS
           ┌─────────────────┼─────────────────┐
           ▼                 ▼                 ▼
    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
    │  设备中枢API  │  │  用户登录API  │  │  开放平台API  │
    │ (api.jimitu) │  │ (api.jimitu) │  │              │
    └──────────────┘  └──────────────┘  └──────────────┘

小程序架构

目录结构

miniprogram/
├── app.ts / app.json / app.wxss   # 入口、路由/窗口/权限声明、全局样式
├── pages/                         # 页面
│   ├── login/                     # 登录页（触发微信登录 → 写入 Storage）
│   ├── tabs/index/                # 设备首页（活动设备绑定的角色详情 + 状态卡 + 编辑入口）
│   ├── tabs/chat-now/             # 对话 tab（按设备过滤的会话列表）
│   ├── tabs/settings/             # 我的（版本、绑定设备列表、设置）
│   ├── chat/                      # 聊天（消息流、TTSTTS、角色详情入口）
│   ├── device/{ble-bind,device-bind,device-info}  # 蓝牙绑定/设备码绑定/设备信息
│   └── character/character-detail # 角色详情/编辑
├── services/                      # 业务封装
│   ├── api-client.ts              # 开放平台 API（角色/会话/消息/TTS、分页/流式）
│   ├── hub.ts                     # 设备中枢 /lg/mac-auth（绑定/解绑/列表/追踪）
│   ├── user-auth.ts               # 用户登录 /auth/wx-login、/auth/me
│   ├── auth.ts                    # 鉴权状态（Storage 读写、活动设备、设备列表缓存）
│   └── bluetooth.ts               # BLE 适配器/扫描/连接/GATT（供 BLUFI 使用）
├── utils/                         # 基础能力
│   ├── constants.ts               # API 基地址/路径常量、版本
│   ├── request.ts                 # wx.request 封装（鉴权头注入、错误统一、分页解包）
│   ├── sse-request.ts             # 流式请求（消息/TTS）
│   ├── blufi/*                    # BLUFI 帧/加密/客户端（设备配网）
│   └── device-error.ts / time.ts  # 错误映射、时间格式化
├── components/{chat-bubble,icon}  # 组件
├── custom-tab-bar/                # 自定义 TabBar（设备/对话/我的）
├── config/tts-voices.ts           # TTS 音色映射
├── typings/                       # 类型定义
├── images/ / assets/previews/     # 资源（tab 图标、音色试听 mp3）
└── miniprogram_npm/               # 依赖（mobx / tdesign-miniprogram 等，打包时 npm run build 生成）

pages 由 app.json 声明路由；tabBar.custom 启用自定义 TabBar，permission 声明 scope.bluetooth 与 scope.userLocation；stores/ 当前为空（预留）。

调用链路

页面（pages/*）/ 组件
        │
        ├── services/api-client.ts ──→ utils/request.ts  ──→ 开放平台API（角色/会话/消息/TTS）
        ├── services/hub.ts        ──→ utils/request.ts  ──→ 设备中枢API（/lg/mac-auth/*）
        ├── services/user-auth.ts  ──→ utils/request.ts  ──→ 用户登录API（/lg/wx-mini/user/*）
        ├── services/bluetooth.ts + utils/blufi/*           ──→ 微信 BLE（设备配网）
        └── services/auth.ts        ──→ wx.Storage（deviceId/externalUserId/token/设备列表缓存）

request.ts 统一处理：constants.ts 的基地址拼接、auth 的鉴权头注入、错误码映射与提示；分页与业务错误按开放平台约定解包。

关键状态

• 鉴权：auth.ts 持久化 deviceId、externalUserId、miniToken，暴露 isLoggedIn 与内存缓存的设备列表；未登录时 getUserId 返回空串，调用方需先检查。
• 蓝牙：bluetooth.ts 封装适配器开关与扫描/连接/GATT，utils/blufi/* 按 BLUFI 帧格式与设备配网（2.4G、错误码映射见设备侧文档）。

蓝牙配对与绑定代码索引

以下代码索引以 demo 分支为准，按调用链查看蓝牙配对与绑定流程：

入口

miniprogram/pages/device/device-bind/index.ts:194

点击“蓝牙绑定”，跳转蓝牙页面。

页面流程

miniprogram/pages/device/ble-bind/index.ts:123

扫描设备、建立连接、获取设备 ID、WiFi 配网、确认绑定。

BLE 底层

miniprogram/services/bluetooth.ts:100

打开蓝牙、扫描、GATT 连接、订阅通知、写入数据、MTU 协商。

BLUFI 协议

miniprogram/utils/blufi/blufi-client.ts:54

解析设备通知、识别 AT+ID、处理 WiFi 状态和错误码。

BLUFI 数据发送

miniprogram/utils/blufi/blufi-client.ts:103

发送 AT+GETID 和 WiFi 配网命令。

后端绑定

miniprogram/pages/device/ble-bind/index.ts:414

用户确认设备信息后，调用 DeviceAuthClient.bind() 完成设备绑定。

后端接口封装

miniprogram/services/hub.ts:40

向后端发送 POST /bind，提交 device_id、渠道和角色信息。

前置准备

在配置小程序之前，需要先获取以下账号和凭据：

• [ ] 开放平台 API Key：申请开放平台 API Key，用于角色、会话、TTS 等接口
• [ ] 设备中枢接入密钥（mk_）：从设备中枢管理后台获取，用于小程序调用设备绑定/列表等接口
• [ ] 微信小程序 appid（在微信公众平台注册），并配置服务器域名白名单（request 合法域名：api.jimitu.top）
• [ ] 用户登录服务地址：从用户登录服务提供方获取，用于微信登录换取 JWT

重要说明

说明：开放平台的 API Key 与设备中枢的接入密钥（mk_）是两套不同的密钥，分别用于角色/会话接口与设备绑定接口，详见“获取外部 API 接入凭据”。

获取外部 API 接入凭据

开放平台 API Key

申请开放平台 API Key，用于调用角色、会话、TTS 等接口。

设备中枢接入密钥（mk_）

从设备中枢管理后台的「接入密钥」页面获取。每个部署实例独立密钥，互不可见。

用户登录服务地址

从用户登录服务提供方获取服务地址，格式通常为 https://<域名>/lg/wx-mini/user。

小程序配置

打开 miniprogram/utils/constants.ts，替换以下占位符：

export const API_BASE_URL = '<开放平台基地址>';            // 开放平台服务基地址
export const DEFAULT_API_KEY = '<你的开放平台 Key>';        // 开放平台 API Key
export const DEVICE_AUTH_BASE_URL = '<设备中枢地址>/lg/mac-auth/api'; // 设备中枢服务地址
export const MINI_AUTH_BASE_URL = '<用户登录服务地址>';       // 用户登录服务地址
export const APP_VERSION = '<与微信后台一致的版本号>';

• 删除源码中 miniprogram/config/product-config.ts（演示产品切换，正式环境不使用；如已删除可跳过）
• project.config.json 的 appid 改为你自己的
• 在微信公众平台把 api.jimitu.top 加入 request 合法域名

替换完以上 key 与地址后，小程序即完成对接，设备管理、对话、语音、绑定等功能可直接使用。

© 2026 jimitu.top · 小程序对接 · 小程序对接文档 · 更新时间 2026/08/24