177 lines
8.0 KiB
Markdown
177 lines
8.0 KiB
Markdown
---
|
||
name: reader-digest-flow
|
||
description: 编排 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；不得使用通用知识补写原文没有的信息，也不为满足长度而扩写。
|
||
|
||
## 默认生产参数
|
||
|
||
用户未显式覆盖时使用：
|
||
|
||
```json
|
||
{
|
||
"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`，按其最终页面结构生成：
|
||
|
||
- `今日概览`
|
||
- `今日重点`
|
||
- `趋势观察`
|
||
- `延伸阅读`
|
||
|
||
仅发布用户在 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 内容。
|
||
|
||
异步 MCP 不可用时才使用项目 CLI fallback。不要因为内容较短而引入原文之外的知识。
|
||
|
||
### Phase 7：上传到 IMA
|
||
|
||
上传前按需读取：
|
||
|
||
- 格式规则：`references/ima-format-quickref.md`
|
||
- API 和上传步骤：`references/ima-upload-api.md`
|
||
- 凭证定位：`references/ima-credential-chain.md`
|
||
|
||
硬规则：
|
||
|
||
- 使用完整文章标题作为文件名；
|
||
- 以 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`。
|
||
|
||
## 停止与人工介入
|
||
|
||
出现以下任一情况时停止自动流程并报告：
|
||
|
||
- 用户没有授权运行、发布或知识库写入；
|
||
- Job/Run 返回不可恢复，或连续恢复失败；
|
||
- Payload、候选 ID 或 Artifact 之间无法可靠关联；
|
||
- 生成内容缺少可追踪来源；
|
||
- Hugo 部署验证失败；
|
||
- IMA 凭证、目标知识库或上传结果无法验证。
|
||
|
||
## Reference 路由
|
||
|
||
- `references/flow.md`：具体 MCP 调用序列、候选映射、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。
|
||
- `references/ima-credential-chain.md`：IMA 凭证与知识库配置定位。
|
||
- `references/keyword-engine-maintenance.md`：关键词治理 Skill 路由。
|