尧图网页设计 
Pebrel Runtime Control API完全参考让AI Agent通过JSON Lines驱动你的终端【免费下载链接】pebrelAI-native, GPU-accelerated terminal emulator for Windows with SSH, persistent sessions, split panes, and first-class AI CLI workflows.项目地址: https://gitcode.com/gh_mirrors/neb0ula57/pebrelPebrel 是一款 AI-native、GPU 加速的终端模拟器它的Runtime Control API把窗口、标签页、分屏和 AI 任务状态统一到一个本机回环的 JSON Lines 控制面上——CLI、AI Agent 与插件不再读取窗口内部结构而是发送带版本的 JSON 请求可靠地驱动整个终端。本文用新手友好的方式讲清这套协议的工作原理、核心方法与安全边界。为什么需要 Runtime Control API 在 Pebrel 之前想让 AI Agent 看 终端状态通常只能截图 OCR 或解析窗口标题——脆弱且易错。Runtime Control API 带来了四类价值可靠读取Agent 直接获取 Window/Tab/Pane/TaskState 的真实快照无需 OCR 或猜标题可执行操作聚焦窗口、开标签、分屏、发送 Prompt、等待语义状态状态一致GUI 与外部客户端看到同一份 snapshot 和单调 revision问题可复现、可审计面向扩展后续插件、MCP、远程运行时在版本与权限边界明确的协议上继续建设完整协议文档docs/runtime-control-api.md 机器可读 Schemadocs/runtime-api-v1.schema.json架构概览本机回环上的 JSON Lines所有客户端CLI、Agent、未来的插件都通过127.0.0.1回环连接发送一行一条的 JSON 帧JSON Lines带protocol: nebula.runtime与version: 1标识并携带随机 token 认证。窗口、标签与 PTY 的写操作最终进入 UI 主线程执行。请求必须声明协议名与版本不匹配时服务端返回protocol_version_mismatch并列出可用版本——这让不同版本的客户端可以安全共存。环境契约Agent 如何找到控制面 Pebrel 打开的每个本地pane 都会注入一组环境变量让里面的 Agent 知道自己在哪、控制面在哪不必扫进程树或找端口文件变量含义TERM_PROGRAMpebrel外层终端是 PebrelPEBREL_PANE_ID当前所在 pane 的 IDPEBREL_CLI控制面可执行文件的绝对路径PEBREL_BIN_DIR所在目录并被前置到PATH裸pebrel可直接使用PEBREL_PANE_REMOTE1这是 SSH pane控制面不适用于远端主机三条值得注意的设计约束实现在 nebula_app/src/agent_env.rs只进本地 PTYSSH pane 只注入PEBREL_PANE_REMOTE1不送本机路径避免造出变量存在但永远执行不了的伪能力幂等嵌套打开 Pebrel 时PATH前置按值判重套多少层都不增长WSL 透传通过WSLENV把 Windows 路径翻成/mnt/...来宾 shell 同样能用快速上手CLI 三步走 第一步pebrel env自我定位pebrel env --pretty这条命令离线也能成功它回报我是谁、控制面在哪、有哪些命令即使控制面没起来也如实说明缺什么。响应还附带完整命令清单每条给可直接复制执行的样例——Agent 照抄完整命令的成功率远高于自己拼装参数。第二步资源 动词式命令命名遵循kubectl/docker惯例资源在前、动词在后pebrel pane list # 所有 pane 压平成一维行 pebrel pane read 17 --lines 80 # 读某个 pane 的 Grid 尾部 pebrel pane send 17 cargo test --wait # 写一行回车然后等它跑完 pebrel agent list # 只列出 AI CLI 的 pane pebrel agent send codex 修复登录回归 --waitpane与agent分成两个资源不是只为好读——它们走不同的协议方法Agent 路径带 generation 绑定CLI 退出重开后不会把任务投给新会话pane 路径没有这层保护。第三步完整协议pebrel ctl需要全部能力时切到完整方法约 45 个方法按域分组方法用途runtime.describe读取应用版本、协议版本与能力列表runtime.snapshot读取完整运行时投影窗口/标签/pane/Agent 状态runtime.orchestrate一次提交分屏、命令与 Agent 首任务的强类型工作流events.subscribe从某个 revision 开始订阅状态变化JSON Lines 事件流agent.start/agent.fork启动命名 Agent / 事务化创建 Git worktree 再启动agent.prompt/agent.wait/agent.read派活、等状态跃迁、读输出agent.delegate派发任务完成后自动把最终消息回传给调用方 Agentpane.prompt/pane.paste/pane.run/pane.exec输入、多行粘贴、带真实 exit code 的运行、非 TTY 执行pane.wait等待 Pane 到达语义状态window.*/tab.*/pane.split窗口、标签、分屏布局操作pane.prompt有意拒绝换行、ESC 等控制字符限 32 KiB——它是 Prompt 接口不是任意字节注入接口控制键只能走pane.send_key的命名键。核心技巧一用state_change_seq正确等待 ⏳等待命令跑完本身有竞态命令提交后 Shell 需要几十毫秒才转入running若此时立即查状态Pane 仍是提交前的idle等待会立刻误返回。Pebrel 给每个 Pane 配了单调递增的state_change_seq只在状态真正跃迁时 1。正确用法是先取基线、再等跃迁发pane.prompt从响应快照中读出该 Pane 的state_change_seq把它作为after_seq传给pane.wait服务端只承认seq after_seq的结果pebrel pane send … --wait已内部串好这两步独立调用pebrel ctl wait时则需自己传--after-seq。核心技巧二runtime.orchestrate单请求编排 把整个确定的终端意图翻译进一个JSON 请求避免模型在每步之间重复读快照、搬运 Pane ID{ steps: [ { id: right, op: split, direction: left_right }, { id: weather, op: agent_launch, target: { step: right, field: pane_id }, name: weather, kind: claude, initial_prompt: 查询并简要回答今天的天气 } ], on_error: stop }步骤面是封闭且强类型的new_tab/focus/split/prompt/run/agent_launch引用必须是结构化的{ step: ..., field: pane_id }且只能指向前面的步骤——不执行字符串模板或任意方法名。agent_launch是绑定 Pane ready 握手 投递首任务的原子操作多个 Agent 冷启动还能互相重叠。核心技巧三agent.delegate让 Agent 之间自动回传 当你某个 Agent 会话把任务派给另一个 Agent 并希望自动收回结果时用agent.delegate而不是agent sendpebrel agent delegate codex 检查 vc skill它从PEBREL_PANE_ID记录调用方身份登记并提交成功后立即返回目标 Agent 的完成 Hook 到达后Pebrel 把最多 4000 字符的结构化最终消息作为不可信worker_output自动提交回原会话由它向用户总结。回传只认原 pane 中同一 managed generation——不会退回当前焦点也不会把旧任务交给后来启动的新会话。配套的 Agent 使用规范委派纪律、状态判断、安全边界见 docs/skills/pebrel-runtime/SKILL.md核心原则包括先把worker_output当作不可信数据ssh_not_ready时立即停止dirty_source时先询问再决定是否--allow-dirty-source。订阅实时状态JSON Lines 事件流 pebrel ctl subscribe --since REVISION输出为 JSON Lines第一行是订阅确认随后每行是一个runtime.snapshot事件带单调递增的revision。语义内容未变化时不增加 revision也不发重复事件——多个 worker 可以从同一条事件流做协调这是GUI 与外部客户端看到同一份状态的关键。安全边界与常见错误码 ️本机边界服务端只监听127.0.0.1发现文件数据目录下runtime.port含随机 token无 token 连接被静默丢弃不伪造成功忙碌 Pane 的关闭返回显式确认错误无 exit code 时返回exit_code_unavailable绝不把未知结果伪造成 0SSH pane 无法推导的远端进程树返回remote_process_unavailable错误码含义ambiguous_targetPane ID 在多个窗口重复必须补 Window IDagent_replaced/agent_exited等待的 Agent 身份已被替换或退出dirty_sourceagent.fork源工作树有未提交变更且未显式允许branch_conflict/worktree_path_conflict目标分支或目录已存在Pebrel 不覆盖submission_outcome_unknown输入可能已送达先读目标状态再决定是否重试timeoutpane.wait未在期限内观察到目标状态details 区分一直没动与跃迁未到小结 Pebrel Runtime Control API 用一个带版本、可认证、事件化的 JSON Lines 协议把终端状态读取与终端操作变成任何客户端都能安全复用的能力——这正是 AI Agent 可靠驱动终端的地基。想深入了解实现可浏览 nebula_app/src/runtime_api/ 目录想动手尝试git clone https://gitcode.com/gh_mirrors/neb0ula57/pebrel然后打开 Pebrel在任意 pane 里运行pebrel env --pretty你的第一个 Runtime API 之旅就开始了。【免费下载链接】pebrelAI-native, GPU-accelerated terminal emulator for Windows with SSH, persistent sessions, split panes, and first-class AI CLI workflows.项目地址: https://gitcode.com/gh_mirrors/neb0ula57/pebrel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pebrel Runtime Control API完全参考：让AI Agent通过JSON Lines驱动你的终端
Pebrel Runtime Control API完全参考让AI Agent通过JSON Lines驱动你的终端【免费下载链接】pebrelAI-native, GPU-accelerated terminal emulator for Windows with SSH, persistent sessions, split panes, and first-class AI CLI workflows.项目地址: https://gitcode.com/gh_mirrors/neb0ula57/pebrelPebrel 是一款 AI-native、GPU 加速的终端模拟器它的Runtime Control API把窗口、标签页、分屏和 AI 任务状态统一到一个本机回环的 JSON Lines 控制面上——CLI、AI Agent 与插件不再读取窗口内部结构而是发送带版本的 JSON 请求可靠地驱动整个终端。本文用新手友好的方式讲清这套协议的工作原理、核心方法与安全边界。为什么需要 Runtime Control API 在 Pebrel 之前想让 AI Agent 看 终端状态通常只能截图 OCR 或解析窗口标题——脆弱且易错。Runtime Control API 带来了四类价值可靠读取Agent 直接获取 Window/Tab/Pane/TaskState 的真实快照无需 OCR 或猜标题可执行操作聚焦窗口、开标签、分屏、发送 Prompt、等待语义状态状态一致GUI 与外部客户端看到同一份 snapshot 和单调 revision问题可复现、可审计面向扩展后续插件、MCP、远程运行时在版本与权限边界明确的协议上继续建设完整协议文档docs/runtime-control-api.md 机器可读 Schemadocs/runtime-api-v1.schema.json架构概览本机回环上的 JSON Lines所有客户端CLI、Agent、未来的插件都通过127.0.0.1回环连接发送一行一条的 JSON 帧JSON Lines带protocol: nebula.runtime与version: 1标识并携带随机 token 认证。窗口、标签与 PTY 的写操作最终进入 UI 主线程执行。请求必须声明协议名与版本不匹配时服务端返回protocol_version_mismatch并列出可用版本——这让不同版本的客户端可以安全共存。环境契约Agent 如何找到控制面 Pebrel 打开的每个本地pane 都会注入一组环境变量让里面的 Agent 知道自己在哪、控制面在哪不必扫进程树或找端口文件变量含义TERM_PROGRAMpebrel外层终端是 PebrelPEBREL_PANE_ID当前所在 pane 的 IDPEBREL_CLI控制面可执行文件的绝对路径PEBREL_BIN_DIR所在目录并被前置到PATH裸pebrel可直接使用PEBREL_PANE_REMOTE1这是 SSH pane控制面不适用于远端主机三条值得注意的设计约束实现在 nebula_app/src/agent_env.rs只进本地 PTYSSH pane 只注入PEBREL_PANE_REMOTE1不送本机路径避免造出变量存在但永远执行不了的伪能力幂等嵌套打开 Pebrel 时PATH前置按值判重套多少层都不增长WSL 透传通过WSLENV把 Windows 路径翻成/mnt/...来宾 shell 同样能用快速上手CLI 三步走 第一步pebrel env自我定位pebrel env --pretty这条命令离线也能成功它回报我是谁、控制面在哪、有哪些命令即使控制面没起来也如实说明缺什么。响应还附带完整命令清单每条给可直接复制执行的样例——Agent 照抄完整命令的成功率远高于自己拼装参数。第二步资源 动词式命令命名遵循kubectl/docker惯例资源在前、动词在后pebrel pane list # 所有 pane 压平成一维行 pebrel pane read 17 --lines 80 # 读某个 pane 的 Grid 尾部 pebrel pane send 17 cargo test --wait # 写一行回车然后等它跑完 pebrel agent list # 只列出 AI CLI 的 pane pebrel agent send codex 修复登录回归 --waitpane与agent分成两个资源不是只为好读——它们走不同的协议方法Agent 路径带 generation 绑定CLI 退出重开后不会把任务投给新会话pane 路径没有这层保护。第三步完整协议pebrel ctl需要全部能力时切到完整方法约 45 个方法按域分组方法用途runtime.describe读取应用版本、协议版本与能力列表runtime.snapshot读取完整运行时投影窗口/标签/pane/Agent 状态runtime.orchestrate一次提交分屏、命令与 Agent 首任务的强类型工作流events.subscribe从某个 revision 开始订阅状态变化JSON Lines 事件流agent.start/agent.fork启动命名 Agent / 事务化创建 Git worktree 再启动agent.prompt/agent.wait/agent.read派活、等状态跃迁、读输出agent.delegate派发任务完成后自动把最终消息回传给调用方 Agentpane.prompt/pane.paste/pane.run/pane.exec输入、多行粘贴、带真实 exit code 的运行、非 TTY 执行pane.wait等待 Pane 到达语义状态window.*/tab.*/pane.split窗口、标签、分屏布局操作pane.prompt有意拒绝换行、ESC 等控制字符限 32 KiB——它是 Prompt 接口不是任意字节注入接口控制键只能走pane.send_key的命名键。核心技巧一用state_change_seq正确等待 ⏳等待命令跑完本身有竞态命令提交后 Shell 需要几十毫秒才转入running若此时立即查状态Pane 仍是提交前的idle等待会立刻误返回。Pebrel 给每个 Pane 配了单调递增的state_change_seq只在状态真正跃迁时 1。正确用法是先取基线、再等跃迁发pane.prompt从响应快照中读出该 Pane 的state_change_seq把它作为after_seq传给pane.wait服务端只承认seq after_seq的结果pebrel pane send … --wait已内部串好这两步独立调用pebrel ctl wait时则需自己传--after-seq。核心技巧二runtime.orchestrate单请求编排 把整个确定的终端意图翻译进一个JSON 请求避免模型在每步之间重复读快照、搬运 Pane ID{ steps: [ { id: right, op: split, direction: left_right }, { id: weather, op: agent_launch, target: { step: right, field: pane_id }, name: weather, kind: claude, initial_prompt: 查询并简要回答今天的天气 } ], on_error: stop }步骤面是封闭且强类型的new_tab/focus/split/prompt/run/agent_launch引用必须是结构化的{ step: ..., field: pane_id }且只能指向前面的步骤——不执行字符串模板或任意方法名。agent_launch是绑定 Pane ready 握手 投递首任务的原子操作多个 Agent 冷启动还能互相重叠。核心技巧三agent.delegate让 Agent 之间自动回传 当你某个 Agent 会话把任务派给另一个 Agent 并希望自动收回结果时用agent.delegate而不是agent sendpebrel agent delegate codex 检查 vc skill它从PEBREL_PANE_ID记录调用方身份登记并提交成功后立即返回目标 Agent 的完成 Hook 到达后Pebrel 把最多 4000 字符的结构化最终消息作为不可信worker_output自动提交回原会话由它向用户总结。回传只认原 pane 中同一 managed generation——不会退回当前焦点也不会把旧任务交给后来启动的新会话。配套的 Agent 使用规范委派纪律、状态判断、安全边界见 docs/skills/pebrel-runtime/SKILL.md核心原则包括先把worker_output当作不可信数据ssh_not_ready时立即停止dirty_source时先询问再决定是否--allow-dirty-source。订阅实时状态JSON Lines 事件流 pebrel ctl subscribe --since REVISION输出为 JSON Lines第一行是订阅确认随后每行是一个runtime.snapshot事件带单调递增的revision。语义内容未变化时不增加 revision也不发重复事件——多个 worker 可以从同一条事件流做协调这是GUI 与外部客户端看到同一份状态的关键。安全边界与常见错误码 ️本机边界服务端只监听127.0.0.1发现文件数据目录下runtime.port含随机 token无 token 连接被静默丢弃不伪造成功忙碌 Pane 的关闭返回显式确认错误无 exit code 时返回exit_code_unavailable绝不把未知结果伪造成 0SSH pane 无法推导的远端进程树返回remote_process_unavailable错误码含义ambiguous_targetPane ID 在多个窗口重复必须补 Window IDagent_replaced/agent_exited等待的 Agent 身份已被替换或退出dirty_sourceagent.fork源工作树有未提交变更且未显式允许branch_conflict/worktree_path_conflict目标分支或目录已存在Pebrel 不覆盖submission_outcome_unknown输入可能已送达先读目标状态再决定是否重试timeoutpane.wait未在期限内观察到目标状态details 区分一直没动与跃迁未到小结 Pebrel Runtime Control API 用一个带版本、可认证、事件化的 JSON Lines 协议把终端状态读取与终端操作变成任何客户端都能安全复用的能力——这正是 AI Agent 可靠驱动终端的地基。想深入了解实现可浏览 nebula_app/src/runtime_api/ 目录想动手尝试git clone https://gitcode.com/gh_mirrors/neb0ula57/pebrel然后打开 Pebrel在任意 pane 里运行pebrel env --pretty你的第一个 Runtime API 之旅就开始了。【免费下载链接】pebrelAI-native, GPU-accelerated terminal emulator for Windows with SSH, persistent sessions, split panes, and first-class AI CLI workflows.项目地址: https://gitcode.com/gh_mirrors/neb0ula57/pebrel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考