@plolink/sdk 0.0.4 → 0.0.6

package/dist/modules/video-psych-analysis/index.d.ts

@@ -0,0 +1,700 @@
+import { P as PlolinkClient } from '../../client-D2HlV7GT.js';
+import { P as Poller } from '../../poller-DWKZjuSw.js';
+import '../../core-77EbLgbp.js';
+import 'axios';
+
+/**
+ * 视频人物心理分析模块类型
+ */
+/**
+ * 视频人物心理分析状态枚举
+ */
+type VideoPsychAnalysisStatus = 'PENDING' | 'SUBMITTING' | 'SUBMITTED' | 'PROCESSING' | 'SYNCING_RESULTS' | 'GENERATING_REPORT' | 'COMPLETED' | 'FAILED';
+/**
+ * 创建视频心理分析任务参数
+ */
+interface CreateVideoPsychAnalysisParams {
+    /** 任务名称（可选，用于用户识别） */
+    name?: string;
+    /** 视频文件ID数组 */
+    videoFileIds: string[];
+    /** 人物参考图文件ID */
+    referenceImageFileId: string;
+    /** 人物背景与分析目标（如：视频是华为CEO任正非的公开演讲，请分析他对某话题的真实态度） */
+    prompt: string;
+    /** 人物背景信息（Markdown格式，可选） */
+    familyBackground?: string;
+    /** 切帧FPS（1-30，默认3） */
+    frameFps?: number;
+    /** 分析语言（默认zh-CN） */
+    language?: string;
+}
+/**
+ * 视频元数据信息
+ */
+interface VideoInfo {
+    /** 视频宽度 */
+    width: number;
+    /** 视频高度 */
+    height: number;
+    /** 视频时长（秒） */
+    duration: number;
+    /** 文件大小（字节） */
+    file_size: number;
+    /** 帧率 */
+    fps: number;
+    /** 视频编码 */
+    video_codec: string;
+    /** 音频编码 */
+    audio_codec: string | null;
+    /** 视频比特率 */
+    video_bitrate: number;
+    /** 音频比特率 */
+    audio_bitrate: number | null;
+    /** 首帧图URL */
+    first_frame_url?: string | null;
+}
+/**
+ * 进度信息
+ */
+interface AnalysisProgress {
+    /** 已完成步骤数 */
+    done: number;
+    /** 总步骤数 */
+    total: number;
+    /** 当前阶段 */
+    stage: string;
+}
+/**
+ * 文件信息
+ */
+interface FileInfo {
+    /** 文件ID */
+    id: string;
+    /** 文件访问URL */
+    url: string;
+    /** 文件名 */
+    name: string;
+    /** 文件大小（字节） */
+    size: number;
+    /** MIME类型 */
+    mimeType: string;
+}
+/**
+ * 创建分析任务响应
+ */
+interface CreateVideoPsychAnalysisResponse {
+    /** 分析任务ID */
+    id: string;
+    /** 当前状态 */
+    status: VideoPsychAnalysisStatus;
+    /** 提示消息 */
+    message: string;
+}
+/**
+ * 视频心理分析详情
+ */
+interface VideoPsychAnalysisDetail {
+    /** 分析任务ID */
+    id: string;
+    /** 任务名称 */
+    name: string;
+    /** 当前状态 */
+    status: VideoPsychAnalysisStatus;
+    /** 进度信息 */
+    progress: AnalysisProgress;
+    /** 错误信息 */
+    errorMessage: string;
+    /** 视频元数据信息 */
+    videoInfo: VideoInfo | null;
+    /** AI生成的最终报告（Markdown格式） */
+    reportContent: string;
+    /** 报告生成时间 */
+    reportGeneratedAt: string | null;
+    /** 创建时间 */
+    createdAt: string;
+    /** 更新时间 */
+    updatedAt: string;
+    /** 用户Prompt（人物背景与分析目标） */
+    prompt: string;
+    /** 人物背景信息（Markdown格式，可选） */
+    familyBackground?: string;
+    /** 视频文件信息列表 */
+    videoFiles: FileInfo[];
+    /** 参考图文件信息 */
+    referenceImage: FileInfo;
+    /** 切帧FPS */
+    frameFps: number;
+    /** 分析语言 */
+    language: string;
+}
+/**
+ * 同步任务状态响应
+ */
+interface SyncStatusResponse {
+    /** 当前状态 */
+    status: string;
+    /** 进度信息 */
+    progress: AnalysisProgress;
+    /** 提示消息 */
+    message: string;
+}
+/**
+ * 表情动作项
+ */
+interface ExpActItem {
+    /** 帧ID */
+    id: string;
+    /** 帧图片路径 */
+    path: string;
+    /** 时间戳（秒） */
+    sec: number;
+    /** 小时 */
+    h: number;
+    /** 分钟 */
+    m: number;
+    /** 秒 */
+    s: number;
+    /** 毫秒 */
+    ms: number;
+    /** 表情参数（已解码的对象） */
+    exp_params: Record<string, unknown> | null;
+    /** 动作分析描述 */
+    act_params: string;
+}
+/**
+ * 声纹信息
+ */
+interface WaveInfo {
+    /** 对象类型 */
+    object: string;
+    /** 声纹参数 */
+    wave_params: Record<string, unknown>;
+}
+/**
+ * 文本维度分析项
+ */
+interface TextAnalysisItem {
+    /** 文本ID */
+    id: string;
+    /** 文本内容 */
+    text: string;
+    /** 开始时间（毫秒） */
+    start_ms: number;
+    /** 结束时间（毫秒） */
+    end_ms: number;
+    /** 所属段落ID */
+    group_id: string;
+    /** 说话人编号 */
+    speaker: number;
+    /** 声纹信息 */
+    wave_info?: WaveInfo;
+    /** 表情动作列表 */
+    exp_act_list?: ExpActItem[];
+}
+/**
+ * 文本维度结果
+ */
+interface TextsData {
+    /** 总数 */
+    total: number;
+    /** 文本项列表 */
+    items: TextAnalysisItem[];
+}
+/**
+ * 帧维度分析项
+ */
+interface FrameAnalysisItem {
+    /** 帧ID（格式：HH-MM-SS-mmm） */
+    frame_id: string;
+    /** 时间戳（毫秒） */
+    time_ms: number;
+    /** 帧图片路径 */
+    frame_path: string;
+    /** 表情参数（已解码的对象，包含详细的FACS分析等） */
+    exp_params: Record<string, unknown> | null;
+    /** 动作分析描述 */
+    act_params: string;
+}
+/**
+ * 帧维度结果
+ */
+interface FramesData {
+    /** 总数 */
+    total: number;
+    /** 帧项列表 */
+    items: FrameAnalysisItem[];
+}
+/**
+ * 段落分析项
+ */
+interface ParagraphAnalysisItem {
+    /** 段落ID */
+    group_id: string;
+    /** 段落文本 */
+    text: string;
+    /** 段落摘要 */
+    summary: string;
+    /** 开始时间（毫秒） */
+    start_ms: number;
+    /** 结束时间（毫秒） */
+    end_ms: number;
+    /** 声纹信息 */
+    wave_info?: WaveInfo;
+    /** 微表情描述 */
+    micro_expression_desc?: string;
+    /** 动作描述 */
+    action_desc?: string;
+    /** NLP分析结果 */
+    nlp_result?: {
+        /** 行为一致性（0-1） */
+        behavior_consistency?: number;
+        /** 说话人情绪 */
+        speaker_emotion?: string;
+        /** 情绪强度（0-1） */
+        speaker_emotion_intensity?: number;
+        /** 真实态度 */
+        real_attitude?: string;
+    };
+}
+/**
+ * 段落结果
+ */
+interface ParagraphsData {
+    /** 总数 */
+    total: number;
+    /** 段落项列表 */
+    items: ParagraphAnalysisItem[];
+}
+/**
+ * 列表查询参数
+ */
+interface ListVideoPsychAnalysesParams {
+    /** 页码（默认1） */
+    page?: number;
+    /** 每页数量（默认20） */
+    pageSize?: number;
+    /** 关键词搜索（搜索任务名称） */
+    keyword?: string;
+    /** 状态筛选 */
+    status?: VideoPsychAnalysisStatus;
+    /** 排序字段（默认createdAt） */
+    sortBy?: 'createdAt' | 'updatedAt';
+    /** 排序方向（默认desc） */
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * 分析任务摘要（列表项）
+ */
+interface VideoPsychAnalysisSummary {
+    /** 分析任务ID */
+    id: string;
+    /** 任务名称 */
+    name: string;
+    /** 当前状态 */
+    status: VideoPsychAnalysisStatus;
+    /** 进度信息 */
+    progress: AnalysisProgress;
+    /** 错误信息 */
+    errorMessage: string;
+    /** 报告生成时间 */
+    reportGeneratedAt: string | null;
+    /** 视频元信息（任务提交后更新） */
+    videoInfo: VideoInfo | null;
+    /** 视频文件信息列表 */
+    videoFiles: FileInfo[];
+    /** 参考图文件信息 */
+    referenceImage: FileInfo;
+    /** 创建时间 */
+    createdAt: string;
+    /** 更新时间 */
+    updatedAt: string;
+}
+/**
+ * 列表查询响应
+ */
+interface ListVideoPsychAnalysesResponse {
+    /** 任务列表 */
+    list: VideoPsychAnalysisSummary[];
+    /** 总数 */
+    total: number;
+    /** 当前页码 */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+}
+/**
+ * 语言选项
+ */
+interface LanguageOption {
+    /** 语言标签 */
+    label: string;
+    /** 语言代码 */
+    value: string;
+}
+/**
+ * 视频心理分析配置
+ */
+interface VideoPsychAnalysisConfig {
+    /** 语言选项列表 */
+    languageOptions: LanguageOption[];
+    /** 默认语言 */
+    defaultLanguage: string;
+}
+/**
+ * 更新分析任务参数
+ */
+interface UpdateVideoPsychAnalysisParams {
+    /** 任务名称 */
+    name?: string;
+    /** 人物背景与分析目标 */
+    prompt?: string;
+    /** 人物背景信息（Markdown格式） */
+    familyBackground?: string;
+}
+/**
+ * 更新分析任务响应
+ */
+interface UpdateVideoPsychAnalysisResponse {
+    /** 分析任务ID */
+    id: string;
+    /** 任务名称 */
+    name: string;
+    /** 用户Prompt */
+    prompt: string;
+    /** 人物背景信息 */
+    familyBackground: string;
+    /** 当前状态 */
+    status: VideoPsychAnalysisStatus;
+    /** 更新时间 */
+    updatedAt: string;
+}
+
+/**
+ * 视频人物心理分析模块
+ */
+declare class VideoPsychAnalysis {
+    private client;
+    constructor(client: PlolinkClient);
+    /**
+     * 获取视频心理分析配置
+     *
+     * @returns 配置信息（包括语言选项等）
+     *
+     * @example
+     * ```typescript
+     * const config = await videoPsych.getConfig();
+     * console.log('语言选项:', config.languageOptions);
+     * console.log('默认语言:', config.defaultLanguage);
+     * ```
+     */
+    getConfig(): Promise<VideoPsychAnalysisConfig>;
+    /**
+     * 查询分析任务列表
+     *
+     * @param params - 查询参数（可选）
+     * @returns 任务列表
+     * @throws {PlolinkError} 当查询失败时抛出
+     *
+     * @example
+     * ```typescript
+     * // 查询所有已完成的任务
+     * const result = await videoPsych.list({
+     *   status: 'COMPLETED',
+     *   page: 1,
+     *   pageSize: 20
+     * });
+     * console.log(`共 ${result.total} 个任务`);
+     * result.list.forEach(item => {
+     *   console.log(`${item.name}: ${item.status}`);
+     * });
+     * ```
+     */
+    list(params?: ListVideoPsychAnalysesParams): Promise<ListVideoPsychAnalysesResponse>;
+    /**
+     * 创建视频心理分析任务
+     *
+     * @param params - 创建参数
+     * @returns 创建结果，包含任务ID和初始状态
+     * @throws {PlolinkError} 当参数验证失败或创建失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const result = await videoPsych.create({
+     *   name: '候选人A面试分析',
+     *   videoFileIds: ['file1', 'file2', 'file3'],
+     *   referenceImageFileId: 'refImage1',
+     *   prompt: '请以专业心理分析师的视角，分析候选人的情绪、态度和心理状态',
+     *   frameFps: 3,
+     *   language: 'zh'
+     * });
+     * console.log(`任务ID: ${result.id}, 状态: ${result.status}`);
+     * ```
+     */
+    create(params: CreateVideoPsychAnalysisParams): Promise<CreateVideoPsychAnalysisResponse>;
+    /**
+     * 获取分析任务详情
+     *
+     * @param id - 任务ID
+     * @returns 任务详情信息
+     * @throws {PlolinkError} 当任务不存在或无权访问时抛出
+     *
+     * @example
+     * ```typescript
+     * const detail = await videoPsych.getDetail('analysis_123');
+     * console.log(`任务: ${detail.name}`);
+     * console.log(`状态: ${detail.status}`);
+     * console.log(`进度: ${detail.progress.done}/${detail.progress.total}`);
+     *
+     * if (detail.reportContent) {
+     *   console.log('报告已生成');
+     * }
+     * ```
+     */
+    getDetail(id: string): Promise<VideoPsychAnalysisDetail>;
+    /**
+     * 获取视频元数据信息
+     *
+     * @description
+     * 获取任务的视频元数据信息（videoInfo）。在异步模式下，任务创建时 videoInfo 为空，
+     * 需要等待任务进入 PROCESSING 状态后由定时任务自动同步。
+     *
+     * **使用场景**：
+     * - 获取视频的宽高、时长、编码等信息用于界面展示
+     * - 在任务创建后轮询此接口直到获取到 videoInfo
+     *
+     * **注意**：
+     * - 如果视频信息尚未生成，返回 null
+     * - 建议配合任务状态查询使用，等待状态变为 PROCESSING 后再查询
+     *
+     * @param id - 任务ID
+     * @returns 视频元数据信息，如果尚未生成则返回 null
+     * @throws {PlolinkError} 当任务不存在时抛出
+     *
+     * @example
+     * ```typescript
+     * // 轮询获取 videoInfo
+     * const checkVideoInfo = async (analysisId: string) => {
+     *   const maxAttempts = 60;
+     *   let attempt = 0;
+     *
+     *   while (attempt < maxAttempts) {
+     *     const videoInfo = await videoPsych.getVideoInfo(analysisId);
+     *
+     *     if (videoInfo) {
+     *       console.log(`视频信息: ${videoInfo.width}x${videoInfo.height}`);
+     *       console.log(`时长: ${videoInfo.duration}s`);
+     *       console.log(`文件大小: ${(videoInfo.file_size / 1024 / 1024).toFixed(2)}MB`);
+     *       return videoInfo;
+     *     }
+     *
+     *     console.log('视频信息还在处理中...');
+     *     await new Promise(resolve => setTimeout(resolve, 5000)); // 等待5秒
+     *     attempt++;
+     *   }
+     *
+     *   throw new Error('获取视频信息超时');
+     * };
+     *
+     * const info = await checkVideoInfo('analysis_123');
+     * ```
+     */
+    getVideoInfo(id: string): Promise<VideoInfo | null>;
+    /**
+     * 更新分析任务
+     *
+     * @description
+     * 更新分析任务的基本信息（仅限 PENDING 和 FAILED 状态的任务）。
+     *
+     * @param id - 任务ID
+     * @param params - 更新参数
+     * @returns 更新后的任务信息
+     * @throws {PlolinkError} 当任务不存在、状态不允许更新或更新失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const updated = await videoPsych.update('analysis_123', {
+     *   name: '李四的心理分析',
+     *   prompt: '请以临床心理学专家的视角进行分析'
+     * });
+     * console.log(`已更新: ${updated.name}`);
+     * ```
+     */
+    update(id: string, params: UpdateVideoPsychAnalysisParams): Promise<UpdateVideoPsychAnalysisResponse>;
+    /**
+     * 删除分析任务
+     *
+     * @description
+     * 删除分析任务（软删除）。
+     *
+     * @param id - 任务ID
+     * @throws {PlolinkError} 当任务不存在或删除失败时抛出
+     *
+     * @example
+     * ```typescript
+     * await videoPsych.delete('analysis_123');
+     * console.log('任务已删除');
+     * ```
+     */
+    delete(id: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * 重试失败的分析任务
+     *
+     * @description
+     * 对失败(FAILED)状态的任务进行重试，使用原有参数重新提交到AI引擎进行分析。
+     * 重试会清空之前的错误信息和分析结果，重新开始完整的分析流程。
+     *
+     * **注意**：
+     * - 只能重试状态为 FAILED 的任务
+     * - 重试后任务状态会重置为 PENDING
+     * - 会清空之前的分析结果和报告内容
+     * - 建议配合 `watchAnalysisStatus()` 方法监听重试后的任务状态
+     *
+     * @param id - 任务ID
+     * @returns 更新后的任务信息
+     * @throws {PlolinkError} 当任务不存在、状态不是FAILED或重试失败时抛出
+     *
+     * @example
+     * ```typescript
+     * // 重试失败的任务
+     * const result = await videoPsych.retry('analysis_123');
+     * console.log(`任务已重新提交: ${result.id}`);
+     * console.log(`当前状态: ${result.status}`);
+     *
+     * // 监听重试后的任务状态
+     * const poller = videoPsych.watchAnalysisStatus(result.id, (detail) => {
+     *   console.log(`重试进度: ${detail.progress.done}/${detail.progress.total}`);
+     *   if (detail.status === 'COMPLETED') {
+     *     console.log('重试成功，分析完成！');
+     *   } else if (detail.status === 'FAILED') {
+     *     console.error('重试后仍失败');
+     *   }
+     * });
+     * poller.start();
+     * ```
+     */
+    retry(id: string): Promise<VideoPsychAnalysisDetail>;
+    /**
+     * 同步任务状态
+     *
+     * @description
+     * 主动触发后端从 AI TOOLS API 同步最新状态和中间结果。
+     *
+     * **注意**：通常不需要手动调用此方法，系统会每30秒自动轮询同步所有非完成态的任务。
+     *
+     * @param id - 任务ID
+     * @returns 同步后的状态信息
+     * @throws {PlolinkError} 当任务不存在或同步失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const status = await videoPsych.syncStatus('analysis_123');
+     * console.log(`当前状态: ${status.status}`);
+     * console.log(`进度: ${status.progress.done}/${status.progress.total}`);
+     * ```
+     */
+    syncStatus(id: string): Promise<SyncStatusResponse>;
+    /**
+     * 轮询分析任务状态
+     *
+     * @description
+     * 创建一个轮询器持续监听任务状态变化，直到任务达到终态（COMPLETED/FAILED）。
+     * 使用指数退避策略，初始间隔5秒，最大间隔30秒。
+     *
+     * @param id - 任务ID
+     * @param onStatusChange - 状态变化回调函数
+     * @returns Poller实例，可用于手动停止轮询
+     *
+     * @example
+     * ```typescript
+     * const poller = videoPsych.watchAnalysisStatus('analysis_123', (detail) => {
+     *   console.log(`状态: ${detail.status}`);
+     *   console.log(`进度: ${detail.progress.done}/${detail.progress.total} (${detail.progress.stage})`);
+     *
+     *   if (detail.status === 'COMPLETED') {
+     *     console.log('分析完成，报告已生成！');
+     *     console.log(detail.reportContent);
+     *   } else if (detail.status === 'FAILED') {
+     *     console.error(`分析失败: ${detail.errorMessage}`);
+     *   }
+     * });
+     *
+     * // 开始轮询
+     * poller.start();
+     *
+     * // 需要时可以手动停止
+     * // poller.stop();
+     * ```
+     */
+    watchAnalysisStatus(id: string, onStatusChange: (detail: VideoPsychAnalysisDetail) => void): Poller<VideoPsychAnalysisDetail>;
+    /**
+     * 获取文本维度分析结果
+     *
+     * @param id - 任务ID
+     * @returns 文本维度分析数据
+     * @throws {PlolinkError} 当任务不存在或分析未完成时抛出
+     *
+     * @example
+     * ```typescript
+     * const texts = await videoPsych.getTexts('analysis_123');
+     * console.log(`共 ${texts.total} 条文本`);
+     * texts.items.forEach(item => {
+     *   console.log(`${item.start_time}s: ${item.text}`);
+     *   if (item.nlp_result) {
+     *     console.log(`  情绪: ${item.nlp_result.speaker_emotion}`);
+     *     console.log(`  态度: ${item.nlp_result.real_attitude}`);
+     *   }
+     * });
+     * ```
+     */
+    getTexts(id: string): Promise<TextsData>;
+    /**
+     * 获取帧维度分析结果
+     *
+     * @param id - 任务ID
+     * @returns 帧维度分析数据
+     * @throws {PlolinkError} 当任务不存在或分析未完成时抛出
+     *
+     * @example
+     * ```typescript
+     * const frames = await videoPsych.getFrames('analysis_123');
+     * console.log(`共 ${frames.total} 帧`);
+     * frames.items.forEach(item => {
+     *   console.log(`${item.timestamp}s: ${item.image_url}`);
+     *   if (item.vision_result) {
+     *     console.log(`  表情: ${item.vision_result.expression}`);
+     *     console.log(`  动作: ${item.vision_result.action}`);
+     *   }
+     * });
+     * ```
+     */
+    getFrames(id: string): Promise<FramesData>;
+    /**
+     * 获取段落分析结果
+     *
+     * @param id - 任务ID
+     * @returns 段落分析数据
+     * @throws {PlolinkError} 当任务不存在或分析未完成时抛出
+     *
+     * @example
+     * ```typescript
+     * const paragraphs = await videoPsych.getParagraphs('analysis_123');
+     * console.log(`共 ${paragraphs.total} 段`);
+     * paragraphs.items.forEach(item => {
+     *   console.log(`段落 ${item.id}:`);
+     *   console.log(`  时间: ${item.start_time}s - ${item.end_time}s`);
+     *   console.log(`  内容: ${item.text}`);
+     *   console.log(`  摘要: ${item.summary}`);
+     *   if (item.nlp_result) {
+     *     console.log(`  情绪: ${item.nlp_result.speaker_emotion}`);
+     *     console.log(`  态度: ${item.nlp_result.real_attitude}`);
+     *   }
+     * });
+     * ```
+     */
+    getParagraphs(id: string): Promise<ParagraphsData>;
+}
+
+export { type AnalysisProgress, type CreateVideoPsychAnalysisParams, type CreateVideoPsychAnalysisResponse, type FileInfo, type FrameAnalysisItem, type FramesData, type LanguageOption, type ListVideoPsychAnalysesParams, type ListVideoPsychAnalysesResponse, type ParagraphAnalysisItem, type ParagraphsData, type SyncStatusResponse, type TextAnalysisItem, type TextsData, type UpdateVideoPsychAnalysisParams, type UpdateVideoPsychAnalysisResponse, type VideoInfo, VideoPsychAnalysis, type VideoPsychAnalysisConfig, type VideoPsychAnalysisDetail, type VideoPsychAnalysisStatus, type VideoPsychAnalysisSummary };