跳到内容
PaneflowPaneflow

脚本参考

Paneflow 自动化的 CLI verb、selector、JSON-RPC method、event frame、config key、workspace spec、flow spec、MCP tool、hook 和退出码。

这是 脚本与自动化 的紧凑参考。它命名了人类脚本或 LLM 可以精确引用的公共接口。

CLI verb

paneflow 二进制会拦截这些 verb,并在 GUI 启动前退出。未知 verb 会以 usage code 2 退出,而不是静默启动 app。

Verb主要 method 或 engine是否写入面板用途
ls [--human]surface.list否列出活动工作区中的面板
read <target>surface.read否读取面板 scrollback
search <target> <pattern>surface.search否搜索面板 scrollback
ps [--json]fleet.list否列出跨工作区检测到的智能体
status <target> [--json]surface.status否读取单个面板的智能体状态
new [--name] [--cwd] [--space]workspace.create否创建工作区,除非 --space 指定了其他空间,否则在活动空间中创建
select <index>workspace.select否选择工作区,并切换到其所在空间
split <h|v>surface.split否分割面板
focus <target>surface.focus否聚焦面板及其工作区
send <target> <text>surface.send_textgated预填或提交文本
key <target> <keystroke>surface.send_keystrokegated发送一个不会提交的按键
wait --match <sel>surface.read, events.subscribe否阻塞到 pattern、idle 或两者都满足
watch [--surface <sel>] [--type <event>]events.subscribe否流式输出生命周期和 surface 事件
up <file>Workspace spec engine仅预填创建声明式工作区
flow run <file>Flow engine提交 step 需要 gate运行本地多智能体 DAG
sessions [--json] [--follow]worker 会话流否读取智能体会话状态,有无窗口均可

CLI 接受的 alias:list_panes 映射到 ls,read_pane 映射到 read,search_pane 映射到 search。

Selector

Selector示例说明
Numeric idpaneflow read 42精确匹配 surface_id
Namepaneflow status backend持久脚本的最佳 selector
cmdline:<substr>paneflow read cmdline:viteLinux 上是完整 foreground argv,macOS 和 Windows 上是 executable basename
cwd:<path>paneflow read cwd:/home/me/api匹配面板工作目录

如果 selector 不匹配任何面板,或匹配多个面板,会以 code 3 退出。但显式接受多匹配的 command 例外,例如 send --broadcast、 wait --any 和 wait --all。

退出码

Code含义
0成功
1Runtime failure:实例不可达、面板关闭、gate 拒绝或 handler error
2CLI usage error
3target not found 或 ambiguous,或 send 拒绝了正在等待决定或已离开前台的目标智能体
4wait timeout 或 flow ready timeout

写入 gate

读取默认允许。写入按 capability 区分:

OperationGate
send without --submitPANEFLOW_IPC_SCRIPTING=1 或 ai_unrestricted
send --submitPANEFLOW_IPC_SCRIPTING=1 或 ai_unrestricted
keyPANEFLOW_IPC_SCRIPTING=1
从面板内执行 send --scope all、key --scope all、flow run --scope allPANEFLOW_IPC_ORCHESTRATION=1
控制客户端发起的 host session.inputPANEFLOW_IPC_SCRIPTING=1
控制客户端发起、带命令、prompt 或 env 的 host session.createPANEFLOW_IPC_ORCHESTRATION=1
控制客户端发起的其他 host session.createPANEFLOW_IPC_SCRIPTING=1
Flow step with submit = truesystem.capabilities 报告的 scripting capability

除非存在 --submit,否则 send 不会附加 carriage return。key 会拒绝 enter、ctrl-m 和 ctrl-j 等提交型按键。单个 surface.send_text payload 上限为 64 KiB。

相关 config key:

KeyDefault含义
ai_unrestrictedfalse允许受信任的 AI 自动化在没有 env gate 的情况下提交文本
ai_injection_fencetrue将 surface.read 文本包裹在不可信终端 envelope 中
submit_paste_delay_ms70bracketed paste 与提交 carriage return 之间的基础延迟
terminal.envnone注入到新终端的环境变量

读取字段

paneflow read <target> --json 和原始 surface.read 返回:

Field含义
textscrollback 文本,默认 fenced
lines返回的行数
total_lines保留的总行数
eof是否读到了保留缓冲区中最旧的行
output_generation随面板输出前进的 monotonic counter

默认值和限制:lines 默认 200,并被 clamp 到 1-4000。offset 从 buffer 末尾开始计算。超出范围的 offset 是 invalid-params error。

JSON-RPC param fenced 默认使用 ai_injection_fence。CLI flag --raw 会传入 fenced: false。

智能体状态字段

paneflow ps --json 返回 {"agents":[...]}。paneflow status <target> --json 返回一个 status object。

Field含义
pid智能体 process id,已知时存在
tool智能体家族,例如 claude、codex、opencode 或 gemini
statethinking、waiting_for_input、finished、errored、stalled、idle 或 unknown_running
hooked当前启动是否通过 Paneflow 安装的 lifecycle hook 报告;之前启动的 hook 永远不算
state_seq每次状态转换时递增的每会话 counter,在 status 上
reason检测原因,包括 no_hook
surface_id面板 id
surface_name面板名称
workspace工作区 index
active_tool_name智能体内部当前运行的 tool
message等待中的 prompt 或 permission text
last_result可用时的 last turn summary
waiting_ms等待输入的时间
idle_ms距离观测到的上次 activity 的时间
output_generationstatus 上的面板输出 counter;未知时缺省

空 fleet 会以 exit code 0 返回 {"agents":[]}。没有 tracked agent 的面板返回 idle state,而不是 error。

Workspace spec

paneflow up <file> 读取 TOML workspace spec。

Top-level fieldTypeDefaultNotes
namestring"Workspace"工作区标题
spacestring活动空间空间名称(不区分大小写)或 id;Default 表示默认空间
layoutstring"even_h"even_h、even_v、main_vertical 或 tiled
port_baseinteger3000${port_offset} allocation 的 base
[[panes]]arrayrequired每个面板一个 entry
Pane fieldTypeDefaultNotes
cwdstringnoneexpansion 和 canonicalization 后必须存在
agentstringnone智能体 launcher name,与 command 互斥
commandstringnone原始 command,与 agent 互斥
promptstringnone预填到智能体输入中,up 永不提交
focusboolfalse给此面板初始焦点
envtablenone合并在 terminal.env 之上;支持 ${port_offset}
namestringnone稳定 selector name
worktreestringnoneworktrees.dir 根目录下 managed worktree 的 branch name(见配置 schema)
fromstringHEADup 创建 worktree 时其 branch 的起点 branch 或 commit
copy_envbooltrue将仓库 .worktreeinclude 中的条目复制进 worktree;没有该文件时复制顶层 .env* 和 AGENTS.override.md
setupstringnonelaunch 前运行的 command
setup_timeout_secsinteger300setup timeout
worktree_teardownstring"auto"auto 在关闭时移除干净 worktree;keep 保留

${port_offset} 只在 env value 中替换。未知 key 是 error。创建工作区会先验证 path,再创建面板。

Flow spec

paneflow flow run <file> 读取 TOML flow spec,并在当前 Paneflow 实例上运行。

FieldTypeNotes
idstring必需且唯一的 step id
needsarraydependency;在 foreach 上等待所有 instance
foreacharrayfan-out,每个 item 一个 instance
paneinline table使用 workspace pane field 创建面板
sendinline table{ target, text, submit? };需要 dependency
readytable{ pattern, timeout_secs? };regex barrier
capturetable{ var, lines };在 ready 后捕获 1-500 行
submitbool提交 spawned pane prompt;需要 scripting access

Variables:

VariableScope
${item}foreach step:cwd、name、worktree、env、send.target、ready.pattern、prompt 和 text
${var}send.text 和 submitting pane.prompt 中的 captured value
${var.<item>}来自 foreach group 的 capture

runner 会在执行前验证 unknown key、missing dependency、dependency cycle、invalid regex、undefined capture、pane budget 和 missing timeout。Ctrl-C 会停止 orchestration loop;已创建的面板会保留在 Paneflow 中。

JSON-RPC 连接

PropertyValue
Linux endpoint$XDG_RUNTIME_DIR/paneflow/paneflow.sock;若 XDG_RUNTIME_DIR 未设置或不是可写目录,则使用 $TMPDIR,否则使用 ~/.cache/run
macOS endpoint$TMPDIR/paneflow/paneflow.sock,否则使用 ~/Library/Caches/run;忽略 XDG_RUNTIME_DIR
Windows endpoint\\.\pipe\paneflow
FramingNewline-delimited JSON-RPC 2.0
Request model除 events.subscribe 外,每个连接一个 request
Local trust仅同一用户;无网络 listener、无 token、无 TLS
Backpressure连接上限和 bounded event queue 会返回 structured error 或 dropped frame

运行时探测 capability:

bash
printf '%s\n' '{"jsonrpc":"2.0","method":"system.capabilities","params":{},"id":1}' \
| nc -U "$PANEFLOW_SOCKET_PATH"

JSON-RPC method

MethodParamsReturns or notes
system.ping-liveness check
system.capabilities-{scripting, methods[]}
system.identify-{name, version, protocol}
workspace.list-带全局 index、title,以及 space: {id, name}(默认空间为 null)的工作区
workspace.current-当前显示的工作区,含其 space
workspace.createname?, cwd?, layout?, space?创建工作区;space 为名称(不区分大小写)或 id,缺省时为活动空间;未知空间会被拒绝,并返回 unknown space: <value>
workspace.selectindex切换工作区;如果其空间处于隐藏状态,也会切换到该空间
workspace.closeindex关闭工作区
workspace.upname, layout, panes[], space?up 和 flow root 使用的声明式 spawn;space 与 workspace.create 相同
workspace.restore_layoutlayout应用 layout tree
surface.list-{surfaces:[{surface_id,name,title,cwd,cmd,workspace,space}]}
surface.readsurface_id, lines?, offset?, fenced?scrollback 和 output_generation
surface.searchsurface_id, pattern, max_matches?case-insensitive substring match
surface.renamesurface_id, name重命名或清空面板 name
surface.focussurface_id聚焦面板和工作区
surface.statussurface_id单个面板的智能体状态
surface.send_textsurface_id, text, submit?, paste?gated PTY text write
surface.send_keystrokesurface_id, keystrokeenv-gated non-submitting keystroke
surface.splitdirection, surface_id?, cwd?, command?, prompt?, env?, name?, managed_worktree?分割面板
tmux.compatteam, surface_id, argv, scope_session?来自 Claude Code team 面板的 tmux 命令;team 是 Paneflow 发给该 team 面板的 token,回复为 {stdout, stderr, exit}
fleet.list-read-only fleet snapshot
events.subscribesurfaces?, types?persistent newline-delimited event stream

app socket 不再接受 ai.* lifecycle method;生命周期事件来自 paneflow-ai-hook reporter,events.subscribe 仍会推送 ai.* event。

结构化失败使用 JSON-RPC error envelope:-32602 invalid params、 -32601 gated method、-32001 permission 和 -32000 backpressure。部分 legacy validation error 仍会以 result 内的 {"error":"..."} 形式返回;client 应将两种形态都视为 failure。

Event

paneflow watch 和原始 events.subscribe 会发出 newline-delimited JSON。第一帧确认 subscription。

Event type含义
subscribedsubscription acknowledged
ai.session_start智能体 session starts
ai.prompt_submitprompt is submitted
ai.tool_use智能体 reports tool use
ai.notification智能体 asks for input or permission
ai.stop智能体 turn stops
ai.exit智能体 process exits
ai.session_end智能体 session closes
surface_changed面板 output_generation advanced
heartbeatidle keepalive
droppedsubscriber lagged and events were shed

收到 dropped frame 后,用 paneflow ps --json 或 paneflow status <target> --json 重新同步。

MCP 桥接

paneflow-mcp 是基于同一个 Paneflow socket 的 stdio MCP server。

ToolParamsReturns
list_panes-带有 surface_id、name、title、cwd、cmd、workspace 的面板
read_panetarget, lines?, offset?scrollback text
search_panetarget, pattern, max_matches?matching lines
write_panetarget, text, submit?人工允许该组合前返回 approval_pending,之后返回投递结果;带 submit 时还包括 started 和 state

write_pane 是唯一会写入的 tool,并且只在人工于 Paneflow 中允许这一对智能体会话之后写入;其控制细节见自动化指南。没有用于发送按键、聚焦或分割面板的 tool。返回的终端输出会被 fenced 为不可信数据。

生命周期 hook

paneflow-ai-hook 从 stdin 读取 event JSON,向本地 host 发送一个生命周期事件(ai.stop、ai.notification 等),然后以 0 退出,这样停止的 Paneflow 实例不会破坏智能体。hooks 把智能体的身份和会话元数据传给 ps、status、 watch 和 paneflow sessions;turn 状态来自 OSC 7501。

命令作用
paneflow integrations list列出带安装器的 runtime 及其状态
paneflow integrations install <runtime>为 claude-code(或 claude)或 codex 安装 hooks,并注册 paneflow MCP server
paneflow integrations remove <runtime>只移除 Paneflow 自己的 handler;同一 hook group 中你自己的 handler 会保留
paneflow hooks setup安装所有检测到且带安装器的 runtime
paneflow hooks uninstall移除这些 integration 和 paneflow MCP 条目
paneflow hooks status每个 runtime 输出一行 <runtime>: <state>;始终以 0 退出

hooks 每台机器安装一次,可通过 CLI 或 Settings > Agents。Claude Code 的 hooks 写入 $CLAUDE_CONFIG_DIR/settings.json(默认 ~/.claude/settings.json), Codex 的 hooks 写入 $CODEX_HOME/hooks.json(默认 ~/.codex/hooks.json),在 Paneflow 面板之外会立即退出。其他智能体没有安装器:仍然可以运行,并通过进程被检测到,但只有通过 OSC 7501 报告时才会有 turn 状态。

Worker 与会话

智能体状态由每个 home 一个的 worker 保存,以 paneflow serve run 启动。它以分离方式运行,每个 PANEFLOW_HOME 一个,把每个会话通过 OSC 7501 声明的状态归约为一个状态,重启时从磁盘重建该状态,并且从不触碰正在运行的 shell。无论是否打开窗口, status、send --submit 和 wait --idle 都会从 worker 读取归约状态; paneflow sessions 会直接读取 worker。

命令作用
paneflow serve start为当前 PANEFLOW_HOME 启动 worker,或接管已在服务的 worker
paneflow serve status输出 pid、protocol、home、会话数和 capabilities
paneflow serve stop [--drain-ms 5000]停止 worker;终端不受影响
paneflow sessions [--json] [--follow]输出侧边栏显示的会话列表;--follow 每次状态变化输出一行,并在 worker 重启后自动重连
paneflow sessions ack <session-id>...清除已完成回合设置的 unread 标记

相关