PulseOps 复盘——设备工单 Agent,为什么终点是「关单」而不是「看见异常」
仓库:lau0708/pulseops · Node 20 / React 19 / Python · TypeScript · 飞书卡片
一句话:从「巡检发现异常」到「这张单被谁、在什么时候、用什么办法关掉」的可审计闭环。
一、背景:没人盯得住 24 小时的曲线
一条产线 4 台设备,值班的是班组长和 2 个维修工。异常通常在「已经停机之后」才被发现,工单靠口头传,处置结果留在师傅脑子里。很多「设备大屏」的终点是看见异常,很热闹;但看见之后呢?谁去处理、结果记在哪、下次同类故障能不能直接查到——这些才是真正决定价值的部分。
所以 PulseOps 的定位是把后半截做成闭环,而不是再做一块更漂亮的大屏。三个入口收敛到同一条链路:定时巡检(主线)、人工问诊(「3 号机振动不对」)、班次简报(收班时汇总这一班有没有留坑)。
二、确定性骨架 + 两个 LLM 节点,而不是「全交给模型」
链路里每一环的性质不同,分层切得很硬:巡检、阈值判异、幂等去重、状态流转、推送、沉淀、留痕,全部用普通代码;只有「根因假设与处置方案」「自然语言问诊解析」这两个不可穷举的点交给 LLM。
收益很直接:模型只做判断,不碰写操作。建单、改状态、推送都由代码执行,模型吐出的每个数字都能在 mes.db 里对账;模型挂了、key 失效、返回坏 JSON(重试 1 次后)都降级为知识库关键词命中,巡检循环不中断。
同一条告警,LLM 模式与降级模式的实测差异,正好说明「有模型」和「可靠」是两件事:
LLM 根因=主轴轴承磨损复发,振动 12.7 mm/s 超 8.0 阈值 置信度 0.85 降级 根因=主轴轴承磨损 置信度 0.80
健康设备进同一个节点时,LLM 输出「无异常证据,不编造根因」,置信度回落到 0.5——这条是防幻觉的验收项。
三、幂等:应用层检查省钱,数据库级约束保命
巡检定时跑,同一台劣化设备会连续 N 轮越限。每轮都建单,维修班会被刷屏,工单表会烂掉。所以「一台设备同时只允许一张未闭环单」落了两层:入口先查一次,命中就跳过(顺便省掉一次 LLM 诊断调用);建单函数再兜一次,返回 deduplicated: true。但代码检查挡不住并发——巡检进程和 API 进程可能同时查到「没有未闭环单」。
最后落了一道数据库级不变式,部分唯一索引:
CREATE UNIQUE INDEX ux_work_order_open
ON work_order(equipment_id) WHERE status IN ('open','assigned','done');
绕过任何函数直插第二张未闭环单,SQLite 自己会拒。分层的意义:入口检查为了省钱,库级约束为了保证正确。
四、状态机:状态只认数据库,不认卡片
WORK_ORDER_TRANSITIONS = {
"open": {"assigned", "done"}, # 允许跳过派单直接回填
"assigned": {"done"},
"done": {"closed"},
"closed": set(), # 终态
}
跳级、回退、终态再流转一律抛 WorkOrderError,HTTP 层映射成 409。派单必须带 operator 并回填 assignee——「谁派的」和「派给谁」都留痕。
五、飞书卡片:3 秒预算与就地重绘
工单处置不在浏览器,而在飞书群。报警卡片就是一张随身工单,点「接单 → 已处理 → 确认闭环」后卡片就地重绘成下一状态,不新发卡。预算来自飞书卡片回调的超时约束:从点击到完成状态校验、落库、回写,必须在 3 秒预算内(测试按 2.2 秒卡)。这倒逼状态机流转足够轻:LLM 不进入实时链路。
六、经验回流:关单即沉淀,知识不留在师傅脑子里
关单时自动把这次处置写成一条可检索的经验。几个刻意取舍:只认 closed(没处置结果的阶段沉淀进去是废料);幂等键 = source_wo_id(同一张单关几次只产出一条);沉淀失败不影响关单;时间线写一条 knowledge_sediment 留痕。
这条链路落地时抓到一个真 bug:关单占位文案「人工回填闭环」会覆盖 done 阶段填的真实处置。修法是关单留白不覆盖、API 层透传 body.resolution,并先写一条会失败的用例把它钉住。
七、守护进程:五个服务,一个入口
make up 背后的零依赖守护托管五个服务,各自挂了有不同的后果:
| 服务 | 端口 | 挂了会怎样 |
|---|---|---|
| 后端 / API / WebSocket | 3000 | 看板白屏、飞书失联 |
| Web 前端 | 5173 | 打不开页面 |
| MES API | 8002 | 工单、看板、卡片按钮全挂 |
| 工况模拟器 | — | 曲线停在原地,巡检永远「无异常」 |
| 班次简报定时器 | — | 收班没人提醒,坑留到下一班 |
守护做了四件容易漏的事:子进程退出按指数退避重启(1s → 60s,稳定后归零);带端口的服务每 5s 探活、连续 3 次失败判僵死并强杀重启;SIGTERM 按进程组整体收尾不留孤儿;给每个服务注入 NO_PROXY——宿主机上的 HTTP_PROXY 会把 127.0.0.1 的探活也代理走。
踩坑记录:后端冷启动(tsx 编译)实测 25~40s,默认启动宽限 20s,导致「慢」被误判成「僵死」,重启进入死循环。宽限调到 60s 一次通过——凡是带编译/迁移的服务,别用默认值赌启动速度。
八、测试与验收
回归用例 127 项(Python 112 + TypeScript 15),CI 卡在 PR 上。分布如下:
| 文件 | 用例 | 盯的是什么 |
|---|---|---|
test_state_machine.py | 15 | 状态机非法流转、时间线留痕、数据口径 |
test_closed_loop.py | 13 | 建单幂等(含库级索引)、经验回流、双触发 |
test_feishu.py | 17 | 卡片结构、按钮 payload、webhook 降级 |
test_ingest.py | 29 | 上报鉴权/校验/幂等、模拟器不污染演示库 |
test_sediment.py | 12 | 沉淀字段来源、幂等、开关、失败不阻断 |
test_shift_report.py | 18 | 班次口径、峰值判定、历史还原 |
test_agent_nodes.py | 8 | 诊断/问诊节点(假传输层,不联网不耗 token) |
mes-workorder-actions.test.ts | 15 | 点击翻译、2.2s 预算、409 翻译、卡片重建 |
九、诚实的边界
比藏起来更省事的,是把没做和做浅的写清楚:
- 阈值是示例常量(振动 8.0 / 温度 75.0 / 压力 5.5),接真实产线要按设备型号、工况分段;
- 故障码靠关键词推断,覆盖不了长尾描述;
- 单机 SQLite 够一条产线用,多车间要换 PostgreSQL 并给
metric分区; - 卡片回调依赖长连接,断线重连期间点按钮会失败,靠重试兜住,但没有本地队列补偿。
十、复盘
这个项目最想证明的一件事:Agent 的价值不在模型有多强,而在把不可靠的部分关进确定性的格子里。模型只做判断,代码管写操作,幂等落到数据库约束,状态只认数据库——这几条加起来,才谈得上「闭环可审计」。