Prime Agent 日常使用完全指南交互模式、Slash 命令、会话管理与自主运行【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agentPrime Agent 是一个面向编码工作流与长时间自主任务的 RLMRecursive Language ModelAgent。它围绕唯一一个面向模型的内置工具——持久化 Python REPL 内核——构建同时由 TypeScript 宿主负责提供商调用、会话状态、工具执行、调度与子代理生命周期。本文以 usage.md 为核心系统讲解 Prime Agent 的日常使用方法从交互界面四大区域、编辑器技巧、全套 Slash 命令、消息队列与会话管理到递归子代理、上下文文件、会话导出以及完整的 CLI 参考与自主autonomous模式预算机制帮助你在阅读结束后能够熟练完成会话创建、模型切换、上下文压缩、任务委派与无人值守的自主运行配置。整体架构一个工具组合出整个运行时在深入日常操作之前先理解 Prime Agent 的架构定位面向模型暴露的工具面保持极小而 Python REPL 运行时保持强大与可组合。内置的ipython工具提供跨轮次保留的 Python 状态durable state项目命令执行Python 技能skillsMCP 支撑的集成MCP-backed integrations原生的rlm委派 API——支持递归子代理。这些能力并不会各自暴露为独立的模型工具而是统一收纳在同一个 REPL 工具内。设计原则见 usage.md 的 Design Principles 一节还强调递归子代理是核心能力而非可选扩展TypeScript 宿主拥有每一个父代理与子代理循环递归复用同一套提供商、会话、工具、技能、调度、用量统计与恢复基础设施Python 的rlm包只是宿主的薄桥接层并非独立的代理实现。扩展extensions、技能skills、提示模板prompt templates、主题themes与 Prime Agent 包则是主要的定制面。交互模式界面Prime Agent 的默认模式是交互式 TUI。界面包含四个主要区域启动头部Startup header——紧凑的品牌与运行时摘要使用--verbose时还会列出加载的上下文文件、提示模板、技能和扩展消息区Messages——用户消息、助手响应、工具调用、工具结果、通知、错误以及扩展 UI编辑器Editor——输入区域底部栏Footer——默认为空使用/usage可查看 token、成本与上下文详情。编辑器可以被内置 UI如/settings或自定义扩展 UI 临时替换。启动头部中加载的 Context/Skills/Prompts/Extensions 分组合并了AGENTS.md、SKILL.md、提示模板与扩展的路径信息便于快速确认运行时装配了哪些资源。编辑器功能速查功能操作方式文件引用输入模糊搜索项目文件路径补全按 Tab 补全路径多行输入ShiftEnterWindows Terminal 上为 CtrlEnter图片CtrlV 粘贴Windows 上为 AltV或将图片拖入终端Shell 命令!command运行命令并把输出发送给模型隐藏 Shell 命令!!command运行命令但不把输出发送给模型外部编辑器CtrlG 打开$VISUAL或$EDITOR全部快捷键与自定义方式见 Keybindings。Slash 命令在编辑器中输入/会打开命令补全。扩展可以注册自定义命令技能以/skill:name形式可用提示模板通过/templatename展开。从源码看内置命令定义于 slash-commands.ts其中/usage是/context的别名/side是/btw的别名/clear是/new的兼容别名/thinking是/effort的别名/rename是/name的别名。会话级命令/compact、/refine、/goal、/autonomous被标记为execution: session由会话侧解析执行。命令描述/login,/logout管理 OAuth 或 API-key 凭据/model切换模型/effort设置推理/思考级别/scoped-models启用/禁用用于 CtrlP 循环切换的模型/settings思考级别、主题、消息投递、传输方式/resume [id\|path]打开 agents 视图或直接恢复某个会话/new开始新会话/name name设置会话显示名称/session显示会话文件、ID 与消息计数/traces [status\|on\|off\|preview\|upload-current\|upload-all\|login]预览、上传或管理可选的 trace 共享/usage,/context显示父代理与子代理的上下文、token 与成本明细/tree跳转到会话中任意位置并从那里继续/fork从之前的某条用户消息创建新会话/clone把当前活动分支复制到一个新会话/compact [prompt]手动压缩上下文可选携带自定义指令/refine [instructions]精炼或回滚会话支撑的 harness 状态/copy复制最后一条助手消息到剪贴板/btw question,/side question提出一条内联侧问不写入会话回复继续侧对话Esc 返回/export [file]将会话导出为 HTML/share作为私有 GitHub gist 上传附可分享的 HTML 链接/reload重新加载按键绑定、扩展、技能、提示与上下文文件/hotkeys显示所有键盘快捷键/changelog显示版本历史/quit退出 Prime Agent除上述之外源码中还有/fast切换 OpenAI Fast 模式、/import从 JSONL 导入并恢复会话、/mcp管理 MCP 连接、/system-prompt显示发送给模型的精确系统提示、/logs、/update、/fullscreen、/rlm-max-depth、/heartbeat、/heartbeats等命令均可在输入/后的补全列表中查看。消息队列在 Agent 工作时继续输入当 Agent 仍在工作时你可以继续提交消息Enter排队一条 steering 消息在当前助手轮次的工具调用全部执行完之后投递。AltEnter排队一条 follow-up 消息在 Agent 完成所有工作之后投递。CtrlC中断当前操作并短暂显示退出提示在提示可见时再次按 CtrlC 退出。已排队的消息会被保留在你下次提交或编辑后继续。Escape清空输入栏而不中断 Agent。AltUp / AltDown逐条浏览已排队的消息并可回到未改动的草稿。浏览时Enter把编辑应用为 steering 输入AltEnter应用为 follow-up提交空编辑会删除该项。CtrlOptionUp / CtrlOptionDown在各自队列内把选中项上移/下移。在 Windows Terminal 上 AltEnter 默认是全屏快捷键。如果你希望 Prime Agent 收到该快捷键按 Terminal setup 中的说明重新映射。消息投递方式可在 Settings 中通过steeringMode与followUpMode配置两者默认均为one-at-a-time可选all或one-at-a-time同节中的transport设置控制多传输提供商的首选传输方式sse、websocket或auto默认sse。会话管理会话自动以扁平 JSONL 文件形式保存在~/.prime/agent/sessions/下。每个会话头部记录其工作目录会话选择器据此提供项目级作用域视图。prime-agent -c # 继续最近的会话 prime-agent -r [path|id] # 浏览会话或直接恢复一个 prime-agent --no-session # 临时模式不保存 prime-agent --fork path|id # 把会话派生到一个新会话文件常用会话命令/session显示当前会话文件与 ID。/usage显示 token、成本与上下文使用量。/tree导航会话文件内的会话树并可总结被遗弃的分支。/fork从更早的一条用户消息创建新会话。/clone把当前活动分支复制到一个新会话文件。/compact汇总较早的消息以释放上下文。更深入的会话格式与压缩机制见 Sessions 与 Compaction。Agent 与递归子代理常规交互会话是由隔离 worker 进程支撑的持久化 Agent。关闭 TUI 只会分离客户端用以下命令查找并重新挂接正在运行的工作prime-agent agents prime-agent list [--all] prime-agent attach agent prime-agent stop agent prime-agent shutdown [--force]prime-agent stop agent停止一个根 Agentprime-agent shutdown停止所有 worker 与本地 supervisor。在会话内部模型可以通过 Python REPL 中已可用的rlm对象进行委派# 生成独立的子代理。每次调用在准入admission时返回子代理句柄 # 永远不会直接返回子代理的答案。 review await rlm.spawn( Review authentication and reply to the parent with findings., nameauth-reviewer, ) tests await rlm.spawn(Find missing regression tests and reply to the parent., nametest-reviewer) docs await rlm.spawn(Find stale public documentation and reply to the parent., namedocs-reviewer) # 子代理从自己的会话中以如下方式回复 # await agent_message.send(message, receiver_roleparent) # 它们的回复会以普通 Agent 消息的形式到达这里。 # 恢复句柄并向保留下来的子代理跟进。 children await rlm.list_subagents() await agent_message.send( Also check authorization boundaries., receiver_rolechild, receiver_namereview.name, )子代理默认继承父代理的模型除非用户另行指定。它们以 TypeScriptAgentSession实例的形式运行在同一个根 worker 之下可以使用相同的提供商、工具、技能、会话存储与调度系统。运行时架构详见 RLM Runtime Architecture。上下文文件Prime Agent 在启动时会从以下位置加载AGENTS.md或CLAUDE.md~/.prime/agent/AGENTS.md——全局指令从当前工作目录逐级向上查找的父目录当前目录。用上下文文件存放项目约定、命令、安全规则与偏好。使用--no-context-files或-nc可禁用加载。系统提示文件用以下方式替换默认系统提示.prime/agent/SYSTEM.md——项目级~/.prime/agent/SYSTEM.md——全局。若只想在默认提示后追加而不替换可在上述任一位置放置APPEND_SYSTEM.md。导出与分享会话/export [file]把会话写入 HTML命令行对应prime-agent session export file [output]。/share以私有 GitHub gist 上传附可分享的 HTML 链接。CLI 参考prime-agent [options] [files...] [messages...]Shell 命令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 schedule list|add|cancel prime-agent status prime-agent doctor [--fix] prime-agent shutdown [--force] prime-agent package install source [--local] prime-agent package remove source [--local] prime-agent package list prime-agent package update [source] prime-agent update [--force] prime-agent config包源与安全说明见 Prime Agent Packages。运行模式标志描述default交互模式-p,--print打印响应后退出--mode json以 JSON 行输出全部事件见 JSON mode--mode rpc通过 stdin/stdout 的 RPC 模式见 RPC mode在 print 模式下Prime Agent 还会读取管道输入的 stdin 并合并进初始提示cat README.md | prime-agent -p Summarize this text模型选项选项描述--provider name提供商如anthropic、openai、google--model pattern模型模式或 ID支持provider/id与可选的:thinking--api-key keyAPI 密钥覆盖环境变量--thinking leveloff、minimal、low、medium、high、xhigh或max--models patterns逗号分隔的模式用于 CtrlP 循环切换使用prime-agent model list [search]列出可用模型。会话选项选项描述-c,--continue继续最近的会话-r,--resume [path\|id]浏览并选择会话或恢复指定会话文件/部分 UUID--fork path\|id把会话文件或部分 UUID 派生到新会话--session-dir dir自定义会话存储目录--no-session临时模式不保存工具选项选项描述--tools list,-t list白名单指定内置、扩展与自定义工具--no-builtin-tools,-nbt禁用内置工具但保留扩展/自定义工具--no-tools,-nt禁用全部工具内置工具为ipython。资源选项选项描述-e,--extension source从路径、npm 或 git 加载扩展可重复--no-extensions,-ne禁用扩展发现--skill path加载技能可重复--no-skills,-ns禁用技能发现--prompt-template path加载提示模板可重复--no-prompt-templates,-np禁用提示模板发现--theme path加载主题可重复--no-themes禁用主题发现--no-context-files,-nc禁用AGENTS.md与CLAUDE.md发现把--no-*与显式标志组合可以精确加载你需要的资源而忽略设置。例如prime-agent --no-extensions -e ./my-extension.ts自主Autonomous选项自主模式是一种面向无人值守工作的宿主策略默认关闭。--autonomous启用它提供任何--autonomous-*子选项也会同时启用它。宿主会在每次启用运行时以全新的 continuation、turn、token 与耗时计数器开始。交互式会话可通过/autonomous命令设置同样的预算/autonomous on接受上述所有预算选项使用去掉--autonomous-前缀的标志名--max-continuations、--max-turns、--max-tokens、--timeout-ms、--gate、--gate-retries、--gate-timeout-ms并兼容完整的 CLI 拼写作为别名。例如/autonomous on --max-continuations 10 --gate npm run check启用十次 continuation 的运行默认是三次。数值遵循同样的正整数规则可以使用--flagvalue或--flag value写法并接受,或_作为数字分隔符因此--max-tokens 100,000,000,000与--max-tokens 100_000_000_000均可。四个预算上限还接受unlimited以移除该上限。命名预算标志定义整个预算任何未命名的上限都会变为无限因此只有你传入的标志加上 gate决定运行何时停止——例如/autonomous on --max-tokens 100,000会一直运行到该 token 预算耗尽。如果完全不带预算标志则仍应用已配置或默认的上限。若一次运行的所有预算上限均为无限且没有 gate则没有任何自动停止点因此务必配合 gate 或显式的大预算使用。从源码实现autonomous.ts看默认上限常量DEFAULT_AUTONOMOUS_LIMITS与文档一致maxContinuations: 3、maxTurns: 12、maxTokens: 80_000、timeoutMs: 30 * 60 * 100030 分钟默认 gate 配置DEFAULT_AUTONOMOUS_GATES为无命令、maxRetries: 3、timeoutMs: 5 * 60 * 10005 分钟。token 计数只累计 input、output 与 cache-write token不计入 cache-read token见autonomousTokenDelta因为缓存读取是重复服务的高频上下文若累计计入会让长自主校验循环过早耗尽宿主侧 token 预算。选项行为、单位与默认值--autonomous启用自主 continuation。无 gate 时宿主持续请求工作直到某个上限阻止下一次 continuation。--autonomous-gate command添加一个必须在运行结束前通过的 shell 命令。可重复命令按 CLI 顺序执行默认无 gate。--autonomous-gate-retries n设置每个 gate 的重试上限。默认3。失败 gate 在已记录尝试次数不超过该值时仍可继续下一次失败尝试即耗尽该 gate。--autonomous-gate-timeout-ms n设置每个 gate 进程的超时毫秒。默认3000005 分钟。超时的 gate 判定为失败并终止其进程树。--autonomous-max-continuations n设置宿主注入的后续消息最大条数。默认3。--autonomous-max-turns n设置自主模式启用期间计数的最大助手响应数。默认12。--autonomous-max-tokens n设置累计 token 上限。默认80000计数包含 input、output 与 cache-write token但不含 cache-read token。--autonomous-timeout-ms n设置最大自主运行耗时毫秒。默认180000030 分钟。所有n值必须是正整数0、负数、小数与非数值都会被拒绝。带值的自主标志要求独立参数不接受--flagvalue形式。缺失值会被拒绝后续的长选项不会被当作值消费。重复数值标志取最后一次的值重复--autonomous-gate则追加另一个 gate。在每次助手响应之后配置的 gate 会先于普通 continuation 上限执行评估。所有 gate 必须全部通过运行才算完成。失败的 gate 会把有界的命令输出提供给下一次 continuation让 Agent 修复它Prime Agent 会避免重跑未变化的失败 gate而是推进其尝试计数。通过的 gate 即使在 continuation、turn、token 或时间上限已到的情况下也允许完成。若 gate 未通过或没有 gate宿主只有在四个上限均低于配置值时才能注入下一次 continuation。上限检查顺序为continuations、turns、tokens、elapsed time。达到任一上限都会阻止下一次自动 continuation但这并不代表任务成功。从源码的shouldAutonomouslyContinue与runAutonomousQualityGates可以看出更多细节gate 通过快照比较git worktree snapshot包含git status --porcelain、git diff HEAD与未跟踪文件 SHA-256 哈希来判定工作区是否自上次失败后发生变化若未变化则不再重跑该 gate 并直接推进尝试计数失败文本为 not rerun: workspace unchanged since previous failed gate避免空转。每个 gate 的输出会被截断到MAX_GATE_OUTPUT_CHARS6000 字符命令自身输出上限为 1 MiB超时进程树会被killProcessTree终止。例如下面这次非交互运行使用本地可用的模型配置、跳过启动期网络操作并约束所有自主预算同时要求项目检查通过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.--offline禁用启动期网络操作它不提供模型凭据也不会让提供商推理离线。请选择本地环境已配置好的模型。目标Goals与自主模式相互独立--goal objective仅为没有既有目标状态的新根会话启动一个持久化目标而自主模式决定宿主是否应注入下一次 continuation。--goal-token-budget n是该初始目标的正整数 token 预算且要求同时使用--goal。其他选项选项描述--cwd dir为会话指定工作目录--system-prompt text替换默认提示上下文文件与技能仍会追加--append-system-prompt text追加到系统提示--verbose强制详细启动输出--offline禁用启动期网络操作-h,--help显示帮助-v,--version显示版本--结束选项解析其后的所有参数都视为消息文件参数用前缀把文件包含进消息prime-agent prompt.md Answer this prime-agent -p screenshot.png Whats in this image? prime-agent code.ts test.ts Review these files示例# 带初始提示的交互模式 prime-agent List all .ts files in src/ # 非交互 prime-agent -p Summarize this codebase # 非交互 管道 stdin cat README.md | prime-agent -p Summarize this text # 切换模型 prime-agent --provider openai --model gpt-4o Help me refactor # 带提供商前缀的模型 prime-agent --model openai/gpt-4o Help me refactor # 带思考级别简写的模型 prime-agent --model sonnet:high Solve this complex problem # 限制模型循环切换 prime-agent --models claude-*,gpt-4o # 只保留内置 Python REPL 工具 prime-agent --tools ipython -p Review the code环境变量变量描述PRIME_AGENT_CODING_AGENT_DIR覆盖配置目录默认~/.prime/agentPRIME_AGENT_SESSION_DIR覆盖会话存储目录被--session-dir覆盖PRIME_AGENT_CODING_AGENT_SESSION_DIRPRIME_AGENT_SESSION_DIR的旧别名PI_PACKAGE_DIR覆盖包目录适用于 Nix/Guix store 路径PI_OFFLINE禁用启动期网络操作包括更新检查与包更新检查PI_SKIP_VERSION_CHECK跳过启动时的版本更新检查避免 release manifest 请求PRIME_AGENT_DOWNLOAD_BASE_URL覆盖 release manifest 与 tarball 的基址 URLPI_CACHE_RETENTION设为long以在支持处启用扩展提示缓存PRIME_API_KEYPrime Inference API 密钥当其带有agent_traces权限时也用于 trace 共享PRIME_AGENT_TRACES_API_KEY仅用于可选 trace 共享的 Prime API 密钥PRIME_AGENT_TRACES_BASE_URL覆盖 trace 上传 API 基址PRIME_AGENT_KERNEL_PYTHON使用已有的、装有prime-agent-runtime的 Python 环境而不是引导~/.prime/agent/kernel-venvVISUAL,EDITORCtrlG 使用的外部编辑器其余PI_*变量是当前运行时仍会读取的兼容名称。它们不会改变应用名、命令或默认的~/.prime/agent配置路径。设计原则小结把文档的 Design Principles 落到日常使用中可以概括为三条实践准则工具面小、运行时强模型面对的唯一工具是ipython文件操作、命令执行、技能、MCP 与rlm委派都由 REPL 运行时组合提供减少模型误选工具的可能。递归是一等公民子代理与父代理共享全部基础设施提供商、会话、工具、技能、调度、用量与恢复因此委派任务无需为子代理单独配置一套环境。定制走扩展面扩展、技能、提示模板、主题与包是主要定制入口可围绕内置运行时增加项目专属工作流、自定义工具与 UI、权限策略、提供商集成与编排模式。Prime Agent 保留了对其上游 pi-mono 血统的 MIT 署名但上游 Pi 的产品声明与局限并不描述当前 Prime Agent 的架构。进一步阅读快速开始设置与配置会话格式 与 压缩机制按键绑定RLM 运行时架构JSON 模式 与 RPC 模式Prime Agent 包【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考