🤖 AI 笔记接口 · 调用说明

一、认证方式（必须）

所有 /api/* 接口都需要 API Key，两种传法任选其一：

• 请求头：X-API-Key: 你的密钥
• URL 参数：?api_key=你的密钥

密钥错误返回 401 {"ok": false, "error": "..."}。

二、端点总览

三、新增笔记 POST /api/notes

请求体（JSON）字段说明

请求示例（curl）

curl -X POST "http://服务器地址:端口/api/notes" \
  -H "X-API-Key: 你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "广播与订阅事件机制原理",
    "question": "这个项目中，广播事件，订阅事件机制原理是什么？举例说明",
    "content": "<ctx><t>前情提要：</t>来自 FPS 项目</ctx><h3>一、原理</h3><warnbox>坑：…</warnbox>"
  }'

请求示例（Python requests）

import requests

requests.post(
    "http://服务器地址:端口/api/notes",
    headers={"X-API-Key": "你的密钥"},
    json={
        "title": "广播与订阅事件机制原理",
        "question": "这个项目中，广播事件，订阅事件机制原理是什么？",
        "content": "<ctx><t>前情提要：</t>…</ctx><h3>一、原理</h3>",
    },
)

成功响应（201）

{
  "ok": true,
  "note": {
    "id": 8, "ord": 8, "title": "广播与订阅事件机制原理",
    "question": "这个项目中，广播事件，订阅事件机制原理是什么？",
    "date": "2026-09-15",
    "content": "<div class='ctx'><span class='t'>前情提要：</span>…</div>…"
  }
}

四、content 字段写作规范（自定义标签 DSL，重点！）

正文不写原生 HTML（写了也会被白名单过滤），改用下面的自定义标签，提交时系统自动转换：

一个完整示例（照这个感觉写就行）

<ctx><t>前情提要：</t>来自 FPS Microgame 项目</ctx>
<law>一句话原理：事件就是一张方法订阅名单</law>
<h3>一、原理</h3>
<p>正文段落，<b>加粗</b>，行内代码 <code>Invoke()</code>。</p>
<table><thead><tr><th>写法</th><th>含义</th></tr></thead>
<tbody><tr><td class="ok">+=</td><td>订阅</td></tr></tbody></table>
<flow>子弹命中 → 扣血 → 广播 OnDamaged → 火花特效</flow>
<codeblock><k>public</k> UnityAction OnDie;   <c>// 广播名单</c></codeblock>
<warnbox>坑：订阅代码别写进 Update，会重复注册！</warnbox>
<tipbox>小结：发布方和订阅方互不认识，靠名单传话。</tipbox>

五、AI 添加一条笔记的标准流程

1. GET /api/notes → 看现有条数 count 和 next_order，确认新笔记该排第几；
2. （可选）GET /api/style 或 GET /api/notes/<某条id> → 校准写作风格；
3. 把问答整理成规范 content（忠实原问答干货：原理、步骤、坑、对比表），
4. POST /api/notes 写入；
5. （可选）GET /api/notes 复查确认成功。

六、响应码速查