@elpapi42/pi-fleet-sdk (英语)
创建并发现耐用,主机-本地的Pi代理.
npm install @elpapi42/pi-fleet-sdk
import { connectPiFleet } from "@elpapi42/pi-fleet-sdk"
const client = await connectPiFleet()
const agent = await client.create({
name: "researcher",
cwd: process.cwd(),
agentDir: "/home/user/pi-profiles/researcher",
env: {
RESEARCH_MODE: "schema-review",
EMPTY_OVERRIDE: "",
},
})
await agent.send("Investigate the database schema")
console.log(await agent.status())
await client.close()
piArgs 通过 Pi 选项。 Pi-fleet 添加( P) --mode rpc 和拒绝 --mode 财务报告和审定财务报表 --no-session。用户会话选择器仍然具有权威性:
await client.create({
name: "existing-session",
cwd: process.cwd(),
piArgs: ["--session", "/path/to/session.jsonl"],
})
Pi拥有会话查询,工作-指导选择,提示,以及失败. 呼叫者拥有的Pi会话选择者保持不变并具有权威性. 对于舰队拥有的会话,pi-fleet按其准确路径恢复了现有的物理会话. 如果 Pi 报告了会话路径和ID,但没有实现文件, pi-fleet 则会用持续会话ID重启,仍需要 Pi 报告准确的ID.
agentDir 是可选的不可变 Pi 配置。 跟经纪人不一样 cwd {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}还有水手 stateDir。当提供时,SDK从创建进程当前目录中解析,坚持绝对路径,并作为 PI_CODING_AGENT_DIR 给每个Pi孩子的启动、Pi康复和工人康复。 省略后,pi-fleet保留了今天所继承的Pi环境行为. 用户拥有配置创建,内容,证书,权限,共享,以及出错. Pi决定了证书优先级. 所选择的配置文件可以提供证书,从进程环境继承的提供者证书仍然可供Pi使用. Pi-fleet不复制或删除配置文件数据,改变信任,或将其作为沙盒处理. 项目 .pi 资源与项目或祖先 AGENTS.md 保持Pi自有行为.
env 是 SDK 唯一不可改变的 Pi 儿童配置 。 提供 Record<string, string> 在私人代理记录中长期存在,并在初始启动、Pi恢复和工人恢复期间适用。 Pi-fleet合并了继承的工人环境,然后 env,则 agentDir 页:1 PI_CODING_AGENT_DIR。地图必须是普通的或无效的原型对象。 密钥必须是非空并包含无 = 或无字节. 值必须是没有空字节的字符串 。 空字符串覆盖已继承的值 。 没有未设置或更新操作 。 变化中的环境覆盖需要销毁并再造该剂. 娱乐创造出新的不可改变的代理ID,并通过正常的破坏来去除旧世代的活动历史. PATH 财务报告和审定财务报表 PI_CODING_AGENT_DIR 保留和拒绝 env。 。 。 .
处理 env 作为可信任的本地进程配置,而不是秘密商店或沙盒。 Pi和它开始的过程可以继承它的价值观. 值是LMDB中的平正文字,可以留在进程环境和备份中. Pi-fleet不直接将环境配置添加到状态,列表或事件上,但Pi和工具可以读取值并将其纳入活动输出. 在验证错误、日志或测试输出中不要打印秘密值或用户提供的实际值。 在文档示例中只使用无害占位符 。 销毁会删除逻辑代理记录, 但不会安全地去除旧的 LMDB 页面或备份 .
默认情况下, pi- fleet 将它的 LMDB 环境和工人 IPC 套接字存储在 ~/.pi-fleet。稳定前释放不会自动从较早的地点迁移。 明确 stateDir 必须为生成的 Unix IP 套接字路径留下空间。 超长路径抛出 InvalidStateDirectoryError 在Pi-fleet创建状态之前. 过 stateDir 改为 connectPiFleet 只有当您需要明确位置时,例如孤立测试或本地高级设置时:
const client = await connectPiFleet({ stateDir: "/path/to/pi-fleet-state" })
client.get(name) 财务报告和审定财务报表 client.list() 发现另一个本地客户端创建的代理. client.close() 只关闭 SDK 客户端 。 它不会阻止代理工人.
运行的代理保持了创建时使用的工人版本. 在更新了SDK后,在测试工人康复等新的工人行为之前,先创建出一个新的代理. SDK 软件 0.12.2 删除 work.interrupted 从回放,所以由更古老的版本所创建的代理在升级后得不到支持,必须被销毁再被再创建.
agent.send(message) pi闲暇时开始工作。 在积极工作期间,它使用 steer 默认。 使用 followUp 在当前工作结束后交付:
await agent.send("Summarize the findings", { delivery: "followUp" })
send() 只有在 Pi 确认指令后才能解决。 在皮或出厂前工人康复期间,它等待修复和交付. 它不等待工作完成。 如果老工人可能接受了请求,但其承认却丢失了, AgentSendUncertainError 报告pi -fleet没有重新测试它.
agent.receive() 提供持久的语义活性流。 每个客户都收到独立的单一消费者流。 溪流报告 thinking.started, (中文(简体) ), thinking.finished, (中文(简体) ), message.started, (中文(简体) ), message.finished, (中文(简体) ), tool.started, (中文(简体) ), tool.finished,以及 agent.destroyed. . . . . 工人恢复在上次交付光标后重新连接,重放一次错过的事件,并继续进行直播. 健康的活流产量 agent.destroyed 然后,当所有者摧毁代理人时,通常结束。 当消费者停止或客户端关闭时,流也正常结束. 它会扔 AgentUnavailableError 如果有限度的恢复失败.
运行中的 Pi 运行时丢失会改变代理状态为粘滞 interrupted调用 agent.status() 来探测它. interrupted 工人或Pi准备就绪后和 send() 验收。 改为: working 只当Pi开始新发工作,然后 idle 当Pi和解. list() 是登记清单,可以暂时显示已失效 working 在未观察的工人损失之后。 Pi拥有普通工具故障和活模式或工具摊位.
每个事件都有不透明的 cursor,语义 eventId,一个 activityId 连接匹配的开始和结束事件, 以及一个由工人指派的 Unix- millisecond timestamp。流序是权威的。 时间戳不定义命令,并且 eventId 不是重放光标。 Pi-fleet项目Pi助理信封入语义活性:思考和只使用工具的信封不发出消息事件; message.started a. 在第一个非空白助理文本中发出;以及 message.finished.text 包含辅助文本块的最后非白空空间连接。 如果一个提供者只发送一个已完成的消息, pi-fleet 将发送一个匹配的消息开始并一起完成.
let cursor: string | undefined
for await (const event of agent.receive({ fromStart: true })) {
cursor = event.cursor
}
for await (const event of agent.receive({ after: cursor })) {
// Events after cursor, then live events.
}
平面 receive() 仅限直播。 它开始订阅第一个执行者读取,这样它就可能错过在工人承认之前承诺的活动. 使用 receive({ fromStart: true }) 当工作在接收器创建后立即开始,并且不能错过第一个活动. receive({ after: cursor }) 从光标后开始。 这些方案是相互排斥的。 光标的版本为不透明值,与一个不可变的代理ID相接. 无效、 错误的代理或未来光标 InvalidCursorError。 。 。 .
await agent.destroy() 无需确认。 它可以停止活动,立即删除代理名称,产量 agent.destroyed 然后去掉工人、皮、IPC套接字、代理记录和完整的事件记录。 拨打旧手柄然后抛出 AgentNotFoundError。重新创建此名称将创建一个新的不可移动代理ID.
tool.started.args 包含 Pi 的模型请求参数。 皮可以先验证或改造后再执行. 何时 argsTruncated 实值 true, (中文(简体) ), args 实值 null 因为所要求的参数超过 16 KiB.
tool.finished.output 包含有边框的最后文本、图像省略元数据以及可选的结构细节. detailsTruncated 报告省略了结构化的细节. truncated 报告任何省略或缩短的输出,包括图像数据。 语义事件从未包含基础64图像数据. 工人将文本输出限制在64 KiB,结构化细节限制在16 KiB. CLI 显示每个参数或输出预览最多 8 KiB . tool.updated 尚未提供.
在Pi恢复期间,工人最多持有32个发送和1个MiB的短信. AgentRecoveryQueueFullError 说明Pi没有收到被拒绝的指示. AgentSendUncertainError 表示Pi或老工人在确认丢失前可能已经接受了该指示,因此Pi-fleet不重试.
工具参数和输出可以包含敏感的本地数据. Pi-fleet不默地编辑此数据,因为编辑可以改变其意义. 相同的受限事件数据持续存在于 ~/.pi-fleet 直到主人打电话 destroy()。还没有过期或保留设置,所以磁盘的使用可以增加。 SDK消费者必须将事件历史视为具有与代理商及其Pi会话相同的本地信任级别.
切片 8 用 ZeroMQ 支持类似 Unix 的主机 ipc:// 支助。 它提供创建,获取,列表,状态,发送,持久接收,破坏,以及透明的皮和工人过程恢复. status, (中文(简体) ), send,以及 receive 通过附带条件的LMDB索赔,对无法工作的工人进行懒散调节. get 财务报告和审定财务报表 list 保持只登记操作。 回收从不显示持续存在的 PID 或 处理组; 它失败 AgentUnavailableError 如果旧的运行时间不 安全排出。 运行时间退休和收缩在初始产品之外.