✨ feat(scheduler): 新增热点自动采集功能并优化发布路径

- 新增热点自动采集后台线程，支持定时搜索关键词并执行 AI 分析，结果缓存至结构化状态 - 新增热点分析状态管理接口，提供线程安全的 `get_last_analysis` 和 `set_last_analysis` 方法 - 新增热点数据桥接函数 `feed_hotspot_to_engine`，将分析结果注入 TopicEngine 实现热点加权推荐 - 新增热点选题下拉组件，分析完成后自动填充推荐选题，选中后自动写入选题输入框 - 优化 `generate_from_hotspot` 函数，自动获取结构化分析摘要并增强生成上下文 - 新增热点自动采集配置节点，支持通过 `config.json` 管理关键词和采集间隔 ♻️ refactor(queue): 实现智能排期引擎并统一发布路径 - 新增智能排期引擎，基于 `AnalyticsService` 的 `time_weights` 自动计算最优发布时段 - 新增 `PublishQueue.suggest_schedule_time` 和 `auto_schedule_item` 方法，支持时段冲突检测和内容分布控制 - 修改 `generate_to_queue` 函数，新增 `auto_schedule` 和 `auto_approve` 参数，支持自动排期和自动审核 - 重构 `_scheduler_loop` 的自动发布分支，改为调用 `generate_to_queue` 通过队列发布，统一发布路径 - 重构 `auto_publish_once` 函数，移除直接发布逻辑，改为生成内容入队并返回队列信息 - 新增队列时段使用情况查询方法 `get_slot_usage`，支持 UI 热力图展示 📝 docs(openspec): 新增内容排期优化和热点探测优化规范文档 - 新增 `smart-schedule-engine` 规范，定义智能排期引擎的功能需求和场景 - 新增 `unified-publish-path` 规范，定义统一发布路径的改造方案 - 新增 `hotspot-analysis-state` 规范，定义热点分析状态存储的线程安全接口 - 新增 `hotspot-auto-collector` 规范，定义定时热点自动采集的任务流程 - 新增 `hotspot-engine-bridge` 规范，定义热点数据注入 TopicEngine 的桥接机制 - 新增 `hotspot-topic-selector` 规范，定义热点选题下拉组件的交互行为 - 更新 `services-queue`、`services-scheduler` 和 `services-hotspot` 规范，反映功能修改和新增参数 🔧 chore(config): 新增热点自动采集默认配置 - 在 `DEFAULT_CONFIG` 中新增 `hotspot_auto_collect` 配置节点，包含 `enabled`、`keywords` 和 `interval_hours` 字段 - 提供默认关键词列表 `["穿搭", "美妆", "好物"]` 和默认采集间隔 4 小时 🐛 fix(llm): 增强 JSON 解析容错能力 - 新增 `_try_fix_truncated_json` 方法，尝试修复被 token 限制截断的 JSON 输出 - 支持多种截断场景的自动补全，包括字符串值、数组和嵌套对象的截断修复 - 提高 LLM 分析热点等返回 JSON 的函数的稳定性 💄 style(ui): 优化队列管理和热点探测界面 - 在队列生成区域新增自动排期复选框，勾选后隐藏手动排期输入框 - 在日历视图旁新增推荐时段 Markdown 面板，展示各时段权重和建议热力图 - 在热点探测 Tab 新增推荐选题下拉组件，分析完成后动态填充选项 - 在热点探测 Tab 新增热点自动采集控制区域，支持启动、停止和配置采集参数
2026-02-28 22:22:27 +08:00
parent 1889e9a222
commit 4d83c0f4a9
34 changed files with 1318 additions and 161 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-28
@@ -0,0 +1,83 @@
+## Context
+
+当前系统有两条独立的发布路径：
+1. `scheduler.py` → `auto_publish_once()` → 直接生成 + 直接发布到小红书（绕过队列）
+2. `queue_ops.py` → `generate_to_queue()` → `PublishQueue` SQLite 持久化 → `QueuePublisher._loop()` → 按排期/审核状态发布
+
+`AnalyticsService` 已在 `content_weights.json` 中保存 `time_weights`（3小时段权重，如 `"18-21时": {"weight": 85, "count": 12}`），但这些数据没有被排期逻辑使用。用户排期必须手动输入时间字符串。
+
+## Goals / Non-Goals
+
+**Goals:**
+- G1: 基于 `time_weights` 自动计算最优发布时段，为入队内容分配 `scheduled_time`
+- G2: 消除调度器绕过队列的直接发布路径，统一为队列驱动
+- G3: 支持内容间距控制（同一时段不超过 N 篇），分散到多天
+- G4: UI 增加自动排期开关和排期建议展示
+
+**Non-Goals:**
+- 不改动 `PublishQueue` 的 SQLite 表结构（不新增列）
+- 不增加 A/B 测试或基于实时反馈的动态调整
+- 不修改 `QueuePublisher` 的发布执行逻辑（仅改其上游输入）
+- 不改变评论/点赞/收藏等非发布类自动化任务
+
+## Decisions
+
+### D1: 智能排期引擎放在 `publish_queue.py` 中作为 `PublishQueue` 的方法
+
+**决定**: 在 `PublishQueue` 类上新增 `suggest_schedule_time()` 和 `auto_schedule_item()` 方法。
+
+**理由**: 排期引擎需要查询现有队列排期（避免时段冲突），`PublishQueue` 已持有 SQLite 连接和查询方法，放在此处可避免跨模块传递 db 连接。
+
+**备选方案**: 独立模块 `schedule_engine.py` — 但会增加新文件，且仍需注入 `PublishQueue` 实例来查询已排期项。
+
+### D2: `time_weights` 通过 `AnalyticsService.get_time_weights()` 新方法获取
+
+**决定**: 在 `AnalyticsService` 上新增 `get_time_weights() -> dict` 方法，返回 `time_weights` 字典。无数据时返回默认值。
+
+**理由**: 封装内部 `_weights` 结构，提供干净的 API 供排期引擎调用。
+
+**默认时段**: 无分析数据时 fallback 到: `{"08-11时": 70, "12-14时": 60, "18-21时": 85, "21-24时": 75}`（小红书高流量经验值）。
+
+### D3: 统一发布路径 — 调度器 publish 分支改为 generate_to_queue + auto_approve
+
+**决定**: `_scheduler_loop` 的自动发布分支改为调用 `generate_to_queue(auto_schedule=True, auto_approve=True)`，不再调用 `auto_publish_once` 内的发布逻辑。`auto_publish_once` 保留但重构为仅生成内容入队。
+
+**理由**: 
+- 统一发布路径，所有内容都走队列审核流程
+- `QueuePublisher` 已有重试、错误处理、日志记录能力
+- 调度器生成的内容也会出现在队列表格和日历中，可追溯
+
+**行为变化**: 调度器发布从「立即生成并发布」变为「生成入队 → QueuePublisher 下一轮 check（最多 60s）发布」。延迟可接受。
+
+### D4: 时段冲突检测基于 SQLite 查询
+
+**决定**: `suggest_schedule_time()` 查询 `queue` 表中 `scheduled_time` 列，统计每个时段已排队的数量，优先选择高权重且低负载的时段。
+
+**规则**:
+- 每个3小时段最多 `max_per_slot`（默认 2）篇
+- 同一天内最多 `max_per_day`（默认 5）篇
+- 优先当天还有空余的高权重时段，当天满则顺延到次日
+- 最远排到7天后
+
+### D5: `generate_to_queue` 新增 `auto_schedule` 和 `auto_approve` 参数
+
+**决定**: `generate_to_queue()` 签名增加 `auto_schedule: bool = False` 和 `auto_approve: bool = False`：
+- `auto_schedule=True` → 调用 `PublishQueue.suggest_schedule_time()` 为每篇内容分配时间
+- `auto_approve=True` → 入队后自动调用 `approve()`，状态从 draft 直接变为 scheduled/approved
+
+**理由**: 最小改动，对现有手动流程无影响；调度器场景两者都开启，UI 场景用户可选。
+
+### D6: UI 增加自动排期复选框和排期建议面板
+
+**决定**: 
+- 在「批量生成到队列」区域增加 `auto_schedule` 复选框，勾选后隐藏手动排期输入框
+- 在日历视图旁增加「📊 推荐时段」Markdown 面板，展示 `time_weights` top 时段
+
+**理由**: 最小 UI 变更，不重构现有布局。
+
+## Risks / Trade-offs
+
+- **[排期延迟]** 调度器发布不再即时，会有最多 60s 延迟（QueuePublisher check 间隔）→ 对社交媒体发布场景可接受，且可通过缩短 `check_interval` 缓解
+- **[无数据 fallback]** 首次使用时 `time_weights` 为空，排期基于经验默认值 → 运行一段时间后数据学习会逐步优化
+- **[时段冲突查询性能]** 每次入队都需查询队列排期 → 队列规模通常 < 100 项，SQLite WAL 模式下查询性能无忧
+- **[auto_approve 安全性]** 调度器自动审核跳过人工审核 → 仅在调度器自动模式下启用，用户手动入队仍需审核
@@ -0,0 +1,33 @@
+## Why
+
+当前系统存在两条独立的发布路径：`scheduler.py` 的 `auto_publish_once` 直接生成并发布，完全绕过队列；而 `PublishQueue` + `QueuePublisher` 提供了另一套排期发布机制。两套系统互不感知，导致：
+
+1. **排期时间全靠手动输入** — 用户必须自己判断最佳发布时间并以文本形式输入 `scheduled_time`，`analytics_service.py` 中已有的 `time_weights`（基于历史数据的3小时段权重）完全没有被利用。
+2. **调度器发布绕过队列** — 自动化调度器的发布操作不经过审核流程，没有草稿预览、排期管理的保障；而队列系统又缺少自动化生成能力，两者无法联动。
+3. **无内容分布控制** — 没有机制防止多篇内容扎堆发布，也没有将内容分散到高流量时段的能力。
+
+## What Changes
+
+- 新增**智能排期引擎**：基于 `AnalyticsService` 的 `time_weights` 自动计算最佳发布时间槽（peak hours），为入队内容自动分配 `scheduled_time`，避免同一时段拥堵
+- 新增**自动排期模式**：内容生成入队时可选择"自动排期"，系统自动跨天分散安排到高权重时段
+- 将调度器的 `auto_publish_once` 重构为**通过队列发布**，统一发布路径，所有发布都经过队列 → 审核 → 排期 → 发布的标准流程
+- 修改内容排期 UI，增加一键自动排期、排期建议、时段热力图展示
+
+## Capabilities
+
+### New Capabilities
+
+- `smart-schedule-engine`: 智能排期引擎 — 基于 `time_weights` 分析数据计算最优发布时段，自动为队列项分配排期时间，支持内容间距控制和时段负载均衡
+- `unified-publish-path`: 统一发布路径 — 将 `scheduler.py` 的自动发布改为生成内容到队列 + 自动审核 + QueuePublisher 发布，消除绕过队列的直接发布
+
+### Modified Capabilities
+
+- `services-queue`: 队列添加时支持 `auto_schedule=True` 参数调用智能排期引擎；`generate_to_queue` 新增自动排期选项
+- `services-scheduler`: `_scheduler_loop` 的 publish 分支改为调用 `generate_to_queue`（自动排期 + 自动审核），不再直接调用 `auto_publish_once` 的发布逻辑
+
+## Impact
+
+- **代码变更**: `services/publish_queue.py`（新增排期引擎方法）、`services/queue_ops.py`（`generate_to_queue` 增加自动排期参数）、`services/scheduler.py`（publish 路径重构）、`services/analytics_service.py`（暴露 `time_weights` 查询接口）、`ui/app.py`（排期 UI 增强）
+- **数据依赖**: 智能排期依赖 `content_weights.json` 中的 `time_weights` 字段；首次使用若无数据则 fallback 到默认高流量时段（08-10, 12-14, 18-22）
+- **行为变更**: 调度器的自动发布不再即时发布，改为入队后由 QueuePublisher 按排期时间发布，会有分钟级延迟
+- **向后兼容**: 手动输入 `scheduled_time` 仍然有效，智能排期仅在用户未手动指定时生效
@@ -0,0 +1,32 @@
+## MODIFIED Requirements
+
+### Requirement: 排期队列操作函数迁移至独立模块
+系统 SHALL 将内容排期队列相关函数从 `main.py` 提取至 `services/queue_ops.py`，包括：`generate_to_queue`、`_queue_publish_callback`、`queue_refresh_table`、`queue_refresh_calendar`、`queue_preview_item`、`queue_approve_item`、`queue_reject_item`、`queue_delete_item`、`queue_retry_item`、`queue_publish_now`、`queue_start_processor`、`queue_stop_processor`、`queue_get_status`、`queue_batch_approve`、`queue_generate_and_refresh`。
+
+`generate_to_queue` SHALL 新增 `auto_schedule: bool = False` 和 `auto_approve: bool = False` 参数：
+- 当 `auto_schedule=True` 时，SHALL 为每篇生成的内容调用 `PublishQueue.auto_schedule_item()` 自动分配排期时间
+- 当 `auto_approve=True` 时，SHALL 在入队后自动将状态从 `draft` 变为 `approved`（或 `scheduled`，如果有排期时间）
+
+#### Scenario: 模块导入成功
+- **WHEN** `main.py` 执行 `from services.queue_ops import queue_generate_and_refresh, queue_refresh_table` 等导入
+- **THEN** 所有函数可正常调用
+
+#### Scenario: publish callback 在 main.py 完成注册
+- **WHEN** 应用启动时 `main.py` 调用 `pub_queue.set_publish_callback(_queue_publish_callback)`（`_queue_publish_callback` 已迁移至 `queue_ops.py`）
+- **THEN** 队列发布回调 SHALL 正常注册并在队列处理时触发
+
+#### Scenario: 队列操作读写 pub_queue 单例
+- **WHEN** `queue_ops.py` 中的函数需要访问 `pub_queue` 或 `queue_publisher`
+- **THEN** 这些单例 SHALL 通过函数参数传入，不在 `queue_ops.py` 模块顶层初始化
+
+#### Scenario: 自动排期生成
+- **WHEN** 调用 `generate_to_queue(auto_schedule=True)` 生成 3 篇内容
+- **THEN** 每篇内容入队后 SHALL 调用 `auto_schedule_item()` 分配排期时间，3 篇内容 SHALL 分配到不同时段
+
+#### Scenario: 自动审核生成
+- **WHEN** 调用 `generate_to_queue(auto_approve=True)` 
+- **THEN** 入队项 SHALL 在添加后立即被审核通过，状态变为 `approved` 或 `scheduled`
+
+#### Scenario: queue_generate_and_refresh 传递新参数
+- **WHEN** UI 层调用 `queue_generate_and_refresh` 且用户勾选了自动排期
+- **THEN** `auto_schedule=True` SHALL 被传递到 `generate_to_queue`
@@ -0,0 +1,22 @@
+## MODIFIED Requirements
+
+### Requirement: 自动调度器函数迁移至独立模块
+系统 SHALL 将调度器相关的状态变量和函数从 `main.py` 提取至 `services/scheduler.py`，包括：`_scheduler_next_times`、`_auto_log`（列表）、`_auto_log_append`、`_scheduler_loop`、`start_scheduler`、`stop_scheduler`、`get_auto_log`、`get_scheduler_status`、`_learn_running`、`_learn_scheduler_loop`、`start_learn_scheduler`、`stop_learn_scheduler`。
+
+`_scheduler_loop` 中的自动发布分支 SHALL 改为调用 `generate_to_queue(auto_schedule=True, auto_approve=True)` 生成内容入队，不再调用 `auto_publish_once` 中的 MCP client 直接发布逻辑。
+
+#### Scenario: 调度器启停正常工作
+- **WHEN** `start_scheduler(...)` 被调用并传入合法参数
+- **THEN** 调度器线程 SHALL 正常启动，`get_scheduler_status()` 返回运行中状态
+
+#### Scenario: 日志追加线程安全
+- **WHEN** 多个自动化任务并发调用 `_auto_log_append(msg)`
+- **THEN** 日志条目 SHALL 正确追加，不丢失和乱序
+
+#### Scenario: engagement 通过回调写日志
+- **WHEN** `services/engagement.py` 中的函数需要写日志时
+- **THEN** SHALL 通过 `log_fn` 参数（由 `scheduler.py` 传入 `_auto_log_append`）写入，不直接导入 `scheduler.py`
+
+#### Scenario: 自动发布走队列路径
+- **WHEN** `_scheduler_loop` 中 `publish_enabled=True` 且到达发布时间
+- **THEN** SHALL 调用 `generate_to_queue(auto_schedule=True, auto_approve=True)` 替代直接发布，日志记录入队结果
@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: 最优时段计算
+系统 SHALL 基于 `AnalyticsService` 的 `time_weights` 数据计算每个 3 小时段的权重得分，并按得分降序排列为候选时段列表。
+
+#### Scenario: 有分析数据时按权重排序
+- **WHEN** `time_weights` 包含至少 1 个时段的权重数据
+- **THEN** `suggest_schedule_time()` SHALL 按 `weight` 值降序排列时段，优先返回高权重时段的具体时间
+
+#### Scenario: 无分析数据时使用默认时段
+- **WHEN** `time_weights` 为空字典或不存在
+- **THEN** 系统 SHALL 使用默认的高流量时段作为候选：08-11 时（权重 70）、12-14 时（权重 60）、18-21 时（权重 85）、21-24 时（权重 75）
+
+### Requirement: 时段冲突检测
+系统 SHALL 在分配排期时间前查询已有队列排期，避免同一时段内容拥堵。
+
+#### Scenario: 单时段内容上限控制
+- **WHEN** 某个 3 小时时段中已排期的队列项数量达到 `max_per_slot`（默认 2）
+- **THEN** 系统 SHALL 跳过该时段，选择下一个权重最高且有空余的时段
+
+#### Scenario: 单日内容上限控制
+- **WHEN** 某天的已排期总数达到 `max_per_day`（默认 5）
+- **THEN** 系统 SHALL 将内容排期到次日的最优可用时段
+
+#### Scenario: 最远排期范围
+- **WHEN** 未来 7 天内所有时段均已满
+- **THEN** `suggest_schedule_time()` SHALL 返回 `None`，内容以 approved 状态入队（不带排期时间）
+
+### Requirement: 排期时间精确化
+系统 SHALL 在选定的 3 小时段内随机选择一个精确的分钟级时间点，避免所有内容在整点发布。
+
+#### Scenario: 时段内随机时间
+- **WHEN** 系统选定 18-21 时段为最优
+- **THEN** SHALL 在该时段范围内随机生成精确时间（如 `2026-02-28 19:37:00`），格式为 `%Y-%m-%d %H:%M:%S`
+
+### Requirement: 队列项自动排期
+`PublishQueue` SHALL 提供 `auto_schedule_item(item_id, analytics)` 方法，为指定队列项调用排期引擎并更新其 `scheduled_time`。
+
+#### Scenario: 自动排期成功
+- **WHEN** 调用 `auto_schedule_item(item_id, analytics)` 且队列项状态为 draft 或 approved
+- **THEN** 系统 SHALL 计算最优时间并更新该项的 `scheduled_time` 和状态为 `scheduled`
+
+#### Scenario: 自动排期无可用时段
+- **WHEN** 调用 `auto_schedule_item()` 但未来 7 天无可用时段
+- **THEN** 系统 SHALL 保持队列项当前状态不变，返回 `False`
@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: 调度器发布通过队列执行
+`_scheduler_loop` 中的自动发布分支 SHALL 调用 `generate_to_queue(auto_schedule=True, auto_approve=True)` 替代 `auto_publish_once` 中的直接发布逻辑。
+
+#### Scenario: 调度器触发自动发布
+- **WHEN** `_scheduler_loop` 的 publish 定时触发且 `publish_enabled=True`
+- **THEN** 系统 SHALL 调用 `generate_to_queue` 生成内容入队（带 `auto_schedule=True, auto_approve=True`），不再直接调用 MCP client 发布
+
+#### Scenario: 发布由 QueuePublisher 完成
+- **WHEN** 调度器生成的内容入队后
+- **THEN** `QueuePublisher._loop()` SHALL 在下一次检查循环中检测到该排期/待发布项并执行实际发布
+
+### Requirement: auto_publish_once 重构为入队操作
+`auto_publish_once` SHALL 重构为仅生成内容并加入队列，不再包含直接调用 MCP client publish 的逻辑。
+
+#### Scenario: auto_publish_once 返回入队结果
+- **WHEN** 调用 `auto_publish_once` 
+- **THEN** 函数 SHALL 生成文案和图片、调用 `generate_to_queue` 入队，返回队列项 ID 和排期时间信息
+
+#### Scenario: QueuePublisher 未运行时的提示
+- **WHEN** `auto_publish_once` 成功入队但 `QueuePublisher` 未启动
+- **THEN** 返回信息中 SHALL 包含提示「内容已入队，请启动队列处理器以自动发布」
@@ -0,0 +1,34 @@
+## 1. AnalyticsService 时段权重接口
+
+- [x] 1.1 在 `services/analytics_service.py` 新增 `get_time_weights() -> dict` 方法，返回 `time_weights` 字典；无数据时返回默认高流量时段 `{"08-11时": 70, "12-14时": 60, "18-21时": 85, "21-24时": 75}`
+
+## 2. 智能排期引擎 (PublishQueue)
+
+- [x] 2.1 在 `services/publish_queue.py` 的 `PublishQueue` 类新增 `suggest_schedule_time(analytics, max_per_slot=2, max_per_day=5) -> str | None` 方法：查询未来 7 天各时段已排期数量，结合 `analytics.get_time_weights()` 权重，返回最优排期时间（格式 `%Y-%m-%d %H:%M:%S`），所有时段满时返回 `None`
+- [x] 2.2 在 `PublishQueue` 新增 `auto_schedule_item(item_id, analytics, max_per_slot=2, max_per_day=5) -> bool` 方法：调用 `suggest_schedule_time()` 并更新队列项的 `scheduled_time` + 状态为 `scheduled`，无可用时段返回 `False`
+- [x] 2.3 在 `PublishQueue` 新增 `get_slot_usage(days=7) -> dict` 辅助方法：查询未来 N 天各日期各时段已排期的数量，供排期引擎和 UI 热力图使用
+
+## 3. generate_to_queue 增加自动排期参数
+
+- [x] 3.1 修改 `services/queue_ops.py` 中 `generate_to_queue()` 签名，新增 `auto_schedule: bool = False` 和 `auto_approve: bool = False` 参数
+- [x] 3.2 在 `generate_to_queue` 入队循环中，`auto_schedule=True` 时调用 `_pub_queue.auto_schedule_item(item_id, _analytics)` 为每篇内容自动分配排期时间
+- [x] 3.3 在 `generate_to_queue` 入队循环中，`auto_approve=True` 时调用 `_pub_queue.approve(item_id)` 自动审核通过
+- [x] 3.4 修改 `queue_generate_and_refresh()` 签名，新增 `auto_schedule` 参数并传递给 `generate_to_queue`
+
+## 4. 统一发布路径 (scheduler)
+
+- [x] 4.1 修改 `services/scheduler.py` 中 `_scheduler_loop` 的自动发布分支：将 `auto_publish_once(...)` 调用替换为 `generate_to_queue(auto_schedule=True, auto_approve=True, count=1, ...)`，记录入队日志
+- [x] 4.2 重构 `auto_publish_once`：移除直接 MCP client 发布逻辑，改为调用 `generate_to_queue(auto_schedule=True, auto_approve=True, count=1)`，保留函数签名供向后兼容
+- [x] 4.3 在 `queue_ops.py` 的 `configure()` 中新增 `_analytics` 注入（如尚未注入），确保 `auto_schedule_item` 可获取分析服务
+
+## 5. UI 排期增强
+
+- [x] 5.1 在 `ui/app.py` 的「批量生成到队列」区域新增 `gr.Checkbox(label="🤖 自动排期", value=False)` 组件，勾选后隐藏手动排期输入框
+- [x] 5.2 修改批量生成按钮事件绑定，将自动排期复选框状态作为参数传入 `queue_generate_and_refresh`
+- [x] 5.3 在日历视图旁新增「📊 推荐时段」`gr.Markdown` 面板，调用 `analytics.get_time_weights()` 展示各时段权重和建议
+
+## 6. 验证
+
+- [x] 6.1 `ast.parse()` 验证所有修改文件语法正确
+- [ ] 6.2 手动测试：生成内容到队列并启用自动排期，确认 `scheduled_time` 被正确分配且不冲突
+- [ ] 6.3 手动测试：调度器自动发布走队列路径，确认内容出现在队列表格中