@plolink/sdk 0.0.9 → 0.0.11

package/dist/modules/preset-agent-task/index.d.cts

@@ -0,0 +1,736 @@
+import { P as PlolinkClient } from '../../client-CAjIQKPm.cjs';
+import '../../core-77EbLgbp.cjs';
+import 'axios';
+
+/**
+ * Preset Agent Task 模块类型定义
+ */
+/**
+ * 预设执行状态
+ */
+type PresetExecutionStatus = 'INITIALIZING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
+/**
+ * Token和费用统计
+ */
+interface ExecutionMetrics {
+    /** 输入Token数 */
+    inputTokens: number;
+    /** 输出Token数 */
+    outputTokens: number;
+    /** 缓存读取Token数 */
+    cacheReadTokens: number;
+    /** 缓存创建Token数 */
+    cacheCreationTokens: number;
+    /** 总费用（美元） */
+    totalCost: number;
+}
+/**
+ * 预设配置（完整信息）
+ */
+interface PresetConfig {
+    /** 预设ID */
+    id: string;
+    /** 预设唯一标识 */
+    code: string;
+    /** 预设名称 */
+    name: string;
+    /** 预设描述 */
+    description?: string;
+    /** 预设指令模板 */
+    prompt: string;
+    /** AI模型 */
+    model: string;
+    /** 内置skills列表 */
+    selectedSkills: string[];
+    /** 扩展skills压缩包文件ID */
+    extendedSkillsFileId?: string;
+    /** 超时时间（毫秒），0表示永不超时 */
+    timeoutMs: number;
+    /** 静默超时（毫秒） */
+    silentTimeoutMs: number;
+    /** 业务标识 */
+    businessKey: string;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 创建人ID */
+    creatorId: string;
+    /** 团队ID */
+    teamId: string;
+    /** 创建时间 */
+    createdAt: string;
+    /** 更新时间 */
+    updatedAt: string;
+}
+/**
+ * 预设列表项（精简信息）
+ */
+interface PresetListItem {
+    /** 预设ID */
+    id: string;
+    /** 预设唯一标识 */
+    code: string;
+    /** 预设名称 */
+    name: string;
+    /** 预设描述 */
+    description?: string;
+    /** AI模型 */
+    model: string;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 创建时间 */
+    createdAt: string;
+    /** 更新时间 */
+    updatedAt: string;
+}
+/**
+ * 创建预设参数
+ */
+interface CreatePresetParams {
+    /** 预设唯一标识（团队内唯一） */
+    code: string;
+    /** 预设名称 */
+    name: string;
+    /** 预设描述 */
+    description?: string;
+    /** 预设指令模板 */
+    prompt: string;
+    /** AI模型 */
+    model: string;
+    /** 内置skills列表 */
+    selectedSkills?: string[];
+    /** 扩展skills压缩包文件ID */
+    extendedSkillsFileId?: string;
+    /** 超时时间（毫秒），0表示永不超时 */
+    timeoutMs?: number;
+    /** 静默超时（毫秒） */
+    silentTimeoutMs?: number;
+    /** 业务标识 */
+    businessKey: string;
+    /** 是否启用 */
+    enabled?: boolean;
+}
+/**
+ * 更新预设参数
+ */
+interface UpdatePresetParams {
+    /** 预设名称 */
+    name?: string;
+    /** 预设描述 */
+    description?: string;
+    /** 预设指令模板 */
+    prompt?: string;
+    /** AI模型 */
+    model?: string;
+    /** 内置skills列表 */
+    selectedSkills?: string[];
+    /** 扩展skills压缩包文件ID */
+    extendedSkillsFileId?: string;
+    /** 超时时间（毫秒） */
+    timeoutMs?: number;
+    /** 静默超时（毫秒） */
+    silentTimeoutMs?: number;
+    /** 业务标识 */
+    businessKey?: string;
+    /** 是否启用 */
+    enabled?: boolean;
+}
+/**
+ * 执行预设参数
+ */
+interface ExecutePresetParams {
+    /** 预设唯一标识 */
+    code: string;
+    /** 附加指令（与预设指令合并） */
+    additionalPrompt?: string;
+    /** 输入文件ID（ZIP格式） */
+    inputFileId?: string;
+}
+/**
+ * 预设执行记录（完整详情）
+ *
+ * ⚠️ 注意：不包含 agentTaskId、runId（完全隐藏Agent Task细节）
+ */
+interface PresetExecution {
+    /** 执行ID */
+    id: string;
+    /** 预设ID */
+    presetId: string;
+    /** 预设标识 */
+    presetCode: string;
+    /** 预设名称 */
+    presetName: string;
+    /** 附加指令 */
+    additionalPrompt?: string;
+    /** 输入文件ID */
+    inputFileId?: string;
+    /** 输出文件ID（对外暴露） */
+    outputFileId?: string;
+    /** 最终合并的prompt */
+    finalPrompt: string;
+    /** 执行状态 */
+    status: PresetExecutionStatus;
+    /** 执行时长（毫秒） */
+    duration: number;
+    /** 错误信息 */
+    errorMessage?: string;
+    /** Token和费用统计 */
+    metrics: ExecutionMetrics;
+    /** 创建人ID */
+    creatorId: string;
+    /** 团队ID */
+    teamId: string;
+    /** 创建时间 */
+    createdAt: string;
+    /** 更新时间 */
+    updatedAt: string;
+    /** 完成时间 */
+    completedAt?: string;
+}
+/**
+ * 执行记录列表项（精简信息）
+ */
+interface PresetExecutionListItem {
+    /** 执行ID */
+    id: string;
+    /** 预设ID */
+    presetId: string;
+    /** 预设标识 */
+    presetCode: string;
+    /** 预设名称 */
+    presetName: string;
+    /** 执行状态 */
+    status: PresetExecutionStatus;
+    /** 输入文件ID */
+    inputFileId?: string;
+    /** 输出文件ID */
+    outputFileId?: string;
+    /** 执行时长（毫秒） */
+    duration: number;
+    /** 创建人ID */
+    creatorId: string;
+    /** 创建时间 */
+    createdAt: string;
+    /** 更新时间 */
+    updatedAt: string;
+    /** 完成时间 */
+    completedAt?: string;
+}
+/**
+ * 预设列表查询参数
+ */
+interface PresetListQuery {
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 页码（从1开始） */
+    page?: number;
+    /** 每页数量 */
+    pageSize?: number;
+}
+/**
+ * 执行记录列表查询参数
+ */
+interface ExecutionListQuery {
+    /** 预设ID */
+    presetId?: string;
+    /** 执行状态 */
+    status?: PresetExecutionStatus;
+    /** 页码（从1开始） */
+    page?: number;
+    /** 每页数量 */
+    pageSize?: number;
+}
+/**
+ * 分页结果
+ */
+interface PaginatedResult<T> {
+    /** 数据列表 */
+    list: T[];
+    /** 总条数 */
+    total: number;
+    /** 当前页码 */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+}
+/**
+ * 执行结果（execute方法的返回值）
+ */
+interface ExecutionResult {
+    /** 执行ID */
+    executionId: string;
+    /** 初始状态 */
+    status: PresetExecutionStatus;
+}
+/**
+ * 预设配置（用于导出/导入，不含团队特定字段）
+ */
+interface PresetConfigForExport {
+    /** 预设唯一标识 */
+    code: string;
+    /** 预设名称 */
+    name: string;
+    /** 预设描述 */
+    description?: string;
+    /** 预设指令模板 */
+    prompt: string;
+    /** AI模型 */
+    model: string;
+    /** 内置skills列表 */
+    selectedSkills: string[];
+    /** 扩展skills压缩包文件ID */
+    extendedSkillsFileId?: string;
+    /** 超时时间（毫秒） */
+    timeoutMs: number;
+    /** 静默超时（毫秒） */
+    silentTimeoutMs: number;
+    /** 业务标识 */
+    businessKey: string;
+    /** 是否启用 */
+    enabled: boolean;
+}
+/**
+ * 导出配置
+ */
+interface ExportedConfig {
+    /** 配置版本 */
+    version: string;
+    /** 导出时间 */
+    exportedAt: string;
+    /** 预设配置数组 */
+    presets: PresetConfigForExport[];
+}
+/**
+ * 导入结果详情
+ */
+interface ImportResultDetail {
+    /** 预设标识 */
+    code: string;
+    /** 导入状态 */
+    status: 'imported' | 'skipped' | 'failed';
+    /** 预设ID（导入成功时返回） */
+    presetId?: string;
+    /** 错误信息（导入失败时返回） */
+    error?: string;
+}
+/**
+ * 导入结果
+ */
+interface ImportResult {
+    /** 导入成功数量 */
+    imported: number;
+    /** 跳过数量 */
+    skipped: number;
+    /** 失败数量 */
+    failed: number;
+    /** 详细结果 */
+    details: ImportResultDetail[];
+}
+/**
+ * 冲突策略
+ */
+type ConflictStrategy = 'skip' | 'overwrite';
+/**
+ * Webhook负载（执行完成通知）
+ *
+ * ⚠️ 注意：不包含 agentTaskId、runId（完全隐藏Agent Task）
+ */
+interface PresetExecutionWebhookPayload {
+    /** 模块名 */
+    module: 'preset-agent-task';
+    /** 动作 */
+    action: 'execution.completed' | 'execution.failed';
+    /** 时间戳 */
+    timestamp: string;
+    /** 数据 */
+    data: {
+        /** 执行ID */
+        executionId: string;
+        /** 预设标识 */
+        presetCode: string;
+        /** 预设名称 */
+        presetName: string;
+        /** 执行状态 */
+        status: 'COMPLETED' | 'FAILED';
+        /** 输入文件ID */
+        inputFileId?: string;
+        /** 输出文件ID */
+        outputFileId?: string;
+        /** 执行时长（毫秒） */
+        duration: number;
+        /** 错误信息 */
+        errorMessage?: string;
+        /** Token和费用统计 */
+        metrics: ExecutionMetrics;
+    };
+}
+
+/**
+ * 预设Agent任务模块
+ *
+ * @description
+ * 预设Agent任务是对Agent Task能力的封装，提供开箱即用的业务能力。
+ *
+ * 核心功能：
+ * - 预设配置管理（CRUD）
+ * - 预设执行（通过code调用）
+ * - 执行记录查询
+ * - 执行管理（取消、重试）
+ * - 配置导出/导入
+ *
+ * 注意：完全隐藏Agent Task实现细节，不暴露agentTaskId、runId
+ *
+ * @example
+ * ```typescript
+ * import { PlolinkClient } from '@plolink/sdk';
+ * import { PresetAgentTask } from '@plolink/sdk/preset-agent-task';
+ *
+ * const client = new PlolinkClient({
+ *   mode: 'apiKey',
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * const presetAgentTask = new PresetAgentTask(client);
+ *
+ * // 执行预设
+ * const result = await presetAgentTask.execute({
+ *   code: 'talent-resume-parse',
+ *   additionalPrompt: '请特别关注技能匹配度',
+ *   inputFileId: 'file-resume-123'
+ * });
+ *
+ * console.log('执行ID:', result.executionId);
+ * console.log('初始状态:', result.status);
+ *
+ * // 方式1：轮询查询结果
+ * const execution = await presetAgentTask.getExecutionById(result.executionId);
+ * console.log('输出文件:', execution.outputFileId);
+ *
+ * // 方式2：通过Webhook接收结果（需要在系统中配置Webhook）
+ * // POST /your-webhook-url
+ * // { module: "preset-agent-task", action: "execution.completed", data: {...} }
+ * ```
+ *
+ * @module preset-agent-task
+ */
+
+/**
+ * 预设Agent任务模块
+ */
+declare class PresetAgentTask {
+    private client;
+    private baseUrl;
+    constructor(client: PlolinkClient);
+    /**
+     * 创建预设
+     *
+     * @param params - 创建参数
+     * @returns 预设ID和code
+     * @throws {PlolinkError} 当参数无效或创建失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const result = await presetAgentTask.create({
+     *   code: 'talent-resume-parse',
+     *   name: '简历解析预设',
+     *   description: '自动解析简历并提取关键信息',
+     *   prompt: '请解析上传的简历文件，提取候选人的基本信息、教育背景、工作经历等关键数据',
+     *   model: 'doubao-seed-1-6-lite-251015',
+     *   selectedSkills: ['talent/resume-parse', 'common/file-extract'],
+     *   timeoutMs: 1800000,
+     *   businessKey: 'talent-resume-parse'
+     * });
+     *
+     * console.log('预设ID:', result.id);
+     * console.log('预设标识:', result.code);
+     * ```
+     */
+    create(params: CreatePresetParams): Promise<{
+        id: string;
+        code: string;
+    }>;
+    /**
+     * 获取预设列表
+     *
+     * @param options - 查询选项
+     * @returns 分页的预设列表
+     * @throws {PlolinkError} 当请求失败时抛出
+     *
+     * @example
+     * ```typescript
+     * // 获取所有启用的预设
+     * const result = await presetAgentTask.list({
+     *   enabled: true,
+     *   page: 1,
+     *   pageSize: 20
+     * });
+     *
+     * console.log('总数:', result.total);
+     * result.list.forEach(preset => {
+     *   console.log(`${preset.code}: ${preset.name}`);
+     * });
+     * ```
+     */
+    list(options?: PresetListQuery): Promise<PaginatedResult<PresetListItem>>;
+    /**
+     * 获取预设详情
+     *
+     * @param id - 预设ID
+     * @returns 预设详细信息
+     * @throws {PlolinkError} 当预设不存在时抛出
+     *
+     * @example
+     * ```typescript
+     * const preset = await presetAgentTask.getById('clx_preset_123');
+     * console.log('预设名称:', preset.name);
+     * console.log('预设指令:', preset.prompt);
+     * console.log('AI模型:', preset.model);
+     * ```
+     */
+    getById(id: string): Promise<PresetConfig>;
+    /**
+     * 通过code获取预设
+     *
+     * @param code - 预设唯一标识
+     * @returns 预设详细信息
+     * @throws {PlolinkError} 当预设不存在时抛出
+     *
+     * @example
+     * ```typescript
+     * const preset = await presetAgentTask.getByCode('talent-resume-parse');
+     * console.log('预设ID:', preset.id);
+     * console.log('预设名称:', preset.name);
+     * ```
+     */
+    getByCode(code: string): Promise<PresetConfig>;
+    /**
+     * 更新预设
+     *
+     * @param id - 预设ID
+     * @param params - 更新参数
+     * @throws {PlolinkError} 当预设不存在或更新失败时抛出
+     *
+     * @example
+     * ```typescript
+     * await presetAgentTask.update('clx_preset_123', {
+     *   name: '简历解析预设（更新）',
+     *   enabled: false
+     * });
+     *
+     * console.log('预设更新成功');
+     * ```
+     */
+    update(id: string, params: UpdatePresetParams): Promise<void>;
+    /**
+     * 删除预设
+     *
+     * @param id - 预设ID
+     * @throws {PlolinkError} 当预设不存在或删除失败时抛出
+     *
+     * @example
+     * ```typescript
+     * await presetAgentTask.delete('clx_preset_123');
+     * console.log('预设删除成功');
+     * ```
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * 执行预设（核心方法）
+     *
+     * @description
+     * 通过预设code执行预设任务。可以附加额外指令和输入文件。
+     *
+     * 执行后可以通过以下方式获取结果：
+     * - 方式1：轮询查询 - 使用 getExecutionById() 定期查询执行状态
+     * - 方式2：Webhook推送 - 配置Webhook接收执行完成通知
+     *
+     * @param params - 执行参数
+     * @returns 执行ID和初始状态
+     * @throws {PlolinkError} 当预设不存在或执行失败时抛出
+     *
+     * @example
+     * ```typescript
+     * // 执行预设
+     * const result = await presetAgentTask.execute({
+     *   code: 'talent-resume-parse',
+     *   additionalPrompt: '请特别关注技能匹配度',
+     *   inputFileId: 'file-resume-123'
+     * });
+     *
+     * console.log('执行ID:', result.executionId);
+     * console.log('初始状态:', result.status); // 'INITIALIZING'
+     *
+     * // 方式1：轮询查询结果
+     * let execution;
+     * do {
+     *   await new Promise(resolve => setTimeout(resolve, 5000)); // 等待5秒
+     *   execution = await presetAgentTask.getExecutionById(result.executionId);
+     *   console.log('当前状态:', execution.status);
+     * } while (execution.status === 'INITIALIZING' || execution.status === 'RUNNING');
+     *
+     * console.log('执行完成！');
+     * console.log('输出文件:', execution.outputFileId);
+     * console.log('Token消耗:', execution.metrics.inputTokens);
+     * console.log('费用:', execution.metrics.totalCost);
+     *
+     * // 方式2：通过Webhook接收结果（需要在系统中配置）
+     * // Webhook URL会收到POST请求：
+     * // {
+     * //   module: "preset-agent-task",
+     * //   action: "execution.completed",
+     * //   data: {
+     * //     executionId: "...",
+     * //     outputFileId: "...",
+     * //     metrics: {...}
+     * //   }
+     * // }
+     * ```
+     */
+    execute(params: ExecutePresetParams): Promise<ExecutionResult>;
+    /**
+     * 获取执行记录列表
+     *
+     * @param options - 查询选项
+     * @returns 分页的执行记录列表
+     * @throws {PlolinkError} 当请求失败时抛出
+     *
+     * @example
+     * ```typescript
+     * // 查询特定预设的执行记录
+     * const result = await presetAgentTask.listExecutions({
+     *   presetId: 'clx_preset_123',
+     *   status: 'COMPLETED',
+     *   page: 1,
+     *   pageSize: 20
+     * });
+     *
+     * console.log('总数:', result.total);
+     * result.list.forEach(execution => {
+     *   console.log(`执行ID: ${execution.id}, 状态: ${execution.status}`);
+     * });
+     * ```
+     */
+    listExecutions(options?: ExecutionListQuery): Promise<PaginatedResult<PresetExecutionListItem>>;
+    /**
+     * 获取执行详情
+     *
+     * @description
+     * 获取执行记录的完整信息，包括输出文件ID、Token消耗、费用等。
+     * 注意：不包含agentTaskId、runId（完全隐藏Agent Task细节）
+     *
+     * @param executionId - 执行ID
+     * @returns 执行详细信息
+     * @throws {PlolinkError} 当执行记录不存在时抛出
+     *
+     * @example
+     * ```typescript
+     * const execution = await presetAgentTask.getExecutionById('clx_exec_789');
+     *
+     * console.log('执行状态:', execution.status);
+     * console.log('预设名称:', execution.presetName);
+     * console.log('输入文件:', execution.inputFileId);
+     * console.log('输出文件:', execution.outputFileId);
+     * console.log('执行时长:', execution.duration, 'ms');
+     * console.log('Token消耗:', execution.metrics.inputTokens, '+', execution.metrics.outputTokens);
+     * console.log('总费用:', execution.metrics.totalCost, 'USD');
+     *
+     * if (execution.status === 'FAILED') {
+     *   console.error('错误信息:', execution.errorMessage);
+     * }
+     * ```
+     */
+    getExecutionById(executionId: string): Promise<PresetExecution>;
+    /**
+     * 取消执行
+     *
+     * @param executionId - 执行ID
+     * @param reason - 取消原因（可选）
+     * @throws {PlolinkError} 当执行不存在或取消失败时抛出
+     *
+     * @example
+     * ```typescript
+     * await presetAgentTask.cancelExecution('clx_exec_789', '用户主动取消');
+     * console.log('执行已取消');
+     * ```
+     */
+    cancelExecution(executionId: string, reason?: string): Promise<void>;
+    /**
+     * 重新执行
+     *
+     * @description
+     * 使用相同的参数重新执行预设任务。
+     *
+     * @param executionId - 原执行ID
+     * @returns 新的执行ID和状态
+     * @throws {PlolinkError} 当原执行不存在或重试失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const result = await presetAgentTask.retryExecution('clx_exec_789');
+     * console.log('新执行ID:', result.executionId);
+     * console.log('初始状态:', result.status);
+     * ```
+     */
+    retryExecution(executionId: string): Promise<ExecutionResult>;
+    /**
+     * 导出预设配置
+     *
+     * @description
+     * 导出选中的预设配置为JSON格式，可用于跨团队/环境迁移。
+     * 注意：extendedSkillsFileId需要手动处理（文件不跨团队）
+     *
+     * @param presetIds - 预设ID数组
+     * @returns 导出的配置（JSON格式）
+     * @throws {PlolinkError} 当预设不存在或导出失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const config = await presetAgentTask.export(['clx_preset_123', 'clx_preset_456']);
+     *
+     * console.log('配置版本:', config.version);
+     * console.log('导出时间:', config.exportedAt);
+     * console.log('预设数量:', config.presets.length);
+     *
+     * // 保存到文件（Node.js环境）
+     * const fs = require('fs');
+     * fs.writeFileSync('presets.json', JSON.stringify(config, null, 2));
+     * ```
+     */
+    export(presetIds: string[]): Promise<ExportedConfig>;
+    /**
+     * 导入预设配置
+     *
+     * @description
+     * 从导出的JSON配置导入预设到当前团队。
+     * 支持冲突处理策略：skip（跳过已存在）或 overwrite（覆盖已存在）
+     *
+     * @param config - 导出的配置
+     * @param conflictStrategy - 冲突策略（'skip' 或 'overwrite'），默认 'skip'
+     * @returns 导入结果
+     * @throws {PlolinkError} 当配置无效或导入失败时抛出
+     *
+     * @example
+     * ```typescript
+     * // 从文件读取（Node.js环境）
+     * const fs = require('fs');
+     * const config = JSON.parse(fs.readFileSync('presets.json', 'utf-8'));
+     *
+     * // 导入（跳过已存在的code）
+     * const result = await presetAgentTask.import(config, 'skip');
+     * console.log('导入成功:', result.imported);
+     * console.log('跳过:', result.skipped);
+     * console.log('失败:', result.failed);
+     *
+     * result.details.forEach(detail => {
+     *   console.log(`${detail.code}: ${detail.status}`);
+     *   if (detail.status === 'imported') {
+     *     console.log('  新预设ID:', detail.presetId);
+     *   } else if (detail.status === 'failed') {
+     *     console.log('  错误:', detail.error);
+     *   }
+     * });
+     * ```
+     */
+    import(config: ExportedConfig, conflictStrategy?: ConflictStrategy): Promise<ImportResult>;
+}
+
+export { type ConflictStrategy, type CreatePresetParams, type ExecutePresetParams, type ExecutionListQuery, type ExecutionMetrics, type ExecutionResult, type ExportedConfig, type ImportResult, type ImportResultDetail, type PaginatedResult, PresetAgentTask, type PresetConfig, type PresetConfigForExport, type PresetExecution, type PresetExecutionListItem, type PresetExecutionStatus, type PresetExecutionWebhookPayload, type PresetListItem, type PresetListQuery, type UpdatePresetParams };