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

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

此版本避免了仅限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）。如果用户提到“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":"Test note","text":"Hello","parentId":"@alias::inbox"}'

Python 辅助脚本

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

python3 {baseDir}/scripts/fabric.py POST /v2/notepads --json '{"name":"Test note","text":"Hello","parentId":"@alias::inbox"}'

注意事项：

• 两个辅助脚本在成功时都会打印响应体。
• 当发生 HTTP 错误（4xx/5xx）时，它们会向标准错误输出HTTP <状态码> <原因短语> 并且仍然会打印响应体，然后以非零状态码退出（类似于curl --fail-with-body命令的行为）。如果您传递一个绝对 URL（
• If you pass an absolute URL (https://...), 助手不会附加X-Api-Key除非您明确传递--with-key。

核心工作流程

1) 创建记事本（笔记）

端点：POST /v2/notepads

规则：

• 将用户“标题”映射为名称
• 使用文本作为Markdown内容
• 始终包含parentId
• 如果您正在调试400错误，请从最小化开始（仅必需字段），然后添加名称，接着添加标签。

最小化创建：

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

创建一个带有名称的记事本：

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"name":"Calendar Test Note","text":"Created via OpenClaw","parentId":"@alias::inbox"}'

创建带有标签的记事本（正确的格式）：

node {baseDir}/scripts/fabric.mjs POST /v2/notepads --json '{"name":"Ideas","text":"# Ideas\\n\\n- First\\n- Second\\n","parentId":"@alias::inbox","tags":[{"name":"ideas"},{"name":"draft"}]}'

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

2) 创建一个文件夹

端点：POST /v2/folders

node {baseDir}/scripts/fabric.mjs POST /v2/folders --json '{"name":"My new folder","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":"Example","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":"meeting notes","filters":{"kinds":["notepad"]}}],"pagination":{"page":1,"pageSize":20},"sort":{"field":"modifiedAt","order":"desc"}}'

错误处理 + 重试（实用指南）

• 400 错误请求：模式验证失败。请重新检查必填字段，并确保标签是[{名称}|{ID}]且非嵌套结构。
• 401/403：认证/订阅/权限问题。停止操作并报告错误详情；不要暴力尝试。
• 404：端点错误、ID错误或无访问权限。
• 429：请求频率超限。采用退避策略（延迟+随机抖动）后重试读取类操作。避免对创建类操作盲目重试（可能导致重复创建）。
• 5xx 错误：临时性错误；采用退避策略重试。

参考文件

• OpenAPI规范（唯一可信源）：{baseDir}/fabric-api.yaml
• 补充架构说明：{baseDir}/references/REFERENCE.md
• 调试手册：{baseDir}/references/TROUBLESHOOTING.md