在 Cloudflare Agents 项目中固化未发布依赖：pi AgentHarness 的 vendored 开发版构建输入解析-北京尧图网络

在 Cloudflare Agents 项目中固化未发布依赖pi AgentHarness 的 vendored 开发版构建输入解析【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents本文围绕examples/next/harnesses/pi/vendor/pi-dev/README.md这一构建输入说明文档展开。该目录承载了一个实验性早期访问示例pi harness example所需的未发布版 piAgentHarness依赖包归档是理解如何在不发布上游包的前提下把第三方未发布 API 固化进仓库、并通过真实包名安装、用 SHA256SUMS 校验字节、最终平滑迁移回官方 npm 版本这一完整供应链实践的钥匙。读完本文你将掌握 vendored tgz 归档的元数据含义、五个真实 npm 包名与其在 durable agent 组合中的分工、清单裁剪与字节校验机制以及它们如何被示例源码、测试与 RFC 设计文档逐层消费和验证。1. 背景为什么一个 harness 示例需要开发版构建输入examples/next/harnesses/pi是 Cloudflare Agents SDK 仓库中的一个实验性示例。它把开源项目 earendil-works/pi下称 pi的 durableAgentHarness持久化 Agent 执行框架负责转录、工具意图与结算、重试、取消、崩溃恢复放进一个普通的 Durable Object 中运行并与 SDK 自身的 Lifecycle 能力Tasks、Streams、WebSockets组合成一个完整的可恢复对话系统。关键事实是示例使用的 piAgentHarnessAPI 在当时尚未发布属于 pi 上游的dev分支/开发版能力。为了让示例在仓库内可复现、可构建、可测试而无需依赖一个尚不存在的 npm 版本仓库把该构建固定为本地归档文件放在examples/next/harnesses/pi/vendor/pi-dev/下并用vendor/pi-dev/README.md记录其来源、版本与消费方式。这就是Pi development build inputs的含义——它是构建输入build inputs不是示例自身的源码。该说明文档的核心信息可概括为一条供应链事实链上游仓库earendil-works/pi固定提交c4b0e35abe631bc830190fa6cafbe81b098b97d7包版本0.84.4许可证MIT详见 examples/next/harnesses/pi/licenses/mit-earendil-pi.txt注原文档中指向许可证的相对链接为../../licenses/mit-earendil-pi.txt相对vendor/pi-dev/目录按仓库根目录换算后即上面的路径。2. 五个真实 npm 包名归档在真实包名下安装说明文档明确指出示例以这些包的真实 npm 名称安装归档而不是改名为自定义命名空间。归档目录下对应五个.tgz文件包名归档文件在示例中的角色earendil-works/chordearendil-works-chord-0.84.4.tgzpi 的底层核心运行库上下文、后台执行原语等pi-agent-core的类型投影自 Chord Contextearendil-works/pi-agent-coreearendil-works-pi-agent-core-0.84.4.tgz提供AgentHarness、AgentLane、AgentHarnessTool、StorageBackedSession、HarnessEvent、LaneSnapshot、OpenOperation等核心 APIearendil-works/pi-aiearendil-works-pi-ai-0.84.4.tgzpi 的模型/提供方抽象Models、Model、Api、ImageContent以及各 provider 子路径earendil-works/pi-session-backend-sqlite-nodeearendil-works-pi-session-backend-sqlite-node-0.84.4.tgzpi 的 SQLite 会话存储后端SqliteStorage负责把 pi 会话落到 Durable Object 的 SQLite 数据库earendil-works/pi-telemetryearendil-works-pi-telemetry-0.84.4.tgzpi 的遥测/用量记录这些包名并非空泛描述——它们被示例源码直接import。例如 src/harness/pi-harness.ts 从earendil-works/pi-agent-core导入了AgentHarness、StorageBackedSession、uuidv7及十余个类型从earendil-works/pi-ai导入Api/Model/Models/ImageContent从earendil-works/pi-session-backend-sqlite-node/storage导入SqliteStorage。这印证了说明文档归档在真实包名下安装的做法源码保持与未来正式 npm 版本一致的导入路径迁移时无需改动源码。3. 安装机制file:协议指向本地 tgz示例的依赖清单examples/next/harnesses/pi/package.json中这五个包全部以file:协议指向vendor/pi-dev/下的归档dependencies: { earendil-works/chord: file:vendor/pi-dev/earendil-works-chord-0.84.4.tgz, earendil-works/pi-agent-core: file:vendor/pi-dev/earendil-works-pi-agent-core-0.84.4.tgz, earendil-works/pi-ai: file:vendor/pi-dev/earendil-works-pi-ai-0.84.4.tgz, earendil-works/pi-session-backend-sqlite-node: file:vendor/pi-dev/earendil-works-pi-session-backend-sqlite-node-0.84.4.tgz, earendil-works/pi-telemetry: file:vendor/pi-dev/earendil-works-pi-telemetry-0.84.4.tgz }这意味着安装流程pnpm install会从仓库本地解包这些 tgz而不是从 npm registry 拉取。它的直接效果是可复现不依赖上游 pi 仓库当时的发布状态任何人 checkout 仓库后都能装出完全一致的依赖树锁定 API 形状示例代码针对方便的devAPI 编写归档把该 API 快照固定下来防止上游日常提交破坏示例零凭证无需 npm 私有 registry 或 GitHub token 即可安装。从实现角度看这正是vendoring依赖固化的经典形态把源码树中不可变的外部产物作为构建输入纳入版本控制。4. 清单裁剪与字节校验只留运行时依赖说明文档强调两点构建卫生约束这两点在源码与归档文件中都能找到对应物。4.1 清单只保留运行时依赖Manifests keep only the runtime dependencies the built artifacts need.——归档内嵌的package.jsonmanifest被裁剪过只保留构建产物实际运行所需的运行时依赖。这是 vendoring 场景下的常见取舍既然归档是构建产物快照就不需要再携带其自身的开发依赖、构建脚本等与在宿主示例中运行无关的内容从而减小仓库体积、避免依赖图膨胀。4.2 SHA256SUMS 固定归档字节vendor/pi-dev/SHA256SUMSexamples/next/harnesses/pi/vendor/pi-dev/SHA256SUMS为每个 tgz 记录了 SHA-256 摘要c1f9d94668ca1066da61ca74d4d8eac02f4cb2741dd5ef880bb7b481b0f01306 earendil-works-chord-0.84.4.tgz 1c23d8aa2e73782d3278840238f41d9b822acd8b7ad97b9e431957a76894d094 earendil-works-pi-agent-core-0.84.4.tgz 8a5493cb855e9472448a363353f23c20170fe2f3c337837624863349a7d7b35e earendil-works-pi-ai-0.84.4.tgz 371be6b938498968d3d8217c33d7e762fdfe0e80a404d100ec77dd6aec84be79 earendil-works-pi-session-backend-sqlite-node-0.84.4.tgz d8a4119f2753bf443c189e08de41e00f389eed9f9a4231d055e81e377d05339c earendil-works-pi-telemetry-0.84.4.tgzSHA256SUMSpins the checked-in bytes 的含义是摘要锁定的不是语义版本号而是归档文件的实际字节内容。任何对归档内容的改动哪怕是压缩包内部一个字节的差异导致重新打包都会改变摘要从而在供应链审计层面被立刻发现。这是对提交了一个不可变构建产物这一声明的机器可验证背书。5. 这些包在示例中如何被消费源码级证据说明文档是构建输入的说明书而示例源码展示了这些输入最终被组装成什么。理解消费方式才能真正看懂为什么需要固定这五个包。5.1 核心组装PiHarness把 pi 挂进 Lifecyclesrc/harness/pi-harness.ts 中的PiHarness类继承自LifecycleCapability是示例对上游AgentHarness的适配壳。它在构造时把Tasks能力上注册一个 lane 驱动任务LANE_DRIVER_DEFINITION __cf_pi_harness_lanev1见 pi-harness.ts之后在onStart/onJob生命周期钩子中用StorageBackedSessionSqliteStorage把 pi 的会话状态落到 Durable Object 的 SQLite见 pi-harness.ts 的#attach通过createModels/resolveModel选择模型把tools、resources、systemPrompt等注入上游AgentHarnessOptions每个 lane 的工作作为一次Tasksrun 的 journaled steps 驱动 pi 直至结算settlement崩溃后由Tasks重放、而 pi 从自身 durable 状态恢复——Tasks 从不重放模型/工具副作用pi 的 session 就是恢复证据。5.2 SQLite 适配器pi 表被命名空间隔离src/harness/do-sqlite.ts 定义了一张表名映射表把 pi 自己的七张表全部加上cf_agents_pi_前缀branch_entries - cf_agents_pi_branch_entries branch_meta - cf_agents_pi_branch_meta entries - cf_agents_pi_entries list_values - cf_agents_pi_list_values scalar_values - cf_agents_pi_scalar_values sessions - cf_agents_pi_sessions usage_ledger - cf_agents_pi_usage_ledger这就是 RFC 中通过一个小的适配器把 pi 的表命名空间化为cf_agents_pi_*的实现落地见 design/rfc-pi-harness-example.md。pi-session-backend-sqlite-node的SqliteStorage正是这些表的读写后端。5.3 Workers AI 提供方零 API key 的模型调用src/providers/workers-ai.ts 利用earendil-works/pi-ai的cloudflareWorkersAIProvider与openAICompletionsApi实现了一个通过 WorkerAIbinding 转发的 pi provider请求经binding.run(model, body, { returnRawResponse: true })发出无需 API keyAI Gateway 按 id 挂接。它注册的 provider id 是cloudflare-workers-ai见 workers-ai.ts并允许通过models选项向 pi 的 Workers AI 目录补充 catalog 中缺失的模型。5.4 Skillsagents/skills变成 pi 的资源与工具src/harness/skills.ts 把 SDK 的agents/skills技能源解析成 pi 的PiSkill资源与activate_skill/read_skill_resource工具模型侧的系统提示中还会注入技能目录 catalog。示例自带的trip-planning技能即通过此路径暴露给模型。5.5 组合模式总览示例 READMEexamples/next/harnesses/pi/README.md给出了最终组装代码正是上述五个包与 SDK 能力的汇合点export class PiAgent extends DurableObjectEnv { readonly tasks new Tasks(); readonly streams new Streams(); readonly harness new PiHarness({ models: createModels({ providers: [workersAI(this.env.AI)] }), model: { provider: cloudflare-workers-ai, modelId: MODEL_ID }, tasks: this.tasks, streams: this.streams, tools: () tools }); readonly webSockets new WebSockets(this.harness.webSockets()); readonly lifecycle Lifecycle.install(this) .use(this.tasks) .use(this.streams) .use(this.webSockets) .use(this.harness); }责任边界为pi 拥有转录、操作状态、工具意图与结果、重试与崩溃恢复SDK 提供 durable 唤醒Tasks、输出日志Streams与客户端传输WebSockets。提交在任何结算结果对调用方可见之前就已写入 intake 行并 enqueue lane driver因此崩溃不会留下已接受但无唤醒的工作。6. 为什么用 vendor 归档以及何时替换回 npm 版本说明文档最后一句给出了明确的退出策略Replace the archives with normal npm versions once a pi release contains the same durable harness API.即vendor 方案是过渡性供应链手段不是长期依赖策略。设计文档 design/rfc-pi-harness-example.md 的 Known costs 与 Before this becomes a package export 两节记录了这个判断的完整脉络示例固定了未发布的 pi 提交c4b0e35a即归档内的0.84.4未来希望达成的状态是agents/sessions能力落地后pi 的Storage契约直接实现在 sessions 表之上一个对象只保留一个消息存储Tasks 提供公开的capability 注册自有驱动入口有一个包含 harness API 的正式 pi 发布版本——届时归档即可删除package.json中的file:依赖替换为正常 npm 版本号示例的导入路径无需变化。也就是说替换的触发条件不是pi 发布了 0.84.5而是pi 发布版本包含了与示例所 pin 的 dev API 等价的 durable harness API。在此之前vendor/pi-dev/目录 SHA256SUMS就是该 API 契约在仓库内的权威快照。7. 端到端验证本地运行与驱逐恢复测试这套 vendored 输入是否真的可构建、可运行、可恢复示例自带的测试给出了可执行证明运行pnpm test配置见 src/tests/vitest.config.ts本地运行pnpm install pnpm run start注意示例使用远程 Workers AI binding无需 API key若 Wrangler 登录账户多于一个需设置CLOUDFLARE_ACCOUNT_ID。测试逻辑src/tests/harness.test.ts启动一个真实的 Durable Object使用 pi-ai 的 faux provider 驱动一次乘法工具调用至结算断言事件序列包含operation_start → turn_start → tool_start → tool_end → turn_end → operation_end随后用evictDurableObject(stub)驱逐对象再验证转录不变、并能发起第二次调用继续得到结果。该测试正好验证了文档所述能力的核心pi 从自身 durable 会话恢复、Tasks 重放驱动、Streams 承载事件日志——而这一切都建立在 vendor 归档中的五个包能如实提供相应 API 的前提之上。8. 小结一份构建输入说明文档的工程价值vendor/pi-dev/README.md虽然篇幅简短但它在仓库供应链中承担了不可替代的审计锚点作用它记录来源上游 commit、版本0.84.4、许可MIT、真实包名、清单裁剪原则、字节校验方式与替换条件。配合 examples/next/harnesses/pi/package.json、examples/next/harnesses/pi/vendor/pi-dev/SHA256SUMS、examples/next/harnesses/pi/src/harness/pi-harness.ts 与 design/rfc-pi-harness-example.md读者可以完整还原未发布第三方能力 → 归档固化 → 真实包名安装 → 源码消费 → 测试验证 → 未来迁移 npm 版本的全链路。这也为其他需要在仓库内安全引入未发布依赖的工程实践提供了一个可复制的参考范式。【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

在 Cloudflare Agents 项目中固化未发布依赖：pi AgentHarness 的 vendored 开发版构建输入解析

相关推荐

我用华为云码道从0到1做出一款战棋游戏：一个周末的完整实战记录

PS2022扩展面板未经正确签署：CEP签名与PlayerDebugMode修复

Qwen3.8-27B 私有化部署压测完，云端兜底的 Base URL 改到 TaoToken

更多资讯

Monolith：面向内容推荐场景的轻量级推荐系统——实时捕捉用户兴趣，一步跑通训练与推理

Ant Design Tree 树形控件入门实战：从 basic 示例掌握展开、选中、勾选与禁用

Windows下PyCharm Ctrl+Alt+L失效的根因与系统级修复方案

Altium Designer导入OrCAD .DSN文件的完整技术指南

回归测试的本质：缺陷驱动的靶向验证与环境感知

esp-iot-solution 的 i2c_bus 组件演进史与源码剖析：从硬件 I2C 到软件 I2C 的完整实践指南

今日更新

AReaL 调试指南：从 Agent Workflow 验证到分布式训练死锁诊断

MATLAB实现GPS L1 C/A信号仿真与二维捕获验证

彻底搞懂ASCII、Unicode与UTF-8：从乱码根源到编码实战

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？