@open-dy/vibecoding-sdk-taro 0.0.1-beta.1

package/dist/reference/sdk-api/runtime/createMicroappClient.md

@@ -0,0 +1,378 @@
+# createMicroappClient
+
+<!-- Generated by build/src/sdk-reference/skill-reference.ts. Do not edit. -->
+
+导入路径：`@open-dy/vibecoding-sdk-taro/runtime`
+源码：`src/runtime/default-client.ts`
+
+#### 说明
+
+创建普通小程序的网络入口；SDK 自动绑定项目 Taro 运行时。
+
+参数：
+
+| 名称 | 说明 |
+| --- | --- |
+| `options` | 平台渠道配置；默认使用内场渠道。 |
+
+返回：提供普通网络方法，以及显式追加 X-Closed-Domain 标记的对应方法；标记方法不改变请求目标或云服务 SERVICE_ID。
+
+备注：业务优先从模板的 @/network 导入 Network；HTTP(S) 绝对地址直接交给 Taro。
+
+示例：
+
+```ts
+const Network = createMicroappClient({ platformChannel: 'ext' })
+const response = await Network.request({ url: '/api/products', method: 'GET' })
+```
+
+#### AI 使用约束
+
+| 规则 | 内容 |
+| --- | --- |
+| 意图 | 创建绑定默认 Taro 实例的普通小程序 Network。 |
+| 适用时机 | 业务代码需要统一调用普通小程序的 request、uploadFile、downloadFile 或 streamSse 时。 |
+| 避免 | 不要在页面中直接调用 Taro.request，也不要传入 OpenCard 的 taro 实例。 |
+| 示例 | `const Network = createMicroappClient({ platformChannel: 'ext' })` |
+
+#### 声明
+
+```ts
+function createMicroappClient(options?: CreateMicroappClientOptions);
+```
+
+### createMicroappClient 的类型契约
+
+#### 工厂签名
+
+```ts
+(options?: CreateMicroappClientOptions): { request: <T = any, U = any>(option: Taro.request.Option<T, U>) => Taro.RequestTask<T>;
+  requestClosedDomain: <T = any, U = any>(option: Taro.request.Option<T, U>) => Taro.RequestTask<T>;
+  uploadFile: (option: Omit<Taro.uploadFile.Option, "url" | "name"> & { url?: string; name?: string; }) => ReturnType<typeof Taro.uploadFile>;
+  uploadFileClosedDomain: (option: Omit<Taro.uploadFile.Option, "url" | "name"> & { url?: string; name?: string; }) => ReturnType<typeof Taro.uploadFile>;
+  downloadFile: (option: Omit<Taro.downloadFile.Option, "url"> & { url?: string; }) => ReturnType<typeof Taro.downloadFile>;
+  downloadFileClosedDomain: (option: Omit<Taro.downloadFile.Option, "url"> & { url?: string; }) => ReturnType<typeof Taro.downloadFile>;
+  streamSse: (option: { url: string; method?: string; data?: unknown; header?: Record<string, unknown>; onMessage(frame: string): void; onError?(error: Error): void; onComplete?(): void; }) => Promise<{ close: () => void; }>;
+  streamSseClosedDomain: (option: { url: string; method?: string; data?: unknown; header?: Record<string, unknown>; onMessage(frame: string): void; onError?(error: Error): void; onComplete?(): void; }) => Promise<{ close: () => void; }>; }
+```
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| options | `CreateMicroappClientOptions` | 平台渠道配置；默认使用内场渠道。 |
+
+##### options 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| platformChannel? | `"" \| "ext" \| undefined` | 平台渠道：空字符串为内场，ext 为外场；默认空字符串。 |
+
+#### 返回值
+
+- 类型:
+
+```ts
+{ request: <T = any, U = any>(option: Taro.request.Option<T, U>) => Taro.RequestTask<T>;
+  requestClosedDomain: <T = any, U = any>(option: Taro.request.Option<T, U>) => Taro.RequestTask<T>;
+  uploadFile: (option: Omit<Taro.uploadFile.Option, "url" | "name"> & { url?: string; name?: string; }) => ReturnType<typeof Taro.uploadFile>;
+  uploadFileClosedDomain: (option: Omit<Taro.uploadFile.Option, "url" | "name"> & { url?: string; name?: string; }) => ReturnType<typeof Taro.uploadFile>;
+  downloadFile: (option: Omit<Taro.downloadFile.Option, "url"> & { url?: string; }) => ReturnType<typeof Taro.downloadFile>;
+  downloadFileClosedDomain: (option: Omit<Taro.downloadFile.Option, "url"> & { url?: string; }) => ReturnType<typeof Taro.downloadFile>;
+  streamSse: (option: { url: string; method?: string; data?: unknown; header?: Record<string, unknown>; onMessage(frame: string): void; onError?(error: Error): void; onComplete?(): void; }) => Promise<{ close: () => void; }>;
+  streamSseClosedDomain: (option: { url: string; method?: string; data?: unknown; header?: Record<string, unknown>; onMessage(frame: string): void; onError?(error: Error): void; onComplete?(): void; }) => Promise<{ close: () => void; }>; }
+```
+
+##### 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| request | `<T = any, U = any>(option: Taro.request.Option<T, U>) => Taro.RequestTask<T>` | 发起请求并复用 SDK 管理的身份与当前应用服务配置。 |
+| requestClosedDomain | `<T = any, U = any>(option: Taro.request.Option<T, U>) => Taro.RequestTask<T>` | 发起请求并追加 X-Closed-Domain 标记；不改变请求目标或云服务 SERVICE_ID。 |
+| uploadFile | `(option: Omit<Taro.uploadFile.Option, "url" \| "name"> & { url?: string; name?: string; }) => ReturnType<typeof Taro.uploadFile>` | 上传文件并返回平台上传结果。 |
+| uploadFileClosedDomain | `(option: Omit<Taro.uploadFile.Option, "url" \| "name"> & { url?: string; name?: string; }) => ReturnType<typeof Taro.uploadFile>` | 上传文件并追加 X-Closed-Domain 标记；不改变请求目标或云服务 SERVICE_ID。 |
+| downloadFile | `(option: Omit<Taro.downloadFile.Option, "url"> & { url?: string; }) => ReturnType<typeof Taro.downloadFile>` | 下载文件并返回平台下载结果。 |
+| downloadFileClosedDomain | `(option: Omit<Taro.downloadFile.Option, "url"> & { url?: string; }) => ReturnType<typeof Taro.downloadFile>` | 下载文件并追加 X-Closed-Domain 标记；不改变请求目标或云服务 SERVICE_ID。 |
+
+- `streamSse`
+
+```ts
+(option: { url: string; method?: string; data?: unknown; header?: Record<string, unknown>; onMessage(frame: string): void; onError?(error: Error): void; onComplete?(): void; }) => Promise<{ close: () => void; }>
+```
+说明：建立服务端事件流并返回可关闭的流句柄。
+- `streamSseClosedDomain`
+
+```ts
+(option: { url: string; method?: string; data?: unknown; header?: Record<string, unknown>; onMessage(frame: string): void; onError?(error: Error): void; onComplete?(): void; }) => Promise<{ close: () => void; }>
+```
+说明：建立带 X-Closed-Domain 标记的服务端事件流；不改变请求目标或云服务 SERVICE_ID。
+
+#### createMicroappClient().request
+
+发起请求并复用 SDK 管理的身份与当前应用服务配置。
+
+##### 签名
+
+```ts
+<T = any, U = any>(option: Taro.request.Option<T, U>): Taro.RequestTask<T>
+```
+
+##### 参数
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| option | `Taro.request.Option<T, U>` | 请求、上传或下载的配置对象。 |
+
+###### option 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| url | `string` | 开发者服务器接口地址 |
+| data? | `U \| undefined` | 请求的参数 |
+| header? | `TaroGeneral.IAnyObject \| undefined` | 设置请求的 header，header 中不能设置 Referer。 `content-type` 默认为 `application/json` |
+| timeout? | `number \| undefined` | 超时时间，单位为毫秒 |
+| method? | `keyof Taro.request.Method \| undefined` | HTTP 请求方法 |
+| dataType? | `string \| undefined` | 返回的数据格式 |
+| responseType? | `keyof Taro.request.ResponseType \| undefined` | 响应的数据类型 |
+| useHighPerformanceMode? | `boolean \| undefined` | 使用高性能模式。从基础库 v3.5.0 开始在 Android 端默认开启，其他端暂不生效。该模式下有更优的网络性能表现。 |
+| enableHttp2? | `boolean \| undefined` | 开启 http2 |
+| enableQuic? | `boolean \| undefined` | 开启 quic |
+| enableCache? | `boolean \| undefined` | 开启 cache |
+| enableHttpDNS? | `boolean \| undefined` | 是否开启 HttpDNS 服务。如开启，需要同时填入 httpDNSServiceId 。 HttpDNS 用法详见 移动解析HttpDNS |
+| httpDNSServiceId? | `string \| undefined` | HttpDNS 服务商 Id。 HttpDNS 用法详见 移动解析HttpDNS |
+| enableChunked? | `boolean \| undefined` | 开启 transfer-encoding chunked。 |
+| forceCellularNetwork? | `boolean \| undefined` | wifi下使用移动网络发送请求 |
+| enableCookie? | `boolean \| undefined` | headers 中设置 cookie 字段是否生效。如果为 false，则 headers 中的 cookie 字段将被忽略，请求头中将包含服务端上一次返回的 cookie（如果有）。 |
+| referrerStrategy? | `keyof Taro.request.ReferrerStrategy \| undefined` | referer 策略，用于控制当前请求 header 对象中 referer 字段格式。该参数默认值可通过 app.json 中的配置进行修改。 |
+| success? | `((result: Taro.request.SuccessCallbackResult<T>) => void) \| undefined` | 接口调用成功的回调函数 |
+| fail? | `((res: TaroGeneral.CallbackResult) => void) \| undefined` | 接口调用失败的回调函数 |
+| complete? | `((res: Partial<Taro.request.SuccessCallbackResult> & TaroGeneral.CallbackResult) => void) \| undefined` | 接口调用结束的回调函数（调用成功、失败都会执行） |
+| jsonp? | `string \| boolean \| undefined` | 设置是否使用 jsonp 方式获取数据 |
+| jsonpCache? | `RequestCache \| undefined` | 设置 jsonp 请求 url 是否需要被缓存 |
+| mode? | `keyof Taro.request.CorsMode \| undefined` | 设置是否允许跨域请求 |
+| credentials? | `keyof Taro.request.Credentials \| undefined` | 设置是否携带 Cookie |
+| cache? | `keyof Taro.request.Cache \| undefined` | 设置缓存模式 |
+| retryTimes? | `number \| undefined` | 设置请求重试次数 |
+| backup? | `string \| string[] \| undefined` | 设置请求的兜底接口 |
+| signal? | `AbortSignal \| undefined` | 设置请求中止信号 |
+| dataCheck? | `(() => boolean) \| undefined` | 设置请求响应的数据校验函数，若返回 false，则请求兜底接口，若无兜底接口，则报请求失败 |
+| useStore? | `boolean \| undefined` | 设置请求是否使用缓存 |
+| storeCheckKey? | `string \| undefined` | 设置请求缓存校验的 key |
+| storeSign? | `string \| undefined` | 设置请求缓存签名 |
+| storeCheck? | `(() => boolean) \| undefined` | 设置请求校验函数，一般不需要设置 |
+
+##### 返回值
+
+- 类型：`Taro.RequestTask<T>`
+- Promise resolve 类型：`Taro.request.SuccessCallbackResult<T>`
+
+###### 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| data | `T` | 开发者服务器返回的数据 |
+| header | `TaroGeneral.IAnyObject` | 开发者服务器返回的 HTTP Response Header |
+| statusCode | `number` | 开发者服务器返回的 HTTP 状态码 |
+| errMsg | `string` | 调用结果 |
+| cookies? | `string[] \| undefined` | cookies |
+
+#### createMicroappClient().requestClosedDomain
+
+发起请求并追加 X-Closed-Domain 标记；不改变请求目标或云服务 SERVICE_ID。
+
+参数和返回字段结构同 `createMicroappClient().request`；该方法只改变服务域。
+
+##### 签名
+
+```ts
+<T = any, U = any>(option: Taro.request.Option<T, U>): Taro.RequestTask<T>
+```
+
+##### 返回值
+
+- 类型：`Taro.RequestTask<T>`
+- Promise resolve 类型：`Taro.request.SuccessCallbackResult<T>`
+
+#### createMicroappClient().uploadFile
+
+上传文件并返回平台上传结果。
+
+##### 签名
+
+```ts
+(option: Omit<Taro.uploadFile.Option, "url" | "name"> & { url?: string; name?: string; }): ReturnType<typeof Taro.uploadFile>
+```
+
+##### 参数
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| option | `Omit<Taro.uploadFile.Option, "url" \| "name"> & { url?: string; name?: string; }` | 请求、上传或下载的配置对象。 |
+
+###### option 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| filePath | `string` | 要上传文件资源的路径 |
+| header? | `TaroGeneral.IAnyObject \| undefined` | HTTP 请求 Header，Header 中不能设置 Referer |
+| formData? | `TaroGeneral.IAnyObject \| undefined` | HTTP 请求中其他额外的 form data |
+| timeout? | `number \| undefined` | 超时时间，单位为毫秒 |
+| fileName? | `string \| undefined` | 上传的文件名 |
+| withCredentials? | `boolean \| undefined` | 是否应使用传出凭据 (cookie) 发送此请求 |
+| complete? | `((res: TaroGeneral.CallbackResult) => void) \| undefined` | 接口调用结束的回调函数（调用成功、失败都会执行） |
+| fail? | `((res: TaroGeneral.CallbackResult) => void) \| undefined` | 接口调用失败的回调函数 |
+| success? | `((result: Taro.uploadFile.SuccessCallbackResult) => void) \| undefined` | 接口调用成功的回调函数 |
+| url? | `string \| undefined` | 请求地址。 |
+| name? | `string \| undefined` |  |
+
+##### 返回值
+
+- 类型：`Taro.UploadTask.UploadTaskPromise`
+- Promise resolve 类型：`Taro.uploadFile.SuccessCallbackResult`
+
+###### 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| data | `string` | 开发者服务器返回的数据 |
+| statusCode | `number` | 开发者服务器返回的 HTTP 状态码 |
+| errMsg | `string` | 调用结果 |
+| header? | `TaroGeneral.IAnyObject \| undefined` | 开发者服务器返回的 HTTP Response Header |
+| cookies? | `string[] \| undefined` | cookies |
+
+#### createMicroappClient().uploadFileClosedDomain
+
+上传文件并追加 X-Closed-Domain 标记；不改变请求目标或云服务 SERVICE_ID。
+
+参数和返回字段结构同 `createMicroappClient().uploadFile`；该方法只改变服务域。
+
+##### 签名
+
+```ts
+(option: Omit<Taro.uploadFile.Option, "url" | "name"> & { url?: string; name?: string; }): ReturnType<typeof Taro.uploadFile>
+```
+
+##### 返回值
+
+- 类型：`Taro.UploadTask.UploadTaskPromise`
+- Promise resolve 类型：`Taro.uploadFile.SuccessCallbackResult`
+
+#### createMicroappClient().downloadFile
+
+下载文件并返回平台下载结果。
+
+##### 签名
+
+```ts
+(option: Omit<Taro.downloadFile.Option, "url"> & { url?: string; }): ReturnType<typeof Taro.downloadFile>
+```
+
+##### 参数
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| option | `Omit<Taro.downloadFile.Option, "url"> & { url?: string; }` | 请求、上传或下载的配置对象。 |
+
+###### option 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| filePath? | `string \| undefined` | 指定文件下载后存储的路径 |
+| header? | `TaroGeneral.IAnyObject \| undefined` | HTTP 请求的 Header，Header 中不能设置 Referer |
+| timeout? | `number \| undefined` | 超时时间，单位为毫秒 |
+| withCredentials? | `boolean \| undefined` | 是否应使用传出凭据 (cookie) 发送此请求 |
+| complete? | `((res: TaroGeneral.CallbackResult) => void) \| undefined` | 接口调用结束的回调函数（调用成功、失败都会执行） |
+| fail? | `((res: TaroGeneral.CallbackResult) => void) \| undefined` | 接口调用失败的回调函数 |
+| success? | `((result: Taro.downloadFile.FileSuccessCallbackResult) => void) \| undefined` | 接口调用成功的回调函数 |
+| url? | `string \| undefined` | 请求地址。 |
+
+##### 返回值
+
+- 类型：`Taro.DownloadTask.DownloadTaskPromise`
+- Promise resolve 类型：`Taro.downloadFile.FileSuccessCallbackResult`
+
+###### 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| filePath | `string` | 用户文件路径。传入 filePath 时会返回，跟传入的 filePath 一致 |
+| statusCode | `number` | 开发者服务器返回的 HTTP 状态码 |
+| tempFilePath | `string` | 临时文件路径。没传入 filePath 指定文件存储路径时会返回，下载后的文件会存储到一个临时文件 |
+| errMsg | `string` | 调用结果 |
+| header? | `TaroGeneral.IAnyObject \| undefined` | 开发者服务器返回的 HTTP Response Header |
+| dataLength? | `number \| undefined` | 数据长度，单位 Byte |
+| cookies? | `string[] \| undefined` | cookies |
+| profile? | `TaroGeneral.IAnyObject \| undefined` | 网络请求过程中一些调试信息 |
+
+#### createMicroappClient().downloadFileClosedDomain
+
+下载文件并追加 X-Closed-Domain 标记；不改变请求目标或云服务 SERVICE_ID。
+
+参数和返回字段结构同 `createMicroappClient().downloadFile`；该方法只改变服务域。
+
+##### 签名
+
+```ts
+(option: Omit<Taro.downloadFile.Option, "url"> & { url?: string; }): ReturnType<typeof Taro.downloadFile>
+```
+
+##### 返回值
+
+- 类型：`Taro.DownloadTask.DownloadTaskPromise`
+- Promise resolve 类型：`Taro.downloadFile.FileSuccessCallbackResult`
+
+#### createMicroappClient().streamSse
+
+建立服务端事件流并返回可关闭的流句柄。
+
+##### 签名
+
+```ts
+(option: { url: string; method?: string; data?: unknown; header?: Record<string, unknown>; onMessage(frame: string): void; onError?(error: Error): void; onComplete?(): void; }): Promise<{ close: () => void; }>
+```
+
+##### 参数
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| option | `{ url: string; method?: string; data?: unknown; header?: Record<string, unknown>; onMessage(frame: string): void; onError?(error: Error): void; onComplete?(): void; }` | 请求、上传或下载的配置对象。 |
+
+###### option 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| url | `string` | 请求地址。 |
+| method? | `string \| undefined` | HTTP 请求方法。 |
+| data? | `unknown` | 请求负载。 |
+| header? | `Record<string, unknown> \| undefined` | 请求头。 |
+| onMessage | `(frame: string) => void` |  |
+| onError? | `((error: Error) => void) \| undefined` |  |
+| onComplete? | `(() => void) \| undefined` |  |
+
+##### 返回值
+
+- 类型：`Promise<{ close: () => void; }>`
+- Promise resolve 类型：`{ close: () => void; }`
+
+###### 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| close | `() => void` |  |
+
+#### createMicroappClient().streamSseClosedDomain
+
+建立带 X-Closed-Domain 标记的服务端事件流；不改变请求目标或云服务 SERVICE_ID。
+
+参数和返回字段结构同 `createMicroappClient().streamSse`；该方法只改变服务域。
+
+##### 签名
+
+```ts
+(option: { url: string; method?: string; data?: unknown; header?: Record<string, unknown>; onMessage(frame: string): void; onError?(error: Error): void; onComplete?(): void; }): Promise<{ close: () => void; }>
+```
+
+##### 返回值
+
+- 类型：`Promise<{ close: () => void; }>`
+- Promise resolve 类型：`{ close: () => void; }`

package/dist/reference/sdk-api/runtime/index.md

@@ -0,0 +1,10 @@
+# runtime
+
+<!-- Generated by build/src/sdk-reference/skill-reference.ts. Do not edit. -->
+
+导入路径前缀：`@open-dy/vibecoding-sdk-taro/runtime`
+
+| API | 说明 | 文档 |
+| --- | --- | --- |
+| `createMicroappClient` | 创建普通小程序的网络入口；SDK 自动绑定项目 Taro 运行时。 | [查看](./createMicroappClient.md) |
+| `CreateMicroappClientOptions` | 配置普通小程序 Network 的平台渠道。 | [查看](./CreateMicroappClientOptions.md) |