Prime Agent 新手教程

长时任务与后台

终端关掉,活还在跑。daemon、心跳、持久目标与有界自主模式,构成了它的长时运行栈。

1后台代理:detach 而不是中断

持久会话跑在 worker 进程里,TUI 只是「接上去」的客户端。

普通交互会话由隔离的 worker 进程支撑:关掉 TUI 是脱离(detach),会话、Python REPL 状态、定时任务与子代理继续运行。日常管理就这七条命令:

prime-agent agents        # 浏览运行中 / 空闲 / 已保存的会话
prime-agent list [--all]  # 列出代理
prime-agent attach <agent>    # 重新接入
prime-agent stop <agent>      # 停掉某个代理
prime-agent rename <agent> <name>
prime-agent send <agent> <message>   # 给运行中的代理发消息
prime-agent status            # 后台服务状态
prime-agent doctor [--fix]    # 检查或修复后台服务
prime-agent shutdown [--force]  # 停掉所有代理、worker 与后台服务

注意 send:你可以直接给一个正在干活的代理「递纸条」——这就是最朴素的 agent-to-agent 通信入口,代理之间也能互相发现、互发消息、互相编排,不必事事经过用户。

2心跳与定时:让会话自己醒来

三种机制:交互式 /heartbeat、内核里的 rlm_heartbeat、以及命令行调度器。

  • /heartbeat:在 TUI 里给当前会话配置周期性唤醒;
  • rlm_heartbeat:Python 侧的宿主请求(经 rlm.host_request),代理可自己安排下一次醒来;
  • prime-agent schedule:在 shell 里管理定时任务。
prime-agent schedule list
prime-agent schedule add
prime-agent schedule cancel

典型用法:让一个「看护」代理每小时检查一次 CI 状态,发现红了就修——心跳唤醒、检查、汇报、睡觉,全程不需要人守着。

3持久目标:/goal

目标与其进度跨轮次保持活跃,直到完成、暂停或清除。

交互模式里 /goal 设定目标后,代理在后续每一轮都看得见目标与进度,不会聊几句就「忘了初心」。命令行也能起一个带预算的新目标:

prime-agent --goal "把仓库里所有 TODO 整理成 issue 清单" --goal-token-budget 200000
--goal 只对没有现有目标状态的新根会话生效;--goal-token-budget 必须配合 --goal 使用。目标与自主模式是两套独立机制:goal 管「要做什么」,autonomous 管「要不要自动继续」。

4有界自主模式:/autonomous

自动延续不是「放飞」——四重预算 + 质量门,全部可配置。

参数默认值含义
--autonomous关闭启用自主延续;无质量门时会一直请求工作直到触限
--autonomous-max-continuations3宿主注入的后续消息上限
--autonomous-max-turns12自主模式下的助手回复轮数上限
--autonomous-max-tokens80000累计 token 上限(含输入/输出/缓存写,不含缓存读)
--autonomous-timeout-ms1800000自主模式总时长上限(默认 30 分钟)
--autonomous-gate <cmd>无结束前必须通过的外壳命令,可重复追加
--autonomous-gate-retries3每个质量门的失败重试上限
--autonomous-gate-timeout-ms300000单个质量门进程超时(默认 5 分钟,超时算失败)

规则要点:所有数值必须是正整数(支持 , / _ 分隔符);四个预算可用 unlimited 单独解除;每次助手回复先跑质量门、再查延续预算,检查顺序为 continuations → turns → tokens → elapsed time。交互模式用 /autonomous on,参数可省略 --autonomous- 前缀。官方完整的非交互示例:

prime-agent -p \
  --autonomous \
  --autonomous-gate "npm run check" \
  --autonomous-gate-retries 2 \
  --autonomous-gate-timeout-ms 300000 \
  --autonomous-max-continuations 3 \
  --autonomous-max-turns 12 \
  --autonomous-max-tokens 80000 \
  --autonomous-timeout-ms 1800000 \
  --model openai/gpt-5.1-codex \
  --offline \
  --thinking high \
  "Fix the failing check and report the verified result."
重要认知

质量门通过只代表「这个门验证的东西通过了」;触达预算上限也不代表任务成功。把 gate 设计成贴近「任务完成」的可执行检查(如测试套件),才是自主模式可靠的用法。

Prime Agent 新手教程