核心用法
Fulcra Annotations 是一套面向个人生活数据追踪的技能，允许 AI 助手通过 Fulcra Life API 创建注释定义（annotation definition）并记录具体事件（annotation record）。核心类型包括：
- moment：无值的"时刻"记录，用于标记事件发生在何时
- boolean：是/否类追踪
- numeric：计数或测量值（如咖啡杯数）
- scale：主观评分（如 1-5 专注度）
工作流程遵循"先查后建"原则：运行 list 检查现有定义 → 必要时用 create 创建 → 用 record 记录数据 → 通过 recent 或返回值中的 verified_matches 确认写入成功。
显著优点
1. 人机共享记忆：注释数据可在 Fulcra Context iOS App 中同步查看，实现跨设备、跨代理的上下文共享
2. 类型安全：脚本封装了 Fulcra 的 UUID 解析、标签管理、时区转换和载荷构建，避免手写 curl 的 token 泄露风险
3. 写入确认机制：不依赖 HTTP 204 即认为成功，必须通过 readback 验证 verified_matches >= 1
4. 灵活的标签系统：支持定义级标签（稳定分类）和记录级标签（单次上下文），自动创建缺失标签
5. 历史数据回填：支持 --recorded-at 写入过去时刻，配合 ledger 模式可实现幂等批量导入
潜在缺点与局限性
- 认证门槛：需要 Fulcra 账户和设备授权流程，非纯 API key 模式
- 生态依赖：深度绑定 Fulcra 云服务，数据可移植性受限
- duration 类型支持不完整：文档明确建议暂时避免使用 duration 类型
- CLI 环境要求：依赖
uv和 Python 3，远程代理需维持 CLI 进程等待用户授权 - 删除/更新受限：定义元数据的修改需走单独的管理流程，日常 skill 仅暴露 CR 操作
适合人群
- 量化自我（Quantified Self）实践者，希望用结构化方式追踪习惯、症状、情绪或重要时刻
- 需要为 AI 代理建立长期记忆上下文的进阶用户
- 研究团队或健康追踪场景，需要可审计的事件日志
常规风险
- Token 泄露：虽然脚本设计将 token 隔离在进程环境，但远程部署仍需确保
FULCRA_ACCESS_TOKEN的机密性 - 时区错误：历史记录必须使用带偏移的 ISO-8601 时间戳， naive 本地时间会导致数据错位
- 重复写入：自动化场景需配合 ledger + dedupe key 模式，避免同一源事件产生多条记录
- 隐私边界：演示场景默认使用合成数据，真实健康/位置数据需显式用户授权后才可展示
安全设计亮点
- 强制 HTTPS 端点（
api.fulcradynamics.com），禁止 token 重定向到自定义主机 FULCRA_CLI_COMMAND白名单限制，防止命令注入- 设备授权码仅通过"活跃可信用户通道"传输，不留在日志或聊天中
- 原始凭证、refresh token、私有记录数据明确禁止打印到聊天