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

name, description

name	description
reader-digest-flow	编排 reader 项目的端到端 AI 日报流程。仅在用户要求运行/重跑日报、汇报候选、发布 Hugo 日报、沉淀选中文章或继续已有日报任务时使用；覆盖异步 MCP 任务、候选确认、发布、单篇摘要和 IMA 知识库上传。不要因验证、排障冲动或候选质量不佳自行重跑。

Reader Digest Flow

职责边界

本 Skill 负责：

• 通过 reader MCP 启动、观察和恢复日报任务；
• 向用户展示候选并保持稳定编号；
• 根据用户选择生成并发布 Hugo 日报；
• 对用户选中的文章生成知识笔记并编排 IMA 上传；
• 在每个副作用边界执行确认和结果验证。

本 Skill 不负责：

• 实现 reader 内部抓取、摘要、过滤或恢复逻辑；
• 通过手拼目录推导 Run 状态或 Artifact；
• 未经用户要求自行重跑 Pipeline；
• 未经用户确认发布日报或写入知识库；
• 直接维护关键词配置；关键词治理委托给 keyword-cleanup-review。

核心规则

1. 只按用户指令运行。 只有用户明确要求“跑日报”“重新跑”“再跑一次”时才启动新 Pipeline。验证、解释排序和排障默认读取已有 Run。
2. 一次对话绑定一个当前 Run。 以异步 Job 结果返回的 run_id 为稳定句柄；新 Run 产生新的候选编号体系，不混用历史编号。
3. 状态以 MCP 返回为准。 Agent 只根据顶层 status 和 recommended_action 分支；status_source、state_conflict 仅用于解释。
4. 路径以返回值为准。 使用 output_dir、artifact.path、delivery_output、report_output 和 written_paths；不要根据 run_id 手拼 outputs/...。
5. 候选编号保持稳定。 用户编号永远对应当前候选列表的原始顺序（1-based）；跨产物读取详情时按 URL 或完整 item_id 关联，不按数组位置关联。
6. 副作用必须授权。 用户确认 Hugo 文章后才能发布；用户确认 IMA 文章后才能生成并上传知识笔记。
7. 内容必须有来源。 日报和知识笔记只能基于当前 Run 的 article.plain_text、摘要、highlights 等 Artifact；不得使用通用知识补写原文没有的信息，也不为满足长度而扩写。

默认生产参数

用户未显式覆盖时使用：

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

• 默认只处理未读文章。
• include_read=true 仅在用户明确要求扩大到已读内容时使用。
• debug/test/validation 才允许 mark_read=false 或 debug_artifacts=true。
• 不随机生成文章数量；用户指定 limit 时按用户值执行。

正式流程

Phase 1：启动并观察日报 Job

正式生产入口统一为异步 MCP：

1. 调用 start_freshrss_pipeline_job；
2. 轮询 get_freshrss_pipeline_job_status；
3. status=success 后调用 get_freshrss_pipeline_job_result；
4. 保存返回的 run_id 和 Artifact 路径；
5. 使用 get_run_status、get_delivery_payload、get_run_report 读取业务状态和结果。

失败时：

1. 使用 get_run_status(run_id) 读取关联 Run；
2. 调用 inspect_resume_plan(run_id)；
3. recommended_action=resume 时启动并轮询异步 Resume Job；
4. recommended_action=read_terminal_result 时直接读取已有终态结果；
5. recommended_action=start_new_run 时停止并向用户报告，不自行新建 Run。

CLI 仅用于 MCP 不可用时的 fallback、debug 或人工排障，不是默认生产入口。具体调用序列见 references/flow.md。

Phase 2：汇报候选

• 使用当前 Run 返回的 Delivery Payload 或 digest brief Artifact；
• 按候选原始顺序从 1 编号，状态可显示为“已入选/待确认”，但不得重新分组编号；
• 每篇提供标题、来源、2-3 句摘要和筛选理由，避免原始 JSON dump；
• 用户质疑编号或排序时读取当前 Run 产物核对，不重新运行 Pipeline；
• 需要跨 Artifact 取详情时按 URL 或完整 item_id 交叉验证。

Feishu 输出不要使用 Markdown 表格，见 references/feishu-format-notes.md。

Phase 3：等待 Hugo 选择

• 等待用户明确选择要发布的文章；
• 用户编号映射到当前候选列表，不映射到 extracted 文件序号；
• 用户拒绝发布时立即停止当日日报后续流程，不劝说、不自动换一批；
• 用户明确要求重跑时才创建新 Run，并重新建立编号体系。

Phase 4：生成并发布 Hugo 日报

发布前读取 references/public-digest-example.md，按其最终页面结构生成：

• 今日概览
• 今日重点
• 趋势观察

每篇 今日重点 文章末尾必须添加 来源：[来源名](原文 URL)，来源链接跟随对应文章，不再生成独立的 延伸阅读 章节或重复链接。

仅发布用户在 Phase 3 选中的文章。公开页面不得出现 keep/review/drop、候选、待确认等内部状态。

写入 Hugo 后执行部署，并验证首页、日报列表页和当日详情页均可访问。命令和检查项见 references/flow.md。

Phase 5：等待 IMA 选择

Hugo 发布选择与知识沉淀选择相互独立。询问用户哪些文章值得长期保存：

• 仅处理用户明确选择的文章；
• 不把整份日报上传到 IMA；
• 本次选择本身即授权后续单篇摘要和 IMA 上传，不重复确认。

Phase 6：生成单篇知识笔记

对每篇选中文章：

1. 通过 URL/完整 item_id 找到对应 extracted Artifact；
2. 使用 start_article_summary_job(extracted_path=<返回的 Artifact 路径>, selected_ids=[<完整 item_id>])；
3. 轮询 get_article_summary_job_status，成功后读取 get_article_summary_job_result；
4. 只使用现有 article.plain_text，不重新抓取原 URL；
5. 使用返回的 written_paths 定位结果并检查 Markdown 内容。
6. extracted_path 必须传绝对路径（前缀 /home/ubuntu/zhu/github/reader/）：summary-mcp 工作目录是 /root/.hermes，相对路径会报 extracted_path does not exist。同一工具连续 3 次失败会触发 MCP 冷却（约 45-60s，报 MCP server 'reader' is unreachable），等待冷却后再重试，不要循环重试同一调用。

异步 MCP 不可用时才使用项目 CLI fallback。不要因为内容较短而引入原文之外的知识。

Phase 7：上传到 IMA

上传前按需读取：

• 格式规则：references/ima-format-quickref.md
• API 和上传步骤：references/ima-upload-api.md（含 -200 版本拦截修复）
• 凭证定位：references/ima-credential-chain.md
• 批量上传脚本：scripts/ima_upload_one.py（Python 编排，规避中文文件名 bash 引号问题）

硬规则：

• 使用完整文章标题作为文件名；
• 以 Markdown 文件 media_type=7 上传到 daily knowledge base；
• 保留原文 URL 和 Category，保证来源可追踪；
• 不使用 URL 导入或 Notes 类型替代知识库文件；
• 上传后验证目标知识库中存在对应条目；
• 失败时报告具体阶段，不无限重试。

关键词治理路由

只有用户明确要求“清理关键词”“词库治理”等操作时才触发关键词治理。Review bundle 和 Suggestions 生成委托给 keyword-cleanup-review，确认与 Apply 仍由当前编排层负责：

1. 生成 review bundle；
2. 生成规则层与可选语义层 Suggestions JSON；
3. 等待人工确认；
4. dry-run 后按精确 accept 参数 Apply。

reader-digest-flow 不直接编辑 term_aliases.json、term_stopwords.json 或兴趣配置。简要路由见 references/keyword-engine-maintenance.md。

环境坑位（本机部署）

• MCP 相对路径陷阱：summary-mcp 服务工作目录是 /root/.hermes，不是 reader 项目根。MCP 返回的 output_dir/artifact.path 是相对路径，直接传给 start_article_summary_job(extracted_path=...) 会报 extracted_path does not exist。传入前必须拼绝对路径前缀 /home/ubuntu/zhu/github/reader/。
• 提取失败不等于运行失败：status_counts.extract_failed 的条目（CONTENT_EXTRACTION_FAILED，retryable=false）跳过即可并如实汇报；失败文章常是推广/活动等低价值内容，不因此自行重跑。linked_run_status=partial 时先读 run-report 的 item 级 error 确认原因。
• 用户要求"重新跑一批"：候选质量低（用户主动提出）时重跑，应 include_read=true 并调高 limit（如 10），否则默认 include_read=false 会拉回同一批未读文章。重跑是新 Run，候选编号体系重新建立，汇报时提醒用户按新列表选择。

停止与人工介入

出现以下任一情况时停止自动流程并报告：

• 用户没有授权运行、发布或知识库写入；
• Job/Run 返回不可恢复，或连续恢复失败；
• Payload、候选 ID 或 Artifact 之间无法可靠关联；
• 生成内容缺少可追踪来源；
• Hugo 部署验证失败；
• IMA 凭证、目标知识库或上传结果无法验证。

Reference 路由

• references/flow.md：具体 MCP 调用序列、候选映射（含 extracted_path 绝对路径、候选≠文件名顺序）、Hugo 发布和 IMA 主步骤。
• references/content-extraction.md：FreshRSS 内容来源与 plain_text 质量判断。
• references/public-digest-example.md：可直接参考的 Hugo 最终页面结构。
• references/feishu-format-notes.md：Feishu 输出格式限制。
• references/ima-format-quickref.md：IMA Markdown 格式规则。
• references/ima-upload-api.md：IMA Markdown 文件上传 API（含 -200 版本拦截修复）。
• references/ima-credential-chain.md：IMA 凭证与知识库配置定位。
• references/keyword-engine-maintenance.md：关键词治理 Skill 路由。
• scripts/ima_upload_one.py：单篇 Markdown 上传 daily 知识库的完整 Python 脚本（preflight→重名→create_media→COS→add_knowledge）。