Conductor reference

本页是 Conductor 的紧凑 reference。它定义公开 surface，以及脚本或 LLM 可以依赖的字段。

CLI verbs

Verb	Primary method	Use
ps [--json]	fleet.list	列出所有 workspace 中检测到的 agents
status <target> [--json]	surface.status	读取一个 pane 的 agent state
watch [--surface <sel>] [--type <event>]	events.subscribe	流式输出 lifecycle events 和 surface changes
read <target>	surface.read	读取 pane scrollback
send <target> <text>	surface.send_text	在 pane 中准备或提交 text
wait --match <sel>	surface.read，idle mode 使用 event stream	阻塞直到 idle state、regex 或两者都满足
up <file>	workspace orchestration	创建声明式 agent workspace
flow run <file>	flow orchestration	运行 multi-agent pipeline
ls, search, focus, key	scripting methods	当 conductor state 不够时使用底层 pane automation

读取操作默认允许。send --submit、key 以及会提交文本的 flow step 等写入操作需要 scripting gate 或 AI free access mode。

Selectors

Selector	Example	Notes
Numeric id	paneflow status 42	精确 pane id
Name	paneflow status backend	conductor workflows 的最佳 selector
cmdline:<substr>	paneflow read cmdline:claude	有用，但不如 pane name 可移植
cwd:<path>	paneflow read cwd:/home/me/app	适合 repo-scoped scripts

如果 selector 没有匹配或匹配多个 pane，会以 code 3 退出。明确接受多个匹配的命令除外，例如 broadcast sends、wait --any 和 wait --all。

fleet.list

paneflow ps --json 返回 agents array。

Field	Meaning
pid	agent process id，scan-only detection 时为 null
tool	claude、codex、opencode 或 gemini 等 agent family
state	thinking、waiting_for_input、finished、errored、stalled、idle 或 unknown_running
hooked	Paneflow 收到 lifecycle hook events 时为 true
reason	detection reason，包括未 hooked 进程的 no_hook
surface_id	已解析时的 pane id
surface_name	存在时的 pane name
workspace	workspace index
active_tool_name	agent 内当前运行的 tool，如果被报告
message	等待中的 question 或 permission text，如果被报告
last_result	hook 提供时的 last turn summary
waiting_ms	等待输入的毫秒数
idle_ms	自上次观察到 activity 以来的毫秒数

空 fleet 是 exit code 0 的 {"agents":[]}。

surface.status

paneflow status <target> --json 返回一个 pane status。

Field	Meaning
surface_id	pane id
state	与 fleet.list 相同的 state vocabulary
hooked	lifecycle tracking 是否活跃
tool	检测到时的 agent family
active_tool_name	当前运行的 tool，如果被报告
message	等待中的 question 或 permission text，如果被报告
last_result	可用时的 last turn summary
waiting_ms	等待输入的毫秒数
idle_ms	自上次观察到 activity 以来的毫秒数
output_generation	pane output 改变时递增的 monotonic counter

没有 active agent 的 pane 会返回 idle state，而不是 error。

surface.read

paneflow read <target> 返回 terminal text。默认情况下，输出会被包在 <untrusted_terminal_output> 中，让 LLM 可以检查它，而不会把它当作指令。只有可信的人类脚本才应使用 --raw。

JSON mode 中有用的 fields 包括 text、lines、total_lines、eof 和 output_generation。

events.subscribe 和 watch

paneflow watch 是 newline-delimited JSON。它可能 emit：

Event type	Meaning
ai.session_start	agent session 开始
ai.prompt_submit	prompt 被提交
ai.tool_use	agent 调用 tool
ai.notification	agent 提问或请求 permission
ai.stop	turn 结束
ai.exit	agent process 退出
ai.session_end	session 关闭
surface_changed	pane 的 output_generation 已推进

Control frames 也有效：

Frame	Meaning
subscribed	subscription acknowledged
heartbeat	keepalive frame
dropped	subscriber 落后，events 被丢弃

client 收到 dropped 后，应通过 paneflow ps --json 或 paneflow status <target> --json 重新同步。

wait

wait --idle 在可用时使用 event stream，必要时安全 fallback。wait --pattern 每 500 ms 轮询最近的 scrollback，并扫描最新 500 行。

Mode	Example	Use
Idle	paneflow wait --match reviewer --idle --timeout 600	agent 停止工作后继续
Pattern	paneflow wait --match backend --pattern '^DONE:' --timeout 300	sentinel line 出现后继续
Idle plus pattern	paneflow wait --match reviewer --idle --pattern '^REPORT_DONE' --timeout 600	同时要求稳定 pane 和 marker
Any or all	paneflow wait --match 'cmdline:claude' --pattern 'tests passed' --all	在 pattern mode 下协调多个 panes

Timeout 以 code 4 退出。

Config keys

Key	Default	Meaning
ai_unrestricted	false	启用后允许可信 AI automation submit
ai_injection_fence	true	把 peer terminal output 包装为 untrusted text
agent_stall_threshold_secs	app default	把静默的 in-progress turns 标记为 stalled

Exit codes

Code	Meaning
0	Success
1	Runtime failure
2	CLI usage error
3	Target not found or ambiguous
4	wait timeout

Related pages

• Conductor guide
• Scripting and automation