API 网关

这是面向 脚本与 AI Agent 的接口说明：复用主站全部权限与规则（帖子、作业、投票、公告、共享文件、画板、标签、围棋、维基与哈基八）。本页由 api/endpoints.php 的端点登记表生成，与网关上实际生效的路由、/openapi.json 同源。

v1（新调用一律用它）

/client/v1/… 是 Cloudflare 风格的调用方式：恒定信封 {success, errors, messages, result, result_info}、数字错误码、page/per_page 分页、Idempotency-Key 幂等写、每个响应带 Forum18-Request-Id。接口契约的唯一权威是仓库里的 docs/api-spec.md；机器可读版是 https://api.forum18.cn/client/v1/openapi.json。

鉴权有两条通道（任选其一，详见 docs/api-spec.md §3.2）：Authorization: Bearer <令牌>（脚本 / Agent / 第三方），或第一方页面的浏览器会话（Cookie PHPSESSID，写请求必须再带 X-CSRF-Token，缺失返回 2008；会话通道不支持 Idempotency-Key）。只读令牌只能发 GET，写方法（POST/PUT/DELETE）必须用写入令牌，否则 403 2004。

Agent MCP / OAuth

本地mcp/server.mjs以stdio接入，FORUM18_API_URL/FORUM18_API_TOKEN读取现有令牌。远程POST /mcp使用论坛OAuth授权码+PKCE S256及resource绑定（普通API令牌不可用）；元数据在/.well-known/oauth-protected-resource/mcp及发行方/.well-known/oauth-authorization-server，注册/令牌/撤销在/oauth/register、/oauth/token、/oauth/revoke。主站/oauth/authorize.php复用登录/2FA并显式确认范围；账号设置/oauth/grants.php可撤销整组授权。支持2026-07-28无状态HTTP与2025-11-25初始化；没有旧HTTP+SSE。工具来自v1用户路由，不开放管理员、MC原生接口或通用宿主命令。本地ZIP文件工具仅接受明确的绝对路径，远程ZIP以base64分片暂存；下载同样有限分片。业务失败返回structuredContent/isError，202受理须另查job_id。blog_credentials与blog_ssh必须显式授权；缺Git出口/硬池时拒绝，不在宿主拉仓库。此功能仅本机实现，尚未部署生产，Docker Git/运行时与真实2FA投递未验。

博客 API

博客部署 POST 使用 multipart/form-data 的单个 file ZIP 字段（最大50MiB）及可选config JSON，支持packages原始1MiB分片、git异步发布、redeploy与rollback。其幂等指纹包含文件SHA-256/配置；下载成功为 ZIP 二进制，失败仍是恒定信封。所有操作仅限本人所选 site_id，清理过的本地发布包无法下载。 SSH 必须显式授予 blog_ssh 的写令牌，旧空范围全量令牌不能用于 SSH。只允许本人容器非 root shell/workspace，拒绝 SFTP/SCP 与 TCP/Unix/Agent/X11 转发。CLI 密码提示可粘贴该令牌；不得放入 argv、URL 或日志。撤销/到期后至多 30 秒断开。共享硬资源池及网关未完成时 SSH 返回 3002，不因 API 上线而开放。

令牌与鉴权（弃用路径）

在 设置中心 → 账号 → API 令牌 生成：填写自定义名称并勾选范围，密钥为 32 位区分大小写随机字符，只在创建成功时一次性展示（库中仅存哈希）。令牌分两种：

密钥不放在 URL 路径里（避免进入访问日志与 Referer），改用请求头或请求体携带：

# 方式一：请求头（推荐，GET/POST 通用）
-H "Authorization: Bearer <密钥>"
-H "X-API-Token: <密钥>"

# 方式二：POST 请求体字段
-d "token=<密钥>"          # 表单
{"token": "<密钥>", ...}      # JSON

令牌范围

创建令牌时按区域勾选，越权返回 403 insufficient_scope。没有勾选范围的旧令牌视为全量；显式勾过范围的旧令牌不会自动获得新范围，要用维基等新接口请在设置页补勾或重新创建。

无需令牌

• GET /file/lead — 共享文件总览：id、文件名、大小（字节）、简介、下载次数、下载直链（jump_url）
• GET /file/{id} — 下载共享文件：文件流；支持 Range 单段续传，受全服连接数与带宽限制；无身份，不计账号日限额
• GET /openapi.json — OpenAPI 3.1 描述：本网关全部端点的机器可读描述（OpenAPI 3.1），可直接喂给 Agent 或代码生成器

只读接口

响应统一为 {"success":true,"data":{…}}；令牌无效返回 401，范围不足返回 403，内容不可见返回 404。

写接口

表单字段用 application/x-www-form-urlencoded；维基编辑与哈基八也接受 JSON 请求体。成功通常返回 302 与 location 字段；JSON 端点（like/coin/chat）原样透传主站响应。

示例

# 查看帖子信息
curl "https://api.forum18.cn/r/thread?id=1" -H "Authorization: Bearer <密钥>"
# 下载共享文件（无需令牌）
curl -O "https://api.forum18.cn/file/12"
# 查看维基条目（含维基语法与渲染后的 HTML）
curl "https://api.forum18.cn/r/wiki/page?title=十八中" -H "Authorization: Bearer <密钥>"
# 搜索维基 / 看最近更改
curl "https://api.forum18.cn/r/wiki/search?q=校园" -H "X-API-Token: <密钥>"
curl "https://api.forum18.cn/r/wiki/recent?limit=20" -H "X-API-Token: <密钥>"
# 新建或编辑维基条目（写入令牌，JSON 提交）
curl -X POST "https://api.forum18.cn/w/wiki/edit" \
  -H "X-API-Token: <密钥>" -H "Content-Type: application/json" \
  -d '{"title":"十八中","content":"== 简介 ==\n学校条目。","summary":"首次创建"}'
# 发布帖子
curl -X POST "https://api.forum18.cn/w/post" \
  -H "X-API-Token: <密钥>" \
  -d "type=post" -d "title=你好" -d "content=正文"
# 当前令牌账号（金币、签到、未读通知）
curl "https://api.forum18.cn/r/me" -H "X-API-Token: <密钥>"
# 询问哈基八（令牌放 JSON body）
curl -X POST "https://api.forum18.cn/r/ai" \
  -H "Content-Type: application/json" \
  -d '{"token":"<密钥>","messages":[{"role":"user","content":"今天有什么新帖子？"}]}'
# 拉取 OpenAPI
curl "https://api.forum18.cn/openapi.json"