更新记录

1.2.0（2026-10-15） 下载此版本

多语言支持：SDK 内置中文文案，接入方按 Android strings.xml / iOS XML 同构格式 提供 st_* 同名文案覆盖即可切换语言，未覆盖条目自动回落中文，两端共用同一份翻译清单 新增自动点数开关：结果页加载图片后，无手动标记点时自动执行识别并返回结果 新增服务地址配置：支持自定义识别服务地址（协议+域名+端口） 新增暗黑模式设置：默认 / 浅色 / 深色三档

平台兼容性

uni-app(4.24)

shantu-countsdk 图片计数插件

shantu-countsdk 是面向 uni-app App 端的图片计数插件：宿主传入配置后调用相机或相册，插件内部完成选图、主体框选、遮盖笔涂抹、AI 识别计数与结果编辑，最终通过回调把结果图和各标签数量返回给宿主。

• 插件 ID：shantu-countsdk（v1.2.0）
• 技术栈：Vue 3 + TypeScript，uni-app uni_modules 规范
• 运行环境：App（Android / iOS / 鸿蒙）；核心图片能力依赖 HTML5+ plus API，不支持 H5 与小程序
• 识别接口：POST {base_url}/ai/distinguish_v3，默认服务地址 https://openapi.zhunmou.com

环境要求

• HBuilderX / uni-app 编译器 ^3.6.9：Vue 3 <script setup> 页面要求 3.2+，3.6.9 起全部功能无降级；鸿蒙端识别流程需 HBuilderX 4.23+
• Android 或 iOS 真机/模拟器（H5 端无法运行完整流程）
• 有效的 AccessKey / AccessSecret（自动识别模式需要）

低于 3.6.9 时插件仍可运行，但主题能力降级：osTheme 需 uni-app 3.4.10+，Android 端 uni.onThemeChange 需 3.6.9+。相关读取均有守卫，未达标时自动模式按浅色渲染、不实时跟随系统主题切换。

安装

1. 将整个 shantu-countsdk 目录复制到宿主工程的 src/uni_modules/ 下。
2. 页面路由无需手动配置：插件自带的 pages_init.json 声明了三个页面（main_body、covering_pen、count_result），编译时自动合并进宿主路由。
3. 在宿主 manifest.json 中确认相机、相册、存储权限：

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.CAMERA\"/>",
          "<uses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\"/>",
          "<uses-permission android:name=\"android.permission.WRITE_EXTERNAL_STORAGE\"/>"
        ]
      },
      "ios": {
        "privacyDescription": {
          "NSCameraUsageDescription": "用于拍照识别物品数量",
          "NSPhotoLibraryUsageDescription": "用于选择图片进行物品数量识别",
          "NSPhotoLibraryAddUsageDescription": "用于保存识别结果图片"
        }
      }
    }
  }
}

快速开始

import { initCountPlugin, openCountCamera, openCountAlbum } from '@/uni_modules/shantu-countsdk'

// 每次冷启动后、调用 open* 之前先初始化（回调不持久化，必须重新注册）
initCountPlugin(
  {
    encrypt_mode: 1,
    access_key: '你的 AccessKey',
    access_secret: '你的 AccessSecret',
    mode_type: 1,
    main_body: 1,
    auto_identify: true
  },
  {
    onSuccess: (payload) => {
      // payload.image: 标注后的结果图临时路径
      // payload.num:   [{ cls: 类别ID, count: 数量 }]
      console.log(payload.image, payload.num)
    },
    onCancel: () => {
      // 用户在插件页面直接退出
    },
    onError: (error) => {
      // 识别失败等错误，error.message 可直接展示
    }
  }
)

// 打开相机或相册
openCountCamera()
openCountAlbum()

说明：

• initCountPlugin(config, callbacks) 可重复调用，每次打开插件前重新调用即可更新配置。
• 配置会持久化到 uni Storage，但回调只保存在内存：冷启动后若未重新 initCountPlugin 就直接调用 openCountCamera()，插件会以空配置运行且结果无法回传。
• 手动点数模式（auto_identify: false）不调用识别接口，无需凭据。

页面流程

宿主页面
  └─ openCountCamera() / openCountAlbum()   // uni.chooseImage 选图
      └─ pages/main_body                    // 主体框选：智能框选/手动调整、遮盖笔入口、发起识别
          ├─ pages/covering_pen             // 遮盖笔：涂抹、擦除、撤销/恢复排除区域
          └─ pages/count_result             // 结果页：点数增删、标签筛选、样式调整、导出结果
              └─ onSuccess / onCancel 回调宿主

API 一览

类型 CountPluginConfig、CountPluginCallbacks、CountPluginOpenOptions、CountPluginSourceType 均从插件入口导出。

配置项（CountPluginConfig）

非法取值会在控制台输出 [点数插件] 错误的参数: ... 并回退默认值。

回调（CountPluginCallbacks）

加密与签名

SDK 内部加密（encrypt_mode: 1）

宿主直接传入 access_key / access_secret，插件在每次识别请求时自动生成签名并携带请求头 Access-Key、Timestamp（毫秒）、Signature。注意凭据会随包分发，仅建议在安全要求不高或凭据可被服务端限权时使用。

外部加密（encrypt_mode: 0，生产推荐）

凭据不出现在客户端包内，由宿主实现 getExternalSignature 返回签名（可从宿主服务端获取，或复用插件工具在本地生成）：

import { initCountPlugin } from '@/uni_modules/shantu-countsdk'
import { createSignature } from '@/uni_modules/shantu-countsdk/utils/signature'

initCountPlugin(
  { encrypt_mode: 0, mode_type: 1 },
  {
    async getExternalSignature() {
      const accessKey = '...'
      const accessSecret = '...' // 建议由宿主安全模块/服务端提供
      const timestamp = Date.now()
      return { timestamp, accessKey, signature: createSignature(accessSecret, timestamp) }
    }
  }
)

签名算法（与插件内部实现一致，也可在服务端实现后下发）：

stringToSign = `${timestamp}\n${accessSecret}`        // timestamp 为毫秒
signature    = encodeURIComponent(base64(HMAC-SHA256(accessSecret, stringToSign)))

服务端校验时间窗为 10 秒（超时返回 err_code: 1002），请保证设备时钟准确、签名即用即生成。

识别接口与错误码

插件内部调用 POST {base_url}/ai/distinguish_v3，请求体：

{
  "image_base64": "...",
  "mode_type": 1,
  "main_body": { "x": 0, "y": 0, "w": 0, "h": 0 }
}

main_body 为关闭主体框选时手动框选的区域（自动框选/关闭时可能为 null）。err_code 非 0 时通过 onError 返回，文案已内置映射：

网络层失败统一报「网络出小差」，未知错误码回退服务端 err_msg。

识别模型（mode_type）

示例宿主内置的模型编号（实际可用模型以识别服务端支持范围为准）：

1 钢管、2 钢筋、3 盘口横杆、4 方木、5 快拆架、6 圆木、7 方管、8 布料卷、9 轮扣、10 珍珠、69 蚕卵分类、139 圆扁竹签、157 槽楔

多标签与标注样式

标签：tags 数组元素为 { title: string, color: string, cls: number }，color 建议使用 '#RRGGBB'。数组长度大于 1 时自动切换多标签模式；最多取前 8 个；为空或未传时为单标签模式。结果 payload.num 中的 cls 即此处传入的 cls。

自定义标注样式（preset_point_styles: 2 时生效）：

custom_point_style: {
  point_color: '#87D13F',            // 已识别点颜色，默认 '#87D13F'
  add_point_color: '#FF0000',        // 手动补点颜色，默认 '#FF0000'
  point_opacity: 100,                // 透明度 0-100，默认 100
  point_shape: 2,                    // 形状：1 方形，2 圆形，默认 2
  point_identifier_enabled: false    // 是否显示点编号，默认 false
}

自定义文案（strings_xml）

传入 strings.xml 格式的 XML 片段，按 key 覆盖内置中文，可只覆盖部分 key：

strings_xml: '<string name="st_confirm">OK</string><string name="st_cancel">Cancel</string>'

可覆盖的内置 key（st_error_1001~st_error_1007 同样可覆盖）：

注意事项

• 凭据安全：不要把真实 AccessKey / AccessSecret 提交到仓库；生产环境优先使用 encrypt_mode: 0 外部签名，由宿主服务端下发短期签名。
• 平台限制：图片读取、缩放与 Base64 转换依赖 plus，完整流程仅能在 App 端验证；H5 与小程序端不可用。
• App 端自动深色模式：dark_mode: 0 要生效，宿主需在 manifest 中开启 App 暗黑模式（iOS 还需将应用主题设为「跟随系统」），否则自动模式恒为浅色。
• 临时路径：onSuccess 返回的 image 是应用沙盒临时文件，需要在宿主侧持久化（如 uni.saveFile）。
• base_url：自建服务时传入完整前缀（含端口与路径），末尾不带 /；插件会拼接 /ai/distinguish_v3。