核心用法
Fulcra Annotations 是 Fulcra 官方提供的量化自我（Quantified Self）基础设施技能，允许AI代理帮用户创建可复用的「记录按钮」并写入时间线数据。核心操作围绕两类对象：
1. Annotation Definition（定义）：用 create 创建可重复使用的指标模板，支持 moment（事件打点）、boolean（是/否）、numeric（数值计数）、scale（1-5主观量表）四种类型。定义可附加标签（tags）便于后续过滤。
2. Annotation Record（记录）：用 record 在特定时间点写入实际数据。支持实时记录（默认当前时间）或历史补录（--recorded-at 带时区），并可附加单次标签。记录成功后必须通过 verified_matches >= 1 的读回验证才算确认。
典型工作流：先 list 查重 → create 建定义（保存返回的 id/source_id）→ record 写数据 → recent 读回验证 → 向用户展示确认结果。
显著优点
- 官方原生集成：由 Fulcra 直接维护，API 路径与鉴权体系与 Fulcra CLI/iOS Context 应用完全一致，数据互通无摩擦。
- 安全设计优先：强制设备码 OAuth 登录，脚本不接收外部 token；成功写入必须通过读回验证，避免「假成功」。
- 类型丰富且可扩展：从简单「发生了」moment 到带刻度量表，覆盖大多数生活追踪场景；
measurement-schema命令暴露底层元数据供高级定制。 - 人机共享记忆：同一账户下，代理写入的数据可在 iOS Context 应用中实时查看，实现「代理记录、人类回顾」的协作闭环。
潜在缺点与局限
- 写入延迟与验证成本：ingest API 返回 204 仅为「已接收」，需额外
recent查询确认，批量写入时效率受限。 - Duration 类型支持不完整：官方明确建议暂用 moment/boolean/numeric/scale 替代，待文档完善后再迁移。
- CLI 功能缺口：Fulcra CLI 0.1.36 仍未暴露 record 的原生 write/delete/replace 命令，必须依赖 ingest 路径和自定义脚本。
- 时区处理责任：用户说「昨天10点」需代理自行解析为带偏移的 ISO-8601，误用 naive 时间会导致数据错位。
- Android 待支持：移动端仅 iOS，Android 用户暂无法使用 Context 应用同步。
适合人群
- 量化自我实践者：希望用结构化方式追踪专注度、症状、摄入量、情绪波动等。
- AI 工作流构建者：需要代理自动记录任务完成、决策节点或外部事件时间线。
- 健康/科研追踪用户：通过 scale 量表和 numeric 计数建立可分析的个人数据集。
- iOS 生态用户：已使用或愿意安装 Fulcra Context 应用查看可视化时间线。
常规风险
- 数据隐私：尽管脚本不打印 token，但 Fulcra 账户本身存储敏感生物、位置、健康数据，需确保账户密码与设备授权流程不被截屏或转发。
- 误操作覆盖：
update可修改定义元数据和标签，需显式用户批准；目前无delete暴露，但未来版本可能开放，需关注破坏性变更。 - 时间线污染：自动化流水线若未实现幂等（dedupe key + ledger），可能产生重复记录，污染后续分析。
- 演示泄露风险：公开场景下默认使用合成数据，真实健康/情绪值需用户明确授权方可展示。