Team.LightControl

面向 .NET Framework 4.8 和现代 .NET 的光源控制 SDK。使用端只提交全局通道编号；SDK 按控制器实例分组，独立连接并行，同一控制器内按批次互斥执行。

当前正式版本为 1.0.2，已包含 KCS 实测探测应答格式、KDC3 实测拼接写入帧（1.0.1）及按 KDC-12V60W-4T 手册修正的 4T 写入协议与写入应答校验（1.0.2）。

包结构

按需安装 1.0.2 品牌包即可，NuGet 会引入同版本的公共依赖。本库没有 WPF、Prism、海康 VM、数据库或配置文件路径依赖。现代 .NET 使用 netstandard2.0 资产；自动验证覆盖 Windows 的 .NET Framework 4.8 和 .NET 10。KDC3-24V300W-8T 已记录实测串口探测与批量写入报文，KDC-12V60W-4T 写入协议按手册实现；其他型号、固件和运行环境仍按现场配置确认。

使用

using Team.LightControl;
using Team.LightControl.Communication;
using Team.LightControl.Drivers.Kcs;

using var service = new LightService();
service.RegisterController(
    controllerId: 1,
    driver: KcsLightController.CreateSerial(
        KcsModel.Kdc12V60W4T,
        new SerialConnectionOptions("COM3", baudRate: 19200)),
    mappings: new[]
    {
        new ChannelMapping(10, 0), new ChannelMapping(20, 1),
        new ChannelMapping(30, 2), new ChannelMapping(40, 3)
    });

var connections = await service.ConnectAllAsync(cancellationToken);
// 必须检查每个连接的 IsSuccess / Error。
var result = await service.ApplyAsync(new[]
{
    new GlobalChannelUpdate(10, brightness: 120, enabled: true),
    new GlobalChannelUpdate(20, brightness: 130, enabled: true),
    new GlobalChannelUpdate(30, brightness: 140, enabled: true),
    new GlobalChannelUpdate(40, brightness: 150, enabled: true)
}, cancellationToken);

// result.IsSuccess、Channels 和 Controllers 提供逐通道结果与命令数、耗时。
await service.SetEnabledAsync(10, false, cancellationToken);
await service.DisconnectAllAsync(cancellationToken);

同一个 LightService 继续注册其他品牌、其他连接上的设备即可。业务代码仍然只使用全局通道编号。实际通道索引统一从 0 开始；驱动负责转换协议地址。

GlobalChannelUpdate 的亮度/开关可以单独提供，未指定字段保持原状态。亮度为设备原始值，当前型号范围 0..255。连接后输出状态可能未知；KCS 首次设置请同时明确提供亮度和开关。开启尚无已知目标亮度的通道会返回 UnknownState，不会默认点亮为 100。

关闭 KCS 通道统一写入 0000：实测 F 标记加记忆亮度的写法设备返回正常应答但并不熄灭（按帧内亮度值输出），手册兼容指令亦无 F 标记。目标亮度保留在本会话快照中，再次开启（不带亮度）自动恢复该目标。断开、重连或不确定写入会使缓存失效，重新应用完整目标状态。TSD 保留原工程的开关命令和“开启后设置亮度”顺序。

批次语义

1. 一次 ApplyAsync 表达一个明确的业务批次。重复编号、未知通道、越界亮度或空变更会拒绝整批，且不发送命令。
2. 按控制器实例分组，独立端点异步并行；同一控制器的整个批次互斥，命令不会被其他批次穿插。异步锁不承诺严格 FIFO。
3. KCS 原生批量使用拼接帧：按通道序拼接逐通道子命令（每个以 '#' 结尾）一次串口写入，支持任意通道子集与混合开关，亮度可以各不相同。4/8/16 通道均适用。
4. KCS 可通过 enableNativeFullFrame: false 禁用原生批量，改用逐通道顺序执行。TSD 使用逐通道回退（先开后调亮），不扩展写入到未参与请求的通道。
5. 单个控制器出现错误后停止该组剩余操作；其他控制器继续完成。业务收到全部组的结果后再决定是否拍照。
6. 取消以逐通道结果返回：保留已确认项，未开始项为 NotExecuted，在途写入不确定时为 Unknown。取消和跨设备失败不会自动回滚已完成操作。
7. 成功注册后服务拥有驱动。成功注册前校验失败的驱动仍由调用方释放。所有注册、映射修改和注销仅允许在服务无在途操作时执行；服务释放会取消在途驱动操作并关闭资源。
8. 全局编号不自动重新分配。当前每个物理端点只允许注册一个控制器，拒绝重复 COM 口/端点；多地址共享总线调度留待后续型号接入时实现。

逐通道结果包括 Confirmed、Failed、PartiallyApplied、Unknown、NotExecuted。CommandAcknowledged 仅表示命令确认；不代表逐通道回读或光学测量。TSD 输出开关状态不会通过亮度是否大于零来推断。

多个控制器的并行不保证硬件同步点亮。拍照流程共享通道时，业务需从应用光源到采图完成持有相应的资源占用，并在全部必要通道成功及稳定时间满足后拍照。

通信和设备验证边界

传输由 ICommandTransport 隔离。串口使用标准 System.IO.Ports，有界读取在后台执行；完整帧到达立即返回，无 100ms 空闲分包等待。TCP 使用异步流收发。超时、在途取消、截断/异常响应会关闭会话，防止迟到回复被下一条请求使用；不会自动重试写命令。

KCS 所有型号默认按 5 字节探测应答解析，兼容实测的 A0073（通道字母在首位，末 3 位表示亮度 73）和旧格式 ?ADDD（通道字母在次位）。读取命令按型号区分：KDC-12V60W-4T 用 SA#，KDC3/KDC4 用 SRA#（与旧工程一致）。写入：开用 4T 手册裸格式 S<字母>0XXX#（KDC-12V60W-4T）或实测 S<字母><DDDD>T# 标记（KDC3/KDC4）；仅设亮度和关闭统一裸格式，关闭写 0000（实测 F#+记忆亮度设备不熄灭）。写入应答同时接受通道字母序列（KDC3 实测，如 ABCDEFGH）与每子命令一个 !（4T 手册，如 !!!!），字母序列大小写不敏感。使用旧 7 字节探测格式的固件可通过构造函数显式指定 readResponseLength: 7。TSD 使用 8 字节 ASCII 帧和动态 XOR 校验，写应答要求匹配命令回显。不同型号与固件的具体格式以现场手册和真实报文为准。

内部通信超时会报告包含时限的明确错误信息，外部取消保留独立错误码，原始异常保存在 InnerException。回归测试分别验证内部超时和主动取消，避免把超时误读为用户取消。

ConnectAsync 会进行只读协议探测，探测成功后才就绪，不主动设置设备输出。配置保存、UI 数据绑定、产品配方和参数审计由应用层负责。

构建、测试和打包

Windows、.NET SDK 10.0.402（同补丁系列可滚动）。测试和示例包含 net48 与 net10.0 两个目标。

dotnet build Team.LightControl.sln -c Release
dotnet test tests/Team.LightControl.Tests -c Release
dotnet run --project samples/Team.LightControl.ConsoleDemo -c Release -f net10.0
./scripts/Pack.ps1

模拟示例使用真实驱动和虚拟传输，不连接硬件。Pack.ps1 默认从 Directory.Build.props 读取统一版本，依次构建、执行双框架测试、生成四个 NuGet 包，检查嵌入图标，并在隔离缓存中通过纯 PackageReference 消费验证，最终生成 SHA256 清单和 ZIP。不会上传包或使用发布凭据。

输出目录：artifacts/packages/。可以直接将此目录添加为本地 NuGet 源。需要使用的品牌包及其公共依赖都要上传到私有源。

包图标

四个包共享根目录的 icon.png，通过 PackageIcon 指向包内图标，无需外部图片服务。图标为 128x128 像素、透明背景 PNG，小于 1MB，符合 NuGet 官方图标规范。打包验证会检查四个包的图标声明、PNG 格式、尺寸、文件大小和内容一致性。

原图由内置 imagegen 生成，保存在 assets/branding/icon-source.png；完整提示词见 assets/branding/icon-prompt.txt。Windows 下可运行 ./scripts/Export-PackageIcon.ps1 重新导出 128x128 图标。只将小尺寸图标嵌入 NuGet 包。

实施计划见 docs/IMPLEMENTATION_PLAN.md，原项目接入说明见 docs/MIGRATION.md。