核心用法
Fulcra Annotations 是一个用于与 Fulcra Life API 交互的代理技能，专注于创建、记录和管理用户自定义数据注释。它支持四种核心注释类型：
- Moment: 纯事件记录（如"完成某事"）
- Boolean: 是/否状态
- Numeric: 数值计数或测量值
- Scale: 主观评分量表（如 1-5 分专注力）
工作流程遵循"定义→记录→验证"的闭环：先通过 list 检查现有定义，必要时用 create 创建，再用 record 写入数据，最后通过 recent 或脚本返回的 verified_matches 确认写入成功。
显著优点
1. 安全优先设计: 强制通过脚本工具调用，避免手写 curl 泄露 token；支持设备码 OAuth 流程，凭证隔离于聊天环境外
2. 数据完整性保障: 每次写入后自动回读验证（verified_matches >= 1 才确认成功），防止"假成功"状态
3. 灵活的标签系统: 区分定义级标签（稳定分类）和记录级标签（单次上下文），支持自动创建与解析
4. 历史数据支持: 完整的 ISO-8601 时间戳支持，可进行回溯补录
5. 幂等写入模式: 内置去重键与本地账本机制，适合自动化流水线
潜在局限
- Duration 类型支持有限: 文档明确说明 duration 注释仅部分支持，建议使用其他类型替代
- 依赖 Fulcra 生态: 必须拥有 Fulcra 账号并完成 OAuth 授权，存在第三方服务依赖
- 学习曲线: 需要理解 annotation definition vs record、tag 分层、时区处理等概念
- 无可视化内置: 需配合 Context App 或自建仪表板查看数据
适合人群
- 个人量化自我（Quantified Self）实践者: 追踪习惯、症状、情绪、专注度等
- 代理工作流开发者: 构建需要持久化记忆的 AI 代理系统
- 健康/研究数据记录: 需要结构化、可验证的时间序列数据输入
- 自动化极客: 希望将外部事件流（日历、IoT、代码提交）沉淀为可查询的记忆
常规风险
| 风险类别 | 说明 | 缓解措施 |
|---------|------|---------|
| 凭证泄露 | Token 误入聊天记录 | 强制使用 `uv tool run` 脚本，禁止直接 curl |
| 数据误删 | 更新/删除定义不可逆 | 必须用户显式批准，建议先 dry-run |
| 时区混淆 | 本地时间与 UTC 转换错误 | 始终带偏移量写入，接受 UTC 回读 |
| 重复记录 | 自动化任务重试导致重复 | 使用幂等写入模式与本地账本 |
| 隐私暴露 | 演示场景泄露真实数据 | 默认使用合成数据，需显式授权才用真实值 |
使用建议
首次使用建议采用"快速有用循环"模式：选择 1-2 个具体指标（如"今日咖啡数"或"专注度评分"），完成一次端到端的创建-记录-验证流程，让用户看到数据实际出现在 Fulcra 中，再逐步扩展。避免一上来就问"你想追踪什么"这种开放式问题。