Add detailed step comments to _process_item helper

src/summary_mcp/workflows/freshrss_pipeline.py

@@ -89,6 +89,7 @@ def _process_item(
 ) -> dict[str, Any]:
     # 处理单条 item：提取 -> LLM 摘要 -> 规则过滤 -> 候选构建
     # 返回 item_report dict；delivered 时额外携带 _candidate/_external_id 供调用方解包
+    # 步骤 1：确定各中间文件路径（debug_artifacts=False 时大部分路径为 None，不写盘）
     item_key = f"item-{index:02d}"
     item_path = _maybe_path(debug_artifacts, resolved_output_dir / "items" / f"{item_key}.item.json")
     extracted_path = resolved_output_dir / "extracted" / f"{item_key}.extracted.json"
@@ -100,6 +101,7 @@ def _process_item(
     if item_path is not None:
         _save_json(item_path, item.model_dump(mode="json"))
 
+    # 步骤 2：初始化 item_report，记录基础元信息；debug 模式下附加各中间文件路径
     item_report: dict[str, Any] = {
         "item_key": item_key,
         "item_id": item.item_id,
@@ -118,6 +120,7 @@ def _process_item(
             "openclaw_candidate": str(openclaw_path) if openclaw_path else None,
         }
 
+    # 步骤 3：内容提取（RSS 内联内容 or 回源抓取）；extracted.json 始终写盘
     extraction = extract_content(ExtractionInput(item=item))
     extracted_payload = extraction.model_dump(mode="json")
     if extracted_path is not None:
@@ -127,6 +130,7 @@ def _process_item(
         item_report["error"] = extraction.error.model_dump(mode="json") if extraction.error else None
         return item_report
 
+    # 步骤 4：LLM 摘要循环，失败时最多重试 max_retries 次
     item_report["status"] = "extracted"
     summary_exit_code, summary_payload, summary_report = run_loop_payload(
         extracted_payload=extracted_payload,
@@ -144,6 +148,7 @@ def _process_item(
             item_report["summary_errors"] = summary_report.errors
         return item_report
 
+    # 步骤 5：规则引擎过滤，产出 keep/review/drop 决策及 digest_rank
     summary = LlmSummaryResult.model_validate(summary_payload)
     decision = evaluate_filter_rules(
         FilterInput(item=item, article=extraction.article, summary=summary, context=filter_context),
@@ -152,6 +157,7 @@ def _process_item(
     if filter_path is not None:
         _save_json(filter_path, decision.model_dump(mode="json"))
 
+    # 步骤 6：构建 ArticleCandidateRecord 和 OpenClawCandidateInput
     record = build_article_candidate_record(
         summary=summary,
         article=extraction.article,
@@ -176,6 +182,7 @@ def _process_item(
     if openclaw_path is not None:
         _save_json(openclaw_path, openclaw_input.model_dump(mode="json"))
 
+    # 步骤 7：标记 delivered，附加临时键 _candidate/_external_id 供主函数解包后加入投递列表
     item_report["status"] = "delivered"
     item_report["selection_decision"] = decision.decision
     item_report["candidate_id"] = openclaw_input.candidate_id