@plolink/sdk 0.0.4 → 0.0.5

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

@@ -0,0 +1,562 @@
+import { P as PlolinkClient } from '../../client-CwNikk7i.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;
+    /** 用户Prompt（如：心理分析专家的专业风格） */
+    prompt: string;
+    /** 切帧FPS（1-30，默认3） */
+    frameFps?: number;
+    /** 分析语言（默认zh） */
+    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;
+}
+/**
+ * 进度信息
+ */
+interface AnalysisProgress {
+    /** 已完成步骤数 */
+    done: number;
+    /** 总步骤数 */
+    total: number;
+    /** 当前阶段 */
+    stage: 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;
+}
+/**
+ * 同步任务状态响应
+ */
+interface SyncStatusResponse {
+    /** 当前状态 */
+    status: string;
+    /** 进度信息 */
+    progress: AnalysisProgress;
+    /** 提示消息 */
+    message: string;
+}
+/**
+ * 文本维度分析项
+ */
+interface TextAnalysisItem {
+    /** 文本ID */
+    id: string;
+    /** 文本内容 */
+    text: string;
+    /** 开始时间（秒） */
+    start_time: number;
+    /** 结束时间（秒） */
+    end_time: number;
+    /** NLP分析结果 */
+    nlp_result?: {
+        /** 说话人情绪 */
+        speaker_emotion?: string;
+        /** 真实态度 */
+        real_attitude?: string;
+        /** 其他NLP字段 */
+        [key: string]: unknown;
+    };
+    /** 其他字段 */
+    [key: string]: unknown;
+}
+/**
+ * 文本维度结果
+ */
+interface TextsData {
+    /** 总数 */
+    total: number;
+    /** 文本项列表 */
+    items: TextAnalysisItem[];
+}
+/**
+ * 帧维度分析项
+ */
+interface FrameAnalysisItem {
+    /** 帧ID */
+    id: string;
+    /** 帧图片URL */
+    image_url: string;
+    /** 时间戳（秒） */
+    timestamp: number;
+    /** 视觉分析结果 */
+    vision_result?: {
+        /** 表情 */
+        expression?: string;
+        /** 动作 */
+        action?: string;
+        /** 其他视觉字段 */
+        [key: string]: unknown;
+    };
+    /** 其他字段 */
+    [key: string]: unknown;
+}
+/**
+ * 帧维度结果
+ */
+interface FramesData {
+    /** 总数 */
+    total: number;
+    /** 帧项列表 */
+    items: FrameAnalysisItem[];
+}
+/**
+ * 段落分析项
+ */
+interface ParagraphAnalysisItem {
+    /** 段落ID */
+    id: string;
+    /** 段落文本 */
+    text: string;
+    /** 段落摘要 */
+    summary: string;
+    /** 开始时间（秒） */
+    start_time: number;
+    /** 结束时间（秒） */
+    end_time: number;
+    /** NLP分析结果 */
+    nlp_result?: {
+        /** 说话人情绪 */
+        speaker_emotion?: string;
+        /** 真实态度 */
+        real_attitude?: string;
+        /** 其他NLP字段 */
+        [key: string]: unknown;
+    };
+    /** 其他字段 */
+    [key: string]: unknown;
+}
+/**
+ * 段落结果
+ */
+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;
+    /** 创建时间 */
+    createdAt: string;
+    /** 更新时间 */
+    updatedAt: string;
+}
+/**
+ * 列表查询响应
+ */
+interface ListVideoPsychAnalysesResponse {
+    /** 任务列表 */
+    list: VideoPsychAnalysisSummary[];
+    /** 总数 */
+    total: number;
+    /** 当前页码 */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+}
+/**
+ * 更新分析任务参数
+ */
+interface UpdateVideoPsychAnalysisParams {
+    /** 任务名称 */
+    name?: string;
+    /** 用户Prompt */
+    prompt?: string;
+}
+/**
+ * 更新分析任务响应
+ */
+interface UpdateVideoPsychAnalysisResponse {
+    /** 分析任务ID */
+    id: string;
+    /** 任务名称 */
+    name: string;
+    /** 用户Prompt */
+    prompt: string;
+    /** 当前状态 */
+    status: VideoPsychAnalysisStatus;
+    /** 更新时间 */
+    updatedAt: string;
+}
+
+/**
+ * 视频人物心理分析模块
+ *
+ * @description
+ * 提供视频人物心理分析相关功能，包括：
+ * - 创建分析任务
+ * - 查询任务详情和状态
+ * - 同步任务状态（轮询）
+ * - 获取分析结果（文本/帧/段落维度）
+ * - 生成心理分析报告
+ *
+ * @example
+ * ```typescript
+ * import { PlolinkClient } from '@plolink/sdk';
+ * import { VideoPsychAnalysis } from '@plolink/sdk/video-psych-analysis';
+ *
+ * const client = new PlolinkClient({
+ *   mode: 'apiKey',
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * const videoPsych = new VideoPsychAnalysis(client);
+ *
+ * // 创建分析任务
+ * const result = await videoPsych.create({
+ *   name: '候选人A面试分析',
+ *   videoFileIds: ['file1', 'file2'],
+ *   referenceImageFileId: 'refImage1',
+ *   prompt: '请以专业心理分析师的视角进行分析',
+ *   frameFps: 3,
+ *   language: 'zh'
+ * });
+ * console.log(`任务已创建: ${result.id}`);
+ *
+ * // 轮询任务状态
+ * const poller = videoPsych.watchAnalysisStatus(result.id, (detail) => {
+ *   console.log(`分析进度: ${detail.progress.done}/${detail.progress.total}`);
+ *   if (detail.status === 'COMPLETED') {
+ *     console.log('分析完成，报告已生成！');
+ *     console.log(detail.reportContent);
+ *   }
+ * });
+ * ```
+ *
+ * @module video-psych-analysis
+ */
+
+/**
+ * 视频人物心理分析模块
+ */
+declare class VideoPsychAnalysis {
+    private client;
+    constructor(client: PlolinkClient);
+    /**
+     * 查询分析任务列表
+     *
+     * @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
+     * 更新分析任务的基本信息（仅限 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
+     * 主动触发后端从 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 FrameAnalysisItem, type FramesData, type ListVideoPsychAnalysesParams, type ListVideoPsychAnalysesResponse, type ParagraphAnalysisItem, type ParagraphsData, type SyncStatusResponse, type TextAnalysisItem, type TextsData, type UpdateVideoPsychAnalysisParams, type UpdateVideoPsychAnalysisResponse, type VideoInfo, VideoPsychAnalysis, type VideoPsychAnalysisDetail, type VideoPsychAnalysisStatus, type VideoPsychAnalysisSummary };