Skip to content

Troubleshooting zh CN

ChrAlpha edited this page Nov 12, 2026 · 8 revisions
🇬🇧English | 🇨🇳中文

故障排查

先运行 tmag doctor。安装 skill 中的排查表涵盖安装、插件批准及 pane 关联问题。

诊断

新的 hook.log 记录仅包含时间戳、来源和固定的失败类别,不含命令输出或 hook 输入。日志通过串行化追加和轮转控制在 256 KiB;旧的原始记录最多保留到下次轮转,doctor 展示时会脱敏。

tmag doctor 共用一个两秒的诊断预算,限制宿主命令输出,并清理自己启动的辅助进程。它报告当前第一个元数据故障及位置、从最多 32 个目录条目中读取的最近 hook 联系时间、近期仅含元数据的 hook 失败记录,以及现有 event log 验证结果。

未完成的探测保持 unknown;历史失败本身不能证明当前仍有故障。日志验证沿用既有恢复行为,doctor 不提供历史取证完整性保证。

doctor 还会指出会悄悄抵消 tmag 显示效果的 tmux 选项,并给出恢复它的配置行:monitor-bell off 会让提醒无法标记 window,allow-set-title off(tmux 3.5 及以上)会让 Codex pane 无法显示其 thread。tmag 不会修改这两个选项。

已知限制

  • Agent 第一次 hook 之前(启动、目录信任对话框等阶段)显示为 unknown;对其 pane 执行 tmag wait 会一直等到它上报。
  • Claude Code 不上报通过 Esc 中断的 turn,之后也可能不发送 idle 通知。因此,直接在终端中断的 session 可能一直显示 working,直到下一个 prompt;通过 tmag interrupt 中断则会立即变为 idle。
  • Codex title items 不是稳定接口。tmag 读取 Codex 0.167 的 thread-id 项:thread id 前 29 个字符加 ...,可位于 title 任意位置。若后续 Codex 版本改变格式,Codex panes 将无法关联到 sessions;daemon 中存在 Codex sessions 却没有对应 panes 时,tmag doctor 会警告。
  • Codex thread 在第一个 prompt 前已存在,但 hooks 从该 prompt 才开始运行;此前 pane 显示为 unknown。
  • Codex daemon 在最后一个终端关闭后约一分钟卸载 thread,此时才上报 thread 结束。
  • 无法证明运行 claude attach 的 pane 对应哪个后台 session,见 Session 与 pane。
  • Pi 和 oh-my-pi 没有 hooks;tmag 的 extension 读取 Pi 1.5.0 和 oh-my-pi 18.18.6 的 events,其他版本可能改变它们。它们的 packages 来自 tmux 插件的目录:若 tmag 以其他方式安装,tmag setup 无法接入它们;先于它们移除 tmux 插件,agents 会警告 package 缺失。
  • Pi session 中,extension 在 turn 期间打开的任何对话框(包括 permission gate)都会显示为 blocked (question):Pi 不会告知是哪一种。
  • Pi 在所有模式下都把进程命名为 pi。由其他程序(例如编辑器)在 pane 中运行时,它会上报自己的模式并作为 service 运行,但该 pane 仍会列为一个未显示任何 session 的 pi pane。

Clone this wiki locally