agent-shell

Agent Shell

为 Agent 会话提供后台 Shell 执行。对于耗时较长的命令，无需让当前轮次一直保持打开；使用 agent-shell run 启动命令，然后结束回复即可。命令会在分离的监督进程下持续运行；运行期间，你的会话每 2 分钟会收到一轮进度通知，其中包含最后一行输出；命令完成时，会收到一轮完成通知，其中会指出任务名称和退出状态。你可以使用 agent-shell show 查看输出。muse 成员始终使用 muse --yolo 运行，因此不会请求审批。

全文使用以下术语：

• 任务是一个后台命令。其 id（例如 sh-1234-5678）是唯一可靠的标识方式；其 name（例如 build）是便于人识别的简短标签。
• 进度轮次是任务运行期间，你的会话每 2 分钟收到的消息：shell job '<name>' still running (<elapsed> elapsed). Last line: ...。它会告知你 Shell 是卡住了还是仍在工作；无需采取任何操作。
• 完成轮次是任务结束时，你的会话收到的唯一一条消息：shell job '<name>' done (exit <code>, <time>). Read with: agent-shell show <id>。其中不会包含完整输出。

所有操作都通过 agent-shell 命令执行，这是 PATH 上的一个全局二进制文件。首次调用前，请运行 agent-shell --version。如果失败，请停止并告知用户未安装 agent-shell CLI：运行 curl -fsSL https://raw.githubusercontent.com/bdsanxz/agent-shell/main/install.sh | sh 可将其安装到 ~/.local/bin/agent-shell，且需要在 PATH 上安装 Bun。不要自行安装。然后运行 agent-shell --help，以及所需命令对应的 agent-shell <command> --help，以了解其参数、默认值、输出和退出代码；运行帮助不会执行其他操作。

操作规则（必须遵守）

1. 将任务与等待分开。 在 run 行中写明完整命令、执行目录和预期输出。任务不会承担持续职责；完成轮次只会说明任务已结束。
2. 绝不通过休眠或轮询等待。 启动任务后，正常结束回复即可。进度和完成通知会作为普通轮次送达；任务仍在运行并不代表失败。不要调用 sleep，不要循环执行 agent-shell list 或 agent-shell show，也不要阻塞 Shell。
3. 启动后即不再干预。 run 会立即返回任务 id，且不会阻塞。不要传入 --wait 之类的选项，也不要在任务运行期间持续查看日志。
4. 收到完成通知后读取一次。 进度轮次无需处理：它只会显示最后一行输出。完成轮次指出任务后，使用 agent-shell show <id> 读取输出。之后不要再次读取，除非你基于该任务启动了新工作。

步骤 1：确认你的身份

打印调用方上下文并查找通知目标：

printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"

你的通知目标是你的 pane ID（$HERDR_PANE_ID），如果你在旧版 herdr 之外运行，则为 herdr-core 终端（$HC_TERMINAL_ID）。run 默认使用该目标，因此通知轮次会通过 herdr agent prompt（或 hc send）送达此会话。如果用户指定了另一位成员接收通知（herdr Agent 名称、pane ID 或 hc 终端），则使用 --notify <target> 传入。如果你不属于上述任何一种情况（既没有 HERDR_PANE_ID，也没有 HC_TERMINAL_ID），任务仍会运行，但会跳过通知；请说明这一点，并明确读取任务结果。

第 2 步：启动任务

agent-shell run --name build -- bun test
agent-shell run --notify framesmith-lead --cwd /path/to/dir -- sh -c 'sleep 30; echo done'
agent-shell run --name e2e --heartbeat 5m -- sh -c './scripts/e2e.sh'
agent-shell run --name quick --no-heartbeat -- sh -c './scripts/fast.sh'

命令是 -- 后的所有内容；需要使用 Shell 功能（管道、重定向、&&）时，请使用 sh -c '...'。为 --name 设置简短的 kebab-case 名称（build、test-e2e），如果命令必须在其他位置运行，则设置 --cwd。默认情况下，每个任务每 2 分钟发送一次进度轮次，并附上最后一行输出，让你判断任务是卡住了还是仍在运行；--heartbeat <duration>（最短为 1s，例如 30s、5m）可更改间隔，--no-heartbeat 则会禁用进度轮次，只保留完成轮次。输出会显示任务 ID、通知目标、心跳设置和读取命令。对于快速命令，可传入 --wait <duration>（例如 5s），等待命令完成，并直接显示其输出和退出状态，而不是结束当前轮次。然后结束当前轮次。

第 3 步：读取结果

任务运行期间，每 2 分钟会收到一次进度轮次，无需采取任何操作：最后一行有更新表示任务仍在运行，最后一行未变化则表示任务可能卡住了。完成轮次会自动到达。使用结果前，先验证一次任务：

agent-shell check <id>
agent-shell show <id>

check 会为每个项目显示一行 ok/FAIL 状态，包括是否已完成、是否记录了退出代码、输出是否可读以及通知是否已送达，另外还会显示 check <id>: 4/4 pass 汇总。只有四项全部通过时，退出代码才为 0。被终止的任务无法通过检查（输出不完整，且没有通知）；仍在运行的任务退出代码为 2。检查通过后，使用 show（状态、退出代码、通知详情、输出末尾）或 tail 读取输出。在下一轮中根据结果采取行动：报告失败、修复问题，或继续执行需要该结果的工作。

第 4 步：管理任务

agent-shell list             # running first, then newest done
agent-shell kill <id>        # stop a running job; a killed job gets no notify
agent-shell clean            # remove finished jobs
agent-shell clean --older-than 7d

被终止的任务仍可读取其部分输出，且不会收到完成通知。show 会显示心跳设置（heartbeat 120000ms 或 heartbeat off），以及已发送进度轮次后的进度计数。clean 不会处理仍在运行的任务。