捕获代理 PTY 转录¶

Orca 的就绪规则和阻塞提示规则是针对代理 CLI 在终端上绘制内容的文本规则。它们的质量只取决于所针对的屏幕。这是如何逐字节记录一个屏幕，以便规则可以固定到证据，而不是固定到记忆中的屏幕。

相关：antigravity-readiness-evidence.md 列出了仍然缺失的具体 Antigravity 转录，以及每个转录判定什么。

记录器¶

node config/scripts/capture-agent-pty-transcript.mjs --name <fixture-name> [options] -- <command> [args...]

它分配一个真实 PTY，在其中启动代理，将会话镜像到你的终端，以便你手动操作，并将它接收到的每个字节追加到 src/main/runtime/__fixtures__/<fixture-name>.txt。它不会剥离转义序列、折叠 \r、重新换行或规范化任何内容——该文件就是终端接收到的内容。

• 结束捕获： 按 Ctrl+]。记录器会消费该按键且从不转发它，这是在_对话框仍占据屏幕时_结束捕获的唯一方式。如果改为退出代理，则会先关闭你正要记录的对话框。
• --cols N --rows M 固定 PTY 尺寸（默认：你的终端尺寸）。换行是证据的一部分，因此要记录尺寸——伴随文件会替你完成。
• --duration S 在无人值守模式下于 S 秒后停止，适用于无需交互的屏幕。
• --send "<ms>:<text>" 在固定偏移处向 PTY 输入，可重复使用，支持 \r \n \t \e 转义。对话框捕获必须被驱动，而无人值守运行（CI 或代理）没有可输入的 TTY；按键会经过与人类相同的 PTY。例如，已提交的 antigravity-dialog-model-picker.txt 使用 --duration 24 --send "14000:/model" --send "16000:\r" 记录，捕获停止时选择器仍占据屏幕。
• --note "<text>" 在伴随文件中记录账户类型、套餐、模型和 CLI 版本。
• --out <path> 写入夹具目录之外（首次试运行可使用它）。

每次捕获还会写入 <fixture-name>.meta.json，包含时间戳、平台、命令、 PTY 尺寸、备注和退出码。请与转录一起提交；屏幕背后的版本和账户类型无法从字节中恢复。

前提条件： node-pty 必须为普通 Node 构建：

node config/scripts/ensure-native-runtime.mjs --runtime=node

Orca 本身无需运行，且记录器从不触及 Orca 状态。

平台说明¶

• macOS / Linux： 无特殊要求。会为子进程设置 TERM=xterm-256color。
• Windows： 请从 Windows Terminal / PowerShell 运行，而不是 Git Bash (MSYS) 窗格——MSYS 会重写以 / 开头的参数，这会破坏 cmd.exe /c 的交接。.cmd 或 .bat 代理垫片无法由 node-pty 直接启动，因此记录器会替你通过 cmd.exe 路由它们。
• WSL： 在发行版_内部_捕获（从发行版的检出目录运行记录器）。从 Windows 侧记录 wsl.exe 会将登录 shell 横幅添加到转录中。
• SSH： 在执行主机上记录。本地记录的转录不是关于远程代理输出内容的证据。

隐私：提交前清理¶

实时代理屏幕通常包含不应进入 git 历史的内容：

记录器在捕获结束后立即扫描文件，并打印每个命中项的行和 列。要清理：

node config/scripts/capture-agent-pty-transcript.mjs --scan src/main/runtime/__fixtures__/<name>.txt --redact

脱敏会用等长占位符替换每个命中项（u…u@example.com、XXXX…）。 长度很重要：转录的价值在于其精确的换行和列对齐，较短的 替换会重新排版屏幕并破坏证据。

验证其已消失¶

1. node config/scripts/capture-agent-pty-transcript.mjs --scan src/main/runtime/__fixtures__/<name>.txt 必须打印 clean 并以 0 退出。它能识别自己的占位符，因此已清理的文件会通过。
2. 搜索扫描器无法知道的特定内容： rg -n -i -- "$(whoami)|<your-email>|<your-org>|<your-hostname>" src/main/runtime/__fixtures__/<name>.txt
3. 以可见转义序列的方式阅读一次：LC_ALL=C cat -v src/main/runtime/__fixtures__/<name>.txt。 扫描器匹配模式；只有人类才能发现项目名称。
4. 也检查伴随文件——--note 文本是自由格式且会被提交。

config/scripts/pty-transcript-secret-scan.test.mjs 会重新扫描每个已提交的 __fixtures__/*.txt，因此跳过步骤 1 的转录会使测试套件失败。

在测试中消费转录¶

将原始字节通过运行时处理，而不是直接送入匹配器：转义处理、 尾部保留和标题跟踪都位于 onPtyData 中，在预规范化文本上测试的规则是在测试某种任何窗格都看不到的东西。

src/main/runtime/agent-transcript-pane-test-harness.ts 构建该窗格； src/main/runtime/terminal-interactive-wait-visibility.test.ts（cursor-agent）和 src/main/runtime/antigravity-readiness-transcripts.test.ts（Antigravity）是两个使用者。

实例：Antigravity 捕获¶

六个已提交的 antigravity-*.txt 夹具是以这种方式在 macOS 上针对 agy 1.1.25 记录的。有两点可以推广：

• 在不修改操作者配置的情况下达到某个状态。 就绪屏幕捕获运行在 CLI 已经信任的目录中，因此没有写入任何信任应答。如果某个对话框只能通过将操作者登出或删除其设置才能到达，则保持未捕获并如实记录，而不是强行触发。
• 当设置项无法充当捕获控制项时，环境变量是合法的捕获控制项。 AGY_CLI_HIDE_ACCOUNT_INFO=1 生成了第二个没有账户行的就绪屏幕，这是仅凭对第一个屏幕进行任何推理都无法提供的证据。它不会在磁盘上更改任何内容。

现有捕获中的已知缺口¶

三个 cursor-agent-*.txt 夹具包含没有转义字节，也没有回车符。 无论是什么生成了它们，都经过了渲染器和剪贴板，因此它们保留了措辞和 盒线字形，但没有保留文本光标、光标移动、重绘，或 CLI 是否使用 备用屏幕缓冲区。对于基于措辞构建的规则而言，它们已经足够，并且 不能作为其他任何方面的证据。使用此记录器制作的新捕获会保留这些字节； Antigravity 脚手架会断言它们的存在，因此粘贴的屏幕无法冒充捕获。