git clone https://github.com/wjunhere/chrono-handoff.git
cd chrono-handoff

# 建议 3.13+：实测抖动更低，3.12 会让 selftest 间歇性失败（见 docs/agent-setup.md §一.0）
uv venv .venv --python "$(uv python find 3.13)"
uv pip install --python .venv/Scripts/python.exe -e ".[all]"

.venv/Scripts/chrono selftest      # 机制自检，预期 10/10

chrono doctor                       # 环境探测：时钟 / 音频 / 控制台 / 串口
chrono daemon --window --background # conductor + 原生提示窗口 + IPC

chrono submit --json '{
  "id": "reset-demo",
  "instruction": "按一下开发板上的 RESET 键",
  "lead_s": 3,
  "ioi_ms": 500,
  "tail_beats": 6,
  "target_in_s": 8,
  "duration_s": 25
}'

chrono status reset-demo            # 当前状态
chrono observe reset-demo           # 增量读取事件日志
chrono cancel reset-demo            # 中止

{
  "mcpServers": {
    "chrono-handoff": {
      "command": "chrono",
      "args": ["mcp"],
      "lifecycle": "lazy",
      "searchKeywords": {
        "*": ["human in the loop", "countdown timer", "operator cue", "timing"],
        "chrono_cue": ["ask human physical action", "pop up panel", "press button", "reset device"]
      }
    }
  }
}

chrono_cue(
  instruction = "按一下开发板上的 RESET 键",
  target_in_s = 6,     # 6 秒后动作应命中
  lead_s      = 3,     # 倒计时时长
  ioi_ms      = 500,   # 拍间距
  tail_beats  = 6      # 命中后脉冲延续
)

src/chrono_handoff/
├── clock.py        单调时钟、亚毫秒落点、无漂移拍点网格
├── model.py        CuePlan / SignalSpec / WindowSpec / Event
├── audio.py        跨平台非阻塞音频（后端分级 + 采样级混音）
├── cue.py          提示通道（音频转出 + 终端倒计时）
├── inputs.py       观测源：控制台 / stdin / HTTP / 串口 / 合成
├── effectors.py    执行器抽象：人类 / 串口 / HTTP / 日志
├── calibrate.py    人类偏移估计（median + MAD + 截断）
├── conductor.py    快控制器：拍点网格、动作窗口、闭环、事件日志
├── daemon.py       常驻进程与单实例守卫
├── mcp_server.py   MCP 表面 + IPC 客户端
├── remote.py       跨进程 conductor 代理
├── webui.py        提示面板服务端
├── window.py       原生置顶窗口（WebView2）
├── winshell.py     Windows 11 原生外观（圆角 / 亚克力 / 主题描边）
├── settings.py     设置持久化
├── statics/        单文件前端 + 本地字体
├── probe.py        M1 实验协议
├── analyze.py      离线日志分析
└── cli.py          命令行入口

chrono selftest                       # 核心机制，10 项
basedpyright src scripts desktop/sidecar   # 静态检查，要求 0 error（standard 模式）
python scripts/e2e_audio.py           # 音频后端：混音/选择/非阻塞不变量
python scripts/e2e_panel.py           # 面板 HTTP 全链路
python scripts/e2e_panel_attach.py    # 面板附加到 daemon（chrono panel）
python scripts/e2e_window.py          # 原生窗口
python scripts/e2e_ui_layout.py       # 布局几何
python scripts/e2e_resize.py          # 窗口缩放
python scripts/e2e_theme_drag.py      # 主题对比度与拖拽隔离
python scripts/e2e_daemon_window.py   # 一体化模式
python scripts/e2e_split_mode.py      # 分离模式
python scripts/e2e_state_paths.py     # 用户状态落点（与 cwd 无关）
python scripts/e2e_update_window.py   # cue 安全窗口：不安全时 409 拒，安全时 daemon 自退
python scripts/e2e_desktop_shell.py   # Tauri 桌面外壳（需先 cargo build）
cd desktop/src-tauri && cargo test    # 外壳几何算式（边方向/夹紧/累计位移/窗口位置与恢复）
python desktop/sidecar/build.py       # 冻结侧车并自检（--no-build 只自检，--stale-check 只比指纹）