feat: add async resume jobs and doc navigation

README.md

@@ -1,6 +1,6 @@
 # Reader MCP Workflow Service
 
-reader 当前已经收口为面向 OpenClaw 的 MCP workflow service。正式能力边界以 FreshRSS 日报工作流为准：启动 run、写入 `run-state.json`、查询运行状态、读取结构化结果，以及最小可用的 `resume_run`。CLI 仍保留，但定位为 debug / fallback，而不是正式集成入口。
+reader 当前已经收口为面向 OpenClaw 的 MCP workflow service。正式能力边界以 FreshRSS 日报工作流为准：启动 run、写入 `run-state.json`、查询运行状态、读取结构化结果，以及异步恢复 job。CLI 与同步入口仍保留，但定位为 debug / fallback，而不是正式集成入口。
 
 ## 运行
 
@@ -9,62 +9,54 @@ pip install -e .
 summary-mcp
 ```
 
-服务当前暴露 17 个工具。
+服务当前暴露 21 个工具。
 
-正式 workflow service 相关工具：
+正式集成摘要：
 
-- `start_freshrss_pipeline_job`
-- `get_freshrss_pipeline_job_status`
-- `get_freshrss_pipeline_job_result`
-- `get_run_status`
-- `list_runs`
-- `list_run_artifacts`
-- `get_delivery_payload`
-- `get_run_report`
-- `resume_run`
+- 主日报正式入口：`start_freshrss_pipeline_job`
+- 主日报正式读取：`get_run_status`、`get_delivery_payload`、`get_run_report`
+- 恢复正式入口：`inspect_resume_plan`、`start_resume_job`、`get_resume_job_status`、`get_resume_job_result`
+- 单篇总结正式入口：`start_article_summary_job`、`get_article_summary_job_status`、`get_article_summary_job_result`
+- `run_freshrss_openclaw_pipeline`、`resume_run`、`generate_article_summaries` 仅用于同步 debug / fallback
 
-单步处理 / 调试相关工具：
+## 文档入口
 
-- `run_freshrss_openclaw_pipeline`（同步 debug / fallback）
-- `extract_url_content`
-- `extract_item_content`
-- `filter_summary_result`
-- `generate_article_summaries`（同步模式）
-- `start_article_summary_job`
-- `get_article_summary_job_status`
-- `get_article_summary_job_result`
+如果你在做 OpenClaw 集成，不要只看这个 README，优先看：
+
+- `docs/openclaw/README.md`
+- `docs/openclaw/openclaw-handoff.md`
+- `docs/openclaw/openclaw-orchestration-flow.md`
+
+字段契约见：
+
+- `docs/openclaw/openclaw-candidate-input-field-spec.md`
+- `docs/openclaw/openclaw-delivery-payload-spec.md`
+
+文档总索引见：
+
+- `docs/README.md`
+- `docs/current/context-reset-brief.md`
+- `docs/design/README.md`
+- `plans/README.md`
 
 ## 正式能力边界
 
 - 当前正式 workflow 只有 `freshrss_daily_digest`
+- 当前生产编排默认走异步 job，而不是同步 MCP / CLI
 - 每次 FreshRSS 主流水线 run 都会在 `outputs/freshrss/rerun/<run_dir>/run-state.json` 落地运行真相
-- FreshRSS 主日报的正式生产启动路径已切到最小异步 job：`start_freshrss_pipeline_job` -> `get_freshrss_pipeline_job_status` -> `get_freshrss_pipeline_job_result`
-- OpenClaw 正式读取结果应优先使用 `get_delivery_payload` 与 `get_run_report`，而不是自己拼输出目录路径
-- `digest-brief.json` 当前会随主流水线产出，但还没有独立的 MCP 读取工具；如需定位它，应通过 `list_run_artifacts` 或 `get_run_report` 返回的信息发现
-- `run_freshrss_openclaw_pipeline` 仍保留，但定位已降级为同步 debug / fallback 路径，不再是 OpenClaw 的默认生产启动入口
-- 单篇总结已补上最小异步 job 形态：`start_article_summary_job` / `get_article_summary_job_status` / `get_article_summary_job_result`
-- `generate_article_summaries` 仍保留，但定位是同步 debug 路径，而不是 OpenClaw 的正式生产集成入口
+- OpenClaw 正式读取结果应优先使用 MCP 返回的 `run_id`、`output_dir`、`delivery_output`、`report_output`
+- 正式恢复只支持带有效 `run-state.json` 的当前 run，不处理历史推断 run
+- 正式生产恢复依赖 `summary/summary-batch.json` 与 `candidates/candidate-batch.json`
 
-## OpenClaw 推荐调用路径
+## OpenClaw 最短调用路径
 
-1. 调用 `start_freshrss_pipeline_job` 启动正式日报 job，并保存返回的 `job_id`
-2. 轮询 `get_freshrss_pipeline_job_status(job_id)`，直到 `status` 变成 `success` 或 `failed`
-3. 成功后调用 `get_freshrss_pipeline_job_result(job_id)` 读取 `run_id` 与关键产物路径
-4. 后续所有 run 级状态判断都基于 `get_run_status(run_id)` 或 `list_runs(...)`
-5. 需要看产物列表时用 `list_run_artifacts(run_id)`，不要在 OpenClaw 里硬编码 `outputs/freshrss/rerun/...`
-6. 需要消费正式结果时优先用 `get_delivery_payload(run_id)` 与 `get_run_report(run_id)`
-7. 仅当 `resume_run` 的最小恢复范围满足时，才对失败 run 调用 `resume_run(run_id)`；否则应重启一个新 run
+1. 调 `start_freshrss_pipeline_job`
+2. 轮询 `get_freshrss_pipeline_job_status`
+3. 成功后读 `get_freshrss_pipeline_job_result`，拿 `run_id`
+4. 用 `get_run_status`、`get_delivery_payload`、`get_run_report` 做后续读取
+5. 如需恢复，先调 `inspect_resume_plan`，只有 `recommended_action=resume` 才走 `start_resume_job`
 
-主日报 async job 的自身状态目录固定在 `outputs/freshrss/pipeline_jobs/<job_id>/`，最少包含 `run-state.json`、`input.json`、`result.json`（成功时）和 `job-report.json`。
-
-## `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
+更完整的状态分支、恢复策略和人工介入条件见 `docs/openclaw/openclaw-orchestration-flow.md`。
 
 ## 单篇文章总结后处理（可选使用独立 LLM）
 
@@ -83,10 +75,10 @@ summary-mcp
 
 相关能力：
 
-- `start_article_summary_job` / `get_article_summary_job_status` / `get_article_summary_job_result`（正式推荐的最小异步 job 路径）
-- `generate_article_summaries` MCP 工具（同步 debug 路径）
-- `scripts/run_article_summaries.py` CLI 辅助脚本
-- `scripts/run_article_summary_job.py` 后台 runner 入口
+- 正式路径：`start_article_summary_job` / `get_article_summary_job_status` / `get_article_summary_job_result`
+- 同步 debug：`generate_article_summaries`
+- CLI：`scripts/run_article_summaries.py`
+- 后台 runner：`scripts/run_article_summary_job.py`
 
 ## 校验 LLM 摘要结果