ai-sdk/harness-pi 适配器全解析在 AI SDK Harness 中内嵌 Pi 编码 Agent【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/aiai-sdk/harness-pi是 AI SDK Harness 体系中面向 Piearendil-works/pi-coding-agent的HarnessV1适配器它将 Pi 这一编码 Agent 以宿主 Node.js 进程内库的形式接入统一的HarnessAgent抽象使其能够在沙箱中读写文件、执行 shell 命令并调用自定义工具。本文基于仓库中该包的 CHANGELOG.md 与 README.md结合 pi-harness.ts、pi-session.ts、pi-auth.ts 等源码实现完整梳理它的架构原理、配置项、内置工具、认证与模型解析、会话生命周期与安全边界帮助你直接上手或将 Pi 集成进自己的 Agent 工作流。一、包定位Harness 家族中的 Pi 适配器从 CHANGELOG.md 的版本历史可以看到ai-sdk/harness-pi于 1.0.0 正式发布其源头提交3d9a50c同时实现了Claude Code、Codex、Pi三个编码 Agent 的 harness 适配器。它与 packages/harness公共抽象层和 packages/harness-claude-code、packages/harness-codex 属于同一批结构均遵循harness-v1规范。从 package.json 可以确认它的依赖关系ai-sdk/harnessworkspace 内公共类型与工具earendil-works/pi-coding-agent^0.84.3与earendil-works/pi-ai0.74.2Pi 本体pi-mcp-adapter2.12.1把 MCP 服务器适配为 Pi 扩展typeboxPi 侧工具参数描述与 zod 兼容层配合peer 依赖zod^3.25.76 || ^4.1.8Node 运行环境要求22。包的导出面非常克制index.ts 只导出createPi、默认实例pi等价于createPi()、VERSION、PiHarnessSettings与PiAuthenticationMode两个类型。也就是说用户不需要学习 Pi 专属 API全部通过createPi(settings)一个入口完成配置。二、核心架构Pi 在宿主进程内运行沙箱只做远端文件系统与 Shellai-sdk/harness-pi与其它编码 Agent 适配器最大的区别在于部署形态README.md 明确写道Pi runs in the host Node.js process and uses the sandbox as a remote filesystem shell — no bridge process is installed inside the sandbox.即Pi 本体跑在你的服务进程里不做进程桥接不需要在沙箱内安装任何 Agent 运行时沙箱sandbox仅作为远端文件系统 shellPi 的read/write/edit/bash/grep/find/ls等原生工具通过HarnessV1SandboxProvider的受限会话getRestrictedSandboxSession见 pi-session.ts落盘执行因此沙箱无需暴露任何端口ai-sdk/sandbox-vercel与ai-sdk/sandbox-just-bash均可直接使用这一点与依赖网络沙箱端口的其它适配器不同。架构上还隐含一个关键事实Pi 的进程内运行意味着它的默认资源发现会触及宿主开发者本机配置~/.pi/agent/*、~/.agents/*。为此适配器在创建DefaultResourceLoader时显式关闭了noExtensions、noThemes、noPromptTemplates见 pi-session.ts避免宿主个人扩展在服务进程中被加载执行只保留调用方显式传入的扩展工厂与受控技能。三、快速上手安装与最小可运行示例按 README.md 的 Setup 说明安装三个包npm i ai-sdk/harness-pi ai-sdk/harness ai-sdk/sandbox-vercel最小示例完整继承 README 的用法import { HarnessAgent } from ai-sdk/harness/agent; import { createPi } from ai-sdk/harness-pi; import { createVercelSandbox } from ai-sdk/sandbox-vercel; import { tool } from ai; import { z } from zod/v4; const agent new HarnessAgent({ harness: createPi({ thinkingLevel: medium }), id: demo, sandbox: createVercelSandbox({ runtime: node24 }), skills: [ { name: careful-refactors, description: Make minimal diffs and keep tests green., content: Prefer changes that touch the fewest files possible., }, ], tools: { deploy: tool({ description: Deploy a service., inputSchema: z.object({ env: z.enum([staging, production]) }), execute: async ({ env }) ({ url: https://${env}.example.com }), }), }, }); const session await agent.createSession(); try { const result await agent.generate({ session, prompt: Read README.md and summarise the goals., }); console.log(result.text); } finally { await session.destroy(); }要点createPi()返回一个HarnessV1对象specificationVersion: harness-v1harnessId: pi见 pi-harness.ts它只是HarnessAgent的一个配置片段会话创建后用try/finally保证session.destroy()避免泄漏宿主侧镜像目录与沙箱资源自定义工具如deploy通过HarnessAgent.tools注入会被翻译成 Pi 的 host tool 暴露给模型。四、createPi 配置项详解PiHarnessSettingsPiHarnessSettings在 pi-harness.ts 中定义共 6 个可选字段按用途分三组说明。4.1 auth认证来源与模式auth?: PiAuthenticationMode类型为HarnessV1Authenticationopenai | anthropic | custom见 pi-auth.ts。支持三种取值形态字符串模式openai、anthropic、custom、ai-gateway、auto默认值显式认证环境记录直接传入{ OPENAI_API_KEY, ... }这类记录适配器会为其构建隔离的凭据存储createIsolatedPiCredentialStorepi-auth.ts使认证完全与宿主进程环境解耦不传undefined走 Pi 本地的auth.jsonagentDir指向的目录或默认~/.pi/agent。各字符串模式从环境变量读取的凭据见resolvePiEnv与pickProviderEnvpi-auth.ts模式识别/使用的环境变量默认 Base URLopenaiOPENAI_API_KEY、OPENAI_BASE_URLhttps://api.openai.com/v1anthropicANTHROPIC_API_KEY、ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKENhttps://api.anthropic.comcustom所有*_API_KEY/*_BASE_URL结尾的变量及ANTHROPIC_AUTH_TOKEN依变量而定ai-gatewayAI_GATEWAY_API_KEY、AI_GATEWAY_BASE_URLhttps://ai-gateway.vercel.shauto优先 gateway其次回退到 OpenAI/Anthropic/自定义凭据同上在auto模式下只要环境中存在AI_GATEWAY_API_KEY就会注册vercel-ai-gatewayprovider 并路由全部推理请求否则回退到环境中能找到的其它 provider 凭据每个X_*_API_KEY会被映射为x-*形式的 provider id要求同时存在对应的X_*_BASE_URL。这一优先级顺序与 CHANGELOG 中83fe754将auth参数简化为字符串选择认证方式、e0d7cfb支持从隔离环境认证并移除旧版 auth 选项类型等条目一脉相承。另外无论哪种模式适配器都会在推理请求中携带User-Agent与x-client-app: ai-sdk/harness-pi/VERSION头PI_CLIENT_APPpi-harness.ts对应 CHANGELOG 中b2d0306与eeed977支持通过headers属性附加任意请求头。4.2 providers显式注册自定义模型 Providerproviders?: ReadonlyRecordstring, ProviderConfig按 provider id 显式注册 Pi 的模型与 API 协议ProviderConfig来自earendil-works/pi-coding-agent。适合“模型元数据与认证环境变量解耦”的场景例如通过 gateway 路由xai/grok-4.3这类第三方模型而不必为它单独准备环境变量。注册逻辑见 pi-session.ts会先继承ModelRegistry中该 provider 已有的配置再合并传入项。4.3 thinkingLevel思考预算档位thinkingLevel?: off | minimal | low | medium | high | xhigh | maxPiThinkingLevelpi-session.ts直接映射到 Pi SDKcreateAgentSession的thinkingLevel选项。CHANGELOG 中f7fa993专门修复了max档位在会话配置中的传递问题说明该选项完整覆盖了 Pi 的全部思考档位。4.4 agentDir复用 Pi CLI 的全局配置agentDir?: string对应 CHANGELOG81c3aa5为createPi增加agentDir选项以复用 CLI 配置指向存放 Pi 全局 Agent 配置auth.json、models.json、settings.json的目录。行为细节见 pi-session.ts提供时认证、模型注册表、通用设置全部复用该目录SettingsManager.create(hostWorkDir, agentDir)持久化到磁盘未提供时从 Pi 默认 Agent 目录发现订阅认证~/.pi/agent或$PI_CODING_AGENT_DIR见 pi-subscription.ts而模型与通用设置按会话隔离SettingsManager.inMemory()传入了记录型auth或ai-gateway时resolvePiSubscriptionAgentDir返回undefined即不再读取磁盘上的auth.json/models.json防止文件中的凭据绕过显式配置。4.5 mcpServers每个 Harness 一套 MCP 服务器mcpServers?: Recordstring, unknown对应 CHANGELOGa03ff6c为 harness 增加 per-harness MCP 服务器支持值使用 Pi 运行时的原生 MCP 服务器配置格式。实现上适配器通过动态引入pi-mcp-adapter的createMcpAdapter生成一个内联扩展来服务这些服务器参数为{ directTools: true, toolPrefix: mcp, disableProxyTool: true }pi-session.ts——即 MCP 工具直接暴露给模型统一以mcp前缀命名不启用代理工具。4.6 extensionFactories受信任的内联扩展extensionFactories?: ReadonlyArrayExtensionFactory对应 CHANGELOGc20a315支持调用方提供的内联 Pi 扩展工厂a514695修复扩展读取宿主侧会话工作区c359fc0修复内联扩展注册的工具暴露给模型。README 给出了完整示例import { createPi } from ai-sdk/harness-pi; const harness createPi({ extensionFactories: [ pi { pi.on(agent_start, () { console.log(Pi agent started); }); }, ], });需要注意的边界README 与 pi-session.ts 均有说明扩展工厂在宿主 Node.js 进程中执行只应传入你信任的代码常规轮次间的资源刷新不会重新初始化扩展工厂只有底层 Pi 会话被重建时工厂才会对新运行时初始化preserveExtensionsResult机制保证资源刷新不重启扩展运行时此选项不启用文件系统扩展发现用户、项目、个人与 settings 级 Pi 扩展仍被禁用主题与提示模板同样禁用。五、内置工具集与 Pi 原生工具的一一映射createPi返回的HarnessV1暴露了 7 个内置工具pi-harness.ts并声明supportsBuiltinToolApprovals: true与supportsBuiltinToolFiltering: true公共工具名Pi 原生名工具类别入参readreadreadonlyfile_pathwritewriteeditfile_path、contenteditediteditfile_path、old_string、new_stringbashbashbashcommand、可选timeoutgrepgrepreadonlypattern、可选path/glob/ignoreCase/literal/context/limitglobfindreadonlypattern、可选path/limitlslsreadonly可选path/limit公共名到原生名的映射PUBLIC_TO_NATIVE、工具类别PI_NATIVE_TOOL_KINDS以及工具过滤逻辑resolveActivePiBuiltinNames集中在 pi-session.ts过滤模式为allow时按白名单映射为deny时先转公共名再排除。内置工具审批方面requestBuiltinToolApprovalpi-session.ts按permissionMode默认allow-all决定是否把工具调用升级为tool-approval-request流事件等待宿主批准CHANGELOG 中32349cc修复了“Pi 单步发出多个工具调用时只弹出一个审批请求”的问题确保每个工具调用都能触发审批0027d69则修复过客户端侧工具审批的回归。b6d0025与cc3e121分别修复了路径穿越与工作区符号链接逃逸详见第九节安全边界。六、模型解析provider/id 作用域与 Gateway 优先Pi 模型解析逻辑位于 pi-model-resolver.ts默认模型未显式配置model且环境中存在 Gateway 凭据时使用默认模型 idanthropic/claude-sonnet-4.6DEFAULT_PI_GATEWAY_MODEL_ID解析优先级createPiModelResolver返回的闭包存在 Gateway 凭据时优先匹配vercel-ai-gatewayprovider 下同 id/name 的条目——因为同一模型 id 可能同时注册在openrouter、vercel-ai-gateway等多个 provider 下若不优先 Gateway 就会派发到未注册的 provider 而报 “No API key found”findScopedMatch按provider/id前缀在对应 provider 作用域内查找要求该 provider 已配置认证唯一命中的已认证扁平匹配回退到作用域匹配或任意扁平匹配。b6642fa修复复合 provider/id 模型 id 在作用域 provider 下解析与9ee30bf指令注入从首条用户消息改为系统提示附加都落在这一层及其周边。另外HarnessAgent层面的模型能力CHANGELOG 中7608210将model参数上移到HarnessAgent、8961fde允许轮次间通过 call options 更换模型、14d4fc0支持通过prepareCall()在轮次间修改 harness 设置、62a9c2a支持output结构化输出都由 packages/harness 公共层实现Pi 适配器只负责把当前解析到的模型注入 Pi 会话。七、会话生命周期工作区镜像、VFS 与跨进程恢复7.1 宿主侧目录布局每次会话在宿主tmpdir()下建立隔离目录树pi-session.tstmpdir/ai-sdk-harness/pi/safeSessionId/ ├── agent/ # Pi 的 auth.json、models.json 等全局状态仅宿主可见 ├── sessions/ # Pi 会话 journal 文件 └── workspace/ # 沙箱工作区的宿主镜像沙箱文件系统不可见时使用safeSessionId会把\、/、:、空格替换为-避免会话 id 变成磁盘上的子目录树。CHANGELOG0f5de2d专门修复了 Pi 的.sessions基础设施目录污染 Agent 工作目录的问题即与此布局相关。7.2 工作区可用性探测与 VFS 挂载关键机制isWorkspaceAvailableOnHostpi-session.ts向沙箱工作目录写入带随机 UUID 的探测文件再通过沙箱 API 读回比对证明该路径确实由沙箱持有才允许 Pi 直接使用。当沙箱文件系统是远程的适配器先通过syncHostWorkspaceFromSandbox把沙箱工作区快照到宿主镜像见 pi-workspace-mirror.ts再用PiWorkspaceVfs把hostWorkDir → sessionWorkDir挂载给 Pi 的fs资源加载pi-workspace-vfs.ts使 Pi 对模型展示的 “Current working directory” 解析在沙箱内同时本地资源加载走镜像。CHANGELOG 中7c3211d工作区镜像改为批量归档传输而非每文件一个请求与61d2b84对find不支持符号链接跟随标志的沙箱镜像 Pi 项目配置都是围绕这一镜像管线的优化。7.3 同进程驻留恢复与跨进程恢复Pi 没有沙箱内桥接进程工具审批暂停时 Pi turn 仍然存活并阻塞在自定义工具 promise 上。因此同进程恢复doSuspendTurn把存活会话“驻留”parkedPiSessions映射后续恢复时直接复用而不是 stop 会话并让 promise 以错误结束pi-session.ts跨进程恢复走持久化会话文件。恢复时会从沙箱拉取 Pi 会话文件到宿主镜像pullSessionFileFromSandbox用SessionManager.open打开 journal悬空宿主工具调用journal 中处于“等待宿主输入通常是审批”的工具调用在进程退出后成为悬空调用框架通过submitToolResult重新投递结果deferRerunUntilHostToolResults会阻塞重跑直到所有悬空调用的结果到齐再写入 journal 后重新驱动 turn避免模型看到合成空结果CHANGELOG39bd17e修复的正是跨进程恢复后工具结果被静默丢弃的问题。7.4 终止与资源清理permissionMode默认allow-allabortSignal贯穿会话创建与 turn 执行中止时清理 pending 的工具结果与审批settlePendingToolResults/settlePendingToolApprovals。八、技能Skills与指令注入技能写入harness 提供的技能会被写入沙箱 HOME 的.agents/skills/name/SKILL.mdcreateHarnessPiSkillspi-session.ts并在skillsOverride中过滤为“工作区内的项目技能 harness 技能”避免宿主个人技能进入模型上下文资源刷新applySessionInstructions在指令变化时触发reloadResourcesOnly()——有扩展工厂时通过preserveExtensionsResult保留活动扩展运行时只刷新资源无扩展时直接resourceLoader.reload()指令注入CHANGELOG9ee30bf修复了指令注入位置——从“塞进首条用户消息”改为“追加到系统/开发者提示”Pi 侧通过appendSystemPromptOverride消费pi-session.ts。九、安全与隔离边界从 CHANGELOG 提炼适配器在过去多个版本中持续收敛安全边界可归纳为四条线路径穿越防御b6d0025修复潜在路径穿越、cc3e121在文件工具中拦截工作区符号链接逃逸。宿主侧通过isWithinDirectory/isWithinWorkspace校验发现的资源路径必须落在sessionWorkDir或hostWorkDir内pi-session.ts宿主配置隔离默认不加载宿主的个人/项目 Pi 扩展与主题、提示模板noExtensions/noThemes/noPromptTemplates扩展只能来自显式传入的extensionFactories认证记录型传入时构建隔离凭据存储避免磁盘auth.json绕过命令转义43a8c68在适配器中使用shellQuote对 shell 参数进行转义配合00127df修复的 grep 误用降低命令注入面状态目录隔离0f5de2d.sessions不污染工作目录、61d2b84沙箱find能力降级时的配置镜像与c0595b4支持受限文件系统/进程沙箱会话在网络沙箱方法不可用时回退共同保证 Pi 状态不越界。此外pi-events.ts 用宽松 schemaz.looseObject解析 Pi 的session.subscribe事件流只提取可识别字段文本增量、工具调用、错误、压缩事件等对新增事件类型天然向前兼容。十、能力演进时间线从 CHANGELOG 看适配器成熟路径如果按 CHANGELOG 版本梳理可以清晰看到适配器的成长脉络也是排查问题时定位“某个能力从哪个版本开始可用”的索引阶段代表提交/版本能力1.0.0 首发3d9a50cClaude Code / Codex / Pi 三适配器落地harness-v1规范稳定内置工具b6d0025、cc3e121、43a8c68路径穿越、符号链接逃逸、shell 转义配置深化81c3aa5agentDir、83fe754auth 字符串化、e0d7cfb隔离认证CLI 配置复用与认证解耦扩展与 MCPc20a315内联扩展、a03ff6cper-harness MCP、c359fc0/a514695扩展工具暴露与工作区读取可插拔扩展体系模型与指令b6642faprovider/id 作用域解析、9ee30bf系统提示注入、8961fde轮次间换模型、62a9c2a结构化输出模型与输出控制会话健壮性7c3211d批量归档镜像、39bd17e跨进程恢复投递、32349cc多工具审批、e115d16工具输入流式、f7fa993max 思考档恢复、审批、流式观测与请求b2d0306、eeed977User-Agent/x-client-app/自定义 headers可观测性与网关兼容截至当前仓库版本包版本为1.0.109见 package.json其最近若干版本仍以跟随 packages/harness 公共层的能力升级为主如prepareCall、headers、askUserQuestions工具归一化、移除废弃的model/modelId配置项等。结语ai-sdk/harness-pi展示了“编码 Agent 作为库”的集成范式Pi 在宿主进程内运行沙箱降级为纯执行环境harness 层则负责把 Pi 的原生能力翻译成统一的HarnessAgent会话模型。无论你是想在 Next.js 应用中让 Agent 直接读写仓库文件、通过 MCP 挂载外部工具还是构建需要跨进程恢复的长时间编码任务都可以从 README.md 的最小示例起步再依据本文的配置项与源码路径逐步深入。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
