@tacoreai/web-sdk 1.0.11 → 1.1.0

package/README.md

@@ -0,0 +1,404 @@
+# @tacoreai/web-sdk
+
+Tacore Web SDK for AI generated applications. This SDK provides tools to interact with Tacore's backend services for applications, including authentication, data, AI, and file storage.
+
+## Version
+1.0.15
+
+## Installation
+
+npm install @tacoreai/web-sdk
+
+## Usage
+
+### AppsAuthManager
+示例略（保持原有章节）
+
+### AppsClient (Data & AI)
+示例略（保持原有章节）
+
+---
+
+## 文件存储 API（CloudBase 通道）
+
+先确保已通过 AppsAuthManager 登录，并使用 AppsClient 初始化时提供 appId。以下接口均作用于 /apps 路由，需携带 Authorization。
+
+1) 上传文件（<=20MB）
+
+import { AppsClient } from '@tacoreai/web-sdk'
+const client = new AppsClient('YOUR_APP_ID')
+
+const input = document.querySelector('#fileInput')
+const file = input.files[0]
+const result = await client.uploadFile(file, { expires: 3600 })
+// result.data => { fileID, url, path, mimeType, size, expiresIn }
+
+2) 获取临时下载 URL
+
+const { data } = await client.getFileUrl('<fileID>', 1800)
+// data.url 为可直接访问的签名地址（有效期30分钟）
+
+3) 批量删除文件
+
+await client.deleteFiles(['<fileID1>', '<fileID2>'])
+
+4) 下载文件为 Blob（用于预览或保存）
+
+const blob = await client.downloadFile('<fileID>')
+// 例如：保存为本地文件
+const a = document.createElement('a')
+a.href = URL.createObjectURL(blob)
+a.download = 'download.bin'
+a.click()
+URL.revokeObjectURL(a.href)
+
+---
+
+## [新增] 文件上传与分析
+
+此接口用于上传文件（如 PDF、图片）以供 AI 进行深度分析或作为图片编辑的输入。
+
+### `uploadFileForAnalysis(file)`
+- **功能**: 将文件上传至 Google 的专用存储，并返回一个可供 AI 模型引用的 `fileUri`。
+- **参数**:
+  - `file` (File): 从文件输入框获取的 File 对象。
+- **返回值**: `Promise<{fileUri: string, mimeType: string, ...}>`
+
+---
+
+## 图片生成 (Apps 路由)
+
+请确保已通过 AppsAuthManager 登录，并使用 AppsClient 发起请求（会自动附带 Authorization）。
+
+### `generateImage(options)`
+- **功能**: 调用文生图服务。默认使用 Google Imagen，可按需切换。
+- **返回**: `Promise<Object>` (后端响应对象，包含 `data.uri` 或 `data.images`)
+
+#### 1. 调用 Google Imagen (默认)
+
+import { AppsClient } from '@tacoreai/web-sdk'
+const client = new AppsClient('YOUR_APP_ID')
+
+const result = await client.generateImage({
+  prompt: '一只在云端奔跑的小狗，卡通风格'
+});
+// 获取图片 URI
+const imageUri = result.data.uri;
+
+#### 2. 调用豆包 4.0 模型
+通过 `provider` 参数切换服务商。
+
+const result = await client.generateImage({
+  provider: 'volcengine', // 指定使用火山引擎
+  prompt: '一只在云端奔跑的小狗，中国水墨画风格',
+  // 可选，指定豆包模型版本，默认为 doubao-seedream-4-5-251128
+  // model: 'doubao-seedream-4-5-251128', 
+});
+const imageUri = result.data.uri;
+
+注意：
+- 计费：Apps 路由会根据 appId 自动解析组织并扣费。
+- 错误码：402（余额不足）、404（组织不存在）、500/503（外部服务异常）等。
+
+---
+
+## [更新] 图片编辑 (Google Image Edit) - Apps 路由
+
+图片编辑支持更复杂的工作流：单图编辑、双图融合（如“把衣服穿到模特身上”）、掩膜修复/扩展（Inpainting/Outpainting）。
+
+- **接口**: /agent/generate-google-image-edit
+- **方法**: `AppsClient.editImage(options)`
+- **返回**: `Promise<Object>` (后端响应对象，包含 `data.uri` 或 `data.images`)
+
+### 核心流程
+1.  **上传图片**: 所有源图片（包括底图、叠加图、掩膜图）都**必须**先通过 `uploadFileForAnalysis(file)` 上传，获取 `fileUri` 和 `mimeType`。
+2.  **调用编辑**: 使用获取到的 `fileUri` 和 `mimeType`，通过 `editImage` 方法并采用**简化的 `prompt + inputs` 模式**进行调用。
+
+### 前置要求
+- **必须先登录** (AppsAuthManager)
+- `uploadFileForAnalysis`
+
+### 1. 简化调用 (prompt + inputs 模式，推荐)
+SDK 会自动将 `prompt` 和 `inputs` 数组组合成标准的多模态 `messages`。
+
+import { AppsClient } from '@tacoreai/web-sdk'
+const client = new AppsClient('YOUR_APP_ID')
+
+// 1. 上传源文件
+const baseFile = await client.uploadFileForAnalysis(file);
+
+// 2. 调用编辑接口
+const result = await client.editImage({
+  prompt: '仅移除图中叠加的文字，保持其他区域不变，输出高清。',
+  inputs: [
+    { type: 'uploaded_file', fileUri: baseFile.fileUri, mimeType: baseFile.mimeType }
+  ]
+});
+// 获取图片 URI (兼容不同后端返回结构)
+const editedBase64 = result.data.uri || (result.data.images && result.data.images[0]?.uri);
+// editedBase64 即可直接作为 <img src={editedBase64} />
+
+### 2. 典型场景范式
+
+- **场景 A：单图编辑（去字/去水印/局部替换）**
+
+const base = await client.uploadFileForAnalysis(file);
+const result = await client.editImage({
+  prompt: '移除叠加文字，其他区域完全保持不变。',
+  inputs: [
+    { type: 'uploaded_file', fileUri: base.fileUri, mimeType: base.mimeType }
+  ]
+});
+const base64 = result.data.uri || result.data.images?.[0]?.uri;
+
+- **场景 B：双图融合（将服装穿到模特身上）**
+
+const garment = await client.uploadFileForAnalysis(garmentFile);
+const modelPhoto = await client.uploadFileForAnalysis(modelFile);
+
+const result = await client.editImage({
+  prompt: '将服装自然替换到模特身上，保持姿态与光照；去除服装图背景；保持背景不变；不改变面部和发型。',
+  inputs: [
+    // 建议顺序：底图（模特）放前，叠加/融合图（服装）放后
+    { type: 'uploaded_file', fileUri: modelPhoto.fileUri, mimeType: modelPhoto.mimeType },
+    { type: 'uploaded_file', fileUri: garment.fileUri, mimeType: garment.mimeType }
+  ]
+});
+const base64 = result.data.uri || result.data.images?.[0]?.uri;
+
+- **场景 C：掩膜修复/扩展（Inpainting / Outpainting）**
+
+const base = await client.uploadFileForAnalysis(baseFile);
+const mask = await client.uploadFileForAnalysis(maskFile); // 掩膜语义按后端约定
+
+const result = await client.editImage({
+  prompt: '在掩膜区域进行修复，移除水印并保持纹理一致；不要改变未掩膜区域。',
+  inputs: [
+    // 建议顺序：底图 -> 掩膜
+    { type: 'uploaded_file', fileUri: base.fileUri, mimeType: base.mimeType },
+    { type: 'uploaded_file', fileUri: mask.fileUri, mimeType: mask.mimeType }
+  ]
+});
+const base64 = result.data.uri || result.data.images?.[0]?.uri;
+
+### 3. 高级模式 (messages 透传)
+用于完全控制请求结构，不推荐常规使用。
+
+const base = await client.uploadFileForAnalysis(file)
+
+const result = await client.editImage({
+  model: 'gemini-2.5-flash-image-preview',
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: '移除图中叠加的文字...' },
+        { type: 'uploaded_file', uploaded_file: { fileUri: base.fileUri, mimeType: base.mimeType } }
+      ]
+    }
+  ]
+})
+const base64 = result.data.uri || result.data.images?.[0]?.uri;
+
+---
+
+## [新增] Sora 视频生成
+
+通过 AppsClient 调用 Sora 视频生成服务。计费将自动关联到应用所属的组织。
+
+### 定价
+- **sora-2**: 300 积分/次
+- **sora-2-pro**: 1500 积分/次
+
+### `createVideoJob(options)`
+- **功能**: 创建一个异步的视频生成任务。
+- **参数**:
+  - `options` (object):
+    - `prompt` (string, 必填): 视频描述提示词。
+    - `model` (string, 必填): 模型名称, 'sora-2' 或 'sora-2-pro'。
+    - `size` (string, 可选): 视频尺寸, 默认为 '1920x1080'。
+    - `seconds` (number, 可选): 视频时长, 默认为 6。
+- **返回值**: `Promise<object>` - 包含任务初始状态的文档。
+
+### `remixVideoJob(jobId, options)`
+- **功能**: 基于一个已完成的视频，创建一个新的 Remix 任务。
+- **参数**:
+  - `jobId` (string, 必填): 原始视频任务的 `wyID`。
+  - `options` (object):
+    - `prompt` (string, 必填): 用于修改视频的提示词。
+- **返回值**: `Promise<object>` - 包含新的 Remix 任务初始状态的文档。
+
+### `getVideoJob(jobId)`
+- **功能**: 查询指定视频任务的状态。
+- **参数**:
+  - `jobId` (string, 必填): `createVideoJob` 或 `remixVideoJob` 返回的任务 `wyID`。
+- **返回值**: `Promise<object>` - 包含任务最新状态的文档。当 `status` 为 'completed' 时，`resultUrl` 字段将包含视频的下载链接。
+
+### `listVideoJobs(options)`
+- **功能**: 获取视频任务列表。
+- **参数**:
+  - `options` (object):
+    - `page` (number, 可选): 页码, 默认 1。
+    - `pageSize` (number, 可选): 每页数量, 默认 10。
+- **返回值**: `Promise<object>` - 包含任务列表和分页信息的对象。
+
+### 工作流示例
+
+const client = new AppsClient('YOUR_APP_ID');
+
+async function generateAndPollVideo() {
+  try {
+    // 1. 提交任务
+    const jobResult = await client.createVideoJob({
+      prompt: 'A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage.',
+      model: 'sora-2'
+    });
+    const jobId = jobResult.data.wyID;
+    console.log('视频任务已创建, ID:', jobId);
+
+    // 2. 轮询状态
+    const pollStatus = setInterval(async () => {
+      const updatedJob = await client.getVideoJob(jobId);
+      console.log('当前状态:', updatedJob.data.status, '进度:', updatedJob.data.progress);
+
+      if (updatedJob.data.status === 'completed') {
+        console.log('视频生成成功! URL:', updatedJob.data.resultUrl);
+        clearInterval(pollStatus);
+      } else if (updatedJob.data.status === 'failed') {
+        console.error('视频生成失败:', updatedJob.data.error);
+        clearInterval(pollStatus);
+      }
+    }, 5000); // 每5秒查询一次
+
+  } catch (error) {
+    console.error('操作失败:', error.message);
+  }
+}
+
+---
+
+## 网页爬虫服务 - Apps 路由
+
+请确保已通过 AppsAuthManager 登录，并使用 AppsClient 发起请求（会自动附带 Authorization）。
+
+### 1) 单个URL爬取
+
+import { AppsClient } from '@tacoreai/web-sdk'
+const client = new AppsClient('YOUR_APP_ID')
+
+try {
+  const result = await client.scrapeUrl({
+    url: 'https://example.com/article',
+    projectId: 'project_123' // 可选，项目ID
+  })
+  
+  console.log('爬取成功:', result)
+  // result.data 包含：
+  // - url: 原始URL
+  // - markdown: 转换后的Markdown内容
+  // - contentLength: HTML内容长度
+  // - markdownLength: Markdown内容长度
+  // - creditsCost: 消耗的积分（固定50积分）
+} catch (error) {
+  console.error('爬取失败:', error.message)
+  // 常见错误：
+  // - 402: 积分余额不足
+  // - 400: URL格式无效或网页访问失败
+  // - 404: 组织不存在
+}
+
+### 2) 批量URL爬取
+
+import { AppsClient } from '@tacoreai/web-sdk'
+const client = new AppsClient('YOUR_APP_ID')
+
+try {
+  const result = await client.scrapeMultipleUrls({
+    urls: [
+      'https://example.com/article1',
+      'https://example.com/article2',
+      'https://example.com/article3'
+    ],
+    projectId: 'project_123', // 可选，项目ID
+    maxConcurrent: 3 // 可选，最大并发数，默认3，最大5
+  })
+  
+  console.log('批量爬取完成:', result)
+  // result.data 包含：
+  // - totalUrls: 总URL数量
+  // - successfulUrls: 成功爬取的URL数量
+  // - failedUrls: 失败的URL数量
+  // - results: 详细结果数组
+  // - creditsCost: 总消耗积分（只为成功的URL计费）
+  
+  // 处理每个URL的结果
+  result.data.results.forEach((item, index) => {
+    if (item.success) {
+      console.log(`URL ${index + 1} 成功:`, item.data.markdown)
+    } else {
+      console.log(`URL ${index + 1} 失败:`, item.error)
+    }
+  })
+} catch (error) {
+  console.error('批量爬取失败:', error.message)
+}
+
+### 爬虫服务特性
+
+- **智能转换**: 自动将HTML内容转换为干净的Markdown格式
+- **内容限制**: 单个页面最大5MB内容限制
+- **并发控制**: 批量爬取支持并发控制，最大并发数为5
+- **数量限制**: 批量爬取最多支持10个URL
+- **计费模式**: 每个成功爬取的URL消耗50积分，失败的URL不计费
+- **错误处理**: 详细的错误信息和状态码，便于调试和处理
+
+### 错误码说明
+
+- **400**: 参数错误或URL格式无效
+- **402**: 积分余额不足
+- **404**: 组织不存在
+- **500**: 服务器内部错误
+
+### 注意事项
+
+- 爬虫服务会自动根据 appId 解析组织并进行计费
+- 支持爬取大部分公开网页，但可能受目标网站的反爬虫策略影响
+- 转换后的Markdown内容会自动移除脚本、样式、图片等非文本元素
+- 建议在爬取前先检查积分余额，避免因余额不足导致爬取失败
+
+---
+
+## 平台态图片能力（需平台鉴权与 x-org-id）
+
+若在"平台态（/plat）"调用接口，请在请求头中携带：
+- Authorization: Bearer <platform_token>
+- x-org-id: <组织ID>
+
+1) 文生图 /plat/agent/text2image
+
+POST /plat/agent/text2image
+Headers: Authorization + x-org-id
+Body:
+{
+  "organizationId": "<可不传，若传与 x-org-id 一致>",
+  "userId": "<平台用户ID>",
+  "prompt": "卡通风格的星空小屋",
+  "...其它可选项"
+}
+
+---
+
+## 给 Web Agent 的提示片段
+
+你是生成 App 前端代码的 Web Agent。项目已集成 @tacoreai/web-sdk，提供文件、图片和爬虫 API，请遵循：
+- 文件接口：仅通过 AppsClient 调用，不直接使用 fetch。
+- 图片接口：Apps 路由优先，使用 AppsClient.generateImage() 与 AppsClient.editImage()。
+- 爬虫接口：使用 AppsClient.scrapeUrl() 或 AppsClient.scrapeMultipleUrls()。
+- 爬虫服务必填：url（单个）或 urls（批量）。每个成功URL消耗50积分。
+- 计费：Apps 路由按 appId 归属组织进行计费；平台路由需带 x-org-id，并传 userId。
+- 常用方法：
+  • 文生图：generateImage({ prompt, ... })
+  • 图像编辑：editImage({ messages }) 或 editImage({ prompt, inputs, ... })
+  • 单个爬虫：scrapeUrl({ url, projectId? })
+  • 批量爬虫：scrapeMultipleUrls({ urls, projectId?, maxConcurrent? })
+- 错误处理：注意处理 401 未登录、402 余额不足、404 组织不存在、500/503 外部服务异常等。

package/amd-config.json

@@ -0,0 +1,11 @@
+{
+  "name": "@tacoreai/web-sdk",
+  "version": "1.57.0",
+  "entry": "index.js",
+  "externals": [],
+  "buildOptions": {
+    "minify": true,
+    "sourcemap": false,
+    "format": "esm"
+  }
+}