网页研究助手如何避免摘要覆盖原文：URL 转 Markdown 的证据链设计

网页研究助手如何避免摘要覆盖原文，真正困难的通常不是完成一次 API 调用，而是让结果可以校验、失败可以定位、后续能够回到原始证据。本文围绕“如何把网页正文、摘要和来源链接分层保存，构建可追溯的 AI 研究助手”给出一套可以直接落到任务状态和数据契约上的实现方式。

问题与结果

把原始 URL、Markdown 正文、摘要和处理版本分开保存，任何结论都能回到原始证据。

最终交付不是一段不可追溯的模型回答，而是一组带来源、版本、状态和失败记录的数据。这样既方便接入后续系统，也能在接口、页面或模型输出变化时定位问题。

适用场景

竞品与行业资料整理
内容研究和选题归档
网页知识库入库前处理

实现前先确定边界

正文抓取成功后才能进入摘要步骤
摘要是派生数据，不能覆盖原始 Markdown
同一 URL 的刷新结果必须保留抓取时间和版本

可验证工作流

网页研究助手如何避免摘要覆盖原文工作流架构图

API 编排与职责

步骤	接口	请求方式	用途
网页转 Markdown	网页 URL 转 Markdown	GET	把网页正文转换成适合 AI 阅读的 Markdown
文本摘要	文本多语言 AI 摘要	POST	对 Markdown 正文生成短摘要和研究结论

最小可运行实现

先把网页转换成 Markdown：

curl -G "https://api.gugudata.com/websitetools/url2markdown" \
  --data-urlencode "appkey=YOUR_APPKEY" \
  --data-urlencode "url=https://example.com/research/article"

再把 Markdown 正文交给摘要接口：

curl -X POST "https://api.gugudata.com/ai/text-summarize?appkey=YOUR_APPKEY&lang=zh-cn&streaming=false" \
  -H "Content-Type: application/json" \
  -d '{
    "textContent": "这里放入上一步得到的 Markdown 正文",
    "streaming": false
  }'

在 Agent 里可以把这两个动作封装成工具：

import requests

APPKEY = "YOUR_APPKEY"


def fetch_markdown(url: str) -> str:
    """Fetch a webpage and return Markdown content."""
    response = requests.get(
        "https://api.gugudata.com/websitetools/url2markdown",
        params={"appkey": APPKEY, "url": url},
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    return payload["Data"]


def summarize_text(text: str) -> str:
    """Summarize Markdown text for a research note."""
    response = requests.post(
        "https://api.gugudata.com/ai/text-summarize",
        params={"appkey": APPKEY, "lang": "zh-cn", "streaming": "false"},
        json={"textContent": text, "streaming": False},
        timeout=60,
    )
    response.raise_for_status()
    payload = response.json()
    return payload["Data"]["summary"]

返回处理

建议在自己的任务记录里保存四类信息：原始 URL、Markdown 正文摘要、接口返回状态、处理时间。这样后续可以判断内容是否需要刷新，也能避免同一个链接被 Agent 重复处理。

如果 DataStatus.StatusCode 不是成功状态，Agent 不应该继续生成研究结论，而应该把任务标记为“待重试”或“需要人工查看”。对于网页无法访问、URL 格式错误、请求频率受限等情况，错误处理要比让模型猜测网页内容更可靠。

工程化注意事项

APPKEY 只放在服务端环境变量或密钥管理系统中，不要写入前端页面。
对外部 URL 做白名单、黑名单或风险校验，避免让 Agent 处理不可信输入。
对长网页设置摘要分段策略，先分块摘要，再汇总成研究笔记。
保存原始链接和生成时间，避免把过期网页内容当成当前事实。

数据契约与留痕

建议至少保存以下字段；真实项目可以继续拆分，但不要删除来源、版本和状态信息。

字段	作用
`source_url`	来源或目标 URL，保留最终跳转前后的差异
`fetched_at`	带时区的采样或生成时间，判断数据新鲜度
`content_hash`	内容哈希，用于完整性校验、版本识别和去重
`markdown`	正文内容，与来源和版本绑定保存
`summary`	派生结果，必须关联输入版本与生成时间
`pipeline_status`	显式状态或结果，禁止用空值代替失败

所有派生结果都应带生成时间和输入版本。发生重试时新增尝试记录，不要覆盖最后一次失败，以免排查时只剩“最终成功”而看不到中间问题。

验收清单

失败网页不会生成推测性摘要
重复 URL 可通过内容哈希识别
研究结论能定位到对应正文版本

能力边界

网页可访问不等于内容真实或当前有效；摘要结果仍需要调用方结合来源和时间判断。

示例中的 YOUR_APPKEY 仅为占位符。真实密钥只能放在服务端环境变量或密钥管理系统中，不应进入前端、文章、日志或版本库。