本页面的翻译由 LLM 生成。如果你发现翻译有误,请在 GitHub 上提交 issue 告诉我们。

CLI 参考

Next docs describe unreleased work from master. Stable docs remain at /docs/.

PK-Herdr 的 CLI 通过与集成和智能体相同的本地 socket API 与运行中的服务器通信。

大多数命令输出 JSON 响应。需要确定性自动化时,从脚本中使用它们。

启动与状态

herdr                         # 启动或连接默认会话
pk-herdr --session work          # 启动或连接命名会话
pk-herdr --remote workbox        # 通过 SSH 连接,使用本地按键绑定
pk-herdr --remote workbox --remote-keybindings server
pk-herdr --remote workbox --handoff
pk-herdr --no-session            # 单进程逃生舱
pk-herdr --default-config        # 打印默认配置
pk-herdr update                  # 从配置的通道下载并安装
pk-herdr update --handoff        # 对受支持的运行中服务器启用实时交接
pk-herdr completion zsh          # 生成 zsh 补全脚本
pk-herdr channel show            # 打印 stable 或 preview
pk-herdr channel set preview     # 启用预览构建
pk-herdr channel set stable      # 把 Linux/macOS 直接安装切回稳定版
pk-herdr --version               # 打印版本

状态命令:

pk-herdr status
pk-herdr status server
pk-herdr status client

API schema 命令:

pk-herdr api schema
pk-herdr api schema --json
pk-herdr api schema --output herdr-api.schema.json

pk-herdr api schema 会打印安装的二进制中包含的 socket 协议 schema 简短摘要。需要完整 JSON Schema 文档时使用 --json;要写入文件则使用 --output PATH。

Shell 补全

pk-herdr completion zsh
pk-herdr completions zsh
pk-herdr completion bash
pk-herdr completion fish
pk-herdr completion powershell
pk-herdr completion elvish

completion 会把脚本打印到 stdout。completions 是别名。临时 zsh 会话可以直接加载脚本:

source <(pk-herdr completion zsh)

持久 zsh 设置中,把生成的 _herdr 函数写到 compinit 运行前已经在 fpath 上的位置:

mkdir -p ~/.zfunc
pk-herdr completion zsh > ~/.zfunc/_herdr

然后确认 .zshrc 包含:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit

服务器

pk-herdr server
pk-herdr server stop
pk-herdr server reload-config
pk-herdr server agent-manifests [--json]
pk-herdr server update-agent-manifests [--json]
pk-herdr server reload-agent-manifests

pk-herdr server 显式运行无界面服务器,适合被监管或服务式的部署。reload-config 在不重启窗格的情况下应用可重载设置。agent-manifests 显示生效的智能体检测清单来源、缓存的远程版本和最近的远程更新结果。update-agent-manifests 立即拉取远程清单更新,重载到运行中的服务器,并打印更新后的清单状态;要原始状态响应就加 --json。reload-agent-manifests 在编辑本地覆盖后,把智能体检测清单重载到运行中的服务器。

通知

pk-herdr notification show <title> [--body TEXT] [--position top-left|top-right|bottom-left|bottom-right] [--sound none|done|request]

notification show 使用配置的 [ui.toast] 投递方式。--position 只影响 PK-Herdr 应用内的 toast。--sound 默认为 none;done 和 request 只在通知实际显示时播放已有的完成音和需要关注音。

会话

pk-herdr session list [--json]
pk-herdr session attach <name>
pk-herdr session stop <name> [--json]
pk-herdr session delete <name> [--json]

需要显式停止默认会话时,把会话名写成 default。

工作区

pk-herdr workspace list
pk-herdr workspace create [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus]
pk-herdr workspace get <workspace_id>
pk-herdr workspace focus <workspace_id>
pk-herdr workspace rename <workspace_id> <label>
pk-herdr workspace report-metadata <workspace_id> --source ID [--token NAME=VALUE] [--clear-token NAME] [--seq N] [--ttl-ms N]
pk-herdr workspace close <workspace_id>

不抢占焦点地创建工作区:

pk-herdr workspace create --cwd ~/project --label api --no-focus

工作区是顶层项目或工作上下文。创建工作区也会创建第一个标签页和根窗格。JSON 响应中的 .result.workspace.workspace_id、.result.tab.tab_id 和 .result.root_pane.pane_id 是对应 ID。

Worktree

pk-herdr worktree list [--workspace ID | --cwd PATH | --ssh TARGET --repo PATH] [--json]
pk-herdr worktree create [--workspace ID | --cwd PATH | --ssh TARGET --repo PATH] [--branch NAME] [--base REF] [--path PATH] [--label TEXT] [--focus] [--no-focus] [--json]
pk-herdr worktree open [--workspace ID | --cwd PATH | --ssh TARGET --repo PATH] (--path PATH | --branch NAME) [--label TEXT] [--focus] [--no-focus] [--json]
pk-herdr worktree remove --workspace ID [--force] [--json]

worktree 是带有 Git 检出来源信息的普通 PK-Herdr 工作区。worktree create 创建一个 Git worktree 检出,作为工作区打开,并与父仓库工作区分到一组。如果 --branch 指向已有的本地分支,PK-Herdr 检出它;否则从 --base 或 HEAD 创建分支。没有 --path 时,PK-Herdr 在 <worktrees.directory>/<repo>/<branch-slug> 下创建检出。

workspace close 只关闭 PK-Herdr 状态。worktree remove 是显式的检出删除路径;它运行 git worktree remove,从不删除分支,并在 Git 拒绝脏检出时要求 --force。

SSH 目标 worktree

--ssh TARGET 让 worktree 操作通过 SSH 在远程主机上执行,而不是本地机器 — 适合 Tailscale 网格,例如 PK-Herdr 运行在 Windows 上,却把 worktree 部署到一台 Mac。TARGET 可以是你的 ssh 接受的任何形式:~/.ssh/config 别名、user@host 或 MagicDNS 名称。--ssh 需要用 --repo 指定该主机上的仓库路径,且不能与 --workspace/--cwd 同用。

pk-herdr worktree create --ssh mac --repo ~/src/myrepo --branch feat/x
pk-herdr worktree list   --ssh mac --repo ~/src/myrepo
pk-herdr worktree open   --ssh mac --repo ~/src/myrepo --path ~/.herdr/worktrees/myrepo/feat-x
pk-herdr worktree remove --workspace 3          # 远程删除按工作区的 ssh 来源信息路由

--ssh 下的语义:

--path 和 --repo 在远程主机上按原样解释(POSIX 路径或 ~/...),绝不会针对本地文件系统解析。
没有 --path 时,检出默认位于远程的 ~/.herdr/worktrees/<repo>/<branch-slug>。
Git 命令通过带 BatchMode=yes 的 ssh -T TARGET /bin/sh -s 一次性执行,因此基于密钥的认证必须已经能非交互工作(先用 ssh TARGET 验证;带口令的密钥用 ssh-add 加载)。PK-Herdr 从不禁用主机密钥检查 — 新主机密钥请先手动 ssh TARGET 接受一次。
打开的工作区窗格是远程检出中的实时 ssh -t 登录 shell。会话恢复会重新生成 SSH 窗格。远程 worktree 必须用 --path 打开,不能用 --branch。
SSH 连接断开时(exit 255),窗格会自动重连 — 最多连续 3 次,连接保持一分钟后重置。远程正常 exit 会像平常一样关闭窗格。重连会启动新的远程 shell;断开会话中的进程不会恢复。
代理检测无法看到远程主机上的进程,本地 git 状态刷新会跳过远程工作区。

Tailscale Service 放置

给 --ssh 的主机部分加上 svc: 前缀,就会拨号一个 Tailscale Service 而不是固定机器。服务名是一个稳定入口,背后是当前通告该服务的那些 tailnet 机器,因此 create 会落在任何可用的机器上:

pk-herdr worktree create --ssh user@svc:build.tailnet.ts.net --repo ~/src/myrepo --branch feat/x
pk-herdr worktree list   --ssh user@svc:build.tailnet.ts.net --repo ~/src/myrepo

服务只在放置时选择一次机器。PK-Herdr 拨号服务,向应答的机器询问其稳定标识(Tailscale MagicDNS 名称,回退到主机名),并把 worktree 固定到该具体主机。之后的所有操作 — 工作区的 SSH 窗格、list、remove、会话恢复、重连 — 都使用固定的主机而非服务名,因此服务改路由到其他后端也不会让检出失联。可选的 user@ 前缀会保留在固定后的目标上。

由于已有的检出只存在于一台机器上,worktree open 拒绝 svc: 目标;请用 pk-herdr worktree list 显示的固定主机打开远程 worktree。后端主机必须能以自己的名字被 SSH 访问(Tailscale SSH,或对每个后端都有效的密钥),跨机器的持久性来自把分支 push 到 git 远端 — 服务只负责路由新的放置,不会移动文件。

标签页

pk-herdr tab list [--workspace <workspace_id>]
pk-herdr tab create [--workspace <workspace_id>] [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus]
pk-herdr tab get <tab_id>
pk-herdr tab focus <tab_id>
pk-herdr tab rename <tab_id> <label>
pk-herdr tab close <tab_id>

标签页是工作区内的另一个终端布局。不指定 --workspace 时,tab create 使用活动工作区;如果没有活动工作区则失败。JSON 响应中的 .result.tab.tab_id 和 .result.root_pane.pane_id 是对应 ID。

创建工作区、标签页和拆分窗格默认不改变焦点。--focus 选择新布局;--no-focus 显式表达默认行为。不指定 --cwd 时,新终端遵循 terminal.new_cwd 设置,默认跟随来源窗格或工作区。每个 --env KEY=VALUE 在新的根 shell 中添加或替换一个环境变量。

窗格

pk-herdr pane list [--workspace <workspace_id>]
pk-herdr pane current [--pane ID|--current]
pk-herdr pane get <pane_id>
pk-herdr pane layout [--pane ID|--current]
pk-herdr pane process-info [--pane ID|--current]
pk-herdr pane neighbor --direction left|right|up|down [--pane ID|--current]
pk-herdr pane edges [--pane ID|--current]
pk-herdr pane focus --direction left|right|up|down [--pane ID|--current]
pk-herdr pane resize --direction left|right|up|down [--amount FLOAT] [--pane ID|--current]
pk-herdr pane zoom [<pane_id>|--pane ID|--current] [--toggle|--on|--off]
pk-herdr pane rename <pane_id> <label>|--clear
pk-herdr pane split [<pane_id>|--pane ID|--current] --direction right|down [--ratio FLOAT] [--cwd PATH] [--env KEY=VALUE] [--focus] [--no-focus]
pk-herdr pane swap --direction left|right|up|down [--pane ID|--current]
pk-herdr pane swap --source-pane ID --target-pane ID
pk-herdr pane move <pane_id> --tab <tab_id> --split right|down [--target-pane ID] [--ratio FLOAT] [--focus|--no-focus]
pk-herdr pane move <pane_id> --new-tab [--workspace ID] [--label TEXT] [--focus|--no-focus]
pk-herdr pane move <pane_id> --new-workspace [--label TEXT] [--tab-label TEXT] [--focus|--no-focus]
pk-herdr pane close <pane_id>

接受 --current 的窗格命令在 PK-Herdr 窗格内运行时使用调用方的 HERDR_PANE_ID。对 pane split 而言,显式窗格 ID 或 --pane ID 拆分该窗格,--current 拆分调用方窗格,省略目标则使用 UI 当前聚焦的窗格。拆分响应中的新窗格 ID 位于 .result.pane.pane_id。

执行 pane move 后,后续命令应使用 .result.move_result.pane.pane_id。跨工作区移动会改变带工作区前缀的窗格 ID;旧值保留在 .result.move_result.previous_pane_id。运行中进程的 HERDR_PANE_ID、HERDR_TAB_ID 和 HERDR_WORKSPACE_ID 保持启动时的值,但 PK-Herdr 会把旧窗格 ID 保留为该终端的别名,所以使用 --current 的窗格命令仍能解析它。实时智能体名称也会跟随终端。

读取输出:

pk-herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi] [--raw]
pk-herdr pane read <pane_id> --source visible --ansi
pk-herdr pane read <pane_id> --source recent-unwrapped --lines 120

pane read 直接打印 UTF-8 终端文本。默认去除 ANSI 转义;来源包含样式时,使用 --format ansi 或 --ansi 保留。detection 来源始终是纯文本。对 recent 类来源,--lines N 会在可选的取消折行之前选择最后 N 个已渲染终端行;省略时默认读取 80 行。对 visible 和 detection,省略 --lines 会返回完整快照,指定时保留按换行分隔的最后 N 行。agent read 使用相同的输出和行数行为。

发送输入:

pk-herdr pane send-text <pane_id> <text>
pk-herdr pane send-keys <pane_id> <key> [key ...]
pk-herdr pane run <pane_id> <command>

<key> 使用 PK-Herdr 的组合键语法: a 这类普通可打印键,enter、tab、esc、backspace、left、right、up、down 这类特殊键,ctrl+h、control+j、alt+x、shift+tab 这类修饰组合键,f1 这类功能键,以及 minus、plus、backtick 这类命名标点。旧式的 C-c 和 c-c 作为 ctrl+c 的别名被接受。

标准拼写是 esc;也接受 escape。

pane run 会遵循当前的 bracketed paste 模式,并把文本和 Enter 作为一个原子操作提交。发送命令时优先用它,而不是 send-text 加 send-keys Enter;单独的发送操作仍是底层操作,不会提交命令。

从自定义钩子上报智能体状态:

pk-herdr pane report-agent <pane_id> \
  --source ID \
  --agent LABEL \
  --state idle|working|blocked|unknown \
  [--message TEXT] \
  [--seq N] \
  [--agent-session-id ID] \
  [--agent-session-path PATH]

pk-herdr pane report-agent-session <pane_id> \
  --source ID \
  --agent LABEL \
  [--seq N] \
  [--agent-session-id ID] \
  [--agent-session-path PATH] \
  [--session-start-source SOURCE]

pk-herdr pane release-agent <pane_id> \
  --source ID \
  --agent LABEL \
  [--seq N]

report-agent-session 只更新原生会话身份,不上报生命周期状态。release-agent 在智能体进程退出时结束该来源的生命周期权威。

当官方集成上报了原生会话引用时,pane get、pane list、agent get 和 agent list 会包含一个只读的 agent_session 对象。没有存储原生会话引用时,该字段被省略。

当 PK-Herdr 能解析控制窗格的前台进程的 cwd 时,这些命令会包含 foreground_cwd。已有的 cwd 字段仍然是用于标签和 follow-cwd 行为的窗格/工作区 cwd。

上报仅用于展示的窗格元数据,而不接管语义状态:

pk-herdr pane report-metadata <pane_id> \
  --source ID \
  [--agent LABEL] \
  [--applies-to-source ID] \
  [--title TEXT|--clear-title] \
  [--display-agent TEXT|--clear-display-agent] \
  [--state-label STATUS=TEXT] \
  [--clear-state-labels] \
  [--token NAME=VALUE] \
  [--clear-token NAME] \
  [--seq N] \
  [--ttl-ms N]

STATUS 是 idle、working、blocked、done 或 unknown 之一。--agent 和 --applies-to-source 只守卫 --title、--display-agent 和 --state-label,不守卫令牌补丁。上报方负责清除令牌或刷新 TTL。用 --display-agent 修改可见名称。

元数据文本在存储前会被规范化。PK-Herdr 去掉首尾空白、移除控制字符,并把 --title、--display-agent、每个 --state-label 和令牌值截断到 80 个字符。规范化后为空的令牌值会清除该键。

--token 设置一个命名展示值,--clear-token 删除一个值。未提及的令牌保持不变。窗格令牌可在智能体侧边栏行中写成 $name;工作区令牌可用于空间行。TTL 分别应用于该次调用更新的每个令牌键。

--source 和 --applies-to-source 必须不超过 80 个字符,并且只能包含 ASCII 字母、数字、冒号、点、下划线和连字符。--ttl-ms 让元数据自动过期,取值必须在 1 到 86400000 毫秒之间。想让元数据一直保留到被替换、清除或窗格或工作区关闭时,省略它。--seq 让 PK-Herdr 忽略来自同一 --source 的过期上报;过期上报会被 API 接受,但被窗格状态忽略。每个窗格或工作区在其生命周期内最多接受来自 32 个不同来源的带序号令牌上报,清除或过期不会释放这些来源名额。

智能体

窗格与智能体的模型和完整协调示例见智能体自动化。

pk-herdr agent list
pk-herdr agent get <target>
pk-herdr agent read <target> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi]
pk-herdr agent send-keys <target> <key> [key ...]
pk-herdr agent prompt <target> <text> [--wait] [--until STATUS]... [--timeout MS]
pk-herdr agent rename <target> <name>|--clear
pk-herdr agent focus <target>
pk-herdr agent wait <target> [--until STATUS]... [--timeout MS]
pk-herdr agent attach <target> [--takeover]
pk-herdr agent start <name> --kind KIND --pane ID [--timeout MS] [-- <agent-args...>]
pk-herdr agent explain <target> [--json|--verbose]
pk-herdr agent explain --file PATH --agent LABEL [--json|--verbose]

智能体目标只能是唯一的实时智能体名称,或当前承载该智能体的窗格 ID。终端 ID 和单独的智能体 kind 标签不能作为目标。通过 agent start 启动的智能体必须有名称;手动启动的智能体保持未命名,通过窗格 ID 寻址。

agent start 会在现有可用 shell 窗格中启动智能体:交互式 shell 必须占用前台,不能有正在前台运行的命令、编辑器或智能体。拓扑必须单独创建。名称在实时智能体中必须唯一,并匹配 [a-z][a-z0-9_-]{0,31}。支持的 kind 是 pi、claude、codex、gemini、cursor、devin、agy、cline、omp、mastracode、opencode、copilot、kimi、kiro、droid、amp、grok、hermes、kilo、qodercli 和 maki。名称属于当前窗格占用者,在该智能体退出、release 或被替换时清除;短暂的检测不确定不会清除它。

start 只有在预期智能体占用同一终端并可接受交互输入后才返回。默认启动超时是 30000 毫秒;显式值必须大于 3000 且不超过 300000。

agent prompt 遵循当前的 bracketed paste 模式，即使智能体处于 working 也会原子地提交文本和编码后的 Enter。使用 --wait 时，从非 working 状态发送的提示必须在五秒内产生可观察的生命周期变化，否则 PK-Herdr 返回 agent_prompt_stalled；调用方超时不超过五秒时，仍返回普通的 timeout 错误。观察到活动后，它会等待请求的稳定状态。它不会跟踪单独的轮次。如果智能体已经处于 working，当前轮次的完成可能满足等待。--until 用于缩小匹配状态，不带 --wait 时会被拒绝。独立的 agent wait 在当前状态匹配时立即返回。两者默认匹配 idle、done 或 blocked；需要 unknown 时请明确使用 --until unknown。

idle 表示智能体在等待输入,且其标签页已在聚焦的 PK-Herdr 界面中显示。done 是相同的底层 idle 状态,用于未查看的后台工作完成后。聚焦该标签页或用 pane focus / agent focus 指向它会标记为已查看;仅通过 CLI 读取不会改变它。blocked 表示 PK-Herdr 识别到审批或提问界面。unknown 表示智能体存在但无法可靠分类,不代表工作成功。

agent send-keys 发送 enter、up、esc、ctrl+c 等逻辑按键。PK-Herdr 会在写入任何字节前验证所有按键。agent read 读取解析出的终端流,agent rename 为已检测到的智能体命名。

agent explain 请求运行中的服务器对屏幕检测所用的同一份底部缓冲区检测快照进行分类,因此实时输出反映服务器生效的清单缓存。因为它使用 agent.explain socket 方法,升级 PK-Herdr 后,请先重启或交接到更新后的服务器,再使用实时 explain。用 --file PATH --agent LABEL 可以改为在本地解释一份保存的样本。默认输出显示智能体、最终状态、清单来源和版本、匹配的规则及其区域证据,以及任何回退、跳过或警告原因。加 --verbose 可以看到可见证据标志、缓存的远程版本、本地覆盖的遮蔽情况、远程更新状态,以及带匹配器和区域证据的完整已评估规则列表。提交问题报告或写测试时加 --json。

普通终端、服务器、测试、shell 或底层终端控制,请使用 pane send-text、pane send-keys、pane run 和 terminal attach。想带回车提交命令时用 pane run。

直接终端附加

pk-herdr terminal attach <terminal_id> [--takeover]
pk-herdr terminal title set <title>
pk-herdr terminal title clear

从直接附加中用 ctrl+b q 分离。用 ctrl+b ctrl+b 发送字面的 ctrl+b。 terminal title clear 恢复 PK-Herdr 默认的外层终端窗口标题。

输出等待

等待窗格中的输出:

pk-herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--raw]

普通命令和服务器用 pane wait-output。编程智能体用 agent wait。

pane wait-output 会立即检查所选快照,所以已经存在的输出也能匹配。默认来源名是 recent;匹配时会把最近 80 个已渲染终端行作为未折行输出处理。--lines 可以修改这个行数限制。--match 在单行中查找字面子串;--regex 使用 Rust 正则表达式语法并逐行匹配。

pane wait-output、agent wait 和 agent prompt --wait 在省略 --timeout 时会无限等待。超时或服务器错误以 JSON 写到 stderr,退出状态为 1。CLI 用法错误的退出状态为 2。

集成

pk-herdr integration install pi
pk-herdr integration install omp
pk-herdr integration install ompk
pk-herdr integration install claude
pk-herdr integration install codex
pk-herdr integration install copilot
pk-herdr integration install devin
pk-herdr integration install droid
pk-herdr integration install kimi
pk-herdr integration install opencode
pk-herdr integration install kilo
pk-herdr integration install hermes
pk-herdr integration install mastracode
pk-herdr integration install qodercli
pk-herdr integration install cursor
pk-herdr integration uninstall pi
pk-herdr integration uninstall omp
pk-herdr integration uninstall ompk
pk-herdr integration uninstall claude
pk-herdr integration uninstall codex
pk-herdr integration uninstall copilot
pk-herdr integration uninstall devin
pk-herdr integration uninstall droid
pk-herdr integration uninstall kimi
pk-herdr integration uninstall opencode
pk-herdr integration uninstall kilo
pk-herdr integration uninstall hermes
pk-herdr integration uninstall mastracode
pk-herdr integration uninstall qodercli
pk-herdr integration uninstall cursor
pk-herdr integration status [--outdated-only]

插件

插件命令用于安装和运行本地可执行的工作流插件。插件是清单加进程外命令;PK-Herdr 负责宿主侧,插件负责自己的实现语言。

安装、列出和移除插件:

pk-herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
pk-herdr plugin list [--plugin ID] [--json]
pk-herdr plugin uninstall <plugin_id|owner/repo[/subdir...]>
pk-herdr plugin enable <plugin_id>
pk-herdr plugin disable <plugin_id>

plugin install 只接受 GitHub 简写,比如 ogulcancelik/herdr-plugin-examples/worktree-bootstrap。它使用 git,在交互式终端显示信任预览,运行受支持的清单构建命令,并把 GitHub 安装保存在 PK-Herdr 管理的目录中。非交互式安装用 --yes。重新安装 GitHub 管理的插件会替换该托管检出。不允许覆盖安装到本地链接的插件之上。插件清单必须声明 min_herdr_version;当插件要求更新的 PK-Herdr 二进制时,install 和 link 会失败。plugin list 默认是人类可读的;要原始 API 响应就传 --json。

本地开发:

pk-herdr plugin link <path> [--disabled]
pk-herdr plugin unlink <plugin_id>

plugin link 接受包含 herdr-plugin.toml 的插件目录,或直接指向清单的路径。从本地检出编写或测试插件时,它仍然是正确的命令。plugin unlink 注销插件、不动文件。plugin uninstall 注销插件,并同时删除 PK-Herdr 管理的 GitHub 检出文件。对 GitHub 安装,uninstall 既接受插件 id,也接受与 install 相同的 owner/repo[/subdir...] 简写。动作、事件钩子、窗格和链接处理器在清单中声明;运行时动作注册不在 v1 范围内。

配置目录:

pk-herdr plugin config-dir <plugin_id>

plugin config-dir 打印插件的配置目录,需要时会创建它 (旧版插件配置位置存在时会从那里初始化)。在安装文档和 shell 脚本中用它给用户指出一个稳定路径,用于存放 .env 等用户可编辑配置,与托管的插件检出分开。

动作:

pk-herdr plugin action list [--plugin ID]
pk-herdr plugin action invoke <action_id> [--plugin ID]

plugin action invoke 为一个已安装、已启用、平台兼容的插件动作启动清单命令,并在 JSON 响应中打印已启动命令的日志记录。当多个插件使用相同的动作 id 时,使用限定的动作 id (plugin.id.action)。本地动作 id 不能包含点,所以即使插件 id 包含点,限定 id 也不会有歧义。

日志:

pk-herdr plugin log list [--plugin ID] [--limit N]

托管终端窗格:

pk-herdr plugin pane open --plugin ID --entrypoint ID [--placement overlay|popup|split|tab|zoomed] [--width SIZE] [--height SIZE] [--workspace ID] [--target-pane PANE] [--direction right|down] [--cwd PATH] [--env KEY=VALUE] [--focus|--no-focus]
pk-herdr plugin pane focus <pane_id>
pk-herdr plugin pane close <pane_id>

plugin pane open 要求插件已链接、已启用并与当前平台兼容。它把清单声明的 [[panes]] 命令作为 PK-Herdr 管理的终端窗格启动。清单的默认值是 overlay,在活动窗格上方打开一个临时的缩放覆盖层。它也可以作为分割、新标签页、缩放窗格,或不改变标签页布局的会话级模态 popup 打开。--width 和 --height 以终端单元格数或 80% 这样的百分比设置弹窗外层尺寸;省略时默认为终端大小的一半,过小的值会限制为弹窗最小尺寸。弹窗不是 PK-Herdr 窗格,不会收到 HERDR_PANE_ID,也不参与 pane 或智能体 API。非终端的原生插件窗格是之后的能力面。

--env KEY=VALUE 可以在启动进程的命令上重复使用,只作用于新启动的进程。当与调用方提供的环境变量冲突时,HERDR_SOCKET_PATH、HERDR_BIN_PATH、HERDR_ENV、HERDR_WORKSPACE_ID、HERDR_TAB_ID、HERDR_PANE_ID、HERDR_PLUGIN_ID、HERDR_PLUGIN_ROOT、HERDR_PLUGIN_CONFIG_DIR、HERDR_PLUGIN_STATE_DIR、HERDR_PLUGIN_ENTRYPOINT_ID 和 HERDR_PLUGIN_CONTEXT_JSON 等 PK-Herdr 管理的变量保持权威。

读取来源

来源	含义
`visible`	当前渲染的屏幕。最适合 UI 反馈循环。
`recent`	带终端折行的最近回滚内容。
`recent-unwrapped`	不带软折行的最近回滚内容。最适合日志。
`detection`	智能体屏幕检测使用的底部缓冲区快照。

此表描述读取时的含义。仅对 pane wait-output 而言,recent 和 recent-unwrapped 都搜索 recent 的未折行快照,默认写法仍是 recent。

环境变量

变量	用途
`HERDR_CONFIG_PATH`	覆盖配置文件路径。
`HERDR_SESSION`	为 CLI 命令选择命名会话。
`HERDR_SOCKET_PATH`	底层 socket 路径覆盖。
`HERDR_ENV`	在 PK-Herdr 管理的窗格进程内设为 `1`。
`HERDR_PANE_ID`	运行中窗格进程的公开窗格 id。
`HERDR_TAB_ID`	运行中窗格进程的公开标签页 id。
`HERDR_WORKSPACE_ID`	运行中窗格进程的公开工作区 id。
`HERDR_LOG`	设置日志过滤,例如 `HERDR_LOG=herdr=debug`。
`HERDR_DISABLE_SOUND`	即使启用了声音通知也禁用声音播放。