Fulcra Annotations 技能评估
核心用法
Fulcra Annotations 是一套用于向 Fulcra Life API 写入结构化个人数据的 agent 工具集，支持创建可复用的标注定义（如「专注度」「咖啡杯数」）和记录具体的数据实例。核心类型包括：
- moment（时刻）：无值事件，如「开始深度工作」
- boolean（布尔）：是/否状态
- numeric（数值）：计数或测量值，支持单位元数据
- scale（量表）：1-5 等主观评分，可配置标签映射
操作分为两层：定义层（create/update/delete）使用 CLI 的 data-type 命令或 Python 辅助函数；记录层（record）通过 ingest API 写入，需配合 readback 验证（verified_matches >= 1 才视为成功）。支持标签系统区分「定义标签」（稳定分类）与「记录标签」（单次上下文），以及历史时间戳的精确回写。
显著优点
1. 类型安全与验证闭环：写入后强制 readback 验证，避免「HTTP 200 但数据丢失」的静默失败
2. 灵活的标签与元数据：双层标签系统支持复杂查询场景，自动解析/创建标签降低使用门槛
3. 历史数据补录：完整支持 --recorded-at 回写，适合批量导入或延迟记录
4. 幂等写入模式：内置的「本地账本 → 去重键 → 状态机（pending/verified/failed）」模式，适合自动化 pipeline
5. 与 Fulcra 生态深度整合：记录数据可直接在 Context iOS/Web 中可视化，与位置、健康、日历等原生数据流并列
潜在缺点与局限
- CLI 功能缺口：Fulcra CLI 0.1.35 仍缺少原生的 record write/delete/replace 命令，必须依赖 ingest API 和自定义脚本
- duration 类型支持不全：文档明确建议暂用 moment/numeric/scale 替代，直到上游 schema 稳定
- 认证流程较重：需要完整的 OAuth 设备流（非 API key），远程 agent 场景需保持进程存活并安全传递 device code
- 安全约束严格：禁止在聊天中打印 token、原始记录或 capability URL，调试时需额外注意
- 学习曲线：需要理解「定义 vs 记录」「标签解析」「时区处理」「验证状态」等多个抽象概念
适合人群
- 自我量化（Quantified Self）实践者：希望将 agent 交互转化为可分析的个人数据流
- 人机协作工作流设计者：需要记录「何时请求了 agent 的新能力」等元事件以优化提示策略
- 健康/习惯追踪用户：替代或补充专用 app，统一存储于 Fulcra 的免费 5GB 个人数据空间
- 自动化 pipeline 开发者：利用幂等写入模式和 ledger 状态机构建可靠的批量标注系统
常规风险
| 风险类别 | 具体描述 |
|---------|---------|
| 数据完整性 | 网络超时或 ingest 延迟可能导致「假成功」，必须依赖 readback 验证 |
| 时区处理 | 相对时间（如「昨天 10 点」）需显式解析为用户本地时区， naive 时间会导致记录偏移 |
| 标签污染 | 标签用于过滤而非备注，误用（如放入人名、详细描述）会降低查询效率 |
| 认证泄露 | device code 和 auth URL 必须通过「活跃可信用户通道」传递，不可暴露在公开日志 |
| 重复记录 | 自动化场景缺少本地账本时，重试机制会产生重复数据 |
安全等级说明
该技能涉及个人敏感数据的写入和 OAuth 认证流程，但设计上有明确的 token 隔离、readback 验证和敏感信息输出禁令。CLI 和脚本均支持通过 FULCRA_ACCESS_TOKEN 或本地凭证文件认证，不强制要求硬编码密钥。综合评估为 S 级（需用户显式授权，数据流可控，无已知高危漏洞模式）。