# Loop 指令协议（v0.5 草案）

本文档定义 Telos Web 端与未来实体 Loop（手环）之间的指令协议。当前 Web 端在「Loop 模拟器」（回放视图）中实时回放这些指令；接入实体设备时，监听同名事件即可。

## 事件入口

Web 端每次需要驱动 Loop 时，会在 `window` 上派发一个自定义事件：

```js
window.addEventListener("telos:loop-command", (event) => {
  const { tone, pattern, message, at } = event.detail;
  // 交给手环 SDK / BLE 通道
});
```

## 载荷（Payload）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `tone` | string | 光效/震动基调：`green`（完成·专注）/ `warm`（提醒·降阶）/ `blue`（AI 工作） |
| `pattern` | string | 震动/光效模式：`pulse`（单次）/ `double`（双脉冲，里程碑级庆祝） |
| `message` | string | 人类可读的指令语义（如「已完成」「里程碑达成 · AI 滚动中」），用于调试与屏幕显示 |
| `at` | string | ISO 8601 时间戳 |

## 语义映射建议（硬件侧）

| tone | 建议 LED | 建议震动 | 典型触发场景 |
| --- | --- | --- | --- |
| `green` + `pulse` | 绿色渐亮 | 单次轻震 80ms | 完成一个动作 |
| `green` + `double` | 绿色双闪 | 双震 80ms × 2 | 里程碑/目标达成 |
| `warm` + `pulse` | 琥珀色呼吸 | 单次轻震 | 稍后重排 / 降阶提醒 |
| `blue` + `pulse` | 蓝色呼吸 | 无震动（静默） | AI 正在静默重排 |

持续状态（专注保护、AI 思考呼吸）由 CSS 类驱动，硬件侧可映射为周期 1.1s 的呼吸光；协议层只传离散指令。

## 未来接入点

- BLE 通道：Web Bluetooth API 在事件回调中下发指令；
- 配套 SDK：`telos-loop-sdk`（待建）负责指令缓存、断连重放与电量回报；
- 回传通道：手环侧传感器（加速度计、PPG）数据回传后，接入现有 `/api/transcribe` 与 PACE 输入的同一数据管线。


## 物理按键手势（AI-Native 主入口）

手环只保留一个主按键。Web 端虚拟手环（右下角设备）已支持真实手势检测：单击 / 双击 / 三击 / 长按（700ms）。同一手势在不同状态下的语义：

| 手势 | 空闲时 | 专注中（已开始） | 目标已完成 |
| --- | --- | --- | --- |
| 单击 tap | 开始当前动作 | 完成这一步 | 打开制定新目标 |
| 双击 double_tap | 我卡住了 → 拆微步骤 | 我卡住了 → 拆微步骤 | 提示制定新目标 |
| 三击 triple_tap | 切换到下一个目标 | 切换到下一个目标 | 切换到下一个目标 |
| 长按 long_press | 稍后 → 重排 | 结束专注（不标记完成） | 提示制定新目标 |

未来的实体 SDK 只需调用同一入口：`handleLoopGesture("tap" | "double_tap" | "triple_tap" | "long_press")`。

## 语音指令（AI-Native 第二入口）

开启「短片段语义分析」后，说话会被转写并交给 AI 做意图识别；置信度 ≥ 0.7 时自动执行。

| intent | 示例说法 | 执行动作 |
| --- | --- | --- |
| start | 「开始」「现在开始」 | 开始当前动作 |
| complete | 「完成了」「做完了」 | 完成当前动作 |
| stuck | 「卡住了」「好难」 | 拆微步骤 |
| postpone | 「稍后」「先不做了」 | 稍后重排 |
| breathe | 「呼吸」「喘口气」 | 呼吸一刻 |
| switch_goal | 「换个目标」「下一个」 | 切换目标 |
| weekly | 「写周报」「本周总结」 | 生成周报 |
| replan | 「重新规划」 | AI 重排 |
| new_goal | 「定个新目标」 | 打开新目标弹窗 |
| end_focus | 「结束专注」 | 结束专注 |
| energy_low / energy_ok / energy_high | 「有点累」/「还可以」/「满血」 | 一键打卡精力 |

手势与语音都汇入同一 Command Bus（`runCommand(intent, payload, source)`），日志以「按键手势/语音指令」进入回放感知流。

## 版本

- 0.6（当前）：新增按键手势语义表 + 语音指令 intent 集合；
- 0.5：事件派发 + 载荷草案；
- 未来：增加 `priority`（是否允许静默过滤）与 `ack`（设备回执）字段。