Task Delegation · 基于 Herdr 与 Magpie 的任务委托
有独立目标和验收、需要另一 runner 的能力或上下文、或并行执行收益大于交接成本时,
主 Agent 才委托;紧耦合的小任务直接自己做。委托时选择能完成任务且成本与延迟合理的
执行通道,交接后追踪真实结果。Herdr 管理执行终端与 Agent 状态;Magpie 提供模型、
provider、账户与额度线索;
runner 自己拥有会话和恢复方式。具体 route 是否能调用,仍要核对认证、产品条款、runner
参数与实际配置。技能不创建另一套 Agent 框架,也不把配置文字当作权限保证。
多任务的分工、覆盖和总体验收由
divide-and-conquer
负责;本技能只处理每项任务的选路、交接和接续记录。用户只要套餐价格比较时用
plan-value-analysis。
首次启用:与用户协商策略
全局策略位置为 XDG_CONFIG_HOME/task-delegation/policy.md;XDG_CONFIG_HOME 未设置
或不是绝对路径时使用 ~/.config/task-delegation/policy.md。先检查是否已有策略,
有则保留并读取,不能以模板覆盖。没有时,先与用户对话协商:已拥有且允许使用的套餐与
官方访问方式、当前可安装/使用的 runner、偏好的 provider/model、优先/避开/禁止、
付费 API fallback 及预算、任务的质量与延迟取舍。只需问会影响选路的未知,不索取凭据。
据工具、上下文、恢复、隔离、质量/延迟和用户偏好,与用户选定默认及备选 runner,
记录取舍理由;这是可修订的起点,不强制每项任务用同一 runner。取得这些决定后由
主 Agent 直接写可编辑 Markdown;以
策略示例作结构参考,不照抄其中占位符当用户事实。
策略是给主 Agent 和获准决策器阅读的指引:禁止是硬边界,避开是可解释的软偏好。
写着“有订阅”不等于当前已认证可调用,Markdown 也不会机械强制权限。项目自身的
AGENTS.md 和本次任务授权继续适用;与全局策略冲突的硬边界在澄清前不得放宽。
策略更改需保留用户已有选择,不因工具目录变化自动改写个人偏好。配置和日志位置、
保留内容及示例见配置与接续日志。
为任务选可兑现的路
- 明确任务目标、范围、输入与可读上下文、允许的写入或外部效果、产物和验收依据。
先判定工具、上下文、会话恢复、隔离、推理可靠性和可接受延迟;不让低价覆盖能力缺口。
- 读取适用策略,先排除禁止的 runner、provider、route 和计费路径;“避开”是可解释的
软偏好,不等于禁止。确认套餐的官方受支持入口和当前认证/计费身份,区分原生 runner
订阅、官方授权的套餐集成与单独计费的 API。订阅不自动产生 API key,登记账户不等于可调用。
- 用 Magpie 当前目录、配额及 runner 的真实模型参数检查候选;目录说明候选 ID,不证明
质量、剩余额度或可用认证。同一共享池的两个 route 不算两份余额。默认从能满足上述
门槛的较轻量 runner 起选,再比较成功率、端到端延迟和边际费用;尊重用户偏好,优先
利用合规、已付且可用的套餐额度。不固定 Claude、Pi、Fx 或最轻模型,也不以用完额度为目标。
- 依据当期官方模型能力目录、可比的原始评测和本地任务反馈,按任务类别、工具可靠性、
上下文、端到端延迟与成本选择。记录准确模型版本、runner/推理档、来源日期及未知。
初始化、目录或套餐变化、证据过时、任务类型变化、反复失败或 429 时刷新相关证据,
不为每个小任务重抓全网,也不编造实时排名。详见选路判断。
- 若有当前已验证、获授权且符合相同禁止/预算边界的 decision API 或 Jev,可让它辅助筛选;
先计入选路调用自身的费用。若只能走未授权付费通道、能力不符或接口未证实,主 Agent
直接按上述策略选择。Magpie 的 Jev effort classifier 与任务级路由不同,不能替代此步。
委托、观察与回收
主 Agent 可从 Herdr pane 内控制当前会话;在外部终端控制时须有相应授权,明确指定
--session、核对目标 pane,不能依赖默认会话。Fx 桥接器的 start/resume 本身只能在
真实 Herdr pane 中运行,不伪造环境变量。读取
已核实的 CLI 接口与示例,核对现场 --help、runner 认证和执行参数;
不修改 Magpie 的全局模型、group 或 fallback 配置来完成一次委托。Herdr 不支持的 runner
不能假装为 Herdr kind。优先选满足任务的实际执行形态:Herdr 原生支持的 runner 可由
Herdr 启动;已有 Agent 若能按授权调用 Fx,可让它执行;一次性 Fx 任务可直接用其 CLI
并核对 JSON 回执;只有需要 Herdr 追踪 Fx 多轮状态与恢复时才用可选长驻薄适配器,见
Fx 接入参考。由受支持 Agent 调用 Fx 时,Herdr 跟踪的是外层 Agent;
它须另收 Fx 回执和原生 session ID,且外层 Agent 的模型调用也计入套餐或费用。适配器由
主 Agent 在获准环境中部署并启动;自报告 Fx 的输入先由适配器编码成 shell 空操作封套,
再通过 Herdr pane 接口提交并核对适配器回执,不能套用原生 agent prompt 或向 pane
直接发送任务正文。Markdown 策略不是路由白名单。交给执行者的任务应包含:
目标与验收;范围和禁止事项;必要上下文及权威来源;可读写位置、工具与权限;
期望产物与路径;应运行的检查;失败、阻塞和未知时返回什么。
Herdr 的状态只说明观察到的生命周期,不证明产物正确。blocked 先检查问题或审批界面;
stalled、超时及 unknown 先核对状态与输出,不盲目重发。拿到结果后按原验收依据审查
产物、验证和权限边界,再向调用者交还采用的 route、理由、实际观察和剩余未知。
在跨项目日志中记短描述、带时区时间、runner、状态和稳定 task_ref;Herdr agent/pane 与
真实 runner session 分列。未知 session 先标 pending,确认后以同一 task_ref 追加事件,
不把 pane ID 当作可恢复会话,也不记任务全文、凭据或完整地址。详见
配置与接续日志。
遇到 429 先区分短期限流、共享池和真正耗尽,尊重可用的重试时间;余额未知既不是零也
不是无限。付费 API fallback 未获允许时停下或等待合规通道恢复,绝不静默切到付费。
还须检查套餐耗尽后 provider 是否会自动消耗购买的点数或信用额;没有可核实的收费边界时,
不能把该 route 当作保证只扣套餐的选择。
证据边界
命令的已核实版本与边界见接口参考;版本变化以现场 CLI 为准。
策略与静态检查不证明套餐认证、条款允许、
模型效果或实际执行成功;这些须分别由当前通道和任务结果验证。会话 hook 只在目标
runner 支持且获授权时使用,不默认安装或修改
个人配置。本技能不自动安装工具、登录服务、生成凭据或更改全局模型配置。
策略配置与跨项目接续日志
策略
全局策略为 XDG_CONFIG_HOME/task-delegation/policy.md。只有 XDG_CONFIG_HOME 是绝对
路径时才用它;未设置或相对路径时退回 ~/.config/task-delegation/policy.md。主 Agent
在首次启用时先与用户协商策略示例中的实际选择,再直接写 Markdown。
已存在的文件不覆盖;用户要求修订时针对既有内容修改。Markdown 是给 Agent 阅读的偏好与
边界,不是运行时强制器;项目规则、本次授权及工具权限继续约束执行。
接续日志
所有项目共用 XDG_STATE_HOME/task-delegation/delegations.jsonl;只有 XDG_STATE_HOME
是绝对路径时使用它,否则退回 ~/.local/state/task-delegation/delegations.jsonl。
主 Agent 在实际委托时写短事件,便于跨项目找到原任务和接续位置。事件至少包含带时区
时间、短描述、项目、runner、状态与稳定 task_ref;Herdr Agent 名、pane ID 和 runner
自身 session ID 各自独立。日志不存任务全文、凭据、完整地址或账户资料。
可用本技能的最小 helper 追加事件。先把 SKILL_DIR 设为实际安装的本技能目录;以下
只展示调用形状。task_ref 省略时 helper 生成本地 UUID 并只打印该 UUID,主 Agent
应保存它供后续事件复用:
python3 "$SKILL_DIR/scripts/log.py" --project PROJECT --description '简短任务描述' --runner RUNNER --status started --herdr-agent NAME --herdr-pane PANE_ID
可选 --runner-session-id ID 只有在 runner 确认后传;未知时日志写 null 与
session_state: pending,确认后用 --task-ref UUID 追加同一任务的事件,不回填或改写旧行。
这里的 pending 仅表示 helper 未收到非空 ID;有意使用 --no-save 等不保存会话时,
主 Agent 在简短状态或描述中注明不可恢复,读日志时据此不安排补查或恢复。
--log ABS_PATH 只供隔离测试或明确覆盖日志目标。Herdr 的 pane 是终端位置,不能作为
runner 可恢复会话;agent get 的 agent_session 只有在集成真实报告后才可用。
helper 使用 POSIX fcntl 锁,适用于 macOS/Linux;未验证 Windows 支持。
使用 Fx 薄适配器时,适配器用同一 task_ref 为每轮追加简短状态及确认的
Fx session ID;主 Agent 不要再为同一轮重复写一条等价事件。Fx 的详细回执保存在
私有状态目录,用 task-delegation-fx-bridge inspect --task-ref UUID 查看摘要,
全局日志仍只记录定位和状态。
状态事件描述已观察的进度,不能代替验收。失败、超时或 blocked 时保留原任务标识,
先查现场与产物,不盲目重派;交付后日志只追加简短结果状态,验证依据留在原任务回执
或产物中。没有真实委托时
不制造日志事件。
Fx:单次调用与 Herdr 多轮委托
Fx 可以是短任务的轻量候选;“更快”仍须用相同任务条件下的端到端耗时、质量和失败率验证,
不能由 runner 名称推断。先按主技能的策略确认任务能力、当前认证与计费通道。Fx 的
认证说明列出 Codex/Grok 套餐登录及
AI Gateway 的账户或 API 凭据;安装或选择 provider 都不证明当前请求会扣套餐。
FX_PROVIDER 和 --model 可为单次请求选 provider/model;检查当前身份和 Gateway 的
fallback 后再用。--ultrafast 属更高价格档,不能未经付费授权启用。见
fx ask。
一次性任务:按进程与 JSON 回执收结果
在已安装、已认证且任务允许的环境中,主 Agent 可从项目工作目录运行
printf '%s' "$TASK" | fx ask --json --model "$MODEL";MODEL 与 TASK 必须先按策略
确定。本机 Fx 0.0.14 的 ask --help 确认无 prompt 参数时可从 stdin 读取任务文字;
这样任务正文不进入 Fx 进程 argv。管道输入无法回答交互审批,需审批的任务改用合适的
交互执行方式。
它是一次非交互请求,结束即退出。检查进程退出码和 JSON exit_code,再读
final_output、session_id、错误与产物;final_output 可能为空,成功退出也不代替
任务验收。需要后续接续时保留实际返回的 session_id,按
会话文档用 fx ask --resume ID 或
fx resume ID,可用 fx sessions --all、fx session ID --json 查证。
有意使用 --no-save 时 session_id 为空且不可恢复;按全局日志
保留空的 runner session ID,并在简短状态或描述中注明不可恢复,不安排后补。
只有预期保存但回执暂未知时,才将缺失 ID 记为 pending 并尝试补查真实 ID;
不拿 Herdr pane ID 或自造 ID 顶替。
fx ask --json 要交互审批时须在真实终端中显式使用 --prompt-permissions;管道或重定向
输入不能接收审批提示。不要假设短命进程可提供持续的 blocked 状态;进程退出后也不能
向它 agent prompt。在 Herdr 中用已核实的 herdr pane run PANE_ID COMMAND... 只能
启动普通 pane 命令,不会因此获得 Agent 生命周期;pane read 读的是终端文本,
agent wait 的状态也不是结果验收。若需要稳定的结构化 JSON,直接捕获 Fx 子进程的
stdout 与退出码,而不是把 pane run 的确认回执当成 Fx 结果。见
Herdr 智能体自动化。
多轮任务:使用薄适配器
Herdr 0.9.5 的 agent start --kind 没有 fx。本技能的
scripts/fx_bridge.py 提供 task-delegation-fx-bridge 命令入口:它在 Herdr pane 中
长驻、逐行接收终端输入,每轮调用一次 fx ask --json,然后继续等待下一轮。Fx CLI
子进程可以结束,但适配器必须继续运行,Herdr 才有可等待和可恢复的当前 Agent。
此脚本使用 POSIX 文件锁和进程组;在其他操作系统部署前须核对或适配这些接口。
安装或链接这个入口须由主 Agent 按当前任务授权完成,且目标 pane 的 PATH 与
Herdr 恢复后的 PATH 都必须能找到同名命令。源码存在不表示入口已安装;先在目标
环境核对 command -v task-delegation-fx-bridge,并确认该命令解析符号链接后指向
本次运行的同一个适配器脚本;否则不能登记 Herdr 恢复 argv。不要写
agent start --kind fx。
先按策略核对 provider、精确模型、认证、套餐与 fallback,确认适配器会继承的 Fx 配置。
start 可选 --fx-home ABS 指向已有 Fx 配置家目录、--fx-bin ABS 指向已安装的
Fx 可执行文件;--no-additional-dirs 限制额外工作目录。新任务默认给 Fx 子进程最小
环境;只有核实目标通道确需并允许继承环境中的认证或其他变量时,才显式使用
--inherit-fx-env。已有任务恢复沿用启动时保存的环境模式。最小环境不保证每种通道
都能认证成功,继承环境也不能替代项目上下文与工具权限检查。
恢复会记住这些路径、provider 和模型,但配置文件以后
可能被人修改,因此接续前仍要重新核对实际路由。
以下使用 --current 的创建示例仅适用于主 Agent 已在真实 Herdr pane 内;从外部终端
控制时须获得授权,在每条命令显式指定已核对的 --session 与目标 pane,不能隐式选默认
会话。无论控制命令从哪里发,适配器 start/resume 都必须实际运行在 Herdr pane 内。
从创建结果 .result.pane.pane_id 取得真实 ID,等待该 pane 到 shell prompt 后再启动。
以下是命令形状,PROJECT、DESCRIPTION
与 MODEL_ID 换成已核实的值,动态文字须按 shell 规则安全引用,不把任务全文写到
--description 中:
herdr pane split --current --direction right --cwd "$PWD" --no-focus
# 仅在创建成功后,从返回 JSON 的 .result.pane.pane_id 取 PANE_ID 并核对目标 pane。
herdr pane run "$PANE_ID" \
"task-delegation-fx-bridge start --project PROJECT --description DESCRIPTION --provider PROVIDER --model MODEL_ID"
herdr pane wait-output "$PANE_ID" --match FX_BRIDGE_READY --timeout 30000
herdr agent get "$PANE_ID"
herdr agent read "$PANE_ID" --source recent-unwrapped --lines 40
pane run 只确认命令已送入终端;wait-output 也可能匹配旧 scrollback,因此需检查
刚启动的前台进程和最新输出。等适配器上报 idle,并从终端的
FX_BRIDGE_READY 行读取真实 task_ref 后,才准备完整任务;任务中仍要交代
目标、范围、上下文、产物与验收。encode 从标准输入接收一行 UTF-8 任务文字,拒绝
原始换行、回车与控制符,再输出 : FXB1_... 封套。为避开 macOS PTY 的单行限制,
封套最多 900 个 ASCII 字节;超限时缩短任务文字,改给经过授权、目标 runner 可读的
文件路径与具体范围。Herdr 0.9.5 只把此适配器的自报告用于状态展示,
agent prompt 仍要求原生识别的前台 Agent,不能给自报告的 Fx 提交任务;改名也不会改变
这一检查。用 pane run 将编码后的单行封套和 Enter 一次送到当前适配器,再按本轮标识
等回执:
TASK_REF=ACTUAL_UUID # 从 FX_BRIDGE_READY 读取,不自行生成
NEXT_TURN=1 # inspect 的当前 turn + 1
TASK_TEXT='一行内写清目标、范围、产物和验收'
if WIRE=$(printf '%s' "$TASK_TEXT" | task-delegation-fx-bridge encode \
--task-ref "$TASK_REF" --turn "$NEXT_TURN"); then
herdr pane run "$PANE_ID" "$WIRE"
else
printf '%s\n' '编码失败:没有提交任务' >&2
fi
编码成功且 pane run 已提交后,等待本轮回执;提交结果不确定时先查 pane 与 inspect,
不要重发:
herdr pane wait-output "$PANE_ID" --source recent-unwrapped \
--match "FX_BRIDGE_RESULT {\"task_ref\":\"$TASK_REF\",\"turn\":$NEXT_TURN," --timeout 120000
task-delegation-fx-bridge inspect --task-ref "$TASK_REF"
herdr agent get "$PANE_ID"
封套只使用 shell 安全字符,前面的 : 是 shell 空操作;即使适配器在检查与提交之间
退出,落到 shell 的这一行也不会执行任务正文。适配器只接受匹配当前 task_ref 与下一
轮次的封套,拒绝原始任务文字和旧封套。编码并不加密,仍不可借此传递凭据或越权内容。
encode 须与目标适配器使用同一用户状态目录,且仅在其状态为 idle 时生成封套。
pane run 的成功回执只表示文本已送达终端;pane wait-output 会先搜索已有 scrollback,
所以每次都用实际 task_ref 和预期 turn 匹配,不能只等泛用的 FX_BRIDGE_RESULT。
等待超时先查 inspect 与 pane 输出,确认当前轮是否已提交或完成,不自动重发。
适配器将精简的 FX_BRIDGE_RESULT 印到 pane,不把模型正文复制到终端摘要;
私有状态文件存 Fx 的 JSON 回执,inspect 读取最近一轮状态与 final_output。
确认进程退出码、JSON exit_code、final_output、
真实 session_id 与产物,再按任务验收,不能仅凭 Herdr 的 idle、done 或
pane wait-output 认定完成。agent wait 不跟踪独立轮次,已有其他轮次在运行时尤其
需要核对 task_ref 与回执。
适配器只在 Herdr 确认环境变量齐全时自报,使用不与内建 adapter 冲突的稳定 source
和递增 seq。真开始 Fx 请求时上报 working;成功回执落盘且适配器可接收下一行时
才上报 idle。任一轮失败会保存回执、上报 unknown 并退出;此时必须用 inspect
查原因,不可自动重发。resume 遇到已记录的失败轮次会拒绝恢复;检查回执和可能的
实际副作用后,确需继续时显式加 --ack-failed-turn,它不会自动重发上一轮。
不能可靠判定审批或提问时不虚报 blocked。Fx CLI 的非交互审批限制
仍然存在;需要人决策的任务应选支持可观察审批的执行方式。Herdr 上报使用短超时,
不应让本地状态服务故障阻塞 Fx。仅显式 /exit 会调用 release-agent;异常退出与
Herdr 服务停止时不会由适配器主动清除恢复信息,但不能因此推断 Herdr 已保存或自动恢复成功。
轮次超时会尽力终止 Fx 的进程组并保存 turn_timeout 回执;自行脱离该进程组的后代
可能继续运行。状态不确定时先核实实际产物和费用,不自动重发。
会话接续与日志
首次提交前没有 Fx session ID;只有回执实际取得非空 session_id 后,适配器才通过
Herdr 报告原生 ID 和 task-delegation-fx-bridge resume --task-ref UUID 恢复 argv。
若 Fx 回执没有 session ID,适配器记录 fx_session_missing 并退出,不继续发下一轮,
以免悄悄新建对话;这时先核查私有回执和真实 Fx 会话,不能自行补造 ID。
这个命令重进适配器,重新使用已记录的 provider、精确模型与 Fx 配置目录,再用
fx ask --resume-id ID 接续;不能把 pane ID 或自造 ID 当 Fx session,也不能把
裸 fx resume 当成 Herdr 适配器。Herdr 恢复 argv 首词须是 PATH 中的普通命令名,
参数不能含撇号或控制符,最多 64 项、8 KiB;用户也可能在 Herdr 配置中禁用自动恢复。
Herdr 停止与重启后的自动恢复须在独立会话实际观察新适配器、原生 ID 和下一轮回执;
保存的 argv 或 mock 不能证明成功。具体合同见官方自接入文档与
会话恢复说明。
若旧适配进程确已退出而 Herdr 没有自动恢复,可在新的空 shell pane 中手动运行
task-delegation-fx-bridge resume --task-ref ACTUAL_UUID,再检查 FX_BRIDGE_READY、
agent get 和下一轮回执;不要同时在两个 pane 续写一个 task_ref。
适配器使用跨项目日志追加简短的轮次状态和真实 Fx session ID,
主 Agent 不必再为同一轮手动写一份日志。日志与 pane 的 task_ref 相连,不保存任务
全文或凭据。inspect 是离线回执读取,不会重新提交 prompt;已有任务不确定时先查它。
显式 /exit 会释放 Herdr 当前 Agent 与其自动恢复命令;只在旧进程确已退出且
仍有有效 Fx session 时才手动启动 resume --task-ref UUID,避免两个适配器同时写同一任务。
本参考描述的是薄适配器与 Herdr 的实际接口;Mock 报告只验证适配器的自报告调用形状,
不能替代真实 pane 的启动、等待、回执与重启恢复测试。Fx 的
SDK instrumentation不是 CLI 生命周期 hook,
不应把其他 runner 的 hook 配置复制给 Fx。
Herdr 与 Magpie 的已核实接口
此页记录 2026-10-22 核对的 Herdr 0.9.5、Magpie 0.1.1321、Fx 0.0.14
与 Claude Code 2.1.306 CLI 帮助快照,以及 Pi/Fx 官方文档。版本只标明命令证据,
不代表别的主机已安装这些 runner。
使用时复核现场版本、配置与产品条款;命令语法成立不代表当前账户已登录、
套餐可由该 runner 调用,或调用不计费。以下检查本身不发起模型任务。
只读预检
herdr --version
herdr agent start --help
herdr agent prompt --help
herdr pane report-agent --help
magpie models codex
magpie accounts codex --json
magpie quota codex --json
codex --help
command -v claude
command -v pi
command -v fx
fx ask --help
示例中的 codex 同时是该环境的 Agent 名和 provider ID;换环境时,magpie models
与 magpie accounts 的参数须用现场 Magpie agent 名,magpie quota 的参数须用现场
provider ID,不能假定两者同名。再逐个核对可见模型、账户与额度。
magpie models [agent] 给出 provider/model 候选;magpie accounts [agent] --json 是
登记和用量线索;magpie quota [provider] --json 返回可读取的配额窗口。三者都不单独证明
目标 runner 当前认证、实际扣费路径或任务能力;读取失败也不能推断额度耗尽。命令输出
可能含个人账户信息,勿原样写入任务 prompt、日志或报告。magpie healthcheck 只检测网关
应答,不测试某模型认证;隔离环境中本地 TCP 被阻止时,状态仍未知。
Magpie 的 magpie <agent> <model>、magpie use <profile>、magpie group add/set/rule
和 provider fallback 配置会影响持久路由,不是一次委托的临时参数。现有 group 也可能含共享池、
付费成员或自动 fallback;选择前须检查其实际成员和当前策略。Herdr agent start 的 kind
列表含 pi、claude、codex、gemini、cursor 等,不含 magpie 或 fx。
本机 Herdr 支持某 kind 不意味着对应 runner 已安装。Magpie 是模型访问与路由层,
不是 Herdr Agent kind。
单次启动与交接示例
以下 --current 示例只能在 HERDR_ENV=1 的真实 Herdr pane 中使用。主 Agent 若从外部
终端控制,须先取得该操作授权,在每条命令显式指定目标 herdr --session SESSION 和已核对的
pane;不能依赖隐式默认会话或冒用 Herdr 环境变量。此例的 MODEL 必须由当前 Codex CLI
识别,且其路由与认证已核对;不能把任一 Magpie 目录 ID 直接套入。不要原样使用示例 Agent
名,先确认同一 Herdr server 中唯一。
if [ "${HERDR_ENV:-}" = 1 ]; then
herdr pane split --current --direction right --cwd "$PWD" --no-focus
else
printf '%s\n' 'This command requires a Herdr-managed pane.' >&2
false
fi
只有上条成功创建 pane,才从返回 JSON 的 .result.pane.pane_id 取得 PANE_ID;
等待新 pane 到交互 shell prompt,再继续以下命令。此 --current 示例在非 Herdr 环境
或创建失败时停止;不要改用聚焦 pane 或默认会话执行。获授权的外部控制另按已核实的
--session 和目标 pane 操作。
herdr agent start worker_name --kind codex --pane PANE_ID -- -m MODEL
只有 agent start 成功识别到新 Agent,才提交任务;失败时检查 pane 与 runner,
不可把 prompt 发给可能已占用同名的旧 Agent。下面的 agent prompt 仅适用于 Herdr
原生识别的前台 runner;自报告的 Fx 薄适配器不满足此条件,须按
Fx 接入参考先编码成 shell 空操作封套,再用 pane run 提交并按轮次核对回执;
不要直接把任务正文送进 pane。
herdr agent prompt worker_name '目标、范围、上下文、产物与验收写在这里' --wait --timeout 120000
herdr agent get worker_name
herdr agent read worker_name --source recent-unwrapped --lines 120
codex --help 证实 -m, --model <MODEL> 是单次启动选项;claude --help 对应
--model <model>。换 runner 时应复核自身参数及它对目标 route 的支持。agent start
要求现有 pane 已在交互 shell prompt,成功只表示识别到 agent 可输入;提交 prompt 不等于
任务完成。agent prompt --wait 默认等待 idle、done 或 blocked,并不按 turn 跟踪;
被阻塞时输入会在发送前拒绝。stalled 或超时后先 agent get 与 agent read,因为 prompt
可能已交付,不能自动再发。进一步等待用 herdr agent wait worker_name --timeout 120000;
agent read 输出终端文本,其余控制调用通常返回 JSON,读取实际状态及标识,不猜测。
参考 Herdr 官方 Agent automation。
runner 会话与恢复
Herdr 的 pane_id 是终端位置,Agent 名是该 pane 当前占用者标识,都不能冒充 runner
可恢复的 session ID。herdr agent get 只有在相应集成实际报告后才可能包含
agent_session;未出现时记录 session pending,不要由 pane 或任务名推算。
Herdr 的集成和
session 状态还须按 runner 核实。
| runner | 当前可证实的单次选择与会话接口 | 边界 |
| Claude Code | 已安装版本的 --model <model>、--session-id <uuid>、--resume <id>;见官方 CLI与会话 | 预生成 UUID 只有成功建立且确认 session 后才能写为 confirmed;--resume 依真实 ID。Herdr kind=claude 可用,但不能仅凭 agent start 返回推断恢复 ID。 |
| Pi | 官方 --provider、--model、--session;--mode json 首条事件含 session.id,见CLI、JSON和会话 | 需在目标主机核对安装及版本。JSON 事件中的 agent_end 仍可能有后续自动工作;确认 agent_settled 才作本轮无自动后续的观察。Herdr 有 kind=pi,只在 runner 实际存在且交互方式兼容时使用。 |
| Fx | fx ask --json --model MODEL 返回进程结果和 JSON exit_code、final_output、session_id;本机 0.0.14 的精确续接选项为 fx ask --resume-id ID,见ask、会话、CLI | Herdr 没有 kind=fx,不能写 herdr agent start --kind fx。--no-save 没有可恢复 ID。单次走原生 CLI;需要 Herdr 管理多轮输入时使用Fx 薄适配器,由真实回执和自报告提供状态、结果与恢复。 |
会话 hook 不默认安装。只有普通 runner/Herdr 回执不足,且目标 hook 能解决真实 session
捕获或必要完成观察缺口时,才考虑接入;还须目标支持、项目允许、用户授权,并保留既有配置。
Claude 的 SessionStart可提供 session ID,
但 Stop、SessionEnd 都不是产物验收;Pi 使用不同的
extension,Fx 没有同类已核实的可靠 hook。
决策接口的真实边界
Magpie group ... effort=auto classifier=... 中的 Jev 为每轮推理档分类,不是已证实的
任务级模型/provider/runner 决策 API。Magpie 文档另有 /v1/systemone 决策端点,但本次
未验证本机网关可达、权限、请求格式与套餐计费路径;不得把它作为默认可调用接口。
Rossovia 的 Decision/Jev 是由宿主注入 HTTP transport、endpoint、model 与权限的实现,
Rossovia Assistant 的命令受其自身 grant 约束,均不是 Herdr 通用子命令。任何外部决策器
只有经当前环境核实接口、认证、权限、价格和输入数据边界后才可用;不满足时由主 Agent 选路。
可编辑策略示例
此页只帮助主 Agent 与用户讨论选路,不是待原样复制的默认政策。核实个人可用通道与偏好后,
由主 Agent 将商定内容写到全局策略位置。不记凭据、令牌、登录态、
完整账户资料或未经确认的订阅。已有策略要读取并保留,不覆盖。
硬边界
- 禁止:[准确的 runner / provider / route、禁止原因;包括决策器与执行器的 fallback。]
- 付费 API fallback:[默认不允许;如授权,写明条件、币种和每任务或周期预算。未设上限不等于无限。]
- 任务与环境权限:[项目规则与本次任务权限由其 owner 控制,策略不能扩大文件、网络或付费权限。]
套餐候选与当前可用入口
可记录用户声明拥有并允许考虑的套餐,但明确标为“待核实”;只有当前按官方方式确认
认证和计费的 route 才标为“可调用”。套餐原生 runner、官方授权的套餐集成与按量计费
API 分开。不要把订阅当作通用 API key,也不使用非官方代理绕过产品条款。
| runner | provider / 模型准确版本 | 通道与认证状态 | 共享额度池 / 限制 | 核实日期和来源 |
| [待协商] | [待核实] | [套餐原生 / 官方授权集成 / 付费 API;待核实] | 未知 | [待填写] |
同池不同 route 不算独立余额。额度未知既不是零也不是无限;429 先区分短期限流、并发限制
和明确耗尽,按可用重试时间决定等待或改选。
偏好与任务适配
- 默认 runner 与理由:[协商后填写;说明工具、上下文、恢复、隔离、质量/延迟和用户偏好,非所有任务的硬指定。]
- 备选 runner 与触发条件:[协商后填写;说明何种能力缺口、等待或失败才改选,以及共享额度池和付费边界。]
- 优先:[用户偏好的 runner / provider / 模型 / 套餐;前提是满足任务能力与授权。]
- 避开:[低优先级及例外条件。避开是偏好,不等同禁止。]
- 质量、延迟、成本:[哪些任务要更高可靠性,哪些可由较轻量 runner 完成;可接受截止时间。]
- 工具、上下文、恢复与隔离:[执行任务必须具备的能力与验收方式。]
- 保留余量:[需要为交互或关键任务保留的共享池余量;不以耗尽套餐为目标。]
- 决策器:[可用且授权的 decision API / Jev 路径及计费;不可用或只剩未准许付费路径时主 Agent 直接选。]
初始化及模型、runner、套餐、条款或任务类别变化时,刷新相关目录、官方能力与费用资料,
记录版本、runner 推理档、来源日期和不确定处。一次失败是修正证据,不永久拉黑。
任务与模型选路
使用当期证据,不写固定榜单
先从实际 Magpie 目录和 runner 能识别的 route 找候选,再逐个查该候选 provider 当期官方
模型能力、上下文、价格与使用条件;不要从固定厂商清单或旧型号榜单反推候选。
Models.dev 可帮助发现 ID、上下文和价格候选,但聚合条目不是当前
账户权限、官方费率或质量排名的证明。
性能可参考 Artificial Analysis 模型测量及其
方法,编码任务可参考
SWE-bench 官方榜。记录评测日期、测试集与 harness;综合分数
不自动适用于具体任务或 runner。保留当前任务的成功/失败与端到端延迟作为后续修正证据,
一次失败不永久拉黑 route。没有可比实时数据时写明不确定,不捏造排名。
按顺序判断:
- 能力门槛:任务类别、工具调用可靠性、所需上下文、恢复路径、工作目录隔离、
语言或多模态能力、权限与输出格式;不满足者即使免费也不入选。多轮长任务尤其要先
核实 session ID 与可恢复方式,Herdr pane ID 不是 runner session。
- 通道门槛:当前 runner 识别 route,当前认证身份与官方允许的计费路径已核实。
已有套餐优先,但套餐声明不是当前认证,也不是可在任意 API 使用的凭据。官方支持的
套餐集成须经用户主动授权;私有代理或绕过条款的转接不作候选。
- 权衡:遵循用户偏好,默认从能满足能力、质量与延迟门槛的较轻量 runner 起选,
不固定 Claude、Pi、Fx 或最轻模型。合格者比较预计端到端延迟、可用额度和边际成本。
已付合规套餐优先,仍要为关键任务保留合理余量。共享套餐池只算一次;
窗口、并发、速率和剩余用量未知时保持未知,不假设无限。选路模型调用也计入成本和额度。
- 决策记录:写出 route(runner、provider、模型准确版本、推理档)、选择理由、查证
日期与来源、已知共享池与用量限制、预计付费影响及不确定处。不要按旧型号名单自动选。
对现有 group 或 fallback,检查其每个成员是否都满足禁止与付费限制;Magpie 的自动切换
不能替主 Agent 审核。429 可能是短期限流、并发限制、共享池窗口耗尽或 API 支付/认证问题,
须按返回错误及 Retry-After 分类;不同 route 若共用同一池,不是有效的额度 fallback。
套餐耗尽后,provider 也可能在同一 route 自动消耗购买的点数或信用额,无需切换
gateway fallback。严格禁止额外付费时,还要核对 provider 侧的续扣规则与可执行的硬上限;
无法核实或限制时,不能宣称此 route 只耗套餐,改用已核实的候选或返回阻塞。
预算或付费 API fallback 未获允许时,等待明确重置、改用已核实的合规候选或返回阻塞。
当模型、runner CLI、套餐/计费条款、目录、任务类型变化,相关证据过时、反复失败或遇
429 时刷新受影响项;无需每轮全网重搜。具体套餐读当前官方条款,尤其区分 Codex 等
原生订阅、官方授权的第三方套餐共享
与普通 API 计费。Claude Code 认证说明
及 Cursor CLI 认证说明展示同一 runner
可能有不同登录方式,不能从工具名称推断收费方式。