StormFlow

Appearance

模块：AI Service ​

唯一职责：向后端 AI API 发送生成请求和查询请求，返回结构化结果。不感知 Vue/Pinia 状态。

边界 ​

属于本模块：

  • HTTP 请求构造与发送（ApiClient）
  • 统一 headers 注入（App-Id、Platform）
  • 后端响应解包（ApiResponse<T> → T）
  • 业务错误转换（HTTP 错误 → ApiError）
  • 三种生成能力封装：文本、图片、视频
  • 模型列表查询

不属于本模块（调用方负责）：

  • 节点状态管理（idle → generating → done/error）
  • 错误展示 UI
  • 生成结果写入节点数据
  • 模型列表缓存（由 modelsStore 负责）

对外接口 ​

AiService 接口 ​

typescript
interface AiService {
  generateText: (params: TextGenerateParams) => Promise<TextGenerateResult>
  generateImage: (params: ImageGenerateParams) => Promise<ImageGenerateResult>
  generateVideo: (params: VideoGenerateParams) => Promise<VideoGenerateResult>
}

参数与返回类型 ​

typescript
interface TextGenerateParams {
  prompt: string
  model: string
  variations: number
  images?: string[] // 参考图片 URL 列表
  videos?: string[] // 参考视频 URL 列表
}
interface TextGenerateResult { content: string }

interface ImageGenerateParams {
  prompt: string
  model: string
  variations: number
  imageUrl?: string // @deprecated，使用 images
  images?: string[] // 参考图片（自身 + 上游合并）
  aspectRatio?: string
  imageSize?: string
  videos?: string[] // 参考视频 URL 列表
}
interface ImageGenerateResult { imageUrl: string, results: string[] }

interface VideoGenerateParams {
  prompt: string
  model: string
  images?: string[] // 参考图片 URL 列表
  videos?: string[] // 参考视频 URL 列表
}
interface VideoGenerateResult { videoUrl: string }

ApiClient 接口 ​

typescript
interface ApiClient {
  get: <T>(path: string, query?: Record<string, string>) => Promise<T>
  post: <T>(path: string, body?: unknown) => Promise<T>
}

工厂函数 ​

typescript
function createRealAiService(client: ApiClient): AiService
function createApiClient(baseURL: string): ApiClient
function useApiClient(): ApiClient // Nuxt composable（services/http/index.ts）
function useAiService(): { service: ComputedRef<AiService> } // Nuxt composable（composables/useAiService.ts），节点组件的实际入口

模型列表 API ​

typescript
function fetchModelsByModality(client: ApiClient, modality: ModelModality): Promise<AiModelInfo[]>

后端 Endpoints ​

方法路径用途
POST/ability/v1/texts/action/generate文本生成
POST/ability/v1/images/action/generate图片生成
POST/ability/v1/videos/action/generate视频生成
GET/resource/v1/models?modality={modality}模型列表

错误场景 ​

场景模块行为调用方预期
NUXT_PUBLIC_API_BASE 未配置抛出 Error显示配置错误提示
后端返回非 200 code抛出 ApiError(code, message)catch 后更新节点状态为 error
网络超时 / 断网$fetch 抛出 FetchErrorcatch 后更新节点状态为 error

实现位置 ​

角色文件路径
HTTP 客户端apps/web/services/http/client.ts
HTTP 类型apps/web/services/http/types.ts
HTTP composableapps/web/services/http/index.ts
AI 接口定义apps/web/services/ai/types.ts
真实实现apps/web/services/ai/real.ts
模型列表 APIapps/web/services/ai/modelsApi.ts
AI composableapps/web/app/composables/useAiService.ts