用 URL 转 Markdown 和摘要接口搭建 AI 研究助手

用 URL 转 Markdown 和摘要接口搭建 AI 研究助手

摘要：这篇文章演示如何把一个网页研究任务拆成 Agent 可以执行的步骤：抓取网页、转成 Markdown、生成摘要、沉淀结构化笔记。它适合内容运营、产品调研、竞品资料整理和知识库入库等场景。

关键词：AI 研究助手、Agent 工作流、URL 转 Markdown API、文本摘要 API、网页内容处理

问题背景

很多研究任务的输入只是一个链接，但真实工作并不是“打开网页看看”这么简单。团队通常需要提取正文、过滤导航和广告、保留标题层级、生成摘要，再把结果交给知识库或后续问答系统。

如果让 Agent 直接访问网页，它需要处理页面结构、正文抽取、编码、内容长度和失败重试。更稳定的做法是把网页处理能力封装成工具调用，让 Agent 专注于决策和总结。

Agent 工作流

接口编排

调用示例

先把网页转换成 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 处理不可信输入。
• 对长网页设置摘要分段策略，先分块摘要，再汇总成研究笔记。
• 保存原始链接和生成时间，避免把过期网页内容当成当前事实。

标准架构拆解

从技术架构上看，这类研究助手可以拆成四层：

入口层不要直接调用模型，而是先把任务规范化。例如同一个网页可能带有追踪参数，入库前应统一 URL 格式；同一个研究主题可能包含多条链接，应拆成子任务并保留父任务 ID。

工具层只做确定性输入输出，不应该夹带业务判断。网页转 Markdown 负责把页面内容变成文本，摘要接口负责压缩内容；至于是否可信、是否进入知识库，应该放在编排层或审核层完成。

数据流与接口边界

一个可维护的数据流可以按下面的顺序设计：

1. 任务创建：用户提交 URL 和研究目标。
2. URL 规范化：去掉无意义参数，检查协议和域名。
3. 内容转换：调用网页 URL 转 Markdown。
4. 文本处理：清理空段落、过长代码块和重复导航。
5. 摘要生成：调用文本多语言 AI 摘要。
6. 结果落库：保存摘要、正文、来源和状态。
7. 后续消费：供搜索、问答、日报或人工分析使用。

接口边界上，url2markdown 的输出是中间内容，不建议直接展示给最终用户。更适合展示的是摘要、关键段落和来源链接。这样既能保证页面体验，也方便后续替换摘要模型或补充新的处理步骤。

可靠性与观测

研究助手最常见的问题不是代码报错，而是外部网页波动。因此需要记录以下指标：

对于失败任务，建议区分“URL 无效”“页面不可访问”“正文为空”“摘要失败”四类状态。这样运营或研发能快速判断是内容源问题、接口调用问题，还是下游处理问题。

落地清单

• 先做单链接处理，再扩展到批量链接队列。
• 每次处理都保存 source_url、normalized_url、processed_at 和接口状态。
• Markdown 正文入库前做长度限制，避免单篇文章影响后续检索。
• 摘要结果不要覆盖原文，原文和摘要应分别保存。
• 对外展示时标明来源和处理时间，避免用户误以为是实时事实。

可扩展方向

这个工作流可以继续接入网页链接提取接口，自动发现同站点相关链接；也可以接入命名实体识别，把公司、产品、人物、地点等实体写入知识图谱。对内部知识库来说，URL 转 Markdown 是入口，摘要和结构化标签才是长期可检索的资产。

相关接口

• 网页 URL 转 Markdown
• 文本多语言 AI 摘要
• 网页 URL 链接提取