调试与故障排查
先记录“做了什么、预期什么、实际什么”，再按下面顺序查。不要同时改手势、窗口命名和动作代码。
程序没有启动
确认完整解压、配置与 exe 同级、运行目录可写、CPU 满足发行说明。conf.toml 必须包含 [def] 和 [gs]。不要用源码仓库代替完整运行目录，也不要换用不配套的 AHK。
有错误报告时保存完整内容。错误文件可能出现在运行目录 err.txt；控制台隐藏时，可临时移除 hide_console=1 后重启观察。
快捷键全部无效
确认 def_hotkey 命令存在且自动启动。key= 只是命令属性，主程序会把生成的热键代码追加到这份宿主。缺少它时，单纯添加 key 不足以注册热键。
只有某个热键无效，再检查冲突、hotif、同名命令、文件扩展名及保存后是否重启。
手势没有反应
- 用体验快捷键确认命令本身能执行。
- 在普通空白窗口使用配置的触发键。
- 查看记录是否出现这次输入。
- 核对实际触发串，检查触发键名单和识别样本。
- 有触发串后，再查作用域、条件与最终命令名。
按入门快捷键 Ctrl+Alt+F11 导出记录。记录中 gs 是识别信息，dn／up 是执行命令，undef 或 tip 通常表示本次未找到命令。日志里的内部耗时不直接当作用户感知延迟的可靠基准。
命令加载了但不执行
检查 ban、pc／pc_bl、.skip 目录、文件名归一化及同名规则。遇到 src type err 时，检查 type 是否确有执行分支；字母能排序不等于组合有效。
正文报错时保留 AHK 的完整报告，包括命令名称和调用位置。先把动作换成简单提示验证，再逐步加回逻辑。
改正文仍是旧效果
列表正文和普通预读脚本需要重启。read 主要用于独立线程调试；复用执行器中已编译的函数或标签不会因此自动更新。修改元数据、命令名或热键也需要重启。
窗口、文件或网页字段为空
确认这个入口会提供该字段，目标软件支持采集，配套扩展或接收端已连接。热键入口不自动拥有鼠标释放坐标。不要给缺失字段编造默认含义。
输入异常或退出后有进程
先通过任务管理器结束 diatom.exe，确认普通输入是否恢复。独立 e 进程可能继续，需要按它自身的退出方式结束；Job 模式通常跟随主程序清理。
提交问题时提供
程序版本、触发动作、目标软件、相关命令定义、对应日志或完整错误报告，以及最近是否改过输入后端或运行时路径。分享前检查日志里的私人路径、窗口标题、选中文本和令牌。