AMNW ——「智能体原生网」介绍

硅基极客
0 阅读4分钟

AMNW ——「智能体原生网」介绍

作者：吴桂荣

AI Agent 越来越多地被用于自动化操作网页。但现在的网站基本是为人类设计的——大量嵌套的 HTML 标签、靠 class 名隐含语义，Agent 要"读懂"一个页面，要么解析 DOM，要么依赖单独维护的 API。

有没有一种方式，让同一份内容，既能被 Agent 直接理解，又能被浏览器渲染为好看的界面？

笔者设计开源的 AMNW（Agent Markdown-Native-Web）就是为这个问题设计的。

一、它是什么

AMNW 是一套 Markdown 扩展规范，加上一个参考实现。

核心思路很简单：用 Markdown 写内容，浏览器和 Agent 各取所需。

  • Agent 访问 .md 文件，直接读取原始 Markdown，里面有结构化的元数据和操作声明；
  • 浏览器访问同一个 .md 文件，文件头部的脚本会自动加载渲染器，把它变成带样式的 HTML 页面。

两类访问者用同一个 URL，服务器根据请求头区分返回格式，内容只需要维护一份。

二、语法扩展

AMNW 在标准 Markdown 上做了两类扩展。

第一类是 Frontmatter 元数据。 文件顶部用 YAML 声明页面信息，包括页面类型、可执行的操作等：

---
title: 商品列表
agent-role: product-list
actions:
  - id: add-to-cart
    method: POST
    endpoint: /api/cart/add
    body:
      - name: item_id
        type: string
        required: true
---

actions 字段告诉 Agent 这个页面有哪些操作可以执行，以及如何执行。

第二类是容器块语法。 用 ::: 包裹一段内容，赋予它语义：

:::alert{type=info}
所有商品本周享受 8 折优惠。
:::

:::card-grid

:::card
![超轻单人帐](img.jpg)
## 超轻单人帐 UL
**¥499**
- 重量 0.9kg，适合长距离徒步
[加入购物车](#){rel=action action-id=add-to-cart item-id=SKU-001}
:::

:::card
## 三季帐篷 Pro
**¥899** ~~¥1299~~
- 3人容量，防水 3000mm
[加入购物车](#){rel=action action-id=add-to-cart item-id=SKU-002}
:::

:::

浏览器渲染后，:::card-grid 变成响应式卡片网格，[加入购物车] 变成按钮。Agent 读到的则是干净的 Markdown 文本，从 {rel=action action-id=add-to-cart item-id=SKU-001} 中提取操作参数。

目前支持 13 种容器类型：card、card-grid、hero、alert、tabs、tab、form、step-list、data、collapsible、compare、agent-hint、agent-context。

其中 agent-hint 比较特殊——内容只给 Agent 看，浏览器完全隐藏：

:::agent-hint
当前页面展示商品列表。可用 search action 搜索，
用 add-to-cart action 加购（需提供 item_id）。
:::

渲染效果 image.jpg

三、浏览器端的工作原理

每个 .md 文件头部嵌入一行引导脚本：

<!--BROWSER-ONLY: Agent please skip this block-->
<script src="/amnw-bootstrap.js"></script>
<!--END BROWSER-ONLY-->

注释里的提示是给 Agent 的，让它跳过这段。浏览器执行这个脚本后，会依次加载 DaisyUI、Tailwind CDN、渲染器（gzip 约 76 KB），然后 fetch 当前页面的 Markdown 内容，渲染为 HTML 注入到页面。

整个过程对 Markdown 内容本身没有任何污染。

四、全站配置

导航栏、页脚、主题、自定义样式、JS 脚本，统一在项目根目录的 site.config.js 里配置：

window.AMNW_SITE = {

  styles: {
    files: ['/custom.css'],  // 外部样式
  },

  scripts: ['/custom.js'],   // 页面挂载前加载

  hooks: {
    // 页面渲染完成、DOM 就绪后执行
    onMount(container, frontmatter) {
      console.log('当前页面类型：', frontmatter['agent-role']);
    },
    // 用户点击 action 按钮时执行
    onAction(actionId, data, el) {
      if (actionId === 'add-to-cart') {
        fetch('/api/cart/add', {
          method: 'POST',
          body: JSON.stringify({ itemId: data.itemId }),
        });
      }
    },
  },

  chrome: {
    layout: 'top-nav',  // 顶栏布局
    navbar: {
      brand: '我的站点',
      brandUrl: '/',
      links: [
        { label: '商品', url: '/products' },
        { label: '文档', url: '/docs' },
      ],
      showThemePicker: true,
    },
    footer: {
      copyright: '我的站点 © 2026',
    },
  },
};

修改这一个文件，所有页面同步生效。

chrome.layout 支持四种布局：顶栏布局（top-nav）、左侧栏（sidebar-left）、右侧栏（sidebar-right）、纯侧边栏（sidebar-only）。

五、本地运行

git clone https://github.com/wuguirongsg/AMNW
cd AMNW
npm ci
npm run build
node server.js

启动后访问 http://localhost:3005/，默认展示商品列表示例页面。examples/ 目录下还有商品详情、产品对比、博客文章等几个示例。

六、项目结构

代码仓库是 npm workspaces 的 monorepo，包含两个核心包：

  • @amnw/parser：将 AMNW Markdown 解析为 AST。内部用自研的栈式解析器处理 ::: 容器语法，支持任意深度嵌套。
  • @amnw/renderer：将 AST 渲染为 DaisyUI HTML，处理导航、布局、页脚、样式注入和生命周期钩子。

七、目前的状态

v1.0 刚完成，基本功能都有了：解析器、渲染器、布局系统、样式扩展、生命周期钩子、示例页面、文档。

尚未完善的部分包括：CLI 工具（目前需要自己搭服务器）、生产构建管道（目前使用 Tailwind Play CDN）、更多容器类型（图表、时间轴等）、以及 MCP Server 适配器。后续计划见仓库里的 ROADMAP.md。

项目以 MIT 许可证开源。

参考资料

avatar
文章
阅读
粉丝