Fabric.co API skill

核心用法

Fabric API 技能用于读写 Fabric 工作空间内容，基于官方 HTTP API (api.fabric.so)。提供跨平台调用方案：

• Node 脚本 (fabric.mjs)：推荐方案，依赖现代 fetch
• Python 脚本 (fabric.py)：备用方案

关键调用模式：

• 创建笔记 → POST /v2/notepads（注意：无 /v2/notes 端点）
• 创建文件夹 → POST /v2/folders
• 创建书签 → POST /v2/bookmarks
• 搜索内容 → POST /v2/search
• 浏览目录 → POST /v2/resources/filter

字段映射陷阱：用户说"title" → API 需用 name；tags 必须是对象数组 [{"name":"tag"}]，非字符串数组。

显著优点

• 原生跨平台：不依赖 bash 包装脚本，Windows/macOS/Linux 一致体验
• 结构化输出：自动 JSON 解析，错误时仍返回响应体便于调试
• 认证隔离：通过 FABRIC_API_KEY 环境变量注入，避免密钥泄露到提示词
• 别名支持：@alias::inbox、@alias::bin 简化默认位置指定
• 调试友好：OpenAPI 规范随包提供，本地可离线查阅

潜在缺点与局限

• API 设计反直觉：notepads vs notes 命名混淆；parentId 在不同端点要求 UUID 或别名不一致
• 标签格式严格：嵌套数组或字符串标签会导致 400 错误，需手动转对象数组
• 无内置重试：429 限流、5xx 错误需调用方实现退避逻辑
• 创建操作幂等性弱：盲目重试可能产生重复资源
• 依赖外部运行时：需 Node ≥18 或 Python 3.x，纯浏览器环境不可用

适合人群

• Fabric 重度用户，需自动化笔记归档、批量导入导出
• 跨平台开发者（Windows 团队与 macOS 团队共享同一套调用脚本）
• 构建与 Fabric 集成的第三方工具/工作流的自动化工程师
• 对 bash 不熟悉的用户，偏好 Node/Python 生态

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 密钥泄露 | API key 硬编码于配置或脚本 | 仅用 `FABRIC_API_KEY` 环境变量，禁止写入日志 |

| 数据误删 | 错误的 `parentId` 或批量操作 | 先执行只读查询验证路径，生产操作前备份 |

| 限流中断 | 429 响应未处理导致任务失败 | 读操作指数退避重试，写操作失败即停人工介入 |

| 格式错误 | `tags`/`name` 字段类型不符 | 对照 `fabric-api.yaml` 验证 payload 结构 |

| 网络中间人 | API 调用被劫持或伪造 | 验证 TLS 证书，勿使用 `FABRIC_BASE` 指向非官方域名 |