Fulcra Annotations

核心用法

Fulcra Annotations 是一个面向生活化数据追踪的写入型技能，允许 AI Agent 与用户协作创建自定义标记定义（如"专注力评分""咖啡计数"）并记录具体事件或数值。核心概念包括：

• Annotation definition：可复用的标记模板，通过 create 命令定义类型（moment/boolean/numeric/scale）和元数据
• Annotation record：单次记录，通过 record 命令写入，支持即时或历史时间戳
• Tag 系统：定义标签（稳定分类）与记录标签（单次语境）双层架构，支持自动解析与创建

典型工作流程：确定追踪类型 → 检查现有定义 → 创建或更新定义 → 记录数据 → 回读验证（verified_matches >= 1）→ 向用户确认。

显著优点

1. 安全优先设计：强制通过脚本封装 API 调用，禁止在对话中暴露 token、凭证或原始 Fulcra 记录；设备授权 URL 仅通过可信通道传递
2. 类型丰富：支持无值时刻（moment）、二元开关（boolean）、数值计数（numeric）、1-5 量表（scale）四种核心类型
3. 自动化友好：内置幂等写入模式，支持历史回填、去重键管理和账本式状态追踪
4. 生态整合：与 Fulcra Context iOS 应用共享账户与存储，移动端 context（位置、健康、日历）可与 Agent 写入数据融合
5. 验证闭环：每次写入后强制回读验证，避免"HTTP 200 即成功"的误判

潜在缺点与局限

• Duration 类型支持不完整：官方文档未明确摄入格式，skill 建议暂用其他类型替代
• 账户依赖：需 Fulcra 账户认证，非纯 API key 模式，首次使用需完成 OAuth 设备流
• 时区处理责任：历史记录需调用方自行解析用户时区并生成带偏移的 ISO-8601 时间戳
• Android 支持待发布：移动端生态目前仅限 iOS

适合人群

• 量化自我（Quantified Self）实践者，希望将主观状态（专注度、情绪）与 Agent 协作记录
• 需要构建个人或小型团队 context 记忆系统的开发者
• 希望打通 AI Agent 与移动端生活数据（健康、位置、日历）的进阶用户

常规风险

• 数据隐私：记录内容可能包含敏感健康或行为数据，需确保 Fulcra 账户安全
• 误操作覆盖：update 和 delete 需用户显式确认，避免自动化流程意外修改定义
• 时区/时间解析错误：历史记录若时区处理不当，可能导致数据时间错位
• 演示泄露风险：公开场景下默认使用合成数据，需用户明确授权方可展示真实记录

该技能特别适合构建"用户发起 → Agent 执行 → 双向验证 → 长期追踪"的个性化数据闭环，是 Fulcra 生态中连接 AI 与现实语境的关键写入组件。

核心用法

Fulcra Annotations 是一套用于创建、记录和管理个人生活数据的 Agent 技能。它通过 Fulcra Life API 实现人机共享的记忆系统，让 Agent 能够安全地读写用户的真实世界上下文——包括注意力状态、事件记录、健康数据、地理位置等多维信息流。

该技能支持四种核心标注类型：Moment（时刻）用于记录"某事发生"的简单事件；Boolean（布尔）用于 yes/no 型追踪；Numeric（数值）用于计数或测量数据；Scale（量表）用于 1-5 等主观评分。用户可通过 CLI 工具 fulcra-api 完成认证后，使用封装好的 Python 脚本创建标注定义、记录数据点，并自动完成读写验证。

典型工作流包括：确定追踪目标（如"每日专注度"或"咖啡摄入量"）→ 检查是否已有定义 → 创建标注定义（含类型、标签、默认值）→ 记录实时或历史数据点 → 通过 recent 命令验证写入成功。技能特别强调使用 --recorded-at 处理历史数据，并支持通过 --tag 为定义和单条记录附加分类标签，实现灵活的数据组织。

显著优点

安全架构设计是该技能的首要亮点。凭证通过环境变量 FULCRA_ACCESS_TOKEN 或 Fulcra CLI 获取，脚本内置多层保护：禁止在聊天中打印令牌、强制 HTTPS 通信、30秒超时机制，且所有敏感操作均需用户明确授权。纯 Python 标准库实现零外部依赖，彻底规避了供应链攻击风险。

验证闭环机制确保数据可靠性——每次写入后自动执行 readback 验证，仅当 verified_matches >= 1 时才确认成功，避免"虚假成功"状态。这种设计对自动化管道尤为重要，配合幂等写入模式（基于稳定去重键的本地账本），可实现安全的数据回溯与批处理。

人机协作体验经过精心优化。新手引导模式提供 2-3 个具体选项而非开放式提问，快速建立首个可用标注循环；标签系统支持定义级与记录级双层分类，时间戳处理自动解析用户本地时区；与 Fulcra Context iOS 应用的数据互通，让移动端采集与 Agent 端分析形成完整闭环。

潜在缺点与局限性

认证流程的复杂性可能对部分用户形成门槛。Fulcra 采用 OAuth 设备授权流，需在浏览器中完成授权，对于纯终端环境或无桌面设备的场景不够便捷。远程 Agent 需保持 CLI 进程存活并中转授权 URL，增加了部署复杂度。

功能边界的限制需要注意。Duration（时长）类型标注当前仅部分支持，官方建议暂用 Moment/Boolean/Numeric/Scale 替代；测量单位体系虽已可扩展，但复杂场景仍需手动查阅 schema 或等待脚本更新，不如直接 API 调用灵活。

生态依赖度较高。该技能深度绑定 Fulcra 平台，数据存储于 Fulcra 云端（免费 5GB），虽降低了自建基础设施的成本，但也意味着长期使用需信任该平台的持续运营。与其他数据系统（如 Apple Health、Google Fit）的直连互通能力取决于 Fulcra 官方集成进度。

适合的目标群体

量化自我（Quantified Self）实践者是最匹配的用户群——希望系统追踪专注度、情绪、症状、习惯养成等主观指标，并需要 Agent 协助分析模式、生成洞察的个人用户。

自动化工作流构建者将受益于其幂等写入和验证机制——开发者可搭建定时任务（如每日自动记录屏幕时间摘要）、跨应用数据同步管道，或基于标注事件触发其他 Agent 行为。

人机协作研究团队可利用其共享记忆特性——研究者设计标注协议，Agent 执行标准化数据收集，双方在统一数据层上协作，减少格式转换与传输损耗。

常规使用风险

性能与稳定性方面，API 调用依赖网络连接，30秒超时设置在弱网环境可能导致偶发失败；建议关键流程实现指数退避重试。Fulcra 免费账户的 5GB 存储对高频标注长期积累可能吃紧，需监控使用量或考虑数据归档策略。

依赖项风险虽因零外部依赖而极低，但 Fulcra CLI 工具本身的更新可能引入行为变更，建议锁定版本或关注官方变更日志。Python 版本兼容性方面，脚本使用 urllib.request 等标准库，理论支持 Python 3.6+，但建议在生产环境明确测试目标版本。

数据隐私考量虽已通过 GDPR 数据最小化检查，但用户仍需注意：标注内容本身（如"头痛发作"、"焦虑评分 5"）属于敏感健康信息，在共享演示或日志输出时需脱敏处理。技能文档明确要求公开演示使用合成数据，此规范应严格遵守。

配置安全风险集中在 FULCRA_CLI_COMMAND 环境变量——若该变量被恶意注入，可能导致任意命令执行。建议部署时通过只读环境或配置管理工具锁定该变量，拒绝包含 shell 元字符的输入。