# API 与 Agent 接入文档

水鱼之家是静态站点，本页发布供自动化客户端（Agent、爬虫、工具链）自动发现的机器可读资源：
API 目录、OpenAPI 描述、Markdown 内容协商与内容用途声明。

- HTML 版：https://waterfish.ren/docs/api.html
- Markdown 版：https://waterfish.ren/docs/api.md

## 1. API 目录（RFC 9727）

以 `application/linkset+json` 发布的 linkset 文档，每个条目包含 `anchor` 与链接关系。

| 资源 | URL | Content-Type |
| --- | --- | --- |
| API 目录 | `/.well-known/api-catalog` | `application/linkset+json` |
| OpenAPI（service-desc） | `/.well-known/openapi.json` | `application/vnd.oai.openapi+json;version=3.1` |
| 接口文档（service-doc） | `/docs/api.html` | `text/html` |
| 健康状态（status） | `/api/health` | `application/json` |

## 2. Markdown 内容协商

任意页面都支持 `Accept: text/markdown`：携带该请求头时返回剥离样式的 Markdown，
不携带时依旧返回 HTML（浏览器默认行为不受影响）。

```bash
curl -H "Accept: text/markdown" https://waterfish.ren/

# HTTP/2 200
# content-type: text/markdown; charset=utf-8
# vary: Accept
# x-markdown-tokens: 412
```

也可以直接访问固定的 Markdown 文件，无需协商：

| 页面 | HTML | Markdown |
| --- | --- | --- |
| 主页 | `/` | `/index.md` |
| 服务选择 | `/choose` | `/choose.md` |
| 本页 | `/docs/api.html` | `/docs/api.md` |
| llms.txt | — | `/llms.txt` |

## 3. Link 响应头

首页及全部 HTML 页面都会返回 `Link` 头（RFC 8288），声明机器可读资源的相对位置：

```
Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json",
      </.well-known/openapi.json>; rel="service-desc"; type="application/vnd.oai.openapi+json",
      </docs/api.html>; rel="service-doc"; type="text/html",
      </llms.txt>; rel="describedby"; type="text/plain",
      </sitemap.xml>; rel="sitemap"; type="application/xml"
```

## 4. Content Signals（内容用途声明）

`robots.txt` 中声明了本站内容允许的使用方式：

```
User-agent: *
Content-Signal: ai-train=no, search=yes, ai-input=no
Allow: /
```

| 类别 | 取值 | 含义 |
| --- | --- | --- |
| `search` | yes | 允许建立搜索索引并返回搜索结果（不含 AI 生成式摘要） |
| `ai-input` | no | 不允许把内容实时输入 AI 模型（RAG / 生成式回答） |
| `ai-train` | no | 不允许用于训练或微调模型 |

## 5. 可用接口一览

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/` | 主页（HTML / Markdown） |
| GET | `/choose` | 服务选择页，列出全部子服务入口 |
| GET | `/sitemap.xml` | 站点地图 |
| GET | `/.well-known/api-catalog` | API 目录 |
| GET | `/.well-known/openapi.json` | OpenAPI 3.1 描述 |
| GET | `/api/health` | 站点健康状态（JSON） |

### 子服务入口

- [资源中心](https://ziyuan.waterfish.ren) — 工具、素材与文档
- [博客](https://blog.waterfish.ren) — 文章与动态
- [留言板](https://board.waterfish.ren) — 轻量社区交流
- [代发邮件](https://mail.waterfish.ren) — 匿名发信（测试）
- [工具](https://tool.waterfish.ren) — 工具网站，提供多种工具

---

© 2026 waterfish.ren · 水鱼之家