核心用法
Fulcra Annotations 是一个用于向 Fulcra Life API 写入结构化标注数据的技能。它支持四种核心标注类型：moment（事件标记）、boolean（是/否）、numeric（数值计数）和 scale（主观量表）。用户可通过 bundled Python 脚本完成定义创建、数据记录、历史补录和标签管理，无需手动构造 curl 请求。
典型工作流为：先用 list 检查定义是否存在 → 用 create 创建新定义（可附加标签）→ 用 record 记录实例（支持 --value 和 --recorded-at 历史时间戳）→ 脚本自动执行 readback 验证，确认 verified_matches >= 1 后才视为成功。
显著优点
1. 安全设计：脚本强制将 access token 隔离在环境变量或本地 CLI 配置中，禁止将凭证、refresh token 或原始 API 响应打印到聊天窗口；device auth URL 和 user code 仅通过活跃可信渠道发送给用户本人。
2. 写后验证：不依赖 HTTP 状态码判断成功，而是通过 recent 查询回读确认数据已落盘，避免静默失败。
3. 标签系统：支持定义标签（稳定分类）和记录标签（单次上下文），自动将名称解析为 UUID，并自动创建缺失标签。
4. 历史补录：支持任意 ISO-8601 时间戳（带时区偏移），适合回溯填写过去的事件或指标。
5. 幂等写入模式：文档提供 ledger-backed 的自动化管道最佳实践，含去重键、状态机和验证逻辑，适合批量回填或自动化场景。
潜在缺点与局限
1. 部分功能未成熟：duration 类型仅部分支持，官方文档未完全明确其 ingest 结构，建议暂用 moment/numeric 替代。
2. 时区处理责任在用户：脚本要求调用方将 "yesterday 10am" 等相对时间解析为带偏移的 ISO-8601，需外部处理时区逻辑。
3. CLI 依赖：必须安装并认证 Fulcra CLI（uv tool run fulcra-api），对于无 Python/uv 的环境需额外配置。
4. 无原生 API Key：需通过 OAuth device flow 完成账户级认证，无法使用简单的 API Key 集成。
适合人群
- 需要结构化追踪个人或团队指标（专注度、症状、工作量）的量化自我用户
- 构建自动化 agent 工作流、需将 agent 决策或外部事件写入共享记忆系统的开发者
- 希望将手机端 Context iOS 应用数据与桌面/服务器端脚本打通的跨端用户
常规风险
- 凭证泄露风险：虽脚本设计隔离 token，但用户若手动导出环境变量或截图分享终端，仍可能暴露
FULCRA_ACCESS_TOKEN。 - 误删与误更新：
update和delete操作需显式用户批准，但脚本本身无二次确认交互，依赖调用方（agent）实现确认逻辑。 - 时区/时间解析错误：若未正确处理夏令时或偏移符号，历史记录可能写入错误时间点，导致数据偏移。
- 隐私暴露：默认 readback 可能返回用户其他私有数据，技能文档明确限制仅输出必要字段（name、timestamp、value、note），但实现不当仍可能泄露敏感上下文。