herdr-throwaway-repro

Herdr 一次性复现

当复现需要一个真实的 Herdr 服务、窗格、PTY、Agent 或 socket API，而又不想危及用户的主会话时，请使用一个一次性的具名 Herdr 会话。

这个临时 TUI 只负责保持该一次性会话处于附着状态，并提供终端几何信息。请通过 Herdr 的 CLI/API 从父会话驱动复现。除非该 bug 明确需要客户端输入，否则不要手动操作这个嵌套的 TUI。

不可妥协的安全要求

• 绝不要在默认会话中运行复现。
• 绝不要停止、重启、删除或终止主 Herdr 服务。
• 绝不要使用 pkill、宽泛的进程匹配或猜测的 PID 来进行清理。
• 创建一个唯一的会话名称。绝不要复用或删除一个不相关的具名会话。
• 创建一个新的外层窗格，并在清理时只关闭该窗格。
• 从命令输出中读取 workspace、tab、pane、terminal 和 agent ID。绝不要自行构造它们。
• 使用 /var/tmp 存放复现目录和可能体积较大的产物。
• 不要批准破坏性或非必要的 Agent 操作。
• 未经用户批准，不要消耗付费的 Agent token。使用所要求的低成本模型和尽可能小的提示词。

先了解已安装的接口

已安装的二进制文件才是权威依据。自本技能编写以来，CLI 语法可能已经发生变化。

在做任何事之前，先确认调用方位于 Herdr 内部，并查看相关帮助：

test "${HERDR_ENV:-}" = 1
herdr --version
herdr --help
herdr session
herdr pane
herdr agent

在使用不熟悉或可能产生变更的命令之前，先查看嵌套命令的帮助。不要为了探索而直接运行裸的 herdr，因为它会启动或附着 TUI。

记录本次复现所测试的 Herdr 二进制文件及版本。如果要测试某个 checkout 构建，请遵循该仓库关于运行该构建的说明，而不要悄悄替换为已安装的二进制文件。

创建外层窗格

在当前 tab 中创建一个同级的 shell 窗格，且不要移动焦点。如果测试框架提供了可用的 Herdr 布局工具，请使用它。否则，在查看已安装的窗格拆分命令的帮助后使用该命令。

将 /var/tmp 或一个专用的复现目录作为新窗格的 cwd。保存返回的外层 pane ID。这是清理时唯一允许关闭的父会话窗格。

启动一次性会话

选择一个简短的唯一名称，例如 repro-<topic>-<timestamp>。

启动前，在一次性客户端实际会加载的配置中显式允许嵌套。HERDR_ENV=1 会从外层窗格继承，因此除非启用 [experimental].allow_nested，否则启动会被拒绝。隔离的 XDG_CONFIG_HOME 不会从用户的全局配置继承此设置，即使那里已启用嵌套。

使用文件写入工具在复现目录下创建仅用于测试的配置。对于默认配置复现，其内容可以是：

[experimental]
allow_nested = true

如果使用用户的配置进行复现，请将该配置复制到测试目录，并在其现有的 [experimental] 表中启用 allow_nested（如果该表不存在，则添加该表）。不要创建重复的表或键。切勿为允许复现而编辑用户的全局配置，也不要取消设置 HERDR_ENV 来绕过嵌套检查。

在下方启动时，将测试配置的绝对路径作为 HERDR_CONFIG_PATH 传入。对配置验证以及任何必须加载测试配置的命令使用相同的覆盖。此覆盖选择的是配置文件；它不会隔离已保存的机器目录或其他全局状态。当复现会修改已保存的机器时，还要使用仅用于测试的 XDG_CONFIG_HOME 和 XDG_STATE_HOME，并在所有针对该测试环境的命令中保留这些覆盖。

在新的外层窗格中运行该命名会话。清除继承的会话选择、socket 覆盖和调用方 ID，以免嵌套运行时意外指向父会话：

env \
  -u HERDR_SOCKET_PATH \
  -u HERDR_CLIENT_SOCKET_PATH \
  -u HERDR_SESSION \
  -u HERDR_WORKSPACE_ID \
  -u HERDR_TAB_ID \
  -u HERDR_PANE_ID \
  HERDR_CONFIG_PATH=<absolute-test-config-path> \
  herdr --session <session-name>

需要时，向此启动命令添加特定于复现的环境变量。配置服务所需的环境变量必须在命名服务启动之前就位。

启动前，使用相同的配置覆盖通过 herdr config check 验证测试配置。启动后，读取外层窗格以捕获启动错误，例如 nested herdr is disabled by default；不要仅因为 pane run 成功返回就假定启动成功。

在命名会话的 API 就绪之前不要继续。通过从父会话指向该会话并列出其窗格来确认就绪状态。

仅指向一次性会话

从父会话发出的每条控制命令都必须清除继承的 socket 覆盖并显式选择临时会话：

env \
  -u HERDR_SOCKET_PATH \
  -u HERDR_CLIENT_SOCKET_PATH \
  -u HERDR_WORKSPACE_ID \
  -u HERDR_TAB_ID \
  -u HERDR_PANE_ID \
  HERDR_SESSION=<session-name> \
  herdr pane list

对每条命令重复此前缀。不要依赖 shell 状态在工具调用之间保持。

从 pane list 读取一次性根窗格 ID。在其中的任何操作开始之前，确认其 cwd 和前台进程。

命名会话隔离运行时状态、socket、窗格和持久化。默认情况下，它们仍然共享全局 Herdr 配置和 Agent manifest 覆盖。当配置来源可能影响复现时，检查配置来源。不要仅仅为了让测试通过而修改共享配置。

通过 API 驱动复现

对 shell 和普通进程使用 pane 命令：

• pane run 在可用的 shell 提示符下启动命令。
• pane wait-output 等待确定性输出。
• pane read 捕获终端内容。
• pane send-text 用于输入字面文本。
• pane send-keys 用于受支持的按键。
• pane get、pane process-info 和 pane layout 用于获取运行时状态。

只有在 Herdr 识别出编码 Agent 之后，才使用 agent 命令：

• agent start 在已有的 shell pane 中启动受支持的 Agent。
• agent prompt 原子性地提交一个提示词。
• agent wait 等待 working、blocked、idle、done 或 unknown。
• agent read 捕获 Agent 终端内容。
• agent get 和 agent explain 检查状态和检测结果。
• agent send-keys 用于交互式响应。

先运行相关命令组的帮助，因为名称和选项可能会变化。

优先使用等待，而不是任意睡眠。当计时本身也在测试范围内时，记录时间戳并使用有界轮询。在复现的状态转换之前、期间和之后捕获状态。

当所需终端按键不受高层命令支持时，只有在确认目标应用期望的按键之后，才通过一次性 pane 发送其终端序列。切勿向父 pane 发送原始控制序列。

谨慎启动 Agent

在启动 Agent 之前，检查其已安装的 --version 和 --help。在 Herdr 的参数分隔符之后传递原生 Agent 参数。

使用用户请求或批准的精确模型。从实时 Agent 屏幕验证模型，而不是信任别名。当 Agent 支持时，基线优先使用低 effort、安全模式和手动权限。只有当怀疑的行为依赖 hooks、plugins 或 settings 时，才用用户的真实配置重复。

使用无害操作进行权限状态测试。在捕获证据后拒绝待处理操作，并验证没有创建任何产物。

收集有用的证据

记录足够的信息，以便他人重复该结果：

• Herdr 二进制文件和版本。
• 命名会话和启动环境。
• 目标应用或 Agent 版本和参数。
• 精确的命令或提示词。
• 每次状态转换前后的 pane 和 agent 状态。
• 相关的 pane read、agent read、agent explain、API 输出和会话日志。
• 生效的是全局配置还是本地 manifest 覆盖。

从 herdr session list 读取命名会话目录和 socket，而不是假设其路径。除非用户要求保留到其他位置，否则将大型证据放在 /var/tmp 下。

区分观察到的事实和提出的原因。先复现原生行为，然后每次只改变一个变量。

清理

清理是复现的一部分，包括失败之后。

1. 拒绝待处理的提示词，并在可行时干净地停止测试应用。
2. 验证无害的探测文件或其他测试产物不存在，或仅移除本次复现创建的产物。
3. 使用已安装的 session 命令停止临时命名会话。
4. 删除同一个已停止的会话。
5. 确认它不再显示为运行中。
6. 等待外层 pane 返回到其 shell。
7. 仅关闭此工作流创建的外层 pane。

切勿因为另一个命名会话看起来陈旧就删除它。切勿关闭运行当前 Agent 的 pane 或任何不是为本次复现创建的 pane。

报告结果

说明复现了什么、没有复现什么，以及失败的确切状态转换。包括清理状态。提及可能影响结果的共享配置或 manifest 覆盖。