llm-content-creator 0.1.0

package/docs/workflow-architecture.md

@@ -0,0 +1,549 @@
+# Content Creator LangGraph 工作流架构
+
+## 📊 图结构概览
+
+这是一个基于 LangGraph 的 AI 内容创作工作流，包含 **6 个核心节点** 和 **2 个条件路由**，支持质检失败重试和断点续传。
+
+---
+
+## 🎯 核心流程图
+
+```
+                    ┌─────────────────────────────────────────┐
+                    │           Content Creator               │
+                    │         LangGraph Workflow              │
+                    └─────────────────────────────────────────┘
+                                       │
+                                       ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  1️⃣  SEARCH (搜索资料)                                           │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
+│  输入: topic (主题)                                              │
+│  处理: 使用 Tavily API 搜索相关资料                              │
+│  输出: searchQuery (搜索关键词) + searchResults (搜索结果)       │
+│  检查点: ✅ 保存状态                                             │
+└─────────────────────────────────────────────────────────────────┘
+                                       │
+                                       ▼ (线性边)
+┌─────────────────────────────────────────────────────────────────┐
+│  2️⃣  ORGANIZE (整理大纲)                                         │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
+│  输入: searchResults (搜索结果)                                  │
+│  处理: 使用 LLM 整理成文章大纲和关键点                           │
+│  输出: organizedInfo (大纲、关键点、摘要)                        │
+│  检查点: ✅ 保存状态                                             │
+└─────────────────────────────────────────────────────────────────┘
+                                       │
+                                       ▼ (线性边)
+┌─────────────────────────────────────────────────────────────────┐
+│  3️⃣  WRITE (撰写内容)                                           │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
+│  输入: topic + requirements + organizedInfo                     │
+│  处理: 使用 DeepSeek LLM 生成文章内容                           │
+│  输出: articleContent (Markdown) + imagePrompts (配图提示词)    │
+│  检查点: ✅ 保存状态                                             │
+└─────────────────────────────────────────────────────────────────┘
+                                       │
+                                       ▼ (线性边)
+┌─────────────────────────────────────────────────────────────────┐
+│  4️⃣  CHECK_TEXT (文本质检)                                       │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
+│  输入: articleContent + hardConstraints                        │
+│  处理: 硬规则检查 + LLM 质量评估                                │
+│  输出: textQualityReport (评分、是否通过、详细报告)             │
+│  检查点: ✅ 保存状态                                             │
+└─────────────────────────────────────────────────────────────────┘
+                                       │
+                       ┌───────────────┴───────────────┐
+                       │   条件路由 (Conditional)       │
+                       │   routeAfterCheckText()       │
+                       └───────────────┬───────────────┘
+                                       │
+                    ┌──────────────────┼──────────────────┐
+                    │                  │                  │
+              质检通过 ✅          质检失败 ❌        重试超限 ❌
+            (passed=true)      (retry<3)          (retry>=3)
+                    │                  │                  │
+                    ▼                  ▼                  ▼
+         ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+         │GENERATE_IMAGE│    │   WRITE      │    │  抛出异常    │
+         │  (生成配图)  │◀───│  (重写内容)  │    │   (失败)     │
+         └──────────────┘    └──────────────┘    └──────────────┘
+                    │                                  │
+                    │                                  ▼
+                    │                        ┌──────────────────┐
+                    │                        │  结束 (失败)     │
+                    │                        └──────────────────┘
+                    │
+                    ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  5️⃣  GENERATE_IMAGE (生成配图)                                   │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
+│  输入: imagePrompts (来自 Write 节点)                            │
+│  处理: 使用 Doubao API 生成配图                                  │
+│  输出: images (图片 URL、尺寸、提示词)                          │
+│  检查点: ✅ 保存状态                                             │
+└─────────────────────────────────────────────────────────────────┘
+                                       │
+                                       ▼ (线性边)
+┌─────────────────────────────────────────────────────────────────┐
+│  6️⃣  CHECK_IMAGE (配图质检)                                      │
+│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
+│  输入: images                                                    │
+│  处理: 检查图片质量和相关性                                      │
+│  输出: imageQualityReport (评分、是否通过)                       │
+│  检查点: ✅ 保存状态                                             │
+└─────────────────────────────────────────────────────────────────┘
+                                       │
+                       ┌───────────────┴───────────────┐
+                       │   条件路由 (Conditional)       │
+                       │   routeAfterCheckImage()      │
+                       └───────────────┬───────────────┘
+                                       │
+                    ┌──────────────────┼──────────────────┐
+                    │                  │                  │
+              质检通过 ✅          质检失败 ❌        重试超限 ❌
+            (passed=true)      (retry<2)          (retry>=2)
+                    │                  │                  │
+                    ▼                  ▼                  ▼
+         ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+         │    结束      │    │GENERATE_IMAGE│    │  抛出异常    │
+         │   (成功)     │◀───│  (重新生成)  │    │   (失败)     │
+         └──────────────┘    └──────────────┘    └──────────────┘
+```
+
+---
+
+## 🏗️ 图结构详细说明
+
+### 1️⃣ **节点 (Nodes)**
+
+#### **SearchNode** - 搜索资料节点
+```typescript
+输入: WorkflowState {
+  topic: string;
+  requirements: string;
+}
+
+处理:
+  - 根据 topic 生成搜索关键词
+  - 调用 Tavily API 搜索相关资料
+  - 返回搜索结果列表
+
+输出: Partial<WorkflowState> {
+  searchQuery: string;
+  searchResults: SearchResultItem[];
+  currentStep: 'search';
+}
+```
+
+#### **OrganizeNode** - 整理大纲节点
+```typescript
+输入: WorkflowState {
+  searchResults: SearchResultItem[];
+}
+
+处理:
+  - 使用 LLM 分析搜索结果
+  - 生成文章大纲 (outline)
+  - 提取关键点 (keyPoints)
+  - 生成摘要 (summary)
+
+输出: Partial<WorkflowState> {
+  organizedInfo: {
+    outline: string;
+    keyPoints: string[];
+    summary: string;
+  };
+  currentStep: 'organize';
+}
+```
+
+#### **WriteNode** - 撰写内容节点
+```typescript
+输入: WorkflowState {
+  topic: string;
+  requirements: string;
+  organizedInfo: OrganizedInfo;
+  hardConstraints: { minWords, maxWords, keywords };
+}
+
+处理:
+  - 使用 DeepSeek LLM 生成文章
+  - 生成配图提示词 (imagePrompts)
+  - 保存上一版本用于重写 (previousContent)
+
+输出: Partial<WorkflowState> {
+  articleContent: string;
+  imagePrompts: string[];
+  previousContent: string;
+  currentStep: 'write';
+}
+```
+
+#### **CheckTextNode** - 文本质检节点
+```typescript
+输入: WorkflowState {
+  articleContent: string;
+  hardConstraints;
+  textRetryCount;
+}
+
+处理:
+  1. 硬规则检查 (HardRuleChecker):
+     - 字数检查 (minWords / maxWords)
+     - 关键词检查 (keywords)
+     - 结构检查 (标题、开头、正文、结尾)
+
+  2. LLM 质量评估 (LLMEvaluator):
+     - 相关性 (relevance)
+     - 连贯性 (coherence)
+     - 完整性 (completeness)
+     - 可读性 (readability)
+
+  3. 综合评分 (1-10分)
+
+输出: Partial<WorkflowState> {
+  textQualityReport: {
+    score: number;
+    passed: boolean;
+    hardConstraintsPassed: boolean;
+    details: { ... };
+    fixSuggestions: string[];
+  };
+  currentStep: 'checkText';
+}
+```
+
+#### **GenerateImageNode** - 生成配图节点
+```typescript
+输入: WorkflowState {
+  imagePrompts: string[];
+  articleContent: string;
+}
+
+处理:
+  - 使用 Doubao API 生成图片
+  - 支持多张图片生成
+  - 保存上一版本用于重生成 (previousImages)
+
+输出: Partial<WorkflowState> {
+  images: GeneratedImage[];
+  previousImages: GeneratedImage[];
+  currentStep: 'generateImage';
+}
+```
+
+#### **CheckImageNode** - 配图质检节点
+```typescript
+输入: WorkflowState {
+  images: GeneratedImage[];
+  articleContent: string;
+  imageRetryCount;
+}
+
+处理:
+  - 检查图片质量 (分辨率、格式)
+  - 检查图片相关性
+  - 评分 (1-10分)
+
+输出: Partial<WorkflowState> {
+  imageQualityReport: {
+    score: number;
+    passed: boolean;
+    details: { ... };
+  };
+  currentStep: 'checkImage';
+}
+```
+
+---
+
+### 2️⃣ **边 (Edges)**
+
+#### **线性边 (Linear Edges)**
+```
+search → organize → write → checkText
+generate_image → checkImage
+```
+无条件流转，顺序执行。
+
+#### **条件边 (Conditional Edges)**
+
+**checkText → routeAfterCheckText()**
+```typescript
+function routeAfterCheckText(state: WorkflowState): string {
+  if (state.textQualityReport?.passed) {
+    return 'generate_image';  // 质检通过，生成配图
+  }
+
+  if (state.textRetryCount < 3) {
+    return 'write';  // 质检失败，重试写作
+  }
+
+  throw new Error('Text quality check failed after 3 attempts');
+}
+```
+
+**checkImage → routeAfterCheckImage()**
+```typescript
+function routeAfterCheckImage(state: WorkflowState): string {
+  if (state.imageQualityReport?.passed) {
+    return '__end__';  // 质检通过，结束流程
+  }
+
+  if (state.imageRetryCount < 2) {
+    return 'generate_image';  // 质检失败，重新生成
+  }
+
+  throw new Error('Image quality check failed after 2 attempts');
+}
+```
+
+---
+
+### 3️⃣ **状态 (State)**
+
+```typescript
+interface WorkflowState {
+  // 输入参数
+  taskId: string;
+  mode: 'sync' | 'async';
+  topic: string;
+  requirements: string;
+  hardConstraints: {
+    minWords?: number;
+    maxWords?: number;
+    keywords?: string[];
+  };
+
+  // 流程数据 (节点间传递)
+  searchQuery?: string;
+  searchResults?: SearchResultItem[];
+  organizedInfo?: OrganizedInfo;
+  articleContent?: string;
+  previousContent?: string;      // 用于重写
+  imagePrompts?: string[];
+  images?: GeneratedImage[];
+  previousImages?: GeneratedImage[];  // 用于重生成
+
+  // 质检报告
+  textQualityReport?: QualityReport;
+  imageQualityReport?: QualityReport;
+
+  // 控制数据
+  currentStep: string;
+  textRetryCount: number;        // 文本质检重试次数 (最多3次)
+  imageRetryCount: number;       // 配图质检重试次数 (最多2次)
+
+  // 元数据
+  version: number;               // 乐观锁版本号
+  startTime?: number;
+  endTime?: number;
+  error?: string;
+}
+```
+
+---
+
+### 4️⃣ **检查点机制 (Checkpoint)**
+
+每个节点执行后都会保存检查点：
+
+```typescript
+function wrapNodeWithCheckpoint(nodeName, node) {
+  return async (state: WorkflowState) => {
+    // 1. 执行节点逻辑
+    const result = await node(state);
+
+    // 2. 保存检查点到存储 (SQLite/PostgreSQL)
+    await checkpointManager.saveCheckpoint(
+      state.taskId,
+      nodeName,
+      { ...state, ...result }
+    );
+
+    // 3. 返回结果
+    return { ...result, currentStep: nodeName };
+  };
+}
+```
+
+**断点续传流程：**
+```
+1. 检查点保存: 每个节点完成后保存完整状态
+2. 崩溃恢复: 从最后一个检查点恢复状态
+3. 继续执行: 从崩溃的节点重新开始
+```
+
+---
+
+## 🔄 重试机制
+
+### **文本质检重试**
+```
+失败 → 重试 1 → 失败 → 重试 2 → 失败 → 重试 3 → 失败 → 抛出异常
+       (write)         (write)         (write)
+```
+
+- **最大重试次数**: 3 次
+- **重试策略**: 重新调用 WriteNode 生成新内容
+- **保留历史**: previousContent 保存上一版本
+
+### **配图质检重试**
+```
+失败 → 重试 1 → 失败 → 重试 2 → 失败 → 抛出异常
+       (generate_image)  (generate_image)
+```
+
+- **最大重试次数**: 2 次
+- **重试策略**: 重新调用 GenerateImageNode 生成新图片
+- **保留历史**: previousImages 保存上一版本
+
+---
+
+## 📊 执行流程示例
+
+### **成功路径**
+```
+START
+  ↓
+search (搜索资料) ✅
+  ↓
+organize (整理大纲) ✅
+  ↓
+write (撰写内容) ✅
+  ↓
+checkText (文本质检) ✅ passed=true
+  ↓
+generate_image (生成配图) ✅
+  ↓
+checkImage (配图质检) ✅ passed=true
+  ↓
+END (成功完成)
+```
+
+### **失败重试路径**
+```
+START
+  ↓
+... → write (撰写内容) ✅
+  ↓
+checkText (文本质检) ❌ passed=false, retry=0
+  ↓ (条件路由)
+write (重写内容) ✅ retry=1
+  ↓
+checkText (文本质检) ❌ passed=false, retry=1
+  ↓ (条件路由)
+write (重写内容) ✅ retry=2
+  ↓
+checkText (文本质检) ✅ passed=true
+  ↓
+... → END
+```
+
+---
+
+## 🛠️ 技术实现
+
+### **LangGraph 组件**
+```typescript
+import { StateGraph, END } from '@langchain/langgraph';
+
+// 创建图
+const graph = new StateGraph<WorkflowState>({ channels });
+
+// 添加节点
+graph.addNode('search', searchNodeFn);
+graph.addNode('organize', organizeNodeFn);
+graph.addNode('write', writeNodeFn);
+graph.addNode('checkText', checkTextNodeFn);
+graph.addNode('generate_image', generateImageNodeFn);
+graph.addNode('checkImage', checkImageNodeFn);
+
+// 设置入口
+graph.setEntryPoint('search');
+
+// 添加边
+graph.addEdge('search', 'organize');
+graph.addEdge('organize', 'write');
+graph.addEdge('write', 'checkText');
+graph.addEdge('generate_image', 'checkImage');
+
+// 添加条件边
+graph.addConditionalEdges('checkText', routeAfterCheckText, {
+  write: 'write',
+  generate_image: 'generate_image',
+});
+
+graph.addConditionalEdges('checkImage', routeAfterCheckImage, {
+  generate_image: 'generate_image',
+  __end__: END,
+});
+
+// 编译图
+const compiledGraph = graph.compile();
+```
+
+---
+
+## 🎨 图的类型
+
+### **完整版 (createContentCreatorGraph)**
+- ✅ 带检查点保存
+- ✅ 支持断点续传
+- ✅ 状态持久化到数据库
+
+### **简化版 (createSimpleContentCreatorGraph)**
+- ❌ 无检查点
+- ✅ 更快的执行速度
+- ✅ 适合测试和简单场景
+
+---
+
+## 📈 性能优化
+
+1. **并行执行**: 未来可支持并行搜索多个主题
+2. **缓存机制**: 搜索结果缓存 (CacheService)
+3. **批量处理**: 支持多任务并发执行
+4. **资源管理**: 自动清理临时数据
+
+---
+
+## 🔍 监控和调试
+
+### **日志记录**
+```typescript
+logger.info('Executing node: search', { taskId });
+logger.info('Routing after check text', { passed, retryCount });
+```
+
+### **状态追踪**
+```typescript
+currentStep: 'search' | 'organize' | 'write' | 'checkText' | 'generateImage' | 'checkImage'
+```
+
+### **错误处理**
+```typescript
+try {
+  const result = await node(state);
+} catch (error) {
+  logger.error(`Node failed: ${nodeName}`, { error });
+  throw error;
+}
+```
+
+---
+
+## 📝 总结
+
+这个 LangGraph 工作流实现了：
+
+✅ **6 个核心节点**：搜索 → 整理 → 写作 → 文本质检 → 生成配图 → 配图质检
+✅ **2 个条件路由**：质检失败自动重试
+✅ **检查点机制**：每个节点保存状态，支持断点续传
+✅ **双重质检**：硬规则 + LLM 质量评估
+✅ **自动重试**：文本最多 3 次，图片最多 2 次
+✅ **状态管理**：完整的状态传递和更新机制
+
+这是一个**生产级的 AI 内容创作工作流**，具备高可靠性和可扩展性！

package/package.json

@@ -0,0 +1,126 @@
+{
+  "name": "llm-content-creator",
+  "version": "0.1.0",
+  "description": "AI 驱动的内容创作工具库",
+  "main": "dist/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./config": {
+      "import": "./dist/config/index.js",
+      "require": "./dist/config/index.cjs"
+    },
+    "./database": {
+      "import": "./dist/infrastructure/database/index.js",
+      "require": "./dist/infrastructure/database/index.cjs"
+    },
+    "./workflow": {
+      "import": "./dist/domain/workflow/ContentCreatorGraph.js",
+      "require": "./dist/domain/workflow/ContentCreatorGraph.cjs"
+    },
+    "./executor": {
+      "import": "./dist/application/workflow/SyncExecutor.js",
+      "require": "./dist/application/workflow/SyncExecutor.cjs"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "src/**/*.ts",
+    "README.md",
+    "docs/**/*"
+  ],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:unit": "vitest run --exclude=\"**/integration/**/*.test.ts\" --exclude=\"**/performance/**/*.test.ts\"",
+    "test:integration": "vitest run tests/integration",
+    "test:performance": "vitest run tests/performance",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:verbose": "vitest run --reporter=verbose",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "verify-env": "tsx scripts/verify-env.ts",
+    "db:migrate": "tsx scripts/run-migration.ts run",
+    "db:rollback": "tsx scripts/run-migration.ts undo",
+    "db:status": "tsx scripts/run-migration.ts status",
+    "cli": "tsx src/presentation/cli/index.ts",
+    "cli:create": "tsx src/presentation/cli/index.ts create",
+    "cli:status": "tsx src/presentation/cli/index.ts status",
+    "cli:result": "tsx src/presentation/cli/index.ts result",
+    "cli:cancel": "tsx src/presentation/cli/index.ts cancel",
+    "worker": "tsx src/presentation/worker-cli.ts start",
+    "worker:dev": "tsx watch src/presentation/worker-cli.ts start",
+    "monitor": "tsx src/presentation/monitor-cli.ts start",
+    "scheduler": "tsx src/presentation/scheduler-cli.ts"
+  },
+  "keywords": [
+    "ai",
+    "content-creation",
+    "langgraph",
+    "llm",
+    "workflow",
+    "automation",
+    "writing"
+  ],
+  "author": "Oychao",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oychao1988/content-creator"
+  },
+  "homepage": "https://github.com/oychao1988/content-creator#readme",
+  "bugs": {
+    "url": "https://github.com/oychao1988/content-creator/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@bull-board/api": "^6.16.2",
+    "@bull-board/express": "^6.16.2",
+    "@langchain/core": "^1.1.15",
+    "@langchain/langgraph": "^0.0.26",
+    "@sentry/node": "^8.55.0",
+    "axios": "^1.13.2",
+    "better-sqlite3": "^12.6.2",
+    "bull": "^4.16.5",
+    "bullmq": "^5.66.5",
+    "cache-manager": "^5.7.6",
+    "cache-manager-ioredis": "^2.1.0",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "dotenv": "^17.2.3",
+    "express": "^5.2.1",
+    "ioredis": "^5.9.2",
+    "ora": "^9.0.0",
+    "pg": "^8.17.1",
+    "prom-client": "^15.1.3",
+    "uuid": "^13.0.0",
+    "winston": "^3.19.0",
+    "winston-daily-rotate-file": "^5.0.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/express": "^5.0.6",
+    "@types/ioredis": "^5.0.0",
+    "@types/node": "^25.0.9",
+    "@types/pg": "^8.16.0",
+    "@types/uuid": "^11.0.0",
+    "eslint": "^9.39.2",
+    "prettier": "^3.8.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  }
+}