---
name: article-deep-summary
description: 从单篇提取的文章中生成深度结构化知识笔记。当用户需要对存储在 *.extracted.json 文件中的文章 plain_text 内容进行深度摘要、提炼或创建知识笔记时使用。
---

# 文章深度摘要

当用户拥有已提取的文章文件并希望生成深度知识笔记时使用此技能——不是简短的摘要卡片，而是包含核心结论、论点、方法、细节和可复用洞见的结构化提炼。

此技能**不适用于**验证或修复已有摘要（请使用 `llm-summary-review`），也不适用于关键词索引清理（请使用 `keyword-cleanup-review`）。

## 功能说明

- 读取包含 `plain_text` 的已提取文章 JSON 文件
- 使用专用的文章摘要提示词调用 LLM
- 根据 `ArticleSummaryResult` 模式验证 LLM 输出
- 渲染结构化的中文 Markdown 知识笔记

## 输入

典型文件：

- 已提取的文章 JSON：`outputs/freshrss/rerun/<run_id>/extracted/item-XX.extracted.json`（单篇）或包含 `results` 数组的批量文件
- 提示词模板：`outputs/prompts/article-summary-prompt.txt`

## 工作流程

1. 确定目标提取文件和需要摘要的条目 ID。

2. 通过 CLI 运行文章摘要工作流：

```bash
python -m summary_mcp.workflows.article_summary \
  --extracted <extracted_path> \
  --selected-ids <item_id> \
  --output-dir <output_dir>
```

或调用 MCP 工具 `generate_article_summaries`，参数如下：

- `extracted_path`：已提取的 JSON 文件路径
- `selected_ids`：条目 ID 字符串数组（传入空数组可摘要全部条目）
- `output_dir`：（可选）Markdown 输出目录

3. 工作流内部流程：
   - 解析 LLM 配置（`ARTICLE_SUMMARY_*` 环境变量，未设置时回退到 `LLM_*`）
   - 使用文章摘要提示词和验证器调用 `run_loop_payload`
   - 验证失败时最多重试 2 次

4. 在指定的输出目录中检查生成的 Markdown 文件。

## 输出模式

LLM 返回匹配 `ArticleSummaryResult` 的 JSON：

| 字段 | 类型 | 说明 |
|---|---|---|
| `title` | string | 文章标题 |
| `url` | HttpUrl | 文章 URL |
| `core_conclusion` | string | 作者核心结论，1-2 句话 |
| `main_argument` | string | 主要论点或论题，可为多句 |
| `key_methods` | string[] | 关键方法、机制或技术 |
| `important_details` | string[] | 值得注意的细节、数据点或案例 |
| `reusable_insights` | string[] | 可迁移到其他场景的可复用洞见 |
| `keywords` | string[] | 具体实体——工具名称、框架、方法 |
| `topics` | string[] | 更高层次的主题标签 |
| `category` | enum | 取值之一：`资讯` `方法论` `工具实践` `观点评论` |
| `worth_keeping` | bool | 该文章是否值得长期保留 |
| `reason` | string | 一句话说明保留理由 |

验证器强制约束：

- `keywords` 和 `topics` 不得重叠
- `keywords` 聚焦具体实体；`topics` 聚焦抽象主题
- `category` 必须为四个允许值之一

## Markdown 输出

每篇文章生成一个 `.md` 文件，包含以下章节：

- 核心结论
- 主要论点
- 关键方法 / 机制
- 重要细节
- 可复用启发
- 关键词
- 主题

## LLM 配置

专用环境变量（未设置时回退到主 `LLM_*` 变量）：

- `ARTICLE_SUMMARY_LLM_API_URL`
- `ARTICLE_SUMMARY_LLM_API_KEY`
- `ARTICLE_SUMMARY_LLM_MODEL`

## 代码实现

相关代码：

- 工作流：`src/summary_mcp/workflows/article_summary.py`
- 验证器：`src/summary_mcp/validators/article_summary.py`
- 数据模型：`src/summary_mcp/models/article_summary_result.py`
- 提示词：`outputs/prompts/article-summary-prompt.txt`
- MCP 工具：`generate_article_summaries`，位于 `src/summary_mcp/server.py`

## 何时停止

满足以下条件之一时停止：

- 所有请求条目的 Markdown 知识笔记已生成
- 工作流报告反复验证失败，应由用户决定后续操作
- 用户要求手动检查中间结果