llm-content-creator 0.1.0 → 0.1.1

package/docs/user-guide.md

@@ -65,11 +65,11 @@ cp .env.example .env
 pnpm run db:migrate
 
 # 5. 创建第一个任务
-pnpm run cli:create \
+pnpm run cli create \
   --topic "人工智能的未来" \
   --requirements "写一篇关于 AI 未来发展的文章" \
   --audience "技术爱好者" \
-  --sync
+  --mode sync
 ```
 
 ### Docker 快速启动
@@ -294,7 +294,7 @@ pnpm run start
 #### 创建内容创作任务
 
 ```bash
-pnpm run cli:create \
+pnpm run cli create \
   --topic "文章主题" \
   --requirements "创作要求" \
   --audience "目标受众" \
@@ -302,7 +302,7 @@ pnpm run cli:create \
   --keywords "关键词1,关键词2" \
   --min-words 500 \
   --max-words 2000 \
-  --sync
+  --mode sync
 ```
 
 #### 参数说明
@@ -324,7 +324,7 @@ pnpm run cli:create \
 ##### 示例 1：技术博客文章
 
 ```bash
-pnpm run cli:create \
+pnpm run cli create \
   --topic "TypeScript 5.0 新特性解析" \
   --requirements "详细介绍 TypeScript 5.0 的新特性、改进和迁移指南" \
   --audience "前端开发者" \
@@ -332,13 +332,13 @@ pnpm run cli:create \
   --keywords "TypeScript,JavaScript,前端开发" \
   --min-words 1000 \
   --max-words 2000 \
-  --sync
+  --mode sync
 ```
 
 ##### 示例 2：生活类文章
 
 ```bash
-pnpm run cli:create \
+pnpm run cli create \
   --topic "健康生活方式建议" \
   --requirements "提供实用的健康生活建议，包括饮食、运动和睡眠" \
   --audience "普通读者" \
@@ -346,7 +346,7 @@ pnpm run cli:create \
   --keywords "健康,生活,养生" \
   --min-words 800 \
   --max-words 1200 \
-  --sync
+  --mode sync
 ```
 
 ### 方式二：程序化调用
@@ -394,20 +394,20 @@ console.log('配图 URL:', result.finalState.imageUrl);
 ### create - 创建任务
 
 ```bash
-pnpm run cli:create [options]
+pnpm run cli create [options]
 ```
 
 **示例**:
 
 ```bash
 # 同步执行（推荐用于测试）
-pnpm run cli:create \
+pnpm run cli create \
   --topic "主题" \
   --requirements "要求" \
-  --sync
+  --mode sync
 
 # 异步执行（推荐用于生产）
-pnpm run cli:create \
+pnpm run cli create \
   --topic "主题" \
   --requirements "要求" \
   --mode async
@@ -415,27 +415,122 @@ pnpm run cli:create \
 
 ### 其他 CLI 命令
 
+#### 查看历史任务列表
+
+```bash
+# 查看最近 20 个任务（默认）
+pnpm run cli list
+
+# 查看最近 10 个任务
+pnpm run cli list --limit 10
+
+# 只查看已完成的任务
+pnpm run cli list --status completed
+
+# 只查看失败的任务
+pnpm run cli list --status failed
+
+# 只查看异步任务
+pnpm run cli list --mode async
+
+# 查看第 2 页（分页）
+pnpm run cli list --offset 20
+
+# 以 JSON 格式输出（方便脚本处理）
+pnpm run cli list --json
+```
+
+**显示内容**：
+- 任务主题
+- 任务 ID
+- 当前状态（等待中/运行中/已完成/失败）
+- 执行模式（同步/异步）
+- 创建时间（智能相对时间）
+- 执行耗时
+- 错误信息（如果失败）
+
+#### 重新执行任务
+
+```bash
+# 重新执行单个任务
+pnpm run cli retry --task-id <任务ID>
+
+# 批量重新执行所有等待任务
+pnpm run cli retry --all
+
+# 批量重新执行失败任务
+pnpm run cli retry --all --status failed
+
+# 模拟运行（预览但不实际执行）
+pnpm run cli retry --all --dry-run
+
+# 限制处理数量
+pnpm run cli retry --all --limit 5
+```
+
+**使用场景**：
+- Worker 临时停止导致任务堆积
+- 任务创建时队列不可用
+- 失败的任务需要重试
+- 想要重新执行历史任务
+
 #### 查看任务状态
 
 ```bash
-pnpm run cli:status <task-id>
+pnpm run cli status --task-id <task-id>
+```
+
+#### 获取任务结果
+
+```bash
+pnpm run cli result --task-id <task-id>
 ```
 
 #### 取消任务
 
 ```bash
-pnpm run cli:cancel <task-id>
+pnpm run cli cancel --task-id <task-id>
 ```
 
-#### 监控面板
+#### 监控面板 (Monitor)
+
+**启动监控面板**:
 
 ```bash
-# 启动 BullMQ 监控面板
+# 启动 BullMQ 监控面板（默认端口 3000）
 pnpm run monitor
 
-# 访问 http://localhost:3000/admin/queues
+# 指定端口启动
+npx tsx src/presentation/monitor-cli.ts start -p 3001
 ```
 
+**访问 Web UI**:
+
+启动后访问: `http://localhost:3000/admin/queues`
+
+**功能特性**:
+- ✅ **实时队列监控** - 查看待处理、执行中、已完成、失败的任务
+- ✅ **任务详情查看** - 查看任务数据、堆栈跟踪、执行日志
+- ✅ **任务管理** - 手动重试失败任务、删除任务、暂停/恢复队列
+- ✅ **队列统计** - 实时查看队列状态和任务数量
+- ✅ **错误追踪** - 查看失败任务的原因和错误信息
+
+**API 端点**:
+
+```bash
+# 健康检查
+curl http://localhost:3000/health
+
+# 获取队列统计
+curl http://localhost:3000/api/stats
+```
+
+**使用场景**:
+- 监控异步任务执行状态
+- 查看失败任务并进行手动重试
+- 清理堆积的任务队列
+- 调试任务执行问题
+
 ---
 
 ## 🔌 API 接口
@@ -459,10 +554,10 @@ pnpm run monitor
 ```bash
 # 创建批量脚本
 for topic in "AI发展" "区块链应用" "云计算趋势"; do
-  pnpm run cli:create \
+  pnpm run cli create \
     --topic "$topic" \
     --requirements "详细介绍 $topic" \
-    --sync
+    --mode sync
 done
 ```
 
@@ -481,17 +576,30 @@ LLM_TEMPERATURE=0.3           # 降低创造性（更确定性）
 创建任务时设置：
 
 ```bash
-pnpm run cli:create \
+pnpm run cli create \
   --topic "主题" \
-  --requirements "要求" \
-  --no-search  # 如果支持
+  --requirements "要求"
+  # --no-search  # 暂不支持此参数
 ```
 
 或在代码中设置 `useCache: true` 强制使用缓存。
 
 ### Q4: 如何查看任务历史？
 
-查询数据库：
+使用 CLI 命令：
+
+```bash
+# 查看最近的任务
+pnpm run cli list
+
+# 查看失败的任务
+pnpm run cli list --status failed
+
+# 以 JSON 格式输出
+pnpm run cli list --json
+```
+
+或直接查询数据库：
 
 ```bash
 # 使用 psql
@@ -660,11 +768,52 @@ pnpm run verify-env
 
 # 数据库状态
 pnpm run db:status
+```
+
+### Monitor 监控面板
 
-# 监控面板
+**启动监控面板**:
+
+```bash
+# 启动 Monitor（推荐）
 pnpm run monitor
+
+# 指定端口
+npx tsx src/presentation/monitor-cli.ts start -p 3001
 ```
 
+**访问地址**:
+- Web UI: http://localhost:3000/admin/queues
+- 健康检查: http://localhost:3000/health
+- 队列统计: http://localhost:3000/api/stats
+
+**监控面板功能**:
+
+1. **队列概览**
+   - Waiting（等待中）- 待处理的任务
+   - Active（执行中）- 正在执行的任务
+   - Completed（已完成）- 成功完成的任务
+   - Failed（失败）- 执行失败的任务
+   - Delayed（延迟）- 延迟执行的任务
+
+2. **任务操作**
+   - 查看任务详情（点击任务 ID）
+   - 重试失败任务（Retry 按钮）
+   - 删除任务（Delete 按钮）
+   - 查看任务日志和堆栈跟踪
+
+3. **队列管理**
+   - 暂停队列（Pause 按钮）
+   - 恢复队列（Resume 按钮）
+   - 清空队列（Clean all 按钮）
+   - 批量操作失败任务
+
+4. **性能监控**
+   - 任务处理速度
+   - 队列堆积情况
+   - 失败率统计
+   - Worker 性能指标
+
 ### 日志查看
 
 ```bash
@@ -673,6 +822,9 @@ tail -f ./logs/app.log
 
 # 搜索错误日志
 grep "error" ./logs/app.log
+
+# 查看 Monitor 日志
+tail -f ./logs/app.log | grep BullBoard
 ```
 
 ### 性能指标
@@ -683,6 +835,21 @@ grep "error" ./logs/app.log
 - 缓存命中率
 - 错误率
 
+### 常用监控组合
+
+```bash
+# 终端 1: 启动监控面板
+pnpm run monitor
+
+# 终端 2: 启动 Worker
+pnpm run worker
+
+# 终端 3: 创建异步任务
+pnpm run cli create --topic "测试" --requirements "测试描述" --mode async
+
+# 浏览器: 访问 http://localhost:3000/admin/queues 观察任务执行
+```
+
 ---
 
 ## 📞 技术支持

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-content-creator",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AI 驱动的内容创作工具库",
   "main": "dist/index.js",
   "type": "module",
@@ -52,6 +52,8 @@
     "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:list": "tsx src/presentation/cli/index.ts list",
+    "cli:retry": "tsx src/presentation/cli/index.ts retry",
     "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",

package/src/application/workflow/SyncExecutor.ts

@@ -206,6 +206,7 @@ export class SyncExecutor {
       id: taskId,
       userId: params.userId,
       mode: params.mode,
+      type: 'content-creator', // 添加默认类型
       topic: params.topic,
       requirements: params.requirements,
       hardConstraints: params.hardConstraints,

package/src/config/index.ts

@@ -62,7 +62,7 @@ const envSchema = z.object({
   S3_BUCKET: z.string().optional(),
 
   // Worker 配置
-  WORKER_ID: z.string().default('worker-1'),
+  WORKER_ID: z.string().optional(),
   WORKER_CONCURRENCY: z.coerce.number().int().positive().default(2),
 
   // 日志配置
@@ -160,7 +160,7 @@ class Config {
     console.log('Configuration Loaded Successfully');
     console.log('========================================');
     console.log(`Environment: ${this.env.NODE_ENV}`);
-    console.log(`Worker ID: ${this.env.WORKER_ID}`);
+    console.log(`Worker ID: ${this.env.WORKER_ID || 'Not set (auto-generating UUID)'}`);
     console.log(`Concurrency: ${this.env.WORKER_CONCURRENCY}`);
     console.log(`Database Type: ${this.databaseType}`);
 
@@ -256,7 +256,7 @@ class Config {
       // 连接超时
       connectTimeout: 10000,
       // 命令超时
-      commandTimeout: 5000,
+      commandTimeout: 30000,
     };
   }
 

package/src/domain/repositories/TaskRepository.ts

@@ -17,6 +17,7 @@ export interface CreateTaskInput {
   id?: string;
   userId?: string;
   mode: ExecutionMode;
+  type?: string;
   topic: string;
   requirements: string;
   hardConstraints?: {

package/src/infrastructure/database/MemoryTaskRepository.ts

@@ -127,7 +127,42 @@ export class MemoryTaskRepository {
   }
 
   /**
-   * 抢占任务（Worker 抢占机制）
+   * 抢占任务（Worker 抢占机制）- 按任务ID抢占
+   */
+  async claimTask(taskId: string, workerId: string, version: number): Promise<boolean> {
+    const task = this.tasks.get(taskId);
+    if (!task) {
+      return false;
+    }
+
+    // 检查版本号（乐观锁）
+    if (task.version !== version || task.status !== TaskStatus.PENDING) {
+      logger.warn('Task claim failed (version mismatch or not pending)', {
+        taskId,
+        expectedVersion: version,
+        actualVersion: task.version,
+        status: task.status
+      });
+      return false;
+    }
+
+    const now = new Date();
+    const updatedTask: Task = {
+      ...task,
+      status: TaskStatus.RUNNING,
+      workerId,
+      startedAt: now,
+      version: version + 1,
+      updatedAt: now,
+    };
+
+    this.tasks.set(taskId, updatedTask);
+    logger.info('Task claimed (memory)', { taskId, workerId });
+    return true;
+  }
+
+  /**
+   * 抢占任务（Worker 抢占机制）- 批量抢占
    */
   async claimForProcessing(workerId: string, limit: number = 1): Promise<Task[]> {
     const now = new Date();
@@ -361,6 +396,59 @@ export class MemoryTaskRepository {
     return true;
   }
 
+  /**
+   * 查询任务列表（支持过滤和分页）
+   */
+  async findMany(filter?: any, pagination?: any): Promise<Task[]> {
+    const { limit = 50, offset = 0 } = pagination || {};
+
+    let tasks = Array.from(this.tasks.values());
+
+    // 应用过滤
+    if (filter?.status) {
+      tasks = tasks.filter((t) => t.status === filter.status);
+    }
+    if (filter?.userId) {
+      tasks = tasks.filter((t) => t.id === filter.userId); // Memory 没有 userId 字段
+    }
+    if (filter?.mode) {
+      tasks = tasks.filter((t) => t.mode === filter.mode);
+    }
+
+    // 按创建时间倒序排序
+    tasks.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+
+    // 分页
+    return tasks.slice(offset, offset + limit);
+  }
+
+  /**
+   * 统计任务数量
+   */
+  async count(filter?: any): Promise<number> {
+    let tasks = Array.from(this.tasks.values());
+
+    // 应用过滤
+    if (filter?.status) {
+      tasks = tasks.filter((t) => t.status === filter.status);
+    }
+    if (filter?.userId) {
+      tasks = tasks.filter((t) => t.id === filter.userId);
+    }
+    if (filter?.mode) {
+      tasks = tasks.filter((t) => t.mode === filter.mode);
+    }
+
+    return tasks.length;
+  }
+
+  /**
+   * 根据 userId 查询任务列表
+   */
+  async findByUserId(userId: string, pagination?: any): Promise<Task[]> {
+    return this.findMany({ userId }, pagination);
+  }
+
   /**
    * 获取统计信息
    */

package/src/infrastructure/database/SQLiteQualityCheckRepository.ts

@@ -0,0 +1,102 @@
+/**
+ * SQLite Quality Check Repository
+ *
+ * 使用 better-sqlite3 实现的轻量级质量检查数据访问层
+ * 适合开发和测试环境
+ */
+
+import Database from 'better-sqlite3';
+import { v4 as uuidv4 } from 'uuid';
+import { createLogger } from '../../infrastructure/logging/logger.js';
+import type { IQualityCheckRepository, CreateQualityCheckParams, QualityCheckRecord } from '../../domain/repositories/QualityCheckRepository.js';
+
+const logger = createLogger('SQLite:QualityCheckRepository');
+
+/**
+ * SQLite Quality Check Repository 实现
+ */
+export class SQLiteQualityCheckRepository implements IQualityCheckRepository {
+  private db: Database.Database;
+
+  constructor(dbPath?: string) {
+    const actualDbPath = dbPath || './data/content-creator.db';
+    this.db = new Database(actualDbPath);
+    logger.info('SQLite quality check repository initialized', { dbPath: actualDbPath });
+  }
+
+  /**
+   * 创建质量检查记录
+   */
+  async create(params: CreateQualityCheckParams): Promise<void> {
+    const now = new Date().toISOString();
+    const stmt = this.db.prepare(`
+      INSERT INTO quality_checks (
+        id, task_id, check_type, score, passed, hard_constraints_passed,
+        details, fix_suggestions, rubric_version, model_name, prompt_hash, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const details = params.details ? JSON.stringify(params.details) : null;
+    const fixSuggestions = (params.fixSuggestions && params.fixSuggestions.length > 0)
+      ? JSON.stringify(params.fixSuggestions)
+      : null;
+
+    try {
+      stmt.run(
+        uuidv4(), // 使用 UUID v4 确保唯一性
+        params.taskId,
+        params.checkType,
+        params.score,
+        params.passed,
+        params.hardConstraintsPassed,
+        details,
+        fixSuggestions,
+        params.rubricVersion || null,
+        params.modelName || null,
+        params.promptHash || null,
+        now
+      );
+
+      logger.info('Quality check created', {
+        taskId: params.taskId,
+        checkType: params.checkType,
+        score: params.score,
+        passed: params.passed,
+      });
+    } catch (error) {
+      logger.error('Failed to create quality check', { error: error as any, params });
+      throw error;
+    }
+  }
+
+  /**
+   * 根据任务 ID 查询质量检查
+   */
+  async findByTaskId(taskId: string): Promise<QualityCheckRecord[]> {
+    const stmt = this.db.prepare('SELECT * FROM quality_checks WHERE task_id = ? ORDER BY created_at DESC');
+    const rows = stmt.all(taskId) as any[];
+
+    return rows.map((row) => ({
+      id: row.id,
+      taskId: row.task_id,
+      checkType: row.check_type,
+      score: row.score,
+      passed: row.passed,
+      hardConstraintsPassed: row.hard_constraints_passed,
+      details: row.details ? JSON.parse(row.details) : null,
+      fixSuggestions: row.fix_suggestions ? JSON.parse(row.fix_suggestions) : null,
+      rubricVersion: row.rubric_version,
+      modelName: row.model_name,
+      promptHash: row.prompt_hash,
+      createdAt: new Date(row.created_at),
+    })) as QualityCheckRecord[];
+  }
+
+  /**
+   * 关闭数据库连接
+   */
+  close(): void {
+    this.db.close();
+    logger.info('SQLite quality check repository connection closed');
+  }
+}

package/src/infrastructure/database/SQLiteResultRepository.ts

@@ -0,0 +1,95 @@
+/**
+ * SQLite Result Repository
+ *
+ * 使用 better-sqlite3 实现的轻量级结果数据访问层
+ * 适合开发和测试环境
+ */
+
+import Database from 'better-sqlite3';
+import { v4 as uuidv4 } from 'uuid';
+import { createLogger } from '../../infrastructure/logging/logger.js';
+import type { IResultRepository, CreateResultParams, ResultRecord } from '../../domain/repositories/ResultRepository.js';
+
+const logger = createLogger('SQLite:ResultRepository');
+
+/**
+ * SQLite Result Repository 实现
+ */
+export class SQLiteResultRepository implements IResultRepository {
+  private db: Database.Database;
+
+  constructor(dbPath?: string) {
+    const actualDbPath = dbPath || './data/content-creator.db';
+    this.db = new Database(actualDbPath);
+    logger.info('SQLite result repository initialized', { dbPath: actualDbPath });
+  }
+
+  /**
+   * 创建结果记录
+   */
+  async create(params: CreateResultParams): Promise<void> {
+    const now = new Date().toISOString();
+    const stmt = this.db.prepare(`
+      INSERT INTO results (
+        id, task_id, result_type, content, file_path, metadata, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const metadata = params.metadata ? JSON.stringify(params.metadata) : null;
+
+    try {
+      stmt.run(
+        uuidv4(), // 使用 UUID v4 确保唯一性
+        params.taskId,
+        params.resultType,
+        params.content || null,
+        params.filePath || null,
+        metadata,
+        now
+      );
+
+      logger.info('Result created', {
+        taskId: params.taskId,
+        resultType: params.resultType,
+      });
+    } catch (error) {
+      logger.error('Failed to create result', { error: error as any, params });
+      throw error;
+    }
+  }
+
+  /**
+   * 根据任务 ID 查询结果
+   */
+  async findByTaskId(taskId: string): Promise<ResultRecord[]> {
+    const stmt = this.db.prepare('SELECT * FROM results WHERE task_id = ? ORDER BY result_type');
+    const rows = stmt.all(taskId) as any[];
+
+    return rows.map((row) => ({
+      id: row.id,
+      taskId: row.task_id,
+      resultType: row.result_type,
+      content: row.content,
+      filePath: row.file_path,
+      metadata: row.metadata ? JSON.parse(row.metadata) : null,
+      createdAt: new Date(row.created_at),
+    })) as ResultRecord[];
+  }
+
+  /**
+   * 删除任务的所有结果
+   */
+  async deleteByTaskId(taskId: string): Promise<void> {
+    const stmt = this.db.prepare('DELETE FROM results WHERE task_id = ?');
+    stmt.run(taskId);
+    logger.info('Results deleted', { taskId });
+  }
+
+  /**
+   * 关闭数据库连接
+   */
+  close(): void {
+    this.db.close();
+    logger.info('SQLite result repository connection closed');
+  }
+}