用途：调试 tmux 中针对 AI 代理（opencode、claude、amp）的面板状态检测，排查状态图标错误、模式不匹配，以及添加新识别模式。
主要能力：提供快速命令列出所有代理面板、抓取面板原始内容、以便于查看控制字符的方式抓取、在面板内容中搜索模式；提供调试脚本遍历会话/窗口/面板，读取代理程序并输出清洗后的内容与检测状态；包含模式测试片段，用正则逐条匹配样例内容。
状态优先级（先匹配先赢）：ERROR（Traceback、panic、FATAL ERROR、API 错误）、WAITING（Allow once?、Permission required、yes/no/skip 提示）、BUSY（Thinking...、spinner、Running tools、esc interrupt）、IDLE（输入提示、上下文显示、OpenCode 版本、ctrl+p commands）、UNKNOWN（无匹配回退）。
必要用法：列出面板执行 tmux list-panes -a -F "#{session_name}:#{window_name}.#{pane_index} #{pane_current_command}" | grep -E "opencode|claude|amp"；抓取内容执行 tmux capture-pane -t "main:1" -p -S -30 | tail -40，查看控制字符加 cat -v；搜索模式可用 tmux capture-pane -t "main:1" -p -S -20 | grep -o "pattern"。调试脚本需放入 /tmp/debug_status.py，用带 libtmux 的 Nix Python 运行；通过 nix build .#tmux-opencode-integrated --no-link --print-out-paths 获取路径，再查看 smart-name.sh 找到 Python 路径。新增模式后需在 tests/test_smart_name.py 添加用例，执行 uvx pytest tests/test_smart_name.py -v 并重新构建。
限制与常见问题：报 No module named 'libtmux' 通常是 Python 选择错误，必须用包内 Nix 包装的 Python；模式不匹配可能受终端控制字符干扰，需用 cat -v 检查原始内容；误报 ERROR 可能是面板最后 20 行残留了历史错误字符串，因为检测只查看最近 20 行内容。其他未提及的用法与配置暂未提供。