编程语言AI Agent编译器CLI人工智能【免费下载链接】bamlThe programming language for agents项目地址https://gitcode.com/gh_mirrors/ba/baml点击查看免费下载baml-bridge 是 BAMLThe programming language for agents为 C# 生成的客户端提供的托管运行时桥接包PackageId为baml-bridge。由于它既要承载跨平台的原生库bridge_cffi.dll/libbridge_cffi.dylib/libbridge_cffi.so又要保证包内依赖与打包形态在真实消费场景中不出问题仓库在 bridge_csharp/tests/Baml.Bridge.NuGetPackageSmoke 下维护了一套专门的 NuGet 包冒烟测试。本文以该测试目录的 README.md 为骨架结合 verify.sh、verify-deployment.sh 等脚本源码完整拆解这套冒烟测试的验证维度、执行流程与底层机制帮助读者理解一个 NuGet 包如何被端到端地验证为可发布状态。测试定位只验证打包不重复测语言特性在深入脚本之前先明确这套测试的边界。README 开宗明义地指出这些脚本使用稳定的basic_callsAPI 测试打包。语言特性覆盖属于普通 C# SDK 测试套件。这意味着测试对象是打包形态NuGet 包本身的结构、原生资产的放置、恢复restore、发布publish以及最终可执行行为而不是 BAML 语言特性的正确性使用最小稳定的 API 面测试只调用一个最小的basic_calls函数用它代表生成代码 托管桥 原生桥的完整链路语言特性的深度验证如流式、媒体、类型系统等由 bridge_csharp/tests 下的其他探针Probe项目负责例如Baml.Bridge.Stream.Tests、Baml.Bridge.GeneratedContract.Tests、Baml.Bridge.HostCallable.Tests等。整套冒烟测试由两个脚本组成脚本职责verify.sh为每个 RID 恢复并执行确切版本的包同时检查包选择、不支持的 RID 诊断、NativeAOT 诊断、版本不匹配行为、包卫生package hygieneverify-deployment.sh检查**裁剪trimmed与单文件single-file**两种部署形态下的产物形状与运行正确性冒烟测试的固定骨架fixture、消费者工程与探测程序两个脚本共用一套固定的测试物料理解它们是读懂脚本的前提。1. BAML 源文件 fixture测试使用的 BAML 源位于 sdk_tests/crates/csharp/basic_calls/baml_src/ns_csharp_basic_calls/main.bamlfunction basic_calls( flag: bool, count: int, ratio: float, text: string, nullable: string?, ) - string { text }这个函数刻意覆盖了bool、int、float、string与可空string?五种基础类型的参数往返返回值直接透传text方便在探测程序中做严格相等断言。配套的 baml.toml 声明了 C# 生成器配置[package] name csharp-basic-calls [generator.csharp] output_type csharp output_dir . naming_convention language2. 探测程序 Program.csProgram.cs 通过生成的CsharpBasicCalls命名空间分别做一次同步和一次异步调用验证参数能原样往返using CsharpBasicCalls; const string Text héllo\0雪; string synchronous Functions.BasicCalls( flag: true, count: 42, ratio: 1.25, text: Text, nullable: null); if (synchronous ! Text) { throw new InvalidOperationException(packaged synchronous primitive result changed); } string asynchronous await Functions.BasicCallsAsync( flag: false, count: -17, ratio: -2.5, text: Text, nullable: present); if (asynchronous ! Text) { throw new InvalidOperationException(packaged asynchronous primitive result changed); } Console.WriteLine(csharp_nuget_package_smokeok);注意两点文本特意使用了含\0与多字节 UTF-8 字符é、雪的字符串用于验证原生桥接层对字符串编解码没有破坏程序成功跑完才会输出csharp_nuget_package_smokeok因此脚本对输出做grep -Fx精确匹配即等价于断言整个调用链路正常。3. 消费者工程 Baml.Bridge.NuGetPackageSmoke.csprojBaml.Bridge.NuGetPackageSmoke.csproj 模拟一个真实的下游应用工程Project SdkMicrosoft.NET.Sdk PropertyGroup OutputTypeExe/OutputType TargetFrameworknet10.0/TargetFramework LangVersion14.0/LangVersion Nullableenable/Nullable ImplicitUsingsenable/ImplicitUsings TreatWarningsAsErrorstrue/TreatWarningsAsErrors Deterministictrue/Deterministic AssemblyNameBaml.Bridge.NuGetPackageSmoke/AssemblyName BamlBridgePackageVersion Condition$(BamlBridgePackageVersion) 0.15.0/BamlBridgePackageVersion /PropertyGroup ItemGroup PackageReference Includebaml-bridge Version[$(BamlBridgePackageVersion)] / /ItemGroup /Project关键设计精确版本锁定Version[$(BamlBridgePackageVersion)]中的方括号表示仅此版本、不允许浮动解析配合-p:BamlBridgePackageVersion$version把待测包版本精确注入严格编译TreatWarningsAsErrors让任何编译警告都成为失败信号确定性构建Deterministictrue与打包侧保持一致便于比对产物。4. 产品源映射 NuGet.ConfigNuGet.Config 使用了packageSourceMapping把包来源严格隔离configuration packageSources clear / add keybaml-product value%BAML_CSHARP_PRODUCT_FEED% / add keynuget.org valuehttps://api.nuget.org/v3/index.json protocolVersion3 / /packageSources packageSourceMapping packageSource keybaml-product package patternbaml-bridge / /packageSource packageSource keynuget.org package patternGoogle.* / package patternMicrosoft.* / /packageSource /packageSourceMapping /configurationbaml-bridge只能来自环境变量BAML_CSHARP_PRODUCT_FEED指向的本地产品源杜绝意外从 nuget.org 拉取到同名旧包依赖的Google.Protobuf等传递依赖只能来自 nuget.orgclear /确保不继承全局用户级源配置测试环境干净可复现。verify.sh为每个 RID 验证确切包的完整生命周期verify.sh 是主冒烟脚本。其用法为verify.sh exact-package [rid] [canonical-native-name] [generated-source-root]参数含义默认值exact-package待测.nupkg的绝对路径必填rid目标 Runtime Identifierlinux-x64canonical-native-name该 RID 下期望的原生库文件名libbridge_cffi.sogenerated-source-root已生成的*.g.cs源码根省略则自动生成空自动生成此外还支持一个独立子命令verify.sh --verify-repository-paths repository-root publish-dir下面按验证维度拆解。1. 版本提取与校验脚本从 nupkg本质是 zip中解压baml-bridge.nuspec用正则提取version标签version$(unzip -p $package baml-bridge.nuspec \ | sed -n s#.*version\([^]*\)/version.*#\1#p) if [[ ! $version ~ ^[0-9A-Za-z][0-9A-Za-z.-]*$ ]]; then echo exact package contains an invalid or missing version: $version 2 exit 1 fi版本字符串必须符合 NuGet 版本字符集否则直接判定失败。2. 生成 BAML 客户端源码fixture 代码生成若未提供generated-source-root脚本会在baml_language目录下用baml_cli从 fixture 重新生成 C# 代码(cd $language_root cargo run --quiet -p baml_cli -- \ generate --from $fixture)随后把生成结果中的全部*.g.cs文件复制到消费者工程的baml_sdk/目录并对文件清单做一次diff -u确保消费者拿到的生成文件集合与代码生成器刚产出的文件集合完全一致。同时脚本检查两个关键文件必须存在Baml/Generated/BamlProgram.g.csCsharpBasicCalls/Functions.g.cs3. 干净消费者环境与包选择检查脚本在mktemp -d的临时目录里构造feed、consumer、packages三层结构把待测包复制进产品源把消费者工程、NuGet.Config、Program.cs、生成源码复制进消费者目录。随后执行带 RID 的 restoreenv -u BAML_BRIDGE_CSHARP_NATIVE_LIBRARY \ NUGET_PACKAGES$dotnet_packages \ dotnet restore $project --runtime $rid --configfile $config \ -p:NuGetAuditfalse \ -p:BamlBridgePackageVersion$version这里的包选择检查包含三层含义解析结果唯一restore 完成后全局包目录$packages/baml-bridge下只允许存在一个*.nupkgtest $restored_product_package_count -eq 1解析到的是确切包把该 nupkg 与传入的exact-package做cmp字节级比对证明消费端恢复到的就是待测产物而非其他来源的版本源映射生效正因为NuGet.Config把baml-bridge锁定到产品源包选择才可控、可比对。顺带一提restore 前还会清空环境变量BAML_BRIDGE_CSHARP_NATIVE_LIBRARY——这是为了让测试验证原生库完全由 NuGet 包提供的路径而不是被外部环境变量覆盖。4. 发布publish与原生资产一致性restore 通过后进行框架依赖--self-contained false的 Release 发布env -u BAML_BRIDGE_CSHARP_NATIVE_LIBRARY \ NUGET_PACKAGES$dotnet_packages \ dotnet publish $project \ --configuration Release \ --runtime $rid \ --self-contained false \ --no-restore \ --output $publish \ -p:NuGetAuditfalse \ -p:BamlBridgePackageVersion$version随后三项断言发布目录中原生库文件恰好一个native_count -eq 1且文件名就是canonical_native从 nupkg 中unzip -p出的runtimes/$rid/native/$canonical_native与发布产物做cmp证明包内原生资产 → 消费端运行时文件的传递无损实际运行发布出的程序grep -Fx csharp_nuget_package_smokeok证明端到端调用成功。5. 不支持的 RID 诊断BAML0010脚本故意用不支持的 RIDlinux-s390x再次 build期望构建失败且日志包含诊断码BAML0010if env NUGET_PACKAGES$dotnet_packages \ dotnet build $project --configuration Release --runtime linux-s390x \ --no-restore -p:NuGetAuditfalse \ -p:BamlBridgePackageVersion$version \ $work/unsupported-rid.log 21; then echo build unexpectedly accepted an unsupported RID 2 exit 1 fi if ! grep -F BAML0010 $work/unsupported-rid.log; then ...该诊断由打包进包的buildTransitive/baml-bridge.targets触发。其源模板在 baml-bridge.targets.inTarget NameBamlRejectUnsupportedRuntimeIdentifiers BeforeTargetsPrepareForBuild ItemGroup _BamlRequestedRid Include$(RuntimeIdentifier) Condition$(RuntimeIdentifier) ! / _BamlRequestedRid Include$(RuntimeIdentifiers) Condition$(RuntimeIdentifiers) ! / _BamlSupportedRid IncludeBAML_SUPPORTED_RIDS / _BamlUnsupportedRid Include(_BamlRequestedRid) / _BamlUnsupportedRid Remove(_BamlSupportedRid) / /ItemGroup Error Condition(_BamlUnsupportedRid) ! CodeBAML0010 Textbaml-bridge does not support RuntimeIdentifier(s) (_BamlUnsupportedRid, , ). Supported RIDs: (_BamlSupportedRid, , ). / /TargetBAML_SUPPORTED_RIDS占位符在打包时由 pack-product.sh 依据 platforms.json 中的 C# RID 集合替换从而保证门禁清单与实际打包的原生资产清单始终同源。6. NativeAOT 诊断BAML0019同样脚本用-p:PublishAottrue再次 build期望失败且日志包含BAML0019。对应门禁也在 baml-bridge.targets.inTarget NameBamlRejectUnsupportedNativeAot BeforeTargetsPrepareForBuild Condition$(PublishAot) true Error CodeBAML0019 Textbaml-bridge does not support NativeAOT in v1. Use a normal, trimmed, single-file, or trimmed single-file JIT publish instead. / /Target这条诊断明确表达了当前版本v1的策略原生桥暂不支持 NativeAOT用户应改用普通 JIT、裁剪、单文件或裁剪 单文件的发布形态——而这些形态正是 verify-deployment.sh 要逐一验证的对象。7. 版本不匹配行为脚本构造一个不存在的版本9999.0.0用-p:BamlBridgePackageVersion9999.0.0在独立目录独立的NUGET_PACKAGES执行 restore期望失败并且错误日志中必须包含该版本号mismatch_version9999.0.0 if env NUGET_PACKAGES$dotnet_mismatch_packages \ dotnet restore $mismatch/Baml.Bridge.NuGetPackageSmoke.csproj \ --configfile $mismatch/NuGet.Config \ -p:NuGetAuditfalse \ -p:BamlBridgePackageVersion$mismatch_version \ $work/mismatch.log 21; then echo restore unexpectedly accepted a mismatched package version 2 exit 1 fi grep -F $mismatch_version $work/mismatch.log这个用例验证的是当精确版本不可用时restore 必须硬失败并明确报出版本号而不是静默降级、回退到浮动解析或复用旧缓存。这是发布一致性至关重要的行为契约。8. 包卫生检查package hygiene包卫生是 README 特别点名的验证维度脚本从两个方向检查a干净消费者目录restore 前消费者目录内不得出现*.proto、*.baml、*.toml、*.bin等源码或运行时资产——这些只应存在于 SDK 开发环境绝不允许混入仅消费包的用户工程if find $consumer -type f \ \( -name *.proto -o -name *.baml -o -name *.toml -o -name *.bin \) \ | grep -q .; then echo clean consumer contains a forbidden source/runtime asset 2 exit 1 fib发布目录publish 后不得出现*.proto、*.baml、baml-cli*、baml.toml、*.csprojif find $publish -type f \ \( -name *.proto -o -name *.baml -o -name baml-cli* \ -o -name baml.toml -o -name *.csproj \) \ | grep -q .; then echo published consumer contains a forbidden source/tooling asset 2 exit 1 fic仓库路径泄漏检查通过--verify-repository-paths子命令verify_repository_paths函数用grep -r -a -F -l扫描发布目录确保其中不含仓库根路径字符串。实现上特意在仓库根后补/repository_path_prefix${repository_root%/}/防止/work这类短挂载点误伤/worker.rs之类的无关路径段。这条防线是为了防止构建机路径如/data/.../baml被编译进产物而泄露到用户环境。9. 成功信号所有检查通过后脚本输出一行固定的成功标记csharp_nuget_package_smokeokCI 只需对输出做精确匹配即可判定该 RID 的包验证通过。verify-deployment.sh裁剪与单文件部署形态验证verify-deployment.sh 专门回答一个问题在裁剪trimmed和单文件single-file发布下原生库资产与程序是否依然正确。其用法固定为 4 个必填参数verify-deployment.sh exact-package rid canonical-native-name generated-source-root与 verify.sh 不同这里要求generated-source-root已存在不再自动生成且生成源码整目录复制进消费者cp -R .../baml_sdk/并在脚本内直接生成一份含BAML_CSHARP_PRODUCT_FEED环境变量引用的 NuGet.Config。1. 三种发布形态矩阵脚本覆盖了裁剪 × 单文件 × 原生库打包方式的组合矩阵共 5 个发布产物发布形态PublishTrimmedTrimModePublishSingleFileIncludeNativeLibrariesForSelfExtract原生库位置裁剪侧车trimmed sidecartruelinkfalse—输出目录旁文件单文件侧车single-file sidecar未裁剪false—truefalse输出目录旁文件单文件侧车single-file sidecar裁剪truelinktruefalse输出目录旁文件单文件自解压self-extract未裁剪false—truetrue打进单文件 bundle单文件自解压self-extract裁剪truelinktruetrue打进单文件 bundle公共发布参数非常严格common( --configuration Release --runtime $rid --self-contained true --no-restore -p:NuGetAuditfalse -p:BamlBridgePackageVersion$version -p:SuppressTrimAnalysisWarningsfalse -p:TrimmerSingleWarnfalse -p:ILLinkTreatWarningsAsErrorstrue ) trimmed(-p:PublishTrimmedtrue -p:TrimModelink)其中SuppressTrimAnalysisWarningsfalse与ILLinkTreatWarningsAsErrorstrue意味着任何裁剪分析警告都会让构建失败——这验证了Baml.Bridge本身是干净可裁剪的其工程设置了IsTrimmabletrue、EnableTrimAnalyzertrue见 Baml.Bridge.csproj。2. 产物清单断言inventoryassert_single_file_inventory函数对单文件发布目录做白名单校验目录下只允许存在可执行文件Baml.Bridge.NuGetPackageSmoke、*.pdb以及仅侧车模式下一个canonical_native原生库任何其他散落文件都视为失败case $(basename $file) in Baml.Bridge.NuGetPackageSmoke|*.pdb) ;; $canonical_native) test $include_native true ;; *) echo unexpected loose single-file publish asset: $file 2 return 1 ;; esac3. 侧车模式运行验证run_sidecar侧车模式下原生库以独立文件形式与单文件程序共存。run_sidecar断言输出目录恰好一个原生资产、路径就是$output/$canonical_native、且与包内runtimes/$rid/native/$canonical_native字节一致最后运行程序并匹配csharp_nuget_package_smokeok。4. 自解压模式运行验证run_self_extract自解压模式下原生库被嵌入单文件 bundle因此输出目录中不应有任何原生资产bundled_output_native数量为 0assert_single_file_inventory $output false。运行时通过DOTNET_BUNDLE_EXTRACT_BASE_DIR指定解压根目录env -u BAML_BRIDGE_CSHARP_NATIVE_LIBRARY \ DOTNET_BUNDLE_EXTRACT_BASE_DIR$extraction_root \ $output/Baml.Bridge.NuGetPackageSmoke \ | grep -Fx csharp_nuget_package_smokeok运行成功后再检查解压目录中恰好出现一个、且与包内原生资产字节一致的文件。这验证了嵌入式原生库被正确提取并可加载。5. 成功信号全部形态通过后输出csharp_exact_package_deploymentnormal_trimmed_and_single_file_shapes_ok打包侧的契约支撑pack-product.sh 与 platforms.json冒烟测试能成立依赖打包侧已经产出了正确结构的包。从 pack-product.sh 可以看到与冒烟测试呼应的多重契约八 RID 清单单一来源[release/platforms.json](https://link.gitcode.com/i/430d52d1f1804fda081f06ffcc65bb95)中artifacts.csharp定义了每个目标的rid与native_asset共 8 个osx-arm64、osx-x64、linux-arm64、linux-musl-arm64、linux-x64、linux-musl-x64、win-x64、win-arm64原生库分别对应libbridge_cffi.dylib/libbridge_cffi.so/bridge_cffi.dll。这正是 verify.sh 逐 RID 循环的测试矩阵来源原生资产完整性打包前用sha256sum -c校验原生资产清单并把runtimes/rid/native/asset路径集合与 platforms.json 生成的期望集合做diff -u二进制卫生用llvm-readobj/llvm-nm/llvm-objdump检查 ELF/Mach-O/COFF 格式、禁止调试段、禁止符号表、禁止 RPATH/RUNPATH导出符号必须精确等于 release/bridge-cffi-public-exports.txt 允许清单确定性打包同一输入打两次包经Baml.NuGetNormalizer规范化后必须cmp逐字节相同包结构白名单nupkg 条目集合被严格枚举为[Content_Types].xml、_rels/.rels、README.md、baml-bridge.nuspec、buildTransitive/baml-bridge.targets、lib/net10.0/Baml.Bridge.dll、core-properties 加上 8 个原生资产条目依赖门禁nuspec 必须含Google.Protobuf依赖但Grpc.Tools仅构建期工具绝不允许泄漏进产品包依赖图。冒烟测试脚本中对 nupkg 的unzip -p提取、cmp比对、发布目录清单扫描正是从消费端视角反向验证这些打包契约在真实 restore/publish 流程中没有被破坏。运行前提与限制要让这两个脚本在自己环境跑通需要满足以下前提以当前仓库实际内容为准.NET SDK目标框架为net10.0、LangVersion14.0需要对应版本的 .NET SDKRust 工具链verify.sh 在未提供generated-source-root时会调用cargo run -p baml_cli生成代码需要可用的 Rust 工具链与已解析的依赖平台原生能力验证某个 RID 需要在对应平台上运行例如linux-s390x只用于负向诊断测试Windows 下脚本通过RUNNER_OS判断并用cygpath -am转换路径外部依赖restore 过程中Google.Protobuf等传递依赖需要能访问 nuget.org打包产物来源脚本输入是确切版本的 nupkg如baml-bridge.version.nupkg该产物由打包管线pack-product.sh 发布计划产出冒烟测试本身不负责打包。限制方面脚本只覆盖basic_calls的最小 API 面更深的语言特性流式、媒体、动态类型等需由 bridge_csharp/tests 下各 Probe/Tests 项目补充当前 v1 明确不支持 NativeAOT因此部署验证只覆盖 JIT 下的普通/裁剪/单文件组合。总结一套完整的可发布性验证闭环从 README 的简短描述出发结合脚本源码可以看到这套 NuGet 冒烟测试实际构成了一个多维闭环包选择正确性restore 唯一命中确切包源映射隔离生效资产传递完整性包内runtimes/rid/native/原生库与发布产物逐字节一致门禁诊断有效性BAML0010不支持的 RID、BAML0019NativeAOT在错误场景如约触发失败语义正确性版本不匹配必须硬失败并报出版本号包卫生无源码/工具资产泄漏无仓库路径泄漏部署形态兼容性普通、裁剪、单文件侧车、单文件自解压四种形态均能加载原生库并跑通端到端调用。对于想要为 baml-bridge 的发布质量把关的开发者这套测试既是每个 RID 的可执行验收标准也提供了一个可复用的范式用一个最小稳定 API 面 严格产物清单 负向用例把包能不能被真实消费验证到极致。赞分享编程语言AI Agent编译器CLI人工智能【免费下载链接】bamlThe programming language for agents项目地址https://gitcode.com/gh_mirrors/ba/baml点击查看免费下载相关推荐Mastra Server 部署验证测试指南--test server 从部署到 API 冒烟验证Mastra Server 部署验证测试指南 test server 从部署到 API 冒烟验证 本指南是 Mastra 项目冒烟测试体系中 server 专人工智能Agent 框架AI AgentRAG后端nacos-docker环境变量全解析30核心参数配置指南nacos docker环境变量全解析30核心参数配置指南 nacos docker是部署Nacos服务的高效解决方案通过环境变量配置可以灵活定制服务特性微服务云原生Mastra 冒烟测试完全指南本地验证、云部署与 Release 发布前检查实战Mastra 冒烟测试完全指南本地验证、云部署与 Release 发布前检查实战 本文基于 Mastra 仓库中 .claude/skills/mastra人工智能Agent 框架AI AgentRAG后端上一篇CAD Sketcher安装失败深度分析如何彻底解决Blender插件依赖冲突问题下一篇Release v21.5.8:创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 BAML C NuGet 包冒烟测试全解析：精确版本恢复、RID 门禁与多形态部署验证
编程语言AI Agent编译器CLI人工智能【免费下载链接】bamlThe programming language for agents项目地址https://gitcode.com/gh_mirrors/ba/baml点击查看免费下载baml-bridge 是 BAMLThe programming language for agents为 C# 生成的客户端提供的托管运行时桥接包PackageId为baml-bridge。由于它既要承载跨平台的原生库bridge_cffi.dll/libbridge_cffi.dylib/libbridge_cffi.so又要保证包内依赖与打包形态在真实消费场景中不出问题仓库在 bridge_csharp/tests/Baml.Bridge.NuGetPackageSmoke 下维护了一套专门的 NuGet 包冒烟测试。本文以该测试目录的 README.md 为骨架结合 verify.sh、verify-deployment.sh 等脚本源码完整拆解这套冒烟测试的验证维度、执行流程与底层机制帮助读者理解一个 NuGet 包如何被端到端地验证为可发布状态。测试定位只验证打包不重复测语言特性在深入脚本之前先明确这套测试的边界。README 开宗明义地指出这些脚本使用稳定的basic_callsAPI 测试打包。语言特性覆盖属于普通 C# SDK 测试套件。这意味着测试对象是打包形态NuGet 包本身的结构、原生资产的放置、恢复restore、发布publish以及最终可执行行为而不是 BAML 语言特性的正确性使用最小稳定的 API 面测试只调用一个最小的basic_calls函数用它代表生成代码 托管桥 原生桥的完整链路语言特性的深度验证如流式、媒体、类型系统等由 bridge_csharp/tests 下的其他探针Probe项目负责例如Baml.Bridge.Stream.Tests、Baml.Bridge.GeneratedContract.Tests、Baml.Bridge.HostCallable.Tests等。整套冒烟测试由两个脚本组成脚本职责verify.sh为每个 RID 恢复并执行确切版本的包同时检查包选择、不支持的 RID 诊断、NativeAOT 诊断、版本不匹配行为、包卫生package hygieneverify-deployment.sh检查**裁剪trimmed与单文件single-file**两种部署形态下的产物形状与运行正确性冒烟测试的固定骨架fixture、消费者工程与探测程序两个脚本共用一套固定的测试物料理解它们是读懂脚本的前提。1. BAML 源文件 fixture测试使用的 BAML 源位于 sdk_tests/crates/csharp/basic_calls/baml_src/ns_csharp_basic_calls/main.bamlfunction basic_calls( flag: bool, count: int, ratio: float, text: string, nullable: string?, ) - string { text }这个函数刻意覆盖了bool、int、float、string与可空string?五种基础类型的参数往返返回值直接透传text方便在探测程序中做严格相等断言。配套的 baml.toml 声明了 C# 生成器配置[package] name csharp-basic-calls [generator.csharp] output_type csharp output_dir . naming_convention language2. 探测程序 Program.csProgram.cs 通过生成的CsharpBasicCalls命名空间分别做一次同步和一次异步调用验证参数能原样往返using CsharpBasicCalls; const string Text héllo\0雪; string synchronous Functions.BasicCalls( flag: true, count: 42, ratio: 1.25, text: Text, nullable: null); if (synchronous ! Text) { throw new InvalidOperationException(packaged synchronous primitive result changed); } string asynchronous await Functions.BasicCallsAsync( flag: false, count: -17, ratio: -2.5, text: Text, nullable: present); if (asynchronous ! Text) { throw new InvalidOperationException(packaged asynchronous primitive result changed); } Console.WriteLine(csharp_nuget_package_smokeok);注意两点文本特意使用了含\0与多字节 UTF-8 字符é、雪的字符串用于验证原生桥接层对字符串编解码没有破坏程序成功跑完才会输出csharp_nuget_package_smokeok因此脚本对输出做grep -Fx精确匹配即等价于断言整个调用链路正常。3. 消费者工程 Baml.Bridge.NuGetPackageSmoke.csprojBaml.Bridge.NuGetPackageSmoke.csproj 模拟一个真实的下游应用工程Project SdkMicrosoft.NET.Sdk PropertyGroup OutputTypeExe/OutputType TargetFrameworknet10.0/TargetFramework LangVersion14.0/LangVersion Nullableenable/Nullable ImplicitUsingsenable/ImplicitUsings TreatWarningsAsErrorstrue/TreatWarningsAsErrors Deterministictrue/Deterministic AssemblyNameBaml.Bridge.NuGetPackageSmoke/AssemblyName BamlBridgePackageVersion Condition$(BamlBridgePackageVersion) 0.15.0/BamlBridgePackageVersion /PropertyGroup ItemGroup PackageReference Includebaml-bridge Version[$(BamlBridgePackageVersion)] / /ItemGroup /Project关键设计精确版本锁定Version[$(BamlBridgePackageVersion)]中的方括号表示仅此版本、不允许浮动解析配合-p:BamlBridgePackageVersion$version把待测包版本精确注入严格编译TreatWarningsAsErrors让任何编译警告都成为失败信号确定性构建Deterministictrue与打包侧保持一致便于比对产物。4. 产品源映射 NuGet.ConfigNuGet.Config 使用了packageSourceMapping把包来源严格隔离configuration packageSources clear / add keybaml-product value%BAML_CSHARP_PRODUCT_FEED% / add keynuget.org valuehttps://api.nuget.org/v3/index.json protocolVersion3 / /packageSources packageSourceMapping packageSource keybaml-product package patternbaml-bridge / /packageSource packageSource keynuget.org package patternGoogle.* / package patternMicrosoft.* / /packageSource /packageSourceMapping /configurationbaml-bridge只能来自环境变量BAML_CSHARP_PRODUCT_FEED指向的本地产品源杜绝意外从 nuget.org 拉取到同名旧包依赖的Google.Protobuf等传递依赖只能来自 nuget.orgclear /确保不继承全局用户级源配置测试环境干净可复现。verify.sh为每个 RID 验证确切包的完整生命周期verify.sh 是主冒烟脚本。其用法为verify.sh exact-package [rid] [canonical-native-name] [generated-source-root]参数含义默认值exact-package待测.nupkg的绝对路径必填rid目标 Runtime Identifierlinux-x64canonical-native-name该 RID 下期望的原生库文件名libbridge_cffi.sogenerated-source-root已生成的*.g.cs源码根省略则自动生成空自动生成此外还支持一个独立子命令verify.sh --verify-repository-paths repository-root publish-dir下面按验证维度拆解。1. 版本提取与校验脚本从 nupkg本质是 zip中解压baml-bridge.nuspec用正则提取version标签version$(unzip -p $package baml-bridge.nuspec \ | sed -n s#.*version\([^]*\)/version.*#\1#p) if [[ ! $version ~ ^[0-9A-Za-z][0-9A-Za-z.-]*$ ]]; then echo exact package contains an invalid or missing version: $version 2 exit 1 fi版本字符串必须符合 NuGet 版本字符集否则直接判定失败。2. 生成 BAML 客户端源码fixture 代码生成若未提供generated-source-root脚本会在baml_language目录下用baml_cli从 fixture 重新生成 C# 代码(cd $language_root cargo run --quiet -p baml_cli -- \ generate --from $fixture)随后把生成结果中的全部*.g.cs文件复制到消费者工程的baml_sdk/目录并对文件清单做一次diff -u确保消费者拿到的生成文件集合与代码生成器刚产出的文件集合完全一致。同时脚本检查两个关键文件必须存在Baml/Generated/BamlProgram.g.csCsharpBasicCalls/Functions.g.cs3. 干净消费者环境与包选择检查脚本在mktemp -d的临时目录里构造feed、consumer、packages三层结构把待测包复制进产品源把消费者工程、NuGet.Config、Program.cs、生成源码复制进消费者目录。随后执行带 RID 的 restoreenv -u BAML_BRIDGE_CSHARP_NATIVE_LIBRARY \ NUGET_PACKAGES$dotnet_packages \ dotnet restore $project --runtime $rid --configfile $config \ -p:NuGetAuditfalse \ -p:BamlBridgePackageVersion$version这里的包选择检查包含三层含义解析结果唯一restore 完成后全局包目录$packages/baml-bridge下只允许存在一个*.nupkgtest $restored_product_package_count -eq 1解析到的是确切包把该 nupkg 与传入的exact-package做cmp字节级比对证明消费端恢复到的就是待测产物而非其他来源的版本源映射生效正因为NuGet.Config把baml-bridge锁定到产品源包选择才可控、可比对。顺带一提restore 前还会清空环境变量BAML_BRIDGE_CSHARP_NATIVE_LIBRARY——这是为了让测试验证原生库完全由 NuGet 包提供的路径而不是被外部环境变量覆盖。4. 发布publish与原生资产一致性restore 通过后进行框架依赖--self-contained false的 Release 发布env -u BAML_BRIDGE_CSHARP_NATIVE_LIBRARY \ NUGET_PACKAGES$dotnet_packages \ dotnet publish $project \ --configuration Release \ --runtime $rid \ --self-contained false \ --no-restore \ --output $publish \ -p:NuGetAuditfalse \ -p:BamlBridgePackageVersion$version随后三项断言发布目录中原生库文件恰好一个native_count -eq 1且文件名就是canonical_native从 nupkg 中unzip -p出的runtimes/$rid/native/$canonical_native与发布产物做cmp证明包内原生资产 → 消费端运行时文件的传递无损实际运行发布出的程序grep -Fx csharp_nuget_package_smokeok证明端到端调用成功。5. 不支持的 RID 诊断BAML0010脚本故意用不支持的 RIDlinux-s390x再次 build期望构建失败且日志包含诊断码BAML0010if env NUGET_PACKAGES$dotnet_packages \ dotnet build $project --configuration Release --runtime linux-s390x \ --no-restore -p:NuGetAuditfalse \ -p:BamlBridgePackageVersion$version \ $work/unsupported-rid.log 21; then echo build unexpectedly accepted an unsupported RID 2 exit 1 fi if ! grep -F BAML0010 $work/unsupported-rid.log; then ...该诊断由打包进包的buildTransitive/baml-bridge.targets触发。其源模板在 baml-bridge.targets.inTarget NameBamlRejectUnsupportedRuntimeIdentifiers BeforeTargetsPrepareForBuild ItemGroup _BamlRequestedRid Include$(RuntimeIdentifier) Condition$(RuntimeIdentifier) ! / _BamlRequestedRid Include$(RuntimeIdentifiers) Condition$(RuntimeIdentifiers) ! / _BamlSupportedRid IncludeBAML_SUPPORTED_RIDS / _BamlUnsupportedRid Include(_BamlRequestedRid) / _BamlUnsupportedRid Remove(_BamlSupportedRid) / /ItemGroup Error Condition(_BamlUnsupportedRid) ! CodeBAML0010 Textbaml-bridge does not support RuntimeIdentifier(s) (_BamlUnsupportedRid, , ). Supported RIDs: (_BamlSupportedRid, , ). / /TargetBAML_SUPPORTED_RIDS占位符在打包时由 pack-product.sh 依据 platforms.json 中的 C# RID 集合替换从而保证门禁清单与实际打包的原生资产清单始终同源。6. NativeAOT 诊断BAML0019同样脚本用-p:PublishAottrue再次 build期望失败且日志包含BAML0019。对应门禁也在 baml-bridge.targets.inTarget NameBamlRejectUnsupportedNativeAot BeforeTargetsPrepareForBuild Condition$(PublishAot) true Error CodeBAML0019 Textbaml-bridge does not support NativeAOT in v1. Use a normal, trimmed, single-file, or trimmed single-file JIT publish instead. / /Target这条诊断明确表达了当前版本v1的策略原生桥暂不支持 NativeAOT用户应改用普通 JIT、裁剪、单文件或裁剪 单文件的发布形态——而这些形态正是 verify-deployment.sh 要逐一验证的对象。7. 版本不匹配行为脚本构造一个不存在的版本9999.0.0用-p:BamlBridgePackageVersion9999.0.0在独立目录独立的NUGET_PACKAGES执行 restore期望失败并且错误日志中必须包含该版本号mismatch_version9999.0.0 if env NUGET_PACKAGES$dotnet_mismatch_packages \ dotnet restore $mismatch/Baml.Bridge.NuGetPackageSmoke.csproj \ --configfile $mismatch/NuGet.Config \ -p:NuGetAuditfalse \ -p:BamlBridgePackageVersion$mismatch_version \ $work/mismatch.log 21; then echo restore unexpectedly accepted a mismatched package version 2 exit 1 fi grep -F $mismatch_version $work/mismatch.log这个用例验证的是当精确版本不可用时restore 必须硬失败并明确报出版本号而不是静默降级、回退到浮动解析或复用旧缓存。这是发布一致性至关重要的行为契约。8. 包卫生检查package hygiene包卫生是 README 特别点名的验证维度脚本从两个方向检查a干净消费者目录restore 前消费者目录内不得出现*.proto、*.baml、*.toml、*.bin等源码或运行时资产——这些只应存在于 SDK 开发环境绝不允许混入仅消费包的用户工程if find $consumer -type f \ \( -name *.proto -o -name *.baml -o -name *.toml -o -name *.bin \) \ | grep -q .; then echo clean consumer contains a forbidden source/runtime asset 2 exit 1 fib发布目录publish 后不得出现*.proto、*.baml、baml-cli*、baml.toml、*.csprojif find $publish -type f \ \( -name *.proto -o -name *.baml -o -name baml-cli* \ -o -name baml.toml -o -name *.csproj \) \ | grep -q .; then echo published consumer contains a forbidden source/tooling asset 2 exit 1 fic仓库路径泄漏检查通过--verify-repository-paths子命令verify_repository_paths函数用grep -r -a -F -l扫描发布目录确保其中不含仓库根路径字符串。实现上特意在仓库根后补/repository_path_prefix${repository_root%/}/防止/work这类短挂载点误伤/worker.rs之类的无关路径段。这条防线是为了防止构建机路径如/data/.../baml被编译进产物而泄露到用户环境。9. 成功信号所有检查通过后脚本输出一行固定的成功标记csharp_nuget_package_smokeokCI 只需对输出做精确匹配即可判定该 RID 的包验证通过。verify-deployment.sh裁剪与单文件部署形态验证verify-deployment.sh 专门回答一个问题在裁剪trimmed和单文件single-file发布下原生库资产与程序是否依然正确。其用法固定为 4 个必填参数verify-deployment.sh exact-package rid canonical-native-name generated-source-root与 verify.sh 不同这里要求generated-source-root已存在不再自动生成且生成源码整目录复制进消费者cp -R .../baml_sdk/并在脚本内直接生成一份含BAML_CSHARP_PRODUCT_FEED环境变量引用的 NuGet.Config。1. 三种发布形态矩阵脚本覆盖了裁剪 × 单文件 × 原生库打包方式的组合矩阵共 5 个发布产物发布形态PublishTrimmedTrimModePublishSingleFileIncludeNativeLibrariesForSelfExtract原生库位置裁剪侧车trimmed sidecartruelinkfalse—输出目录旁文件单文件侧车single-file sidecar未裁剪false—truefalse输出目录旁文件单文件侧车single-file sidecar裁剪truelinktruefalse输出目录旁文件单文件自解压self-extract未裁剪false—truetrue打进单文件 bundle单文件自解压self-extract裁剪truelinktruetrue打进单文件 bundle公共发布参数非常严格common( --configuration Release --runtime $rid --self-contained true --no-restore -p:NuGetAuditfalse -p:BamlBridgePackageVersion$version -p:SuppressTrimAnalysisWarningsfalse -p:TrimmerSingleWarnfalse -p:ILLinkTreatWarningsAsErrorstrue ) trimmed(-p:PublishTrimmedtrue -p:TrimModelink)其中SuppressTrimAnalysisWarningsfalse与ILLinkTreatWarningsAsErrorstrue意味着任何裁剪分析警告都会让构建失败——这验证了Baml.Bridge本身是干净可裁剪的其工程设置了IsTrimmabletrue、EnableTrimAnalyzertrue见 Baml.Bridge.csproj。2. 产物清单断言inventoryassert_single_file_inventory函数对单文件发布目录做白名单校验目录下只允许存在可执行文件Baml.Bridge.NuGetPackageSmoke、*.pdb以及仅侧车模式下一个canonical_native原生库任何其他散落文件都视为失败case $(basename $file) in Baml.Bridge.NuGetPackageSmoke|*.pdb) ;; $canonical_native) test $include_native true ;; *) echo unexpected loose single-file publish asset: $file 2 return 1 ;; esac3. 侧车模式运行验证run_sidecar侧车模式下原生库以独立文件形式与单文件程序共存。run_sidecar断言输出目录恰好一个原生资产、路径就是$output/$canonical_native、且与包内runtimes/$rid/native/$canonical_native字节一致最后运行程序并匹配csharp_nuget_package_smokeok。4. 自解压模式运行验证run_self_extract自解压模式下原生库被嵌入单文件 bundle因此输出目录中不应有任何原生资产bundled_output_native数量为 0assert_single_file_inventory $output false。运行时通过DOTNET_BUNDLE_EXTRACT_BASE_DIR指定解压根目录env -u BAML_BRIDGE_CSHARP_NATIVE_LIBRARY \ DOTNET_BUNDLE_EXTRACT_BASE_DIR$extraction_root \ $output/Baml.Bridge.NuGetPackageSmoke \ | grep -Fx csharp_nuget_package_smokeok运行成功后再检查解压目录中恰好出现一个、且与包内原生资产字节一致的文件。这验证了嵌入式原生库被正确提取并可加载。5. 成功信号全部形态通过后输出csharp_exact_package_deploymentnormal_trimmed_and_single_file_shapes_ok打包侧的契约支撑pack-product.sh 与 platforms.json冒烟测试能成立依赖打包侧已经产出了正确结构的包。从 pack-product.sh 可以看到与冒烟测试呼应的多重契约八 RID 清单单一来源[release/platforms.json](https://link.gitcode.com/i/430d52d1f1804fda081f06ffcc65bb95)中artifacts.csharp定义了每个目标的rid与native_asset共 8 个osx-arm64、osx-x64、linux-arm64、linux-musl-arm64、linux-x64、linux-musl-x64、win-x64、win-arm64原生库分别对应libbridge_cffi.dylib/libbridge_cffi.so/bridge_cffi.dll。这正是 verify.sh 逐 RID 循环的测试矩阵来源原生资产完整性打包前用sha256sum -c校验原生资产清单并把runtimes/rid/native/asset路径集合与 platforms.json 生成的期望集合做diff -u二进制卫生用llvm-readobj/llvm-nm/llvm-objdump检查 ELF/Mach-O/COFF 格式、禁止调试段、禁止符号表、禁止 RPATH/RUNPATH导出符号必须精确等于 release/bridge-cffi-public-exports.txt 允许清单确定性打包同一输入打两次包经Baml.NuGetNormalizer规范化后必须cmp逐字节相同包结构白名单nupkg 条目集合被严格枚举为[Content_Types].xml、_rels/.rels、README.md、baml-bridge.nuspec、buildTransitive/baml-bridge.targets、lib/net10.0/Baml.Bridge.dll、core-properties 加上 8 个原生资产条目依赖门禁nuspec 必须含Google.Protobuf依赖但Grpc.Tools仅构建期工具绝不允许泄漏进产品包依赖图。冒烟测试脚本中对 nupkg 的unzip -p提取、cmp比对、发布目录清单扫描正是从消费端视角反向验证这些打包契约在真实 restore/publish 流程中没有被破坏。运行前提与限制要让这两个脚本在自己环境跑通需要满足以下前提以当前仓库实际内容为准.NET SDK目标框架为net10.0、LangVersion14.0需要对应版本的 .NET SDKRust 工具链verify.sh 在未提供generated-source-root时会调用cargo run -p baml_cli生成代码需要可用的 Rust 工具链与已解析的依赖平台原生能力验证某个 RID 需要在对应平台上运行例如linux-s390x只用于负向诊断测试Windows 下脚本通过RUNNER_OS判断并用cygpath -am转换路径外部依赖restore 过程中Google.Protobuf等传递依赖需要能访问 nuget.org打包产物来源脚本输入是确切版本的 nupkg如baml-bridge.version.nupkg该产物由打包管线pack-product.sh 发布计划产出冒烟测试本身不负责打包。限制方面脚本只覆盖basic_calls的最小 API 面更深的语言特性流式、媒体、动态类型等需由 bridge_csharp/tests 下各 Probe/Tests 项目补充当前 v1 明确不支持 NativeAOT因此部署验证只覆盖 JIT 下的普通/裁剪/单文件组合。总结一套完整的可发布性验证闭环从 README 的简短描述出发结合脚本源码可以看到这套 NuGet 冒烟测试实际构成了一个多维闭环包选择正确性restore 唯一命中确切包源映射隔离生效资产传递完整性包内runtimes/rid/native/原生库与发布产物逐字节一致门禁诊断有效性BAML0010不支持的 RID、BAML0019NativeAOT在错误场景如约触发失败语义正确性版本不匹配必须硬失败并报出版本号包卫生无源码/工具资产泄漏无仓库路径泄漏部署形态兼容性普通、裁剪、单文件侧车、单文件自解压四种形态均能加载原生库并跑通端到端调用。对于想要为 baml-bridge 的发布质量把关的开发者这套测试既是每个 RID 的可执行验收标准也提供了一个可复用的范式用一个最小稳定 API 面 严格产物清单 负向用例把包能不能被真实消费验证到极致。赞分享编程语言AI Agent编译器CLI人工智能【免费下载链接】bamlThe programming language for agents项目地址https://gitcode.com/gh_mirrors/ba/baml点击查看免费下载相关推荐Mastra Server 部署验证测试指南--test server 从部署到 API 冒烟验证Mastra Server 部署验证测试指南 test server 从部署到 API 冒烟验证 本指南是 Mastra 项目冒烟测试体系中 server 专人工智能Agent 框架AI AgentRAG后端nacos-docker环境变量全解析30核心参数配置指南nacos docker环境变量全解析30核心参数配置指南 nacos docker是部署Nacos服务的高效解决方案通过环境变量配置可以灵活定制服务特性微服务云原生Mastra 冒烟测试完全指南本地验证、云部署与 Release 发布前检查实战Mastra 冒烟测试完全指南本地验证、云部署与 Release 发布前检查实战 本文基于 Mastra 仓库中 .claude/skills/mastra人工智能Agent 框架AI AgentRAG后端上一篇CAD Sketcher安装失败深度分析如何彻底解决Blender插件依赖冲突问题下一篇Release v21.5.8:创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 RELATED READING
延伸阅读
更多一线实战笔记与深度复盘，助您持续精进
