docs: formalize reader MCP workflow service handoff

README.md

@@ -1,6 +1,6 @@
-# 内容提取 MCP
+# Reader MCP Workflow Service
 
-这是一个基于 Python 的 MCP 项目骨架，用于完成文章内容提取、结构化摘要校验、确定性过滤，以及 Markdown 输出落盘。
+reader 当前已经收口为面向 OpenClaw 的 MCP workflow service。正式能力边界以 FreshRSS 日报工作流为准：启动 run、写入 `run-state.json`、查询运行状态、读取结构化结果，以及最小可用的 `resume_run`。CLI 仍保留，但定位为 debug / fallback，而不是正式集成入口。
 
 ## 运行
 
@@ -9,14 +9,50 @@ pip install -e .
 summary-mcp
 ```
 
-服务当前暴露 5 个工具：
+服务当前暴露 11 个工具。
+
+正式 workflow service 相关工具：
+
+- `run_freshrss_openclaw_pipeline`
+- `get_run_status`
+- `list_runs`
+- `list_run_artifacts`
+- `get_delivery_payload`
+- `get_run_report`
+- `resume_run`
+
+单步处理 / 调试相关工具：
 
 - `extract_url_content`
 - `extract_item_content`
 - `filter_summary_result`
-- `run_freshrss_openclaw_pipeline`
 - `generate_article_summaries`
 
+## 正式能力边界
+
+- 当前正式 workflow 只有 `freshrss_daily_digest`
+- 每次 FreshRSS 主流水线 run 都会在 `outputs/freshrss/rerun/<run_dir>/run-state.json` 落地运行真相
+- OpenClaw 正式读取结果应优先使用 `get_delivery_payload` 与 `get_run_report`，而不是自己拼输出目录路径
+- `digest-brief.json` 当前会随主流水线产出，但还没有独立的 MCP 读取工具；如需定位它，应通过 `list_run_artifacts` 或 `get_run_report` 返回的信息发现
+- `run_freshrss_openclaw_pipeline` 与 `resume_run` 当前都是同步 MCP 调用；仓库里还没有后台队列 / worker / 异步任务管理
+
+## OpenClaw 推荐调用路径
+
+1. 调用 `run_freshrss_openclaw_pipeline` 启动正式日报 run，并保存返回的 `run_id`
+2. 后续所有状态判断都基于 `get_run_status(run_id)` 或 `list_runs(...)`
+3. 需要看产物列表时用 `list_run_artifacts(run_id)`，不要在 OpenClaw 里硬编码 `outputs/freshrss/rerun/...`
+4. 需要消费正式结果时优先用 `get_delivery_payload(run_id)` 与 `get_run_report(run_id)`
+5. 仅当 `resume_run` 的最小恢复范围满足时，才对失败 run 调用 `resume_run(run_id)`；否则应重启一个新 run
+
+## `resume_run` 当前最小范围
+
+- 只支持带有效 `run-state.json` 的 run
+- 只支持 workflow `freshrss_daily_digest`
+- 恢复时继续沿用原 `run_id`，不会新建 retry run
+- 当前支持的恢复起点只有：`generate_summaries`、`apply_filters`、`build_delivery_payload`、`write_run_report`
+- 当前明确不支持从 `fetch_feed`、`extract_articles` 恢复；这类失败应新开 run
+- 恢复前会校验关键中间产物是否齐备，缺失时直接返回不可恢复，而不会自动回退到更早 stage
+
 ## 单篇文章总结后处理（可选使用独立 LLM）
 
 ### 生产环境推荐输入
@@ -34,7 +70,7 @@ summary-mcp
 
 相关能力：
 
-- `article-summary` MCP 工具（基于已有 extracted payload 做单篇总结）
+- `generate_article_summaries` MCP 工具（基于已有 extracted payload 做单篇总结）
 - `scripts/run_article_summaries.py` CLI 辅助脚本
 
 ## 校验 LLM 摘要结果
@@ -111,13 +147,14 @@ python scripts/run_freshrss_pipeline.py ^
   --mark-read
 ```
 
-这是当前推荐的**正式生产入口**。默认只写出这些产物：
+这条 CLI 与 MCP `run_freshrss_openclaw_pipeline` 共用同一条主流水线逻辑，但正式生产集成应优先走 MCP；CLI 仅用于本地 debug / fallback。默认会写出这些产物：
 
-- `outputs/freshrss/rerun/<timestamp>/raw/freshrss.raw.json`
-- `outputs/freshrss/rerun/<timestamp>/candidates/openclaw-delivery-payload.json`
-- `outputs/freshrss/rerun/<timestamp>/candidates/digest-brief.json`（给 OpenClaw 生成 public digest 用的轻量输入，仅包含 `keep` 候选）
-- `outputs/freshrss/rerun/<timestamp>/run-report.json`
-- `outputs/freshrss/rerun/<timestamp>/extracted/item-XX.extracted.json`（每篇一份）
+- `outputs/freshrss/rerun/<run_dir>/run-state.json`
+- `outputs/freshrss/rerun/<run_dir>/raw/freshrss.raw.json`
+- `outputs/freshrss/rerun/<run_dir>/candidates/openclaw-delivery-payload.json`
+- `outputs/freshrss/rerun/<run_dir>/candidates/digest-brief.json`（给 OpenClaw 生成 public digest 用的轻量输入，仅包含 `keep` 候选）
+- `outputs/freshrss/rerun/<run_dir>/run-report.json`
+- `outputs/freshrss/rerun/<run_dir>/extracted/item-XX.extracted.json`（每篇一份）
 
 同时还会更新每日关键词索引运行数据：
 
@@ -127,8 +164,8 @@ python scripts/run_freshrss_pipeline.py ^
 主流水线默认**不会**产出批量级的 `freshrss.extracted.json`。
 如果你需要更多逐条中间产物，例如标准化 items、摘要结果、过滤决策、candidate record、candidate input，可以加 `--debug-artifacts`。
 
-当 OpenClaw 接入这个 MCP 服务后，应直接调用 `run_freshrss_openclaw_pipeline` 来获得同样行为。
-在排查复杂问题时，也可以把 `debug_artifacts=true` 打开。
+当 OpenClaw 接入这个 MCP 服务后，应以 `run_id` 作为稳定句柄：先调用 `run_freshrss_openclaw_pipeline`，再通过 `get_run_status` / `get_delivery_payload` / `get_run_report` 读取状态与结果，而不是直接拼接目录路径。
+在排查复杂问题时，也可以把 `debug_artifacts=true` 打开，并结合 `list_run_artifacts` 查看该 run 下实际产物。
 
 ## 对结构化摘要结果执行确定性过滤规则