Skip to content

Latest commit

 

History

History
160 lines (137 loc) · 27.9 KB

AGENTS.md

File metadata and controls

160 lines (137 loc) · 27.9 KB

AGENTS.md — StdUnit.Tags

面向在本仓库中工作的 AI 编码代理。人类用户文档见文末「文档」。

这是什么

面向工业硬件交互的 .NET 类库家族(net8.0,MIT,跨平台)。核心模型:

测点项目 ITagsProject = 通道 ITagChannel + 测点树 ITagGrp + 逻辑 ILogicet

每个 isEntry="true" 的测点组分配一个 ITagGrpRunner,按串行轮询运行: 【执行意图 → 读取输入 → 处理逻辑 → 刷写输出】。入口之间并行,入口内部严格串行。

构建 / 测试(与 CI 一致)

dotnet tool restore                    # 见 .config/dotnet-tools.json
dotnet paket restore                   # 见 paket.dependencies
dotnet build StdUnit.Tags.sln
dotnet test --no-build --collect:"XPlat Code Coverage" --results-directory ./TestResults

CI(.github/workflows/dotnet.yml)有三个 job:

  • build(ubuntu-latest,权威):整解 dotnet build StdUnit.Tags.sln -c Release(含 net472 的编译校验——引用程序集由 SDK 隐式引入的 Microsoft.NETFramework.ReferenceAssemblies 提供)+ 两个测试项目分两步顺序跑 dotnet test -f net8.0(StdUnit.Tags.Tests 与 StdUnit.Tags.Tests.NetCoreOnly,带覆盖率上报 codecov)。

  • net472-on-mono(ubuntu-latest):apt-get install -y mono-complete 自己装 Mono,跑 dotnet test -f net472,让 net472 的运行测试也自动化、又不占 Windows runner 的排队时间。mono ≠ .NET Framework,它绿只说明"大概率没退化",(权威结果仍归发版工作流 release-nuget.yml / release-baget.yml,windows-latest 全 TFM)+ 本机 Windows。当前是硬性把关(未设 continue-on-error);万一出现 mono 专有的伪失败,可在 job 上加 continue-on-error: true 降级为补充信号。mono job 红时先看是不是"mono 与真框架的差异",别急着改产品代码。

  • aot-smoke(ubuntu-latest):三个示例各自 dotnet publish ... -r linux-x64(需 clang + zlib1g-dev)后运行原生产物:AotSmokeTest.LogicetPlugins 验证"无 <Logicet> 的正常加载 + TryAddLogicet<T> + AOT 下配了 <Logicet> 必须快速失败",AotSmokeTest.SimpleFiles 验证"基本类型测点 + JSON 测点(源生成元数据)读写 + AOT 下缺元数据必须快速失败",AotSmokeTest.WebUi 验证"起 Kestrel + 结构树的多态 JSON 序列化([JsonDerivedType] 源生成)+ SSE 从全量基线到增量"。改了 AOT 相关代码(IsAotCompatible、[DynamicallyAccessedMembers]、Compat/*、插件加载路径、WebUi 的 DTO/序列化)时以它为准;publish 输出里的 IL2104/IL3053 来自第三方 McMaster.NETCore.Plugins,属已知噪声。

  • 两条 Linux job 统一遵循 "ubuntu-latest + 依赖自装",不钉镜像版本:本仓库自己装依赖(mono / clang+zlib),就没有理由把 job 的寿命绑在镜像标签上——ubuntu-22.04 已被官方公告 2026-09-17 起弃用、2027-04-17 退役(actions/runner-images#14254,期间还有 brownout 会直接判红),ubuntu-latest 也已宣布 2026-11 起为 26.04。

  • 参考实测(2026-10,本机 WSL):mono 上的结果与 Windows 真 .NET Framework 一致。

  • 改了 Compat/* 或 #if NETFRAMEWORK 分支时,仍建议在本机 Windows 上跑一次 -f net472(或在 PR 里看 net472-on-mono)。 samples/WpfDemo(net8.0-windows + WPF)已从解决方案移除,目录保留、需要时在本机 Windows 上单独 dotnet build samples/WpfDemo/WpfDemo.csproj(只要它还留在解决方案里,Linux 上的整解构建就会失败)。 tests/AotSmokeTest.LogicetPlugins、tests/AotSmokeTest.SimpleFiles 与 tests/AotSmokeTest.WebUi(都是 net8.0 + PublishAot=true)在解决方案内(整解构建顺带编译它们),但不要改成 net8.0-windows 或其他不可跨平台的形态——CI 的 aot-smoke job 要在 Linux 上 publish 并运行它们。

  • SDK 固定为 8.0.102(global.json,rollForward: minor)。

  • 依赖用 Paket 管理。不要 dotnet add package:请改 paket.dependencies 后运行 dotnet paket install(会更新 paket.lock)。

  • 包源有两个:nuget.org 与私有测试源 https://baget.stdunit.com/v3/index.json(后者只是本仓库自身的构建源——paket.dependencies 里列着它;包已发布到 nuget.org,消费方不需要知道私有源)。离线编译依赖 nuget-package-caches/。

  • paket.dependencies 普遍使用 lowest_matching: true ⇒ 默认取最低匹配版本;升级必须显式改版本号。

  • 改了 paket.dependencies/paket.lock 后若 obj/<proj>.<tfm>.paket.resolved 没刷新,删掉 paket-files/paket.restore.cached 与 obj/*.paket.resolved、*.paket.references.cached 再 restore。

目标框架(多目标)

Core / StdUnit.Tags / Rx / R3 / 全部驱动包(S7、ModbusTcp、Hjzk、ZLan、OpcUaClient、ComScanner、SimpleFiles)/ McpServer 都是 net8.0;net472;仅 BlazorLib.Core 仍是 net8.0。

McpServer 走 ModelContextProtocol(核心包)的 netstandard2.0 资产。 ModelContextProtocol.AspNetCore 是 net8-only,与核心包同在 Mcp 组,但只被 net8-only 的项目引用,因此不影响 net472。

新增代码时的约定:

  • 有标准库就用标准库。 跨框架差异用调用点的 #if NETFRAMEWORK 或项目内 Compat/ 目录的单点垫片(如 StdUnit.Tags.Core/Compat/ReferenceEqualityComparer.cs、StdUnit.Tags/Compat/DynamicLoadingCompat.cs、各驱动的 Compat/*.cs)。
  • 不要把 #if 铺到调用点满屏幕,也不要用 #if 去条件修饰公共 API(那会给库使用者制造两套签名)。
  • ImplicitUsings/Nullable/LangVersion/GenerateDocumentationFile 由 src/ 与 tests/ 各自的 Directory.Build.props 统一提供(tests/ 那份不含 NuGet 打包元数据,且已把 GenerateDocumentationFile 设为 false),新建项目不用再写这几项(net472 默认 C# 7.3,少写一次就少一次 CS8630);TargetFrameworks 仍写在各 csproj(存在 net8-only 项目)。src/ 下不生成 XML 文档的项目仍要在本项目显式写 <GenerateDocumentationFile>false</GenerateDocumentationFile>(目前没有这种情况)。src/Directory.Build.props 已开启 TreatWarningsAsErrors(整解仍是 0 警告);tests/ 与 samples/ 有意不加,因为 AOT 冒烟项目的 dotnet publish 会带出第三方 McMaster.NETCore.Plugins 的 IL2104/IL3053 噪声。
  • AOT 相关(逐包状态见 docs/设计决策与边界/4. 目标框架差异.md 的表,新增包记得补一行并放进对应分组):
    • <IsAotCompatible Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">true</IsAotCompatible> ——TFM 下界必须写 net8.0:NETSDK1210 的提示文本里给的是 'net7.0'(SDK 的通用下界),不要照抄—— 本家族的 netcore 地板是 net8.0,写 net7.0 等于在将来真加 net7.0 目标时打开分析器、并对外声称 IsTrimmable=True, 而 AOT 我们只在 net8.0 上验证过(aot-smoke 也只 publish net8.0)。net472 下不能无条件写: SDK 既不生成 IsTrimmable 标记也不开分析器,只会给每个 net472 项目报一条 NETSDK1210 (实测:obj/Debug/net8.0/*.AssemblyInfo.cs 里有 AssemblyMetadata("IsTrimmable", "True"),net472 侧没有)。 新包默认加上,除非有明确阻塞。目前已开的 11 个:核心 Core / StdUnit.Tags,扩展 R3Extensions / McpServer, 驱动 S7 / ModbusTcp / Hjzk / ZLan / OpcUaClient / ComScanner / SimpleFiles; RxExtensions(System.Reactive 对 AOT 支持不好)与 BlazorLib.Core(Blazor Server 不支持 AOT)是 NotPlanned; JSON 测点(type="JSON")的序列化元数据在 AOT/裁剪宿主下必须由使用方登记一次 (AddJsonSerializerContext(MyJsonContext.Default),源生成),反射路径只在普通 JIT 宿主下兜底。
    • DynamicallyAccessedMembers / UnconditionalSuppressMessage 等只在 net5.0+ 存在,标注用 #if NET5_0_OR_GREATER (它们是"编译期分析器的输入",net472 段点掉不构成两套签名);不要给它们建 Compat/ polyfill: public 会与 BCL 同全名类型冲突(消费方 CS0433),internal 则没有分析器会读,纯属命名空间污染。
    • 抑制告警必须用 [UnconditionalSuppressMessage]、不能用 #pragma warning disable——#pragma 只作用于编译期分析器, dotnet publish 的 ILLink 会在元数据上重新分析并照旧报出 IL2026/IL2067(实测)。
    • "宿主能力"的读取要收口到 Compat/ 一处,并作为参数传进判定函数(StdUnit.Tags/Compat/DynamicLoadingCompat.IsSupported、 StdUnit.Tags.SimpleFiles/Compat/JsonReflectionCompat.IsSupported):真实的"能力不足"取值只有 AOT / 裁剪宿主才有, 若在分支里直接读全局开关,那条分支在 JIT 测试里永远走不到,覆盖率必然漏(且同一判定会被复制多份)。
    • ⚠ 位置敏感的坑:PublishAot=true 会被 SDK 写进 runtimeconfig.json,使 RuntimeFeature.IsDynamicCodeSupported 在 IL+JIT 下也是 false;宿主据此判定"不支持动态加载",因此 <Logicet> 在 AOT(以及 PublishAot=true 的 IL 构建)下 必须快速失败(TagsProjectNotSupportedException),不要让它被 LogicetLoader 的通用 catch 吞掉——配了却静默不跑业务逻辑是硬红线。 tests/AotSmokeTest.LogicetPlugins / tests/AotSmokeTest.SimpleFiles / tests/AotSmokeTest.WebUi 是这些链路的端到端验证(CI 的 aot-smoke job)。
  • net472 缺 init-only setter 时,在 paket.references 里加 IsExternalInit(已有先例:Core / StdUnit.Tags / ComScanner / OpcUaClient / SimpleFiles)。
  • net8.0 共享框架里有的 API,在 net472 上一律按需补包引用,且只在 net472 生效:paket.references 写 framework: net472(先例:System.Threading.Channels、System.Diagnostics.DiagnosticSource——后者是 StdUnit.Tags 暴露 Metrics 所需)。这样 net8.0 的 nuspec / 消费方体验完全不变,代价只落在 net472 组。
  • net472 的引用程序集没有可空标注,string.IsNullOrEmpty 之类的 BCL 后置条件看不到,会出现 net472 专属的 CS8601/CS8603/CS8604 假阳性。改用语言级判空(x is null || x.Length == 0),不要用 NoWarn 压掉。
  • 不要用 | Select-Object -First n 过滤 dotnet paket/dotnet build 的长输出:会在第 n 行处终止上游进程。先 Out-File 再 grep。

项目和依赖分层

StdUnit.Tags.Core                硬件无关的核心抽象 + Schemas/tagsproject.xsd
├── StdUnit.Tags                 项目 / 日志 / 插件 / DI,仍与硬件无关
│   ├── StdUnit.Tags.S7
│   ├── StdUnit.Tags.ModbusTcp
│   │   ├── StdUnit.Tags.Hjzk    建立在 ModbusTcp 之上
│   │   └── StdUnit.Tags.ZLan    建立在 ModbusTcp 之上
│   ├── StdUnit.Tags.OpcUaClient
│   ├── StdUnit.Tags.ComScanner
│   ├── StdUnit.Tags.SimpleFiles
│   ├── StdUnit.Tags.McpServer
│   └── StdUnit.Tags.BlazorLib.Core     维护模式(不再加新功能,界面能力走 WebUi)
└── StdUnit.Tags.RxExtensions / R3Extensions     只依赖 Core
  • StdUnit.Tags.SchemaGenerator 是源生成器,把各项目的 XSD 编译成 DLL 内字符串常量(AOT / trim 友好)。
  • 新增驱动包时,需一并提供 Schemas/{driver}.xsd,并以 buildTransitive 方式注入到消费方项目树(照抄 StdUnit.Tags.Core.csproj + Schemas/StdUnit.Tags.Core.targets 的模式),并在 schema 里用 xs:annotation/xs:appinfo 声明 <driver name="…">(必须与 XxxNames.DriverName 一致;WebUi 的 /catalog 设计器元数据靠它把 driver 值绑到命名空间——XSD 1.0 表达不了这层关系,靠命名约定也不行),再实现 ITagsProjectSchemaProvider 注册为 Singleton。 如果驱动会从 TagDescriptor.Extras / TagCbntDescriptor.Extras 里读自己的属性(如 S7 的 maxlen、SimpleFiles 的 autoCreateFile、ModbusTcp 的 interpret),还要在同一个 appinfo 里用 <tagAttribute> / <cbntAttribute> 声明;核心 schema 因 xs:anyAttribute 放行这些属性,但 XSD 1.0 无法给既有类型追加属性,所以"有哪些、什么类型、什么文案"只能由驱动声明(仅供设计器,不参与校验)。详见 Schemas/README.md。
  • 测试分两个项目(xUnit),且主测试项目多目标 net8.0;net472:
    • tests/StdUnit.Tags.Tests:主体测试,跑在两个 TFM 上;
    • tests/StdUnit.Tags.Tests.NetCoreOnly:仅 net8.0,专门存放无法面向 net472 的测试(如依赖 AssemblyLoadContext,或涉及 Blazor / ASP.NET Core 的测试)。目前承载 StdUnit.Tags.WebUi 与 BlazorLib.Core 的测试,并已在 PR CI 中执行(不要把它排除出 CI:它曾是"只在发版当天才跑一次"的盲区)。
  • 新增测试默认放 tests/StdUnit.Tags.Tests(多目标,两个 TFM 都跑);只有当测试依赖 net8.0 专属的包/项目(如 ModelContextProtocol.AspNetCore、BlazorLib.Core、WebUi)或 net8.0 专属运行期 API(如 AssemblyLoadContext)时,才放 tests/StdUnit.Tags.Tests.NetCoreOnly。 不要在 tests/StdUnit.Tags.Tests 里用 #if NETFRAMEWORK 排除整个文件——那是编译期开关,解决不了“引用 net8-only 项目”的问题(目前仅 Core/Logicets/LogicetPluginLifecycleTests.cs 因这一原因用 Compile Remove 在 net472 下排除)。
  • benchmarks/StdUnit.Tags.Benchmarks:BenchmarkDotNet 基准(net8.0)。它在解决方案内,所以整解构建会编译它 (防止 API 漂移后悄悄腐烂),但不参与 CI 的测试与 AOT 冒烟;完整测量只在本地跑 dotnet run -c Release --project benchmarks/StdUnit.Tags.Benchmarks -- --filter *。 依赖走 Paket 的 Benchmarks 组(storage: none),绝不能出现在任何发布包的依赖里。

不可破坏的设计约束

  1. 公开面 = 接口 + DI 扩展 + 工厂/构建器。 TagsProject、TagsProjectCtrl、TagGrpRunner、TagGrpRunnerFactory、LogicetLoader、SimpleFilesDirectTagFactory 等具体实现一律 internal。不要把新的具体实现暴露成 public——用户代码只应通过接口 + DI 使用。
  2. 入口内严格串行。 ILogicet.ProcessAsync 与 TagGrpWriteIntent 都跑在轮询线程上,必须尽快返回。不要在这些路径上同步阻塞(.Result / .Wait() / Thread.Sleep),也不要把这些回调改成"等待外部事件"的形态——那会与 WriteIntent 构成环路等待死锁。
  3. 一个 ITagChannel 实例只能属于一个入口。 运行器崩溃/取消时会断开入口子树中的全部通道(DisconnectAllAsync),EntryChannelExclusivityValidator 依赖此约束。改动清理逻辑时务必保持该语义。
  4. 库不做任何隐式数值转换。 测点值类型必须精确匹配(short 不能写给 int)。GetTagValue<T>() 是硬转换,不做兼容处理。
  5. ITag.Channel 是只读属性(ITagGrp.Channel / ITagCbnt.Channel 可读写);ITagGrp.IsDirty() 是方法,而 ITag.IsDirty / ITagCbnt.IsDirty 是属性。这些不统一之处是刻意为之(比如ITagGrp是否已经是脏数据只依赖于其任意子节点是否已脏)。
  6. 校验器默认值:4 个代码校验器(跨引用、驱动工厂、入口通道独占、嵌套入口)在 UseDefaults = true 下默认开启;XSD 校验(EnableXmlSchemaValidation())默认关闭(opt-in)。
  7. 解析大小写敏感度:EndianKinds / TagAccessMode(LittleEndian、R1W …)大小写敏感;isEntry / isEnabled 不敏感。测试常覆盖这些边界。
  8. IntentCapacity 必须 > 0,且只能在 RunAsync 之前设置。
  9. isEnabled 只作用于自动轮询:TagGrpRunner 以 TraversalMode.RespectEnabled 遍历(自顶向下短路——父节点未使能,其整棵子树既不读也不写,脏标记保留);手动/外部意图里的显式 ReadAsync/WriteAsync 走 TraversalMode.IgnoreEnabled,不检查使能("平时禁用 + 需要时手动点动"是刻意支持的用法)。不要把公开的读写路径也改成检查使能,也不要让驱动自行判 IsEnabled。ITagGrp 的契约里只有 ReadAsync(TraversalMode, ct) / WriteAsync(TraversalMode, ct) 这一对「真身」,1 参版本(ReadAsync(ct))是 ITagGrpExtensions 上的扩展方法、等价于传 IgnoreEnabled(TagUnion 上同理,两个重载都在 TagUnionExtensions)。实现 ITagGrp 时必须把 mode 透传给子节点,否则门控会在该层断掉。ITagCbnt / ITag 不加 mode / IsEnabled:门控的边界是 Cbnt(其下无递归层,mode 传下去没人用),且同一个 Tag.IsEnabled 在「塞进 Cbnt」(整块缓存 IO,拦不住)与「直挂 ITagGrp」(自己做 IO)两种挂法下行为不同,语义不自洽——代价是 DirectTag 想在自动轮询时单独停采只能套一层 isEnabled="false" 的 TagGrp。「不可写」仍用 access="RO" 表达。
  10. 启动是两阶段的(先算后启,事务性):RunAsync 先对全部入口算完逻辑组件匹配(ILogicet.MatchEntry / Order,纯计算),再准备 runner(建意图通道 / 订阅事件)、最后统一启动。因此:匹配/准备阶段失败 → 一个轮次都没开始;启动阶段失败(含第三方 StartAsync 同步抛出)→ 取消并等待已启动的入口退出再抛原异常。两条路径都不能留下 Task 无人等待、令牌永不取消的孤儿 runner。代价:各入口拿到的生命周期令牌是内部 linked 令牌(同一次运行内各回调仍是同一个实例,但不保证 == 传给 RunAsync 的那一个),所以不要用引用相等做判断,取消时机才是契约。MatchEntry / Order 抛异常是确定性的配置错误:报 TagsProjectConfigurationException(Location = 入口路径,消息带逻辑组件类型),不得送入 RunnerCrashed 的重试/断开重连路径,也不得静默跳过该逻辑组件。Enabled 仍是每轮读取,运行期抛异常按普通轮询故障处理。

约定

  • 时间戳一律 UTC:ITag.Timestamp 用 DateTime.UtcNow 写入,不要用 DateTime.Now(本地时间跨时区/夏令时不可比);展示或与本地时间比较时由调用方自行转换。
  • 启停语义:ITagsProjectCtrl.StopAsync() 会先等轮询循环退出(有界超时,默认 30s)再释放项目、断开通道、触发"已停止"事件;StartPollAsync 的 finally 是项目的唯一常规释放点(只有等待超时那一刻才由 StopAsync 兜底释放,因此"只释放一次"是硬约束)。改启停或清理路径时必须保持这个顺序,详见 docs/设计决策与边界/。
  • 取消不是崩溃:StopAsync 引起的取消不触发 RunnerCrashed、不计入连续失败、不按重试策略退避(TagGrpRunner 用 catch (OperationCanceledException) when (ct.IsCancellationRequested) 单独处理),但通道照常断开、StartAsync 仍以 OCE 结束。判据是"令牌确实已取消":驱动因自身原因(如设备超时)抛的 OCE 仍是崩溃。RunnerStarted / RunnerCrashed / TurnProcess 拿到的都是同一个生命周期令牌;清理类异步操作一律用 CancellationToken.None(见 DisconnectAllAsync)。
  • 公共编译设置(ImplicitUsings + Nullable + LangVersion latest + XML 文档文件)在 src/Directory.Build.props(与 tests/Directory.Build.props,后者不含包元数据),NuGet 包元数据(作者/授权/仓库/项目主页/标签/README)只收口在 src/Directory.Build.props;新增会被发布的包时,务必在自己 csproj 里补一行 <Description>(否则 nuget.org 上只会显示 SDK 占位文本 Package Description),并把项目名加进 src/publish-packages.ps1 的列表。
  • 版本号不要写进 workflow:dev 通道(CI 的迭代产物 / 本地预演)用 src/publish-packages.ps1 -DevBuildNumber <构建号>,基线由脚本读仓库根的 next-release-version.txt 拼成 <基础版本>-dev.<构建号>;构建号是 UTC 的 yyMMdd.HHmm(如 261113.0930),由 workflow/命令自动生成,不手填。预发布只有 -dev.* 一种形态(alpha/beta/rc 已停用);它可以发到私有源(日常)也可以发到 nuget.org(公测,release-nuget.yml 选 versionKind=dev)。两个发布工作流都只有 versionKind(release / dev)一个下拉,版本串从 next-release-version.txt 拼出,不手填。正式版发布后要改的是那个文件。README 不写发版细节(它会被打进每个 nupkg),版本通道与发布流程都在 docs/设计决策与边界/3. 打包与发布.md。
  • 测试代码必须跨平台(CI 只跑 Linux),两类路径都要当心:
    • 分隔符:相对路径一律用 / 或 Path.Combine 分段,不要写 @"Samples\Web\index.xml"——反斜杠在 Linux 是合法文件名字符,Path.Combine 不会转换,结果是"Windows 上绿、Linux 上 File.Exists 失败"。夹具/示例用 TestPaths.Fixture("Samples", "Web", "index.xml") 定位。
    • Windows 专有绝对路径:C:\base 在 Linux 上不是 rooted 路径,Path.Combine 的行为会不同(Windows 丢弃前一段、Linux 拼接),于是同一个用例在两个平台上"测的不是同一件事"。需要"绝对路径"语义的数据请用 TestPaths.TempPath("base")(运行时由 Path.GetTempPath() 拼出,两个平台都真 rooted)。
    • 两者都收在 tests/StdUnit.Tags.Tests/TestPaths.cs。新增夹具/路径类用例后请在 WSL 上跑一遍 -f net8.0(或直接看 CI)。
  • 不要用"短固定窗口"等待异步推进:WebUi 的观测流测试要跑真实轮询循环 + SSE 写循环,CI runner 只有 4 个 vCPU、 且多个测试项目可能同时在跑(dotnet test 打解决方案时会并行启动多个 testhost),5s 级的窗口会把"机器忙"变成随机红 (2026-11 实测一次打挂 3 个互不相干的用例:Subscribe_FiltersByEntry / WriteValue_ParsesEveryBuiltinKind / Delta_IsSplitByMaxValuesPerFrame)。
    • 等待"某事发生了"请用 StreamTestContext.WaitUntil(...)(默认 30s,条件成立即返回)或 WaitUntilAsync,不要写 Task.Delay(150) 再断言;
    • 等待上限给宽松不会拖慢通过路径,只影响真失败时的反馈时间——所以宁可 30s 也不要 5s;
    • 断言"某事没有发生"时,必须先用一个正向信号证明"轮询确实又推进了"(例如再改一个值并等它到达), 否则循环停摆也会让负向断言通过(测试失去鉴别力);
    • tests/StdUnit.Tags.Tests.NetCoreOnly/TestProcessSetup.cs 会在进程启动时抬高线程池最小线程数,避免线程池爬坡造成的假超时; 两个 release 工作流也据此把测试项目分成两步顺序跑。
  • 大小写也算"跨平台":Linux 文件系统区分大小写,Windows 不区分。写错大小写的路径(例如测试里的 Schemas/drivers 而 csproj 的 Link 是 Schemas\Drivers)在 Windows 上一直绿,一到 Linux CI 就 DirectoryNotFoundException。
    • 警告:这个坑在 WSL 里测不出来——/mnt/d(DrvFs)同样不区分大小写。要真验证,得把仓库复制到 WSL 的 ext4(tar 排除 bin/obj,删掉 paket-files/paket.restore.cached 后 paket restore),或直接依赖 CI。
    • 需要按名字定位文件/目录时,大小写必须与产出方(csproj 的 Link、TestPaths.Fixture(...))逐字符一致——不要为了"容错"写成不区分大小写,那恰好把这个坑掩盖掉(我们就是先写成 SchemaPath("drivers") 才红的)。写错了就让它在 CI 上红,并顺手核对 csproj。
  • 驱动包内的 DI 扩展类约定同名 TagsProject_Extensions,各自位于自己的命名空间(如 StdUnit.Tags.S7)。
  • 驱动名常量集中在 XxxNames.DriverName(如 S7Names.DriverName = "S7"、ComDriverNames.DriverName = "COM");XML 中的 driver="..." 必须与之完全一致。
  • 每个驱动的支持注册收口为 .AddXxxSupport(),实现为细粒度注册(AddXxxChannel / AddXxxTagCbntBuilder / AddXxxDirectTagBuilder)的组合。新增驱动请沿用这个形状。可选的"策略/判定"类扩展点按这个形状走:注册扩展方法的可选参数 → 注册时闭包构造工厂 → 通道 ctor 的可选参数(默认用内置实现),例:OpcUa 的 checkIsFailed(AddOpcUaClientSupport(checkIsFailed:) → OpcUaClientTagChannelFactory → OpcUaClientTagChannel ctor,默认 OpcUaValueQuality.IsFailed);不要把它做成需要用户自己组装的服务类型。
  • 异常分型(src/StdUnit.Tags.Core/Exceptions/):加载期(XML 解析 / 地址解析 / 描述符解析 / 构建期配置检查 / 校验器)一律抛 TagsProjectLoadException 的具体子类——TagsProjectXmlException(属性值非法)、TagsProjectAddressException(地址无法解析)、TagsProjectConfigurationException(配置语义不自洽,含重名测点)、TagsProjectNotSupportedException(配置合法但当前宿主运行时缺能力:如 AOT 宿主遇到 <Logicet> 动态插件、AOT/裁剪宿主用 SimpleFiles 的 JSON 测点却没登记源生成元数据;判据是"换宿主是否能跑")、TagsProjectValidationException(校验器聚合,Errors 明细)。不要再在这些路径上抛裸 Exception/ArgumentException/InvalidOperationException/NotImplementedException。所有加载期错误消息都要带定位上下文(XElement.GetLocationPath() / ITagGrp.GetLocationPath(),段间用 / 连接,形如 TagGrp(a)/TagCbnt(b)/Tag(c)、Channel(S7-3),与 ITagGrp.Descendant("a/b/c") 语法一致),并尽量把 Location 属性一起填上;具体选型见 docs/异常处理.md 的决策树。运行期(读写/连接/清理)不建新类型,但不许抛裸 Exception:一律用语义贴近的 BCL 类型(入参问题 ArgumentNullException/ArgumentOutOfRangeException/ArgumentException,时序/状态问题 InvalidOperationException,类型不符 InvalidCastException,按名查不到 KeyNotFoundException,能力不支持 NotSupportedException)。运行期故障消息必须能定位现场(RunnerCrashed 只带入口的主通道):通道名 + 操作 + 地址/端点 + 底层错误文本与错误码明细;不要为加前缀而包装第三方异常(SocketException/OpcException/NModbus 自带端点信息,包装会改变调用方可 catch 的类型);日志用 LogError(ex, "...") 而非 LogError("...{ex}", ex.Message)。设备/协议报的读取失败必须抛出去(如 OPC UA 的节点 Bad、PLC 错误码)——只有抛才能走"崩溃 → 断开 → 重连"恢复路径,"跳过 + 记日志 + 保留上次值"会掐断重连路径并对下游完全不可见;不要引入质量/可信度概念,要表达可信度就由业务另加一个测点(详见 docs/异常处理.md)。NotImplementedException 的两处合法用途(扩展点"默认实现没覆盖你的组合"、switch 兜底分支)保留不动,详见 docs/异常处理.md。
  • 公开 API 变更时,同步检查 src/StdUnit.Tags.Core/Schemas/tagsproject.xsd(及驱动 XSD)与 README.md 的文件夹/API 说明。

文档