feat: add keyword cleanup docs, skill updates, and delivery compatibility fix

2026-04-14 09:51:57 +08:00
parent a06f2a1d08
commit e3663f681d
5 changed files with 1642 additions and 0 deletions
@@ -0,0 +1,163 @@
+# reader MCP workflow service formalization summary (2026-04-07)
+
+## Overview
+
+On 2026-04-07, the reader project was formally advanced from a script-first integration model into a reader-centric MCP workflow service model.
+
+The key shift is:
+
+- before: OpenClaw primarily relied on long CLI / exec flows and direct output-path stitching
+- now: reader exposes a formal workflow-oriented MCP surface with run-state, status queries, result reads, and minimal recovery
+
+This document records the main outcomes and commits for the first formalization phase.
+
+---
+
+## Completed capability set
+
+### 1. Run-state persistence
+
+Commit:
+
+- `72a6853` — `Add run-state persistence for FreshRSS pipeline`
+
+Delivered:
+
+- `run-state.json`
+- `RunState / StageState / ArtifactRecord`
+- stage-level state persistence for the FreshRSS pipeline
+
+### 2. Architecture / implementation docs
+
+Commit:
+
+- `7563aa8` — `docs: add reader MCP architecture and implementation plan`
+
+Delivered:
+
+- architecture design
+- implementation plan
+- TODO-driven collaboration model
+
+### 3. MCP run-status query tools
+
+Commit:
+
+- `d9173fb` — `feat: add MCP run status query tools`
+
+Delivered:
+
+- `get_run_status`
+- `list_runs`
+- `list_run_artifacts`
+
+### 4. MCP result-read tools
+
+Commit:
+
+- `4a02894` — `Add MCP delivery payload and run report queries`
+
+Delivered:
+
+- `get_delivery_payload`
+- `get_run_report`
+
+### 5. Minimal resume design
+
+Commit:
+
+- `d91cdbc` — `docs: narrow resume_run minimal recovery design`
+
+Delivered:
+
+- narrowed design for `resume_run`
+- explicit supported / unsupported recovery points
+
+### 6. Minimal `resume_run`
+
+Commit:
+
+- `c622bc6` — `Implement minimal resume_run for freshrss runs`
+
+Delivered:
+
+- minimal `resume_run`
+- supports only freshrss runs with `run-state.json`
+- supports only recent resumable points
+- explicitly rejects `fetch_feed` and `extract_articles`
+
+### 7. Formal handoff / workflow docs
+
+Commits:
+
+- `4f219ef` — `docs: formalize reader MCP workflow service handoff`
+- `2df0af5` — `docs: add openclaw orchestration flow for reader MCP`
+
+Delivered:
+
+- formal handoff aligned to actual implementation
+- OpenClaw orchestration runbook
+- explicit rule that OpenClaw should stop hand-stitching reader paths in the normal production flow
+
+---
+
+## Current formal MCP workflow surface
+
+The current reader MCP workflow surface now includes:
+
+- `run_freshrss_openclaw_pipeline`
+- `get_run_status`
+- `list_runs`
+- `list_run_artifacts`
+- `get_delivery_payload`
+- `get_run_report`
+- `resume_run` (minimal version)
+
+---
+
+## Current boundary
+
+reader is now the upstream workflow engine for:
+
+- FreshRSS pull
+- extraction
+- summary
+- filter
+- payload generation
+- run-state persistence
+- result read
+- minimal recovery
+
+OpenClaw / skill remains responsible for:
+
+- digest markdown generation
+- Hugo publishing
+- chat reporting
+- user confirmation
+- IMA orchestration
+
+---
+
+## Current limitations
+
+The first formalization phase is complete, but some constraints remain:
+
+- `resume_run` is still minimal and does not support arbitrary stage re-entry
+- historical runs without `run-state.json` are not formally recoverable
+- some very old runs may still require conservative artifact/path discovery
+- `rerun_stage` is not implemented
+- deeper runtime consolidation of `run_freshrss_openclaw_pipeline` can still be improved later
+
+---
+
+## Practical conclusion
+
+The reader project should now be treated as a formal MCP workflow service rather than as a long-running CLI-first integration point.
+
+For normal production orchestration:
+
+- start via MCP
+- observe via MCP status tools
+- read results via MCP result tools
+- use `resume_run` only within the documented minimal recovery range
+- keep CLI for debug / fallback only