动态表单与置信度着色

01问题：AI 填表的两种做法

把模型接入设备建卡环节，通常落到两种做法上。

其一，全自动写库。提取结果直接写入台账，效率最高，但使用者无从判断哪些字段取自铭牌、哪些字段来自推断，也无从知道哪一处需要核对。

其二，模型给出建议，全部字段由人工填写。可信度最高，但节省的时间接近于零：每一个字段都要人工确认，前置的识别环节没有承担任何工作量。

两种做法的代价不同，指向的却是同一个问题：使用者以什么形式获知每个字段的可信程度。 EAMX 的处理方式是给每一字段附带一个置信度与一个来源标签：该字段由何处得来、可信度处于哪一档，两个问题均可当场回答。使用者按颜色决定核对范围，不必整表复核。

02两阶段管线与三组分类

表单的构造由两个阶段完成，分工为「先取数、再归类」。

Stage 1 · nameplate-extractor：从铭牌照片或合同 PDF 中提取原始字段，输出 RawField 数组，每个字段带一个 confidence 值。
Stage 2 · field-classifier：以纯代码规则把原始字段归入三组；未命中字段映射表的字段一律进入技术参数区。

三组的分工决定了前端颜色与使用者动作。

表 1 · 三组分类、着色规则与使用者动作
分组	来源	置信度	前端颜色	使用者动作
A 类	铭牌 / 合同 OCR 提取	0.85–0.95	绿色	直接确认
B 类	同租户历史数据推断与系统默认	0.55–0.80	黄色	逐项核对
C 类	未映射的技术参数	沿用铭牌置信度	灰色	存于 JSONB，按需查看

依据：prepare_equipment_form 与 agents/field-classifier.ts 的分类规则。表中数值为字段的经验置信度分档，不构成识别准确率的承诺。

03A 类：文档直接提取（绿色区）

A 类字段可以由铭牌、合同或发票直接读出，共 14 个，包括设备名称、型号规格、出厂序列号、额定功率、重量与原值。

置信度的赋值规则只有一条：字段有值时，取该字段在来源文档上通常的清晰程度所对应的经验值；字段为空时记为 0。无值字段在前端渲染为红色的「待填写」。

表 2 · A 类字段的来源标签与经验置信度（节选）
字段	来源标签	经验置信度
设备名称	铭牌	0.95
型号 / 规格	铭牌	0.92
出厂序列号	铭牌	0.92
额定功率	铭牌	0.88
原值（元）	合同 / 发票	0.88
重量	铭牌 / 手册	0.85

有值的字段一律带来源标签，写明该值取自铭牌、合同还是手册。使用者面对绿色字段时，核对的对象是该字段是否有值，而非逐字比对原文；无值字段按必填与可选的标记由使用者补充。

04B 类：同租户历史推断（黄色区）

设备分类、使用部门、存放位置与设备等级这类字段需要纳入台账管理，而文档中并无记载。 EAMX 从同一租户下同型号的既有设备中推断：按型号模糊匹配取最近 5 条记录，对每一字段取出现频率最高的取值。

const similar = await db.select({ category, department, location, grade }) .from(equipmentsTable) .where(and(eq(tenantId), ilike(model, `%${modelVal}%`))) .orderBy(desc(createdAt)).limit(5); bSuggestion = { category: freq(similar.map(s => s.category)), // 置信度 0.72 department: freq(similar.map(s => s.department)), // 置信度 0.65 location: freq(similar.map(s => s.location)), grade: freq(similar.map(s => s.equipmentGrade)), };

推断结果以黄色呈现，并附来源标签「AI建议 · 同租户历史设备」与一行提示文字。设备分类的置信度为 0.72，使用部门的置信度为 0.65，均落在 0.55–0.80 的黄色区间内。

黄色与提示文字共同构成一次显式提醒，使用者不会在无提示的情况下接受推断结果，也不会把推断值误认为文档提取值。

05C 类：技术参数与 JSONB 存储

铭牌上大量参数并不属于台账列，例如额定电压、工作压力与防护等级。 field-classifier 在字段未命中 FIELD_MAP 时，将该字段写入 technicalSpecs；序列化时由 flattenToFormParams 以 JSON 字符串写入 technicalSpecsJson。

if (!mappedKey) { if (!(field.label in technicalSpecs)) technicalSpecs[field.label] = val; } // flattenToFormParams — 序列化为 JSON 字符串 params.technicalSpecsJson = JSON.stringify(technicalSpecs);

前端以可编辑的技术参数区域呈现这一组字段，每条带 [铭牌] 来源标签，置信度沿用铭牌提取结果。该组不参与台账列的确认，前端以灰色呈现，表示无需逐项确认。

06表单交付协议

表单以 UI_CARD 的形式交付给前端，卡片类型为 dynamic_form，除字段之外还携带表单标题、任务标识、字段分组与技术参数。

return { type: "UI_CARD", cardType: "dynamic_form", formTitle: "设备台账确认", taskId: "create_equipment", // 前端提交时回传 description: "请核对 AI 提取的设备信息……", fieldGroups: [ { id: "classA", title: "A 类 — 基本信息（从文档提取）" }, { id: "classB", title: "B 类 — 管理属性（AI 建议，请核对）" }, ], fields: [ ...classAFields, ...classBFields ], technicalParams, // C 类 };

前端按 fieldGroups 分组渲染，按 confidence 自动着色，按 source 显示来源标签，按 required 标记必填；分组与着色规则写在交付协议内部，界面呈现不依赖前端的额外约定。

07边界与实现落点

上述机制涉及三份实现文件，另有三条边界应当在能力说明之前讲清。

表 3 · 实现落点
文件	职责
`agents/equipment.agent.ts` L226–438	`prepare_equipment_form`：三组字段的构造与置信度赋值
`agents/field-classifier.ts`	Stage 2 的纯代码分类与 `flattenToFormParams` 序列化
`agents/nameplate-extractor.ts`	Stage 1 的视觉提取，提供 A 类字段的原始 confidence