# AI 阅读

组件库文档最容易出错的地方是「AI 凭印象编 API」。本站因此把全部文档额外产出为**三种纯文本形态**，任何 AI 智能体只要拿到站点域名就能读完，不必去解析渲染后的 HTML。

| 入口 | 路径 | 适合场景 |
| --- | --- | --- |
| 全站索引 | [`/llms.txt`](/llms.txt) | 先让模型知道有哪些页面，再按链接取用 |
| 单页 Markdown | `/md/<页面路径>.md` | 精确投喂某一两个组件 |
| 全站单文件 | [`/llms-full.txt`](/llms-full.txt) | 一次性通读整份文档 |

三个入口都是**纯净 Markdown**。页面里的演示代码块已经被展开成完整的 Vue SFC 源码 —— 模型看到的是可以直接运行的代码，而不是文档站的插件语法。

## 推荐用法

### 一、精确投喂单个组件

最省 token 的方式，把目标页面的 Markdown 原文地址直接给模型：

```text
请阅读 https://tongmingwang.github.io/miao-design/md/components/button.md
然后按里面的 API，帮我写一个带加载态的提交按钮。
```

### 二、给项目写一份接入约定

把下面这段放进 `.cursor/rules`、`CLAUDE.md`、`AGENTS.md` 或任何自定义指令的位置，能显著降低 API 幻觉率：

```text
本项目使用 miao-design（Vue 3 组件库）。

- 文档索引：https://tongmingwang.github.io/miao-design/llms.txt
- 需要某个组件的用法时，先抓取 https://tongmingwang.github.io/miao-design/md/components/<组件目录名>.md 再写代码，不要凭印象生成 API。
- 组件标签名一律 M 前缀（MButton / MInput / MSelect …），已在 main.ts 里通过
  app.use(MiaoDesign) 全局注册，模板里无需 import。
- 样式必须引入一次：import 'miao-design/style.css'。
- 主题令牌统一是 CSS 自定义属性，形如 --m-primary / --m-radius / --m-size-default，
  不要硬编码颜色，需要换肤时覆写变量。
- 事件与 v-model 命名遵循 Vue 3 约定：update:modelValue / change / click。
```

### 三、一次性通读

只有在需要「通读整个库」时才用全量文件，否则会浪费上下文：

```bash
curl -s https://tongmingwang.github.io/miao-design/llms-full.txt
```

## 本站为 AI 做的其他约定

- **每页都有 Markdown 替代链接**：页面 `<head>` 里带有 `<link rel="alternate" type="text/markdown" href="/md/xx.md">`，爬虫与智能体可以直接发现。
- **演示源码就是真实文件**：`docs/demos/<组件>/<用例>.vue`，文档里的代码与仓库中的文件一一对应，不存在文档与实现漂移。
- **robots.txt 显式放行**，并在注释里标注了三个纯文本入口。
- **API 表格用 Markdown 表格书写**，而不是自定义组件渲染 —— 保证在任何文本形态下都可读。
- **每页开头有 `description`**，被索引进 `llms.txt`，方便模型快速判断是否要展开该页。

## 人类阅读也能用

页面顶部有一个小工具条，随时可以：

- **复制为 Markdown** —— 把当前页原文（含完整演示源码）复制到剪贴板，粘进对话即可。
- **原文** —— 在浏览器里打开纯 Markdown 版本。
- **llms.txt** —— 打开全站索引。

## 下一步

- [组件总览](/components/) —— 全部组件与指令的实时预览。
- [常见问题](/guide/faq) —— 高频踩坑点，也建议一并投喂给 AI。