Kitty 命令 Flash

记录如何让 kitty 中手动执行的命令通过 Global Pet Assistant 触发短时反馈。

结论

kitty 里的手动命令适合用 flash，不适合用长任务 thread。失败命令应该马上提醒；成功命令只在耗时超过阈值时提醒；cd、ls、pwd、git status 这类高频命令应该过滤掉。

当前实现是一个 zsh hook：

Tools/install-kitty-command-hook.sh

安装器把 examples/hooks/kitty-command-flash.zsh 复制到：

~/.global-pet-assistant/hooks/kitty-command-flash.zsh

然后在 ~/.zshrc 加一个带 marker 的 source 块。新开的 kitty tab/window 会自动生效，已打开的 tab 可以手动运行：

source ~/.zshrc

背景

Global Pet Assistant 有两类事件：

thread：表示 Codex、Claude、CI 这类持续任务的状态，需要保留上下文，参与 badge 和状态优先级。
flash：只表达“刚刚发生了什么”，不需要用户处理，不抢焦点，也不改变 base state。

手动终端命令大多是短动作。如果每条命令都进入 thread，桌面 UI 会被噪声污染。因此 kitty 集成只发送短时 flash。

行为

默认规则：

只在交互式 zsh 和 kitty 环境中启用。
命令失败时发送 danger flash。
命令成功时，只有耗时达到 GPA_KITTY_COMMAND_FLASH_MIN_SUCCESS_MS 才发送 success flash。
默认成功阈值是 5000 毫秒。
高频命令会被忽略，包括 cd、ls、pwd、clear、git status、git diff、git log、git branch 等。

临时关闭：

export GPA_KITTY_COMMAND_FLASH=0

调整成功提醒阈值，例如 2 秒：

export GPA_KITTY_COMMAND_FLASH_MIN_SUCCESS_MS=2000

过程

kitty 已经开启 remote control socket：

allow_remote_control socket-only
listen_on unix:/tmp/global-pet-kitty.sock

命令 hook 使用 zsh 的 preexec 记录命令和开始时间，用 precmd 读取上一条命令退出码和耗时。发送事件时调用：

petctl flash --source "kitty-command:${KITTY_WINDOW_ID}" --level danger --message "false failed (1)"

为了避免 prompt 被通知逻辑污染，hook 会把 petctl flash 放到后台，并关闭 zsh 的 bg_nice 行为。默认优先使用当前 release 构建出的 petctl，没有 release binary 时才 fallback 到 swift run --package-path ... petctl。

验证

可用模拟 kitty 环境验证失败命令：

env KITTY_WINDOW_ID=codex-test \
  KITTY_LISTEN_ON=unix:/tmp/global-pet-kitty.sock \
  zsh -fic 'source ~/.global-pet-assistant/hooks/kitty-command-flash.zsh; __gpa_kitty_command_preexec "false"; false; __gpa_kitty_command_precmd; sleep 1'

应用事件日志应出现：

source=kitty-command:codex-test
type=flash
message=false failed (1)
status=accepted

这个验证重点不是长任务状态是否变化，而是 flash 是否被接受，并且不会覆盖当前 Codex/CI 的 base state。

后续

把阈值和过滤列表做成用户级配置。
考虑为不同工作目录或 tab 定制 source 命名。
如果 shell hook 噪声增多，再增加更严格的命令过滤。