276 lines
5.9 KiB
Markdown
276 lines
5.9 KiB
Markdown
# Content Extract MCP MVP 归档记录
|
||
|
||
## 1. 归档目的
|
||
|
||
本文档用于记录当前 MVP 阶段已经完成的能力、实现边界、验证结果和已知限制。
|
||
|
||
当前结论：MCP 这一层不再负责生成摘要，而是只负责将网页或标准化 `item` 提取为结构化文章内容，再把结果交给上层 LLM 做摘要、分类和知识判断。
|
||
|
||
---
|
||
|
||
## 2. 当前 MVP 的目标与边界
|
||
|
||
当前 MVP 实现的是阅读流中的第 2 步前半段：
|
||
|
||
`RSS / 页面来源 -> Content Extract MCP -> 结构化文章 JSON -> LLM 摘要`
|
||
|
||
### 2.1 当前 MCP 负责的事情
|
||
|
||
- 接收单个 URL
|
||
- 接收标准化 `item`
|
||
- 抓取网页 HTML
|
||
- 抽取标题
|
||
- 抽取正文纯文本
|
||
- 返回结构化文章对象
|
||
- 返回质量标记和结构化错误
|
||
|
||
### 2.2 当前 MCP 不负责的事情
|
||
|
||
- RSS 聚合
|
||
- 摘要生成
|
||
- 主题分类
|
||
- 价值判断
|
||
- 规则过滤
|
||
- 知识库入库
|
||
- 推送通知
|
||
|
||
这意味着：
|
||
|
||
当前实现已经把“内容提取”这一层从整条流水线中独立出来，成为一个可被 LLM 或自动化编排系统复用的能力模块。
|
||
|
||
---
|
||
|
||
## 3. 当前实现的服务定位
|
||
|
||
当前项目虽然目录名仍然沿用了 `summary_mcp`，但实际职责已经调整为：
|
||
|
||
`Content Extraction MCP`
|
||
|
||
也就是：
|
||
|
||
- MCP 负责内容提取
|
||
- LLM 负责总结摘要
|
||
- 规则引擎负责过滤
|
||
- sink 负责入库与推送
|
||
|
||
这比早期“让 MCP 直接产出摘要”的思路更合理，因为职责边界更清楚，也更利于后续替换模型和 prompt。
|
||
|
||
---
|
||
|
||
## 4. 当前工具接口
|
||
|
||
当前 MCP 暴露两个 tool：
|
||
|
||
- `extract_url_content`
|
||
- `extract_item_content`
|
||
|
||
### 4.1 `extract_url_content`
|
||
|
||
用途：
|
||
|
||
- 直接输入 URL
|
||
- 适合单条文章调试
|
||
- 适合上层 Agent 在没有标准化 `item` 时直接调用
|
||
|
||
### 4.2 `extract_item_content`
|
||
|
||
用途：
|
||
|
||
- 输入标准化 `item`
|
||
- 适合与上游 RSS 聚合层对接
|
||
- 保留 `item_id`、`source_id` 等追踪信息
|
||
|
||
---
|
||
|
||
## 5. 当前输出结构
|
||
|
||
当前 MCP 输出的核心对象是结构化文章，而不是摘要结果。
|
||
|
||
关键字段包括：
|
||
|
||
- `extract_id`
|
||
- `item_id`
|
||
- `source_id`
|
||
- `url`
|
||
- `title`
|
||
- `author`
|
||
- `published_at`
|
||
- `language`
|
||
- `content_kind`
|
||
- `plain_text`
|
||
- `quality_flags`
|
||
- `metadata`
|
||
- `pipeline_state`
|
||
|
||
其中：
|
||
|
||
- `plain_text` 是给上层 LLM 的核心输入
|
||
- `quality_flags` 用于后续过滤参考
|
||
- `metadata` 里包含当前提取来源和抽取器信息
|
||
|
||
---
|
||
|
||
## 6. 当前代码结构
|
||
|
||
当前目录结构如下：
|
||
|
||
```text
|
||
src/summary_mcp/
|
||
server.py
|
||
core/
|
||
content_loader.py
|
||
errors.py
|
||
extractor.py
|
||
mapper.py
|
||
normalizer.py
|
||
pipeline.py
|
||
quality_checker.py
|
||
summarizer.py
|
||
models/
|
||
document.py
|
||
item.py
|
||
summary_io.py
|
||
```
|
||
|
||
### 6.1 当前核心模块职责
|
||
|
||
- `server.py`
|
||
- MCP 服务入口
|
||
- 注册 `extract_url_content` / `extract_item_content`
|
||
|
||
- `normalizer.py`
|
||
- 统一 `url` 输入和 `item` 输入
|
||
|
||
- `content_loader.py`
|
||
- 负责正文来源选择和回源抓取
|
||
|
||
- `extractor.py`
|
||
- 负责标题提取和正文抽取
|
||
|
||
- `quality_checker.py`
|
||
- 负责生成质量标记
|
||
|
||
- `mapper.py`
|
||
- 负责将结果映射为结构化文章对象
|
||
|
||
- `pipeline.py`
|
||
- 负责串联整条提取流程
|
||
|
||
### 6.2 当前遗留项
|
||
|
||
- `core/summarizer.py` 仍保留在仓库中，但已经不再属于当前 MCP 的主流程
|
||
- 包名 `summary_mcp` 和项目名 `summary-mcp` 仍然沿用了早期命名，后续建议重命名为更符合职责的名称
|
||
|
||
---
|
||
|
||
## 7. 当前技术选型
|
||
|
||
当前 MVP 使用：
|
||
|
||
- Python
|
||
- MCP Python SDK (`FastMCP`)
|
||
- `httpx` 进行网络抓取
|
||
- `trafilatura` 进行正文抽取
|
||
- `beautifulsoup4` 作为 HTML 解析和兜底手段
|
||
- `pydantic` 定义输入输出模型
|
||
|
||
设计原则是：
|
||
|
||
- 外层 MCP
|
||
- 内层 extraction core
|
||
- 上层 LLM 单独负责总结和判断
|
||
|
||
---
|
||
|
||
## 8. 当前验证结果
|
||
|
||
### 8.1 语法与结构验证
|
||
|
||
已执行：
|
||
|
||
- `python -m compileall src`
|
||
|
||
结果：
|
||
|
||
- 当前 Python 源码可以通过语法编译检查
|
||
|
||
### 8.2 真实 URL 提取验证
|
||
|
||
已使用以下参考文章进行了真实提取测试：
|
||
|
||
- <https://shawnxie.top/blogs/tools/read-flow-2026.html>
|
||
|
||
验证结果：
|
||
|
||
- URL 抓取成功
|
||
- 标题提取成功
|
||
- 正文抽取成功
|
||
- 输出返回结构化 JSON
|
||
- `quality_flags` 正常生成
|
||
- `metadata` 中记录了 `content_source=fetched_html` 和 `extractor=trafilatura`
|
||
|
||
输出文件：
|
||
|
||
- `outputs/read-flow-2026.extracted.json`
|
||
|
||
### 8.3 LLM 摘要链路验证
|
||
|
||
已基于提取结果生成：
|
||
|
||
- `outputs/llm-summary-prompt.txt`
|
||
- `outputs/result.json`
|
||
|
||
验证结果：
|
||
|
||
- LLM 可基于提取结果生成结构化摘要 JSON
|
||
- 在 prompt 收紧后，`summary` 长度和 `keywords/topics` 区分已达到预期
|
||
|
||
---
|
||
|
||
## 9. 当前 MVP 已经达成的结论
|
||
|
||
当前 MVP 已经证明以下链路是成立的：
|
||
|
||
1. 参考文章 URL 可以被 MCP 成功提取为结构化内容
|
||
2. 提取结果可以独立保存为 JSON 文件
|
||
3. JSON 文件可以被上层 LLM 消费
|
||
4. LLM 可以输出稳定的摘要结构
|
||
5. “MCP 负责提取，LLM 负责摘要” 这一职责拆分是可行的
|
||
|
||
这意味着：
|
||
|
||
当前 MVP 的核心目标已经完成。
|
||
|
||
---
|
||
|
||
## 10. 已知限制
|
||
|
||
当前实现仍存在以下限制：
|
||
|
||
- 还没有正式的 JSON Schema 校验器去验证 LLM 输出
|
||
- 还没有批量处理能力
|
||
- 还没有与 RSS 聚合层正式对接
|
||
- 还没有接规则过滤器
|
||
- 还没有接知识库 sink
|
||
- 还没有移除遗留的 `summarizer.py`
|
||
- 项目命名和职责命名仍存在历史包袱
|
||
|
||
---
|
||
|
||
## 11. 下一阶段建议
|
||
|
||
后续建议按以下顺序推进：
|
||
|
||
1. 为 LLM 输出增加 schema 校验
|
||
2. 将提取结果与摘要结果串成标准化流水线
|
||
3. 接入 RSS 聚合层
|
||
4. 引入规则过滤
|
||
5. 接入知识库 sink 或 webhook
|
||
6. 最后再考虑与 OpenClaw 的进一步编排整合
|
||
|
||
---
|
||
|
||
## 12. 当前阶段一句话归档结论
|
||
|
||
当前 MVP 已经完成“内容提取 MCP”这一独立能力层：能够将文章 URL 或标准化 item 提取为结构化 JSON，并稳定交给上层 LLM 做摘要与后续处理。
|