gilvt：让终端知道 Agent 在做什么

gilvt 是什么

同时开着三四个 Claude Code、Codex 会话时，最难的不是写代码，而是知道哪个会话停下来在等你批准、哪个刚跑完测试失败了、哪个已经做完等你看结果。普通终端只给你一格格文字，你只能挨个标签去翻。

gilvt 首先是一个完整、正常可交互的终端，可以当日常终端用。在此之上，它读懂 Claude Code 和 Codex 的运行状态：

• 左栏把所有会话集中列出，「需要你」的排在最上面，⌘⇧J 一键跳过去。
• pane 描边和标签圆点用颜色告诉你每个会话的状态，不用切过去看。
• 右栏检查器按轮次列出 Agent 这一轮执行过的每条命令、每次文件修改，点一下终端就滚回那一行。
• 系统通知和 Dock 角标在你切到别的应用时提醒你。
• ⌘⇧R 找回几天前的会话接着做，⌘⇧N 一步在指定目录开出新的 Agent。
• Quick Look 在终端里直接看代码 diff、排版后的 Markdown 和 Mermaid 图，不用切到编辑器。

设计原则

功能一览

当前版本

已完成的里程碑：M1 基础终端，M2a–M2c 预览与找文件，M3a–M3d Agent 状态、执行过程、会话管理与离线 Review，M4a 产物（每轮的文件改动与「本轮」diff），M5a 配置只读摘要。此外还有：工作现场持久化、git 与 worktree 感知、关闭确认（P0）；会话归档、带附属数据的删除、清理向导与运行目录显示；左栏的终端行；监控官（S1：全局活动视图；S2 阶段 1：✦ AI 总结；阶段 2：⌘, 设置窗口；阶段 3：只读对话；阶段 4：底部命令条）；内置编辑器（含语法高亮与实时预览）；Codex 子 Agent 与后台 terminal 在时间线里显示。M4b（已看状态、diff 范围切换）和 M5b（配置编辑与安全写回）尚未提供（监控官的 [monitor] 已能在设置窗口里修改并安全写回）。

M1 ✓ · M2a ✓ · M2b ✓ · M2c ✓ · M3a ✓ · M3b ✓ · M3c ✓ · M3d ✓ · M4a 产物 ✓ · M5a 配置摘要 ✓ · M4b / M5b 待实现

安装与启动

需要 macOS、Rust 1.95（仓库里的 rust-toolchain.toml 会自动选中）和 Xcode Command Line Tools，不需要完整的 Xcode。

1. 构建并打包成 Gilvt.app。原生系统通知和 Dock 角标需要从 app 启动。请在 /tmp 以外的目录构建，macOS 会忽略 /tmp 下的 app。

   cd gilvt
   scripts/bundle.sh            # 或 scripts/bundle.sh release
   open target/debug/Gilvt.app

2. 建议先做一次稳定签名。按 HACKING.md「稳定签名」创建一张自签名的 gilvt-dev 证书，scripts/bundle.sh 会自动用它签名。否则每次重新构建后，通知、屏幕录制等系统授权都可能要重新授予。
3. 允许通知。第一次有会话需要你时，系统会询问是否允许 gilvt 发通知。选择允许；之后可在「系统设置 → 通知 → gilvt」里修改。Dock 角标也依赖这个开关。
4. 照常使用。在 pane 里直接运行 claude 或 codex，左栏和检查器会自动出现它的状态，不需要任何额外设置。

只想试试也可以直接运行调试构建：cargo build --workspace && ./target/debug/gilvt-app。这种方式下通知改用 osascript，没有声音，点击也不能跳回 pane。

从下载的安装包安装时，请把 Gilvt 拖进「应用程序」文件夹再打开。如果直接在 dmg 窗口里、或在「下载」文件夹里原地打开，gilvt 会在窗口顶部提示「正在从临时位置运行」：macOS 这时让它跑在一个随机的只读副本里，以后的更新和 gilvt integrate install 写入的 hooks 都会失效。点横幅上的「移到「应用程序」」，gilvt 会把自己复制到 /Applications（没有写权限时 ~/Applications）并从那里重新打开；那里已有旧版本时，旧版本先移到废纸篓。「以后再说」只在本次运行中隐藏提示。

更新

下载安装的 gilvt 会自己更新。默认在后台检查 release.gilvt.com，有新版本就下载，在你退出 gilvt 时安装：替换发生在 gilvt 退出之后，所以正在运行的 Agent 不会被更新打断。有下载好的更新在等待时，侧栏底部会显示「gilvt X 已下载，退出时安装 · 现在退出」。应用菜单里的「检查更新…」（在「设置…」之后）会立即检查并显示结果。

config.toml 里的 [update] mode 决定行为：download（默认）、check（只检查，下载前先弹窗询问）或 off（从不检查；重新打开需要重启）。更新带 gilvt 的 EdDSA 签名并经过 Apple 公证；检查时不发送任何标识（见 PRIVACY.zh-CN.md）。从源码构建的版本没有更新功能。

界面与基本操作

gilvt 的窗口分三栏：左栏是会话总览，中间是终端标签与分屏，右栏是检查器。⌘B、⌘I 分别收起两侧，两侧都收起时就是一个纯终端。

标签与分屏

shell 集成

新 pane 的 zsh、bash、fish 会加载 gilvt 的 hook：上报当前目录（新 pane 继承目录、相对路径识别都靠它），标记提示符和命令边界。你自己的 rc 文件照常加载，不会被修改。不想要可以在配置里写 shell_integration = false。

点击路径和链接

终端输出里的文件路径（包括 src/main.rs:42:7 这种带行列号的写法）按住 ⌘ 点击会在 Quick Look 里打开并定位；⌘⇧+点击在内置编辑器里打开（见下文「内置编辑器」）。只有真实存在的文件才会被识别。http / https / mailto 链接 ⌘+点击用浏览器打开。

重启后恢复现场

gilvt 每秒把窗口、标签、分屏方向与比例、每个 pane 的目录、窗口位置和大小存到 ~/Library/Application Support/gilvt/state/workspace.json（只在有变化时写）。⌘Q 退出、崩溃或被强退后重新打开，布局回到最近一两秒的状态。几点要知道：

• Agent 不会自动启动。重启后每个 pane 都是一个普通 shell；原来在跑 Agent 的 pane 会在左栏「需要你」下面列为「待恢复 · N」。点一行，gilvt 在它原来的 pane 里输入 cd <目录> && claude --resume <id>（Codex 是 codex resume <id>）；「全部恢复」约每 0.5 秒恢复一个。你自己在那个 pane 里手动启动了 Agent 时，以实际检测到的会话为准，「待恢复」标记自动消失。
• 某个 pane 的目录已被删掉：该 pane 改在主目录启动，窗口顶部提示「目录 … 已不存在，该 pane 改在主目录启动」。
• workspace.json 损坏时空白启动，原文件另存为 workspace.json.bad，之后正常保存新布局。
• 主动关闭最后一个窗口（不是 ⌘Q）视为「不想保留」，下次启动是空白窗口。
• 内置编辑 pane、Quick Look 预览不会恢复。

关闭确认

关闭范围内有正在思考、执行工具、等待审批或在问你的 Agent 时，⌘W（pane）、⌘⇧W（标签）、关闭窗口和 ⌘Q 都会先出确认条，列出受影响的会话和它们的状态；⌘Q 会把所有窗口的会话合并成一条。默认是取消（↩ 或 Esc），⌘↩ 才「仍然关闭」。空闲、已结束、出错的 Agent 和普通 shell 直接关闭。「仍然关闭」后会话仍在历史里，⌘⇧R 可以恢复、接着对话。

Quick Look 预览

Quick Look 是覆盖在终端区上方的预览浮层，终端在后台照常刷新。在 git 仓库里默认显示与 HEAD 相比的改动：语法高亮、词级 diff、未改动的行折叠。按 ⏎ 可以把它固定为一个分屏 pane，文件保存后自动刷新。分屏太窄不好看时，按住固定 pane（或编辑器 pane）的标题栏拖到标签栏上松开，它就移到一个独占的新标签里；在固定预览里按 T 效果相同。新标签里按 Esc 或 ⌘W 关掉它，都回到原来的标签。

内置编辑器

gilvt 自带一个通用文本编辑器，改 Skill、命令或任何文本文件不必再跳到别的应用。

怎么打开。配置标签里点 Skills / 命令 / 子代理的「查看 ›」，鼠标悬停在某一行上会出现「编辑」按钮；Quick Look 预览里按 E（或 ⌘O）；终端输出里的路径 ⌘⇧+点击。同一个文件已经在编辑 pane 里时，再打开只会聚焦它，不会重复打开。

分屏还是新标签。默认在当前终端 pane 的右边分屏，终端继续可见。当前标签已经有 3 个或更多 pane、或分屏后任何一边会窄于 60 列时，改为在新标签里打开；关掉这个标签会回到你来的那个标签。按住 ⌥（点「编辑」或按 ⌥E）翻转这个选择。

编辑与保存。长行自动换行，续行的行号栏留空；支持中文输入法、鼠标选择、撤销重做、Tab / ⇧Tab 缩进。⌘S（或头部的「保存」）保存，有未保存修改时头部和所在标签显示 ●。⌘⌥O 改用外部编辑器打开磁盘上的文件（不保存）。

不会丢内容。保存时如果文件在磁盘上被别的程序改过，会出现「文件已在磁盘上被修改」的横幅（重新载入 / 对比 / 仍然覆盖），不会静默覆盖。关闭有未保存内容的 pane 或标签时会问你保存、不保存还是取消；关闭窗口或 ⌘Q 时列出所有未保存的文件，↩ 是「全部保存并关闭」，Esc 是取消，⌘↩ 是不保存并关闭。

文件在磁盘上被改了。编辑 pane 会留意它的文件（比如 Agent 正在改同一个 Skill）。没有未保存改动时，新内容会静默载入，状态栏左侧闪一下「已更新」。有未保存改动时，头部下方出现黄色横幅「文件已在磁盘上被修改，而你有未保存的改动。」：

• 重新载入：磁盘内容替换进编辑区，这是一次可撤销的编辑，⌘Z 能找回你的版本。
• 对比：打开对比浮层（见下）。
• 仍然覆盖：用你的版本覆盖磁盘。
• Esc 只是收起横幅；之后按 ⌘S 仍会被拦住，不会悄悄覆盖。

文件被删除或移走时，横幅是「文件已被删除或移走。」：保存（重新创建）/ 关闭 / 知道了。

对比浮层。左边是磁盘版本，右边是你的版本（窗口较窄时合并成上下的统一 diff）；删除的行红底、新增的行绿底，长段没改的内容折叠成一行，点一下展开。如果只有换行符或编码不同，会提示「内容相同」。浮层打开时读一次磁盘，之后不再跟随。底部三个按钮：用磁盘版本（等同「重新载入」，可撤销）、保留我的，稍后再说（只关闭浮层，横幅还在）、仍然覆盖磁盘（红色）。Esc 返回编辑。这是文本对比，没有三方合并。

换编码、只读打开。状态栏里的编码可以点（例如「GBK ▾」）。菜单里有 UTF-8、UTF-8（带 BOM）、UTF-16 LE / BE、GBK、Shift_JIS、EUC-KR、Big5、windows-1252、gb18030，选一个就用它重新读取文件，当前的打 ✓；有未保存改动时会先问「放弃改动并重新打开」。菜单最后一项在「以只读方式打开」和「以可编辑方式打开」之间切换；文件不可写、或解码替换过字符时，「以可编辑方式打开」是灰的。只有重新编码后能与文件字节完全一致的编码才能编辑；否则只能只读，不能表示的字符显示为替代符号，头部标「只读 · 部分字符已替换」。

被拒绝的旧编码文件。因为「旧编码无法原样写回」被拒绝时，红色横幅上多出两个按钮：「选择编码打开…」和「以只读方式打开」。两个都先用猜到的编码只读打开，前者随后弹出编码菜单，选一个能原样写回的编码后即可编辑。

混合换行符。一个文件里同时有 LF 和 CRLF 等多种换行符时，状态栏的换行符显示为琥珀色的「LF · 混合」（保存会统一成这一种）。点它选 LF / CRLF / CR，保存时整个文件按所选换行符写出；文件原本是混合的、或所选与当前不同时，头部显示 ●，直到保存；在统一的文件上选当前这一种不会变脏。只读的文件不能改换行符。

语法高亮。按文件类型给文字着色（Rust、Markdown（含开头的 YAML 头）、TOML、JSON、Shell 等常见语言，颜色随终端配色和浅 / 深主题变化）。纯文本不着色，状态栏写「纯文本」；大文件（超过 2 MiB 或 50 000 行）也不着色，状态栏在语言名后写「（未高亮）」。Markdown 里的代码块整体用代码色，不按围栏里的语言再着色。

实时预览。编辑 pane 头部的「预览 ⌘⇧V」（或直接按 ⌘⇧V）在编辑 pane 右边开一个预览 pane，显示你正在编辑的内容，包括还没保存的修改；停止输入约 0.2 秒后刷新，再按一次 ⌘⇧V 关闭。预览是只读的，关掉任意一边另一边一起关闭，重启后不恢复。

预览打开后，头部的按钮显示「预览：渲染」「预览：图表」「预览：图片」或「预览：改动」；点它切换到下一个可用的预览（循环），只有一个可选时点它就是关闭。gilvt 会记住每种文件类型你的选择。你滚动编辑区或移动光标时，预览会跟到编辑区顶部那一行对应的位置（只是编辑区带动预览，反过来不行）。Mermaid 有错时，源码和错误信息直接显示在预览里，和 Quick Look 一样；SVG 无法解析时显示「无法读取图片」。「改动」预览比较的是你上次编辑或保存时磁盘上的版本，不会监听文件。文件很大（超过 2 MiB 或 5 万行）时，预览打开时构建一次，并立刻提示「文件太大，未实时预览 · 保存后更新」，之后打字只在保存时更新。预览里不响应 Quick Look 的 D、S、拖入文件和文件链接跳转；按 Esc 回到编辑区。

不能编辑的文件。二进制文件、超过 64 MB 的文件、旧编码无法原样写回的文件不会打开编辑，而是在窗口顶部显示红色横幅说明原因，可以改用预览或外部编辑器。没有写权限的文件只读打开；含超过 20 万字符的超长行的文件也只读打开。

Markdown 与 Mermaid

.md 文件在 Quick Look 里默认显示为排版后的文档：正文用比例字体，代码和表格数字用等宽字体。相对对比基准的改动按块标出：左侧绿条是新增块，黄条是修改块，整段删除的内容显示为「已删除 N 行 · 点击展开」。

• S 在渲染视图和源码 diff 视图之间切换，位置保持不变。
• 指向本地文件的相对链接在同一个 Quick Look 里打开，⌘[ 返回；外部链接用浏览器打开。
• 本地图片按阅读宽度显示，远程图片只显示地址、不加载。
• Mermaid 图在后台离线渲染，不请求任何网络资源；语法错误时显示源码和错误信息，R 重试。

⌘P 与拖入文件

⌘P 文件搜索

在终端 pane 里按 ⌘P，搜索该 pane 所在 git 仓库的全部文件（遵循 .gitignore）；不在仓库里时搜索当前目录。有未提交改动的文件、当前目录下的文件、最近预览过的文件排在前面。查询语法与 fzf 相同：空格分隔多个词，^ / $ 锚定，' 精确匹配，! 排除。

从访达拖入

把文件从访达拖到 pane 上：前台是 claude / codex 时插入路径，方便 Agent 当附件读取；其他程序默认用 Quick Look 预览。松手时按住 ⌥ 换成另一种行为。拖动时 pane 上会提示松手后的效果。

gilvt 命令行

每个 pane 的 PATH 里都有 gilvt 命令，用它从命令行打开预览：

gilvt view src/main.rs:42          # 打开并定位到第 42 行
gilvt view --pin README.md         # 固定为右侧预览 pane，保存后自动刷新
git show HEAD:a.rs | gilvt view --as rs -   # 预览标准输入
gilvt diff                         # 逐个预览相对 HEAD 的全部改动文件（←→ 切换）
gilvt diff main                    # 相对 main 分支

在其他终端应用里运行时，gilvt 直接打印带颜色的内容。

Agent 会话

在 pane 里运行 claude 或 codex（包括 codex-w 这类最终执行 codex 的脚本）后，gilvt 会自动识别它，并通过注入的 hooks 实时获得状态。一切都在后台完成，你照常在 Agent 的界面里工作。

会话的状态

左栏

• 需要你：等待审批 / 在问你的会话，等得最久的在前。
• 待恢复：重启后还没恢复的会话（见「重启后恢复现场」），点一行恢复，「全部恢复」一次恢复全部。
• 全部会话：默认按项目（git 根目录名）分组，可切换为按状态分组；全部空闲的分组自动折叠。同一个仓库的主目录和它的 linked worktree 算同一个项目。
• 终端行：没有运行 Agent 的终端 pane 也会以灰色一行出现在左栏（头部写「会话 · N · 终端 M」），点击跳到该 pane；它不进「需要你」，⌘⇧↑ / ⌘⇧↓ 也不会切到它。「按状态」分组下它们归入末尾默认折叠的「终端」组。pane 里的 Agent 退出后，这一行变回终端行。
• 已结束：本次运行中结束的会话，默认折叠。双击恢复，右键可恢复或移到废纸篓。
• 每行显示：Agent 图标（C = Claude，X = Codex）、会话名（见「恢复与管理会话」里的取名规则）、时间、当前动作（如 ⏳ 等待审批 · Bash(rm -rf build)）、位置（标签 · 左 / 右）和上下文占用细条（≥ 80% 黄，≥ 90% 红）。
• git 行：会话所在目录是 git 仓库时，行下多一行 ⎇ main；有未提交改动时写个数（⎇ main ●2），有上游时写领先 / 落后（⎇ main ●1 ↑1↓0）；detached HEAD 显示短提交；在 linked worktree 里会带上 worktree 的目录名前缀。约每 10 秒刷新。不是 git 仓库的目录没有这一行。
• 长文本：长会话名折成两行，长状态行用省略号截断；鼠标悬停约 0.5 秒显示完整的名字、状态、位置和 cwd。
• 点击一行跳到该 pane；右键可重命名、静音通知、复制会话 ID。

在会话之间跳转

精简模式

hooks 没有生效时（例如 claude --bare、Codex 关闭了 hooks），gilvt 改为读取会话记录推断状态，左栏标注「精简模式」。这时看不到审批和提问，其他功能照常。

检查器：过程

右栏检查器跟随当前聚焦的 pane，显示这个会话每一轮做了什么。它只负责展示和跳转，没有任何审批或输入按钮。

• 状态卡：状态与当前动作、第几轮和本轮耗时、上下文占用、模型和权限模式、本轮和会话的 token 数。
• 等待横幅：别的会话在等你时出现在顶部，点击等同 ⌘⇧J。
• TODO：来自 Claude 的 TodoWrite 或 Codex 的 update_plan，完成项划线、进行中加粗。
• 时间线：一行一个事件，可按 全部 / Bash / 编辑 / 失败 过滤。失败的命令直接露出关键报错（最多 3 行）；编辑类附 +N −M；子 Agent 以紫色竖线嵌套显示。标题后的灰色时刻是本轮开始的时间。
• Codex 子 Agent 与后台 terminal：子 Agent 作为紫色过程行显示；持续运行的 terminal 命令保持为同一行，后续 wait / write_stdin 只更新它，不重复占行。
• 跳回终端：点一行，终端滚到这条命令在终端里的位置并短暂高亮；⌘+点文件名用 Quick Look 打开这个文件。
• 历史轮：当前轮下面是之前的轮次，每轮一行（含开始时刻和耗时），点击展开。

检查器宽度可以拖动调整（240–560 px）。⌥⌘1、⌥⌘2、⌥⌘3 分别切到「过程」「产物」「配置」。

检查器：产物

⌥⌘2 切到「产物」标签。它按任务列出这个会话改了哪些文件，每个任务一张卡片，最新的在最上面；顶部是汇总「▸ 本会话净改动 · N 文件 +a −b」。

• 卡片 = 任务：一条提示词开一个任务；紧接着的「继续 / 好的 / ok」这类应答并入它。标题是「开始时刻 · 提示词第一句」，下面一行小字写「第 n–m 轮 · 含 k 次跟进」，右侧是「N 文件 +a −b · 耗时」。文件和行数是整个任务的净改动（第一轮之前 → 最后一轮之后），算出来之前写「计算中」。卡片里是文件列表（M 修改、A 新增、D 删除、R 重命名，加 +a −b）、测试或构建结果（识别 go test、npm test、pnpm test、pytest、cargo test、make test，多次运行取最后一次，✓ 通过、✗ 失败并带退出码）和 Agent 最后一条回复的首句（灰色引语）。
• 进行中的轮：虚线边框，文件列表随工作区实时更新。超过 8 个文件时只显示前 8 个，其余按目录分组查看。
• 无改动的任务：连续的折成一行「▸ N 轮无文件改动 · 标题、…」，点开逐条查看。
• 本会话净改动：顶部汇总行可以点开，列出第一轮之前到最近一轮之后的净改动，只算 Agent 改过的文件；轮次之间你自己改的其他文件不计入，会注明数量。会话先后在几个仓库里工作时，只统计最近的那个仓库，并注明「只统计 仓库名」。
• 「后被改动 · 第 n 轮」：这个任务改过的文件在后面某一轮又被改了，卡片上会标出是哪一轮。
• 键盘：↑ ↓ 在卡片和文件行之间移动，⏎ 在卡片、汇总行和折叠行上展开或收起，在文件行上与 Space 一样在 Quick Look 里看选中文件的 diff（标签是「本轮（第 n 轮前 → 后）」「本任务（第 a 轮前 → 第 b 轮后）」或「本会话（第 a 轮前 → 第 b 轮后）」，加减行数与卡片一致），← → 在同一张卡的文件之间切换。点击卡片标题也能展开或收起；文件行用 ⌘+点击打开 Quick Look，单击只是选中。文件行右键「复制路径:行号」（行号是该文件第一处改动）。
• 降级文案：「非 git 目录，暂不记录文件改动」只显示标题、耗时和引语；「无快照：这一轮发生时 gilvt 没在记录」是 gilvt 启动之前或没赶上的轮，不会编造文件列表；「快照失败：原因」是 git 调用出错，不影响 Agent 和终端；「N 个大文件已跳过」是超过 5 MB 的文件；「中断：没有看到这一轮的结束」是这一轮的结束没被看到（gilvt 退出了，或者下一条提示先到了），只有轮的开头。
• 快照：gilvt 在每轮开始和结束时给工作区拍一份快照，存在自己的目录里，不会改动你的仓库（不动 .git/index、不建提交、不写 .git/objects）。某个仓库 30 天没有新快照时，它的快照整体清理；之后点文件会提示「快照已清理」，卡片上的文件列表仍在。轮进行中，没被 git 跟踪也没被忽略的文件会被复制进 ~/Library/Application Support/gilvt/state/snapshots（没有 .gitignore 的 node_modules 会占满它的体积）；某个仓库 30 天没有新快照，它的整个快照目录会被删除。使用 Git LFS 时，git add 会运行它的 clean 过滤器，缓存留在仓库的 .git/lfs 里。

检查器：配置

⌥⌘3 切到「配置」标签。它在后台读取当前 Agent 和工作目录对应的配置，按卡片显示模型 / 权限模式、MCP、Hooks、Skills / 命令 / 子 Agent 数量、CLAUDE.md / AGENTS.md 和配置来源。每个值旁的「本次会话 / 用户 / 项目 / 项目·本地」说明它来自哪一层；运行中会话实际上报的模型和权限优先。点开 MCP / Hooks / 记忆行可以看脱敏后的详情；点「扩展」里的 Skills / 命令 / 子 Agent 打开列表弹窗（名称、描述、路径），再点一项在 Quick Look 里看它的 Markdown，悬停一行出现的「编辑」在内置编辑器里改它。

这个页面严格只读，不运行 MCP 命令，也不显示 MCP command、URL、token 或环境变量值。配置文件在页面打开期间发生变化时不会自动轮询，点右上角「刷新」重新读取。文件损坏时只显示脱敏的路径与行列，其他来源仍继续展示。当前 M5a 只提供摘要；分层编辑、保存前 diff、保格式写回和冲突检测属于 M5b。

监控官：全局活动视图（⌘⇧O）

⌘⇧O（或菜单「会话 → 监控官」）在最左打开「◎ 监控官」标签，再按一次回到它。它把所有窗口的 Agent 会话和普通终端排成卡片，不用逐个切过去看；显示期间每秒刷新一次。

• 分组：与左栏「按状态」相同：需要你、出错、运行中、完成未看、空闲、终端，最后是默认折叠的「已结束」。顶部筛选条有「全部」和每个非空分组（不含「已结束」）；点一个只看这一组，再点一次回到「全部」，筛选的分组空了也会自动回到「全部」。标签标题会写「· N 需要你」。
• Agent 卡片：会话名和位置、状态与当前动作；⎇ git · 第 N 轮 · 本轮 X / 用时 X · +a −b · N 文件（分支、第几轮、本轮耗时、增删行数和文件数；任务的净改动没算出来（计算中或算不了）时只写文件数）；TODO 进度条与「TODO a/b · 上下文 N%」；完成未看时附最后回复首句的引语「…」。
• 终端卡片：名称 · ~目录；正在运行时显示「● 命令 · 已运行时间」，否则显示「最后一条：✓ / ✗ 命令 · exit N · 用时 · 多久前」（多行命令只显示第一行加 …；失败的命令再附最后一行输出）；末行是「前台：程序」，没有前台程序时是「空闲」。命令需要 gilvt 的 shell 集成（默认开启）。
• 补课：卡片上点「补课」（或选中后按空格），Agent 列出每一轮（提示词首行、结果、耗时、增删行数），终端列出最近 10 条命令。点一轮回到那个会话并在检查器「过程」里展开这一轮；点一条命令回到那个终端并滚到那条命令。
• 键盘：方向键选卡片，⏎ 跳过去，Space 展开或收起补课。
• 监控官只看不写：它不会向任何终端输入内容。重启后监控官标签会恢复。

✦ AI 总结

打开后，每张卡片可以带一块「✦ AI 总结」（目标、近期进展），左栏会话行也显示总结「近期」的第一句。总结由你本机的 Claude 或 Codex CLI 生成，默认关闭。

开启：在 config.toml 里加 [monitor] 并设 enabled = true。也可以直接在设置窗口里开启和调整（见下一小节）。

[monitor]
enabled = true            # 默认 false；false 时不调用任何 CLI，卡片与左栏同未开启
provider = "claude"       # "claude" 或 "codex"
model = ""                # 空 = CLI 默认模型
summary_model = ""        # 总结专用模型；空 = 同 model
command = ""              # CLI 可执行文件路径；空 = 在登录 shell 的 PATH 里找
auto_summary = true       # 自动刷新总结
summary_interval = "2m"   # 运行中的自动刷新间隔，支持 s / m / h，最小 30s
sidebar_summary = true    # 左栏会话行显示总结首句
exclude_paths = []        # 这些目录下的会话 / 终端不总结，支持 ~

summary_interval 无法解析（或含非 ASCII 字符）时退回 2m，并在启动错误里提示。

设置窗口（⌘,）

⌘,（或菜单「gilvt → 设置…」）打开设置窗口，只有一个：已打开时再按只是把它带到前面。⌘W 关闭它；关掉它之后如果没有任何工作区窗口了，gilvt 随之退出。左侧导航有两页：「◐ 外观」（主题，见「主题」一节）和「◎ 监控官」；打开时停在上次看的那一页，第一次是「外观」。

改完立即生效，并写回 config.toml：每个控件一改就在运行中生效（enabled 关掉时总结队列清空、✦ 块消失，已缓存的总结保留；通道、模型、CLI 路径从下一次调用起生效），同时写进 [monitor] 表。写回只动这次改的键，你文件里的注释、排版都原样保留；写之前会重新读取磁盘上的文件，所以不会盖掉你刚在编辑器里改的内容；config.toml 是符号链接时写进链接指向的文件，文件权限不变。从不打开设置窗口、也没有 [monitor] 表的人，config.toml 不会被改动一个字节。写回失败时设置页显示红色提示，修改仍在本次运行中生效。config.toml 是只读文件时 gilvt 不会覆盖它（「外观」页选的主题也一样）：设置页顶部红字先写「config.toml 是只读的，没有写入」，下一行是文件路径，修改只在本次运行中生效。

手改文件也会自动重新加载：在编辑器里改 config.toml 并保存，文件停止变化约 200 毫秒后 gilvt 重新读取并刷新所有窗口（gilvt 自己写回触发的变化会被忽略）。只有文件里改动过的键才覆盖运行中的值，所以用 ⌘+ / ⌘− 临时调的字号不会因为你在设置窗口里点了一下、或在文件里改了别的键而被打回去；文件里的 font_size 本身变了，才以文件为准。还没有 ~/.config/gilvt/ 目录时也一样：目录一出现（第一次写回或点「在编辑器中打开」时创建）就开始监视。文件有语法错误时，设置页顶部出现黄色提示，所有控件只读，gilvt 继续使用最后一次有效的配置，修好保存后自动恢复；文件被删除则回到默认值。

• 模型：「通道」选 Claude 或 Codex，切换通道会把两个模型重置为「CLI 默认」。Claude 的下拉是固定别名：CLI 默认、fable、opus、sonnet、haiku；Codex 的列表来自 codex app-server 的 model/list，打开页面时拉取一次，旁边的「↻ 刷新」可重拉，失败时只有「CLI 默认」并显示原因。「总结模型」多一项「同对话模型」。
• 「其他…」：最后一项，选中后该行变成一个输入框（提示「模型名，⏎ 试跑」），填模型名按 ⏎，gilvt 用这个名字试跑一次总结，成功才写入；Esc 取消。失败时原值不变，提示原因：通常是「模型不存在或无权使用（…）」，也可能是「未找到 claude，请在设置里指定 CLI 路径」、「claude 认证失败（请在终端运行 claude 登录）」或「超时」（Codex 同理）。配置里的值不在列表里时显示「<值> ⚠ 不在列表中」。
• 自定义 CLI 路径：输入框留空 = 在 PATH 里查找；也可以点「选择…」挑一个可执行文件。
• 测试连接：用当前配置试跑一次，它依次检查 CLI 版本、一次总结，再跑一轮真实的对话（让模型调用一次 list_sessions），成功显示「✓ 程序 版本 · 认证正常 · 总结 N s · 对话 N s（list_sessions ✓）」；这一轮对话用的是当次生成的临时 token，关掉设置窗口后它作废。监控官的总开关关着时不跑对话（不向外发送会话数据），结果行末尾是「· 对话未测试（监控官未开启）」，打开开关后再测即可。常见失败：「未找到 claude，请在设置里指定 CLI 路径」→ 在上面填路径；「claude 认证失败（请在终端运行 claude 登录）」→ 在终端里登录（Codex 同理）。测试期间设置又改了，结果作废，需要再测一次。
• ✦ AI 总结：「自动刷新」开关；「最小间隔」分段选择（同一会话两次自动总结之间至少隔这么久）；「左栏显示摘要行」开关。
• 排除目录：「＋ 添加…」选目录；点目录标签上的 × 移除；写入文件时放在用户目录下的写成 ~/… 形式。这些目录下的会话和终端不会送给模型：卡片照常显示，但没有 ✦ 块。
• 在编辑器中打开：用你的默认编辑器直接打开 config.toml。

哪些键何时生效（无论来自设置窗口还是手改文件）：字体（font_family、font_size、line_height、fallback_fonts）、theme、option_as_meta、[notify]、[monitor] 立即生效；[agent] 的 claude_launch / codex_launch 从下一次 gilvt 替你输入启动命令起生效，claude_commands / codex_commands 立即用于识别前台的 Agent 进程。scrollback、kitty_keyboard、shell 只影响之后新开的 pane；claude_commands / codex_commands 交给 shell 集成的部分（让 Agent 向 gilvt 报告状态）也只在新开的 pane 里生效。只有 shell_integration 要重启 gilvt 才生效。

隐私：

• 默认关闭；开启后只有未排除的会话和终端才会把内容交给 CLI。
• exclude_paths 按路径分量匹配（符号链接先解析）：会话或终端的目录在其中就不总结；终端里的单条命令，开始时或结束后 shell 所在的目录在排除目录中（例如在 ~ 里运行的 cd ~/secret && cat notes），或命令行里直接写了排除目录的路径（绝对路径、~/…、$HOME/…，例如 (cd ~/secret && make)），也不会送出。
• 排除只看工作目录和命令行里写出的路径，不看程序实际读写了哪些文件：在普通目录里运行的脚本去读排除目录中的文件，它的命令和输出末尾仍可能送出。
• 送出的数据：Agent 会话首次总结取最近 2 轮，之后滚动更新（上一份总结 + 更新的最多 3 轮）；终端取最近 10 条命令及输出末尾。总长上限 24 KiB，每个工具调用 4 KiB。
• CLI 以无界面方式运行：关闭工具、关闭 hooks、不连接你配置的 MCP 服务器、不写会话文件（claude -p … --strict-mcp-config --no-session-persistence；codex exec --ephemeral -s read-only，并用一个 -c mcp_servers={"<名字>"={enabled=false},…} 关掉 ~/.codex/config.toml 里的所有 MCP 服务器（名字带点或空格也可以）），工作目录是 <state>/monitor/run，超时 90 秒，同时最多 2 个；退出 gilvt 时还在运行的 CLI 会被结束。对话进程同样关闭工具、hooks 与你配置的 MCP 服务器：Claude 用 --strict-mcp-config，Codex 同样用 -c mcp_servers={…} 关掉 ~/.codex/config.toml 里的所有 MCP 服务器，只留 gilvt 自己的 gilvt。Claude 对话进程固定用 --permission-mode dontAsk（不跟随你配置的默认权限模式，只有 gilvt 的工具能用）；Codex（总结与对话）都带 -c notify=[]，你配置的 notify 程序收不到监控官的回答。注意：如果你自己的 Codex 配置里也有一个名叫 gilvt 的 MCP 服务器，它的设置会与 gilvt 注入的合并在一起，请改个名字。
• 找 CLI：从访达或程序坞打开的 gilvt 只有系统默认的 PATH，所以 gilvt 启动时用你的登录 shell（$SHELL -lic）读一次 PATH，在里面找 claude / codex，并把它交给 CLI（npm 装的 CLI 还要靠它找到 node）。仍然显示「✦ 总结失败：未找到 claude（请在 [monitor] command 里填写完整路径）」时，把 command 设成 which claude 的结果。

刷新规则：

• 自动：一轮结束、变成「需要你」或出错时，以及运行中每隔 summary_interval；两次之间至少隔 summary_interval，且只在有新活动时才刷新。
• 手动：点「✦ 重新总结」，点「✦ 生成总结」或「重试」，或选中卡片后按 s（带 ⌘ / ⌃ / ⌥ 时不处理）。
• 连续失败 3 次后暂停该会话的自动总结，卡片显示「✦ 已暂停自动总结：…」，手动成功后恢复。
• 卡片上 ✦ 块的状态：生成中… / 更新中… / 已生成（刚刚、N 分钟前，覆盖第几轮或最近几条命令）/ 有新进展 / 失败 / 已暂停。
• 已结束的会话显示保存的总结（缓存在 <state>/monitor/summaries/），不能再重新总结；终端的总结只在内存里，重启后消失。

对话

打开监控官并开启 [monitor] enabled 后，「◎ 监控官」标签右侧是对话面板（宽 360 px），用来问「哪些需要我？」「有什么出错了？」这类问题。标签页窄于 760 px 时，面板收成右边缘 26 px 的「◎」竖条（有没读过的回答时带角标），点它展开为盖在卡片墙上的浮层；面板标题栏的「⇥」收起它。未开启监控官（enabled = false）时没有面板、竖条和「◎ 问它」，A 键也不处理。

怎么问：

• 直接在输入框里写；⏎ 发送，⇧⏎ 换行。输入框空着时有三个快捷问题：「✦ 生成站会简报」（先列「要你处理」的事，再给「整体」概览）、「哪些需要我？」「有什么出错了？」。
• 卡片上的「◎ 问它」，或选中卡片后按 A（字母键；带 ⌘ / ⌃ / ⌥ 时不处理），把这张卡片作为范围放进输入框。
• 输入框里敲 @（全角 ＠ 也行）弹出会话列表，↑ / ↓ 选、⏎ 确认、Esc 关闭；可以选多个，范围 chip 上的 × 移除。范围随消息留在气泡上，也留在输入框里方便追问。
• 回答里的会话名是链接，点一下回到对应的会话或卡片。

它能看什么：五个只读工具——列出会话、会话概况、某几轮的时间线（最多 3 轮）、终端命令（最多 20 条）、读屏（最多 200 行；对话里会显示「正在读取 … 的屏幕」和「已读取 … 的屏幕（最后 N 行）」）。每个工具调用都会显示在回答里。exclude_paths 下的会话和终端对它不存在。它不能执行任何操作：写入 pane、批准、发消息都不行（那是以后阶段的事）。

进程与费用：

• 第一条消息时才启动你自己的 claude 或 codex；所有窗口共用同一个进程，用的是设置里的「通道」和对话模型，调用的是你自己的账号额度。
• 空闲 30 分钟，进程自动结束（对话历史保留，下一条消息自动重启，并带上最近 6 轮问答作为前情）；「新对话」清空历史并结束进程。
• 回答中再发消息，会先中断当前这一轮（5 秒内没有停下就结束进程、带前情重启）；「停止」只停当前这一轮；一轮连续 5 分钟没有任何输出也会被自动中断，显示「（这一轮已中断）」。
• 进程意外退出时对话里显示「监控官进程已退出（…）」，下一条消息会自动重启。
• Codex 需要能关掉 shell_tool、unified_exec、hooks，保证它只能通过 gilvt 的只读工具查数据；找不到其中任何一个开关时，面板显示红色的「无法启动 Codex 对话」说明卡，可以改用 Claude 或升级；✦ 总结不受影响。

隐私：对话历史只在内存里，重启 gilvt 后清空；工具调用都显示在对话里；gilvt 每次启动对话进程（以及「测试连接」）都生成一个随机 token，只交给它自己启动的那个进程，进程结束即作废，命令行里看不到它。

排错：出错卡片上的「查看日志」打开 ~/Library/Application Support/gilvt/state/monitor/chat.log，「打开设置」跳到设置窗口；设置窗口的「测试连接」会跑一轮对话并调用一次 list_sessions。

已知限制：对话历史不跨重启保留（其他限制见「已知限制与排障」）。

命令条（⌘⇧M）

• 开启监控官后，每个工作区窗口（设置窗口除外）的 pane 区域下方有一条 20 px 的细线：回答、启动、停止进行中显示「◎ 监控官 · 回答中…」（「启动中…」「停止中…」同理）；回答结束后显示最新一条回答的第一句（回答里没有正文、只有标题时用标题）；出错时显示「◎ 监控官 · 出错：…」；还没有对话时只显示「◎ 监控官」。右边的提示是「⌘⇧M 提问」，有没看过的回答时多一个红点。
• 在任何标签里（终端、Agent、编辑器、监控官）按 ⌘⇧M（或点击细线、菜单「会话 → 监控官命令条」），输入框获得焦点，上方显示最近一轮问答；⏎ 发送（发送后浮层保持展开，回答在上方出现）、⇧⏎ 换行、@ 选会话，和对话面板一样。这个组合键不会写进终端或 Agent。
• Esc 或再按 ⌘⇧M 收起，键盘回到原来的位置；@ 候选开着时，第一次 Esc 只关候选。命令条展开时按 ⌘W 只收起命令条，不会关掉下面的 pane；菜单「Close Tab」、点击某个 pane、⌘1–⌘9 切换标签也会收起它。pane 自己关掉（比如 shell 退出）时，命令条保持展开、键盘仍在输入框里。收起时输入框里没发的文字会保留（@ 候选与未完成的输入法拼写不保留）。
• 「在监控官中查看 ↗」：切到本窗口的「◎ 监控官」标签（没有就新建）并打开对话面板；回答里的会话名点击后跳到那个会话（已被排除或找不到的会话只显示为普通文字）。
• 所有窗口的命令条和对话面板是同一条对话；展开、收起状态与输入框草稿则每个窗口各自独立。展开命令条不会改变终端大小（浮层盖在 pane 底部，最高 260 px，超出滚动）。
• 关闭监控官时命令条不出现，⌘⇧M 不起作用；运行中关掉监控官，已展开的命令条随之收起。

恢复与管理会话（⌘⇧R）

「会话」浮层列出本机所有 Claude Code 和 Codex 会话，默认只看当前项目。输入文字时切到「全部项目」，按标题、首条提示词、项目名、目录匹配，也可以输入会话 ID 的开头。

会话叫什么：不再只看第一条提示词。Claude 和 Codex 自己给会话起的标题会优先显示（你在 Claude 里改过的标题 > Agent 生成的标题 > 清洗过的第一个有信息量的提示词，「继续」「好的」这类应答会被跳过）；你在 gilvt 里 ⌘R 改的名字永远最高。搜索既能按标题找，也能按当初的原话找。新会话的标题要等下一次刷新（再按一次 ⌘⇧R）才会出现。

恢复做的事和你手敲完全一样：gilvt 在 pane 里输入 cd <原目录> && claude --resume <id>（Codex 是 codex resume <id>）。恢复后左栏显示原来的会话名，检查器补出之前的轮次。

每行名称下面一行灰色小字是会话运行过的目录（~/…/项目/子目录 · 分支 · N 轮）；目录已经不存在（比如删掉的 worktree）时加删除线并标「目录已不存在」，恢复前就能看到。

归档：处理完了、但想留着的会话，选中后按 ⌘E（或右键「归档」）收起来：它离开默认列表、待 Review 队列和左栏「已结束」，搜索默认也不命中；文件不动。筛选条的「已归档」可以查看、搜索、恢复或取消归档。归档后这个会话又完成了新的一轮，会自动取消归档并回到待 Review，不会漏看；只改标题不算。运行中的会话不能归档。

清理旧会话：打开「≥ 7 天未活动」筛选会显示每个会话的大小，多选后 ⌘⌫ 移到系统废纸篓，可以在访达里「放回原处」。正在运行的会话不能删除。删除会把按会话 ID 命名的附属数据一起带走（Claude 的 file-history/<id>/、tasks/<id>/ 等，Codex 的 shell 快照），确认条里分开显示大小（「X MB + 附属 Y MB」）；history.jsonl、Codex 的 sqlite 这类共享数据不动。

清理向导（⌘⇧K）：一次处理一批。左边四个预设，右边是命中的会话预览，每行带勾选框、默认全选，底部实时显示「已选 N / M · X MB」。

运行中的会话永远不会命中；置顶的会话默认不勾选；还没 Review 的会话只出现在「空会话」「最大的 20 个」里并标「尚未 Review」。「移到废纸篓」仍然先出确认条，取消后什么也没移动。向导的入口还有会话浮层里的「清理…」和「会话」菜单。

待 Review：看完没有？（⌘⇧R → ⌘2）

⌘⇧R 打开的 Session Center 有四个 tab：⌘1 需要你、⌘2 待 Review、⌘3 运行中、⌘4 全部会话（就是上面的恢复与管理）。会话多了以后，「待 Review」告诉你哪些结果还没看：Agent 新完成的 turn 会进入队列，失败的排在前面。左栏标题下的「待 Review N」也是入口。

选中一行按 Space，不用启动 Agent，就能只读查看这个会话新增的 prompt、Agent 的最终回复、工具调用和错误。看完按 ⌘↩「已 Review，下一个」；想晚点再看按 Z 选稍后提醒；只是想换一个看按 S 跳过；F 看完整历史。

在 Review 里按 ⇧⌘E「标记已 Review 并归档」，会话离开队列并自动打开下一项。

几点要知道：第一次启用时，现有的历史会话都算「已看过」，不会一下子灌满队列；只是打开、滚动或关闭 Review 不会标记已看，必须你按 ⌘↩；Review 打开期间 Agent 又完成的新 turn 不会被这次确认吞掉，仍留在队列里；Review 页面从不向终端输入任何内容；带 ⌘ / ⌥ / ⌃ 的字母不是快捷键，不会误触发。

如果会话记录被截断或替换过，保存的 Review 位置会找不到。这样的会话会以「失败」出现，打开后按 B「从当前开始」（现有内容都算看过）或 A「Review 全部可见历史」（现有每一轮都重新待 Review）。

新建 Agent（⌘⇧N）

直接在终端里敲 claude 仍然是最常用的方式。⌘⇧N 适合一次开多个 Agent，或者要在别的目录启动：

• Agent：⌘1 Claude / ⌘2 Codex。
• 目录：默认是当前 pane 的目录，Tab 补全子目录。
• 初始任务：可以留空；⇧↩ 换行。
• 更多：模型和权限模式，→ 展开。
• 在新 worktree 中运行（⌥W）：默认关闭；所选目录不在 git 仓库里时置灰。勾选后 gilvt 在 <仓库>.worktrees/gilvt-<名字>-<4 位> 建一个 worktree、分支 gilvt/<名字>-<4 位>，Agent 在里面启动。建不出来时面板保持打开并在面板里显示红色错误，不启动任何东西。gilvt 不会自动删除 worktree，会话结束后由你自己清理。
• 命令预览：底部实时显示将要执行的完整命令和位置，实际输入的就是这一行。目录不存在时变红，不会执行。

↩ / ⌘↩ / ⌘⇧↩ 决定在哪里打开，规则与「会话」浮层相同。gilvt 会记住你上次选的 Agent、模型和权限模式。

通知与 Dock

只有 gilvt 不在前台、或那个 pane 不可见时才发通知；静音的会话不发。点击通知跳到对应的 pane。

Dock 角标显示「需要你」的会话数（不计静音的）。gilvt 在后台时，每有一个会话开始等你，Dock 图标跳一次。不想要跳动可以设置 [notify] dock_bounce = false。

主题（⌘, →「外观」）

主题在 ⌘, 设置窗口的「◐ 外观」页里选（左栏第一页；窗口打开时停在上次看的那一页，第一次是「外观」）。以前菜单 gilvt → Themes… 打开的浮层选择器已经去掉。

• 搜索与过滤：在搜索框输入主题名；「全部 / 深色 / 浅色」切换过滤。
• 固定 / 跟随系统：「固定」始终用一套主题；「跟随系统」有浅色、深色两个槽位，系统外观变化时自动切换。
• 选中即生效：点一项、↑↓ 或 ⏎（选中高亮的那一行），所有窗口（包括设置窗口）立刻换成它，没有预览和还原这一步；Esc 只清空搜索。外框、状态色和窗口标题栏都跟着变（固定主题时标题栏强制为浅色 / 深色，跟随系统时由系统决定）。右侧预览高亮主题的 16 色、示例输出和四种状态标记；有 [colors] 覆盖时页面上会注明。
• 写回：选择停下约 300 ms 后写入 config.toml（只改 theme 一项，注释保留，符号链接的配置文件也能写）；连续按 ↑↓ 不会每一步都写文件。
• 写回失败：配置文件只读等情况下，主题只在本次运行中生效，页面顶部红字先写原因（如「config.toml 是只读的，没有写入」），下一行是文件路径。配置文件有语法错误时页面只读，修好后才能再选。
• 手改配置：直接编辑 config.toml 的 theme 或 [colors]，保存后立即生效，不用重启；名字写错时同样出现错误横幅。

自己的主题：把主题文件（纯文本，每行一个 key = value，与内置主题同一格式）拷到 ~/.config/gilvt/themes/，文件名就是主题名；它优先于同名的内置主题（先按名字精确匹配，再不区分大小写）。在 config.toml 里写：

theme = "My Theme"                                   # 固定
# theme = { light = "gilvt Light", dark = "My Theme" }   # 跟随系统
[colors]                                             # 可选：在主题之上单项覆盖
# background = "#1b1b26"
# palette = { 1 = "#ff5f5f" }

[colors] 支持 background、foreground、cursor、cursor_text、selection_background、selection_foreground 和 palette（0–15）。名字写错或主题文件无效时，顶部会出现错误横幅和「你是不是想用 …」的建议，gilvt 暂时用默认主题。状态色取主题的 ANSI 3 / 1 / 4 / 2，对比度不够时自动修正；默认主题下 Markdown 预览保持 GitHub 配色。

配置

配置文件是 ~/.config/gilvt/config.toml，所有字段都可选：

font_family = "Menlo"
font_size = 13.0
line_height = 1.25
fallback_fonts = ["PingFang SC", "Apple Color Emoji"]
theme = "system"          # system | light | dark | 主题名 | { light = "…", dark = "…" }（见「主题」）
scrollback = 100000
option_as_meta = true     # Option 作为 Meta
kitty_keyboard = true
shell_integration = true

[agent]
claude_commands = ["claude"]            # 被识别为 Agent 的命令名
codex_commands = ["codex"]              # 包装脚本也写进来，如 ["codex", "codex-w"]
claude_launch = "claude"                # 恢复 / 新建时输入的命令名
codex_launch = "codex"

[notify]
dock_bounce = true

[update]
mode = "download"         # download | check | off（见「更新」）

[colors]                  # 可选：在主题之上单项覆盖
# background = "#1b1b26"

用 codex-w 这类包装脚本启动 Codex 时，把它加进 codex_commands（gilvt 才会识别它），并把 codex_launch 设为它，恢复和新建就会用它。如果你已经给 claude 定义了别名，gilvt 不会覆盖；想让它也被识别，把别名改为 alias claude='gilvt_agent claude claude --model opus'。

gilvt 自己的状态（重命名、静音、界面宽度、会话索引缓存）保存在 ~/Library/Application Support/gilvt/state/。

快捷键总表

已知限制与排障

已知限制

• Quick Look、固定预览 pane 里的文字还不能选中复制（已排入后续版本）。
• 「产物」只在 git 仓库里记录文件改动；非 git 目录只有标题、耗时和引语。
• 多轮任务的净改动包含两轮之间你手动改过的内容；应答类只认整句「继续」「好的」等，不会合并「好的，再把 X 改了」。
• gilvt 没在记录的轮（恢复的旧会话、gilvt 启动前的轮）没有文件列表。
• 同一个目录里有多个会话同时改文件时，各自的快照会混入对方的改动，卡片不做归因。
• 超过 5 MB 的文件不进快照；其中已被 git 跟踪且被修改的，快照里保留的仍是它旧的已提交内容（只提示「已跳过」），所以它的改动看不到。
• 设置窗口：shell_integration 的改动仍需重启 gilvt，scrollback、kitty_keyboard、shell 只影响新开的 pane；Claude 的模型列表是固定别名。
• 「配置」目前只读；不验证 MCP 连接状态，也不能编辑或写回（M5b）。
• 在别的终端应用里运行的会话，gilvt 不知道它在运行。
• 监控官的终端卡片依赖 gilvt 的 shell 集成：关闭 shell_integration、或 bash 里已经有自己的 DEBUG trap 时没有命令记录；bash 里不进历史的命令（HISTCONTROL=ignorespace 下以空格开头）记为「（命令未知）」；与上一条历史编号相同的命令，只有整行与上一条完全相同的简单命令才记录（HISTCONTROL=ignoredups 下重复的简单命令可以正常工作，重复的管道或复合命令记为「（命令未知）」）。命令原文在 shell 端截到 2000 字节（fish 为 600 个字符），截断处以 … 结尾。
• 监控官的对话：历史不跨重启保留。
• 监控官的对话：exclude_paths 只挡掉排除目录下的会话与终端。它读一个未排除终端的屏幕（read_screen）时，屏幕上仍可能留着碰过排除目录的命令的输出；读屏是对话里明示的显式操作。
• 监控官的对话：标签页窄于 760 px 时面板收成右边缘的「◎」竖条、点开是盖在卡片墙上的浮层；默认窗口大小下显示着检查器时，监控官标签就窄于 760 px，要看到侧边面板请用 ⌘I 隐藏检查器或把窗口拉宽。
• 监控官的对话：Codex 需要能关掉 shell_tool、unified_exec、hooks 三个开关，否则面板显示「无法启动 Codex 对话」，✦ 总结照常；对话只有 Claude 与 Codex 两条通道。
• 命令输出摘录可能多一两行或少一两行；命令记录不跨重启保留，每个终端最多保留 50 条。
• 监控官与终端分屏放在同一个标签里时，重启后只恢复终端部分；只有监控官、没有终端标签的窗口不保存，重启后不恢复。
• 实时预览只单向跟随滚动（编辑到预览），不能在预览里编辑。
• 重启后 Agent 不会自动恢复，需要在左栏「待恢复」里点；编辑 pane 和预览也不恢复。
• 归档和清理只作用于已有的会话，不支持自定义条件或定时自动清理；废纸篓里的会话要在访达里还原。
• Codex 第一次启动时可能处于精简模式：gilvt 需要不到 1 秒在后台取得它的 hooks 信任信息，之后启动的会话正常。
• Codex 默认使用备用屏幕界面，时间线里的事件点击只展开详情、不跳转终端。
• 跟随系统模式下，在「外观」页编辑与当前系统外观不同的槽位时，只能在右侧预览里看到效果。
• 设置窗口开着时新放进 ~/.config/gilvt/themes/ 的主题，要关掉设置窗口再打开才会出现在「外观」页的列表里。
• 不支持背景透明度和模糊。
• 主题目录里的符号链接会被跟随：指向别处的链接会被当作主题文件读取。
• 左栏悬停提示（tooltip）始终保持深色样式。

常见问题

• Dock 没有角标：打开「系统设置 → 通知 → gilvt」，确认「允许通知」已打开。关闭通知时 macOS 也会隐藏角标。
• 没有系统通知，或点击通知打开了「脚本编辑器」：请用 scripts/bundle.sh 打包后从 Gilvt.app 启动。
• 左栏显示「精简模式」：hooks 没有生效。检查是否用了 claude --bare，或自己的 claude 别名没有改为调用 gilvt_agent。
• 状态卡显示「该版本暂未完全适配」：Claude / Codex 升级后记录格式有变化，终端本身不受影响。