介绍
# Fabric API (HTTP via curl)
使用此技能通过 Fabric HTTP API (`https://api.fabric.so`) 在用户的 Fabric 工作区中读取/写入内容。
## 关键注意事项（请先阅读）
- “Notes”（笔记）是通过 **POST `/v2/notepads`**（而非 `/v2/notes`）创建的。 - 大多数创建端点都需要 **`parentId`**： - 一个 UUID **或** 以下之一：`@alias::inbox`、`@alias::bin`。 - Notepad（笔记本）创建需要： - `parentId` - 且需要 `text`（markdown 字符串）**或** `ydoc`（高级/结构化）。 - `tags` 必须是一个对象数组，每个对象必须 *要么*： - `{ "name": "tag name" }` 要么 `{ "id": "<uuid>" }` - 绝不能是嵌套数组；绝不能是字符串。
当用户未指定目标文件夹时：默认使用 `parentId: "@alias::inbox"`。
## 设置（Clawdbot）
此技能期望 API 密钥位于：
- `FABRIC_API_KEY`
推荐配置（使用 `apiKey`；Clawdbot 将注入 `FABRIC_API_KEY`，因为设置了 `primaryEnv`）：
```json5 { skills: { entries: { "fabric-api": { enabled: true, apiKey: "YOUR_FABRIC_API_KEY" } } } } ````
## HTTP 基础
* 基础地址：`https://api.fabric.so` * 认证：`X-Api-Key: $FABRIC_API_KEY` * JSON：`Content-Type: application/json`
用于调试时：优先使用 `--fail-with-body`，以便显示 4xx 响应正文。
## 标准 curl 模板（使用 heredocs 避免引用错误）
### GET
```bash curl -sS --fail-with-body "https://api.fabric.so/v2/user/me" \ -H "X-Api-Key: $FABRIC_API_KEY" ```
### POST (JSON)
```bash curl -sS --fail-with-body -X POST "https://api.fabric.so/v2/ENDPOINT" \ -H "X-Api-Key: $FABRIC_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "replace": "me" } JSON ```
## 核心工作流
### 1) 创建 notepad（笔记）
端点：`POST /v2/notepads`
* 将用户提供的“title”（标题）映射到 API 载荷中的 `name`。 * 始终包含 `parentId`。 * 使用 `text` 表示 markdown 内容。
```bash curl -sS --fail-with-body -X POST "https://api.fabric.so/v2/notepads" \ -H "X-Api-Key: $FABRIC_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "Calendar Test Note", "text": "Created via Clawdbot", "parentId": "@alias::inbox", "tags": [{"name":"calendar"},{"name":"draft"}] } JSON ```
如果标签导致验证问题，请将其省略，稍后通过 `/v2/tags` 创建/分配。
### 2) 创建文件夹
端点：`POST /v2/folders`
```bash curl -sS --fail-with-body -X POST "https://api.fabric.so/v2/folders" \ -H "X-Api-Key: $FABRIC_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "name": "My new folder", "parentId": "@alias::inbox", "description": null } JSON ```
### 3) 创建书签
端点：`POST /v2/bookmarks`
```bash curl -sS --fail-with-body -X POST "https://api.fabric.so/v2/bookmarks" \ -H "X-Api-Key: $FABRIC_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "url": "https://example.com", "parentId": "@alias::inbox", "name": "Example", "tags": [{"name":"reading"}] } JSON ```
### 4) 浏览资源（列出文件夹的子项）
端点：`POST /v2/resources/filter`
使用此端点列出文件夹内的内容（使用文件夹 UUID 作为 `parentId`）。
```bash curl -sS --fail-with-body -X POST "https://api.fabric.so/v2/resources/filter" \ -H "X-Api-Key: $FABRIC_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "parentId": "PARENT_UUID_HERE", "limit": 50, "order": { "property": "modifiedAt", "direction": "DESC" } } JSON ```
### 5) 搜索
端点：`POST /v2/search`
当用户提供模糊描述（例如“关于……的笔记”）时，使用搜索。
```bash curl -sS --fail-with-body -X POST "https://api.fabric.so/v2/search" \ -H "X-Api-Key: $FABRIC_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "queries": [ { "mode": "text", "text": "meeting notes", "filters": { "kinds": ["notepad"] } } ], "pagination": { "page": 1, "pageSize": 20 }, "sort": { "field": "modifiedAt", "order": "desc" } } JSON ```
## 标签（安全模式）
### 列出标签
`GET /v2/tags?limit=100`
### 创建标签
`POST /v2/tags` 并附带 `{ "name": "tag name", "description": null, "resourceId": null }`
### 在创建时分配标签
仅使用 `tags: [{"name":"x"}]` 或 `tags: [{"id":"<uuid>"}]`。
## 速率限制 + 重试
如果收到 `429 Too Many Requests`：
* 退避（sleep + 抖动）并重试。 * 避免紧密循环；缓慢进行分页。
如果没有幂等性，不要盲目重试创建请求（可能会创建重复项）。
## 故障排除快速对照表
* `404 Not Found`：几乎总是错误的端点、错误的 resourceId/parentId 或权限问题。 * `400 Bad Request`：模式验证；检查必填字段和标签格式。 * `403 Forbidden`：订阅/权限限制。 * `429 Too Many Requests`：退避 + 重试。
## API 参考
OpenAPI 模式位于此处：
* `{baseDir}/fabric-api.yaml`
如有疑问，请先查阅它，而不是猜测端点名称或载荷格式。