官方能不能出一份使用UTS 写 uniapp uniappx 插件的文档，让ai能看的懂的

欢迎到专业群（ uni-app 官方技术交流群 1 ） 咨询，群中有相关专业的管理员和群友。

基于知识库内容，为你整理一份可供AI学习的UTS插件开发规则文档：

一、UTS插件基础结构规范

1. 目录结构标准

uni_modules/  
├── [plugin-id]/                 # 插件根目录  
│   ├── utssdk/                  # UTS代码目录（必须）  
│   │   ├── interface.uts        # 接口定义文件（必须）  
│   │   ├── index.uts            # 主入口（可选，简单插件可放代码）  
│   │   ├── app-android/         # Android平台代码  
│   │   │   ├── index.uts        # Android平台实现  
│   │   │   ├── config.json      # Android依赖配置  
│   │   │   └── libs/            # 本地jar/aar存放目录  
│   │   ├── app-ios/             # iOS平台代码  
│   │   │   ├── index.uts        # iOS平台实现  
│   │   │   ├── config.json      # iOS依赖配置  
│   │   │   └── Plugins/         # iOS扩展组件（如Widget）  
│   │   ├── app-harmony/         # 鸿蒙平台代码  
│   │   │   ├── index.uts        # 鸿蒙平台实现  
│   │   │   └── config.json      # 鸿蒙依赖配置  
│   │   ├── web/                 # Web平台（JS实现）  
│   │   └── mp-weixin/           # 小程序平台（JS实现）  
│   ├── components/              # 组件插件目录（如为组件）  
│   └── package.json             # 插件配置（必须）

2. 文件命名与位置规则

• interface.uts：必须放在utssdk/根目录，定义对外暴露的API接口
• 平台目录：必须使用app-android、app-ios、app-harmony命名，区分大小写
• config.json：各平台目录下必须存在，用于配置原生依赖

二、interface.uts 编写规则

1. 基本结构

// 定义接口参数类型  
interface MyApiOptions {  
    paramA: boolean;  
    success?: (res: any) => void;  
    fail?: (err: any) => void;  
    complete?: (res: any) => void;  
}  

// 导出API声明（必须）  
export function myApi(options: MyApiOptions): void;  
export function myApiSync(param: boolean): string;

2. 类型导出规则

• 所有需要在Vue/UTS中使用的类型必须通过interface定义并导出
• 回调函数类型必须明确标注参数类型
• 可选参数使用?标记

三、平台实现代码规则

1. Android平台（app-android/index.uts）

依赖配置（config.json）：

{  
    "nativeDependencies": [  
        "com.example:library:1.0.0"  // Maven依赖  
    ],  
    "localDependencies": [  
        "libs/local-lib.jar"          // 本地jar，相对于app-android目录  
    ]  
}

代码规范：

// 导入Android原生类（使用@NativeClass装饰器）  
@NativeClass  
class MyPlugin {  
    // 方法必须使用@NativeMethod装饰器暴露给UTS  
    @NativeMethod  
    static myMethod(param: string): string {  
        // 此处编写Kotlin/Java逻辑  
        return "result";  
    }  
}  

// 导出实现  
export function myApi(options: MyApiOptions): void {  
    try {  
        const result = MyPlugin.myMethod(options.paramA.toString());  
        options.success?.({ data: result });  
    } catch (e) {  
        options.fail?.({ errMsg: e.message });  
    } finally {  
        options.complete?.({});  
    }  
}

重要限制：

• 涉及jar/aar依赖时，必须打包自定义基座才能真机运行
• 本地jar必须放在app-android/libs/目录下，并在config.json中引用

2. iOS平台（app-ios/index.uts）

依赖配置（config.json）：

{  
    "frameworks": [  
        "Foundation",  
        "UIKit"  
    ],  
    "cocoapods": {  
        "dependencies": [  
            "ThirdPartySDK",           // Pod依赖  
            "AnotherSDK ~> 1.0.0"  
        ]  
    }  
}

代码规范：

// 导入Swift/Objective-C类  
import { UIViewController } from 'UIKit';  

// 如果被其他插件依赖且依赖了三方库，导入时必须加断言  
import { QMapView } from 'QMapKit' assert { type: "implementationOnly" };  

// 实现代码  
export function myApi(options: MyApiOptions): void {  
    // iOS原生逻辑  
    dispatch_async(dispatch_get_main_queue(), () => {  
        // 主线程操作  
    });  
}

被其他插件依赖时的特殊规则：

• 三方库导入必须加assert { type: "implementationOnly" }
• 三方库符号不能暴露在public接口中（函数参数、返回值、class属性、继承等）
• 如需暴露，必须将对应函数或class标记为private或fileprivate

3. 鸿蒙平台（app-harmony/index.uts）

重要限制：

• 鸿蒙与App（Android/iOS）完全分离，App代码不能直接用于鸿蒙
• 必须在app-harmony目录单独实现
• 不支持app-plus相关配置

依赖配置（config.json）：

{  
    "dependencies": [  
        "@ohos/xxx"                   // 鸿蒙系统模块  
    ]  
}

代码规范：

// 导入鸿蒙原生API  
import { util } from '@ohos.util';  

// 注意：浏览器API如btoa、TextEncoder在鸿蒙不可用，需使用UTS封装  
export function base64Encode(input: string): string {  
    const base64Helper = new util.Base64Helper();  
    // 鸿蒙特定实现  
    return result;  
}

四、uni-app vs uni-app X 使用差异

1. 调用方式

uni-app（Vue/JS）：

// #ifdef APP-PLUS  
import { myApi } from '@/uni_modules/my-plugin';  
// #endif

uni-app X（UTS）：

import { myApi } from "@/uni_modules/my-plugin";

2. 类型声明（针对uni-app）

如果使用uni-app（非X），需要在插件根目录提供index.d.ts：

// uni_modules/my-plugin/index.d.ts  
declare module '@/uni_modules/my-plugin' {  
    export interface MyApiOptions {  
        paramA: boolean;  
        success?: (res: any) => void;  
    }  
    export function myApi(options: MyApiOptions): void;  
}

五、调试与打包规则

1. 运行环境要求

• Android：HBuilderX 3.6+支持本地编译，但涉及原生依赖需自定义基座
• iOS：HBuilderX 3.6.9+支持本地编译和真机运行，但首次或修改后建议打自定义基座
• 鸿蒙：必须打自定义基座

2. 打包配置

必须配置的环境：

• Android：需配置Android SDK路径（HBuilderX设置）
• iOS：需配置XCode和开发者证书
• 鸿蒙：需配置DevEco Studio

自定义基座要求：

• 包含UTS原生代码的插件，首次运行必须打自定义基座
• 修改了config.json或原生代码（kt/swift），必须重新打自定义基座
• wgt热更新只对JS/CSS生效，UTS代码修改必须重新打包

六、常见错误与解决规则

HBuilderX有定制化的AI Agent插件，用于开发uni-app/uni-appx项目，文档