Agent Documentation

API 使用指南

为 Agent 提供的完整 API 参考文档。通过简单的 HTTP 请求， 即可实现笔记的读取、写入和管理。

01

快速开始

Server URL

Base URL: /

所有 API 请求都基于此地址。

给 AI 使用的文档地址

将这个地址提供给 AI，让 AI 直接读取 Markdown 格式的 API 文档：

复制后发送给 AI：请访问这个地址读取 API 文档

已复制到剪贴板

Scope 说明

Scope（命名空间）是笔记的隔离单元。每个 scope 对应一个独立的存储空间，互不影响。

例如：skill 是一个专用的 scope，用于 Agent 存储和读取笔记。

AI 隔离机制：多个 AI 使用同一个 scope 会互相覆盖。建议在 API 请求中带上 uuid 参数，系统会自动将内容隔离到 scope_uuid 空间。

示例：?scope=skill&uuid=abc123 → 实际存储到 skill_abc123

用户访问地址（重要）

当引导用户通过浏览器访问笔记页面时，URL 格式必须为路径形式：

http://note.fangna.tech/{scope}（Markdown 预览）

http://note.fangna.tech/{scope}.md（Markdown 源码编辑）

正确示例：http://note.fangna.tech/skill、http://note.fangna.tech/work、http://note.fangna.tech/work.md

禁止使用查询参数形式：http://note.fangna.tech/?scope=xxx —— 这不是有效的页面访问地址。

认证方式

当前版本无需认证，直接访问即可。

后续版本可能增加 Token 认证机制。

02

读取笔记

GET /api/notes

获取指定 scope 下的笔记列表。每个 scope 下只有一条笔记（ID = 1）。

请求参数

cURL 示例
# 获取 skill scope 的笔记 curl -X GET "/api/notes?scope=skill" # 或使用 Header 传递 scope curl -X GET "/api/notes" \ -H "X-Scope: skill"
响应示例
{ "success": true, "message": "Notes retrieved successfully", "data": [ { "id": 1, "title": "笔记标题", "content": "笔记内容...", "content_format": "markdown", "scope": "skill", "updated_at": "2026-01-23 10:30:00" } ] }
03

写入笔记

POST /api/notes/create

创建或覆盖指定 scope 的笔记。如果该 scope 已存在笔记，将被完全覆盖。

请求格式

Content-Type: text/plain 或 application/x-www-form-urlencoded

Body: 纯文本内容（Markdown 或 HTML）。Agent 建议写 Markdown 并显式带 ?format=md

写入格式：?format=md / X-Format: markdown 强制 Markdown；format=html 强制 HTML；不传时自动识别（含块级 HTML 标签按 HTML，否则按 Markdown）。

请求参数

cURL 示例
# 方式一：Markdown Body（推荐） curl -X POST "/api/notes/create?scope=skill&format=md" \ -H "Content-Type: text/plain" \ -d '# 标题 这是 **Markdown** 内容' # 方式二：Form 格式（Agent 专用接口默认 Markdown） curl -X POST "/api/agent/notes/create" \ -d "scope=skill" \ -d "title=我的笔记" \ -d "content=# 标题，正文"
响应示例
{ "success": true, "message": "Note created successfully", "data": { "id": 1, "scope": "skill", "version": 42 } }
04

其他接口

版本历史

GET /api/versions?scope=skill

获取指定 scope 的历史版本列表，保留最近 100 个版本。每个版本包含格式与相对上一版本的修改摘要。

GET /api/versions/content?filename=note_20260123_103000.md

读取指定版本文件的内容。

更新笔记

POST /api/notes/update

参数：note_id=1&title=xxx&content=xxx&scope=skill

清空笔记

POST /api/notes/delete

参数：note_id=1&scope=skill，将笔记内容清空（不会删除文件）

Agent 专用接口

POST /api/agent/notes/create

专为 Agent 设计的接口，参数：title=&content=&scope=skill，默认按 Markdown 存储。

05

注意事项