reader/plans/reader-mcp-implementation-plan.md

Reader MCP 实施计划

目标

把 reader 从“生产上主要依赖长 CLI/exec”推进到“以 MCP 为正式入口的工作流服务”。

协作分工

• 架构与方向：由我负责
• 编码实现：由 Codex 负责
• 同步机制：通过 plans/ 下规划文档 + TODO.md 保持进度与方向一致

当前权威文档

实现前，必须先读：

1. plans/reader-mcp-architecture-design.md
2. plans/reader-mcp-implementation-plan.md
3. TODO.md
4. plans/issues/2026-04-06-reader-digest-sigterm.md
5. docs/openclaw/openclaw-handoff.md

如实现细节与旧文档冲突，以：

1. 最新架构设计文档
2. 最新实施计划
3. TODO 当前项

为准。

---

里程碑

M1：运行态落地（最优先）

目标：让现有 freshrss pipeline 拥有明确 run state。

交付：

• 新增 run-state.json 持久化能力
• 定义 RunState / StageState / ArtifactRecord 模型
• 现有 pipeline 按 stage 更新状态
• 保持现有产物目录兼容

完成标准：

• 任意一次 run 都能产出 outputs/freshrss/rerun/<run_id>/run-state.json
• 中途失败时也能看到失败阶段和已有 artifacts

---

M2：状态查询接口

目标：通过 MCP 查询 run 状态，不再只靠 CLI 或手看目录。

交付：

• 新增 get_run_status
• 新增 list_runs
• 新增 list_run_artifacts

完成标准：

• OpenClaw 可通过 MCP 查询 run 当前状态
• 不需要直接读磁盘路径判断是否成功

---

M3：结果读取接口

目标：通过 MCP 获取结果内容，而不是自己拼文件路径。

交付：

• 新增 get_delivery_payload
• 新增 get_run_report
• 视情况新增 get_digest_brief
• 视情况新增 get_extracted_article

完成标准：

• OpenClaw 只要知道 run_id，就能获取关键结果

---

M4：恢复与补跑

目标：reader 具备正式的恢复机制。

交付：

• 新增 resume_run
• 视情况新增 rerun_stage
• 在 run-state.json 中记录 recovery 信息

完成标准：

• 至少支持从最近成功 stage 之后继续执行
• 能给出可恢复/不可恢复的明确判断

---

M5：生产入口切换

目标：OpenClaw 正式从 exec 模式切到 MCP 模式。

交付：

• 保留 CLI 作为 debug/fallback
• 生产推荐入口改为 MCP run + status + payload
• 更新 handoff / README / docs

完成标准：

• 正式流程默认不再依赖长 CLI exec

---

编码原则

1. 优先复用现有业务逻辑

   • 不要重写成熟的 FreshRSS / extract / summary / filter 逻辑
   • 优先抽 runtime 层把现有逻辑包起来

2. 先状态化，再协议扩展

   • 先把 run-state 跑通
   • 再补 MCP tools

3. 保持向后兼容

   • run_freshrss_openclaw_pipeline 先保留
   • 内部逐步改为调用新的 runtime

4. CLI 降级，不删除

   • 仍保留 debug/fallback 价值
   • 但不要让 CLI 和 MCP 背后出现两套逻辑

5. 小步提交

   • 每完成一个可验证的小目标就提交
   • 不要攒一个超大变更

---

建议目录改造

建议新增：

src/summary_mcp/runtime/
  state_models.py
  run_store.py
  artifact_store.py
  workflow_service.py
  stage_runner.py

说明：

• 目录名可微调
• 但必须把“运行态管理”从现有 workflows 中抽出来，避免继续黑箱化

---

Codex 工作方式要求

Codex 每次开始前：

1. 先读 plans/reader-mcp-architecture-design.md
2. 再读本文件
3. 再读 TODO.md
4. 只处理 TODO 中 TODO 状态的当前优先项

Codex 每完成一项后：

1. 更新 TODO.md
2. 在 TODO 对应项下补：
   • 完成情况
   • 改动文件
   • 遗留风险
3. 如实现偏离原架构，必须先更新 plans/ 文档，再继续代码

---

决策规则

如果出现以下情况：

• 需要新增 MCP tool，但架构设计中未定义
• 需要改动现有 pipeline 关键语义
• 需要引入数据库 / 队列 / 线程池 / 后台 worker
• 需要改变 OpenClaw 与 reader 的边界

则不允许 Codex自行拍板，必须先回写到：

• plans/reader-mcp-architecture-design.md
• 或新增 plans/issues/*.md

由架构层确认后再继续。

---

当前实现顺序（强约束）

按以下顺序推进：

1. run-state.json 模型与持久化
2. pipeline 中 stage 状态更新
3. get_run_status
4. list_runs / list_run_artifacts
5. get_delivery_payload / get_run_report
6. resume_run
7. 再考虑 rerun_stage

不要一上来就做复杂异步后台队列。

---

一句话执行口径

先把 reader 做成“有运行真相的 MCP 工作流服务”，再做更多工具；不要反过来先堆接口名。