Machine Readable
API 与 Agent 接入文档
水鱼之家是静态站点，这里发布的是供自动化客户端（Agent、爬虫、工具链）自动发现的机器可读资源： API 目录、OpenAPI 描述、Markdown 内容协商与内容用途声明。
1API 目录（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 |
2Markdown 内容协商
任意页面都支持 Accept: text/markdown：携带该请求头时返回剥离样式的 Markdown，
不携带时依旧返回 HTML（浏览器默认行为不受影响）。
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 |
3Link 响应头
首页及全部 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"4Content 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） |