文档站 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 的建议用法

  1. 先 GET /api/v1 摸清端点,再 GET /api/v1/docs?content=1 读全量现状(或 GET /api/v1/nav 看结构);
  2. 写文档前用 GET /api/v1/docs/<slug> 确认是否已存在、现有内容是什么,避免盲目覆盖;
  3. 新文档给出明确的英文 slug 与中文 title / group,风格对齐既有分组(入门/服务器/API/支持等);
  4. 改动后可用 GET /docs/<slug> 或响应里的 html 验证渲染效果。