# 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. **小步提交**
   - 每完成一个可验证的小目标就提交
   - 不要攒一个超大变更

---

## 建议目录改造

建议新增：

```text
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 工作流服务”，再做更多工具；不要反过来先堆接口名。