> 系列名称：「EAMX 2.0 AI-Native 设备管理系统：从零构建全栈技术实践」
>
> 定位：面向中高级全栈/后端开发者的深度技术文章，聚焦架构决策、代码实现与踩坑复盘。
>
> 差异化：与之前"新用户友好"系列（面向产品/运营读者）不同，本系列面向开发者，每篇文章包含实际源码、架构图、性能对比与工程权衡。

核心问题：一个设备管理系统，从传统 CRUD 到 AI-Native，架构上需要过哪几道坎？

技术点：

• 整体架构图：Express 5 → Drizzle ORM → PostgreSQL，前端 React 19 + Vite 7
• 多租户隔离策略（tenant_id 全局注入 vs Row-Level Security）
• AI-Native 的交互模型翻转："用户操作系统" → "系统理解用户"
• 14 个 Agent、34 个路由模块、11 个插件的职责地图
• 架构评审触发的三阶段重构：Service 层引入 → AI 管道去硬编码 → MCP Server

源码索引：qod/ai-architecture-v2.md、qod/architecture-review-2026-05-08.md、express app.ts、drizzle schema

核心问题：用户说"3号机没劲了"，系统怎么在 200ms 内判断他要报修？

技术点：

• 三层策略架构：Step 1 别名解析（DB lookup）→ Step 2a 静态关键词（0ms 内存匹配）→ Step 2b 意图模式库（DB patterns）→ Step 3 LLM 兜底分类
• IntentAgent.preprocessIntent() 100ms 超时机制
• intent_patterns 表的学习机制：confirmedCount 自增、新模式写入、低频衰减
• entity_aliases 的团队共享 vs 个人隔离设计
• 置信度三分法：high/medium/low 的决策逻辑

源码索引：agents/intent.agent.ts（611行）、intent_patterns 表、entity_aliases 表

性能数据：静态规则 0ms / 本地模式 2-5ms / LLM 兜底 ~200ms / 整体 100ms 超时

核心问题：AI 对话系统如何从 1800 行巨石 Coordinator 重构到可扩展的 Pipeline？

技术点：

• 重构前后对比：从 coordinator.agent.ts（880行）到 orchestrator.ts（233行）
• 四个 Phase 设计：Image Preprocess → Context Build → LLM Reasoning → Learning
• Vercel AI SDK streamText() + stepCountIs(3) 防止死循环
• Tool Registry 替代硬编码 Tool 定义，tool-factory.ts 按权限构造
• SSE 流式输出处理：handleSSEStream() 的分块与 UI Card 嵌入
• 主 LLM 与视觉模型的职责分离：DeepSeek 做主推理，Qwen-VL 做图片预处理

源码索引：ai/orchestrator.ts（233行）、ai/tool-registry.ts（86行）、ai/tool-factory.ts、ai/sse-handler.ts、ai/system-prompt-builder.ts

关键决策：协调器只做编排（调度），不做决策（决策交给 LLM），不实现业务逻辑（业务在 Agent）

核心问题：用户拍一张铭牌照片，系统怎么在 3-8 秒内填好一张 30 字段的设备表单？

技术点（已撰写，可直接复用优化）：

• 两阶段分离设计：Stage 1 视觉提取（Qwen-VL 忠实 OCR）→ Stage 2 纯代码分类（FIELD_MAP 60 条映射）
• Qwen3-VL 思维链陷阱复原：Vercel AI SDK enable_thinking 参数未转发 → 延迟 130s+ → 切换 OpenAI 原生客户端降至 3-8s
• Prompt Engineering 5 要点：忠实转录、模糊字符诚实、JSON only、宁多勿少
• DynamicForm A/B/C 三分类：铭牌提取（绿）/ AI 推断（黄）/ 技术参数 JSONB
• 多源冲突处理：铭牌 + 合同 + 发票并行提取，取高置信度值

源码索引：agents/nameplate-extractor.ts（171行）、agents/field-classifier.ts（232行）、agents/equipment.agent.ts L226-438

核心问题：每次修完一台设备，如何把这次维修经验变成团队可检索的知识？

技术点：

• 知识闭环双路径：工单关闭自动提取 → 知识对 + embedding 写入 vs 故障提交 → 异步相似检索 → 附注历史参考
• pgvector 向量存储：embedding vector(1536)，余弦相似度搜索
• 语义检索 vs 关键词检索：pgvector 的 <=> 操作符与相似度阈值策略
• 知识对提取 Prompt 设计：从维修过程文本中结构化提取"故障模式→根因→方案→关键备件"
• 知识可追溯性：每条知识对附带原始工单 ID，用户可溯源验证

源码索引：agents/rag.ts、agents/external-knowledge.agent.ts、fault_knowledge 表 schema

核心问题：AI 填好表单后，用户怎么在 3 秒内判断哪些字段可以直接信任？

技术点：

• 置信度计算规则：铭牌来源 0.85-0.95 / 合同来源 0.70-0.88 / 推断来源 0.0-0.65 / 系统默认 0.65-0.75
• equipment.agent.ts 中 prepare_equipment_form 的表单构造逻辑（约 230 行）
• A/B/C 三组字段分类：classA（文档提取，绿）/ classB（AI 建议，黄）/ C 类（技术参数 JSONB）
• 来源标签系统：[铭牌] [合同] [AI建议·同租户历史设备] [系统默认] [当前登录用户]
• UI_CARD 协议：前端如何消费后端的 DynamicForm 定义并渲染三色表单
• configurableKeys 机制：前端允许租户管理员自定义技术参数的标签映射

源码索引：agents/equipment.agent.ts L226-438、agents/field-classifier.ts classifyFields/flattenToFormParams

核心问题：11 个业务模块如何做到"独立开发、互不影响"？

技术点：

• PluginRegistry 核心 74 行代码：Tier 0→3 分层、依赖排序、生命周淑钩子
• PluginManifest 五要素：permissions / navItems / approvalSupport / lifecycleHandlers / cronJobs
• LifecycleBus 事件广播：lifecycle.emit("approval.approved", data) → 各插件 handler 自行响应
• 路由隔离：每个插件 createRouter() 返回独立 Express Router，统一 mountAll()
• Service 层重构：从路由直操作 DB 到 Service 层封装（14 个 Service 类）
• 插件注册的显式 vs 自动发现之争：为什么选择了保持显式注册

源码索引：packages/core/src/plugin-registry.ts（74行）、artifacts/api-server/src/plugins/_registry.ts、各 plugin.ts

设计原则：P1 插件自描述、P2 Service 层唯一真相源、P4 LifecycleBus 唯一副作用通道

核心问题：一个设备管理员、维修工程师、仓管员同时登录，如何确保每个人只看到自己该看的数据？

技术点：

• CASL createMongoAbility + AbilityBuilder 的前后端同构实现
• 权限码体系：26 个 Subjects（Equipment/WorkOrder/FaultReport/...）× 19 个 Actions（read/create/update/delete/dispatch/...）
• 三维数据范围：all / department / self 的 SQL 层自动过滤
• 条件权限：{ requisition.amount >= 5000 } 的动态规则执行
• 6 种预设角色的权限矩阵：超管/厂长/车间主任/维修工程师/仓管/财务
• 财务字段脱敏：hasFinanceAccess + 中间件拦截，前端不渲染敏感字段
• 前后端同构：buildAbilityFromPermissions() 在 packages/core 中共享，前端 AbilityProvider 消费

源码索引：packages/core/src/ability.ts（132行）、lib/data-scope.ts、artifacts/eamx-web/src/components/ability-provider.tsx

核心问题：如何在审批引擎完全不感知业务表结构的情况下，让 11 个插件都能接入审批流程？

技术点：

• 审批流状态机：pending → in_progress → approved/rejected/returned/cancelled
• checkApprovalGate(documentType, documentId) — 业务路由只需这一行调用
• LifecycleBus 广播审批结果：lifecycle.emit("approval.approved", payload) → 各插件的 lifecycleHandler 响应
• 审批流定义：DAG 多节点、多审批人、会签/或签模式
• approvalSupport 声明：插件只需声明 { documentType: "inbound_order", label: "入库单" }
• 反面案例：workflows.ts 中的硬编码（L414 inventoryTransactionsTable），以及如何通过 approval.cancelled 事件解耦

源码索引：routes/workflows.ts（596行）、lib/approval-gate.ts、lib/lifecycle.ts、各插件的 lifecycleHandlers

核心问题：如何让 EAMX 的 AI 能力不仅能被自己的前端调用，还能被外部 AI 客户端（Claude Desktop、Cursor、VS Code Copilot）发现和使用？

技术点：

• Tool Registry 架构：McpTool 的五要素（name/description/annotations/inputSchema/handler）
• Tool 按 CASL 权限过滤：getAuthorized(ability) 确保外部客户端也只能调用有权限的 Tool
• inputSchema 的 Zod Schema 自动推导
• MCP Server 桩实现：generateMcpToolList() + executeMcpToolCall()
• Tool 注册与 Agent 调用的统一：executeEquipmentAction("list_equipments") 同时被 LLM Tool Calling 和 MCP Client 调用
• 5 个内置 Tool 的完整解剖：equipment:list / equipment:get / fault:create-report / fault:list / entity:search

源码索引：ai/tool-registry.ts（86行）、mcp/server.ts（66行）、mcp/client.ts、tools/register.ts、tools/equipment/list.tool.ts

``<br>┌─ 01 全景 ────────────────────────────────────────┐<br>│ 架构总览、技术栈、演进路径 │<br>├───────────────────────────────────────────────────┤<br>│ │<br>│ ┌─ AI 管道线 ─────────────┐ ┌─ 架构基础设施线 ──┐ │<br>│ │ 02 意图识别三层策略 │ │ 07 插件化架构 │ │<br>│ │ 03 AI Pipeline 编排器 │ │ 08 CASL 权限系统 │ │<br>│ │ 04 铭牌 OCR 两阶段管线 │ │ 09 审批流引擎 │ │<br>│ │ 05 pgvector RAG 知识库 │ └──────────────────┘ │<br>│ │ 06 DynamicForm 置信度 │ │<br>│ │ 10 Tool Registry+MCP │ │<br>│ └──────────────────────────┘ │<br>│ │<br>└────────────────────────────────────────────────────┘<br>``

前半部分（02-06）是"AI 管道线"——从用户输入到系统响应的完整链路，每篇拆一层。

后半部分（07-09）是"架构基础设施线"——支撑 AI 能力的底层系统设计。

10 是收尾——把前面的 AI 能力通过 Tool Registry 标准化，通过 MCP Server 对外暴露。

| 段落 | 内容 | 占比 |<br>|---|---|---|<br>| 问题与背景 | 为什么要做这个设计？传统方案的痛点 | 15% |<br>| 架构设计 | 核心设计决策 + 架构图 | 25% |<br>| 核心实现 | 关键代码讲解（带行号引用） | 35% |<br>| 踩坑与优化 | 性能问题、兼容性问题、修复过程 | 15% |<br>| 总结 | 设计原则提炼、适用场景 | 10% |

| 已有文章 | 位置 | 可复用于 |<br>|---|---|---|<br>| 《基于Qwen-VL的OCR铭牌自动建设备台账的实现方案》 | 项目根目录 | 04（直接复用，略作优化） |<br>| 《EAMX开发手记-07-插件化架构设计》 | 项目根目录 | 07（面向读者不同，需重写为纯技术风格） |<br>| 《EAMX开发手记-08-CASL权限系统》 | 项目根目录 | 08（同上） |

其余 6-7 篇需要全新撰写。

• 首发平台：CSDN（基于当前打开文件路径判断）
• 转载：掘金、SegmentFault、知乎专栏
• 发布节奏：每周 1-2 篇，配套 GitHub 开源仓库链接
• 每篇字数：3000-5000 字，含代码块与架构图

作者：白杨，十余年设备资产管理从业经验，EAMX 产品负责人。