feat: add async job entrypoint for freshrss pipeline

docs/openclaw/openclaw-handoff.md

@@ -27,21 +27,27 @@ This repository should **not** take over downstream orchestration responsibiliti
 
 ## Production Entrypoint
 
-reader 当前正式工作流服务入口是 MCP tool:
+reader 当前正式工作流服务启动入口是 MCP tool:
 
-- `run_freshrss_openclaw_pipeline`
+- `start_freshrss_pipeline_job`
 
-It starts the only formally supported workflow today: `freshrss_daily_digest`.
+OpenClaw 应先拿到 `job_id`，轮询 job 状态，再在成功后读取 `run_id` 作为正式后续句柄。
 
-OpenClaw should treat the returned `run_id` as the only stable handle for follow-up reads. Do not hand-build `outputs/freshrss/rerun/...` paths in OpenClaw.
+`run_freshrss_openclaw_pipeline` 仍保留，但定位是同步 debug / fallback 路径，而不是正式生产启动入口。
+
+OpenClaw should treat the returned `run_id` from `get_freshrss_pipeline_job_result` as the only stable handle for follow-up reads. Do not hand-build `outputs/freshrss/rerun/...` paths in OpenClaw.
+
+Job state is written under `outputs/freshrss/pipeline_jobs/<job_id>/` and will minimally contain `run-state.json`, `input.json`, `result.json` on success, and `job-report.json`.
 
 ## Supported MCP Tools
 
-Current MCP tools: 14 total, including the FreshRSS workflow set plus article-summary async job tools.
+Current MCP tools: 17 total, including the FreshRSS workflow set plus async job tools for both the main pipeline and article-summary flow.
 
 Workflow service tools:
 
-- `run_freshrss_openclaw_pipeline`
+- `start_freshrss_pipeline_job`
+- `get_freshrss_pipeline_job_status`
+- `get_freshrss_pipeline_job_result`
 - `get_run_status`
 - `list_runs`
 - `list_run_artifacts`
@@ -57,6 +63,7 @@ Article-summary tools:
 
 Single-step / debug tools:
 
+- `run_freshrss_openclaw_pipeline`（同步模式，仅适合 debug / fallback）
 - `extract_url_content`
 - `extract_item_content`
 - `filter_summary_result`
@@ -118,12 +125,14 @@ summary-mcp
 
 Recommended production path:
 
-1. Call `run_freshrss_openclaw_pipeline` and persist the returned `run_id`
-2. Use `get_run_status(run_id)` as the authoritative run-state read for status, stage, artifacts, and recovery
-3. Use `list_runs(...)` when OpenClaw needs recent-run discovery or high-level inspection
-4. Use `list_run_artifacts(run_id)` when OpenClaw needs to inspect what this run actually produced
-5. Use `get_delivery_payload(run_id)` and `get_run_report(run_id)` as the formal result-reading APIs
-6. Use `resume_run(run_id)` only when the run falls inside the minimal supported resume scope
+1. Call `start_freshrss_pipeline_job` and persist the returned `job_id`
+2. Poll `get_freshrss_pipeline_job_status(job_id)` until `status` becomes `success` or `failed`
+3. On success, call `get_freshrss_pipeline_job_result(job_id)` and persist the returned `run_id`
+4. Use `get_run_status(run_id)` as the authoritative run-state read for status, stage, artifacts, and recovery
+5. Use `list_runs(...)` when OpenClaw needs recent-run discovery or high-level inspection
+6. Use `list_run_artifacts(run_id)` when OpenClaw needs to inspect what this run actually produced
+7. Use `get_delivery_payload(run_id)` and `get_run_report(run_id)` as the formal result-reading APIs
+8. Use `resume_run(run_id)` only when the run falls inside the minimal supported resume scope
 
 OpenClaw should not directly derive or hardcode:
 
@@ -154,8 +163,9 @@ Recommended semantics:
 - Use `mark_read=false` only for debug, test, or validation runs.
 - Keep `debug_artifacts=false` for routine production runs.
 - Set `debug_artifacts=true` only when troubleshooting a bad batch.
-- Treat the returned `run_id` as the stable identifier for all follow-up MCP reads.
+- Treat the returned `job_id` as the startup handle, and the later `run_id` from `get_freshrss_pipeline_job_result` as the stable identifier for all follow-up run reads.
 - If no real `openclaw-delivery-payload.json` was produced, OpenClaw should stop instead of generating a digest from placeholders or examples.
+- Use `run_freshrss_openclaw_pipeline` only when a synchronous debug / fallback path is explicitly needed.
 
 ## Formal Capability Boundary
 
@@ -163,10 +173,12 @@ reader 当前正式 MCP workflow service 的边界如下：
 
 - formal workflow: only `freshrss_daily_digest`
 - run truth: every FreshRSS run writes `run-state.json`
+- main production start path: `start_freshrss_pipeline_job` / `get_freshrss_pipeline_job_status` / `get_freshrss_pipeline_job_result`
 - state query tools: `get_run_status`, `list_runs`, `list_run_artifacts`
 - result read tools: `get_delivery_payload`, `get_run_report`
 - `digest-brief.json` is generated and registered as an artifact, but there is no standalone `get_digest_brief` tool yet
-- `run_freshrss_openclaw_pipeline` and `resume_run` are synchronous MCP calls today; there is no background queue / worker model for the FreshRSS daily workflow yet
+- `run_freshrss_openclaw_pipeline` is still supported, but only as a synchronous debug / fallback path
+- the FreshRSS daily workflow now has a minimal background job model backed by a detached runner process, not a full queue / worker system
 - article summary now has a minimal asynchronous job model with `start_article_summary_job` / `get_article_summary_job_status` / `get_article_summary_job_result`
 - `generate_article_summaries` is still supported, but it is a synchronous debug path and outside the formal `resume_run` scope
 
@@ -175,10 +187,11 @@ Historical compatibility note:
 - `get_run_status` / `list_runs` / `list_run_artifacts` can still infer basic state for older run directories without `run-state.json`
 - `resume_run` does **not** support those inferred historical runs; it requires a valid `run-state.json`
 
-## What The Tool Returns
+## What The Async Job Returns
 
-Primary return fields from `run_freshrss_openclaw_pipeline`:
+Primary return fields from `get_freshrss_pipeline_job_result`:
 
+- `job_id`
 - `run_id`
 - `output_dir`
 - `raw_output`
@@ -189,7 +202,6 @@ Primary return fields from `run_freshrss_openclaw_pipeline`:
 - `delivered_count`
 - `marked_read_count`
 - `status_counts`
-- `delivery_payload`
 - `keyword_index`
 
 Optional:
@@ -197,6 +209,8 @@ Optional:
 - `items`
   - returned only when `include_item_reports=true`
 
+`run_freshrss_openclaw_pipeline` still returns the same synchronous payload for debug / fallback use.
+
 Follow-up structured reads should use MCP tools rather than re-reading these files directly.
 
 ## Minimal Output Files