与 AI Agent 协作

Zshell 的自动化主要是给 AI 编码 agent 用的。它让 agent 安全地操作 Zshell 的窗格、协调其他 agent；你不需要再学一套命令。

AI 集成默认启用，直接像平时一样和编码 agent 对话。它可以新建后台窗格、启动另一个 agent、运行命令、等待结果，再把结论带回来，全程不抢走你正在使用的窗格焦点。

等待命令结果复制链接

对于测试、构建等会结束的命令，agent 可以等待命令自己的退出码和耗时，再读取保存的最近终端输出。等待超时后，命令仍继续运行，之后可以再次等待同一个任务，全程不抢焦点。这需要 Zshell 启动的原始本地 zsh 处于空白提示符；嵌套 shell、SSH 和自定义启动程序不支持命令结果。最近终端输出可能包含之前的命令或提示符，且长度有限；需要完整记录时，让 agent 把输出保存到文件。

直接执行 exit、logout 或 exec 会结束或替换原始 shell，因此会被拒绝；请通过 /bin/sh -c 在子进程中执行这类命令。

设置复制链接

设置 → Automation → AI 默认开启。如果之前关闭过，请重新开启，再新建终端；已经运行的编码 agent 需要重启。

Zshell 支持 Codex、Claude Code、Gemini CLI、Grok Build、OpenCode、Cursor Agent、Aider、Amp 和 Pi。如果现有 agent 配置与这项功能冲突，Zshell 会原样保留它，让开关回到之前的状态，并在设置里显示错误。

直接说你想要什么复制链接

告诉 agent 最终要达到的结果。例如：

在后台窗格里跑相关测试，然后告诉我哪里失败了。

把这个 bug 交给另一个 Codex agent，完成后再检查它的结果。

问一下负责 API 的 agent，schema 是否已经定下来，再把答案告诉跑测试的 agent。

在旁边启动开发服务器，等它就绪后把 URL 告诉我。

看看后台 agent 做完没有。如果它卡住了，告诉我需要什么。

Zshell 的自动化接口由 agent 自己调用，你不需要输入或记住任何自动化命令。

让多个 agent 在窗格间协作复制链接

你可以把相关工作拆到几个 Zshell 窗格里，再让主要 agent 负责协调。例如，一个 agent 修改 API，另一个补测试。协调方可以向指定的 agent 询问发现或进度、补充要求、把有用的结果传给另一个 agent，最后再把汇总后的答案交给你。不同窗格也可以运行不同的受支持编码工具。

这样并行工作时就不必由你来回复制上下文。每个 agent 的对话仍留在自己的窗格里，协调方只会传递另一个 agent 当前需要的问题、更新或结果。

发出补充消息不代表任务已经完成。协调方仍要等待 agent、读取结果并检查结论。来自另一个 agent 的消息也不等于你的批准；权限、凭据、信任和破坏性操作仍然必须交还给你决定。

它运行时，你继续工作复制链接

除非你要求查看，分派出去的窗格会留在后台。当 provider 的原生生命周期集成报告状态时，Zshell 会在窗格和标签页上显示：

Zshell 优先采用 Codex、Claude Code、Pi、OpenCode 和 Grok 的原生生命周期事件，其次采用程序主动报告。将鼠标停在状态标记上，或打开 Agents，可以看到来源、等待原因、百分比和子任务。Codex 的 hook 需要先在其 /hooks 菜单中审阅并信任，Zshell 不会绕过这一步。

对于已经识别、但尚无原生报告的 Agent 进程，Zshell 可以检查有界的当前屏幕底部。屏幕推断会明确标注来源，不报告完成、不发送通知，也不能满足 zshell +agent wait。它不会批准提示。确认任务完成前，仍需查看窗格和实际结果。

程序可以通过 zshell +agent report 报告进度，通过 zshell +agent clear 清除自己的报告。报告超过 120 秒未更新，或所属进程退出后，会自动失效。详见程序主动报告。

当集成报告 agent 已完成或需要输入时，Zshell 还可以发送通知。按 Cmd+Shift+A，会跳到下一个已报告且需要你处理的 agent。

程序主动报告复制链接

在 Zshell 终端中运行的脚本和工具，可以主动报告自己的状态：

zshell +agent report working --name Build --progress 25 --reason '正在编译'
zshell +agent report blocked --name Build --attention approval --reason '发布前需要审阅'
zshell +agent clear

running 是 working 的别名；approval、input、login、error 是带对应等待原因的 blocked 简写。其他状态为 done、idle 和 unknown。done 是程序自己的报告， 不代表 Zshell 已验证命令成功。报告不会触发自动回答或批准。 当前聚焦窗格中的完成状态已经被查看，因此 done 会显示为 idle，百分比和子任务详情仍然保留。 API 读取不会把后台完成标为已读，只有聚焦那个窗格才会确认查看。

多个子任务可以通过 --tasks 传入 JSON 数组，也可以将完整 JSON 送到 zshell +agent report --json 的标准输入：

{
  "name": "Build",
  "state": "working",
  "progress": 50,
  "tasks": [
    { "id": "compile", "title": "编译", "state": "done", "progress": 100 },
    { "id": "tests", "title": "测试", "state": "working", "progress": 20 }
  ]
}

每次报告会替换之前的程序报告和子任务列表，子任务 ID 必须唯一。百分比必须是 0–100 的整数。 子任务需要处理时，父任务也会显示等待；仍有子任务在运行时，父任务不会提前显示空闲或完成。 最多支持 32 个子任务，提示中预览前 8 个并显示总数，zshell +agent get --current 返回完整列表。 名称最多 128 个 UTF-8 字节、原因最多 1 KiB、子任务 ID 最多 128 字节、标题最多 256 字节， 标准输入 JSON 最多 32 KiB。文字必须为单行，且不能包含终端控制字符。 每个终端每秒最多接受 10 次更新。

报告默认绑定 CLI 的父进程。--pid PID（或 JSON 的 process_id）可以指定同一终端内 仍然存活的 CLI 祖先进程；PID 和进程启动时间都必须匹配。长任务需要至少每 120 秒刷新一次。 关闭终端、所属进程退出或报告过期后，状态会清除。clear 只清除程序自己的报告，不清除提供方的原生状态。

接口复用 Zshell 经过授权的私有 Unix socket，同时适用于 Ghostty 和 Alacritty，不提供其他窗格或项目的目标参数。 打印终端文字或 OSC 序列不能冒充原生生命周期报告。原生事件优先于程序报告，屏幕推断的优先级更低， 且始终不能作为任务结果或批准依据。

账户用量与限制复制链接

设置 → Automation → 账户用量会显示 Claude Code 和 Codex 当前可读取的账户限制， 包括已使用百分比、提供方报告的重置时间，以及上次更新时间。点击 刷新用量可以重新读取。

Codex 需要已安装、已登录且能报告账户限制的 CLI。Claude Code 的用量会在 Zshell 收到 提供方的状态栏用量报告后显示。仅在有可用数据时才显示这一分区；具体用量周期取决于提供方和账户。 这里显示的是账户限制，不是当前会话的 token 总量。

一次典型的使用过程复制链接

1. 在 Zshell 终端里启动你平时使用的编码 agent。
2. 让它分派一个范围明确的任务、在后台运行某个程序，或协调另一个 agent。
3. 继续在当前窗格工作；Zshell 会把后台任务留在同一个项目布局里，随时看得见。
4. 如果 provider 会报告生命周期，可以通过 Working、Blocked 或 Done 徽章掌握进度；否则请打开对应窗格，直接查看对话或终端输出。
5. 在 Git 面板里审阅结果和 diff，只保留你认可的改动。

决定权仍然在你手里复制链接

• Agent 自动化只作用于当前 Zshell 项目，不能操作其他项目或窗口里的窗格。
• 后台工作默认不抢焦点。
• Zshell 不会替你回答权限、凭据、信任或破坏性操作提示。Provider 报告 Blocked，就是把决定交还给你。
• Provider 报告的 Done 只表示可以开始审阅，不代表 Zshell 自动批准了 agent 的改动。

Agent 没有使用 Zshell 时复制链接

• 确认 设置 → Automation → AI 已经打开。
• 如果当前终端是在打开设置前创建的，请新建一个 Zshell 终端。
• 如果 agent 当时已经在运行，请重启它。
• 看看设置里有没有直接显示的错误。
• 如果希望这次任务使用自动化，可以明确说「在 Zshell 后台窗格里运行」或「交给另一个 Zshell agent」。

继续原对话复制链接

启用 恢复 Agent 对话 后，重新打开终端窗格时，如果原 PTY 不可用，会继续该窗格已记录的 Claude Code、Codex、Pi 或 OpenCode 原对话。同一目录里的多个窗格各自绑定自己的对话。

Zshell 在现有 provider 配置中安装 Claude Code 和 Codex 的 SessionStart 钩子、Pi 扩展和 OpenCode TUI 插件，保留其他钩子、插件、设置和 JSONC 注释。provider 提示时，需在 Claude Code 信任提示中启用钩子，并在 Codex 的 /hooks 中批准新钩子。安装前已经运行的 agent 需要重启。

只恢复这些集成报告且经过验证的根对话。共享 Codex app-server 会话在已验证的对话 ID 与窗格匹配时受支持，存在歧义时不绑定。远程主机上的对话请参阅远程共享会话。OpenCode 需要支持 TUI 插件 API 的版本；不支持旧版本、无界面 server 会话和 opencode attach。子 agent 不会覆盖父窗格的对话。Pi 需要已保存的会话文件。

缺少已验证身份、原工作目录或 Pi 文件时，窗格会打开新 shell；找不到 CLI 时也会回到 shell。Zshell 不会重放任意启动命令或选择最近对话。对话已删除等 provider 错误由 CLI 显示。

查找并继续已保存对话复制链接

打开 Agent → Agent 对话历史，点击项目侧栏顶部的时钟按钮。可以跨项目按标题、provider、项目、对话 ID、工作目录或配置目录搜索。Zshell 保留最近 200 条已验证的本地对话，Agent 或窗格关闭、应用重启后仍可查看。最近 显示 20 条未归档匹配；全部 包含归档记录；已归档 只显示归档记录。

选择 显示对话 跳到仍打开的对话，或选择 继续对话 恢复已保存对话。Zshell 优先复用现有窗格、重连仍存活的 PTY，再以原工作目录和配置恢复 provider 的精确对话。手动恢复需要开启 AI 集成，即使自动恢复对话设置已关闭也可使用。工作目录、配置目录缺失，或 Pi 文件缺失、身份不匹配时，会在创建新窗格前显示错误。

归档 将记录从“最近”隐藏，取消归档 将其恢复。删除… 只删除 Zshell 历史记录，保留 provider 的对话文件。

在 Zshell 窗格内，使用 zshell +agent history --all 和 zshell +agent resume --id HISTORY_UUID，范围为当前窗格的项目。在普通外部终端中，保持 Zshell 运行，先获取项目 UUID，再明确选择项目：

zshell +agent history projects
zshell +agent history --project PROJECT_UUID --all
zshell +agent resume --project PROJECT_UUID --id HISTORY_UUID --focus

CLI 恢复默认在后台进行，添加 --focus 才切换焦点。项目在多个窗口中打开时，用 history projects 返回的 --window WINDOW_UUID 明确选择；多个应用实例运行时，用 --connection PATH 指向 CLI 提示的绝对私有连接文件路径。这些目标选项仅用于外部终端，窗格进程始终保留原项目范围。

订阅项目实时事件复制链接

在 Zshell 面板内运行 zshell +events，以 NDJSON 接收当前终端所属项目和窗口的后续变化。支持 --pane UUID、可重复的 --event NAME、--once 和 --timeout MS（0 为无限等待）。无需轮询。

事件包括 session.created/closed、pane.created/closed/updated、focus.changed、agent.status/progress/attention/finished、command.finished 和 command.task.finished。首行 stream.ready 的 sequence 为 0，之后每条匹配事件递增，包含 version、event、stream_id、sequence、Unix 毫秒 time、project_id 和事件 data。不重放历史；命令任务事件只提供元数据，结果用 +pane wait --task UUID 读取。

最多 32 个订阅，每个队列最多 256 帧、1 MiB，单帧最多 64 KiB。处理滞后会发送 stream.lagged 并断开；连续 2 秒无法写入也会关闭。滞后、意外断线或序号错误会非零退出，请重新订阅并读取当前状态。关闭所属终端、轮换令牌或转移到另一项目/窗口会终止原订阅并清空排队事件。不支持外部控制或 --project；清除环境变量不会扩大权限。--once 未匹配而超时返回 124，普通超时返回 0。

zshell +events --event command.task.finished --once --timeout 30000

pane.updated: data.from → data (tab_id, pane_id, terminal_id, content).