Pi Subagent

Pi Sub-Agent Infrastructure

在 herdr pane 中用 pi --print 运行 sub-agent。

子 Agent 运行后，完整轨迹（每步工具调用、参数、结果、LLM 输出）自动保存到 /tmp/pi-subagent-<name>-last.jsonl，主 Agent 随时可读取审计。

查看可用模型（唯一事实来源）：

pi --list-models

Pi 参数速查

调用前必须理解每个参数的作用，根据场景选用，不要盲目套模板：

参考调用模板

以下是常见场景的参考命令。在实际调用前，请先确认每个参数是否适合你的场景，按需增删。 所有模板均以 --mode json 运行，将轨迹重定向到文件，从中提取最终文本输出。

场景 A：有预定义 system prompt，完全隔离

适合 figure-qa 等无需外部 skill 的审查 agent。 推荐模型：axonhub/gemini-3.1-pro-preview（视觉理解）

TRAJ=/tmp/pi-subagent-myagent-last.jsonl
pi --print \
  --model axonhub/gemini-3.1-pro-preview \
  --thinking off \
  --tools read,bash \
  --mode json \
  --system-prompt /path/to/agent.prompt.md \
  --no-skills \
  --no-context-files \
  --no-extensions \
  --no-session \
  "your message" > "$TRAJ"
# 从轨迹提取最终文本
python3 -c "
import json,sys
for l in open(sys.argv[1]):
    e=json.loads(l)
    if e.get('type')=='agent_end':
        for c in e['messages'][-1].get('content',[]):
            if c.get('type')=='text': print(c['text'])
" "$TRAJ"

场景 B：需要加载某个 skill

TRAJ=/tmp/pi-subagent-myagent-last.jsonl
pi --print \
  --model axonhub/claude-opus-4-7 \
  --thinking off \
  --tools read,bash \
  --mode json \
  --skill /path/to/skill \
  --no-skills \
  --no-context-files \
  --no-session \
  "your message" > "$TRAJ"

场景 C：快速单次推理，无工具，低成本

TRAJ=/tmp/pi-subagent-myagent-last.jsonl
pi --print \
  --model axonhub/gemini-3-flash-preview \
  --mode json \
  --no-tools \
  --no-skills \
  --no-context-files \
  --no-session \
  "your message" > "$TRAJ"

场景 D：需要深度推理

TRAJ=/tmp/pi-subagent-myagent-last.jsonl
pi --print \
  --model axonhub/gemini-3.1-pro-preview \
  --thinking high \
  --tools read,bash \
  --mode json \
  --no-skills \
  --no-context-files \
  --no-session \
  "your message" > "$TRAJ"

herdr 五步流程

规则：pane_split 时必须传 newPane 起别名。 后续所有 run / wait_agent / read / watch / send / stop 均通过别名引用，不得使用数字 pane id。

Step 1 — 创建 pane 并命名别名

{ "action": "pane_split", "direction": "down", "newPane": "subagent" }

Step 2 — 启动 sub-agent

{
  "action": "run",
  "pane": "subagent",
  "command": "<根据上方模板构造的 pi --print 命令，重定向到 /tmp/pi-subagent-<name>-last.jsonl>"
}

Step 3 — 等待完成

{ "action": "wait_agent", "pane": "subagent", "statuses": ["done", "idle"], "timeout": 120000 }

为什么用 wait_agent 而不用 watch？ herdr 能感知 pane 内 pi 进程的 agent 状态（idle / done），无需匹配文本。 watch 依赖输出中出现特定字符串才能触发，而 pi --print 运行期间的输出无规律、内容不可预知，匹配往往不能触发导致超时。 监控 pi sub-agent 完成状态永远使用 wait_agent，禁用 watch。

Step 4 — 读取最终文本（从轨迹文件提取）

{
  "action": "run",
  "pane": "subagent",
  "command": "python3 -c \"import json,sys\nfor l in open(sys.argv[1]):\n    e=json.loads(l)\n    if e.get('type')=='agent_end':\n        for c in e['messages'][-1].get('content',[]):\n            if c.get('type')=='text': print(c['text'])\n\" /tmp/pi-subagent-<name>-last.jsonl"
}

Step 5 — 读取完整轨迹（主 Agent 审计）

用 read 工具直接读取轨迹文件：

/tmp/pi-subagent-<name>-last.jsonl

或用 jq 过滤所需事件：

# 工具调用序列
jq -c 'select(.type=="tool_execution_start") | {tool:.toolName, args:.args}' /tmp/pi-subagent-<name>-last.jsonl

# 工具报错
jq -c 'select(.type=="tool_execution_end" and .isError==true)' /tmp/pi-subagent-<name>-last.jsonl

# turn 数
jq 'select(.type=="turn_end")' /tmp/pi-subagent-<name>-last.jsonl | wc -l

invoke.sh（便捷调用器）

scripts/invoke.sh 封装了上述流程：读取 agents/<name>.md frontmatter，自动组装 --mode json 命令， 将轨迹写入 /tmp/pi-subagent-<name>-last.jsonl，同时将最终文本打印到 stdout。

invoke.sh --agent <name> [--model <model_string>] --msg '<message>' [-- <extra_pi_flags>]

# 示例
invoke.sh --agent figure-qa \
  --msg $'Check image at /tmp/fig.png\nScene: academic\nIntent: pipeline diagram'

# 完成后轨迹已在 /tmp/pi-subagent-figure-qa-last.jsonl，主 Agent 直接 read 即可

-- 之后的参数透传给 pi（如 -- --thinking medium）。

Agent 定义格式

agents/<name>.md — frontmatter（默认参数）+ 调用文档：

---
name: <agent-name>
description: 一句话说明
model: axonhub/gemini-3.1-pro-preview   # pi --list-models 中的完整字符串
thinking: off                            # off / minimal / low / medium / high / xhigh
tools: read,bash
---

# 调用方式 / 输入格式 / 输出格式 / 结果处理

agents/<name>.prompt.md — 纯 system prompt 正文，无 frontmatter。

Agent 目录

文件清单

常见问题