面向在本仓库中工作的 AI 编码代理。人类用户文档见文末「文档」。
面向工业硬件交互的 .NET 类库家族(net8.0,MIT,跨平台)。核心模型:
测点项目 ITagsProject = 通道 ITagChannel + 测点树 ITagGrp + 逻辑 ILogicet
每个 isEntry="true" 的测点组分配一个 ITagGrpRunner,按串行轮询运行:
【执行意图 → 读取输入 → 处理逻辑 → 刷写输出】。入口之间并行,入口内部严格串行。
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 ./TestResultsCI(.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-smokejob 要在 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-smokejob)。
- 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),绝不能出现在任何发布包的依赖里。
- 公开面 = 接口 + DI 扩展 + 工厂/构建器。
TagsProject、TagsProjectCtrl、TagGrpRunner、TagGrpRunnerFactory、LogicetLoader、SimpleFilesDirectTagFactory等具体实现一律internal。不要把新的具体实现暴露成 public——用户代码只应通过接口 + DI 使用。 - 入口内严格串行。
ILogicet.ProcessAsync与TagGrpWriteIntent都跑在轮询线程上,必须尽快返回。不要在这些路径上同步阻塞(.Result/.Wait()/Thread.Sleep),也不要把这些回调改成"等待外部事件"的形态——那会与WriteIntent构成环路等待死锁。 - 一个
ITagChannel实例只能属于一个入口。 运行器崩溃/取消时会断开入口子树中的全部通道(DisconnectAllAsync),EntryChannelExclusivityValidator依赖此约束。改动清理逻辑时务必保持该语义。 - 库不做任何隐式数值转换。 测点值类型必须精确匹配(
short不能写给int)。GetTagValue<T>()是硬转换,不做兼容处理。 ITag.Channel是只读属性(ITagGrp.Channel/ITagCbnt.Channel可读写);ITagGrp.IsDirty()是方法,而ITag.IsDirty/ITagCbnt.IsDirty是属性。这些不统一之处是刻意为之(比如ITagGrp是否已经是脏数据只依赖于其任意子节点是否已脏)。- 校验器默认值:4 个代码校验器(跨引用、驱动工厂、入口通道独占、嵌套入口)在
UseDefaults = true下默认开启;XSD 校验(EnableXmlSchemaValidation())默认关闭(opt-in)。 - 解析大小写敏感度:
EndianKinds/TagAccessMode(LittleEndian、R1W…)大小写敏感;isEntry/isEnabled不敏感。测试常覆盖这些边界。 IntentCapacity必须 > 0,且只能在RunAsync之前设置。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"表达。- 启动是两阶段的(先算后启,事务性):
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。
- 警告:这个坑在 WSL 里测不出来——
- 驱动包内的 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→OpcUaClientTagChannelctor,默认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 说明。
- AI 参考手册(事实清单 / 铁律 / XML 与 API 速查 / 任务配方):https://tags.doc.stdunit.com/assets/999.AI.markdown
- 教程站点:https://tags.doc.stdunit.com/
- 整站单页版:https://tags.doc.stdunit.com/print.html