reader/skills/reader-digest-flow/references/flow.md

Reader Digest Flow 操作参考

本文件承载 reader-digest-flow 的具体执行步骤。正式行为边界以 ../SKILL.md 为准。

1. 日报 Pipeline

默认参数

{
  "limit": 7,
  "include_read": false,
  "mark_read": true,
  "debug_artifacts": false,
  "timeout_seconds": 60,
  "max_retries": 2
}

正式调用序列

start_freshrss_pipeline_job
→ get_freshrss_pipeline_job_status
→ get_freshrss_pipeline_job_result
→ get_run_status
→ get_delivery_payload / get_run_report

状态动作：

• running：按合理间隔继续轮询；
• success：读取结果，保存 run_id；
• failed：读取关联 Run 并执行 Resume Plan；
• partial：优先检查 Run Report、Artifact 和 Recovery 信息。

恢复序列：

inspect_resume_plan
→ recommended_action=resume
→ start_resume_job
→ get_resume_job_status
→ get_resume_job_result

如果建议为 read_terminal_result，直接读取结果；如果为 start_new_run，停止并等待用户决定。

不要根据 run_id 拼目录。后续只消费调用返回的 output_dir、artifact.path、delivery_output、report_output。

2. 候选汇报与选择

优先使用当前 Run 的 digest brief Artifact；不可用时使用 get_delivery_payload 返回的候选。

展示规则：

1. 使用候选数组原始顺序并从 1 编号；
2. 不因 keep/review 分组而重新编号；
3. 每篇展示标题、来源、摘要和判断理由；
4. 用户编号只映射当前候选数组；
5. 跨 Artifact 读取详情时按 URL 或完整 item_id 匹配。

不要按 summary-batch、item-XX 和候选数组的相同位置推断它们是同一篇文章。

extracted 文件与候选编号错位（实测 2026-07-31）

• digest-brief.json 的 top_candidates 没有 item_id 字段，只有 url；
• extracted/item-XX.extracted.json 的文件名序号与候选编号可能不一致（实例：候选2 = item-05、候选3 = item-02）；
• 正确做法：用 URL 交叉匹配（归一化 %3D→= 后逐条比对），或用完整 item_id（从 candidate-batch.json 的 items[i].item_id 按候选数组顺序取）在 extracted 文件里反查；两者都能验证时优先 item_id。

3. Hugo 日报

用户确认发布文章后：

1. 读取 public-digest-example.md；
2. 仅使用用户选中的文章生成公开内容；
3. 写入 Hugo 当日页面；
4. 前台执行部署，避免把构建日志作为聊天通知；
5. 验证首页、列表页和详情页。

当前部署位置：

/home/ubuntu/zhu/apps/hugo-site/content/daily/YYYY-MM-DD/index.md

验证至少覆盖：

http://127.0.0.1:14322/
http://127.0.0.1:14322/daily/
http://127.0.0.1:14322/daily/YYYY-MM-DD/

页面不存在时检查源文件、构建结果、容器状态和页面日期。需要 Docker/Hugo 深度排障时再读取部署项目自己的文档，不把历史事故规则复制回主 Skill。

4. 单篇知识笔记

用户确认 IMA 文章后：

1. 从候选中取得 URL 和完整 item_id；
2. 从 Run Artifact 中找到匹配的 extracted 文件；
3. 交叉验证 article.item_id 或 URL；
4. 对每个单篇文件调用 start_article_summary_job(extracted_path=<返回的 Artifact 路径>, selected_ids=[<完整 item_id>])；
5. selected_ids 传完整、非空、去除 cand: 前缀后的 item_id；
6. 从 Job 结果的 written_paths 读取 Markdown。

⚠️ extracted_path 必须用绝对路径

summary-mcp 进程的工作目录是 /root/.hermes（不是 reader 项目根）。传相对路径（如 outputs/freshrss/...）会直接报 extracted_path does not exist。必须传绝对路径：

/home/ubuntu/zhu/github/reader/outputs/freshrss/rerun/<run_dir>/extracted/item-XX.extracted.json

⚠️ 候选编号 ≠ extracted 文件名顺序

候选数组顺序与 extracted 文件名（item-01…item-07）不一定对齐（实测候选2 落在 item-05）。digest-brief.json 的候选没有 item_id 字段，只有 URL。可靠匹配方法：

1. 从 candidate-batch.json 取每项完整 item_id（在 candidate 嵌套对象里，顶层 item_key 只是 item-XX 文件名序号）；
2. 或按 URL 匹配：归一化（%3D→=）后与每个 extracted 文件的 article.url / article.canonical_url 比对；
3. 绝不要按候选位置对应 extracted 文件序号。

def norm(u): return u.replace('%3D','=').replace('%3d','=').strip()
# 对每个 extracted 文件取 norm(article.url)，与候选 norm(url) 精确比对

正式序列：

start_article_summary_job
→ get_article_summary_job_status
→ get_article_summary_job_result

内容依据是 extracted Artifact 中的 article.plain_text。不得重新抓取原 URL，不得使用原文之外的知识扩写。

CLI 仅在异步 MCP 不可用或人工排障时使用：

python scripts/run_article_summaries.py \
  --extracted <returned-extracted-path> \
  --ids <full-item-id> \
  --output-dir <explicit-output-dir>

5. IMA 上传

用户在知识沉淀阶段的文章选择即为上传授权。

执行顺序：

1. 检查生成的 Markdown 与来源；
2. 文件名规范化为 <完整文章标题>.md；
3. 确认目标为 daily knowledge base；
4. 执行 preflight、create_media、COS upload、add_knowledge；
5. 验证知识库条目存在。

上传格式与 API 参数分别见：

• ima-format-quickref.md
• ima-upload-api.md
• ima-credential-chain.md

失败时记录发生在 preflight、create_media、COS upload 或 add_knowledge 的具体阶段。不要把失败的 Markdown 改写成 URL 导入或 Notes 类型来绕过错误。

6. CLI fallback 原则

CLI 仅在以下场景使用：

• MCP 服务不可用；
• Tool transport/launch 失败且无法取得有效 Job；
• 用户明确要求本地调试；
• 人工排障需要直接检查脚本输出。

如果已取得 job_id 或 run_id，先查询真实状态，避免因响应超时重复启动任务。