first commit

2026-03-24 17:01:35 +08:00
commit 1dfae8ca19
68 changed files with 3898 additions and 0 deletions
@@ -0,0 +1,378 @@
+# Content Extract MCP Service 设计草案
+
+## 1. 文档目的
+
+本文档用于定义当前仓库中已经落地的 MCP 服务设计，即“内容提取 MCP”。
+
+目标是明确：
+
+- 这个 MCP 服务当前真正负责什么
+- 它对外暴露哪些 tool
+- 每个 tool 的输入输出结构是什么
+- validator 与 LLM 摘要如何接在 MCP 之后
+- 当前 MVP 已完成到哪一层
+
+这份文档描述的是当前真实实现，而不是早期“摘要 MCP”设想。
+
+---
+
+## 2. 服务定位
+
+这个 MCP 服务的角色是：为上层 Agent、OpenClaw 或其他自动化流程提供统一的“文章内容提取”能力。
+
+它在整条链路中的位置是：
+
+`RSS 聚合 -> Content Extract MCP -> LLM 摘要 -> 校验 -> 规则过滤 -> 入库 -> 推送`
+
+它不是完整阅读流系统，也不是摘要服务本身，而是阅读流中的“结构化正文提取层”。
+
+### 2.1 服务负责的事情
+
+- 接收 URL 或标准化 `item`
+- 获取正文或补全正文
+- 抽取文章标题
+- 抽取正文纯文本
+- 返回结构化文章对象
+- 返回质量标记和结构化错误
+
+### 2.2 服务不负责的事情
+
+- 管理 RSS 订阅源
+- 生成摘要
+- 主题分类
+- 价值判断
+- 规则过滤
+- 写入知识库
+- 发送通知
+- 执行全流程编排
+
+结论：
+
+当前 MCP 服务边界应保持干净，只负责把网页或 item 转成结构化文章数据。
+
+---
+
+## 3. 总体架构
+
+建议并且当前实现采用的是：
+
+```text
+MCP Server Layer
+  -> Tool Handlers
+    -> extraction core
+      -> normalizer
+      -> content_loader
+      -> extractor
+      -> quality_checker
+      -> mapper
+```
+
+### 3.1 外层 MCP 层职责
+
+- 注册 tools
+- 接收和校验 tool 输入
+- 调用内部 extraction core
+- 将结果包装成 MCP tool 输出
+
+### 3.2 内层 extraction core 职责
+
+- 处理正文获取、标题提取、正文抽取、质量检查、结果映射
+- 与具体 MCP SDK 解耦
+
+### 3.3 为什么必须分层
+
+如果把内容提取逻辑直接写死在 MCP handler 里，后续会出现这些问题：
+
+- 业务逻辑难测试
+- 协议层与抽取逻辑耦合
+- 以后想补 CLI、批处理或其他入口时需要重复实现
+
+因此当前原则是：
+
+- MCP 是外壳
+- extraction core 是内核
+
+---
+
+## 4. 当前暴露的 Tools
+
+当前实现只暴露两个 tool：
+
+- `extract_url_content`
+- `extract_item_content`
+
+### 4.1 `extract_url_content`
+
+角色：
+
+- 直接输入 URL
+- 适合单条文章测试
+- 适合手动调试或上层 Agent 直接调用
+
+建议输入：
+
+```json
+{
+  "url": "https://example.com/post/1",
+  "language_hint": "zh"
+}
+```
+
+建议输出：
+
+```json
+{
+  "success": true,
+  "article": {
+    "extract_id": "sha256:yyy",
+    "item_id": null,
+    "source_id": null,
+    "url": "https://example.com/post/1",
+    "title": "文章标题",
+    "language": "zh",
+    "content_kind": "article",
+    "plain_text": "抽取后的正文",
+    "quality_flags": {
+      "is_paywalled": false,
+      "is_truncated": false,
+      "is_low_content": false
+    },
+    "metadata": {
+      "content_source": "fetched_html",
+      "extractor": "trafilatura",
+      "char_count": 1234
+    },
+    "pipeline_state": "extracted"
+  },
+  "warnings": [],
+  "debug": {
+    "content_source": "fetched_html",
+    "extractor": "trafilatura"
+  }
+}
+```
+
+### 4.2 `extract_item_content`
+
+角色：
+
+- 输入标准化 `item`
+- 与上游 RSS 聚合层对接
+- 保留 `item_id`、`source_id` 等追踪信息
+
+建议输入：
+
+```json
+{
+  "item": {
+    "item_id": "sha256:xxx",
+    "source_id": "my-blog",
+    "title": "文章标题",
+    "url": "https://example.com/post/1",
+    "published_at": "2026-03-23T08:00:00Z",
+    "raw_summary": "RSS 摘要",
+    "raw_content": "RSS 正文片段",
+    "content_kind": "article",
+    "language": "zh"
+  }
+}
+```
+
+建议输出：
+
+```json
+{
+  "success": true,
+  "article": {
+    "extract_id": "sha256:yyy",
+    "item_id": "sha256:xxx",
+    "source_id": "my-blog",
+    "url": "https://example.com/post/1",
+    "title": "文章标题",
+    "published_at": "2026-03-23T08:00:00Z",
+    "language": "zh",
+    "content_kind": "article",
+    "plain_text": "抽取后的正文",
+    "quality_flags": {
+      "is_paywalled": false,
+      "is_truncated": false,
+      "is_low_content": false
+    },
+    "metadata": {
+      "content_source": "item.raw_content",
+      "extractor": "inline",
+      "char_count": 1234
+    },
+    "pipeline_state": "extracted"
+  },
+  "warnings": [],
+  "debug": {
+    "content_source": "item.raw_content",
+    "extractor": "inline"
+  }
+}
+```
+
+---
+
+## 5. 统一输出规范
+
+当前两个 tool 都复用同一个输出结构，即 `ExtractionOutput`。
+
+成功时：
+
+- `success = true`
+- 返回 `article`
+- 可附带 `warnings`
+- 可附带 `debug`
+
+失败时：
+
+- `success = false`
+- 返回结构化 `error`
+- 不返回不完整的 `article`
+
+这样做的好处是：
+
+- 上层流程只需要消费一个稳定 schema
+- 后续 LLM 摘要和 validator 可以独立接上
+- OpenClaw 或其他 Agent 更容易编排
+
+---
+
+## 6. 错误返回规范
+
+建议错误结构如下：
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "CONTENT_FETCH_FAILED",
+    "message": "Failed to fetch article content",
+    "retryable": true,
+    "stage": "fetch",
+    "details": {
+      "url": "https://example.com/post/1"
+    }
+  },
+  "warnings": []
+}
+```
+
+当前错误码包括：
+
+- `INVALID_INPUT`
+- `CONTENT_FETCH_FAILED`
+- `CONTENT_EXTRACTION_FAILED`
+- `CONTENT_TOO_SHORT`
+- `UNKNOWN_ERROR`
+
+使用原则：
+
+- 抓取失败不等于程序崩溃
+- 可以重试的错误应标记 `retryable = true`
+- 错误应指出具体阶段
+
+---
+
+## 7. 当前技术选型
+
+当前 MVP 使用：
+
+- Python
+- MCP Python SDK (`FastMCP`)
+- `httpx` 进行网页抓取
+- `trafilatura` 进行正文抽取
+- `beautifulsoup4` 作为 HTML 兜底解析
+- `pydantic` 进行输入输出约束
+
+设计原则是：
+
+- 外层 MCP
+- 内层 extraction core
+- LLM 摘要和校验作为 MCP 之后的独立环节
+
+---
+
+## 8. 当前目录结构建议
+
+当前实现大致如下：
+
+```text
+summary_mcp/
+  server.py
+  core/
+    normalizer.py
+    content_loader.py
+    extractor.py
+    quality_checker.py
+    mapper.py
+    pipeline.py
+  models/
+    item.py
+    document.py
+    summary_io.py
+    llm_result.py
+  validators/
+    llm_result.py
+```
+
+说明：
+
+- `server.py`：MCP 服务入口
+- `core/`：提取内核
+- `models/`：提取和校验相关模型
+- `validators/`：LLM 输出校验逻辑
+
+---
+
+## 9. 与 LLM 摘要层的关系
+
+当前 MCP 不负责摘要，但它与摘要层的接口已经明确：
+
+1. MCP 产出结构化 `article`
+2. 上层 LLM 根据 `article.title`、`article.url`、`article.plain_text` 等生成摘要 JSON
+3. validator 对摘要 JSON 做 schema 校验与业务校验
+4. 若不合格，进入修复重试
+
+这条闭环当前已经通过本地脚本验证：
+
+- `scripts/run_summary_loop.py`
+
+因此，当前正确的职责拆分是：
+
+- MCP 负责提取
+- LLM 负责摘要
+- validator 负责验收
+
+---
+
+## 10. 当前阶段验收结论
+
+当前 MVP 已完成以下验证：
+
+- 真实 URL 可以提取为结构化文章 JSON
+- 提取结果可以保存为文件
+- 提取结果可以喂给 LLM 生成摘要 JSON
+- 摘要 JSON 可以通过 validator 校验
+- 整条“提取 -> 摘要 -> 校验”最小闭环已经跑通
+
+---
+
+## 11. 后续扩展方向
+
+后续建议按下面顺序推进：
+
+- 接入真实 RSS 聚合结果并映射为 `item`
+- 定义规则过滤层 schema
+- 设计知识库入库格式
+- 增加批量处理能力
+- 引入 Playwright 作为动态页面兜底方案
+- 重命名包和项目名，使其与当前职责一致
+
+---
+
+## 12. 当前阶段一句话结论
+
+当前仓库中的 MCP 已经从早期“摘要 MCP”演进为“内容提取 MCP”，它的职责是稳定产出结构化文章 JSON，并把摘要与验收环节留给后续的 LLM 和 validator 流程。