herdr-throwaway-repro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Herdr throwaway reproduction

Herdr 一次性问题复现

Use a disposable named Herdr session when a reproduction needs a real Herdr server, panes, PTYs, agents, or socket API without risking the user's main session.

The temporary TUI only keeps the disposable session attached and supplies terminal geometry. Drive the reproduction from the parent session through Herdr's CLI/API. Do not manually operate the nested TUI unless the bug specifically requires client input.

当复现场景需要真实的Herdr服务器、面板、PTY、Agent或Socket API，同时又不想影响用户主会话时，请使用一次性命名Herdr会话。

临时TUI仅保持一次性会话连接并提供终端几何参数。通过父会话中的Herdr CLI/API来驱动复现流程。除非Bug明确需要客户端输入，否则请勿手动操作嵌套TUI。

Non-negotiable safety

不可妥协的安全规则

Never run the reproduction in the default session.
Never stop, restart, delete, or kill the main Herdr server.
Never use
```
pkill
```
, broad process matching, or guessed PIDs for cleanup.
Create a unique session name. Never reuse or delete an unrelated named session.
Create a new outer pane and close only that pane during cleanup.
Read workspace, tab, pane, terminal, and agent IDs from command output. Never construct them.
Use
```
/var/tmp
```
for reproduction directories and potentially large artifacts.
Do not approve destructive or unnecessary agent actions.
Do not spend paid agent tokens without the user's approval. Use the requested low-cost model and the smallest useful prompts.

绝不在默认会话中运行复现流程。
绝不停止、重启、删除或终止主Herdr服务器。
清理时绝不使用
```
pkill
```
、宽泛的进程匹配或猜测的PID。
创建唯一的会话名称。绝不重复使用或删除无关的命名会话。
创建一个新的外部面板，清理时仅关闭该面板。
从命令输出中读取工作区、标签页、面板、终端和Agent的ID。绝不自行构造这些ID。
使用
```
/var/tmp
```
作为复现目录和可能产生的大型文件存储位置。
不批准具有破坏性或不必要的Agent操作。
未经用户批准，请勿消耗付费Agent令牌。使用请求的低成本模型和最小化的有效提示词。

Learn the installed interface first

先了解已安装的接口

The installed binary is the authority. CLI syntax may have changed since this skill was written.

Confirm the caller is inside Herdr and inspect the relevant help before doing anything:

bash

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

Inspect nested command help before using unfamiliar or potentially mutating commands. Do not run bare

herdr

for discovery because it launches or attaches the TUI.

Record which Herdr binary and version the reproduction tests. If testing a checkout build, follow the repository's instructions for running that build instead of silently substituting the installed binary.

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

在执行任何操作前，确认调用者处于Herdr环境中并查看相关帮助信息：

bash

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

在使用不熟悉或可能产生变更的命令前，查看嵌套命令的帮助信息。请勿直接运行

herdr

命令进行探索，因为它会启动或连接到TUI。

记录复现测试所使用的Herdr二进制文件及其版本。如果测试的是检出构建版本，请遵循仓库中的说明运行该构建版本，而非静默替换已安装的二进制文件。

Create the outer pane

创建外部面板

Create a sibling shell pane in the current tab without moving focus. Use an available Herdr layout tool when the harness provides one. Otherwise use the installed pane split command after checking its help.

Use

/var/tmp

or a dedicated reproduction directory as the new pane's cwd. Save the returned outer pane ID. This is the only parent-session pane that cleanup may close.

在当前标签页中创建一个同级shell面板，不转移焦点。如果测试工具提供了Herdr布局工具，请使用该工具；否则，在查看其帮助信息后使用已安装的面板拆分命令。

将

/var/tmp

或专用复现目录设为新面板的工作目录。保存返回的外部面板ID。这是清理时唯一可以关闭的父会话面板。

Start the disposable session

启动一次性会话

Choose a short unique name such as

repro-<topic>-<timestamp>

Run the named session inside the new outer pane. Clear inherited session selection, socket overrides, and caller IDs so the nested runtime cannot accidentally address the parent session:

bash

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 --session <session-name>

Add reproduction-specific environment variables to this launch command when needed. Environment variables that configure the server must be present before the named server starts.

Do not continue until the named session's API is ready. Confirm readiness by addressing that session from the parent and listing its panes.

选择一个简短的唯一名称，例如

repro-<topic>-<timestamp>

。

在新的外部面板中运行命名会话。清除继承的会话选择、Socket覆盖和调用者ID，确保嵌套运行时不会意外访问父会话：

bash

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 --session <session-name>

必要时，在此启动命令中添加复现特定的环境变量。配置服务器的环境变量必须在命名服务器启动前设置。

在命名会话的API准备就绪前，请勿继续操作。通过从父会话访问该会话并列出其面板来确认就绪状态。

Address only the disposable session

仅访问一次性会话

Every control command issued from the parent must clear inherited socket overrides and explicitly select the temporary session:

bash

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

Repeat this prefix for every command. Do not rely on shell state persisting between tool calls.

Read the disposable root pane ID from

pane list

. Confirm its cwd and foreground process before starting anything in it.

Named sessions isolate runtime state, sockets, panes, and persistence. They still share global Herdr configuration and agent manifest overrides by default. Check configuration provenance when it could affect the reproduction. Do not modify shared configuration merely to make the test pass.

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

bash

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。在其中启动任何操作前，确认其工作目录和前台进程。

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

Drive the reproduction through the API

通过API驱动复现流程

Use pane commands for shells and ordinary processes:

```
pane run
```
to start a command at an available shell prompt.
```
pane wait-output
```
to wait for deterministic output.
```
pane read
```
to capture terminal contents.
```
pane send-text
```
for literal input.
```
pane send-keys
```
for supported keys.
```
pane get
```
,
```
pane process-info
```
, and
```
pane layout
```
for runtime state.

Use agent commands only after Herdr recognizes a coding agent:

```
agent start
```
to launch a supported agent in an existing shell pane.
```
agent prompt
```
to submit one prompt atomically.
```
agent wait
```
to wait for
```
working
```
,
```
blocked
```
,
```
idle
```
,
```
done
```
, or
```
unknown
```
.
```
agent read
```
to capture the agent terminal.
```
agent get
```
and
```
agent explain
```
to inspect state and detection.
```
agent send-keys
```
for interactive responses.

Run the relevant command group's help first because names and options may change.

Prefer waits over arbitrary sleeps. When timing itself is under test, record timestamps and use bounded polling. Capture state before, during, and after the transition being reproduced.

When a needed terminal key is unsupported by the high-level command, send its terminal sequence through the disposable pane only after confirming the target application's expected key. Never send raw control sequences to the parent pane.

使用面板命令来操作shell和普通进程：

```
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面板中启动受支持的Agent。
```
agent prompt
```
：原子性提交一个提示词。
```
agent wait
```
：等待
```
working
```
、
```
blocked
```
、
```
idle
```
、
```
done
```
或
```
unknown
```
状态。
```
agent read
```
：捕获Agent终端内容。
```
agent get
```
和
```
agent explain
```
：检查状态和检测信息。
```
agent send-keys
```
：发送交互式响应。

先查看相关命令组的帮助信息，因为命令名称和选项可能已更改。

优先使用等待操作而非任意睡眠。当测试对象是计时本身时，记录时间戳并使用有限轮询。在复现的状态转换之前、期间和之后捕获状态。

当高级命令不支持所需的终端按键时，在确认目标应用预期的按键后，仅向一次性面板发送其终端序列。绝不要向父面板发送原始控制序列。

Start agents carefully

谨慎启动Agent

Before launching an agent, inspect its installed

--version

and

--help

. Pass native agent arguments after Herdr's argument separator.

Use the exact model requested or approved by the user. Verify the model from the live agent screen instead of trusting an alias. Prefer low effort, safe mode, and manual permissions for a baseline when the agent supports them. Repeat with the user's real configuration only when the suspected behavior depends on hooks, plugins, or settings.

Use harmless operations for permission-state testing. Reject the pending action after evidence is captured and verify that no artifact was created.

在启动Agent前，查看其已安装版本的

--version

和

--help

信息。在Herdr的参数分隔符后传递Agent原生参数。

使用用户请求或批准的精确模型。从Agent实时界面验证模型，而非依赖别名。当Agent支持时，优先使用低消耗、安全模式和手动权限作为基线。仅当疑似行为依赖于钩子、插件或设置时，才使用用户的真实配置重复测试。

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

Collect useful evidence

收集有用的证据

Record enough information for another person to repeat the result:

Herdr binary and version.
Named session and launch environment.
Target application or agent version and arguments.
Exact commands or prompts.
Pane and agent state before and after each transition.
Relevant
```
pane read
```
,
```
agent read
```
,
```
agent explain
```
, API output, and session logs.
Whether global config or a local manifest override was active.

Read the named session directory and socket from

herdr session list

instead of assuming their paths. Keep large evidence under

/var/tmp

unless the user asks to preserve it elsewhere.

Distinguish observed facts from proposed causes. First reproduce stock behavior, then change one variable at a time.

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

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

从

herdr session list

中读取命名会话目录和Socket，而非假设其路径。除非用户要求保存到其他位置，否则将大型证据存储在

/var/tmp

下。

区分观察到的事实与推测的原因。先复现默认行为，再一次更改一个变量。

Cleanup

清理

Cleanup is part of the reproduction, including after failure.

Reject pending prompts and stop test applications cleanly when practical.
Verify that harmless probe files or other test artifacts do not exist, or remove only artifacts created by this reproduction.
Stop the temporary named session with the installed session command.
Delete that same stopped session.
Confirm it no longer appears as running.
Wait for the outer pane to return to its shell.
Close only the outer pane created by this workflow.

Never delete another named session because it looks stale. Never close the pane running the current agent or any pane not created for the reproduction.

清理是复现流程的一部分，即使失败后也需执行。

尽可能优雅地拒绝待处理提示词并停止测试应用。
确认不存在无害的探测文件或其他测试产物，或仅删除本次复现创建的产物。
使用已安装的会话命令停止临时命名会话。
删除已停止的该会话。
确认它不再显示为运行状态。
等待外部面板返回至shell状态。
仅关闭本工作流创建的外部面板。

绝不要删除看似过期的其他命名会话。绝不要关闭运行当前Agent的面板或任何非本次复现创建的面板。

Report the result

报告结果

State what reproduced, what did not, and the exact transition that failed. Include cleanup status. Mention shared configuration or manifest overrides that may have influenced the result.

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