llm-content-creator 0.1.0 → 0.1.1

package/docs/cli-reference.md

@@ -0,0 +1,623 @@
+# Content Creator CLI 使用参考
+
+**版本**: 0.1.0
+**更新日期**: 2026-01-24
+
+---
+
+## 📖 目录
+
+1. [快速开始](#快速开始)
+2. [主 CLI 命令](#主-cli-命令)
+3. [Worker CLI](#worker-cli)
+4. [Monitor CLI](#monitor-cli)
+5. [Scheduler CLI](#scheduler-cli)
+6. [使用示例](#使用示例)
+7. [常见问题](#常见问题)
+
+---
+
+## 🚀 快速开始
+
+### 安装依赖
+
+```bash
+pnpm install
+```
+
+### 配置环境变量
+
+创建 `.env` 文件并配置所需的 API 密钥和数据库连接信息。
+
+### 创建第一个任务
+
+```bash
+pnpm run cli create \
+  --topic "人工智能的未来" \
+  --requirements "写一篇关于 AI 未来发展的文章" \
+  --mode sync
+```
+
+---
+
+## 💻 主 CLI 命令
+
+主 CLI 提供了任务管理的核心功能：创建、查询、获取结果和取消任务。
+
+### 调用方式
+
+```bash
+# 使用 npm script（推荐）
+pnpm run cli <command> [options]
+
+# 直接调用
+tsx src/presentation/cli/index.ts <command> [options]
+```
+
+### create - 创建任务
+
+创建一个新的内容创作任务。
+
+```bash
+pnpm run cli create [options]
+```
+
+#### 参数说明
+
+| 参数 | 简写 | 说明 | 必填 | 默认值 |
+|------|------|------|------|--------|
+| `--topic` | `-t` | 文章主题 | ✅ | - |
+| `--requirements` | `-r` | 创作要求 | ✅ | - |
+| `--audience` | `-a` | 目标受众 | ❌ | 普通读者 |
+| `--keywords` | - | 关键词（逗号分隔） | ❌ | - |
+| `--tone` | - | 语气风格 | ❌ | 专业 |
+| `--min-words` | - | 最小字数 | ❌ | 500 |
+| `--max-words` | - | 最大字数 | ❌ | 2000 |
+| `--mode` | - | 执行模式 (sync\|async) | ❌ | sync |
+| `--priority` | - | 优先级 (low\|normal\|high\|urgent) | ❌ | normal |
+
+#### 执行模式说明
+
+**sync（同步模式）**:
+- 任务在当前进程中执行
+- 实时显示执行进度
+- 等待任务完成后返回结果
+- 适用于测试和快速验证
+
+**async（异步模式）**:
+- 任务被添加到队列
+- 需要独立的 Worker 进程处理
+- 立即返回任务 ID
+- 适用于生产环境和批量处理
+
+#### 示例
+
+```bash
+# 基本示例
+pnpm run cli create \
+  --topic "TypeScript 5.0 新特性" \
+  --requirements "详细介绍 TypeScript 5.0 的新特性" \
+  --mode sync
+
+# 完整参数示例
+pnpm run cli create \
+  --topic "健康生活方式" \
+  --requirements "提供实用的健康生活建议" \
+  --audience "普通读者" \
+  --tone "亲切友好" \
+  --keywords "健康,生活,养生" \
+  --min-words 800 \
+  --max-words 1200 \
+  --mode sync \
+  --priority normal
+
+# 异步模式
+pnpm run cli create \
+  --topic "云计算趋势" \
+  --requirements "分析云计算的发展趋势" \
+  --mode async
+```
+
+### status - 查询任务状态
+
+查询指定任务的执行状态。
+
+```bash
+pnpm run cli status --task-id <taskId>
+```
+
+#### 参数说明
+
+| 参数 | 简写 | 说明 | 必填 |
+|------|------|------|------|
+| `--task-id` | `-t` | 任务 ID | ✅ |
+
+#### 输出信息
+
+- 任务 ID
+- 当前状态（待处理/运行中/已完成/失败/已取消）
+- 当前步骤
+- 执行模式
+- 优先级
+- 创建/开始/完成时间
+- 重试统计
+- 错误信息（如有）
+
+#### 示例
+
+```bash
+pnpm run cli status --task-id 550e8400-e29b-41d4-a716-446655440000
+```
+
+### result - 获取任务结果
+
+获取已完成任务的执行结果。
+
+```bash
+pnpm run cli result --task-id <taskId> [options]
+```
+
+#### 参数说明
+
+| 参数 | 简写 | 说明 | 必填 | 默认值 |
+|------|------|------|------|--------|
+| `--task-id` | `-t` | 任务 ID | ✅ | - |
+| `--format` | - | 输出格式 (text\|json) | ❌ | text |
+
+#### 输出格式
+
+**text 格式**:
+- 可读性强的文本输出
+- 包含文章内容和配图 URL
+
+**json 格式**:
+- JSON 格式输出
+- 便于程序处理
+
+#### 示例
+
+```bash
+# 文本格式
+pnpm run cli result --task-id 550e8400-e29b-41d4-a716-446655440000
+
+# JSON 格式
+pnpm run cli result --task-id 550e8400-e29b-41d4-a716-446655440000 --format json
+```
+
+### cancel - 取消任务
+
+取消正在执行或等待中的任务。
+
+```bash
+pnpm run cli cancel --task-id <taskId>
+```
+
+#### 参数说明
+
+| 参数 | 简写 | 说明 | 必填 |
+|------|------|------|------|
+| `--task-id` | `-t` | 任务 ID | ✅ |
+
+#### 注意事项
+
+- 只能取消状态为 "运行中" 或 "等待中" 的任务
+- 已完成或失败的任务无法取消
+- 取消操作不可逆
+
+#### 示例
+
+```bash
+pnpm run cli cancel --task-id 550e8400-e29b-41d4-a716-446655440000
+```
+
+### list - 查看历史任务列表
+
+查看系统中创建的所有任务，支持筛选和分页。
+
+```bash
+pnpm run cli list [options]
+```
+
+#### 参数说明
+
+| 参数 | 简写 | 说明 | 必填 | 默认值 |
+|------|------|------|------|--------|
+| `--status` | `-s` | 筛选状态 (pending\|running\|completed\|failed\|cancelled) | ❌ | - |
+| `--mode` | `-m` | 筛选执行模式 (sync\|async) | ❌ | - |
+| `--limit` | `-l` | 显示数量 | ❌ | 20 |
+| `--offset` | `-o` | 偏移量（分页） | ❌ | 0 |
+| `--json` | - | JSON 格式输出 | ❌ | false |
+
+#### 显示信息
+
+- 任务主题
+- 任务 ID（完整 UUID）
+- 当前状态（彩色标识）
+- 执行模式（同步/异步）
+- 创建时间（智能相对时间）
+- 执行耗时
+- 错误信息（如果失败）
+
+#### 示例
+
+```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
+```
+
+#### 使用场景
+
+- 监控任务执行情况
+- 查找失败任务进行重试
+- 统计任务完成率
+- 导出任务数据用于分析
+
+### retry - 重新执行任务
+
+将数据库中已有的任务重新添加到队列中进行处理。
+
+```bash
+pnpm run cli retry [options]
+```
+
+#### 参数说明
+
+| 参数 | 简写 | 说明 | 必填 |
+|------|------|------|------|
+| `--task-id` | `-t` | 重新执行指定任务 | ❌ | - |
+| `--all` | - | 批量重新执行所有等待任务 | ❌ | - |
+| `--status` | `-s` | 按状态筛选 (pending\|failed\|cancelled) | ❌ | pending |
+| `--limit` | `-l` | 处理数量限制 | ❌ | 10 |
+| `--dry-run` | - | 模拟运行（不实际执行） | ❌ | false |
+
+#### 使用场景
+
+**场景 1: 重新执行单个失败任务**
+
+```bash
+pnpm run cli retry --task-id 913efd41-d3d1-478a-9b37-77f2de73b694
+```
+
+**场景 2: 批量重试所有失败任务**
+
+```bash
+# 模拟运行，预览操作
+pnpm run cli retry --all --status failed --dry-run
+
+# 确认后实际执行
+pnpm run cli retry --all --status failed
+```
+
+**场景 3: Worker 停止后恢复处理**
+
+```bash
+# 1. 启动 Worker
+pnpm run worker
+
+# 2. 重新执行所有等待任务
+pnpm run cli retry --all
+```
+
+**场景 4: 分批处理大量任务**
+
+```bash
+# 每次处理 5 个
+pnpm run cli retry --all --limit 5
+```
+
+#### 注意事项
+
+- 确保 Worker 正在运行
+- 已完成的任务不建议重试
+- 使用 `--dry-run` 预览后再实际执行
+- 大量任务使用 `--limit` 分批处理
+
+#### 与其他命令的配合
+
+```bash
+# 1. 查看失败任务
+pnpm run cli list --status failed
+
+# 2. 重新执行失败任务
+pnpm run cli retry --all --status failed
+
+# 3. 查看重试后的状态
+pnpm run cli status --task-id <taskId>
+```
+
+---
+
+## 👷 Worker CLI
+
+Worker 负责处理异步队列中的任务。
+
+### 调用方式
+
+```bash
+# 使用 npm script（推荐）
+pnpm run worker [options]
+
+# 开发模式（带热重载）
+pnpm run worker:dev [options]
+
+# 直接调用
+tsx src/presentation/worker-cli.ts start [options]
+```
+
+### 参数说明
+
+| 参数 | 简写 | 说明 | 必填 | 默认值 |
+|------|------|------|------|--------|
+| `--worker-id` | `-w` | Worker ID | ❌ | 自动生成 |
+| `--concurrency` | `-c` | 并发处理任务数 | ❌ | 2 |
+
+### 启动 Worker
+
+```bash
+# 基本启动
+pnpm run worker
+
+# 指定 Worker ID
+pnpm run worker --worker-id worker-1
+
+# 设置并发数
+pnpm run worker --concurrency 4
+
+# 完整参数
+pnpm run worker --worker-id worker-1 --concurrency 4
+```
+
+### 注意事项
+
+- 确保 Redis 和数据库服务正常运行
+- Worker 需要保持运行状态以处理队列中的任务
+- 可以启动多个 Worker 实例以提高处理能力
+- 使用 `Ctrl+C` 停止 Worker
+
+---
+
+## 📊 Monitor CLI
+
+Monitor 提供了基于 Web 的队列监控面板（使用 Bull Board）。
+
+### 调用方式
+
+```bash
+# 使用 npm script（推荐）
+pnpm run monitor [options]
+
+# 直接调用
+tsx src/presentation/monitor-cli.ts start [options]
+```
+
+### 参数说明
+
+| 参数 | 简写 | 说明 | 必填 | 默认值 |
+|------|------|------|------|--------|
+| `--port` | `-p` | 监控面板端口 | ❌ | 3000 |
+
+### 启动监控面板
+
+```bash
+# 基本启动
+pnpm run monitor
+
+# 指定端口
+pnpm run monitor --port 8080
+```
+
+### 访问监控面板
+
+启动后访问: `http://localhost:3000/admin/queues`
+
+### 功能特性
+
+- 查看待处理任务
+- 查看已完成/失败任务
+- 手动重试失败任务
+- 查看任务详情
+- 清空队列
+
+---
+
+## ⏰ Scheduler CLI
+
+Scheduler 负责定时调度和管理任务。
+
+### 调用方式
+
+```bash
+# 使用 npm script（推荐）
+pnpm run scheduler
+
+# 直接调用
+tsx src/presentation/scheduler-cli.ts
+```
+
+### 注意事项
+
+- Scheduler 需要保持运行状态
+- 确保配置了正确的调度规则
+- 使用 `Ctrl+C` 停止 Scheduler
+
+---
+
+## 💡 使用示例
+
+### 场景 1: 快速测试
+
+```bash
+# 同步执行，立即查看结果
+pnpm run cli create \
+  --topic "远程工作的优势" \
+  --requirements "分析远程工作的优势和挑战" \
+  --mode sync
+```
+
+### 场景 2: 批量生产
+
+```bash
+# 1. 启动 Worker
+pnpm run worker --concurrency 4
+
+# 2. 在另一个终端批量创建任务
+pnpm run cli create \
+  --topic "AI发展" \
+  --requirements "介绍 AI 的发展历程" \
+  --mode async
+
+pnpm run cli create \
+  --topic "区块链应用" \
+  --requirements "讨论区块链的实际应用" \
+  --mode async
+
+pnpm run cli create \
+  --topic "云计算趋势" \
+  --requirements "分析云计算的发展趋势" \
+  --mode async
+```
+
+### 场景 3: 监控任务
+
+```bash
+# 1. 启动监控面板
+pnpm run monitor
+
+# 2. 浏览器访问 http://localhost:3000/admin/queues
+
+# 3. 查看任务状态
+pnpm run cli status --task-id <task-id>
+
+# 4. 查看结果
+pnpm run cli result --task-id <task-id>
+```
+
+### 场景 4: 错误处理
+
+```bash
+# 1. 查询失败任务
+pnpm run cli status --task-id <task-id>
+
+# 2. 如果需要，取消任务
+pnpm run cli cancel --task-id <task-id>
+
+# 3. 重新创建任务
+pnpm run cli create \
+  --topic "主题" \
+  --requirements "要求" \
+  --mode sync
+```
+
+---
+
+## ❓ 常见问题
+
+### Q1: sync 和 async 模式有什么区别？
+
+**sync（同步）**:
+- 在当前进程中执行
+- 等待完成并显示结果
+- 适合测试和调试
+
+**async（异步）**:
+- 任务加入队列
+- 需要 Worker 处理
+- 适合生产环境
+
+### Q2: 为什么异步模式的任务没有执行？
+
+确保：
+1. Worker 正在运行: `pnpm run worker`
+2. Redis 服务正常运行
+3. 数据库连接正常
+4. 使用 `pnpm run cli status --task-id <id>` 查看任务状态
+
+### Q3: 如何提高任务处理速度？
+
+1. 增加并发数: `pnpm run worker --concurrency 4`
+2. 启动多个 Worker 实例
+3. 优化 LLM 调用配置
+4. 启用缓存
+
+### Q4: 任务失败后如何重试？
+
+方式 1 - 使用监控面板:
+1. 访问 `http://localhost:3000/admin/queues`
+2. 找到失败的任务
+3. 点击 "重试" 按钮
+
+方式 2 - 重新创建:
+```bash
+pnpm run cli create \
+  --topic "主题" \
+  --requirements "要求" \
+  --mode sync
+```
+
+### Q5: 如何查看 Worker 日志？
+
+Worker 日志会输出到控制台和日志文件：
+```bash
+# 查看实时日志
+tail -f logs/app.log
+
+# 查看错误日志
+tail -f logs/error.log
+```
+
+### Q6: 可以同时运行多个 Worker 吗？
+
+可以！每个 Worker 需要：
+1. 唯一的 Worker ID: `--worker-id worker-1`
+2. 独立的终端窗口
+3. 共享的 Redis 和数据库连接
+
+```bash
+# 终端 1
+pnpm run worker --worker-id worker-1 --concurrency 2
+
+# 终端 2
+pnpm run worker --worker-id worker-2 --concurrency 2
+```
+
+### Q7: 如何停止正在执行的任务？
+
+```bash
+# 取消任务
+pnpm run cli cancel --task-id <task-id>
+
+# 或停止 Worker
+# 在 Worker 终端按 Ctrl+C
+```
+
+---
+
+## 📚 相关文档
+
+- [用户操作手册](./user-guide.md)
+- [快速开始指南](./quick-start.md)
+- [架构设计文档](./architecture-complete.md)
+
+---
+
+**文档版本**: 1.0
+**最后更新**: 2026-01-24
+**维护者**: Content Creator Team

package/docs/quick-start.md

@@ -200,6 +200,53 @@ npm test
 
 ## 📊 监控和调试
 
+### Monitor 监控面板
+
+**启动监控面板**:
+
+```bash
+# 启动 Bull Board 监控面板
+pnpm run monitor
+```
+
+**访问地址**: http://localhost:3000/admin/queues
+
+**主要功能**:
+- 查看任务队列状态（等待中、执行中、已完成、失败）
+- 手动重试失败的任务
+- 查看任务详情和日志
+- 暂停/恢复队列
+- 清空队列
+
+**测试 API 端点**:
+
+```bash
+# 健康检查
+curl http://localhost:3000/health
+
+# 获取队列统计
+curl http://localhost:3000/api/stats
+```
+
+**完整使用流程**:
+
+```bash
+# 1. 启动监控面板（终端 1）
+pnpm run monitor
+
+# 2. 启动 Worker（终端 2）
+pnpm run worker
+
+# 3. 创建异步任务（终端 3）
+pnpm run cli create \
+  --topic "Web 开发最佳实践" \
+  --requirements "写一篇关于现代 Web 开发的文章" \
+  --mode async
+
+# 4. 在浏览器中访问 http://localhost:3000/admin/queues
+#    观察任务从创建到完成的整个流程
+```
+
 ### 查看日志
 
 系统使用 Winston 日志，输出到控制台和文件。