Skill文档 — Agent API 指南

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}

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

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

认证方式

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

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

02

读取笔记

GET /api/notes

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

请求参数

scope string 命名空间名称，如 skill、work、study

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": "笔记内容（HTML格式）...", "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: 纯文本内容（支持 HTML）

请求参数

scope string (query) 命名空间名称
title string (optional) 笔记标题，不传则自动生成

cURL 示例

# 方式一：纯文本 Body（推荐）
curl -X POST "/api/notes/create?scope=skill" \
  -H "Content-Type: text/plain" \
  -d '<p>这是笔记内容</p><p>支持 HTML 标签</p>'

# 方式二：Form 格式
curl -X POST "/api/notes/create" \
  -d "scope=skill" \
  -d "title=我的笔记" \
  -d "content=<p>笔记内容</p>"
            

响应示例

{ "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.txt

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

更新笔记

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

05

注意事项

Scope 隔离
不同 scope 之间的笔记完全隔离。每个 scope 下只有一条笔记（ID = 1）。
大小限制
单条笔记最大 10MB。超过限制将无法保存。
WebSocket 同步
笔记保存成功后，会通过 WebSocket 广播 content_updated 通知。连接地址：/ws
内容格式
笔记内容以纯文本形式存储，支持 HTML 标签。前端使用 WangEditor 进行富文本编辑。
保留关键字
以下名称不能作为 scope：api、static、ws、 websocket、admin、system