纯VibeCoding了个KC761的HA集成，全程未手写一行代码

### 1. 给 KC761 找个新去处

给大家分享一个折腾出来的小项目：**把 KC761 接进 Home Assistant，在仪表盘里看读数、看能谱，顺手把历史存下来。** 仓库叫 `kc761-ha`，集成名称是 `KC761x`。

先交代一下开发方式：**项目自身的代码完全通过 ChatGPT vibe coding 生成和迭代，不是我逐行手写的。** 仓库由我维护，这里也把代码来源说明白。这个说法不包括 ECharts 等随附的第三方库，它们仍然来自各自的项目。

连接可以走局域网 TCP，也可以走低功耗蓝牙（Bluetooth LE，下面简称 BLE），不通过科创云中转。这帖按 **v0.2.0** 来介绍，要求 **Home Assistant 2026.7.0 或更新版本**，通过 HACS 自定义仓库安装。

项目地址：

```text
https://github.com/GImDX/kc761-ha
```

### 2. 接进去以后能玩些什么

**把读数和设备状态放进 HA**

电量、温度、气压、设备时间，以及已安装通道的计数率、剂量率、剂量当量率、累计时间和累计量，都可以在 HA 里查看。通道实体按设备实际报告的配置创建，没有装的通道就不凑数了。

想知道当前选了哪个通道、音量和背光是什么状态、自动上传有没有开，也有独立的只读实体，**不用为了看状态先打开控制权限**。另外还可以读取 41 项 A6 校准字段，不过这里只是查看，不能修改校准参数。

**在仪表盘里直接看能谱**

集成自带基于 ECharts 的 **KC761 Spectrum** 卡片，装好后会自动注册，在“添加卡片”里选它就行，不用再手填前端资源地址。

卡片支持线性/对数轴、感兴趣区间（ROI）、数据游标和 CSV 导出。想仔细看看某一段谱峰，可以把鼠标移过去，用 **Ctrl + 滚轮横向缩放、Shift + 滚轮纵向缩放**，两者都围绕光标进行；看完双击绘图区复位。

道数也不用手选，集成会根据收到的片段自动适配。软件层面支持 **1024、2048、4096 道候选**；注意，这不是说三种道数的实机都已经测过，后面会说明验证范围。

**把谱图存下来，过后再看**

支持手动或定时保存谱图，再从卡片里切换历史快照。每个配置条目在本地最多保留 **256 份**，需要长期留存或拿去继续分析的，可以导出 CSV。

这里分两条路：普通传感器读数走 HA 的历史记录，完整谱图另存为本地快照。完整点阵不写入 Recorder，也不会把每一道都拆成一个实体。

**默认先看数据，控制另外开**

新建及缺省配置默认关闭设备写入，可以先读取数据、刷新和保存谱图。要操作设备，得单独开启控制；要清空谱图、剂量曲线或累计剂量，还得再开一层清除权限。

**清空设备统计数据不可恢复，别把它当成普通的“刷新”按钮。** 校准写入没有实现，也没有任意原始命令入口。另外，升级会保留此前明确开启的选项，不会替你把已开的控制重新关掉。

### 3. 怎么装

准备好 **Home Assistant 2026.7.0 或更新版本**和 HACS。用 TCP 时，要让 HA 能访问仪器的实际 IP 地址和端口；用 BLE 时，要确保 HA 的 Bluetooth 能发现并连接仪器。

1. 在 HACS 自定义仓库中添加 `https://github.com/GImDX/kc761-ha`，类型选择“集成”。
2. 下载 KC761x，重启 Home Assistant。
3. 进入“设置 → 设备与服务 → 添加集成”，搜索 `KC761x`。
4. 选择 TCP 或 BLE。TCP 填实际地址和端口；BLE 可以从可连接设备列表中选，也可以手动填地址，然后完成连接预检。
5. 打开仪表盘，在“添加卡片”中选择 `KC761 Spectrum`。

第一次接入，先保持设备控制关闭，看看设备信息、读数和能谱是不是正常。

还有个选项值得提一下：**“创建原始读数实体（每个已安装通道 3 个）”**。打开后，会多出原始 CPS、原始剂量率和原始剂量当量率三个只读实体。

这里的“原始”指仪器报告的上一秒读数，不是原始通信帧，也不是开启后就每秒刷新；**它只增加实体，不提高轮询频率**。设备端平均值还有一个已知情况，下面一起说。

### 4. 里面大致怎么跑

数据大致走这么一条路：

```text
KC761 TCP / BLE 接口
        ↓
字节流拆帧、响应匹配、字段解码和谱图重组
        ↓
Home Assistant DataUpdateCoordinator
        ↓
设备实体 / 能谱卡 / 本地谱图存档 / CSV 导出
```

每个配置条目只维持一条活动连接，由 Coordinator 统一处理轮询、谱图请求、重连和资源释放。各个实体读取同一份内存快照，不会各自去向设备要一遍数据。

谱图要先经过分片重组，内部有缺洞或数据冲突的，不会直接拼一张图拿来显示。图表库随集成本地分发，画谱也不依赖外部 CDN。

### 5. 哪些地方还得留个心

**测过哪些，就说哪些。**

v0.2.0 的发布记录里有 169 项测试通过，综合覆盖率为 97.49%，独立分支覆盖率为 95.34%，对应发布提交的 CI 也已通过。但软件测试通过，不等于所有型号的仪器都跑过一遍。

现有有限实机记录覆盖 TCP、BLE 的完整 2048 点谱图接收、TCP 恢复、真实 Gamma 谱图存档及对应 CSV 一致性等项目。实际 1024/4096 点设备、其他型号和固件、中子传感器，还需要继续验证。因此协议档案仍保留 `hardware_verified=false`，不把有限的实机结果说成全系列兼容。

**道数能自动适配，不代表能凭空知道尾片有没有丢。**

A0/A1 谱图片段没有明确的总道数或结束字段，长度只能根据本次收到的数据观测或推断。即使已收到的部分连续，也不一定能排除尾部片段缺失。卡片、存档和 CSV 都会保留相关判定信息，不把推断结果当成硬件能力确认。

**平均值为 0，不一定是接入没成功。**

在已验证的一台设备上，设备端三个 AVG 字段持续为 0，而官方上位机是自己计算 30 秒平均值。本集成保留设备返回的值，不把上位机的计算结果当作设备字段。需要看实时读数，可以打开前面说的原始读数实体；这里描述的是这台设备的已知情况，不代表其他设备遇到 0 都是同一个原因。

**看数字之前，先看一眼单位。**

剂量率和剂量当量率固定用 `mGy/h`、`mSv/h`，累计量固定用 `mGy`、`mSv`，没有单位切换选项。拿它和显示微单位的界面比较时，要先统一单位，别只比数字大小。

串口、科创云、区间谱、A4 脉冲流/瀑布图和校准写入，都不在这个版本的范围内。尚未完成实机验证的控制或清空操作，不应直接用于生产设备。这个项目做的是数据接入、展示和存档，不是给仪器重新做测量认证。

### 6. 欢迎同款设备的坛友一起折腾

集成代码采用 **MIT 许可证**，ECharts 等第三方组件按各自许可证使用。仓库里也放了架构、实体模型、安全边界、协议证据和版本说明，想看实现细节的可以往里翻。

有相同设备的坛友欢迎交流，尤其欢迎不同型号、不同固件的兼容性反馈。碰到问题可以直接回帖，也可以开 GitHub Issue；带上设备型号、固件版本、HA 版本、集成版本、TCP/BLE 连接方式，再说清楚操作和现象，会更容易定位。

贴截图或日志之前，记得先遮掉完整设备 ID、网络地址和凭据。

项目先分享在这里。欢迎挑 bug，也欢迎聊聊还有哪些读数、谱图操作值得接进 HA。