agent 如何使用 Plexus

这页写给代理，也写给配置代理的人。前提是你已经完成连接：所有者已运行“连接代理”流程，授予你一组初始能力，并提供了一条带有一次性注册码的安装命令。如果还没完成，请先看连接一个 agent。

plugin 装好之后，你有且只有一个接口：一个按版本隔离、名为 plexus-<agentId> 的 launcher。它捆绑自己的引擎，并把你的 PLEXUS_AGENT_ID 写死在内——同一主机上的两个 agent 永不冲突，每个 launcher 各自锁定版本。调用路径上不存在全局的 plexus。

唯一的规则

启动器是你完整且唯一的接口。所有交互都必须通过 plexus-<agentId> … 完成。不要自行向网关发送 HTTP 请求，不要猜测认证请求头，也不要尝试签发或读取令牌。这条命令已封装获准使用的 enroll → handshake → grant → invoke 流程：如果某项操作无法通过这条命令完成，就说明这种执行方式未获授权，网关会拒绝这类尝试。

三个动词

plexus-<agentId> enroll —— 一次

plexus-<agentId> enroll <one-time-code>

这是首次运行时的初始化步骤，一键安装通常会替你完成。它用一次性注册码换取该代理专属的长期 PAT（plx_agent_…），由启动器自行保存到自己的主目录，文件权限为 0600；PAT 不会进入你的上下文。（如果你有自己的凭证管理习惯，可以设置 PLEXUS_PAT 环境变量，让启动器优先使用其中的凭证，而非已存文件。）注册码只能使用一次，兑换后即失效；此后，保存的凭证就是你的身份凭据。你只需运行一次，之后每个会话启动时都会复用启动器保存的凭证，完成认证。

plexus-<agentId> list — 查看能力

plexus-<agentId> list

操作前，先用这个命令查看能力。它只列出所有者授权给你的能力，分为三组：

• callable-now —— 你持有常驻授权，可直接调用。
• needs-approval —— 在你的授权子集内、但没有生效常驻授权的 capability：主要是所有者未开启常驻的带副作用（write/execute）capability（每次调用都会挂起、等所有者批准），以及已过期或已被撤销的授权。授权子集之外的请求会被直接拒绝，不会挂起。
• skills — 供你阅读并作为上下文参考的使用指南；plexus-<agentId> <id> 会输出指南，不会发起网络请求。

用 list 查看能力标识符，不要靠猜。它根据握手后下发的代理专属清单展示结果，列出的正是所有者授权给你的全部能力。

plexus-<agentId> <capabilityId> —— 用来调用

plexus-<agentId> workspace.read path=notes/plexus.md

按能力 ID 调用，以 key=value 对传入输入（输入结构较复杂时可用 --input '<json>'）。启动器会在后台完成整个 PAT → scoped token → invoke 流程，再把结果交给你；这些认证和调用步骤不会进入你的上下文。如果能力需要审批，调用会返回结构化的待审批状态，指向所有者的控制台——你不能自行签发令牌，任何错误信息也都不会建议你这样做。

为什么这样设计

有了启动器，你就不必操心底层通信协议的细节。它的认证与调用核心由对应代理类型的确定性模板生成，构建时会与 Floor 逐字节校验；这部分代码不由 LLM 编写，也不可能将越权的认证路径带入发布版本。你有权执行的所有操作，都能通过上面三个命令完成；其余操作，网关会按设计拒绝。

插件附带的 skill 是 Floor 的投影，不能取代 Floor。即使指南内容已经过时，实际能执行什么仍只由网关当前的授权决定。因此，你可以信任 list 的结果，直接据此操作。

深入了解

• 连接一个 agent —— 所有者一侧生成你的安装命令的流程。
• 编译模型 — 为什么由资源用你熟悉的方式引导你接入，而不是让你学习一套协议。