让机器录数据、让人做判断光纤资源管理中的 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.json54 条指令就是它与外部世界的接口。三、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.jsserver.js与 Go 单文件main.go两个后端功能等价默认端口 4666二选一运行Go 版用go:embed把前端打进可执行文件构建产物约 12.7 MBWindows 与 Linuxamd64 / 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 数据主权项目数据是本地 JSONAI 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等。