# 通过 URL

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

AI Agent 可以通过文档页面 URL 读取 HTML 数据，也可以读取 `<DOC_URL>.md` 获取 Markdown 镜像。Markdown 镜像主要包含页面正文，应优先读取；HTML 数据包含导航、脚本和样式，仅作为兜底方式。

<span id="compare-url-types"></span>
## 比较两种 URL

| URL 类型 | 响应内容 | 优点 | 局限 |
| --- | --- | --- | --- |
| Markdown 镜像 | `text/markdown` | 主要包含标题和正文，适合直接加入 Agent 上下文。 | 需要已知目标文档页面，并读取 `<DOC_URL>.md`。 |
| HTML 页面 | `text/html` | 支持网页读取的 Agent 可以直接访问，无需改写地址。 | 原始 HTML 同时包含导航、脚本、样式和页面元数据，会占用额外上下文并影响正文提取。 |

<span id="read-markdown"></span>
## 读取 Markdown 镜像

在文档页面 URL 后追加 `.md`。例如：

- 页面 URL：[快速入门](https://ark.volcengine.com/region:cn-beijing/docs/quick-start)
- Markdown 地址：[快速入门 Markdown](https://ark.volcengine.com/region:cn-beijing/docs/quick-start.md)

Markdown 镜像适合以下场景：

- Agent 已从 `llms.txt`、搜索结果或用户输入中获得目标页面地址。
- 任务只需要页面正文，不需要导航和交互组件。
- 需要把文档内容加入对话上下文或保存为文本语料。

<span id="read-html"></span>
## 读取 HTML 页面

支持网页访问和正文提取的 Agent 可以直接读取页面 URL。文档页面的 HTML 响应包含完整正文，也包含站点导航、交互脚本、样式和页面元数据。

读取 HTML 页面时，Agent 应执行以下处理：

1. 提取文章标题和正文区域。
2. 忽略页面导航、页脚、登录入口和交互控件。
3. 忽略脚本、样式及其配置数据。
4. 保留正文中的代码块、表格和链接语义。

不同网页读取工具的正文提取能力不同。工具直接返回原始 HTML 时，不要把完整响应注入模型上下文。

<span id="agent-instruction"></span>
## 配置直接读取规则

将以下规则加入 Agent 的系统提示词：

```text
已知文档页面地址时，先读取 <DOC_URL>.md 获取 Markdown 镜像。
如果 <DOC_URL>.md 不可用，再读取 <DOC_URL> 获取 HTML 页面。
读取 HTML 页面时，只保留文章标题和正文，忽略导航、脚本、样式、页脚和交互控件。
```

<span id="related"></span>
## 相关文档

- 比较全部读取方式，详情请参见[选择读取方式](/docs/read-docs-with-ai-agents)。
- 通过索引定位文档，详情请参见[llms.txt](/docs/read-ark-docs-with-llms-txt)。