llm-content-creator 0.1.0

package/src/domain/workflow/State.ts

@@ -0,0 +1,321 @@
+/**
+ * Workflow State - 工作流状态定义
+ *
+ * 定义 LangGraph 工作流的状态结构
+ * 每个节点接收完整的 State，返回要更新的字段（Partial<State>）
+ */
+
+import { ExecutionMode } from '../entities/Task.js';
+
+// 重新导出 ExecutionMode 以便外部使用
+export { ExecutionMode };
+
+/**
+ * 搜索结果项
+ */
+export interface SearchResultItem {
+  title: string;
+  url: string;
+  content: string;
+  score?: number;
+  publishedDate?: string;
+  author?: string;
+}
+
+/**
+ * 整理后的信息
+ */
+export interface OrganizedInfo {
+  outline: string;          // 文章大纲
+  keyPoints: string[];      // 关键点列表
+  summary: string;          // 摘要
+}
+
+/**
+ * 质检报告
+ */
+import type { QualityCheckDetails } from '../entities/QualityCheck.js';
+
+export interface QualityReport {
+  score: number;            // 评分（1-10）
+  passed: boolean;          // 是否通过
+  hardConstraintsPassed: boolean; // 硬性约束是否通过
+  modelName?: string;       // 使用的模型名称
+  details: QualityCheckDetails; // 质检详情
+  fixSuggestions?: string[]; // 改进建议（用于重写/重生成）
+  checkedAt?: number;       // 检查时间戳
+}
+
+/**
+ * 图片生成结果
+ */
+export interface GeneratedImage {
+  url: string;              // 图片 URL
+  prompt: string;           // 使用的提示词
+  width?: number;           // 宽度
+  height?: number;          // 高度
+  format?: string;          // 格式
+}
+
+/**
+ * 工作流状态
+ *
+ * 注意：
+ * - State 必须可序列化（JSON.stringify）
+ * - 不能包含函数、循环引用
+ * - 大对象使用引用（避免重复）
+ */
+export interface WorkflowState {
+  // ========== 输入参数 ==========
+  taskId: string;                        // 任务 ID
+  mode: ExecutionMode;                   // 执行模式（sync/async）
+  topic: string;                         // 选题
+  requirements: string;                  // 写作要求
+  hardConstraints: {                     // 硬性约束
+    minWords?: number;                   // 最小字数
+    maxWords?: number;                   // 最大字数
+    keywords?: string[];                 // 必须包含的关键词
+  };
+
+  // ========== 流程数据（各节点累积） ==========
+
+  // 搜索阶段
+  searchQuery?: string;                  // 搜索关键词（由 topic 生成）
+  searchResults?: SearchResultItem[];    // 搜索结果列表
+
+  // 整理阶段
+  organizedInfo?: OrganizedInfo;         // 整理后的信息
+
+  // 写作阶段
+  articleContent?: string;               // 文章内容（Markdown）
+  previousContent?: string;              // 上一版内容（用于重写）
+  imagePrompts?: string[];               // 配图提示词列表
+
+  // 配图阶段
+  images?: GeneratedImage[];             // 生成的配图列表
+  previousImages?: GeneratedImage[];     // 上一版配图（用于重生成）
+
+  // 质检阶段
+  textQualityReport?: QualityReport;     // 文本质检报告
+  imageQualityReport?: QualityReport;    // 配图质检报告
+
+  // ========== 控制数据（持久化到 DB） ==========
+  currentStep: string;                   // 当前步骤名称
+  textRetryCount: number;                // 文本质检重试次数
+  imageRetryCount: number;               // 配图质检重试次数
+
+  // ========== 元数据 ==========
+  startTime?: number;                    // 开始时间（时间戳）
+  endTime?: number;                      // 结束时间（时间戳）
+  error?: string;                        // 错误信息
+
+  // ========== 版本控制（乐观锁） ==========
+  version: number;                       // 版本号（用于数据库更新）
+}
+
+/**
+ * 创建初始状态
+ */
+export function createInitialState(params: {
+  taskId: string;
+  mode: ExecutionMode;
+  topic: string;
+  requirements: string;
+  targetAudience?: string;
+  keywords?: string[];
+  tone?: string;
+  hardConstraints?: {
+    minWords?: number;
+    maxWords?: number;
+    keywords?: string[];
+  };
+}): WorkflowState {
+  return {
+    taskId: params.taskId,
+    mode: params.mode,
+    topic: params.topic,
+    requirements: params.requirements,
+    hardConstraints: params.hardConstraints || {},
+
+    currentStep: 'start',
+    textRetryCount: 0,
+    imageRetryCount: 0,
+    version: 1, // 初始版本号
+
+    startTime: Date.now(),
+  };
+}
+
+/**
+ * 状态更新辅助函数
+ */
+export class StateUpdater {
+  /**
+   * 创建状态更新（类型安全的 Partial）
+   */
+  static update<T extends keyof WorkflowState>(
+    field: T,
+    value: WorkflowState[T]
+  ): Partial<WorkflowState> {
+    return { [field]: value } as Partial<WorkflowState>;
+  }
+
+  /**
+   * 批量更新状态
+   */
+  static updates(updates: Partial<WorkflowState>): Partial<WorkflowState> {
+    return updates;
+  }
+
+  /**
+   * 更新当前步骤
+   */
+  static updateStep(stepName: string): Partial<WorkflowState> {
+    return {
+      currentStep: stepName,
+    };
+  }
+
+  /**
+   * 增加重试计数
+   */
+  static incrementTextRetry(state: WorkflowState): Partial<WorkflowState> {
+    return {
+      textRetryCount: state.textRetryCount + 1,
+    };
+  }
+
+  static incrementImageRetry(state: WorkflowState): Partial<WorkflowState> {
+    return {
+      imageRetryCount: state.imageRetryCount + 1,
+    };
+  }
+
+  /**
+   * 标记错误
+   */
+  static markError(error: string): Partial<WorkflowState> {
+    return {
+      error,
+      endTime: Date.now(),
+    };
+  }
+
+  /**
+   * 标记完成
+   */
+  static markComplete(): Partial<WorkflowState> {
+    return {
+      currentStep: 'complete',
+      endTime: Date.now(),
+    };
+  }
+}
+
+/**
+ * 状态验证工具
+ */
+export class StateValidator {
+  /**
+   * 验证状态是否可序列化
+   */
+  static validateSerializable(state: WorkflowState): boolean {
+    try {
+      JSON.stringify(state);
+      return true;
+    } catch (error) {
+      console.error('State is not serializable:', error);
+      return false;
+    }
+  }
+
+  /**
+   * 验证必需字段
+   */
+  static validateRequired(state: WorkflowState): boolean {
+    const required: Array<keyof WorkflowState> = [
+      'taskId',
+      'mode',
+      'topic',
+      'requirements',
+      'hardConstraints',
+      'currentStep',
+      'textRetryCount',
+      'imageRetryCount',
+      'version',
+    ];
+
+    for (const field of required) {
+      if (state[field] === undefined || state[field] === null) {
+        console.error(`Missing required field: ${field}`);
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * 验证状态完整性
+   */
+  static validate(state: WorkflowState): boolean {
+    return this.validateSerializable(state) && this.validateRequired(state);
+  }
+}
+
+/**
+ * State 快照管理
+ */
+export class StateSnapshotManager {
+  /**
+   * 序列化状态
+   */
+  static serialize(state: WorkflowState): string {
+    if (!StateValidator.validateSerializable(state)) {
+      throw new Error('State is not serializable');
+    }
+    return JSON.stringify(state);
+  }
+
+  /**
+   * 反序列化状态
+   */
+  static deserialize(json: string): WorkflowState {
+    try {
+      const state = JSON.parse(json) as WorkflowState;
+      if (!StateValidator.validate(state)) {
+        throw new Error('Invalid state structure');
+      }
+      return state;
+    } catch (error) {
+      console.error('Failed to deserialize state:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * 克隆状态（深拷贝）
+   */
+  static clone(state: WorkflowState): WorkflowState {
+    return JSON.parse(JSON.stringify(state)) as WorkflowState;
+  }
+
+  /**
+   * 创建检查点快照（只保存必要字段）
+   */
+  static createCheckpoint(state: WorkflowState): Partial<WorkflowState> {
+    return {
+      searchResults: state.searchResults,
+      organizedInfo: state.organizedInfo,
+      articleContent: state.articleContent,
+      imagePrompts: state.imagePrompts,
+      images: state.images,
+      textQualityReport: state.textQualityReport,
+      imageQualityReport: state.imageQualityReport,
+      currentStep: state.currentStep,
+      textRetryCount: state.textRetryCount,
+      imageRetryCount: state.imageRetryCount,
+      version: state.version,
+    };
+  }
+}

package/src/domain/workflow/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Workflow 层导出
+ *
+ * 统一导出所有工作流相关的类和接口
+ */
+
+// State
+export * from './State.js';
+
+// Nodes
+export * from './nodes/BaseNode.js';
+export * from './nodes/index.js';
+
+// Checkpoint Manager
+export * from './CheckpointManager.js';
+
+// Graph
+export * from './ContentCreatorGraph.js';

package/src/domain/workflow/nodes/BaseNode.ts

@@ -0,0 +1,325 @@
+/**
+ * BaseNode - 节点基类
+ *
+ * 所有工作流节点的基类，提供通用功能：
+ * - 错误处理
+ * - Token 记录
+ * - 日志记录
+ * - 状态验证
+ * - 重试支持
+ */
+
+import type { WorkflowState } from '../State.js';
+import { createLogger } from '../../../infrastructure/logging/logger.js';
+
+const logger = createLogger('BaseNode');
+
+/**
+ * 节点执行结果
+ */
+export interface NodeResult {
+  success: boolean;
+  stateUpdate: Partial<WorkflowState>;
+  error?: string;
+  tokenUsage?: {
+    tokensIn: number;
+    tokensOut: number;
+    totalTokens: number;
+  };
+  duration: number; // 执行时长（毫秒）
+}
+
+/**
+ * 节点配置
+ */
+export interface NodeConfig {
+  name: string;              // 节点名称
+  retryCount?: number;       // 重试次数（默认 0）
+  timeout?: number;          // 超时时间（毫秒，默认 60000）
+}
+
+/**
+ * 节点基类
+ */
+export abstract class BaseNode {
+  protected readonly name: string;
+  protected readonly retryCount: number;
+  protected readonly timeout: number;
+  protected readonly logger;
+
+  constructor(config: NodeConfig) {
+    this.name = config.name;
+    this.retryCount = config.retryCount ?? 0;
+    this.timeout = config.timeout ?? 60000; // 60 秒默认超时
+    this.logger = createLogger(`Node:${this.name}`);
+  }
+
+  /**
+   * 执行节点（带重试和错误处理）
+   *
+   * @param state - 当前工作流状态
+   * @returns 节点执行结果
+   */
+  async execute(state: WorkflowState): Promise<NodeResult> {
+    const startTime = Date.now();
+    const attempt = this.getAttemptCount(state);
+
+    this.logger.info('Node execution started', {
+      nodeId: this.name,
+      taskId: state.taskId,
+      attempt: attempt + 1,
+    });
+
+    try {
+      // 验证状态
+      this.validateState(state);
+
+      // 执行节点逻辑（带超时）
+      const stateUpdate = await this.executeWithTimeout(state);
+
+      // 计算执行时长
+      const duration = Date.now() - startTime;
+
+      // 记录成功日志
+      this.logger.info('Node execution completed', {
+        nodeId: this.name,
+        taskId: state.taskId,
+        duration,
+      });
+
+      // 返回结果
+      return {
+        success: true,
+        stateUpdate: {
+          ...stateUpdate,
+          currentStep: this.name,
+        },
+        duration,
+      };
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      // 记录错误日志
+      this.logger.error('Node execution failed', {
+        nodeId: this.name,
+        taskId: state.taskId,
+        error: errorMessage,
+        duration,
+      });
+
+      // 返回错误结果
+      return {
+        success: false,
+        stateUpdate: {
+          error: errorMessage,
+        },
+        error: errorMessage,
+        duration,
+      };
+    }
+  }
+
+  /**
+   * 抽象方法：节点具体逻辑（由子类实现）
+   *
+   * @param state - 当前工作流状态
+   * @returns 状态更新（Partial<WorkflowState>）
+   */
+  protected abstract executeLogic(state: WorkflowState): Promise<Partial<WorkflowState>>;
+
+  /**
+   * 验证状态（可选，由子类重写）
+   *
+   * @param state - 当前工作流状态
+   * @throws Error 如果状态无效
+   */
+  protected validateState(state: WorkflowState): void {
+    // 默认验证：检查是否有错误
+    if (state.error) {
+      throw new Error(`Previous error: ${state.error}`);
+    }
+  }
+
+  /**
+   * 获取当前尝试次数（可选，由子类重写）
+   *
+   * @param state - 当前工作流状态
+   * @returns 尝试次数
+   */
+  protected getAttemptCount(_state: WorkflowState): number {
+    // 默认：返回 0
+    // 子类可以根据 state 中的重试计数器返回实际值
+    return 0;
+  }
+
+  /**
+   * 执行节点逻辑（带超时控制）
+   *
+   * @param state - 当前工作流状态
+   * @returns 状态更新
+   */
+  private async executeWithTimeout(state: WorkflowState): Promise<Partial<WorkflowState>> {
+    return Promise.race([
+      this.executeLogic(state),
+      this.createTimeoutPromise(),
+    ]);
+  }
+
+  /**
+   * 创建超时 Promise
+   */
+  private createTimeoutPromise(): Promise<never> {
+    return new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`Node timeout: ${this.name} exceeded ${this.timeout}ms`));
+      }, this.timeout);
+    });
+  }
+
+  /**
+   * 记录 LLM Token 使用（可选，由子类调用）
+   *
+   * @param state - 工作流状态
+   * @param tokensIn - 输入 Token 数量
+   * @param tokensOut - 输出 Token 数量
+   */
+  protected recordTokenUsage(
+    state: WorkflowState,
+    tokensIn: number,
+    tokensOut: number
+  ): void {
+    this.logger.debug('Token usage recorded', {
+      nodeId: this.name,
+      taskId: state.taskId,
+      tokensIn,
+      tokensOut,
+      totalTokens: tokensIn + tokensOut,
+    });
+
+    // TODO: 保存到数据库（后续实现）
+    // await tokenUsageRepo.create({
+    //   taskId: state.taskId,
+    //   traceId: generateTraceId(),
+    //   stepName: this.name,
+    //   apiName: 'deepseek',
+    //   modelName: 'deepseek-chat',
+    //   tokensIn,
+    //   tokensOut,
+    //   totalTokens: tokensIn + tokensOut,
+    //   ...
+    // });
+  }
+
+  /**
+   * 创建状态更新辅助函数
+   */
+  protected updateState<T extends keyof WorkflowState>(
+    field: T,
+    value: WorkflowState[T]
+  ): Partial<WorkflowState> {
+    return { [field]: value } as Partial<WorkflowState>;
+  }
+
+  /**
+   * 转换为 LangGraph 节点
+   *
+   * @returns LangGraph 节点函数
+   */
+  toLangGraphNode(): (state: WorkflowState) => Promise<Partial<WorkflowState>> {
+    return async (state: WorkflowState) => {
+      logger.debug(`Node ${this.name} received state`, {
+        taskId: state.taskId,
+        topic: state.topic,
+        hasTopic: !!state.topic,
+        stateKeys: Object.keys(state),
+      });
+
+      const result = await this.execute(state);
+
+      if (!result.success) {
+        throw new Error(result.error || 'Node execution failed');
+      }
+
+      return result.stateUpdate;
+    };
+  }
+}
+
+/**
+ * 节点执行上下文
+ *
+ * 提供额外的工具和方法供节点使用
+ */
+export class NodeContext {
+  protected readonly logger;
+
+  constructor(nodeName: string) {
+    this.logger = createLogger(`Node:${nodeName}`);
+  }
+
+  /**
+   * 生成 Trace ID（用于链路追踪）
+   */
+  generateTraceId(): string {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+  }
+
+  /**
+   * 延迟执行（毫秒）
+   */
+  async delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * 计算文本的 Token 数量（估算）
+   */
+  estimateTokens(text: string): number {
+    // 粗略估算：英文约 4 字符/token，中文约 1.5 字符/token
+    const chineseChars = (text.match(/[\u4e00-\u9fa5]/g) || []).length;
+    const englishChars = text.length - chineseChars;
+
+    return Math.ceil(chineseChars / 1.5 + englishChars / 4);
+  }
+
+  /**
+   * 截断文本到指定 Token 数量
+   */
+  truncateToTokens(text: string, maxTokens: number): string {
+    const estimatedTokens = this.estimateTokens(text);
+
+    if (estimatedTokens <= maxTokens) {
+      return text;
+    }
+
+    // 粗略截断：按比例缩短
+    const ratio = maxTokens / estimatedTokens;
+    const truncatedLength = Math.floor(text.length * ratio);
+    return text.substring(0, truncatedLength);
+  }
+
+  /**
+   * 安全地解析 JSON
+   */
+  safeParseJSON<T>(json: string, fallback: T): T {
+    try {
+      return JSON.parse(json) as T;
+    } catch (error) {
+      this.logger.warn('Failed to parse JSON, using fallback', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return fallback;
+    }
+  }
+
+  /**
+   * 格式化错误消息
+   */
+  formatError(error: unknown): string {
+    if (error instanceof Error) {
+      return error.message;
+    }
+    return String(error);
+  }
+}