qingyu-note-desktop-api

name	qingyu-note-desktop-api
description	轻羽云笔记、本机笔记 API、49152、local note API。在 Cursor、OpenClaw、Claude Code、Hermes Agent 中 通过 http://127.0.0.1:49152 读写桌面版本机笔记：列出、读取、创建、更新、移入回收站。

轻羽云笔记本机 API（Agent Skill）

本 Skill 独立于任何笔记应用分发，仅描述固定本机 HTTP 约定。用户需在桌面端运行兼容该 API 的客户端（如轻羽云笔记），并在其 Agent 设置 中开启本机 API。

安装路径见仓库 README。

连接参数（固定）

参数	值
Base URL	http://127.0.0.1:49152（请用 127.0.0.1，勿改用其他 host）
认证	Authorization: Bearer <token>

端口与 Base URL 已写死，不要修改或猜测。

首次使用

1. 向用户索取 Token（必填）。说明：请在兼容客户端（如轻羽云笔记）桌面端 设置 → Agent 设置 复制「连接 Token」并提供给你；勿发到公开渠道。Token 仅用于当前任务，勿写入 Skill 目录、Git 或 Issue。
2. 确认用户已 开启本机 Agent API。
3. 验证连通：

curl -sS -H "Authorization: Bearer <token>" http://127.0.0.1:49152/v1/health

4. 后续请求附加 Authorization: Bearer <token>；POST / PATCH 另加 Content-Type: application/json。

推荐调用顺序

1. GET /v1/health
2. GET /v1/notes 获取 id（列表无 content，且仅为当前可读、未在回收站的笔记子集）
3. GET /v1/notes/{id} 读正文后再 PATCH / DELETE

路径与方法以同目录 openapi.yaml 为准。笔记 id 必须为列表或详情返回的字符串（通常为 UUID），勿自行编造。

响应结构

笔记字段

字段	类型	说明
id	string	笔记 ID
title	string	标题
content	string	Markdown 正文（仅详情接口返回；可能含图片链接等，无单独上传 API）
tags	string[]	标签
user_created_time	int	创建时间，毫秒时间戳
user_updated_time	int	更新时间，毫秒时间戳

各接口

接口	响应要点
GET /v1/health	{ "ok": true, "version": "..." }
GET /v1/notes	{ "notes": [ ... ] }，元素无 content
GET /v1/notes/{id}	单条笔记对象（含 content）
POST / PATCH	{ "note": { ... }, "sync": { "success": bool, "message": string } }
DELETE	{ "ok": true, "message": "...", "sync": { ... } }（移入回收站，非永久删除）

sync 字段

写入类操作成功后，响应可能含 sync。sync.success: false 表示云同步失败，不表示本地笔记未创建/未更新；是否告知用户、是否重试由你判断，勿因此否认本地操作已成功。

错误响应

HTTP 4xx/5xx 时 body 通常为：

{ "error": "<code>", "message": "<human-readable>" }

请将 message 转述给用户（403 时不要自行猜测限制原因）。

写入请求体

POST / PATCH 使用 JSON；各字段均可省略（POST 可发送 {}）。

• title：字符串
• content：字符串（Markdown）
• tags：字符串数组

PATCH：只传要改的字段；若传 tags，会整包替换原标签列表（非增量合并）。改标签前应先 GET 读出原 tags 再合并后写回。

失败时如何处理

情况	处理
连接被拒绝、超时、非 JSON	桌面端未运行、API 未开启或地址错误；先确认应用已启动且已开启本机 API，再核对 Token
401	Token 无效；请用户从客户端 Agent 设置 重新复制 Token
400	请求 JSON 非法；检查 body 格式，不要让用户改 Token
403	将 message 转述给用户，请其在 Agent 设置 中开启对应能力；勿猜测具体限制
404	笔记不存在或当前不可读；勿断言「用户一定删了笔记」
503	本机 API 未开启；请用户在 Agent 设置 中开启
500	服务端异常；可重试或让用户重启桌面端

安全

• 勿将 Token 写入仓库、Skill 文件或公开讨论。
• 仅访问 127.0.0.1；勿将本机 API 暴露到公网。