feat: add async resume jobs and doc navigation
This commit is contained in:
root
@@ -2,152 +2,104 @@
|
||||
|
||||
## 当前结论
|
||||
|
||||
当前仓库已经具备交付给 OpenClaw 的基础条件。
|
||||
当前仓库已经具备作为 OpenClaw 上游服务的正式基础能力。
|
||||
|
||||
当前主链路是：
|
||||
当前正式主链路是：
|
||||
|
||||
`FreshRSS 未读 -> RSS 内容提取 -> LLM 总结 -> 规则过滤 -> OpenClaw delivery payload`
|
||||
|
||||
OpenClaw 应通过 MCP 工具 `run_freshrss_openclaw_pipeline` 调用这条链路，而不是自行拼接脚本。
|
||||
当前正式控制面已经收口为异步 job：
|
||||
|
||||
## 当前已完成
|
||||
- 主日报：`start_freshrss_pipeline_job -> poll -> get result`
|
||||
- 恢复：`inspect_resume_plan -> start_resume_job -> poll -> get result`
|
||||
- 单篇总结：`start_article_summary_job -> poll -> get result`
|
||||
|
||||
- 已完成 FreshRSS `greader` API 接入与未读拉取
|
||||
- 已完成 FreshRSS 条目到标准化 `item` 的映射
|
||||
- 已完成 RSS-first 提取策略
|
||||
- 已完成 LLM 总结与校验闭环
|
||||
- 已完成规则引擎过滤
|
||||
- 已完成 `ArticleCandidateRecord` 与 `OpenClawCandidateInput` 分层
|
||||
- 已完成 `OpenClawDeliveryPayload` 批量投递结构
|
||||
- 已完成 FreshRSS 已读状态回写
|
||||
- 已完成“仅在最终 payload 成功写盘后再标记已读”的语义
|
||||
- 已完成 MCP 工具 `run_freshrss_openclaw_pipeline`
|
||||
- 已完成默认精简输出模式，减少中间文件
|
||||
- 已完成日报级 `keywords` 词元库与全局词频统计
|
||||
- 已完成 `keyword-cleanup-review` skill 骨架与 review bundle 脚本
|
||||
- 已完成低复杂治理层：`term_cleanup_policy` / `term_watchlist` / `term_change_log`
|
||||
- 已完成采纳建议写回脚本 `scripts/apply_term_suggestions.py`
|
||||
同步 `run_freshrss_openclaw_pipeline`、`resume_run`、`generate_article_summaries` 仍保留，但只用于 debug / fallback。
|
||||
|
||||
## 当前 MCP 工具
|
||||
## 当前权威入口
|
||||
|
||||
当前服务入口：
|
||||
先看这些文档：
|
||||
|
||||
- `src/summary_mcp/server.py`
|
||||
1. `README.md`
|
||||
2. `docs/README.md`
|
||||
3. `docs/openclaw/README.md`
|
||||
4. `docs/openclaw/openclaw-handoff.md`
|
||||
5. `docs/openclaw/openclaw-orchestration-flow.md`
|
||||
6. `plans/README.md`
|
||||
7. `TODO.md`
|
||||
|
||||
当前暴露的 MCP 工具：
|
||||
如果问题是 OpenClaw 集成、状态分支或恢复策略，优先看 `docs/openclaw/`，不要先翻历史计划。
|
||||
|
||||
- `extract_url_content`
|
||||
- `extract_item_content`
|
||||
- `filter_summary_result`
|
||||
- `run_freshrss_openclaw_pipeline`
|
||||
## 当前正式能力
|
||||
|
||||
其中生产主入口是：
|
||||
- FreshRSS 主日报 run 会落地 `run-state.json`
|
||||
- `get_run_status` / `list_runs` / `list_run_artifacts` 提供 run 级观测
|
||||
- `get_delivery_payload` / `get_run_report` 提供正式结果读取
|
||||
- 查询层已经支持 stale state 与终态 artifacts 的状态收敛
|
||||
- 主日报正式启动已切到 async job
|
||||
- `resume` 已切到 async job，并在执行前先做 `inspect_resume_plan`
|
||||
- 生产恢复依赖 `summary/summary-batch.json` 与 `candidates/candidate-batch.json`
|
||||
- 单篇总结也已补齐 async job 形态
|
||||
|
||||
- `run_freshrss_openclaw_pipeline`
|
||||
## 当前关键代码入口
|
||||
|
||||
## 当前关键文件
|
||||
- MCP 服务入口：`src/summary_mcp/server.py`
|
||||
- 主日报 workflow：`src/summary_mcp/workflows/freshrss_pipeline.py`
|
||||
- run / artifact 查询：`src/summary_mcp/runtime/query_service.py`
|
||||
- 主日报 async job：`src/summary_mcp/runtime/freshrss_pipeline_jobs.py`
|
||||
- resume 预检与恢复：`src/summary_mcp/runtime/resume_service.py`
|
||||
- resume async job：`src/summary_mcp/runtime/resume_jobs.py`
|
||||
- 单篇总结 async job：`src/summary_mcp/runtime/article_summary_jobs.py`
|
||||
- 关键词治理：`src/summary_mcp/core/keyword_index.py`
|
||||
|
||||
- MCP 服务入口
|
||||
- `src/summary_mcp/server.py`
|
||||
- FreshRSS 统一工作流
|
||||
- `src/summary_mcp/workflows/freshrss_pipeline.py`
|
||||
- 词元统计核心
|
||||
- `src/summary_mcp/core/keyword_index.py`
|
||||
- 词元统计模型
|
||||
- `src/summary_mcp/models/keyword_index.py`
|
||||
- 摘要循环
|
||||
- `src/summary_mcp/core/summary_loop.py`
|
||||
- 提取主流程
|
||||
- `src/summary_mcp/core/pipeline.py`
|
||||
- FreshRSS 集成
|
||||
- `src/summary_mcp/integrations/freshrss.py`
|
||||
- 规则引擎
|
||||
- `src/summary_mcp/filters/engine.py`
|
||||
- LLM 结果校验
|
||||
- `src/summary_mcp/validators/llm_result.py`
|
||||
- OpenClaw candidate 模型
|
||||
- `src/summary_mcp/models/article_candidate.py`
|
||||
- OpenClaw delivery 模型
|
||||
- `src/summary_mcp/models/openclaw_delivery.py`
|
||||
- 生产脚本入口
|
||||
- `scripts/run_freshrss_pipeline.py`
|
||||
- 词元统计重建脚本
|
||||
- `scripts/build_keyword_index.py`
|
||||
- 词元清洗 skill
|
||||
- `skills/keyword-cleanup-review/SKILL.md`
|
||||
- skill review bundle 脚本
|
||||
- `skills/keyword-cleanup-review/scripts/build_review_bundle.py`
|
||||
- 采纳建议写回脚本
|
||||
- `scripts/apply_term_suggestions.py`
|
||||
- 清洗治理配置
|
||||
- `configs/term_cleanup_policy.json`
|
||||
- `configs/term_watchlist.json`
|
||||
- `configs/term_change_log.json`
|
||||
- OpenClaw 交接说明
|
||||
- `docs/openclaw/openclaw-handoff.md`
|
||||
## 当前核心产物
|
||||
|
||||
## 当前输出规则
|
||||
主日报稳定产物：
|
||||
|
||||
默认生产模式只输出：
|
||||
- `outputs/freshrss/rerun/<run_dir>/run-state.json`
|
||||
- `outputs/freshrss/rerun/<run_dir>/raw/freshrss.raw.json`
|
||||
- `outputs/freshrss/rerun/<run_dir>/summary/summary-batch.json`
|
||||
- `outputs/freshrss/rerun/<run_dir>/candidates/candidate-batch.json`
|
||||
- `outputs/freshrss/rerun/<run_dir>/candidates/openclaw-delivery-payload.json`
|
||||
- `outputs/freshrss/rerun/<run_dir>/candidates/digest-brief.json`
|
||||
- `outputs/freshrss/rerun/<run_dir>/run-report.json`
|
||||
- `outputs/freshrss/rerun/<run_dir>/extracted/item-XX.extracted.json`
|
||||
|
||||
- `raw/freshrss.raw.json`
|
||||
- `candidates/openclaw-delivery-payload.json`
|
||||
- `run-report.json`
|
||||
job 状态目录：
|
||||
|
||||
同时会更新本地运行数据：
|
||||
- `outputs/freshrss/pipeline_jobs/<job_id>/`
|
||||
- `outputs/freshrss/resume_jobs/<job_id>/`
|
||||
- `outputs/freshrss/article_summary_jobs/<job_id>/`
|
||||
|
||||
关键词运行数据：
|
||||
|
||||
- `data/term_index/daily/YYYY-MM-DD.json`
|
||||
- `data/term_index/term_stats.json`
|
||||
|
||||
如果需要词元清洗审阅输入，可额外生成：
|
||||
## 当前已验证
|
||||
|
||||
- `outputs/term_index/review/keyword-cleanup-bundle.json`
|
||||
- FreshRSS 未读拉取与已读回写可用
|
||||
- RSS-first 提取策略可用
|
||||
- 主日报 MCP 主链路可触发并写出正式产物
|
||||
- 状态查询与结果读取接口可用
|
||||
- stale state / artifacts 收敛逻辑已落地
|
||||
- `resume` 的 artifact-first 判定已落地
|
||||
- `start_resume_job -> poll -> result` 已做本地 synthetic 验证
|
||||
- 单篇总结 async job 可跑通
|
||||
- 关键词 review bundle 与建议写回脚本可用
|
||||
|
||||
如果需要在人工确认后把建议正式写入 watchlist / change log，可使用：
|
||||
## 当前主要限制
|
||||
|
||||
- `scripts/apply_term_suggestions.py`
|
||||
- 某些源 RSS 正文不足时会被直接跳过
|
||||
- 规则仍然偏保守，部分内容会落到 `review`
|
||||
- `paywall` 启发式对中文仍可能误判
|
||||
- 关键词治理还没有接入周期性调度
|
||||
- `digest-brief.json` 仍没有独立 MCP 读取工具
|
||||
- `resume` 目前的剩余主风险不再是恢复点判定，而是缺少真实生产环境的完整恢复验证
|
||||
|
||||
如果需要排障，可开启：
|
||||
## 当前建议
|
||||
|
||||
- `debug_artifacts=true`
|
||||
- 或脚本参数 `--debug-artifacts`
|
||||
|
||||
这样才会额外输出逐条中间文件。
|
||||
|
||||
## 当前验证状态
|
||||
|
||||
已经验证通过：
|
||||
|
||||
- FreshRSS 未读拉取成功
|
||||
- 已读回写成功
|
||||
- MCP 工具入口可直接触发完整链路
|
||||
- 微信公众号样本可直接使用 RSS 提供的 `summary` 内容提取，不再回源抓网页
|
||||
- 精简输出模式已实际跑通
|
||||
- 日报级词元统计已通过离线样例验证，确认别名、停用词、非 `drop` 过滤和 rerun 覆盖逻辑正常
|
||||
- `keyword-cleanup-review` skill 已通过 `quick_validate.py` 结构校验
|
||||
- review bundle 脚本已实际跑通
|
||||
- `apply_term_suggestions.py` 已通过 dry-run 与临时副本写回验证
|
||||
|
||||
## 当前已知限制
|
||||
|
||||
- 当前对 FreshRSS 条目采用 RSS-first 策略，不再回源抓原网页
|
||||
- 如果 RSS 中没有足够正文内容，该条会直接跳过，不会进入后续总结
|
||||
- 某些规则仍偏保守，部分内容可能落到 `review`
|
||||
- `paywall` 相关启发式仍可能误判中文文本
|
||||
- Webhook / 主动投递到 OpenClaw 外部接口尚未实现，当前是由 OpenClaw 通过 MCP 主动调用
|
||||
- 词元清洗 skill 当前已支持“bundle 构建 -> 建议审阅 -> 人工确认写回 watchlist/change_log”，但尚未接入周期性调度
|
||||
- 当前词元统计仍以前置 `OpenClawDeliveryPayload` 作为日报前代理输入，真实 `DailyDigest` 接入后还需切换上游
|
||||
|
||||
## 当前最建议的交接阅读顺序
|
||||
|
||||
1. `README.md`
|
||||
2. `docs/openclaw/openclaw-handoff.md`
|
||||
3. `docs/openclaw/openclaw-candidate-input-field-spec.md`
|
||||
4. `docs/openclaw/openclaw-delivery-payload-spec.md`
|
||||
5. `docs/design/daily-keyword-index-design.md`
|
||||
6. `skills/keyword-cleanup-review/SKILL.md`
|
||||
7. `TODO.md`
|
||||
|
||||
## 一句话结论
|
||||
|
||||
当前仓库已经从“提取 MCP 原型”演进到“可供 OpenClaw 调用的 FreshRSS -> OpenClaw payload 上游处理器”，并已补上第一阶段的日报级词元统计能力和词元清洗 skill 骨架；后续重点转向 skill 周期调度、知识库状态流转和 webhook 接线。
|
||||
- 把 `docs/openclaw/openclaw-orchestration-flow.md` 当成正式编排手册
|
||||
- 把 `docs/openclaw/openclaw-handoff.md` 当成接手总览
|
||||
- 把 `plans/README.md` 当成规划文档导航
|
||||
- 把 `docs/openclaw/archive/` 和 `docs/archive/` 当成历史资料，不要当当前事实源
|
||||
|
||||
Reference in New Issue
Block a user