@plolink/sdk 0.0.8 → 0.0.10

package/dist/modules/report-writer/index.d.cts

@@ -0,0 +1,476 @@
+import { P as PlolinkClient } from '../../client-CAjIQKPm.cjs';
+import '../../core-77EbLgbp.cjs';
+import 'axios';
+
+/**
+ * Report Writer 模块类型定义
+ */
+/**
+ * 报告状态枚举
+ */
+declare enum ReportStatus {
+    /** 未开始 */
+    PENDING = "PENDING",
+    /** 风格生成中 */
+    STYLE_GENERATING = "STYLE_GENERATING",
+    /** 材料摘要中 */
+    MATERIALS_SUMMARIZING = "MATERIALS_SUMMARIZING",
+    /** 结构生成中 */
+    STRUCTURE_GENERATING = "STRUCTURE_GENERATING",
+    /** 指引生成中 */
+    GUIDANCE_GENERATING = "GUIDANCE_GENERATING",
+    /** 内容生成中 */
+    CONTENT_GENERATING = "CONTENT_GENERATING",
+    /** 校对修订中 */
+    REVIEWING = "REVIEWING",
+    /** 已完成 */
+    COMPLETED = "COMPLETED",
+    /** 失败 */
+    FAILED = "FAILED"
+}
+/**
+ * 材料类型
+ */
+type MaterialType = 'text';
+/**
+ * 材料项
+ */
+interface MaterialItem {
+    /** 材料类型 */
+    type: MaterialType;
+    /** 材料内容 */
+    content: string;
+}
+/**
+ * 材料摘要
+ */
+interface MaterialsSummary {
+    /** 摘要内容（600-1200字） */
+    summary: string;
+    /** 关键事实 */
+    keyFacts: string[];
+    /** 关键词 */
+    keywords: string[];
+}
+/**
+ * 文章风格
+ */
+interface ArticleStyle {
+    /** 语气 */
+    tone: string;
+    /** 写作风格 */
+    writingStyle: string;
+    /** 目标受众 */
+    targetAudience: string;
+    /** 特点 */
+    characteristics: string[];
+}
+/**
+ * 校对建议
+ */
+interface ReviewSuggestion {
+    /** 是否需要修订 */
+    needsRevision: boolean;
+    /** 修改建议列表 */
+    suggestions: string[];
+}
+/**
+ * 文章节点（支持嵌套）
+ */
+interface ArticleNode {
+    /** 节点标题 */
+    title: string;
+    /** 内容填充指引 */
+    guidance: string;
+    /** 生成的内容 */
+    content: string;
+    /** 校对建议 */
+    reviewSuggestion: ReviewSuggestion | null;
+    /** 校对后的内容（如果有修订） */
+    revisedContent: string;
+    /** 子节点数组 */
+    children: ArticleNode[];
+}
+/**
+ * 创建报告参数
+ */
+interface CreateReportParams {
+    /** 报告名称 */
+    name: string;
+    /** 写作指令，描述要生成的文章内容 */
+    instruction: string;
+    /** 业务代号，用于后续处理策略分发 */
+    businessCode: string;
+    /** 外部ID，关联外部业务系统 */
+    externalId: string;
+    /** 参考材料数组 */
+    materials?: MaterialItem[];
+    /** 文章层级，1-3，默认 3 */
+    articleLevel?: number;
+}
+/**
+ * 创建报告响应
+ */
+interface CreateReportResponse {
+    /** 报告ID */
+    id: string;
+    /** 消息 */
+    message: string;
+}
+/**
+ * 列表查询参数
+ */
+interface ListReportsParams {
+    /** 页码，默认 1 */
+    page?: number;
+    /** 每页数量，默认 20 */
+    pageSize?: number;
+    /** 搜索关键词（报告名称、业务代号） */
+    keyword?: string;
+    /** 状态筛选 */
+    status?: ReportStatus;
+    /** 业务代号筛选 */
+    businessCode?: string;
+}
+/**
+ * 报告摘要（用于列表）
+ */
+interface ReportSummary {
+    /** 报告ID */
+    id: string;
+    /** 报告名称 */
+    name: string;
+    /** 业务代号 */
+    businessCode: string;
+    /** 外部ID */
+    externalId: string;
+    /** 状态 */
+    status: ReportStatus;
+    /** 创建时间 */
+    createdAt: string;
+    /** 更新时间 */
+    updatedAt: string;
+}
+/**
+ * 列表响应
+ */
+interface ListReportsResponse {
+    /** 报告列表 */
+    list: ReportSummary[];
+    /** 总数 */
+    total: number;
+    /** 当前页码 */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+}
+/**
+ * 报告详情
+ */
+interface ReportDetail {
+    /** 报告ID */
+    id: string;
+    /** 报告名称 */
+    name: string;
+    /** 写作指令 */
+    instruction: string;
+    /** 业务代号 */
+    businessCode: string;
+    /** 外部ID */
+    externalId: string;
+    /** 文章层级 */
+    articleLevel: number;
+    /** 参考材料 */
+    materials: MaterialItem[];
+    /** 材料摘要 */
+    materialsSummary: MaterialsSummary | null;
+    /** 文章风格 */
+    articleStyle: ArticleStyle | null;
+    /** 文章结构 */
+    articleStructure: ArticleNode[];
+    /** 状态 */
+    status: ReportStatus;
+    /** 错误信息 */
+    errorMessage: string;
+    /** 创建者ID */
+    creatorId: string;
+    /** 团队ID */
+    teamId: string;
+    /** 创建时间 */
+    createdAt: string;
+    /** 更新时间 */
+    updatedAt: string;
+}
+/**
+ * 获取 Markdown 响应
+ */
+interface GetMarkdownResponse {
+    /** Markdown 格式的报告内容 */
+    markdown: string;
+}
+/**
+ * Webhook 数据结构
+ */
+interface ReportWebhookData {
+    /** 业务模块 */
+    businessModule: 'report-writer';
+    /** 业务代码 */
+    businessCode: 'REPORT_COMPLETED' | 'REPORT_FAILED';
+    /** 业务ID（报告ID） */
+    businessId: string;
+    /** 业务数据 */
+    data: {
+        /** 报告ID */
+        reportId: string;
+        /** 外部ID */
+        externalId: string;
+        /** 业务代号 */
+        businessCode: string;
+        /** 状态（仅 REPORT_COMPLETED 时存在） */
+        status?: ReportStatus;
+        /** 报告详情（仅 REPORT_COMPLETED 时存在） */
+        reportDetail?: ReportDetail;
+        /** 错误信息（仅 REPORT_FAILED 时存在） */
+        errorMessage?: string;
+    };
+    /** 团队ID */
+    teamId: string;
+    /** 用户ID */
+    userId: string;
+    /** 同步记录ID */
+    syncRecordId: string;
+    /** 时间戳 */
+    timestamp: number;
+}
+
+/**
+ * Report Writer 模块
+ *
+ * @description
+ * 提供 AI 自动报告写作功能，支持：
+ * - 创建报告任务
+ * - 查询报告列表和详情
+ * - 删除报告
+ * - 导出 Markdown 格式
+ *
+ * @example
+ * ```typescript
+ * import { PlolinkClient } from '@plolink/sdk';
+ *
+ * const client = new PlolinkClient({
+ *   token: 'sk-your-api-key'
+ * });
+ *
+ * // 创建报告
+ * const createResult = await client.reportWriter.create({
+ *   name: '2024年度总结报告',
+ *   instruction: '请根据提供的材料，撰写一份年度工作总结报告',
+ *   businessCode: 'annual-report',
+ *   externalId: '2024-001',
+ *   articleLevel: 3,
+ *   materials: [
+ *     {
+ *       type: 'text',
+ *       content: '2024年完成了10个项目，总营收增长30%...'
+ *     }
+ *   ]
+ * });
+ * console.log(`报告创建成功: ${createResult.id}`);
+ *
+ * // 查询报告详情（轮询检查状态）
+ * let detail = await client.reportWriter.getDetail(createResult.id);
+ * while (detail.status !== 'COMPLETED' && detail.status !== 'FAILED') {
+ *   await new Promise(resolve => setTimeout(resolve, 5000));
+ *   detail = await client.reportWriter.getDetail(createResult.id);
+ *   console.log(`当前状态: ${detail.status}`);
+ * }
+ *
+ * // 获取 Markdown 格式
+ * if (detail.status === 'COMPLETED') {
+ *   const markdown = await client.reportWriter.getMarkdown(createResult.id);
+ *   console.log('报告内容:', markdown.markdown);
+ * }
+ * ```
+ *
+ * @module report-writer
+ */
+
+/**
+ * Report Writer 模块类
+ *
+ * @description
+ * 提供 AI 报告写作相关功能的封装，包括创建报告、查询状态、导出结果等。
+ *
+ * 报告生成流程：
+ * 1. 调用 create() 创建报告，返回 reportId
+ * 2. 后端异步处理，经历多个阶段（STYLE_GENERATING → ... → COMPLETED）
+ * 3. 使用 getDetail() 轮询检查状态
+ * 4. 完成后调用 getMarkdown() 获取最终结果
+ *
+ * Webhook 通知：
+ * - REPORT_COMPLETED - 报告生成完成
+ * - REPORT_FAILED - 报告生成失败
+ */
+declare class ReportWriter {
+    private client;
+    constructor(client: PlolinkClient);
+    /**
+     * 创建报告
+     *
+     * @description
+     * 创建一个新的报告任务，系统会自动加入队列进行处理。
+     * 报告生成过程是异步的，需要通过 getDetail() 方法轮询检查状态。
+     *
+     * @param params - 创建报告参数
+     * @param params.name - 报告名称
+     * @param params.instruction - 写作指令，描述要生成的文章内容
+     * @param params.businessCode - 业务代号，用于后续处理策略分发
+     * @param params.externalId - 外部ID，关联外部业务系统
+     * @param params.materials - 参考材料数组（可选）
+     * @param params.articleLevel - 文章层级，1-3，默认 3（可选）
+     *
+     * @returns 创建结果，包含报告ID
+     *
+     * @throws {PlolinkError} 参数验证失败或 API 调用失败
+     *
+     * @example
+     * ```typescript
+     * const result = await client.reportWriter.create({
+     *   name: '2024年度总结报告',
+     *   instruction: '请根据提供的材料，撰写一份年度工作总结报告',
+     *   businessCode: 'annual-report',
+     *   externalId: '2024-001',
+     *   articleLevel: 3,
+     *   materials: [
+     *     {
+     *       type: 'text',
+     *       content: '2024年完成了10个项目，总营收增长30%...'
+     *     }
+     *   ]
+     * });
+     * console.log(`报告ID: ${result.id}`);
+     * ```
+     */
+    create(params: CreateReportParams): Promise<CreateReportResponse>;
+    /**
+     * 获取报告列表
+     *
+     * @description
+     * 分页获取报告列表，支持按状态、业务代号、关键词筛选。
+     *
+     * @param params - 查询参数（可选）
+     * @param params.page - 页码，默认 1（可选）
+     * @param params.pageSize - 每页数量，默认 20（可选）
+     * @param params.keyword - 搜索关键词（报告名称、业务代号）（可选）
+     * @param params.status - 状态筛选（可选）
+     * @param params.businessCode - 业务代号筛选（可选）
+     *
+     * @returns 分页列表结果
+     *
+     * @throws {PlolinkError} API 调用失败
+     *
+     * @example
+     * ```typescript
+     * // 获取所有报告
+     * const allReports = await client.reportWriter.list();
+     *
+     * // 分页查询
+     * const page2 = await client.reportWriter.list({
+     *   page: 2,
+     *   pageSize: 10
+     * });
+     *
+     * // 按状态筛选
+     * const completedReports = await client.reportWriter.list({
+     *   status: 'COMPLETED'
+     * });
+     *
+     * // 按业务代号和关键词筛选
+     * const filtered = await client.reportWriter.list({
+     *   businessCode: 'annual-report',
+     *   keyword: '2024'
+     * });
+     * ```
+     */
+    list(params?: ListReportsParams): Promise<ListReportsResponse>;
+    /**
+     * 获取报告详情
+     *
+     * @description
+     * 获取单个报告的完整详情，包括文章风格、结构化内容和生成状态。
+     * 可用于轮询检查报告生成进度。
+     *
+     * @param id - 报告ID
+     *
+     * @returns 报告详情
+     *
+     * @throws {PlolinkError} 报告不存在或 API 调用失败
+     *
+     * @example
+     * ```typescript
+     * // 获取报告详情
+     * const detail = await client.reportWriter.getDetail('report-123');
+     * console.log(`状态: ${detail.status}`);
+     *
+     * // 轮询检查状态
+     * let report = await client.reportWriter.getDetail('report-123');
+     * while (report.status !== 'COMPLETED' && report.status !== 'FAILED') {
+     *   await new Promise(resolve => setTimeout(resolve, 5000)); // 等待5秒
+     *   report = await client.reportWriter.getDetail('report-123');
+     *   console.log(`当前状态: ${report.status}`);
+     * }
+     *
+     * if (report.status === 'COMPLETED') {
+     *   console.log('报告生成完成');
+     * } else {
+     *   console.error('报告生成失败:', report.errorMessage);
+     * }
+     * ```
+     */
+    getDetail(id: string): Promise<ReportDetail>;
+    /**
+     * 删除报告
+     *
+     * @description
+     * 软删除指定报告。已删除的报告无法恢复。
+     *
+     * @param id - 报告ID
+     *
+     * @returns Promise<void>
+     *
+     * @throws {PlolinkError} 报告不存在或 API 调用失败
+     *
+     * @example
+     * ```typescript
+     * await client.reportWriter.delete('report-123');
+     * console.log('报告已删除');
+     * ```
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * 获取 Markdown 格式
+     *
+     * @description
+     * 将报告内容渲染为 Markdown 格式。
+     * 只有状态为 COMPLETED 的报告才能导出 Markdown。
+     *
+     * @param id - 报告ID
+     *
+     * @returns Markdown 内容
+     *
+     * @throws {PlolinkError} 报告不存在、未完成或 API 调用失败
+     *
+     * @example
+     * ```typescript
+     * const result = await client.reportWriter.getMarkdown('report-123');
+     * console.log(result.markdown);
+     *
+     * // 保存为文件
+     * const fs = require('fs');
+     * fs.writeFileSync('report.md', result.markdown, 'utf-8');
+     * ```
+     */
+    getMarkdown(id: string): Promise<GetMarkdownResponse>;
+}
+
+export { type ArticleNode, type ArticleStyle, type CreateReportParams, type CreateReportResponse, type GetMarkdownResponse, type ListReportsParams, type ListReportsResponse, type MaterialItem, type MaterialType, type MaterialsSummary, type ReportDetail, ReportStatus, type ReportSummary, type ReportWebhookData, ReportWriter, type ReviewSuggestion };