核心用法
Fulcra Annotations 是一个面向个人量化与生活记录的 API 封装工具，允许用户通过命令行脚本创建可复用的"标注定义"（如专注度评分、咖啡计数、症状检查），并记录具体事件或数值。核心类型包括：
- moment：纯事件记录（"发生了某事"）
- boolean：是/否状态
- numeric：可计量的数值（支持 count、weight、duration 等单位）
- scale：1-5 等主观评分量表
脚本优先于裸 curl，因为它自动处理 token 安全、payload 构建和写入验证。典型工作流：确定类型 → list 查重 → create 创建定义 → record 记录数据 → recent 验证回读。
显著优点
1. 写入即验证：每次 record 后自动调用 readback，确认 verified_matches >= 1 才视为成功，避免"假成功"写入。
2. 标签系统灵活：支持定义级标签（稳定分类如 health）和记录级标签（单次上下文如 manual-test），自动解析/创建标签 ID。
3. 历史数据友好：支持 --recorded-at 写入任意过去时间点，ISO-8601 带时区，适合补录或批量迁移。
4. 幂等写入模式：提供账本驱动的去重机制，适合自动化流水线，防止重复记录。
5. 隐私优先设计：token 和原始记录绝不进入聊天；设备授权码仅通过可信渠道发送给用户本人。
潜在局限
- duration 类型支持有限：官方文档未明确 duration 的 ingest 格式，建议暂用 moment/numeric 替代。
- CLI 依赖：需本地安装
fulcra-apiCLI 或通过uv tool run运行，远程/无头环境需保持进程等待用户授权。 - iOS 生态为主：移动数据（生物识别、位置、日历）需安装 Context iOS 应用；Android 版本即将推出。
- 无原生持久化去重：幂等模式依赖外部账本或本地状态，脚本本身不维护跨会话的写入历史。
适合人群
- 量化自我（Quantified Self）实践者，希望统一追踪健康、习惯、情绪指标
- 需要为 AI agent 构建"记忆"的开发者，让人机共享结构化生活数据
- 从其他量化工具（如 Apple Health、Notion 数据库）迁移数据的用户
- 希望用代码自动化记录（如「每次提交代码时记录专注度」）的技术用户
常规风险
- 数据完整性风险：历史写入若未验证，可能因时区/格式问题导致记录丢失或错位。
- 隐私泄露风险：尽管脚本设计避免打印 token，但用户误操作（如
measurement-schema --raw粘贴到公开频道）可能暴露账户上下文。 - 误删除风险：
delete和update操作需显式用户确认，但自动化脚本若跳过确认逻辑可能造成批量误删。 - 验证竞态条件：高并发写入时，
record的自动验证可能因读回延迟而误判失败，需手动重试recent确认。