Add run-state persistence for FreshRSS pipeline
This commit is contained in:
root
@@ -1,83 +1,151 @@
|
||||
# TODO
|
||||
# TODO - Reader MCP 正式化
|
||||
|
||||
## 当前状态
|
||||
> 本文件用于架构与 Codex 协作同步。
|
||||
>
|
||||
> 规则：
|
||||
> - `TODO` = 未开始
|
||||
> - `DOING` = 正在进行
|
||||
> - `DONE` = 已完成
|
||||
> - 每次只允许一个最高优先级主任务处于 `DOING`
|
||||
|
||||
项目当前已经进入“可交付给 OpenClaw 调用”的阶段。
|
||||
## 0. 协作约束
|
||||
|
||||
当前主链路：
|
||||
开始编码前必须阅读：
|
||||
|
||||
`FreshRSS 未读 -> RSS 内容提取 -> LLM 总结 -> 规则过滤 -> OpenClaw delivery payload`
|
||||
|
||||
当前已经完成：
|
||||
|
||||
- [x] FreshRSS `greader` API 接入
|
||||
- [x] `entry -> item` 标准化映射
|
||||
- [x] RSS-first 内容提取策略
|
||||
- [x] LLM 摘要与校验闭环
|
||||
- [x] 第一版规则引擎
|
||||
- [x] `ArticleCandidateRecord` / `OpenClawCandidateInput` 分层
|
||||
- [x] `OpenClawDeliveryPayload` 批量投递结构
|
||||
- [x] 最终 payload 成功后才标记 FreshRSS 已读
|
||||
- [x] MCP 工具 `run_freshrss_openclaw_pipeline`
|
||||
- [x] 默认精简输出模式
|
||||
- [x] 日报级 `keywords` 词元库与周期性词元清洗 skill 设计完成
|
||||
- [x] 日报级 `keywords` 词元库与全局词频统计实现完成
|
||||
- [x] `keyword-cleanup-review` skill 骨架与 review bundle 脚本实现完成
|
||||
- [x] 词元清洗低复杂治理层落地：`term_cleanup_policy` / `term_watchlist` / `term_change_log`
|
||||
- [x] 已支持人工确认采纳建议并写入 `term_watchlist` / `term_change_log`
|
||||
1. `plans/reader-mcp-architecture-design.md`
|
||||
2. `plans/reader-mcp-implementation-plan.md`
|
||||
3. 本文件
|
||||
4. `plans/issues/2026-04-06-reader-digest-sigterm.md`
|
||||
5. `docs/openclaw/openclaw-handoff.md`
|
||||
|
||||
---
|
||||
|
||||
## P0 - 交接前后最优先
|
||||
## 1. 当前主任务
|
||||
|
||||
- [x] 为 OpenClaw 补齐交接文档
|
||||
- [x] 将 MCP 工具作为统一生产入口
|
||||
- [x] 将默认输出收敛为最小必要文件
|
||||
- [ ] 设计 OpenClaw webhook / delivery payload 的主动推送方式
|
||||
- [ ] 明确 OpenClaw 侧如何注册和启动本 MCP 服务
|
||||
### [DONE][P0] 建立 run-state 运行态基础设施
|
||||
|
||||
目标：
|
||||
- 给 freshrss pipeline 引入正式 run state
|
||||
- 即使失败或中断，也能留下明确运行真相
|
||||
|
||||
要求：
|
||||
- 新增 `RunState / StageState / ArtifactRecord` 模型
|
||||
- 在 `outputs/freshrss/rerun/<run_id>/run-state.json` 持久化
|
||||
- 至少覆盖以下 stages：
|
||||
- `fetch_feed`
|
||||
- `extract_articles`
|
||||
- `generate_summaries`
|
||||
- `apply_filters`
|
||||
- `build_delivery_payload`
|
||||
- `write_run_report`
|
||||
- 失败时写入失败阶段与错误摘要
|
||||
- 不破坏现有输出目录兼容性
|
||||
|
||||
建议文件：
|
||||
- `src/summary_mcp/runtime/state_models.py`
|
||||
- `src/summary_mcp/runtime/run_store.py`
|
||||
- `src/summary_mcp/workflows/...`
|
||||
|
||||
完成标准：
|
||||
- 跑一次 pipeline 后，无论成功失败，都存在 `run-state.json`
|
||||
- 文件中可看出当前/最后阶段、整体状态、关键 artifacts
|
||||
|
||||
进展备注：
|
||||
- 2026-04-07：架构设计文档已建立；开始进入实现阶段。
|
||||
- 2026-04-07：已新增 `runtime` 包骨架，落地 `RunState / StageState / ArtifactRecord` 与文件存储接口。
|
||||
- 2026-04-07：已将 `run-state.json` 接入 `freshrss` 主流程，按阶段持续写入状态与关键 artifacts。
|
||||
- 2026-04-07：已完成成功/失败路径自检，确认 `run-state.json` 在两类路径下都保留且不改变既有对外返回字段。
|
||||
|
||||
---
|
||||
|
||||
## P1 - 下一阶段推进
|
||||
## 2. 后续任务队列
|
||||
|
||||
- [ ] 设计“人工确认后再沉淀知识库”的状态流转
|
||||
- [ ] 收敛 `paywall` 误判规则，降低中文文本误报
|
||||
- [ ] 细化过滤规则并引入更多个性化上下文
|
||||
- [ ] 将 `keyword-cleanup-review` skill 接入周期性执行流程，产出别名/停用词/兴趣词建议
|
||||
- [ ] 增加清洗前后效果对比报告，验证配置调整是否真的改善过滤质量
|
||||
- [ ] 增加批量 run 的保留策略与历史清理策略
|
||||
- [ ] 为 OpenClaw 补一份更正式的 MCP 调用示例和接线说明
|
||||
### [TODO][P1] 增加 MCP 状态查询接口 `get_run_status`
|
||||
|
||||
目标：
|
||||
- 可通过 MCP 查询 run 状态
|
||||
|
||||
要求：
|
||||
- 输入 `run_id`
|
||||
- 返回 status / current_stage / completed_stages / failed_stage / artifacts / recovery
|
||||
|
||||
---
|
||||
|
||||
## P2 - 后续增强
|
||||
### [TODO][P1] 增加 MCP 查询接口 `list_runs`
|
||||
|
||||
- [ ] 将 `Markdown sink` 进一步降级为 debug / fallback 能力
|
||||
- [ ] 增加按天聚合 `ArticleCandidateRecord` 的批处理能力
|
||||
- [ ] 让 OpenClaw 聚合候选内容并生成日级摘要
|
||||
- [ ] 将日级摘要写入知识库，并同步生成面向用户的日报消息
|
||||
- [ ] 支持更多 `content_kind`
|
||||
- [ ] 增加提取缓存、重试和更细粒度日志
|
||||
- [ ] 整理历史 rerun 目录与调试产物保留策略
|
||||
目标：
|
||||
- 查看近期 runs
|
||||
|
||||
要求：
|
||||
- 支持按 workflow / status / latest_n 过滤
|
||||
|
||||
---
|
||||
|
||||
## 当前建议的下一步
|
||||
### [TODO][P1] 增加 MCP 查询接口 `list_run_artifacts`
|
||||
|
||||
优先做这三件事：
|
||||
|
||||
1. 将 `keyword-cleanup-review` skill 接入周期性执行流程
|
||||
2. 设计“人工确认后再沉淀知识库”的状态流转
|
||||
3. 收敛规则误判，尤其是 `paywall` 相关启发式
|
||||
目标：
|
||||
- 统一列出 run 下 artifact
|
||||
|
||||
---
|
||||
|
||||
## 交接时优先阅读
|
||||
### [TODO][P1] 增加 MCP 结果读取接口 `get_delivery_payload`
|
||||
|
||||
- `README.md`
|
||||
- `docs/openclaw/openclaw-handoff.md`
|
||||
- `docs/openclaw/openclaw-candidate-input-field-spec.md`
|
||||
- `docs/openclaw/openclaw-delivery-payload-spec.md`
|
||||
- `docs/design/daily-keyword-index-design.md`
|
||||
- `skills/keyword-cleanup-review/SKILL.md`
|
||||
- `docs/current/context-reset-brief.md`
|
||||
目标：
|
||||
- 按 run_id 读取 delivery payload
|
||||
|
||||
---
|
||||
|
||||
### [TODO][P1] 增加 MCP 结果读取接口 `get_run_report`
|
||||
|
||||
目标：
|
||||
- 按 run_id 读取 run report
|
||||
|
||||
---
|
||||
|
||||
### [TODO][P2] 设计并实现 `resume_run`
|
||||
|
||||
目标：
|
||||
- 基于 `run-state.json` 和现有中间产物继续执行
|
||||
|
||||
说明：
|
||||
- 先做最小可用恢复
|
||||
- 暂不追求任意 stage 任意重入
|
||||
|
||||
---
|
||||
|
||||
### [TODO][P2] 评估 `rerun_stage` 是否值得进入第一阶段
|
||||
|
||||
目标：
|
||||
- 在 `resume_run` 之后评估是否继续增加更细粒度补跑能力
|
||||
|
||||
---
|
||||
|
||||
### [TODO][P2] 调整 `run_freshrss_openclaw_pipeline` 内部实现以复用 runtime
|
||||
|
||||
目标：
|
||||
- 保持外部兼容
|
||||
- 内部不再是黑箱长函数
|
||||
|
||||
---
|
||||
|
||||
### [TODO][P3] 更新 README / handoff / docs，明确 MCP 为正式入口
|
||||
|
||||
目标：
|
||||
- 把生产建议从 CLI 迁移到 MCP
|
||||
- CLI 明确降级为 debug / fallback
|
||||
|
||||
---
|
||||
|
||||
## 3. 记录区
|
||||
|
||||
### 已完成记录
|
||||
|
||||
- 2026-04-07：新增架构设计文档 `plans/reader-mcp-architecture-design.md`
|
||||
- 2026-04-07：新增实施计划文档 `plans/reader-mcp-implementation-plan.md`
|
||||
- 2026-04-07：完成 `freshrss` pipeline 的 run-state 基础设施，新增 `runtime` 包并覆盖关键 stages 状态持久化。
|
||||
|
||||
### 风险提醒
|
||||
|
||||
- 不要在第一阶段引入复杂任务队列
|
||||
- 不要让 CLI 和 MCP 背后变成两套独立逻辑
|
||||
- 若实现偏离架构，先更新 `plans/` 再改代码
|
||||
|
||||
Reference in New Issue
Block a user