Fulcra 注解

当用户希望代理创建、记录或验证 Fulcra 注解时，请使用本技能。

Fulcra 为代理及其人类用户提供作用域明确、安全的现实世界上下文与共享人/代理记忆（包括注意力、事件、位置、日历、健康、可穿戴设备及其他数据流）的读写权限。本技能用于该闭环中的“写入”环节：创建可复用的注解定义，并记录经用户批准的时刻或数值。

代理应优先使用配套脚本。除非脚本缺失必需功能，否则请勿手动编写 curl 调用——因为脚本可避免访问令牌暴露于聊天中，确保 Fulcra 数据摄入载荷格式一致，并执行回读验证。

首次运行引导模式

当用户初次接触 Fulcra 注解时，应优化实现快速、有价值的闭环：选择一个具体事项进行追踪，创建一至两个定义，记录一个真实数据点，完成验证，并向用户展示当前已存在的内容。

1. 从简短、具象的提示开始。不要仅问“你想追踪什么？”，而应基于用户上下文提供 2–3 个具体选项，例如每日专注度评分、咖啡饮用次数、症状自查、锻炼强度，或重要事件的时刻日志。
2. 仅在明确使用场景后才检查认证状态。若 uv tool run fulcra-api user-info 失败，则运行 uv tool run fulcra-api auth login，保持 CLI 进程活跃，并仅通过可信用户通道发送设备 URL/验证码。
3. 将使用场景转化为 1–3 个注解定义。优先选用最简类型以准确捕捉信号：moment 表示事件发生，boolean 表示是非判断，numeric 表示计数或测量值，scale 表示主观评分。
4. 执行 create 前先运行 list 避免重复。若需创建多个定义，请在工作笔记中保存每次 create 返回的 annotation.id、source_id 及类型，以便后续 record 步骤无需再次查询。
5. 对首次记录仅提出一个直接问题；必要时调用 record --id ... 并传入 --value。仅当 verified_matches >= 1 时，方可确认写入成功。
6. 交接时，应汇总定义名称、精确写入时间戳，以及一项自然的后续操作。若生成演示制品，请使用合成数据或经明确授权的真实数据，并确保私有记录不进入聊天上下文。

核心概念

• 注解定义：可复用的按钮/指标定义，例如 Focus 或 Asked Agent to Do Something New。通过 create 创建一次。
• 注解记录：某定义的一次已记录事件/数值。通过 record 写入。
• 时刻注解（Moment annotation）：无值的事件。适用于“此事已发生”类日志。
• 布尔型/数值型/量表型注解：类指标记录，需传入 --value。
• 定义标签（Definition tags）：存储于注解定义上的可复用标签。创建定义时通过重复使用 create --tag 添加。
• 记录标签（Record tags）：存储于单条记录上的标签。记录时通过重复使用 record --tag 添加。
• 标签解析（Tag resolution）：Fulcra 以 UUID 形式存储标签 ID。脚本支持传入标签名或 UUID，自动将标签名解析为 ID，并在标签名不存在时自动创建。
• 历史记录（Historical record）：事件时间非当前时刻的任何记录。必须始终传入 --recorded-at。
• 已确认写入（Confirmed write）：仅当回读结果中 verified_matches >= 1 时，记录才视为已确认。

安全规则

• 切勿在聊天中打印访问令牌、刷新令牌、原始私有 Fulcra 记录、凭据文件或直接能力 URL。
• 经认证的 API 调用严格限定于 https://api.fulcradynamics.com；不得将 Fulcra Bearer Token 重定向至自定义 API 主机。
• FULCRA_CLI_COMMAND 仅限标准 Fulcra CLI 调用（uv tool run fulcra-api、fulcra-api 或以 fulcra-api 结尾的可信绝对路径）。
• 设备认证 URL 和用户代码仅可在目标用户需从其他设备授权 Fulcra 访问时使用；且仅能通过活跃的可信用户通道发送。
• 删除或更新现有注解定义前，必须征得用户同意。
• 公开演示中，除非用户明确批准使用真实数据，否则请使用合成的注解名称/值。
• 不得仅凭 HTTP 状态码断言写入成功。须检查脚本返回结果并验证回读。
• 本技能对持续时间注解（Duration annotations）仅提供部分支持；在 Fulcra 明确文档化持续时间数据摄入格式前，请优先使用 moment/boolean/numeric/scale 类型。

认证

脚本在设置 FULCRA_ACCESS_TOKEN 时从可信密钥管理器令牌获取认证；否则，从本地已认证的 Fulcra CLI 命令获取认证，该命令由 FULCRA_CLI_COMMAND 配置。

Fulcra 要求已认证账户，而非 API 密钥。用户可通过 CLI 认证流程创建账户，永久免费享有 5 GB 存储空间。如需生物特征、位置、日历及其他移动上下文，用户可安装 Context iOS 应用并使用同一账户登录；该应用共享相同免费存储空间，且不再受订阅限制。Android 版本即将发布。

请首先完成认证：

uv tool run fulcra-api auth login

对于远程代理，请保持 CLI 进程运行，在聊天中通过活跃的可信用户通道向目标用户展示打印出的设备授权 URL 和代码，并等待其批准。用户可在任意设备的任意浏览器中打开该 URL。批准后，请使用非令牌命令（如 uv tool run fulcra-api user-info）验证认证状态；切勿将令牌粘贴至聊天中。

若凭据未位于进程 HOME 目录下，请设置 FULCRA_HOME=/path/to/home。

常用命令

创建新注解定义前，请先列出已有定义：

python3 skills/fulcra-annotations/scripts/fulcra_annotations.py list

创建一个时刻注解定义：

python3 skills/fulcra-annotations/scripts/fulcra_annotations.py create 
  --type moment 
  --name "Asked Agent to Do Something New" 
  --description "Logged when the user asks the agent to try a new category of work" 
  --tag agent 
  --tag new-task

多次使用 create --tag 可为定义附加多个标签。定义标签应为简短、稳定的标识，例如 agent、health 或 research。脚本会在发送 API 载荷前将标签名解析为 Fulcra 标签 ID。

立即记录一个时刻注解：

python3 skills/fulcra-annotations/scripts/fulcra_annotations.py record 
  --name "Asked Agent to Do Something New" 
  --note "User asked for a new annotation workflow" 
  --tag new-task

多次使用 record --tag 可为单条记录附加多个标签。若省略 record --tag，则该记录继承定义标签。若指定了 record --tag，则这些显式记录标签将被解析为 Fulcra 标签 ID 并随该记录一同发送。

记录一个历史时刻注解：

python3 skills/fulcra-annotations/scripts/fulcra_annotations.py record 
  --name "Asked Agent to Do Something New" 
  --recorded-at "2026-05-15T10:00:00-04:00" 
  --note "User asked for a new annotation workflow"

历史写入必须使用带时区的完整 ISO-8601 时间戳。若用户说“昨天上午 10 点”，请在其本地时区解析该时间，并显式传入时区偏移，例如 2026-05-15T10:00:00-04:00。Fulcra 回读可能显示等效 UTC 时间，例如 2026-05-15T14:00:00+00:00。

当名称存在歧义时，按注解 ID 记录：

python3 skills/fulcra-annotations/scripts/fulcra_annotations.py record 
  --id "" 
  --note "Logged from automation"

创建一个 1–5 量表注解定义：

python3 skills/fulcra-annotations/scripts/fulcra_annotations.py create 
  --type scale 
  --name "Focus" 
  --description "How focused do I feel right now?" 
  --scale-labels "1=Scattered,2=Low,3=Neutral,4=Focused,5=Locked In" 
  --default-value 3

创建一个数值计数注解：

python3 skills/fulcra-annotations/scripts/fulcra_annotations.py create 
  --type numeric 
  --name "Coffee Count" 
  --description "Number of coffees consumed today" 
  --measurement-type count 
  --tag health 
  --tag intake

对于具有专用单位的测量项，请先通过官方 CLI 或库检查实时 Fulcra Schema，再创建定义；并优先添加经评审的辅助支持，而非临时 API 调用。

记录一个量表/数值/布尔型值：

python3 skills/fulcra-annotations/scripts/fulcra_annotations.py record 
  --name "Focus" 
  --value 4 
  --note "Deep work block started well"

回读最近记录以验证：

python3 skills/fulcra-annotations/scripts/fulcra_annotations.py recent 
  --name "Asked Agent to Do Something New" 
  --hours 72 
  --limit 20

仅在获得用户明确批准后，通过独立评审的管理员工作流更新或删除定义元数据。配套辅助工具有意仅暴露 list、create、record 和 recent 四个命令。

发送任何写入前，请先执行空跑（dry-run）：

python3 skills/fulcra-annotations/scripts/fulcra_annotations.py record 
  --name "Focus" --value 4 --dry-run

工作流

1. 确定注解类型：moment、boolean、numeric 或 scale。对于“此事已发生”类场景，优先选用 moment。
2. 判断标签应置于定义、单条记录，还是两者皆有。
3. 运行 list 检查定义是否已存在。
4. 若现有定义需修改元数据或标签，请先请求用户批准，并使用 update --id ...；大规模重新打标前请先空跑。
5. 若定义缺失且用户要求创建/记录该注解，则运行 create。
6. 使用 record --name ... 或 record --id ... 进行记录。
7. 历史写入时，务必包含 --recorded-at "<带时区的 ISO-8601 时间戳>"。
8. 仅当脚本返回成功且 verified_matches >= 1 时，才信任写入已确认。
9. 若摄入返回 204 后验证失败，请稍作等待，再重新运行 recent --id 或 recent --name "" --hours 。
10. 报告精确写入时间戳及回读时间戳。切勿包含令牌、直接能力 URL 或不必要的私有记录数据。

演示与交接模式

在引导阶段，首个经验证的记录应带来微小的实际收益，而非干巴巴的“完成”消息。

• 在生成仪表板或制品前，提供 2–3 种可视化方向供用户选择。
• 将演示文件保留在工作区本地，避免将原始 HTML 或原始 Fulcra 记录倾倒至聊天中。
• 使用经验证的注解名称、时间戳、数值及简短解读。避免暴露无关的 Fulcra 数据。
• 使下一步操作具体可行：安装/打开 Context 应用以支持移动端记录、在 Context Web 中查看数据、添加另一项注解，或迭代优化仪表板。
• 在公开或群聊演示中，除非用户明确批准共享真实数值，否则请使用合成值。

幂等写入器模式

对于自动化或补录注解流水线，请采用仅追加、账本支持的写入器：

1. 将源事件规范化为稳定字段：注解名称/ID、事件时间戳、来源、严重性/类别、数值/备注，以及任何实际过滤维度。
2. 基于稳定源事实生成去重键（dedupe key）。将此键保留在本地状态、元数据或源端记账中；切勿将其置于可见的备注中。
3. 写入前检查本地账本：跳过 verified 条目，重试 pending 或 failed 条目，仅写入未见过的键。
4. 将摄入 HTTP 成功视为临时状态。须通过 record 输出或 recent 回读确认，并仅当 verified_matches >= 1 时才将账本标记为 verified。
5. 对于变更的源事件，除非变更具有实质性意义，否则应避免重复注解。更推荐为升级/解决添加后续注解，而非重写历史。

标签规则

• 使用定义标签对注解本身进行稳定分类，例如 health、agent、research 或 workflow。
• 使用记录标签表示仅适用于单次记录的上下文，例如 new-task、manual-test、backfill 或 user-requested。
• 通过 create --tag 添加定义标签。多次重复 --tag 可添加多个定义标签。
• 通过 record --tag 添加记录标签。多次重复 --tag 可添加多个记录标签。
• --tag 接受 Fulcra 标签名或现有标签 UUID。
• Fulcra 以 UUID 形式存储标签。脚本会将标签名解析为 UUID，并在标签名不存在时自动创建。
• 若省略 record --tag，则该记录使用定义标签。
• 若提供了 record --tag，则显式指定的记录标签将随该记录一同发送。
• 请使用小写、简短、可复用的标签。优先选用 new-task 而非完整句子。
• 标签应作为筛选维度，而非叙述性文本。对于地点，请优先使用实际地理信息，例如 town-springfield、village-riverside、neighborhood-downtown 或 place-main-campus，而非抽象标签如 scope-town 或 scope-neighborhood。
• 在必要时，将地点标签与类别/来源/严重性标签配对使用，例如 category-traffic、source-town-feed 或 severity-advisory。
• 切勿使用标签表示时间戳、详细备注、数值、人名、去重键或私有上下文。请分别使用 --recorded-at、--note、--value、--source 及本地元数据/账本状态。
• 经用户批准后，可使用 update --id ... --tag ... 对现有定义重新打标；--tag 将替换整个定义标签集。

时间戳规则

• 若省略 --recorded-at，脚本将在当前时刻记录注解。
• 若用户要求历史时间或类似计划的时间，请传入 --recorded-at。
• 解析“昨天上午 10 点”等相对表述时，请使用用户的本地时区。
• 时间戳中必须包含时区偏移。切勿传入无时区的本地时间（naive local times）。
• 预期回读时间为 UTC。请比较时间点（instants），而非字符串相等性。

示例：2026-05-16 东部时间下，“昨天上午 10 点”对应 2026-05-15T10:00:00-04:00，回读可能显示为 2026-05-15T14:00:00+00:00。

验证规则

• record 返回 recorded_at 和 verified_matches。
• verified_matches >= 1 表示脚本在摄入后于 Fulcra 中找到了所写入的记录。
• uv tool run fulcra-api data-updates 可显示某时间范围内已处理的注解相关数据类型，但并非记录级写入验证。切勿将更新计数用作特定注解记录已被创建、修改或删除的证据。
• 对于历史写入，若需二次验证，请使用足够宽的 recent --hours 时间窗口以覆盖目标时间。
• 检查回读结果时，仅使用确认所需的最少字段：注解名称/ID、recorded_at、如有必要则含 value、如有必要则含 note。

API 说明

核心 REST 端点：

• GET /user/v1alpha1/annotation：列出注解定义。
• POST /user/v1alpha1/annotation：创建定义。
• PUT /user/v1alpha1/annotation/{annotation_id}：更新定义。
• DELETE /user/v1alpha1/annotation/{annotation_id}：删除定义。
• POST /ingest/v1/record：记录注解事件。
• POST /ingest/v1/record/batch：批量记录注解事件。
• 回读使用 /data/v1alpha1/event/MomentAnnotation 查询 moment/duration 类型，使用 /data/v1alpha1/metric/{BooleanAnnotation|NumericAnnotation|ScaleAnnotation} 查询指标类注解值。

对于批量或补录流水线，data-updates 是摄入后的粗粒度新鲜度诊断工具。它补充本地账本与记录回读，但无法替代二者。

如需 Schema 细节或上游缺口说明，请查阅 references/api-notes.md。