人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载本文基于 strands-ts/test/packages/README.md 展开深入剖析strands-agents/sdkstrands-ts 目录下的 TypeScript SDK如何通过三层自动化测试确保发布到 npm 的包在真实用户环境中可以被正确导入与使用。读完本文你将掌握该 SDK 的打包验证架构、npm run test:package的完整执行链路以及如何在你的项目中复刻这套「ESM/CJS 双通道导入 Tarball 内容守卫 纯净依赖安装冒烟」的质量防线。为什么需要包级导入验证三类典型的打包缺陷strands-agents/sdk是一个入口众多、依赖复杂存在大量 optional peer dependencies的 SDK在发布前仅靠单元测试与类型检查无法发现打包层面的缺陷。test/packages/目录下的验证测试专门针对以下三类打包 bug 设计ESMimport与 CommonJSrequire的互操作失败SDK 本身是 ESM-only若构建产物或导出映射配置错误CJS 消费者通过await import()互操作与 ESM 消费者都会在模块加载阶段崩溃可选依赖optional peer缺失时的回归SDK 主入口或子路径若在模块顶层直接 re-export 了来自 optional peer dependency 的符号当用户未安装该依赖时import会在模块加载瞬间抛错——这正是文档中点名的RC.0 类 bug主入口 re-export 了一个来自 optional peer dependency 的符号测试产物混入发布包__tests__/、__fixtures__/、*.test.*等生成物若被npm pack一并打包会无谓增大包体积甚至引入环境敏感代码。test/packages/下共部署了三道防线各自捕获不同类别的缺陷且快慢搭配、互为补充防线目录/文件运行位置捕获的缺陷类别特点ESM CJS 导入测试esm-module/、cjs-module/本地npm run test:package构建产物无法被 ESM/CJS 导入、子路径/桶导出barrel解析错误、Node 入口副作用缺失快但通过file:安装、共享仓库根node_modules无法发现缺失 optional peer 的回归Tarball 内容守卫assert-package-contents.js本地npm run test:package发布包混入测试产物读取npm pack --dry-run的 JSON 输出并硬性校验打包 Tarball 安装冒烟npm-pack/CItest-package-pack.yml工作流RC.0 类「主入口依赖 optional peer」缺陷在 monorepo 外的临时目录安装真实 tarball模拟终端用户安装运行方式一条命令跑通本地两道防线在strands-ts/目录SDK 包根目录下执行npm run test:package该脚本在 strands-ts/package.json 中定义如下npm run build cd test/packages/esm-module npm install node esm.js cd ../cjs-module npm install node cjs.js cd ../../.. npm pack --dry-run --ignore-scripts --json | node test/packages/assert-package-contents.js执行链路可拆解为四个阶段npm run build先用tsc --project src/tsconfig.json编译出dist/产物ESM 导入测试进入test/packages/esm-module/npm install通过file:../../..安装 SDK运行node esm.jsCJS 导入测试进入test/packages/cjs-module/同样file:../../..安装后运行node cjs.jsTarball 内容守卫回到 SDK 根目录npm pack --dry-run --ignore-scripts --json将打包清单以 JSON 输出通过管道交给node test/packages/assert-package-contents.js校验。注意两点运行语义file:../../..的安装方式走 monorepo 解析路径与根node_modules共享依赖因此本地两道测试无法探测「缺装 optional peer」的回归——这正是第三道 CI 防线存在的意义而第三道防线npm-pack/冒烟测试在文档中明确说明仍由 CI 工作流单独触发不在test:package内。第一道防线esm-module/与cjs-module/双通道导入目录结构strands-ts/test/packages/ ├── esm-module/ # ES Module 导入测试file: 安装 │ ├── esm.js # 使用 import { ... } from strands-agents/sdk │ └── package.json ├── cjs-module/ # CommonJS 导入测试file: 安装 │ ├── cjs.js # 使用 require(strands-agents/sdk) │ └── package.json ├── npm-pack/ # 打包 tarball 安装冒烟测试CI 专用 │ ├── verify.ts # 类型检查版消费者脚本 │ ├── package.json │ └── tsconfig.json ├── assert-package-contents.js └── README.md两个 fixture 包的package.json结构几乎相同仅type字段不同esm-module/package.json声明type: modulecjs-module/package.json声明type: commonjs依赖均为strands-agents/sdk: file:../../..。ESM 通道esm.js验证了什么esm.js 运行在纯 Node.js ESM 环境无打包器验证点覆盖主入口、模型子路径、工具/插件桶导出与运行时行为主入口导入Agent、BedrockModel、ModelRouter、tool、Tool模型子路径strands-agents/sdk/models/routing、models/bedrock、models/openai、models/anthropic、models/googlevended-tools 子路径与桶导出从vended-tools/notebook、vended-tools/file-editor、vended-tools/http-request、vended-tools/bash逐个导入同时从strands-agents/sdk/vended-tools桶导入同名符号并断言「桶导出 子路径导出」的引用同一性vended-plugins 桶导出AgentSkills、ContextOffloader、GoalLoop、InMemoryStorage必须是可构造的函数typeof function并校验GoalLoop子路径与桶导出一致运行时行为实例化BedrockModel({ region: us-west-2 })并校验getConfig()用tool()工厂定义天气工具并invoke验证返回构造Agent验证工具注入Node 默认沙箱注册void agent.sandbox是一处关键断言——注释明确说明「Node 入口exports.node → index.node.js必须注册宿主默认沙箱若未注册该 getter 会抛错」。CJS 通道cjs.js的互操作模式cjs.js 的验证点与esm.js一一对应但采用纯 CJS 消费者视角async function main() { const { Agent, BedrockModel, ModelRouter, tool, Tool } await import(strands-agents/sdk) // ... 各子路径同样通过 await import() 获取 } main().catch((error) { console.error(error) process.exit(1) })关键语义在文件头注释中写明SDK 本身是 ESM-onlyCJS 消费者必须通过动态await import()互操作。该测试验证的是SDK 的 ESM 构建产物在 CJS 工程中依然可以被动态导入并正常使用所有子路径与桶导出的引用同一性在互操作场景下不被破坏。末尾以void OpenAIModel等语句引用剩余导入避免静态分析误报未使用变量。底层机制exports条件导出与 Node 入口副作用为什么agent.sandbox的 getter 能成为一条有效断言答案在 strands-ts/package.json 的exports映射与 index.node.ts 中.: { types: ./dist/src/index.d.ts, node: ./dist/src/index.node.js, default: ./dist/src/index.js }Node 环境解析主入口时命中node条件加载 index.node.tsimport { registerNodeDefaults } from ./register-node-defaults.js registerNodeDefaults() export * from ./index.js其文件头注释点明了这是一处「承重副作用」load-bearing side effect不能把该模块标记为无副作用否则打包器会 tree-shake 掉注册逻辑。register-node-defaults.ts 会注册 Node 默认沙箱与 MCP server 配置解析器。esm.js中void agent.sandbox的 getter 若抛错即说明exports.node条件或sideEffects声明出了问题——这是典型的「静态构建产物问题只能靠运行时导入测试暴露」的例证。顺带一提package.json 的sideEffects数组精确列出了./dist/src/index.node.js与./src/index.node.ts两个有副作用的入口与上述机制互为印证。第二道防线assert-package-contents.jsTarball 内容守卫assert-package-contents.js 是一个约 50 行的 stdin 管道脚本其头部注释声明了它守卫的回归问题issue #3004发布的 tarball 绝不能携带测试产物。它的输入是npm pack --dry-run --ignore-scripts --json的 stdout核心逻辑分四步空输入即失败npm pack无输出可能 prepack 或打包失败时直接抛错绝不静默通过JSON 解析失败即失败解析错误会携带原始输出的前 500 字符一并抛出便于定位error字段即失败npm pack在生命周期脚本如 prepack 的 build失败时会输出{error:{...}}并以非零退出管道会吞掉退出码因此脚本显式检查该字段文件清单正则过滤从files数组中提取路径用三条正则拦截测试产物const forbiddenPatterns [ /(^|\/)__tests__(\/|$)/, /(^|\/)__fixtures__(\/|$)/, /\.test\./, ]命中任一模式的路径都会被列出并抛错最多展示前 20 个全部通过则输出[package-contents] OK (N files)。值得注意的设计是脚本顶部注释中的同步约定这些正则与 strands-ts/package.jsonfiles数组里的!dist/**/__tests__、!dist/**/__fixtures__、!dist/**/*.test.*取反规则一一对应注释明确要求「新增排除规则如!dist/**/__mocks__时必须同步到此脚本」——防止发布配置与校验逻辑漂移。files数组只发布dist排除三类测试产物、README.md与LICENSE。第三道防线npm-pack/打包 Tarball 安装冒烟测试CI这是唯一能捕获RC.0 类 bug的测试。其思路与本地测试的本质区别在于在 monorepo 之外的临时目录安装真实 tarball且只安装非 optional 的 peer 依赖从而让「任何在模块加载时传递拉取 optional peer 的导入」直接失败。为什么要在 monorepo 外安装本地file:../../..安装与根node_modules共享依赖树optional peer 即使缺失也可能被其他依赖顺带装上缺陷被掩盖而 tarball 安装到独立临时目录后依赖解析完全依赖 tarball 内声明的peerDependencies元数据——required peer 会被自动安装optional peer 被刻意遗漏见 npm-pack/package.json 的注释说明。verify.ts的验证面与刻意回避verify.ts 是类型检查版消费者脚本覆盖主入口Agent、AgentResult、BedrockModel、ContextWindowOverflowError、FunctionTool、Model、StateStore、Tool、ZodTool、tool、模型子路径、multiagentGraph、Swarm、MultiAgentState、vended-tools 与 vended-plugins 的子路径/桶导出并对StateStore做存取 round-trip、对ContextWindowOverflowError做Error子类校验。文件头注释精确划定了测试边界——以下子路径故意不导入因为它们需要 optional peer交给esm-module/与cjs-module/覆盖models/{anthropic,openai,google,vercel}、a2a、a2a/express、session/s3-storage、telemetry这一设计体现了「三层防线各司其职」的架构CI 冒烟只验证不依赖 optional peer 的「安全面」能干净加载而依赖 optional peer 的「全量面」由本地双通道测试在完整依赖环境中验证。消费者侧类型检查npm-pack/tsconfig.json 是配套的类型检查配置其目标明确针对已安装 tarball 的.d.ts表面做校验而非 SDK 源码。因此配置刻意保持极简strict: true但skipLibCheck: true、isolatedModules: true、noEmit: true只为在verify.ts中暴露真实错误避免过严选项产生误报。module: NodeNext与moduleResolution: nodenext则与实际消费者工程保持一致。按文档说明该冒烟测试由 CI 工作流test-package-pack.yml独立触发该工作流文件不在当前仓库快照内流程为npm pack→ 将 tarball 与npm-pack/fixture 复制到 monorepo 外的临时目录 → 安装 tarball → 运行verify.ts并通过tsx执行。三层防线的分工与设计哲学综合三条防线可以提炼出这套打包质量体系的设计原则快慢分层本地test:package一条命令完成构建、双通道导入、内容守卫秒级分钟级CI 冒烟在干净环境中做最终裁决——开发者在提交前即可获得第一层反馈环境隔离补盲区本地共享node_modules是已知盲区CI 的隔离安装正是针对「optional peer 缺失」这类只有真实安装才能暴露的缺陷静默失败零容忍assert-package-contents.js对空输入、解析失败、error字段一律抛错「拒绝在空载荷上通过」——校验器本身不允许被绕过导出面即契约esm.js/cjs.js/verify.ts中每个import子路径、每次「桶导出 子路径导出」的引用同一性断言都在把 package.json 的 exports 映射 当作对外契约逐条钉死任何一条 exports 条目的漂移都会在这里显形。如果你在自己的 TypeScript SDK 中复刻这套方案最小可行集合是一对 ESM/CJS fixture 一个npm pack --dry-run --json内容守卫脚本含空载荷拒绝逻辑 一个 CI 中的隔离 tarball 安装冒烟。参照本文引用的 test/packages/ 目录 结构与 test:package 脚本即可在半小时内为你的发布管线补上同样的质量网。赞分享人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载相关推荐XUnity Auto Translator终极指南3分钟学会为Unity游戏添加实时翻译XUnity Auto Translator终极指南3分钟学会为Unity游戏添加实时翻译 还在为看不懂外语游戏而烦恼吗XUnity Auto Transl后端微服务云原生node-postgres 的 ESM/CJS 双模块导出兼容性测试实践深入 pg-esm-test 内部测试包node postgres 的 ESM/CJS 双模块导出兼容性测试实践深入 pg esm test 内部测试包 导读 node postgres 采用 mo数据库关系型数据库后端smolagents 安装完全指南pip/uv 双通道、可选依赖extras逐项解析与安装验证smolagents 安装完全指南pip/uv 双通道、可选依赖extras逐项解析与安装验证 本文以官方西班牙语文档《Opciones de insta人工智能AI AgentAgent 框架工具调用代码智能体MCP ClientsAgent 沙箱上一篇jQuery Mask Plugin源码架构分析理解Mask类的设计与实现原理下一篇用文字创造机械奇迹Zoo Text-to-CAD让设计变得像说话一样简单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考