226 lines
7.3 KiB
Markdown
226 lines
7.3 KiB
Markdown
# TODO - Reader MCP 正式化
|
||
|
||
> 本文件用于架构与 Codex 协作同步。
|
||
>
|
||
> 规则：
|
||
> - `TODO` = 未开始
|
||
> - `DOING` = 正在进行
|
||
> - `DONE` = 已完成
|
||
> - 每次只允许一个最高优先级主任务处于 `DOING`
|
||
|
||
## 0. 协作约束
|
||
|
||
开始编码前必须阅读：
|
||
|
||
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`
|
||
|
||
---
|
||
|
||
## 1. 当前主任务
|
||
|
||
### [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` 在两类路径下都保留且不改变既有对外返回字段。
|
||
|
||
---
|
||
|
||
## 2. 后续任务队列
|
||
|
||
### [DONE][P1] 增加 MCP 状态查询接口 `get_run_status`
|
||
|
||
目标：
|
||
- 可通过 MCP 查询 run 状态
|
||
|
||
要求：
|
||
- 输入 `run_id`
|
||
- 返回 status / current_stage / completed_stages / failed_stage / artifacts / recovery
|
||
|
||
完成情况：
|
||
- 已通过 MCP 暴露 `get_run_status`
|
||
- 优先读取 `run-state.json`；对无 `run-state.json` 的历史 run 兼容基于现有 run 目录与 `run-report.json` 推断状态
|
||
- 返回补充了 `progress` / `output_dir` / `state_source`，便于 OpenClaw 稳定消费且不必手拼路径
|
||
|
||
改动文件：
|
||
- `src/summary_mcp/runtime/query_service.py`
|
||
- `src/summary_mcp/runtime/run_store.py`
|
||
- `src/summary_mcp/runtime/__init__.py`
|
||
- `src/summary_mcp/server.py`
|
||
|
||
遗留风险：
|
||
- 历史 run 若缺少 `run-state.json`，其阶段状态只能基于现有目录与 `run-report.json` 做保守推断
|
||
|
||
---
|
||
|
||
### [DONE][P1] 增加 MCP 查询接口 `list_runs`
|
||
|
||
目标：
|
||
- 查看近期 runs
|
||
|
||
要求：
|
||
- 支持按 workflow / status / latest_n 过滤
|
||
|
||
完成情况：
|
||
- 已通过 MCP 暴露 `list_runs`
|
||
- 支持按 `workflow` / `status` / `latest_n` 过滤近期 runs
|
||
- 返回 `run_id`、`status`、`progress`、`recovery`、`output_dir` 与 `state_source`
|
||
|
||
改动文件：
|
||
- `src/summary_mcp/runtime/query_service.py`
|
||
- `src/summary_mcp/runtime/__init__.py`
|
||
- `src/summary_mcp/server.py`
|
||
|
||
遗留风险：
|
||
- 当前按文件系统扫描 `outputs/freshrss/rerun/` 聚合，规模继续增大时可能需要再评估缓存或索引，但本阶段先保持文件系统真相
|
||
|
||
---
|
||
|
||
### [DONE][P1] 增加 MCP 查询接口 `list_run_artifacts`
|
||
|
||
目标：
|
||
- 统一列出 run 下 artifact
|
||
|
||
完成情况：
|
||
- 已通过 MCP 暴露 `list_run_artifacts`
|
||
- 对新 run 优先返回 `run-state.json` 已注册 artifacts，并补充 run 目录扫描发现的标准产物
|
||
- 对历史 run 直接基于现有 run 目录发现标准产物，保持兼容
|
||
|
||
改动文件：
|
||
- `src/summary_mcp/runtime/query_service.py`
|
||
- `src/summary_mcp/runtime/__init__.py`
|
||
- `src/summary_mcp/server.py`
|
||
|
||
遗留风险：
|
||
- 当前仅补充扫描固定的一组标准产物；未注册且不在标准集合内的调试文件不会进入稳定 artifact 列表
|
||
|
||
---
|
||
|
||
### [DONE][P1] 增加 MCP 结果读取接口 `get_delivery_payload`
|
||
|
||
目标：
|
||
- 按 run_id 读取 delivery payload
|
||
|
||
完成情况：
|
||
- 已通过 MCP 暴露 `get_delivery_payload`
|
||
- 查询优先复用 `run-state.json` 已注册 artifacts，其次回退标准产物路径、`run-report.json` 引用和 run 目录扫描
|
||
- 返回补充了 `artifact`、`payload_schema_version`、`generated_at`、`delivery_date`、`candidate_count`、`stats`，并保留完整 `payload`
|
||
|
||
改动文件：
|
||
- `src/summary_mcp/runtime/query_service.py`
|
||
- `src/summary_mcp/server.py`
|
||
- `src/summary_mcp/runtime/__init__.py`
|
||
|
||
遗留风险：
|
||
- 历史 run 的 payload 若既未注册也不在标准路径下，只能依赖 `run-report.json` 引用或目录扫描做兼容发现
|
||
|
||
---
|
||
|
||
### [DONE][P1] 增加 MCP 结果读取接口 `get_run_report`
|
||
|
||
目标：
|
||
- 按 run_id 读取 run report
|
||
|
||
完成情况：
|
||
- 已通过 MCP 暴露 `get_run_report`
|
||
- 查询优先复用 `run-state.json` 已注册 artifacts，其次回退标准产物路径、历史 `run-report.json` 固定位置和 run 目录扫描
|
||
- 返回补充了 `artifact`、核心计数摘要、规范化后的关键产物路径与 `keyword_index`，并保留完整 `report`
|
||
|
||
改动文件：
|
||
- `src/summary_mcp/runtime/query_service.py`
|
||
- `src/summary_mcp/runtime/__init__.py`
|
||
- `src/summary_mcp/server.py`
|
||
|
||
遗留风险：
|
||
- 历史 run 的 `run-report.json` 内嵌路径仍保留原始绝对路径于 `report` 字段，当前仅在顶层摘要字段做规范化，避免改变历史文件真相
|
||
|
||
---
|
||
|
||
### [DONE][P2] 设计并实现 `resume_run`
|
||
|
||
目标：
|
||
- 基于 `run-state.json` 和现有中间产物继续执行
|
||
|
||
说明：
|
||
- 先做最小可用恢复
|
||
- 暂不追求任意 stage 任意重入
|
||
- 设计约束已补充到 `plans/resume-run-minimal-design.md`
|
||
- 第一版只支持 freshrss workflow 且仅支持有 `run-state.json` 的 run
|
||
- 第一版仅考虑从最近可恢复点继续；`fetch_feed` / `extract_articles` 暂不支持恢复
|
||
|
||
进展备注：
|
||
- 2026-04-07：已完成 `resume_run` minimal design 与现有 runtime/workflow/server 代码对齐分析，开始实现最小恢复链路。
|
||
- 2026-04-07：已完成 `resume_run` 最小实现编码，新增 runtime 恢复服务并接入 MCP server；当前进入设计对齐与本地自检。
|
||
- 2026-04-07：已完成 `resume_run` 架构对齐与本地自检；已验证 `write_run_report` 可恢复，且 `extract_articles` 会被明确拒绝恢复。
|
||
|
||
---
|
||
|
||
### [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/` 再改代码
|