诊断总表(KLSG)

格式:KLSG + 三位数字(SG = 编译期扩展诊断,生成器与分析器共用)。 逐包登记随 nupkg 分发(AnalyzerReleases.{Shipped,Unshipped}.md),家族单一事实源在 .github · RULES.md。

段位分配

段位 面
KLSG001-013 Layout
KLSG045-049 Wire([WireArray] 045-048 + [WireField]/[WireMember] 宿主 049)
KLSG050-053 Wire([WireMessage])
KLSG260-261 Wire([WireMessage] 字段 ID 冲突/越界——#186)
KLSG054-067 Cli
KLSG070-079 Endpoints(另见段位外 240-241)
KLSG080-094 Di
KLSG100-101 Display
KLSG110-112 Query
KLSG130-139、147-154、158-165 Analyzers(147-154 为契约串真值表/禁用模式/迁移指引,158 端序纪律,159-162 异步纪律,163-164 logger 尾随纪律,165 空 catch 说明注释实际占用)
KLSG140-146、155-157 Validation
KLSG200-249 Ef(已用 200-243;244-249 预留)
KLSG250-259 Http

Cli(KLSG054-067)

ID 级别 规则
KLSG054 Error 命令路径冲突(重名/组名遮蔽/Route 覆写相撞/Route 与树内路径相撞)
KLSG055 Error 非法命令名(空名/含路径分隔符)
KLSG056 Error 命令参数未标注([CommandArg]/[CommandOption]/[CommandBody] 三选一)
KLSG057 Error 不可绑定的参数形态(ref/out/in、指针、ref struct)
KLSG058 Error GET 命令带 body
KLSG059 Error 命令标注宿主非法(游离 [Command]/重复标注/[CommandError] 非 Exception/body 超一个)
KLSG060 Error 参数名占用生成器保留前缀(__tcsg_)
KLSG061 Error 嵌套组未链接线且不可实例化
KLSG062 Error 参数类型不在绑定支持集(复杂对象请改 [CommandBody])
KLSG063 Error loom_cli.* 配置键非法(坏值 fail-fast 回退缺省)
KLSG064 Error 描述资源形态不完整(DescriptionKey 与 ResourceType 只给其一——回退链无法落地)
KLSG065 Error ResourceType 缺可访问的 ResourceManager(public 或同程序集 internal)
KLSG066 Error Confirm 命令的自动 --yes 与用户选项冲突
KLSG067 Error [CommandGroup(Options)] 声明非法(嵌套组声明/选项类契约违例)

Endpoints(KLSG070-079)

ID 级别 规则
KLSG070 Error 契约缺标记接口
KLSG071 Error 同动词路由重复
KLSG072 Warning 契约无端点配对(消费工程可关)
KLSG073 Error 切面类型未实现 IAspect
KLSG074 Error 契约结果类型与端点返回类型不一致
KLSG075 Error 端点方法形态非法
KLSG076 Error route 模板路径参数与契约成员不匹配
KLSG077 Error [FromLastEventId] 用于非 SSE 端点或参数类型非 string
KLSG078 Error LoomEndpoints* MSBuild 配置键值非法
KLSG079 Error 切面声明不可解析(派生切面特性无法确定切面类型/实参非编译期常量)

越段续用(#62 入档——Endpoints 无自有空段,续用 Ef 预留块并双方对齐):

ID 级别 规则
KLSG240 Error 序列化底座不支持类型
KLSG241 Error 端点参数无法绑定

Di(KLSG080-094)

ID 级别 规则
KLSG080 Error captive dependency
KLSG081 Error 依赖未登记
KLSG082 Error 多实现无 Default
KLSG083 Error 多个 Default
KLSG084 Error [SingleImplementation] 被违反
KLSG085 Error 标注误用
KLSG086 Error 严格档注册面越界
KLSG087 Warning 登记未消费
KLSG088 Error 依赖环
KLSG089 Warning Transient 实现可释放接口
KLSG090 Warning Singleton 注入 IServiceProvider
KLSG091 Warning 约定表违规
KLSG092 Error loom_di.* 配置键非法
KLSG093 Error 装饰器构造形态非法(装饰器特性无法解析接口/形态不匹配)
KLSG094 Warning 装饰目标生命周期不确定(跨程序集/手写 Opaque 目标;loom_di.decorator_lifetime 可覆盖)

Display(KLSG100-101)

ID 级别 规则
KLSG100 Error [EnumDisplay] 元数据混源——同枚举 [Description] 与 [Display] 并用(歧义)
KLSG101 Error 资源形态不完整(缺 Name / ResourceType 缺公共静态 ResourceManager)——culture 回退链无法落地

Query(KLSG110-112)

ID 级别 规则
KLSG110 Error 类级 [Filterable] 指向不存在或不可公开读的成员
KLSG111 Error 字段显式操作符越集(不在该类型支持集内)
KLSG112 Error 字段类型不在支持集(string/bool/数值/DateTime·Offset/TimeSpan/Guid 及可空;对象成员未标 [EfComplex] 时带点路径指路)

治理(KLSG130-139、147-154、158-165,Analyzers)

规则分析器族逐规则模板(#350——字段:级别/触发条件/违规样例/修正样例/豁免形态/配置键)。 级别为描述符缺省值,消费方一律以 dotnet_diagnostic.KLSGxxx.severity 按路径裁定(生产 error / 测试 none——等级旋钮不逐条重复);loom_* 配置键逐键全参考见 configuration.md, 完整可下载骨架实例见 skeleton.globalconfig。

分层依赖族(loom_layer.*——KLSG130-133)

KLSG130 禁用引用

  • 级别:Warning
  • 触发条件:using 指令或元数据引用命中 loom_layer.forbidden_reference 箭头对左值 → 右值禁列
  • 违规样例:using Contoso.Legacy;(声明 loom_layer.forbidden_reference = Contoso.App => Contoso.Legacy)
  • 修正样例:删除 using,改经防腐层间接访问
  • 豁免形态:无——依赖治理决策不宜自动放行(检测-only 立场)
  • 配置键:loom_layer.forbidden_reference = <左值程序集> => <目标1 | 目标2>(; 分隔多条)

KLSG131 零内部依赖违约

  • 级别:Warning
  • 触发条件:loom_layer.zero_internal_refs 声明的程序集引用了 internal_assembly_prefix 圈定的族内其他程序集
  • 违规样例:Contoso.Contracts(零内部依赖声明)引用了 Contoso.Domain
  • 修正样例:Contracts 只依赖 BCL,数据经调用方注入
  • 豁免形态:无
  • 配置键:loom_layer.zero_internal_refs = <程序集>(必配 loom_layer.internal_assembly_prefix = <族前缀>,缺一即 KLSG139)

KLSG132 引用白名单越界

  • 级别:Warning
  • 触发条件:左值程序集引用了 loom_layer.allowed_reference 白名单之外的目标
  • 违规样例:Contoso.App 引用 Contoso.ThirdParty(不在白名单)
  • 修正样例:治理批准后把目标补进白名单,或移除引用
  • 豁免形态:无
  • 配置键:loom_layer.allowed_reference = <左值> => <白名单1 | 白名单2>

KLSG133 命名空间归属越界

  • 级别:Warning
  • 触发条件:左值程序集内类型命名空间不在 loom_layer.namespace_prefix 指定的归属前缀下
  • 违规样例:Contoso.App 程序集内声明 namespace Contoso.Misc(归属要求 Contoso.App)
  • 修正样例:命名空间改为归属前缀(官方 CodeFix:命名空间声明改为规则首允许前缀)
  • 豁免形态:无
  • 配置键:loom_layer.namespace_prefix = <左值> => <归属前缀>;分析器经 Diagnostic.Properties 传允许前缀给 fixer

禁用模式族(loom_forbidden.pack——KLSG134-138、152)

KLSG134 裸线程原语

  • 级别:Warning
  • 触发条件:pack 含 bare_threads 时构造/调用裸线程原语(new Thread/Timer/SemaphoreSlim/Mutex/ManualResetEvent(Slim)/PeriodicTimer、Thread.Sleep、Task.Run)
  • 违规样例:Task.Run(() => Pump());
  • 修正样例:TaskSink.Submit(_ => Pump());(后台受控任务一律 TaskSink;循环面走 BackgroundWorkerLoop)
  • 豁免形态:loom_forbidden.exempt.bare_threads = <FQN前缀>(实现组件本体);官方 CodeFix 插 pragma(带理由)
  • 配置键:loom_forbidden.pack 含 bare_threads;loom_forbidden.exempt.bare_threads;loom_forbidden.bare_threads.additional(追加类型,精确全名无通配)

KLSG135 热路径分配纪律

  • 级别:Warning
  • 触发条件:pack 含 hotpath_discipline 时,members_with([特性]) 标注方法体内出现 LINQ/装箱/字符串分配(启发式契约——漏报可能不承诺完备)
  • 违规样例:标注方法内 items.Where(x => x.Ok).Count()
  • 修正样例:手写循环 + 计数器(零分配)
  • 豁免形态:作用域由标注圈定——不加标即不入检
  • 配置键:loom_forbidden.pack 含 hotpath_discipline(必配 loom_forbidden.scope.hotpath_discipline = members_with([<特性FQN>]),双向绑定缺一即 KLSG139)

KLSG136 禁止运行时反射

  • 级别:Warning
  • 触发条件:pack 含 reflection 时调用反射面成员(Type.GetMethod 族 / Activator.CreateInstance / Assembly.Load 族 / *Info.Invoke·GetValue·SetValue——接收者语义确认防同名误伤)
  • 违规样例:typeof(C).GetMethod("M")
  • 修正样例:白盒走 InternalsVisibleTo;委托表/源生成替代
  • 豁免形态:官方 CodeFix 插 pragma(带理由)
  • 配置键:loom_forbidden.pack 含 reflection

KLSG137 禁止同步强制等待异步

  • 级别:Warning
  • 触发条件:pack 含 sync_over_async 时的 .GetAwaiter().GetResult() / Task 族接收者 .Wait() / Task·ValueTask 泛型接收者 .Result
  • 违规样例:var v = SendAsync().GetAwaiter().GetResult();
  • 修正样例:var v = await SendAsync();(官方 CodeFix 改 await——仅 async 作用域内给修复)
  • 豁免形态:loom_forbidden.exempt.sync_over_async = <FQN前缀>;CodeFix 插 pragma
  • 配置键:loom_forbidden.pack 含 sync_over_async;loom_forbidden.exempt.sync_over_async

KLSG138 禁止丢弃 Task/ValueTask

  • 级别:Warning
  • 触发条件:pack 含 fire_and_forget 时的 _ = Task族表达式 / var _ = 声明 / 表达式语句裸调用(CS4014 的治理替代面)
  • 违规样例:_ = SendAsync();
  • 修正样例:TaskSink.Submit(_ => SendAsync());(ValueTask 走 SubmitFast——池化 token 不归还更危险)
  • 豁免形态:loom_forbidden.exempt.fire_and_forget = <FQN前缀>;CodeFix 改 TaskSink(编译内可解析 TaskSink 才给)
  • 配置键:loom_forbidden.pack 含 fire_and_forget;loom_forbidden.exempt.fire_and_forget

KLSG139 分析器配置非法

  • 级别:Error(CompilationEnd)
  • 触发条件:任意 loom_* 键未知/坏令牌/坏值/规则依赖双向缺失/同键异值冲突——fail-fast 绝静默
  • 违规样例:loom_forbidden.pack = bogus
  • 修正样例:改合法令牌(逐键见 configuration.md 全键参考)
  • 豁免形态:无——配置错误必须修
  • 配置键:全部 loom_.

KLSG152 零拷贝丢失

  • 级别:Warning
  • 触发条件:pack 含 zero_copy_loss 时,ROM/ReadOnlyMemory 源上的 .ToArray() 且结果赋给同型 ROM 变量或传给 ROM 参数(高信号形态;byte[] 目标 = 合法拷贝不报)
  • 违规样例:ReadOnlyMemory<byte> copy = rom.ToArray();
  • 修正样例:保持 ROM 一路透传(Wire 分派面);确需物化才显式 ToArray
  • 豁免形态:无(启发式契约——仅报高信号)
  • 配置键:loom_forbidden.pack 含 zero_copy_loss

契约真值表族([StringContract] 标注驱动——KLSG147-151)

KLSG147 契约串 scheme/前缀形态非法

  • 级别:Warning|触发条件:[StringContract] 常量串 scheme/前缀不符合真值表 DSL 形态|违规样例:缺 scheme 段的契约串|修正样例:补 scheme/前缀段|豁免形态:pragma 带理由|配置键:无(标注驱动)

KLSG148 契约串参数名未知

  • 级别:Warning|触发条件:契约串引用真值表未声明的参数名|违规样例:@{unknownParam}|修正样例:补参数声明或改名|豁免形态:pragma 带理由|配置键:无

KLSG149 契约串参数×域矩阵违规

  • 级别:Warning|触发条件:参数组合落在真值表矩阵禁用格|违规样例:矩阵禁用格组合串|修正样例:改组合或扩矩阵|豁免形态:pragma 带理由|配置键:无

KLSG150 契约串参数值域违规

  • 级别:Warning|触发条件:参数值不在 Values= 声明值域|违规样例:level=9(值域 1-3)|修正样例:改值或扩值域|豁免形态:pragma 带理由|配置键:无

KLSG151 契约串参数交叉约束违规

  • 级别:Warning|触发条件:违反 Requires/Excludes 交叉约束|违规样例:a=1 而未满足 a=1 => b|修正样例:补齐被要求参数|豁免形态:pragma 带理由|配置键:无

迁移指引族(KLSG153-154)

KLSG153 QueryFieldCatalog.Build 迁移

  • 级别:Warning
  • 触发条件:调用过时的 QueryFieldCatalog.Build(typeof(契约))
  • 违规样例:QueryFieldCatalog.Build(typeof(OrderFilter))
  • 修正样例:new OrderFilterFilterIndex().ToCatalog()(官方 CodeFix 自动改写)
  • 豁免形态:pragma 带理由
  • 配置键:无

KLSG154 [Entity] 迁移

  • 级别:Warning
  • 触发条件:类型标注旧 [Entity](EfEntity 前代)
  • 违规样例:[Entity] public class Order(Ef 面)
  • 修正样例:[EfEntity(typeof(Db))](官方 CodeFix 改标注)
  • 豁免形态:pragma 带理由
  • 配置键:无

端序纪律族(KLSG158,常开)

KLSG158 端序敏感调用不在 ManualEndian 豁免面

  • 级别:Error
  • 触发条件:BinaryPrimitives 端序族 104 方法 + MemoryMarshal.Read/Write/Cast<byte,T> 调用点不在 [ManualEndian] 标注面(成员或外层类型任一标注即豁免;生成器发射面自带标注)
  • 违规样例:BinaryPrimitives.WriteInt32LittleEndian(span, 5);(无标注面)
  • 修正样例:成员/类型标 [ManualEndian](语义确认本处确实端序敏感),或走 ScalarAccessors
  • 豁免形态:[ManualEndian] 特性——零配置豁免面(豁免必须显式声明语义)
  • 配置键:无(常开)

异步纪律族(loom_async.*——KLSG159-162)

KLSG159 异步方法缺 Async 后缀

  • 级别:Warning
  • 触发条件:返回 Task/ValueTask(含泛型与派生)/IAsyncEnumerable/IAsyncEnumerator(含派生接口)的方法名不以 Async 结尾
  • 违规样例:public Task DoWork() => Send();
  • 修正样例:public Task DoWorkAsync() => Send();(官方 CodeFix 方案级重命名——调用点同步改)
  • 豁免形态:override/接口实现/Main/GetAsyncEnumerator 自动豁免;loom_async.exempt.naming_suffix = <FQN前缀>
  • 配置键:loom_async.pack 含 naming_suffix;loom_async.scope.namespace = <前缀列表>(与 pack 双向绑定必配)

KLSG160 非异步方法带 Async 后缀

  • 级别:Warning
  • 触发条件:方法名以 Async 结尾且返回类型非可等待且非 async 关键字(误导调用方预期可等待)
  • 违规样例:public void ParseAsync() { }
  • 修正样例:public void Parse() { }(官方 CodeFix 方案级重命名)
  • 豁免形态:override/接口实现自动豁免;loom_async.exempt.naming_reverse
  • 配置键:loom_async.pack 含 naming_reverse;scope

KLSG161 async 方法返回 void

  • 级别:Warning
  • 触发条件:async 方法返回 void(异常不可观测、调用方无法等待)
  • 违规样例:public async void DoWorkAsync() => await Send();
  • 修正样例:public async Task DoWorkAsync() => await Send();(官方 CodeFix 改返回类型)
  • 豁免形态:事件处理器形态((object?, EventArgs 派生) 双参)自动豁免——void 是事件签名唯一形态;loom_async.exempt.async_void
  • 配置键:loom_async.pack 含 async_void;scope

KLSG162 末参数应为 CancellationToken

  • 级别:Warning
  • 触发条件:可等待返回方法缺 CT 或 CT 不在末位;ct 必填与 ct = default 可选都合规(不校验默认值);重载对不做同族豁免(本方法参数面判定)
  • 违规样例:public Task SendAsync(string s) => SendCore(s);
  • 修正样例:public Task SendAsync(string s, CancellationToken ct = default) => SendCore(s);(官方 CodeFix 末位追加;CT 错位形态仅检测——改参顺序破坏位置实参调用点)
  • 豁免形态:override/接口实现/Main 自动豁免;loom_async.exempt.ct_last_param
  • 配置键:loom_async.pack 含 ct_last_param;loom_async.ct.parameterless = require | allow(零参方法口径,默认 require);scope

装配注入点 logger 尾随族(loom_logger.*——KLSG163-164)

KLSG163 可空可选 logger 族参数不在尾随块

  • 级别:Error(常开——对齐 KLSG158 先例)
  • 触发条件:可空可选 logger/factory 族参数(= null 形态=装配注入点标志)后仍存在非注入位参数,或 logger 排在 factory 之前(factory 创建 logger——主依赖在前、logger 恒最后)
  • 违规样例:public C(string name, ILogger? logger = null, int retries = 3)
  • 修正样例:public C(string name, int retries = 3, ILogger? logger = null)(官方 CodeFix 重排声明——⚠️ positional 调用点源破坏自修)
  • 豁免形态:扩展方法/必填 logger/合成成员自动豁免;类型集经 loom_logger.types/loom_logger.factory_types 配置(MEL 内置+追加;泛型闭合自动匹配;拒绝参数名启发式)
  • 配置键:loom_logger.types、loom_logger.factory_types

KLSG164 带参构造无 logger 族依赖

  • 级别:Info(suggestion 位)
  • 触发条件:[RequireLoggerInjection] 标注类型的实例构造 ≥1 参数且 logger/factory 任一形态均不在场
  • 违规样例:public C(string name, int retries = 3)(标注类型内)
  • 修正样例:public C(string name, int retries = 3, ILogger? logger = null)(官方 CodeFix 尾补——候选类型分析器按编译可解析序裁定)
  • 豁免形态:零参构造不入射程;未标注类型零报告("构造不传 logger"是正常写法——执法面 opt-in 显式圈定);标注不随继承传导(Inherited = false)
  • 配置键:无(执法面 = 类型级特性标注,KernLab.Loom.Abstractions 内置 [RequireLoggerInjection];loom_logger.scope.namespace 已移除——声明即 KLSG139 fail-fast)

吞没纪律族(KLSG165,常开零配置)

KLSG165 空 catch 缺说明注释

  • 级别:Error
  • 触发条件:catch 体为空且无伴随说明注释(catch 上一行/行尾/块内注释任一在场即合规——存在性判定,不判质量)
  • 违规样例:catch (ObjectDisposedException) { }
  • 修正样例:catch (ObjectDisposedException) { } // ★ 与 Stop 竞速——已释放 = 排干已无意义(写明为什么安全)
  • 豁免形态:无——无说明的空 catch 无可辩护形态;生成代码不分析
  • 配置键:无(常开零配置)

Validation(KLSG140-146、155-157)

ID 级别 规则
KLSG140 Error [Range] 标注在非数值属性上(含 Type 重载边界)
KLSG141 Error [RegularExpression] 正则预解析失败——写错即编译错误,不等到运行时
KLSG142 Error 校验器契约未声明端点——配对悬空(T2 接线无槽位)
KLSG143 Error IValidatable 实现带 I/O 形态(纯函数逃生口不准有副作用)
KLSG144 Error 契约校验图含环(嵌套递归不可收敛)
KLSG145 Warning DataAnnotations 注解不在 T1 支持集或标注类型不匹配(绝静默)/RequiredIf 标注在非可空值类型上(恒存在,不生成规则)
KLSG146 Warning ErrorMessageResourceType/Name 本地化形态不完整(回退字面量/缺省文案)
KLSG155 Error 交叉字段比较目标无效(缺失/不是字段或属性/自引用/不可读)
KLSG156 Error 交叉字段比较两侧类型不可比较(核心类型不匹配或不在支持集)
KLSG157 Error 条件必填标志无效(缺失/不是字段或属性/自引用/不可读/类型非法)

Ef(KLSG200-249)

已用 200-242;250-259 归 Http(段位边界见 RULES.md 与上方段位分配表)。

上下文绑定与实体形态:

ID 级别 规则
KLSG200 Error 实体缺主键
KLSG201 Error 租户实体绑定到未挂租户约定的上下文(配对锁)
KLSG202 Error 多上下文绑定歧义
KLSG203 Error 绑定目标非 DbContext
KLSG204 Error 键策略与键类型冲突
KLSG205 Error AuditTrail 特征无 sink 可落
KLSG206 Error 列名覆盖与真实属性撞名
KLSG207 Error 同实体同上下文重复绑定
KLSG208 Error 绑定上下文不可合并(非本源声明)
KLSG210 Error 同实体混用绑定形态 / 名称绑定歧义
KLSG212 Error 组合键序号非法
KLSG213 Error 组合键与键策略并标
KLSG221 Error watch 字段缺失或处理器签名不匹配
KLSG224 Error ILoomDbContext 壳的基类非 DbContext
KLSG243 Error 上下文须声明在命名空间层——嵌套 DbContext 不支持生成合并(#342 防呆)

查询治理与投影:

ID 级别 规则
KLSG211 Warning IgnoreQueryFilters 全量旁路(配合运行时政策,缺省 Throw)
KLSG214 Warning 裸逃逸口调用(raw SQL / 批更新 / 批删——配合白名单)
KLSG215 Error 并发机制重复声明
KLSG216 Warning 投影成员无匹配
KLSG217 Error/Warning 投影成员类型有损转换(不可无损转换)
KLSG218 Error 投影别名目标缺失
KLSG219 Error 投影绑定到未注册实体
KLSG220 Error 同上下文表名冲突(命名策略转换后同名同拦)
KLSG232 Warning 投影成员引用 [EfNotMapped] 源成员

动态视图与声明词汇(DCL):

ID 级别 规则
KLSG222 Warning 视图 SQL 引租户表无租户谓词
KLSG223 Error 视图引用名无法解析
KLSG225 Error 实体内唯一索引名冲突
KLSG226 Error 统一列特性与细粒度特性同维度双标(二选一)
KLSG227 Error 常量默认与 SQL 默认双设
KLSG228 Error 精度声明非法(非 decimal / scale > precision)
KLSG229 Error 写一次标在键/并发戳属性
KLSG230 Error 计算列与可写声明冲突
KLSG231 Error [EfNotMapped] 与映射声明冲突
KLSG233 Error 默认值字面量无法按属性类型解析

继承与 ComplexType(INH / CT):

ID 级别 规则
KLSG234 Error 鉴别器定制与 Tpt/Tpc 策略互斥
KLSG235 Error 继承策略标在派生实体(须基类根)
KLSG236 Error 复杂类型集合形态不支持(指路 [EfJson])
KLSG237 Error ComplexType 与 [EfJson] 同属性双标
KLSG238 Error 复杂类型成员标 [EfKey](无键)
KLSG239 Error 复杂类型嵌套超深(上限 4)
KLSG242 Warning 冻结模型过期——optimize 产物缺当前实体映射成员(重跑 loom ef optimize)

Http(KLSG250-259)

ID 级别 规则
KLSG250 Error 空客户端契约([HttpApi] 接口无任何动词标注方法——P2 接口主形态)
KLSG251 Error 路由模板与参数不匹配(占位符无参数 / [Path] 无占位符 / catch-all 非 string / 可选段非可空)
KLSG252 Error HTTP 契约类型不在支持集(返回/参数/序列化闭包不可达——P2 边界:流/集合结果/SSE 归 P4)
KLSG253 Error 请求头声明非法([HttpHeader] 名/值空或含换行)
KLSG254 Error 请求体绑定非法(多 [Body] / 无体动词带 [Body] / 有体动词缺 [Body])
KLSG255 Error 参数形态不支持(多绑定特性/未标注复杂类型/重复查询名/[Query] 非标量或集合/[Header] 非 string)
KLSG256 Error 表单绑定非法([FormFile] 用于非 Multipart / 表单方法未标注模式 / 表单参数类型不在支持集)
KLSG257 Error 接口方法形态非法(非 public/静态/泛型/ref-out/重载/缺动词标注/同名客户端冲突)
KLSG258 Warning 未提供 Service/BaseAddress(须由 AddLoomHttpClient 的 LoomHttpOptions.Services 补全)
KLSG259 Error [HttpApi] 记录形态非法(非 record / 缺 IHttpApi<TResult>)

基础面

ID 面 规则
KLSG001-014 Layout 标注用法/字段/布局/校验/嵌套/OrFlags·IsEmpty 目标/union 判别(014——#194)/生成失败
KLSG045-049 Wire [WireArray] 族(045-048)+ [WireField]/[WireMember] 宿主(049)
KLSG050-053 Wire [WireMessage] 族
KLSG260-261 Wire [WireMessage] 字段 ID 冲突/越界(#186)
KLSG054-067 Cli 命令面规则(见上方 Cli 段明细)
KLSG140-146 Validation 校验段(见上方 Validation 段明细)
KLSG250-259 Http 声明式 HTTP 客户端(见上方 Http 段明细)

消费方纪律

  • 严重级按路径声明:
[**/*.cs]
dotnet_diagnostic.KLSG087.severity = none        # 测试/探针按需关闭
  • Warning ≠ 可忽略——家族零警告红线下 Warning 同样致命,"可配置关闭"才是其语义。
  • 受控豁免用 #pragma warning disable <ID> 并注明理由;改名时必须同步 pragma 里的 ID。
  • 新增规则两步:包内 AnalyzerReleases 登记 + 家族 RULES.md 补行。