Web 内容

🔵 Agent OS 包含一个小型内容文件系统：公开站点由 Markdown + YAML 渲染，这些文件完全位于配置树中（config/web/），此外还可以放入原始 HTML 页面（例如完全自定义的落地页），它们会按原样提供。没有数据库和管理 CMS——要修改页面，直接编辑文件；在 live reload 下，更改无需重启和重新构建即可生效。

13.0 内置站点及其替换

二进制文件中内置了默认站点（crates/modules/surfaces/agent_os_site/web/，代码为 crates/modules/surfaces/agent_os_site/src/lib.rs）。它在构建阶段被打包进二进制文件，并在没有 config/web/ 时提供。

要用你自己的站点替换它，请创建 config/web/：

• 完全自定义的落地页——放入 config/web/index.html（原始 HTML，按原样提供；参见 §13.4）。这是自定义设计的推荐方式；
• markdown 站点——创建 config/web/index.md，包含非空的 cards（§13.2）以及页面 config/web/pages/*.md。

一旦 config/web/ 存在并成功加载（Site::load），它就会覆盖内置站点。如果没有 config/web/——则提供内置站点。如果它存在但无法解析，服务器在启动时会回退到内置站点，而在 live reload 时保留最后一个可用版本（并在日志中给出警告）。

config/web/ 支持热重载：修改以及新增/删除的页面都会被自动识别，无需重启（§13.8）。

13.1 可配置的内容

Site::load 在启动时被调用，并在 live reload 时再次调用。站点在 / 和 /site/ 下提供。

13.2 index.md — front matter

Front matter 是位于 --- 行之间的 YAML。除非另有说明，所有字段都是可选的；显示的是默认值。

---
title: My Site
tagline: One-line description
description: SEO / OG meta description (падает на tagline)
canonical_base: https://example.com   # абсолютная база; иначе из запроса
footer: © 2026 My Site

cases_title: Case Studies            # по умолчанию "Кейсы внедрения"
demos_title: Live Demos              # по умолчанию "Живые демо"
dev_title: For Developers            # по умолчанию "Для разработчиков"
dev_href: developers.html            # по умолчанию "developers.html"
dev_label: Tools and API             # по умолчанию "Инструменты и API платформы"
dev_icon: 🔧

nav:
  - { label: Home, href: index.html }
  - { label: Docs, href: documentation.html }

cards:
  - tag: Platform
    title: Overview
    href: overview.html
    desc: One-liner shown on the card
    src: pages/overview.md           # опц.; по умолчанию pages/<href minus .html>.md

demos:
  - { icon: "🚗", title: "Cars demo", href: "/demo/overlay?model=drom-agent", desc: "…" }

extra_pages:
  - { title: "Download", href: download.html, src: pages/download.md }
---

字段参考

src 卡片默认 pages/<href minus .html>.md；请显式指定，以便从其他地方拉取页面（例如 config/web/ 之外的文档文件）。没有可解析 markdown 来源的卡片会被跳过并给出警告。

cards 不能为空——否则站点会加载失败并报错（除非原始 index.html 覆盖了落地页；参见 §13.4）。

href 以 doc- 开头的页面被视为文档页面：它们会被添加侧边栏（

13.3 详情页（pages/*.md）

每个页面是一个 Markdown 文件，由 CommonMark 方言（comrak）渲染。启用的扩展：

markdown 之间的内部链接（[x](foo.md)）会自动重写为 foo.html。

Mermaid 图表

页面可以嵌入 ```mermaid 块。内置模板从 CDN 加载 mermaid.js，并在客户端将其渲染为 SVG：

```mermaid
graph TD; A-->B;
```

站点的 Content-Security-Policy 允许 https://cdn.jsdelivr.net。

13.4 原始 HTML 页面（任意落地页）

config/web/ 中任何 .html 文件（*.tpl.html 除外）都会按原样提供——绕过 markdown 渲染和模板，完全掌控 <head>、脚本、样式和字体。

同名原始 HTML 页面优先于 markdown 页面。原始页面会出现在 sitemap.xml 中（index.html 除外，它映射到 /）。

这是制作自定义落地页的推荐方式：将完整 HTML 文档放入 config/web/index.html，并将组件（独立的 /widget.js）嵌入到任意位置。原始页面在提供时不带 markdown 站点的严格 CSP，因此外部脚本、字体和 iframe 都能按所写的方式正常工作。

index.md 在存在原始 HTML 页面时是可选的：没有它，markdown 站点 只是不渲染。对于 markdown 落地页和 SEO meta，仍然需要一个有效的 index.md，且 cards 非空。

13.5 模板

index.tpl.html 和 page.tpl.html 是可选的。如果在 config/web/ 中存在，它们 会替换内置默认值。占位符由 {key} 填充：

{head} — 生成的 SEO/OG meta 块；{content} — 正文渲染。 内置默认值位于 crates/modules/surfaces/agent_os_site/src/lib.rs （INDEX_TPL_DEFAULT / PAGE_TPL_DEFAULT / DOC_TPL_DEFAULT）；内置 内容位于 crates/modules/surfaces/agent_os_site/web/。

13.6 SEO 与爬虫界面

• GET /sitemap.xml — 索引加上每个 card.href、extra_pages.href 以及 原始 .html 页面（index.html 除外）。
• GET /robots.txt — Allow: / 和 Sitemap: 指针。
• 每个页面上的 <link rel="canonical">、og:* 和 twitter:card，使用 canonical_base（或来自 Host + X-Forwarded-Proto）。
• GET /favicon.ico 和 GET /site/favicon.svg — 内联 SVG favicon。

页面以弱 ETag（内容哈希）和 Cache-Control: no-cache 提供， 因此在 live reload 时未更改的页面会返回 304。

13.7 路由

未知页面 — 样式化的 404。

13.8 Live reload

在 kernel.live_reload: true（默认）时，watcher 会在任何文件变更时从 config/web/ 重新渲染站点 — 无需重启和重新构建。新增和删除的页面也会 同样被拾取：路由 /… 和 /site/… 在每次请求时从共享槽位解析，而不是在启动时固定。 当配置来自 git 仓库（AGENT_OS_CONFIG_REPO / --config-repo）时也同样工作； 参见 §3.1。

13.9 嵌入外部内容 — /proxy

对于不在你的配置树中的页面，有两个端点：

两者都是 SSRF 安全的：私有、loopback、link-local 和 reserved 范围 （包括 169.254.169.254）在每一跳都被阻止。server.yaml 中的 proxy.allow_hosts 额外限制主机；留空 = 任意公共主机。

13.10 面向代理的 Web 内容

以上是面向人的站点。对于阅读 Web 内容的代理，工具 在 §5 中描述：

站点通常由爬虫（agent-os scrape）抓取到归档中，然后由 archive_tool 搜索。