名称： fabric-api
描述： 通过 Fabric HTTP API 创建、搜索和管理 Fabric 资源（记事本/笔记、文件夹、书签、文件、标签）。
主页： https://fabric.so
元数据： {"openclaw":{"emoji":"🧵","homepage":"https://fabric.so","requires":{"env":["FABRIC_API_KEY"],"anyBins":["node","python3","python","curl"]},"primaryEnv":"FABRIC_API_KEY"},"clawdbot":{"emoji":"🧵","homepage":"https://fabric.so","requires":{"env":["FABRIC_API_KEY"],"anyBins":["node","python3","python","curl"]},"primaryEnv":"FABRIC_API_KEY"}}

Fabric API (通过 Node/Python 使用 HTTP)

当您需要使用 Fabric HTTP API (https://api.fabric.so) 读取或写入用户 Fabric 工作区中的内容时，请使用此技能。

此版本避免了仅限 bash 的包装脚本，提供了跨平台的辅助工具：

• Node: {baseDir}/scripts/fabric.mjs (推荐)
• Python: {baseDir}/scripts/fabric.py

关键注意事项（请先阅读）

• 捆绑的 OpenAPI 规范中没有 POST /v2/notes 端点。要创建“笔记”，请使用 POST /v2/notepads。
• 大多数创建端点都需要 parentId：
• 一个文件夹 UUID 或以下别名之一：@alias::inbox、@alias::bin
• 创建记事本需要：
• parentId
• 以及 text (Markdown 字符串) 或 ydoc (高级/结构化内容)
• tags 必须是对象数组，每个元素要么是：
• { "name": "标签名" } 要么 { "id": "<uuid>" }
• 不能是字符串，也不能是嵌套数组。
• 字段名注意点： API 模式使用 name (而非 title)。如果用户提到“标题”，请在请求中将其映射为 name。

当用户未指定目标文件夹时，默认使用：
- parentId: "@alias::inbox"

设置 (OpenClaw / Clawdbot)

此技能期望 Fabric API 密钥位于：
- FABRIC_API_KEY 环境变量中

OpenClaw 配置示例 (~/.openclaw/openclaw.json)：

{
  skills: {
    entries: {
      "fabric-api": {
        enabled: true,
        apiKey: "YOUR_FABRIC_API_KEY"
      }
    }
  }
}

注意：
- apiKey 是为声明了 primaryEnv 的技能提供的便利选项；它会在代理运行期间注入 FABRIC_API_KEY。
- 请勿将 API 密钥粘贴到提示词、客户端代码或日志中。

HTTP 基础

• 基础 URL：https://api.fabric.so (如有需要，可用 FABRIC_BASE 覆盖)
• 认证头：X-Api-Key: $FABRIC_API_KEY
• JSON 头 (用于 JSON 请求体)：Content-Type: application/json

便利脚本 (跨平台)

Node 辅助工具 (推荐)

node {baseDir}/scripts/fabric.mjs GET /v2/user/me

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"name":"测试笔记","text":"你好","parentId":"@alias::inbox"}'

Python 辅助工具

python3 {baseDir}/scripts/fabric.py GET /v2/user/me

python3 {baseDir}/scripts/fabric.py POST /v2/notepads --json '{"name":"测试笔记","text":"你好","parentId":"@alias::inbox"}'

注意：
- 两个辅助工具在成功时都会打印响应体。
- 遇到 HTTP 错误 (4xx/5xx) 时，它们会将 HTTP <状态码> <原因> 打印到 stderr 并仍会打印响应体，然后以非零状态退出 (类似于 curl --fail-with-body)。
- 如果传递绝对 URL (https://...)，辅助工具不会附加 X-Api-Key 头，除非显式传递 --with-key 参数。

核心工作流

1) 创建记事本 (笔记)

端点：POST /v2/notepads

规则：
- 将用户提到的“标题”映射为 name
- 使用 text 字段存放 Markdown 内容
- 始终包含 parentId
- 如果调试 400 错误，请从最简请求开始 (仅必需字段)，然后添加 name，最后再添加 tags。

最简创建：

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"parentId":"@alias::inbox","text":"你好"}'

创建并指定名称：

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"name":"日历测试笔记","text":"通过 OpenClaw 创建","parentId":"@alias::inbox"}'

创建并添加标签 (正确格式)：

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"name":"想法","text":"# 想法\\n\\n- 第一个\\n- 第二个\\n","parentId":"@alias::inbox","tags":[{"name":"ideas"},{"name":"draft"}]}'

如果持续遇到标签验证错误，请暂时省略 tags，先创建记事本。

2) 创建文件夹

端点：POST /v2/folders

node {baseDir}/scripts/fabric.mjs POST /v2/folders --json '{"name":"我的新文件夹","parentId":"@alias::inbox","description":null}'

3) 创建书签

端点：POST /v2/bookmarks

node {baseDir}/scripts/fabric.mjs POST /v2/bookmarks --json '{"url":"https://example.com","parentId":"@alias::inbox","name":"示例","tags":[{"name":"reading"}]}'

4) 浏览资源 (列出文件夹的子项)

端点：POST /v2/resources/filter

重要：
- 此端点的 parentId 期望一个 UUID (而非别名)。
- 如果只有别名，请通过列出资源根目录并选择收件箱/垃圾桶文件夹的 ID 来解析它。

node {baseDir}/scripts/fabric.mjs POST /v2/resources/filter --json '{"parentId":"PARENT_UUID_HERE","limit":50,"order":{"property":"modifiedAt","direction":"DESC"}}'

5) 搜索

端点：POST /v2/search

当用户给出模糊描述时（例如“关于...的笔记”）使用搜索。

node {baseDir}/scripts/fabric.mjs POST /v2/search --json '{"queries":[{"mode":"text","text":"会议记录","filters":{"kinds":["notepad"]}}],"pagination":{"page":1,"pageSize":20},"sort":{"field":"modifiedAt","order":"desc"}}'

错误处理与重试 (实用指南)

• 400 Bad Request: 模式验证错误。重新检查必填字段，并确保 tags 是 [{name}|{id}] 格式，而非嵌套。
• 401/403: 认证/订阅/权限错误。停止操作并报告错误详情；不要暴力尝试。
• 404: 端点错误、ID 错误或无权访问。
• 429: 速率限制。退避 (休眠 + 随机抖动) 后重试读取操作。避免对创建操作盲目重试 (可能导致重复创建)。
• 5xx: 临时性错误；使用退避策略重试。

参考文件

• OpenAPI 规范 (权威来源)：{baseDir}/fabric-api.yaml
• 额外模式说明：{baseDir}/references/REFERENCE.md
• 调试手册：{baseDir}/references/TROUBLESHOOTING.md