# Agent API 使用指南

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

---

## Server URL

**Base URL:** `http://note.fangna.tech/`

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

---

## Scope 说明

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

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

### AI 隔离机制（UUID）

当多个 AI 或用户使用同一个 scope 时，内容会互相覆盖。为避免此问题，**建议在创建/读取笔记时带上 `uuid` 参数**。

系统会将 `uuid` 拼接到 scope 后，形成独立的存储空间：
- 传入 `scope=skill&uuid=abc123` → 实际存储到 `skill_abc123`
- 传入 `scope=work&uuid=xyz789` → 实际存储到 `work_xyz789`

**uuid 传递方式：**
- Query 参数：`?uuid=abc123`
- Header：`X-UUID: abc123`
- Agent 专用接口 Form 参数：`uuid=abc123`

> 不带 uuid 时保持原有行为不变，向后兼容。

---

## 用户访问地址（重要）

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

```
http://note.fangna.tech/{scope}
```

**正确示例：**
- `http://note.fangna.tech/skill`（Markdown 预览）
- `http://note.fangna.tech/work`（Markdown 预览）
- `http://note.fangna.tech/work.md`（直接编辑 Markdown 源码）

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

---

## 认证方式

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

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

---

## 读取笔记

### 获取笔记列表

```
GET /api/notes
```

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

**请求参数：**

| 参数  | 类型   | 说明                          |
|-------|--------|-------------------------------|
| scope | string | 命名空间名称，如 skill、work、study |

**cURL 示例：**

```bash
# 获取 skill scope 的笔记
curl -X GET "http://note.fangna.tech/api/notes?scope=skill"

# 或使用 Header 传递 scope
curl -X GET "http://note.fangna.tech/api/notes" \
  -H "X-Scope: skill"
```

**响应示例：**

```json
{
  "success": true,
  "message": "Notes retrieved successfully",
  "data": [
    {
      "id": 1,
      "title": "笔记标题",
      "content": "笔记内容（HTML格式）...",
      "scope": "skill",
      "updated_at": "2026-01-23 10:30:00"
    }
  ]
}
```

---

## 写入笔记

### 创建或覆盖笔记

```
POST /api/notes/create
```

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

**请求格式：**

- Content-Type: `text/plain` 或 `application/x-www-form-urlencoded`
- Body: 纯文本内容（Markdown 或 HTML）。Agent 建议写 Markdown 并显式带 `?format=md`

**请求参数：**

| 参数   | 类型   | 说明                                      |
|--------|--------|-------------------------------------------|
| scope  | string | 命名空间名称（query 参数）                |
| title  | string | 笔记标题，不传则自动生成                  |
| format | string | 可选。`md` / `markdown` 强制按 Markdown 存储；`html` 强制按 HTML 存储；**不传时自动识别**：含块级 HTML 标签按 HTML，否则按 Markdown |

**cURL 示例：**

```bash
# 方式一：写入 Markdown（推荐）
curl -X POST "http://note.fangna.tech/api/notes/create?scope=skill&format=md" \
  -H "Content-Type: text/plain" \
  -d '# 标题

这是 **Markdown** 内容'

# 方式二：写入 HTML（兼容旧客户端）
curl -X POST "http://note.fangna.tech/api/notes/create?scope=skill" \
  -H "Content-Type: text/plain" \
  -d '<p>这是笔记内容</p><p>支持 HTML 标签</p>'
```

> 写入格式决定最新版本的文件扩展名：Markdown → `note_*.md`，HTML → `note_*.txt`。
> 不传 `format` 时，系统会自动识别内容：包含 `<p>`、`<div>`、`<h1>`、`<table>` 等块级标签按 HTML 存储，否则按 Markdown 存储，避免 Markdown 被误存成 HTML。

**响应示例：**

```json
{
  "success": true,
  "message": "Note created successfully",
  "data": {
    "id": 1,
    "scope": "skill",
    "version": 42
  }
}
```

---

## 其他接口

### 版本历史

```
GET /api/versions?scope=skill
```

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

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

读取指定版本文件的内容。文件名必须匹配 `note_YYYYMMDD_HHMMSS.(txt|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 存储**（可用 `format=html` 覆盖）。

---

## 内容输出格式

读取接口（`GET /api/notes`、`POST /api/notes/get`、`GET /api/versions/content`）支持通过 `?format=` 参数指定返回格式，系统会按**存储格式**自动转换：

| 格式值                  | 说明                                                       |
|-------------------------|------------------------------------------------------------|
| `html`（默认）          | 可直接渲染的 HTML；Markdown 笔记会经 goldmark 渲染          |
| `markdown` / `md`       | Markdown；HTML 笔记会转换（保留图片）                      |
| `text` / `txt`          | 纯文本，去除所有标签                                       |

笔记响应中的 `content_format` 表示**存储格式**（`markdown` 或 `html`），与本参数（期望输出格式）相互独立。

---

## 注意事项

- **Scope 隔离：** 不同 scope 之间的笔记完全隔离。每个 scope 下只有一条笔记（ID = 1）。
- **大小限制：** 单条笔记最大 10MB。超过限制将无法保存。
- **WebSocket 同步：** 笔记保存成功后，会通过 WebSocket 广播 `content_updated` 通知。连接地址：`ws://note.fangna.tech/ws`
- **内容格式：** 存储为 `.md`（Markdown）或历史遗留 `.txt`（HTML）；写入接口未指定 `format` 时按内容自动识别，Agent 仍建议显式带 `?format=md`。
- **保留关键字：** 以下名称不能作为 scope：`api`、`static`、`ws`、`websocket`、`admin`、`system`、`skill`、`changelog`

---

> 本文档同时提供在线版本：`http://note.fangna.tech/skill` 和 Markdown 版本：`http://note.fangna.tech/skill.md`