# Viva helper运行时契约检查 ### 诊断流程样例 触发场景：Viva tooltip 点“更新”后仍显示旧解释，或者制卡只写入短译义。 | 步骤 | 命令/检查 | 通过信号 | 失败信号 | | --- | --- | --- | --- | | 1 | `python helper/tools/check_runtime_contract.py --port 17331 --source helper/anki_concept_helper.py --runtime ~/Library/Application\ Support/VivaAnkiHelper/anki_concept_helper.py` | `source_hash == runtime_hash` | 提示 `RUNTIME_DRIFT`，说明仓库源码和运行时副本不一致 | | 2 | 工具解析 LaunchAgent plist 和监听进程 | plist 指向 runtime helper，pid cmdline 一致 | 提示 `PLIST_PATH_DRIFT` 或 `OLD_PROCESS` | | 3 | 工具请求 `http://127.0.0.1:17331/health` | 返回 `{\"ok\": true}` | 提示 `HELPER_DOWN`，附 `launchctl print`/日志路径 | | 4 | 工具静态检查 prompt schema | card/tooltip prompt 都包含三字段 | 提示 `PROMPT_SCHEMA_MISSING: usageHintZh` | | 5 | 可选：`--live-fixture fixtures/helper-contract/tooltip-person-name.json` | `/explain` 返回三字段，`aiStatus` 合理 | 提示 `RESPONSE_SCHEMA_MISSING` 或 `CACHE_REUSE_RISK` | 建议输出： ```text FAIL RUNTIME_DRIFT source: 20-products/viva/30-rd/anki-local-extension/helper/anki_concept_helper.py runtime: ~/Library/Application Support/VivaAnkiHelper/anki_concept_helper.py next: cp source runtime && launchctl kickstart -k gui/$UID/com.bytedance.viva-anki-concept-helper verify: curl -fsS http://127.0.0.1:17331/health ``` 这个流程把“改了源码但服务仍跑旧代码”“端口上是旧 pid”“prompt 字段缺口”“缓存把旧解释当新解释”拆成独立信号，避免每次从用户可见的 tooltip 现象重新猜。