让机器录数据、让人做判断：光纤资源管理中的 AI 助手与工程化落地
摘要：AI 在工程工具里的合理位置，不是替人做工程判断，而是替人承担结构化录入与批量调整。nVisual FiberMap 的 AI 助手把「建网 → 接续 → 管井 → 敷设 → 自检 → 导出」的重复操作交给自然语言，并以「计划 → 执行 → 回灌 → 自修」的闭环保证结果可验证。本文拆解这套机制的设计，并讨论它与零依赖部署、离线运行、数据主权等工程化问题之间的关系。
一、AI 应该做什么：先划清边界
工程软件引入 AI 时，最容易犯的错误是让它做两件事：猜工程事实和做不可验证的判断。前者会编造数据，后者会掩盖问题。
FiberMap 的边界划得很清楚：
- AI 负责：把自然语言描述转成结构化操作（建对象、改属性、接续、敷设、导出），把批量调整从几十次点击压缩成一句话；
- AI 不负责：决定工程参数是否合理、决定数据是否可以交付、在结果不可验证的情况下宣告成功；
- 判断留给谁：数据结果由合规自检裁决（ERROR 未归零不算完成），最终取舍由人决定（破坏性操作需确认，每条指令可撤销）。
这个边界的工程含义是：AI 的产出物必须能被现有工具校验。做不到这一点的 AI 功能，在竣工资料场景里是不敢用的。
二、两条通路，同一套执行层
FiberMap 的 AI 助手有两条入口，共用同一个指令执行层：
- 内置 AI 面板（左侧停靠抽屉）：用户自填 API Key、接口地址与模型，Key 只存本机浏览器，服务端只做无状态转发、不落盘；
- 外部 Agent 中继：外部智能体（如 WorkBuddy）按自托管的 OpenAPI 契约
POST /api/agent/cmd/:tool驱动打开中的页面，画布实时呈现，与手工操作共享同一份状态与撤销栈。
核心机制是「计划 → 执行 → 回灌 → 自修」闭环：
模型输出唯一 JSON 计划（reply / plan / calls） ↓ 页面内逐条执行指令 ↓ 结构化结果回灌：真实 id / 坐标 / 统计 / 合规自检问题清单 ↓ 模型读结果自我修正；ERROR 未归零不宣告完成外部 Agent 通路的价值在于「可嵌入既有自动化流程」：把 FiberMap 页面当作一个可远程驱动的工程编辑器，OpenAPI 契约（public/api/agent/openapi.json，54 条指令）就是它与外部世界的接口。
三、54 条指令：覆盖面决定可用性
指令按领域分组，覆盖了工具的主要工作流：
| 领域 | 指令示例 |
|---|---|
| 查询与状态 | query.status、query.objects、obj.get、query.checks、query.stats、query.fiberFlow |
| 项目 | project.new、project.meta、project.save、project.undo/redo、project.exportJson |
| 光缆图对象 | closure.add/update/move/delete、cable.add/addChain/update/move/vertex/delete |
| 管井 | well.add/update/move/delete、duct.add/update/sect/delete、route.genFromCable、well.alignFromCable、query.ductPath |
| 接续与成端 | splice.range/splitter/remove/clear、odf.terminate/removeTerms |
| 敷设 | lay.assign/auto/clear/check |
| 外部数据 | import.plan/apply、kml.import、nvisual.fetch |
| 视图与导出 | view.switch/focus/shot、export.xlsx/dxf/png/pdf |
覆盖面很重要：如果 AI 只能「加设备」而不能「接续、敷设、自检、导出」，它就只是演示；只有当它能走完「建网 → 接续 → 管井 → 敷设 → 自检 → 导出」全链路，才谈得上把重复劳动真正交出去。
值得注意的是执行层的复用原则：几何、编号、皮长、断面、接续互斥、敷设车道、导出全部复用既有模块，一行不重写。AI 指令与手工操作走同一套业务逻辑，所以 AI 建出来的数据和手工录的数据在结构上完全一致，不存在「AI 专属数据格式」。
四、三个关键设计点
4.1 四视图联动：用户看得见 AI 在改什么
指令声明目标视图，执行前后自动切换视图并选中聚光：AI 在光缆图加接头包、在纤芯图接芯、在路由图敷设，用户都能在画布上看到。这解决了自动化常见的「黑箱焦虑」——知道它做了什么，才敢让它继续做。
4.2 坐标不过模型
模型只说「对象名 + 方位 + 距离（米）」（如「在 JT003 东侧 120 米新建接头包」），经纬度换算全部在本地完成。这样做从根上杜绝了模型算错坐标的问题——大语言模型做地理计算并不可靠，但「往东 120 米」这种相对描述可以被确定性换算忠实执行。
4.3 清单附件本地解析
拖入 Excel 工程量清单后，先在页内解析成导入计划，只把摘要与预检问题送进上下文，整张表不进 token。这带来两个好处：
- 成本与上下文可控：一份几百行的清单不会把对话撑爆；
- 数据不出本机：甲方数据不被上传到模型服务，只有摘要信息参与对话。
五、安全与可控：让 AI 操作「敢用」
AI 写工程数据，必须有一整套护栏：
- 每条指令 = 一步撤销，可以「撤销本轮 N 步」整体回退；
- 破坏性操作一次确认（删除、清空、批量修改等）；
- 用户操作软锁：AI 执行期间检测到用户正在操作（≤ 2 秒退避）则返回 BUSY_USER，避免机器和鼠标同时写同一份数据；
- 单 Promise 链串行化：指令逐条执行，不并发写状态；
- 工具名白名单与纠错表：未知工具返回 UNKNOWN_TOOL 并给出建议；
- 参数强校验：数值、枚举、字符串类型与结构字段有校验原语，结构性字段禁止直接改；
- 引用消解：按 id → 编号 → 名称 → 唯一前缀解析对象，歧义时返回候选而不是猜；
- 编排层熔断：同一调用失败 3 次 / 单轮对象数超限 / 连续 3 轮 ERROR 不下降即停止；
- 回灌护栏：路径点超过 20 个自动截断，回灌内容长度受限。
这些机制合起来表达了一个立场：AI 的自由度用「可撤销、可确认、可校验」来换，而不是用「信任」来换。
六、工程化落地：工具要能在现场活下来
AI 只是 FiberMap 的一部分；这套工具真正的落地能力，来自一串「不性感但关键」的工程决策：
6.1 零依赖与双后端
- 前端无框架、无构建步骤；
- Node.js
server.js与 Go 单文件main.go两个后端功能等价（默认端口 4666，二选一运行），Go 版用go:embed把前端打进可执行文件，构建产物约 12.7 MB；Windows 与 Linux（amd64 / arm64）均可运行； - 两个后端的代理行为一致（
/nvisual、/tile、/api/ai/*、/api/agent/*），有测试双跑（node tests/nvisual-proxy.unit.mjs go）。
对甲方现场、内网机房这些「装不了 Node、配不了环境」的场景，拷一个可执行文件就能跑，是最低的交付门槛。
6.2 离线可用
- 无本机底图配置时默认离线经纬网格，录入/出图不依赖网络；
- 三维查看的 MapLibre GL JS 本地 vendor，离线可用；
- DEM 地形可选自建瓦片（
public/dem/{z}/{x}/{y}.png），持续失败自动降级平面。
6.3 子路径部署
支持 Nginx 子路径部署（如/fibermap/）：BASE_PATH环境变量或前端basepath.js适配，前端资源与 API 路径自动处理，适合多系统共存的门户环境。
6.4 多语言
中/英文整站切换：静止文案、动态面板/弹窗/Toast/状态栏、title/placeholder、画布文字、原生确认框全部随语言切换，切回中文无损还原；初始语言跟随浏览器，用户选择优先。对涉外项目或多语言团队，这是可交付性的组成部分。
6.5 测试体系
项目维护了以npm run test:*组织的测试套件：纯逻辑单元测试（几何、接续计划、成端、断面、导入、多语言词典等）与无头 Chrome 端到端测试（拖拽、敷设、导出、自检、AI 契约等）。对工程工具来说，测试不是锦上添花——它是「改一处数据，四处视图同步」这类复杂联动的可信度来源。
6.6 数据主权
- 项目数据是本地 JSON；
- AI Key 与底图配置存 localStorage，平台对接经本机代理；
- 附件清单本地解析；
- 无遥测、无强制联网。
对政务、专网、军工等数据敏感场景，这可能是选型的决定性因素。
七、价值：把人力从录入转向判断
把 AI 与工程化放在光纤资源管理的语境里，价值可以分成三层：
- 存量消化：有缆网数据但缺管道资料时，用
route.genFromCable、kml.import、nvisual.fetch批量建库；有清单时用import.plan/apply批量导入； - 批量纠偏：换个命名规范、统一芯数、批量调整位置、批量敷设，用自然语言描述一次执行，比手点几十次可靠；
- 质量闭环：AI 执行完用
query.checks拿问题清单自我修正，ERROR 清零才收工——AI 的工作结果有客观检验，不是「看起来做完」。
最终改变的是人的工作结构：工程师从「反复录入"升级为"描述意图、确认结果、处理例外」。这正是自动化在专业软件里最合理的样子。
八、结语
AI 助手能不能用，取决于背后的工程底座：指令是否覆盖全流程、执行是否复用业务逻辑、结果是否可校验、操作是否可撤销、数据是否可控。FiberMap 把这些条件都当作前提而不是补充，再叠加零依赖、离线、子路径、多语言、双后端这些落地能力。于是 AI 在这里不是噱头，而是一个可以被放进交付流程里的生产力工具——机器负责录入，人负责判断，自检负责裁决。
附：事实来源与核验方式
本文所引 AI 架构与工程化能力来自 nVisual FiberMap 当前版本（截至 2026-10-10）的README.md、docs/AI助手-设计方案.md与源码：
- 指令契约 54 条：
public/api/agent/openapi.json； - 指令执行层与安全护栏：
public/js/agent.js、public/js/agent_*.js； - 计划解析、回灌与熔断：
public/js/ai/ai-orchestrator.js； - 提示词规则与契约裁剪：
public/js/ai/ai-rules.js； - 面板与附件通道：
public/js/ai/ai-panel.js、public/js/ai/ai-attach.js； - 双后端与代理：
server.js、main.go（含/api/ai/*、/api/agent/*、/nvisual、/tile）； - 子路径部署：
public/js/basepath.js、server.js注释中的 Nginx 配置示例； - 多语言引擎：
public/js/i18n.js及词典文件。
相关测试可复现：npm run test:ai（含ai-contract、ai-rules、ai-feedback、ai-attach、ai-relay、ai-proxy）、npm run test:ai-e2e、npm run test:nvisual-proxy-go、npm run test:basepath、npm run test:subpath、npm run test:i18n等。
