核心用法
Fulcra Annotations 是 Fulcra Life API 的写入端封装技能，允许Agent在获得用户授权后，创建可复用的注解定义（如"专注度评分""咖啡计数"）并记录具体数值或事件。支持四种核心类型：moment（无值事件）、boolean（是/否）、numeric（数值计数）、scale（量表评级）。通过封装脚本fulcra_annotations.py实现，避免手动构造API调用，自动处理token安全、标签解析、时区转换和读回验证。
显著优点
1. 安全设计：强制使用脚本而非裸curl，access token不进入对话；设备授权URL仅通过可信用户通道发送
2. 防重与校验：创建前自动list查重，写入后强制读回验证（verified_matches >= 1），支持幂等写入模式
3. 灵活时区处理：自动解析"昨天10点"等相对时间，要求ISO-8601带偏移量，读回UTC可正确比对
4. 标签系统：definition标签（稳定分类）与record标签（单次上下文）分离，支持自动创建缺失标签
5. 历史回填：支持--recorded-at写入过去事件，适合补录或自动化管道
潜在缺点与局限
- duration类型支持不完整：官方文档未明确ingest格式，建议使用moment/boolean/numeric/scale替代
- 依赖本地CLI或环境变量：需预装
uv及fulcra-api工具，远程场景需保持进程等待用户授权 - 无原生批量写入：自动化管道需自建ledger实现幂等和批量控制
- 读回延迟：极端情况下需轮询
recent命令二次确认
适合人群
- 量化自我（Quantified Self）实践者：追踪专注度、症状、习惯等主观指标
- Agent工作流构建者：需要让AI助手代劳记录、形成人机共享记忆
- 健康/研究场景：需要结构化日志且注重数据主权和隐私的用户
- 自动化极客：愿意搭建ledger-backed管道进行历史数据回填
常规风险
- 授权凭证泄露：虽脚本防护完善，但用户可能误将token粘贴到聊天
- 时区歧义：未带偏移的"本地时间"可能导致记录时间错误
- 误删定义：
delete和update需显式用户批准，但误操作仍可能丢失历史分类体系 - 隐私暴露：演示场景需主动使用合成数据，否则可能泄露敏感健康/行为信息