文档站 AI API
本文档站自身开放的 REST API——给 AI 或脚本用 Token 完成文档增删改查、导航、搜索与站点配置。
更新于 2026-10-09
文档站 AI API
本文档站(doc.cheesesynx.cn)自身开放了一套 REST API,专门给 AI 助手或自动化脚本使用: 拿到 Token 后,不需要登录后台网页,就能完成文档的增删改查、读导航树、站内搜索、改站点配置等全部操作。
一、鉴权
所有端点(除 /api/v1/health 与 /api/v1 清单外)都需要 Token,三种携带方式任选:
Authorization: Bearer <token>
X-API-Token: <token>
GET /api/v1/docs?token=<token>
- Token 用服务器上的
npm run api-token(即node bin/api-token.js add <名称>)生成,明文只显示一次; - 服务端只存 sha256 散列(
data/api-tokens.json,权限 600),泄露后可随时 revoke 换新。
二、端点一览
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1 |
端点自描述清单(免鉴权,AI 可先调这个摸清能力) |
| GET | /api/v1/health |
健康检查(免鉴权) |
| GET | /api/v1/docs |
列出全部文档(含隐藏),?content=1 附带每篇正文 |
| POST | /api/v1/docs |
新建或整体保存一篇 |
| GET | /api/v1/docs/<slug> |
读一篇:meta + markdown + 渲染后的 html |
| PATCH | /api/v1/docs/<slug> |
局部更新(只改 meta 或只改正文均可) |
| PUT | /api/v1/docs/<slug> |
整体覆盖(slug 以 URL 为准) |
| DELETE | /api/v1/docs/<slug> |
删除一篇 |
| GET | /api/v1/nav |
前台导航树(不含隐藏文档) |
| GET | /api/v1/search?q=关键词 |
站内搜索(标题+正文,带上下文摘要) |
| GET | /api/v1/config |
读站点配置(已脱敏,不含任何密钥) |
| PATCH | /api/v1/config |
改站点配置:siteName / subSite / company / icp / police / sites |
三、响应格式
统一 JSON。成功:{ "ok": true, ...数据 };失败:{ "ok": false, "message": "中文原因" }。
状态码:200 成功、201 新建成功、400 参数不合法、401 Token 无效、404 文档不存在、405 方法不支持、500 服务器错误。
四、写一篇文档
curl -X POST https://doc.cheesesynx.cn/api/v1/docs \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"slug": "api/example",
"title": "示例文档",
"group": "API",
"order": 9,
"desc": "一句话简介,显示在首页卡片",
"markdown": "# 示例文档\n\n正文用 Markdown 写。\n"
}'
slug只允许小写字母、数字、-、_、/(子目录即分组层级,如api/example);不传时按标题自动生成,中文标题会生成doc-日期-时间形式的兜底 slug,建议 AI 明确指定;group决定前台左侧导航的分组名(中文分组名直接写即可,如「入门」「服务器」);order数字越小越靠前;desc是首页卡片上的一句话简介;hidden: true表示内部手册:前台列表、搜索、直连一律不可见(API 仍可读写);- slug 已存在时
POST是整体覆盖,响应里created: false。
五、局部更新与删除
# 只改标题和排序,不动正文
curl -X PATCH https://doc.cheesesynx.cn/api/v1/docs/api/example \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"title": "新标题", "order": 2}'
# 只替换正文
curl -X PATCH .../docs/api/example -d '{"markdown": "# 全新正文"}'
# 删除
curl -X DELETE .../docs/api/example -H "Authorization: Bearer $TOKEN"
PATCH 没传的字段一律沿用旧值(title / group / order / desc / hidden / markdown 都是可选的)。
六、站点配置(PATCH /api/v1/config)
{
"siteName": "上海芝士昱森科技有限公司公开文档站",
"subSite": "起司云文档站",
"sites": [
{ "slug": "cheese-cloud", "name": "起司云文档站", "desc": "……", "groups": ["入门", "服务器"] }
]
}
sites决定首页的子站点卡片与分组阅读顺序(groups数组的先后就是导航顺序);- 修改即时生效(免重启);飞书密钥、会话密钥不开放给 API,防止 Token 泄露后接管登录。
七、给 AI 的建议用法
- 先
GET /api/v1摸清端点,再GET /api/v1/docs?content=1读全量现状(或GET /api/v1/nav看结构); - 写文档前用
GET /api/v1/docs/<slug>确认是否已存在、现有内容是什么,避免盲目覆盖; - 新文档给出明确的英文
slug与中文title / group,风格对齐既有分组(入门/服务器/API/支持等); - 改动后可用
GET /docs/<slug>或响应里的html验证渲染效果。