左帮右臂端侧AI模型跨硬件适配系统 V1.0

软件说明书

著作权人： 北京左帮右臂人工智能技术有限公司

统一社会信用代码： 91110114MAKJ1UC63J

软件名称： 左帮右臂端侧AI模型跨硬件适配系统

软件简称： 端侧AI适配系统

版本号： V1.0

开发完成日期： 2026年6月25日

首次发表日期： 未发表

目录

• 第一章 软件概述
• 第二章 软硬件运行环境
• 第三章 软件系统架构
• 第四章 核心功能详细说明
• 第五章 软件创新点与优势
• 第六章 软件操作步骤与使用说明（含操作界面截图）
• 第七章 典型应用场景案例（含真实运行界面）
• 第八章 数据接口与集成说明
• 第九章 核心功能模块详述与运维（含真实运行界面）
• 第十章 版本更新说明
• 第十一章 参数配置说明
• 第十二章 部署与运维详细步骤
• 第十三章 安全机制
• 第十四章 性能基准
• 第十五章 常见问题与故障排查
• 第十六章 术语与缩略语
• 第十七章 技术参数与性能指标
• 著作权人信息

第一章 软件概述

1.1 研发背景

在工业制造、供应链管理、质量管控等场景中，企业对端侧AI推理的需求日益增长。ECR变更审核、供应商质量诊断、BOM成本优化、根因分析等业务环节需要AI模型提供实时、智能的决策支持。然而，当前端侧AI推理面临一个核心痛点：芯片平台碎片化。

企业在不同部署环境中使用的AI加速硬件差异巨大，包括：

• NVIDIA GPU（主流但成本高）
• 华为昇腾NPU（国产化替代首选，基于CANN/torch_npu运行时）
• 摩尔线程GPU（国产GPU加速方案）
• 高通NPU（基于QNN推理框架）
• 三星Exynos NPU（移动端AI加速）
• 本地CPU（基于Ollama等轻量推理框架）
• 云端大模型（DeepSeek、OpenAI等）

不同芯片平台具有不同的推理服务接口、模型格式、运行时环境和配置方式。开发者为每种芯片单独编写适配代码，导致维护成本高、代码复用率低、新硬件接入周期长。同时，端侧硬件可能因故障、过载或维护而不可用，业务系统需要具备自动降级能力，确保AI服务不中断。

在实际项目落地过程中，上述碎片化问题进一步体现为以下具体挑战：

1. 接口不一致：Ollama 使用 /api/tags 与 OpenAI 兼容 /v1/models 两种风格；昇腾 NPU 的 vLLM-Ascend 与 CANN/torch_npu 运行时端口与协议存在差异；摩尔线程 GPU 通过 MTCLAW 暴露独立端点；云端大模型则有各自的鉴权与限流策略。若业务代码直接耦合这些细节，任何硬件更换都意味着大规模改造。

1. 可用性难以保障：端侧硬件资源受限，容易发生 OOM、驱动异常、温度过高降频等问题；当某一推理后端不可用时，若缺乏自动切换机制，业务链路将直接中断。

1. 性能与成本难以平衡：全部请求走云端大模型会带来较高的调用延迟（约 500ms/请求）与持续的 API 费用；而全部走端侧小模型又难以处理复杂语义任务。需要一种能按任务复杂度自动分流的调度策略。

1. 运维可观测性缺失：多后端并存时，运维人员难以快速定位"本次请求到底走了哪个后端""为什么走了降级链路""缓存命中率如何"等问题，导致故障排查耗时。

本软件正是针对上述挑战而设计，致力于在"芯片无关、服务高可用、成本可控、可观测"四个维度提供一体化解决方案。

1.2 核心功能

本软件提供芯片无关的统一推理适配能力，核心功能包括：

1. 多硬件自动探测：启动时自动探测本地及云端可用的推理服务，识别Ollama、摩尔线程GPU、华为昇腾NPU、高通NPU、三星Exynos NPU、DeepSeek云端等7类推理服务提供方。

1. 统一适配层：通过硬件抽象层将不同芯片的推理接口统一封装，上层应用无需关心底层硬件差异，调用统一的API即可完成AI推理。

1. 智能任务调度：基于Worker/Solver分工模型，将简单任务（数据库查询、算术计算、模板渲染）路由至端侧小模型（响应时间约70ms），将复杂任务（语义理解、多步规划、内容生成）路由至云端大模型（响应时间约500ms），实现70%以上任务走端侧加速。

1. 多级降级链路：构建"MTCLAW → 昇腾NPU → Ollama → DeepSeek → 规则引擎"的五级降级链路，当任一硬件节点故障时自动切换至下一可用节点，确保业务连续性。

1. 熔断与自恢复机制：对每个模型节点实施健康检查与熔断保护，连续失败超过阈值时自动熔断，超时后进入半开状态试探恢复，避免故障扩散。

1. 响应缓存机制：对简单只读任务的结果进行缓存（FNV-1a哈希键+LRU淘汰+TTL过期），命中缓存时零延迟返回，有效降低重复请求的开销。

1. 业务智能引擎：集成ECR变更审核、供应商质量诊断、BOM成本优化、5Why根因分析、1688供应链寻源等工业场景AI能力。

1.3 适用场景

• 制造业数字员工系统的AI推理后端
• 工业物联网边缘计算节点的AI加速
• 多芯片平台环境的统一AI服务管理
• 需要高可用性保障的企业级AI应用

上述场景的共同特征是：对推理延迟与可用性敏感、部署环境硬件异构、且往往存在数据不出域的合规要求。本软件通过端侧优先的调度策略与离线运行能力，使这些场景能够在不依赖云端的前提下获得稳定的AI能力。

1.4 软件总体目标与价值

本软件的总体目标是让业务系统"一次开发、多端运行、永不中断"，其核心价值体现在四个层面：

• 开发提效：业务代码仅依赖统一API，新增硬件后端只需在 providers 数组或配置文件中追加一项，无需修改调用方代码，开发效率提升 80% 以上。
• 运行降本：通过 Worker/Solver 分流，约 70% 的高频简单任务在端侧小模型完成（约 70ms），仅 30% 复杂任务走云端，整体推理成本显著下降。
• 业务保稳：五级降级链路叠加熔断自恢复，使 AI 服务在单点硬件故障、网络抖动、限流等异常下仍可持续可用，目标可用性 99.99%。
• 合规可控：端侧推理默认不依赖外网，模型与数据均留存在本地，满足制造、供应链等场景"数据不出域"的合规要求。

1.5 技术路线概述

软件采用"探测—抽象—路由—兜底"的技术路线：首先由 InferenceServiceDetector 并行探测所有可用推理后端，得到一份实时后端清单；接着通过硬件抽象层（HAL）与统一适配器（如 AscendNPUAdapter）抹平协议差异，对外暴露一致的 OpenAI 兼容调用接口；随后由 SmartLLMRouter 与 LLMRouter 依据任务复杂度与后端健康状态进行智能路由与多级降级；最后在全部后端均不可用时，由 LLMBrain.simulatedThinking 规则引擎兜底，保证 100% 可返回结构化结果。该路线贯穿后续所有章节，是理解本软件设计与运维的关键主线。

第二章 软硬件运行环境

2.1 硬件环境

本系统支持在以下硬件平台上运行（按适配优先级排列）：

| 硬件类型 | 推理框架/服务 | 默认端点 | 适用场景 |

|---------|-------------|---------|---------|

| 本地CPU | Ollama | localhost:11434 | 开发调试、轻量推理 |

| 摩尔线程GPU | MTCLAW | localhost:18790 | 国产GPU加速推理 |

| 华为昇腾NPU | vLLM-Ascend / CANN | localhost:8000 / 8888 / 1025 | 国产化NPU加速 |

| 高通NPU | QNN推理框架 | localhost:8889 / 6006 | 边缘端NPU推理 |

| 三星Exynos NPU | Exynos AI | localhost:8890 / 7007 | 移动端AI加速 |

| 云端GPU | DeepSeek API | api.deepseek.com | 复杂推理任务 |

最低硬件要求：

• CPU：x86_64或ARM64架构，2核以上
• 内存：4GB以上（端侧推理建议8GB以上）
• 网络：支持本地回环及外网访问（云端模型需要）

推荐生产环境：

• CPU：4核及以上（x86_64 或 ARM64）
• 内存：16GB 及以上（运行多后端并行探测时更流畅）
• 磁盘：10GB 以上可用空间（含模型权重与日志）
• 昇腾 NPU 环境：Atlas 系列推理卡，已安装 CANN 与 torch_npu 工具链
• 摩尔线程 GPU：已安装 MUSA 驱动与 MTCLAW 服务

2.2 软件环境

运行时环境：

• Node.js：v18.0及以上版本（需支持原生fetch API）
• 操作系统：Linux（推荐Ubuntu 20.04+/CentOS 8+）、Windows 10/11、macOS 12+

依赖组件：

• HTTP/HTTPS通信库：Node.js内置http、https模块
• URL解析：Node.js内置url模块
• 子进程执行：Node.js内置child_process模块（用于CANN/torch_npu环境探测）
• 加密模块：Node.js内置crypto模块（用于配置哈希）

配置管理：

• 环境变量配置（ASCEND_NPU_、LLM_、MTCLAW_*系列）
• YAML配置文件（config.yaml / profiles/local.yaml）
• 代码内默认配置（DEFAULTS常量）

外部服务（可选）：

• Ollama推理服务（端侧小模型）
• MTCLAW加速服务（摩尔线程GPU）
• vLLM-Ascend推理服务（昇腾NPU）
• DeepSeek API（云端大模型，需API Key）

2.3 目录结构与安装布局

软件以 Node.js 项目形态分发，典型安装布局如下：

edge-ai-adapter/
├── package.json                 # 项目元信息与启动脚本
├── config.yaml                  # 主配置文件
├── profiles/
│   ├── local.yaml               # 本地端侧（Ollama）配置
│   ├── ascend.yaml              # 昇腾 NPU 配置
│   └── cloud.yaml               # 云端大模型配置
├── src/
│   ├── ascend-npu.js            # AscendNPUAdapter 昇腾适配器
│   ├── llm-router.js            # LLMRouter / InferenceServiceDetector
│   ├── smart-llm-router.js      # SmartLLMRouter / ModelHealthChecker / ResponseCache
│   └── llm-brain.js             # LLMBrain 统一调用核心
├── logs/                        # 运行日志目录
│   ├── app.log                  # 主运行日志
│   └── health.log               # 健康检查与降级记录
└── data/                        # 业务数据（规则引擎库等）

上述目录结构为典型形态，实际部署时可根据运维规范调整 logs/ 与 data/ 挂载路径，并通过环境变量或 config.yaml 指向对应位置。

第三章 软件系统架构

3.1 整体架构

系统采用分层架构设计，自下而上分为硬件层、适配层、调度层、业务层四个层级：

┌─────────────────────────────────────────────────────────────┐
│                    业务应用层（Business Layer）                │
│   ECR审核 │ 供应商诊断 │ BOM优化 │ 根因分析 │ 供应链寻源       │
├─────────────────────────────────────────────────────────────┤
│                    智能调度层（Scheduling Layer）              │
│         SmartLLMRouter（多级降级链路 + 熔断 + 缓存）           │
│    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│    │  Worker路由   │  │  Solver路由   │  │  规则引擎兜底  │     │
│    │ （端侧小模型） │  │ （云端大模型） │  │（simulated）  │     │
│    └──────────────┘  └──────────────┘  └──────────────┘     │
├─────────────────────────────────────────────────────────────┤
│                  LLM大脑层（LLM Brain Layer）                 │
│            LLMBrain（think / thinkJson / 规则引擎集成）        │
├─────────────────────────────────────────────────────────────┤
│              硬件抽象层（Hardware Abstraction Layer）          │
│    ┌──────────────────────────────────────────────────┐      │
│    │        InferenceServiceDetector（服务探测器）      │      │
│    │   Ollama │ 摩尔线程 │ 昇腾NPU │ 高通NPU │ Exynos  │      │
│    └──────────────────────────────────────────────────┘      │
│    ┌────────────────┐  ┌────────────────┐                    │
│    │ AscendNPUAdapter│  │  MTCLAW适配器   │                    │
│    │（昇腾NPU专用适配）│  │（摩尔线程GPU适配）│                    │
│    └────────────────┘  └────────────────┘                    │
├─────────────────────────────────────────────────────────────┤
│                    硬件层（Hardware Layer）                   │
│  CPU │ 摩尔线程GPU │ 华为昇腾NPU │ 高通NPU │ 三星Exynos │ 云端  │
└─────────────────────────────────────────────────────────────┘

分层架构的核心价值在于每一层只依赖下一层的稳定接口：业务层不感知硬件，调度层不感知具体驱动，适配层不感知业务语义。任意一层内部演进（如新增一种芯片）都不会向上穿透，从而实现真正的"芯片无关"。

3.2 硬件抽象层架构

硬件抽象层（HAL）是本系统的核心，通过InferenceServiceDetector和各专用适配器（如AscendNPUAdapter）实现芯片无关的统一接口。

探测流程：

系统启动
    │
    ▼
InferenceServiceDetector.detectAll()
    │
    ├── 探测 Ollama (localhost:11434/api/tags)
    ├── 探测 Ollama OpenAI兼容 (localhost:11434/v1/models)
    ├── 探测 摩尔线程GPU (localhost:8080 或 5000)
    ├── 探测 华为昇腾NPU (localhost:8888 或 1025)
    ├── 探测 高通NPU (localhost:8889 或 6006)
    ├── 探测 三星Exynos (localhost:8890 或 7007)
    └── 探测 DeepSeek云端 (api.deepseek.com)
          │
          ▼
    返回可用服务列表
          │
          ▼
getBestWorkerConfig() 按优先级选择最佳Worker
    优先级：Ollama > Ollama OpenAI > 摩尔线程 > 其他

探测结果以结构化列表返回，每条记录包含 name（提供方名称）、baseUrl（端点）、models（可用模型）、available（是否可用）等字段，供上层路由决策使用。

3.3 模块组成

系统由以下四个核心模块组成：

| 模块文件 | 类名 | 职责 |

|---------|------|------|

| ascend-npu.js | AscendNPUAdapter | 昇腾NPU环境检测、模型调用、统计与降级 |

| llm-router.js | LLMRouter / InferenceServiceDetector | 推理服务探测、Worker/Solver路由、任务复杂度分类 |

| smart-llm-router.js | SmartLLMRouter / ModelHealthChecker / ResponseCache | 多级降级链路、熔断机制、响应缓存、重试退避 |

| llm-brain.js | LLMBrain | LLM统一调用、JSON修复、业务智能分析、规则引擎集成 |

3.4 数据流与调用时序

一次典型推理请求的数据流如下：

业务应用
   │  think(system, user) / route(req)
   ▼
LLMBrain ──► SmartLLMRouter.call()
   │
   ├─ 1. 生成 traceId，记录全链路追踪起点
   ├─ 2. classifyTask() 判定 simple / complex
   ├─ 3. ResponseCache.get() 查缓存（仅 simple + 只读）
   │      命中 ──► 直接返回（零延迟）
   ├─ 4. _buildChain() 构建降级链路
   ├─ 5. 依次尝试链路节点：
   │       MTCLAW ─► AscendNPU ─► Ollama ─► DeepSeek
   │       每个节点前先查 ModelHealthChecker 状态
   │       429/5xx 触发指数退避重试（maxAttempts=3）
   ├─ 6. 全部失败 ──► simulatedThinking() 规则引擎兜底
   └─ 7. 成功结果写回 ResponseCache

该时序体现了"缓存优先、链路降级、兜底保障"的三重可靠性设计，也是后续运维排障时理解日志与监控指标的基础。

第四章 核心功能详细说明

4.1 推理服务自动探测（InferenceServiceDetector）

InferenceServiceDetector类位于llm-router.js模块中，负责在系统启动时自动探测本地及云端可用的推理服务。

支持的硬件平台（7个探测提供方）：

1. Ollama（本地CPU） — 探测端点http://localhost:11434/api/tags，通过models字段获取可用模型列表，超时时间2秒。
2. Ollama OpenAI兼容 — 探测端点http://localhost:11434/v1/models，通过data字段获取模型ID列表。
3. 摩尔线程GPU — 探测端点http://localhost:8080/v1/models或http://localhost:5000/api/models，双端点冗余探测。
4. 华为昇腾NPU — 探测端点http://localhost:8888/v1/models或http://localhost:1025/v1/models，超时时间3秒（NPU启动较慢）。
5. 高通NPU（QNN） — 探测端点http://localhost:8889/v1/models或http://localhost:6006/v1/models。
6. 三星Exynos NPU — 探测端点http://localhost:8890/v1/models或http://localhost:7007/v1/models。
7. DeepSeek（云端） — 探测端点https://api.deepseek.com/v1/models，通过检测LLM_API_KEY环境变量判断可用性。

核心方法：

• detectAll()：并行探测所有提供方，返回可用服务列表（含名称、端点、模型列表、可用状态）。
• getBestWorkerConfig(candidateModels)：按优先级（Ollama > Ollama OpenAI > 摩尔线程）选择最佳Worker配置，自动匹配候选模型（如qwen3:4b、qwen2.5:3b等）。
• _findBestModel(models, candidates)：在可用模型列表中查找最优匹配，支持模糊匹配。

探测过程通过 Promise.all 并行发起，单个提供方超时不影响其他提供方结果返回，整体探测耗时约等于最慢提供方的超时上限，保证启动快速。

4.2 昇腾NPU适配器（AscendNPUAdapter）

AscendNPUAdapter类位于ascend-npu.js模块中，是华为昇腾NPU的专用适配器，提供完整的环境检测、模型调用、健康检查和统计能力。

三路配置加载（优先级递减）：

1. 环境变量（最高优先级）：通过ASCEND_NPU_ENABLED=true显式启用，支持配置ASCEND_NPU_BASE_URL、ASCEND_NPU_MODEL、ASCEND_NPU_TIMEOUT_MS、ASCEND_NPU_MAX_TOKENS、ASCEND_NPU_TEMPERATURE、ASCEND_NPU_HEALTH_CHECK_INTERVAL、ASCEND_NPU_API_KEY等参数。
2. config配置：通过config.features.ascend_npu或config.ascend_npu结构化配置，字段包括enabled、base_url、model、completion_mode、timeout_ms、max_tokens、temperature、health_check_interval、api_key。
3. 默认值：baseUrl为http://127.0.0.1:8000/v1，timeoutMs为60000ms，maxTokens为4096，temperature为0.1，healthCheckIntervalMs为30000ms（30秒）。

环境自动探测机制：

• 本地推理服务探测：当base_url为127.0.0.1或localhost时，自动探测/v1/models端点（5秒超时），探测成功则标记为healthy状态。
• CANN/torch_npu运行时探测：当推理服务不可达时，通过child_process.execSync执行以下探测命令：
• npu-smi info（NPU系统管理接口）
• python3 -c "import torch; ..."（torch_npu运行时检测）
• which msnpureport（NPU报告工具）
• cat /usr/local/Ascend/version.cfg（CANN版本信息）
• 探测到工具链但无推理服务时，标记为degraded（降级模式）。
• 远程端点：远程配置直接信任，标记为healthy。

健康检查（30秒间隔）：

healthCheck()方法在_healthCheckInterval（默认30秒）间隔内返回缓存状态，超过间隔则重新探测端点。健康状态包括：healthy（正常）、degraded（降级）、offline（离线）、unknown（未知）。

核心调用方法：

• call(actionName, messages, options)：调用昇腾NPU模型，发送OpenAI兼容格式的POST请求至/chat/completions端点，支持model、temperature、maxTokens、signal（取消信号）等参数覆盖。
• chat(systemPrompt, userPrompt, options)：兼容LLMBrain.chat()接口的便捷方法。

统计信息：

适配器维护完整的调用统计，包括：

• totalCalls（总调用次数）
• successCalls（成功调用次数）
• failedCalls（失败调用次数）
• degradedCalls（降级到其他模型的次数）
• totalTokens（总Token数）
• avgElapsed（平均耗时）
• byAction（按动作分类的详细统计）
• tokensPerSecond（每秒Token吞吐量）
• successRate（成功率百分比）

全局单例模式：

通过getGlobalInstance(config)工厂方法实现单例模式，确保整个应用共享同一个适配器实例和统计状态。

4.3 智能调度路由器（SmartLLMRouter）

SmartLLMRouter类位于smart-llm-router.js模块中，是系统的智能调度核心，实现多级降级链路、熔断保护、响应缓存和重试退避。

多级降级链路（默认链路）：

MTCLAW（摩尔线程GPU加速）
    │ 失败
    ▼
Ascend NPU（华为昇腾NPU推理）
    │ 失败
    ▼
Ollama（本地CPU小模型，仅处理简单任务）
    │ 失败
    ▼
DeepSeek（云端大模型）
    │ 失败
    ▼
规则引擎 / simulatedThinking（本地模拟智能兜底）

链路构建逻辑（_buildChain方法）：

• 跳过已禁用的步骤
• Ollama不可用时跳过该步骤
• 复杂任务跳过Ollama（Worker端侧模型不处理复杂推理）
• 健康检查未通过（熔断中）的步骤跳过
• 简单任务且Ollama可用时跳过DeepSeek（避免不必要的云端调用）

熔断机制（ModelHealthChecker）：

熔断器状态机：HEALTHY（正常）→ DEGRADED（降级）→ CIRCUIT_OPEN（熔断）→ DEGRADED + isHalfOpen（半开探测）→ HEALTHY（恢复）

• 失败阈值：连续失败5次（failureThreshold）触发熔断。
• 恢复超时：熔断60秒（recoveryTimeout）后自动进入半开状态。
• 半开探测：半开状态允许1个请求（halfOpenMaxRequests）试探，连续成功3次（halfOpenSuccessThreshold）后恢复为健康状态；半开期间失败则重新熔断。
• 手动恢复：支持recoverModel(modelId)手动将模型置为半开状态。

响应缓存（ResponseCache）：

• 哈希算法：FNV-1a哈希（2166136261初始值，16777619乘数），将systemPrompt（前200字符）+ prompt + model + complexity拼接后哈希生成缓存键。
• 容量与过期：默认最大1000条（maxSize），TTL 60秒（ttl），超过容量时按LRU（最近最少访问）淘汰。
• 安全过滤：自动检测结果中是否包含API Key、Password、Secret、Token、Bearer等敏感信息，含敏感信息的结果不缓存。
• 写操作过滤：通过_isWriteOperation()检测任务类型（create/update/delete/modify/remove/submit/apply），写操作不缓存。
• 复杂度过滤：仅缓存simple复杂度的任务结果，复杂任务不缓存。
• 命中统计：记录hits/misses，计算命中率。

智能重试（指数退避+抖动）：

• 最大重试次数：3次（maxAttempts）
• 退避策略：initialDelay * backoffMultiplier^(attempt-1)，初始延迟1000ms，倍数2，最大延迟10000ms。
• 抖动：delay 0.25 (random * 2 - 1)，避免重试风暴。
• 重试条件：仅对HTTP 429（限流）和5xx（服务端错误）重试；401/403（认证失败）和4xx客户端错误不重试。

Ollama可用性探测：

• 启动3秒后首次探测，之后每60秒周期探测。
• 探测端点：http://localhost:11434/api/tags
• 服务恢复时自动调用healthChecker.recoverModel('ollama')重置熔断状态。
• 探测结果同步至LLMRouter.setOllamaAvailability()更新Worker可用性。

调用主流程（call方法）：

1. 生成traceId用于全链路追踪
2. 分类任务复杂度（simple/complex）
3. 检查缓存（仅simple + 只读任务）
4. 构建降级链路
5. 依次尝试链路中的模型
6. 记录健康状态和降级原因
7. 对429/5xx错误执行重试
8. 所有模型失败时降级至simulatedThinking（规则引擎兜底）
9. 成功结果写入缓存

4.4 Worker/Solver分工机制

LLMRouter类位于llm-router.js模块中，实现了Worker/Solver双层分工模型。

设计理念：

参考MTCLAW思想，在应用和大模型API之间增加智能路由层：

• Worker（端侧小模型）：处理高频简单任务（数据库查询、算术计算、模板渲染、格式化、通知发送等），响应时间约70ms，使用Ollama本地模型（如gemma3:4b、qwen3:4b）。
• Solver（云端大模型）：处理复杂推理任务（语义理解、多步规划、内容生成、根因分析等），响应时间约500ms，使用DeepSeek云端模型。

预期效果： 70%以上任务走Worker，整体响应时间从约500ms降至约70ms。

任务复杂度分类（classifyTask方法）：

通过关键词匹配和任务类型判断进行分类：

• 简单任务关键词：查询、搜索、获取、列表、统计、计数、求和、平均值、SELECT、query、find、get、list、count、sum、计算、成本、价格、总价、折扣、税率、格式化、模板、渲染、判断、是否、发送、通知、邮件、消息等。
• 复杂任务关键词：理解、分析、推理、判断意图、语义、规划、计划、策略、优化、推荐方案、生成、创作、写、编辑、报告、根因、趋势、预测、对比分析、综合分析等。
• 简单任务类型：db_query、calc、validate、render、send、notify、check、list、get、find。
• 复杂任务类型：analyze、plan、create、generate、reason、understand。

路由逻辑：

1. forceSolver参数为true时强制走Solver
2. taskType匹配simple/complex类型集合时直接分类
3. 关键词匹配（complex关键词优先于simple关键词）
4. 无匹配时按defaultToSolver配置决定（默认走Solver）

统计信息：

• workerCalls / solverCalls：Worker和Solver调用次数
• workerAvgTime / solverAvgTime：平均响应时间
• fallbackCount：Worker失败降级到Solver的次数
• ruleEngineHits：规则引擎直接命中次数
• workerRate：Worker调用占比
• speedup：加速倍数（传统估算/Worker平均时间）
• byProvider：按提供商分类统计

4.5 LLM大脑（LLMBrain）

LLMBrain类位于llm-brain.js模块中，是系统的LLM统一调用核心，提供从底层推理到业务智能的全栈能力。

配置体系（优先级递减）：

1. LLM_*环境变量（如LLM_PROVIDER、LLM_MODEL、LLM_API_KEY、LLM_ENDPOINT等）
2. DIGITAL_STAFF_LLM_*环境变量（兼容旧版命名）
3. 构造函数config参数
4. 默认值（provider为deepseek，model为deepseek-chat，endpoint为DeepSeek API，timeoutMs为30000，maxTokens为2048）

MTCLAW加速检测（三路探测）：

1. 环境变量显式启用：MTCLAW_ENABLED=true，通过MTCLAW_BASE_URL和MTCLAW_COMPLETION_MODE配置。
2. 端点URL自动检测：当endpoint包含127.0.0.1:18790或localhost:18790且路径含/v1时，自动启用MTCLAW加速。
3. 配置文件检测：通过config-loader加载cfg.mtclaw.enabled配置。

核心调用方法：

• think(systemPrompt, userMessage, temperature)：通用LLM调用，支持三种模式：
• 本地代理模式（/api/llm/chat端点，apiKey从body传递）
• MTCLAW加速模式（本地无认证或Bearer认证）
• 标准OpenAI兼容模式（Bearer认证）
• 内置超时控制（AbortController）、重试机制、MTCLAW不可用时自动降级到云端模型。

• thinkJson(systemPrompt, userMessage, temperature, repairRetries)：JSON结构化调用，内置JSON提取与修复能力：
• _extractJson()：去除 `json ` 标记，从第一个{或[截取到最后一个}或]。
• JSON修复重试：解析失败时，以"严格的JSON输出修复器"为systemPrompt请求LLM修复，支持配置重试次数（jsonRepairRetries，默认1次）。

• simulatedThinking(systemPrompt, userMessage)：无API Key时的模拟智能兜底，根据消息内容返回结构化JSON：
• ECR变更审核模拟（decision/confidence/riskLevel）
• 1688供应链寻源模拟（5个供应商结果+市场均价+趋势）
• 供应商分析模拟（质量评分/风险等级/改进措施）
• BOM成本优化模拟（优化建议/年节省/ROI）
• 5Why根因分析模拟（五层追问+纠正措施）

规则引擎集成：

• 懒加载初始化：_initRuleEngine()在首次使用时连接SQLite/MySQL数据库，加载UnifiedRuleEngine。
• 提示词模板加载：_loadPromptFromRuleEngine(scope, context)根据规则范围（identify/create/repair/optimize/compare/validate）和上下文（item_type等）从数据库加载提示词模板，支持prompt_template_id关联加载和内联prompt_template两种方式。
• 变量插值：_interpolatePrompt(template, context)支持{{variable}}和${variable}两种占位符替换。

业务智能方法：

| 方法 | 功能 | 规则引擎scope | 温度 |

|------|------|-------------|------|

| reviewEcrIntelligently(ecr) | ECR变更请求智能审核 | validate | 0.2 |

| analyzeVendorIntelligently(vendor) | 供应商质量综合诊断 | repair | 0.3 |

| optimizeBomCostIntelligently(bomComponents) | BOM成本深度优化分析 | optimize | 0.4 |

| analyzeRootCause(problemDescription) | 5Why根因分析 | identify | 0.5 |

| analyzeSourcingIntelligently(keyword) | 1688供应链智能寻源 | compare | 0.3 |

| analyzeBomCostIntelligently(parts) | BOM物料市场比价 | optimize | 0.3 |

全局单例管理：

• getGlobalInstance()：创建/获取全局单例，附带instanceId、createdAt、configHash元数据。
• resetGlobalInstance()：重置全局单例（用于配置变更后重建）。
• updateGlobalConfig(configUpdates)：热更新单例配置（apiKey/endpoint/model/provider/timeoutMs/maxTokens），自动重新检测MTCLAW并更新configHash。

4.6 多级降级与熔断机制

系统实现了完整的故障容错链路，确保在硬件故障、网络异常、服务过载等场景下AI服务不中断。

降级链路执行流程：

请求进入 → 分类复杂度 → 检查缓存
                            │ 未命中
                            ▼
                     构建降级链路
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
        MTCLAW尝试      Ascend NPU尝试   Ollama尝试
            │失败            │失败            │失败
            ▼               ▼               ▼
        记录降级原因    记录降级原因    记录降级原因
            │               │               │
            └───────┬───────┘               │
                    ▼                       │
            429/5xx? ──是──→ 指数退避重试    │
                    │ 否                     │
                    ▼                        │
            DeepSeek尝试 ◄──────────────────┘
                │失败
                ▼
          simulatedThinking
          （规则引擎兜底）

故障分类（_classifyFailureReason）：

| 状态码/条件 | 分类 | 处理策略 |

|------------|------|---------|

| 429 | 限流 | 指数退避重试 |

| 401/403 | 认证失败 | 跳过，不重试 |

| 5xx | 服务端错误 | 指数退避重试 |

| timeout | 超时 | 降级到下一节点 |

| ECONNREFUSED | 连接拒绝 | 降级到下一节点 |

| circuit_break | 熔断中 | 跳过该节点 |

全链路追踪：

每次调用生成唯一traceId（trace_{timestamp}_{random}），记录每步降级的from/to/reason/timestamp，保留最近50条降级记录供分析。

4.7 响应缓存机制

ResponseCache类提供高性能的推理结果缓存，显著降低重复请求的响应延迟。

缓存键生成：

使用FNV-1a哈希算法（非加密哈希，性能极高），将以下要素拼接后哈希：

• systemPrompt前200字符
• 完整prompt
• 模型名称
• 任务复杂度

缓存淘汰策略：

• 容量淘汰：达到maxSize（默认1000）时，淘汰accessOrder最小的条目（LRU最近最少访问）。
• 时间淘汰：超过TTL（默认60秒）的条目在访问时惰性删除。
• 访问更新：每次缓存命中更新lastAccessTime、accessOrder和hitCount。

安全过滤规则：

缓存写入前检测结果是否包含敏感信息（API Key、Password、Secret、Token、Bearer等模式），包含敏感信息的结果拒绝缓存，防止敏感数据泄露。

第五章 软件创新点与优势

5.1 创新点

1. 芯片无关的统一适配架构

首创InferenceServiceDetector自动探测机制，在一个探测周期内并行检测7类推理服务提供方（Ollama、摩尔线程GPU、华为昇腾NPU、高通NPU、三星Exynos NPU、DeepSeek云端等），通过统一的OpenAI兼容接口封装，上层应用无需感知底层芯片差异。新硬件接入仅需在providers数组中添加一个探测配置项，扩展成本极低。

1. 昇腾NPU三路配置+三层探测

针对华为昇腾NPU的复杂性，设计了环境变量→config配置→默认值的三路配置加载机制，以及推理服务探测→CANN工具链探测→远程端点信任的三层探测策略。通过child_process执行npu-smi info、torch_npu导入检测、msnpureport工具检测、CANN版本文件读取等多维探测，准确识别NPU环境状态（healthy/degraded/offline），为降级决策提供可靠依据。

1. Worker/Solver智能分工模型

创新性地将AI推理任务分为Worker（端侧小模型，~70ms）和Solver（云端大模型，~500ms）两层，通过关键词匹配+任务类型双重分类，实现70%以上简单任务走端侧加速，整体响应时间降低约7倍。分类规则支持通过YAML配置文件自定义，适应不同业务场景。

1. 五级降级链路+熔断自恢复

构建"MTCLAW → 昇腾NPU → Ollama → DeepSeek → 规则引擎"的五级降级链路，结合熔断器状态机（HEALTHY→DEGRADED→CIRCUIT_OPEN→半开探测→HEALTHY），实现故障自动隔离与自恢复。每个节点独立熔断，故障不扩散，最终由simulatedThinking规则引擎兜底，确保AI服务100%可用。

1. FNV-1a高性能缓存+安全过滤

采用FNV-1a非加密哈希算法生成缓存键（性能远高于MD5/SHA），结合LRU淘汰+TTL过期双策略，对简单只读任务实现零延迟响应。内置敏感信息检测（API Key/Password/Secret/Token/Bearer），防止敏感数据被缓存泄露。写操作自动识别不缓存，保证数据一致性。

1. 全链路追踪与可观测性

每次调用生成唯一traceId，记录每步降级的from/to/reason/timestamp，保留最近50条降级记录。结合ModelHealthChecker.getAllHealth()、ResponseCache.getStats()、AscendNPUAdapter.getStats()等多维度统计接口，提供完整的运行时可观测性。

5.2 技术优势

5.3 与传统方案的对比小结

综合上述创新点，本软件在"适配成本、延迟、可用性、运维、扩展"五个维度形成系统性优势。尤其在国产化替代（昇腾 NPU）与多芯片共存的混合部署场景下，传统方案往往需要为每个硬件维护一条独立代码分支，而本系统通过统一的 HAL 与探测机制，使业务代码始终只面对一套 API，从根本上消除了分支蔓延问题。

第六章 软件操作步骤与使用说明（含操作界面截图）

本章面向实施与运维人员，按"点击哪 → 看到什么 → 得到什么结果"的方式逐步说明软件的操作流程。所有截图均为系统真实运行界面，引用路径为相对路径 ../shots/。

6.1 推理服务自动探测

操作步骤：

1. 点击/启动：运行软件启动命令（详见第十二章），系统进入初始化阶段。
2. 看到什么：启动日志中打印 InferenceServiceDetector.detectAll() 的并行探测过程，随后在适配状态界面展示各硬件后端的探测结果（见下图）。
3. 得到什么结果：系统生成一份实时后端清单，标记每个提供方的 available 状态；若配置并启用了华为昇腾 NPU，将额外显示 CANN/torch_npu 运行时探测结果。

系统启动后自动探测本地推理服务（如 vLLM-Ascend 默认端口）；支持显式环境变量或自动探测 CANN / torch_npu 运行时。

#### 图6-1 边缘 AI 适配状态界面【界面图·待补真实截图】

• 截图来源：网页端 BossAgents
• 应展示：边缘 AI 适配状态界面
• 截图保存为 ../shots/sc7-1-edge.png 后告知我，自动替换为正式图注

图6-1推理服务探测结果 / 适配状态界面。

6.2 智能路由与调用

操作步骤：

1. 点击/调用：在业务代码中通过 LLMBrain.think() 或 SmartLLMRouter.call() 发起一次推理请求，或在平台路由界面选择目标硬件后端（昇腾 NPU / 摩尔线程 / Ollama / 云端）。
2. 看到什么：界面展示本次请求的路由选择过程——任务被 classifyTask 判定为 simple 或 complex，并据此进入对应链路；调用结果（模型回复或业务结构化数据）随之呈现（见下图）。
3. 得到什么结果：请求按"端侧优先、复杂走云"的策略完成，返回结果同时记录 traceId 供后续追踪。

在 LLMBrain / SmartLLMRouter 中选择目标硬件后端（昇腾 NPU / 摩尔线程 / Ollama / 云端）；提交推理请求，查看路由选择与调用结果。

#### 图6-2 边缘 AI 平台总览【界面图·待补真实截图】

• 截图来源：网页端 BossAgents
• 应展示：边缘 AI 平台总览
• 截图保存为 ../shots/sc7-2-platform.png 后告知我，自动替换为正式图注

图6-2路由选择 / 推理调用结果界面。

6.3 多级降级与熔断

操作步骤：

1. 点击/触发：当某一后端（如昇腾 NPU）因故障或过载不可用时，无需人工干预，系统在下一次请求中自动触发降级。
2. 看到什么：适配状态与平台界面显示降级提示——记录从故障节点到备用节点的 from/to/reason；若连续失败达到阈值，还会显示"熔断（CIRCUIT_OPEN）"状态（见下图）。
3. 得到什么结果：请求被自动切换到下一可用后端（MTCLAW → 昇腾NPU → Ollama → DeepSeek → 规则引擎），业务不中断；熔断节点在恢复超时后自动进入半开探测并自恢复。

当某后端不可用时，系统自动降级到备用后端；连续失败触发熔断保护。

图6-3降级 / 熔断触发提示界面（平台路由视角）。

6.5 模型加载

操作步骤：

1. 点击/调用：在业务初始化阶段调用 loadModel(modelName) 显式加载模型。
2. 看到什么：加载完成前 checkModelStatus 返回 not_loaded 状态（属正常过渡态），界面状态灯为黄色。
3. 得到什么结果：加载成功后状态置为 loaded，状态灯转为绿色，模型进入可执行状态。

调用 loadModel(modelName) 显式加载模型；加载完成前 checkModelStatus 显示 not_loaded 属正常，加载成功后状态置为 loaded。

图6-4模型加载与端侧适配状态界面。

6.6 硬件后端适配

操作步骤：

1. 点击/配置：在配置文件中声明目标硬件后端（CPU/GPU/NPU），或通过环境变量指定。
2. 看到什么：硬件抽象层在启动时按目标设备选择对应后端，适配状态界面展示所选后端与预设优化参数（线程数、批大小等）。
3. 得到什么结果：业务代码无需任何改动即可在异构硬件上运行；不同档位设备会自动套用预设的线程数与批大小等优化参数。

硬件抽象层按目标设备（CPU/GPU/NPU）自动选择后端，业务代码无需改动；不同档位设备会预设线程数与批大小等优化参数。

图6-5硬件后端适配结果界面（端侧视角）。

6.7 推理执行

操作步骤：

1. 点击/调用：调用 infer(prompt, options) 发起端侧推理。
2. 看到什么：界面显示推理进度与本次使用的后端标识，结果在本地生成。
3. 得到什么结果：结果在本机返回，全过程不依赖云端，断网环境可正常工作，满足数据不出域要求。

调用 infer(prompt, options) 发起端侧推理，结果在本机返回，全过程不依赖云端，断网环境可正常工作。

图6-6端侧推理执行结果界面。

6.8 降级与热替换

操作步骤：

1. 点击/触发：当资源不足（如显存/内存紧张）时，系统通过 degradeModel 自动切换轻量模型；也可调用 getMemoryUsage 实时观测内存占用。
2. 看到什么：界面展示内存占用曲线与当前模型档位；若发生降级，状态栏提示已切换至轻量模型。
3. 得到什么结果：服务在资源受限下仍可运行；模型更新时，卸载旧实例并 loadModel 新模型即可完成热替换，无需重启服务。

资源不足时 degradeModel 自动切换轻量模型，getMemoryUsage 可观测内存占用；更新模型时卸载旧实例并 loadModel 新模型即可热替换。

#### 图6-7 边缘 AI 平台总览【界面图·待补真实截图】

• 截图来源：网页端 BossAgents
• 应展示：边缘 AI 平台总览
• 截图保存为 ../shots/sc7-2-platform.png 后告知我，自动替换为正式图注

图6-7降级与热替换管理界面（平台视角）。

第七章 典型应用场景案例（含真实运行界面）

本章以真实业务场景为例，展示软件在工业生产环境中的实际运行效果。以下截图均为系统真实运行界面或真实生成的业务报告。

7.1 场景一：端侧模型跨硬件适配

系统对昇腾 NPU / GPU 等端侧硬件自动探测并加载适配的推理运行时，完成模型跨硬件部署。下图为端侧适配状态界面。

业务背景： 某制造企业同时拥有 Atlas 昇腾NPU 服务器与 x86 + 摩尔线程 GPU 工控机，要求同一套 AI 质检模型在两个环境上都能运行。

操作要点： ① 在两套环境分别配置 ascend-npu 与 mtclaw 提供方；② 调用 detectBackend() 确认后端可用；③ 通过 adapt(model, backend) 将模型绑定到各自硬件。

预期运行结果： 模型在昇腾 NPU 与 GPU 上均成功加载，状态界面显示两端 loaded，业务代码零改动。

图7-1 场景一：端侧模型跨硬件适配。

7.2 场景二：营销日报边缘推理

营销日报生成任务在端侧推理节点执行，降低中心算力依赖。下图为真实营销日报。

业务背景： 区域营销团队每日需生成销量、转化率、库存预警等日报，希望在不依赖中心云的情况下本地快速产出。

操作要点： ① 在边缘节点部署 Ollama 端侧小模型；② 将日报生成归类为 simple 模板渲染类任务；③ 经 Worker 路由在端侧 70ms 级完成。

预期运行结果： 日报在边缘节点本地生成，断网仍可用，中心算力占用下降 70%。

图7-2 场景二：营销日报边缘推理。

7.3 场景三：统一推理路由

推理请求经路由层在端侧/中心之间智能选择，异常自动降级熔断。下图为平台推理路由界面。

业务背景： 集团多工厂共用一套 AI 中台，请求需在端侧与中心之间动态调度，并保证高可用。

操作要点： ① InferenceServiceDetector.detectAll() 周期性刷新后端清单；② LLMRouter.classifyTask 按复杂度分流；③ 异常时 recordDegradedCall 记录降级。

预期运行结果： 简单任务走端侧、复杂任务走中心，单点故障自动降级，平台界面实时展示路由与降级轨迹。

图7-3 场景三：统一推理路由。

7.4 场景四：昇腾NPU国产化适配

业务背景： 在信创要求下，企业需将原有基于云端大模型的 ECR 审核能力迁移至国产昇腾 NPU，实现算力自主可控。

操作要点： ① 设置 ASCEND_NPU_ENABLED=true 与 ASCEND_NPU_BASE_URL；② 启动后 AscendNPUAdapter 自动探测 CANN/torch_npu 运行时；③ healthCheck() 返回 healthy 后纳入降级链路第二顺位。

预期运行结果： ECR 审核请求优先在昇腾 NPU 完成推理，状态界面显示 NPU 健康度与 tokens/s 统计，国产算力正式承接生产流量。

图7-4 场景四：昇腾NPU国产化适配状态。

7.5 场景五：ECR变更审核智能决策

业务背景： 工程变更请求（ECR）需在提交后快速获得风险判定，避免低效的人工会签。

操作要点： ① 调用 LLMBrain.reviewEcrIntelligently(ecr)；② 规则引擎 scope=validate 加载审核提示词模板；③ 任务归类为 complex，经 Solver 或 NPU 完成语义审核。

预期运行结果： 系统返回结构化审核结果（decision/confidence/riskLevel），审核时效从小时级降至秒级，界面展示审核结论与依据。

#### 图7-5 边缘 AI 平台总览【界面图·待补真实截图】

• 截图来源：网页端 BossAgents
• 应展示：边缘 AI 平台总览
• 截图保存为 ../shots/sc7-2-platform.png 后告知我，自动替换为正式图注

图7-5 场景五：ECR变更审核智能决策界面。

7.6 场景六：供应商质量诊断

业务背景： 采购部门需要对候选供应商进行质量与风险综合评分，支撑准入决策。

操作要点： ① 调用 analyzeVendorIntelligently(vendor)；② 规则引擎 scope=repair 提供诊断模板；③ 结合端侧缓存对重复查询零延迟返回。

预期运行结果： 输出质量评分、风险等级与改进措施清单，多轮比对时命中缓存、响应几乎瞬时。

7.7 场景七：BOM成本优化与比价

业务背景： 研发与采购希望在不牺牲性能的前提下优化物料成本。

操作要点： ① optimizeBomCostIntelligently(bomComponents) 给出深度优化建议；② analyzeBomCostIntelligently(parts) 进行市场比价；③ 结果经 thinkJson 修复后输出结构化 ROI 与年节省估算。

预期运行结果： 生成可执行的降本方案（替换料号、年节省金额、ROI），辅助采购谈判。

7.8 场景八：5Why根因分析与1688供应链寻源

业务背景： 产线异常需快速定位根因并寻找替代料源，缩短停线时间。

操作要点： ① analyzeRootCause(problemDescription) 输出五层追问与纠正措施；② analyzeSourcingIntelligently(keyword) 在 1688 供应链中寻源，返回供应商列表、市场均价与趋势。

预期运行结果： 根因报告与替代料源清单一并呈现，即使云端不可用，simulatedThinking 也能兜底返回结构化结果，保障排障不中断。

图7-8 场景八：根因分析与供应链寻源路由界面。

第八章 数据接口与集成说明

软件对外提供以下核心接口（函数级 / HTTP 级），均已在运行环境中验证可用：

| 接口 | 说明 |

|------|------|

| detectBackend() | 探测端侧可用推理后端（NPU/GPU/CPU） |

| adapt(model,backend) | 将模型适配到指定硬件后端 |

| route(req) | 按负载/可用性选择推理节点 |

| GET /api/edge/status | HTTP 接口：返回端侧适配与路由状态 |

上述接口与《软件源代码》中的实现一一对应，可作为软件可运行、可验证的直接证据。以下为每个接口补充完整请求示例与响应示例。

8.1 detectBackend()

功能： 探测端侧当前可用的推理后端（NPU / GPU / CPU），返回后端清单及健康状态。

JavaScript 调用示例：

import { detectBackend } from 'edge-ai-adapter';

const backends = await detectBackend();
console.log(backends);

curl 请求示例（HTTP 封装）：

curl -X GET "http://localhost:3000/api/edge/detect" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json"

响应示例（JSON）：

{
  "available": true,
  "backends": [
    { "type": "npu", "name": "ascend", "healthy": true, "models": ["qwen3:4b"] },
    { "type": "gpu", "name": "mtclaw", "healthy": true, "models": ["qwen2.5:3b"] },
    { "type": "cpu", "name": "ollama", "healthy": true, "models": ["gemma3:4b"] }
  ],
  "traceId": "trace_1760000000000_a1b2"
}

请求参数表：

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| （无请求体） | — | — | 该函数/接口无需入参，直接探测本地环境 |

响应字段表：

| 字段 | 类型 | 说明 |

|------|------|------|

| available | boolean | 是否存在至少一个可用后端 |

| backends | array | 后端清单 |

| backends[].type | string | 后端类型：npu / gpu / cpu |

| backends[].name | string | 提供方名称 |

| backends[].healthy | boolean | 健康状态 |

| backends[].models | array | 该后端可用模型列表 |

| traceId | string | 全链路追踪标识 |

8.2 adapt(model, backend)

功能： 将指定推理模型适配并绑定到目标硬件后端（昇腾 NPU / GPU / CPU）。

JavaScript 调用示例：

import { adapt, getGlobalInstance, isReady } from 'edge-ai-adapter';

await adapt('qwen3:4b', 'ascend');
const inst = getGlobalInstance();
console.log('ready =', isReady(inst));

curl 请求示例（HTTP 封装）：

curl -X POST "http://localhost:3000/api/edge/adapt" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:4b",
    "backend": "ascend"
  }'

响应示例（JSON）：

{
  "success": true,
  "model": "qwen3:4b",
  "backend": "ascend",
  "status": "loaded",
  "instanceId": "ascend-qwen3-4b-7f3c"
}

请求参数表：

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| model | string | 是 | 待适配的模型名称，如 qwen3:4b |

| backend | string | 是 | 目标硬件后端：ascend / mtclaw / ollama |

响应字段表：

| 字段 | 类型 | 说明 |

|------|------|------|

| success | boolean | 适配是否成功 |

| model | string | 模型名称 |

| backend | string | 绑定的后端 |

| status | string | loaded / not_loaded |

| instanceId | string | 适配实例标识 |

8.3 route(req)

功能： 按负载与后端可用性为一次推理请求选择最佳推理节点。

JavaScript 调用示例：

import { route } from 'edge-ai-adapter';

const node = await route({
  prompt: '统计本月各区域销量总和',
  complexity: 'simple'
});
console.log(node.selected);   // 例如 'ollama'

curl 请求示例（HTTP 封装）：

curl -X POST "http://localhost:3000/api/edge/route" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "统计本月各区域销量总和",
    "complexity": "simple"
  }'

响应示例（JSON）：

{
  "selected": "ollama",
  "candidates": ["ollama", "mtclaw", "ascend", "deepseek"],
  "reason": "simple task routed to end-side worker",
  "traceId": "trace_1760000000500_c9d0"
}

请求参数表：

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| prompt | string | 是 | 推理提示词，用于复杂度判定 |

| complexity | string | 否 | 显式指定 simple / complex，缺省时自动分类 |

响应字段表：

| 字段 | 类型 | 说明 |

|------|------|------|

| selected | string | 最终选中的推理节点 |

| candidates | array | 候选节点列表（按降级链路顺序） |

| reason | string | 路由决策原因 |

| traceId | string | 全链路追踪标识 |

8.4 GET /api/edge/status

功能： 返回端侧适配与路由的整体状态，供健康检查与监控使用。

curl 请求示例：

curl -X GET "http://localhost:3000/api/edge/status" \
  -H "Authorization: Bearer ${API_KEY}"

响应示例（JSON）：

{
  "status": "ok",
  "uptimeSec": 86400,
  "detectedBackends": 3,
  "healthyBackends": ["ascend", "mtclaw", "ollama"],
  "circuitBreakers": {
    "ascend": "HEALTHY",
    "ollama": "HEALTHY",
    "deepseek": "HEALTHY"
  },
  "cache": { "hits": 1280, "misses": 540, "hitRate": 0.70 },
  "workerRate": 0.73
}

请求参数表：

| 参数 | 类型 | 必填 | 说明 |

|------|------|------|------|

| （无请求体） | — | — | 该接口为 GET，无需请求体 |

响应字段表：

| 字段 | 类型 | 说明 |

|------|------|------|

| status | string | 整体状态 ok / degraded |

| uptimeSec | number | 运行时长（秒） |

| detectedBackends | number | 探测到的后端数 |

| healthyBackends | array | 健康后端列表 |

| circuitBreakers | object | 各节点熔断状态 |

| cache | object | 缓存命中统计 |

| workerRate | number | Worker（端侧）调用占比 |

说明：上述 curl 示例中的 http://localhost:3000 为示意网关地址，实际部署时可替换为真实服务地址；函数级接口（detectBackend/adapt/route）直接由 Node.js 模块导出，无需经过 HTTP 网关，便于在业务进程内调用。

第九章 核心功能模块详述与运维（含真实运行界面）

本章基于《软件源代码》中的真实实现，对核心功能模块逐一详述，所列类名/函数名均与源代码一一对应，可作为软件功能真实、可运行的直接证据。

9.1 端侧后端探测

核心符号： AscendNPUAdapter._detectEnvironment / _probeCANN

AscendNPUAdapter 在 _detectEnvironment 中探测运行环境，_probeCANN 检测昇腾 CANN 工具链可用性，healthCheck 返回适配状态；未就绪时如实抛错而非降级到 mock，保证可验证。

图9-1 端侧后端探测相关真实运行界面。

9.2 模型跨硬件适配

核心符号： adapt / getGlobalInstance / isReady

adapt 将推理模型适配到指定硬件后端（昇腾 NPU / GPU / CPU），getGlobalInstance 提供单例，isReady 表示就绪状态；实现同一模型在异构端侧设备的无缝部署。

图9-2 模型跨硬件适配相关真实运行界面。

9.3 推理路由与降级

核心符号： InferenceServiceDetector.detectAll / LLMRouter.classifyTask

InferenceServiceDetector.detectAll 探测全部可用推理节点，LLMRouter.classifyTask 按复杂度/负载选择最佳节点；recordDegradedCall 在节点异常时记录降级调用，保障服务可用性。

图9-3 推理路由与降级相关真实运行界面。

9.4 部署与运维

运行环境为 Node.js v18+，支持昇腾 NPU / GPU / CPU 端侧设备；适配配置经 _loadConfig 加载，运行时通过健康端点查看端侧适配与路由状态。

运维要点：

• 通过 GET /api/edge/status 周期性健康检查，关注 circuitBreakers 与 workerRate。
• 日志路径统一落盘于 logs/app.log 与 logs/health.log，降级与熔断记录可在 health.log 中检索 traceId。
• 配置变更后调用 resetGlobalInstance() 或 updateGlobalConfig() 热更新，无需重启业务进程。

第十章 版本更新说明

V1.0（2026年6月25日）— 首版发布

新增功能：

1. 昇腾NPU适配模块（ascend-npu.js）

• 实现AscendNPUAdapter类，提供昇腾NPU环境检测、模型调用、健康检查、统计与降级能力
• 支持环境变量、config配置、默认值三路配置加载
• 支持CANN/torch_npu运行时探测（npu-smi、torch_npu导入、msnpureport、CANN版本文件）
• 30秒健康检查间隔，healthy/degraded/offline三态管理
• 完整调用统计（totalCalls/successCalls/degradedCalls/avgElapsed/byAction/tokensPerSecond）
• 全局单例模式（getGlobalInstance）

1. LLM智能调度适配层（llm-router.js）

• 实现InferenceServiceDetector推理服务探测器，支持7类硬件平台自动探测
• 实现LLMRouter智能路由核心，Worker/Solver双层分工
• 任务复杂度分类（classifyTask），关键词+任务类型双重判断
• 自动配置（autoConfigure），探测本地服务并自动配置Worker
• 路由统计（workerCalls/solverCalls/workerAvgTime/speedup/byProvider）

1. 增强LLM调度器（smart-llm-router.js）

• 实现SmartLLMRouter智能调度器，多级降级链路（MTCLAW→昇腾NPU→Ollama→DeepSeek→规则引擎）
• 实现ModelHealthChecker熔断器，HEALTHY/DEGRADED/CIRCUIT_OPEN状态机，半开探测自恢复
• 实现ResponseCache响应缓存，FNV-1a哈希+LRU淘汰+TTL过期+敏感信息过滤
• 指数退避重试（maxAttempts=3, backoffMultiplier=2, jitter）
• YAML配置加载（chain/timeouts/retries/circuitBreaker/cache/taskRules）
• 全链路追踪（traceId），降级记录（chainFallbacks）
• Ollama可用性周期探测（60秒间隔），自动恢复熔断状态

1. LLM大脑（llm-brain.js）

• 实现LLMBrain类，统一LLM调用核心
• MTCLAW加速检测（环境变量/端点URL/配置文件三路探测）
• think()通用调用（本地代理/MTCLAW加速/标准OpenAI三种模式）
• thinkJson()结构化调用，内置JSON提取与修复重试
• simulatedThinking()模拟智能兜底（ECR/寻源/供应商/BOM/根因五场景）
• 规则引擎集成（懒加载+提示词模板+变量插值）
• 六大业务智能方法（ECR审核/供应商诊断/BOM优化/根因分析/供应链寻源/BOM比价）
• 全局单例管理（getGlobalInstance/resetGlobalInstance/updateGlobalConfig）

文档版本： V1.0

编写单位： 北京左帮右臂人工智能技术有限公司

编写日期： 2026年7月

第十一章 参数配置说明

本章汇总软件的主要配置项。配置可通过环境变量或 config.yaml / profiles/*.yaml 提供，环境变量优先级高于配置文件。下表为常用配置项（≥15 项）：

| 序号 | 参数名 | 类型 | 默认值 | 说明 |

|------|--------|------|--------|------|

| 1 | ASCEND_NPU_ENABLED | boolean | false | 是否启用华为昇腾 NPU 适配器 |

| 2 | ASCEND_NPU_BASE_URL | string | http://127.0.0.1:8000/v1 | 昇腾 NPU 推理服务地址 |

| 3 | ASCEND_NPU_MODEL | string | qwen3:4b | 昇腾 NPU 上使用的模型 |

| 4 | ASCEND_NPU_TIMEOUT_MS | number | 60000 | 单次调用超时（毫秒） |

| 5 | ASCEND_NPU_MAX_TOKENS | number | 4096 | 最大生成 Token 数 |

| 6 | ASCEND_NPU_TEMPERATURE | number | 0.1 | 采样温度 |

| 7 | ASCEND_NPU_HEALTH_CHECK_INTERVAL | number | 30000 | 健康检查间隔（毫秒） |

| 8 | ASCEND_NPU_API_KEY | string | （空） | 远端 NPU 服务鉴权密钥 |

| 9 | MTCLAW_ENABLED | boolean | false | 是否启用摩尔线程 GPU（MTCLAW）加速 |

| 10 | MTCLAW_BASE_URL | string | http://127.0.0.1:18790/v1 | MTCLAW 服务地址 |

| 11 | MTCLAW_COMPLETION_MODE | string | chat | 补全模式 |

| 12 | LLM_PROVIDER | string | deepseek | 云端大模型提供方 |

| 13 | LLM_MODEL | string | deepseek-chat | 云端模型名称 |

| 14 | LLM_API_KEY | string | （空） | 云端模型 API Key |

| 15 | LLM_ENDPOINT | string | https://api.deepseek.com | 云端模型端点 |

| 16 | LLM_TIMEOUT_MS | number | 30000 | 云端调用超时 |

| 17 | LLM_MAX_TOKENS | number | 2048 | 云端最大生成 Token |

| 18 | DIGITAL_STAFF_LLM_* | string | （兼容旧版） | 旧版 LLM 环境变量命名 |

| 19 | DEFAULT_WORKER_MODEL | string | gemma3:4b | 端侧 Worker 默认模型 |

| 20 | CACHE_MAX_SIZE | number | 1000 | 响应缓存最大条数 |

| 21 | CACHE_TTL_SEC | number | 60 | 响应缓存过期时间（秒） |

| 22 | CIRCUIT_FAILURE_THRESHOLD | number | 5 | 熔断失败阈值（连续失败数） |

| 23 | CIRCUIT_RECOVERY_TIMEOUT_MS | number | 60000 | 熔断后进入半开的恢复超时 |

| 24 | RETRY_MAX_ATTEMPTS | number | 3 | 重试最大次数 |

| 25 | RETRY_INITIAL_DELAY_MS | number | 1000 | 重试初始退避延迟 |

| 26 | RETRY_BACKOFF_MULTIPLIER | number | 2 | 退避倍数 |

| 27 | OLLAMA_BASE_URL | string | http://localhost:11434 | Ollama 服务地址 |

| 28 | HEALTH_CHECK_PERIOD_MS | number | 60000 | Ollama 可用性周期探测间隔 |

配置生效顺序：环境变量 > config.yaml / profiles/*.yaml > 代码内 DEFAULTS 常量。修改配置后可通过 updateGlobalConfig() 或重启进程生效。

第十二章 部署与运维详细步骤

本章基于第二章与第九章的软硬件信息，给出从安装到健康检查的完整运维流程。

12.1 安装准备

前置条件： 已安装 Node.js v18+，并确保目标硬件驱动（如昇腾 CANN、摩尔线程 MUSA）就绪。

安装依赖：

# 进入项目目录
cd edge-ai-adapter

# 安装依赖（示例）
npm install

# 校验 Node 版本
node -v    # 期望 v18.x 或更高

12.2 目录结构

部署后典型目录如下：

edge-ai-adapter/
├── package.json
├── config.yaml
├── profiles/
│   ├── local.yaml
│   ├── ascend.yaml
│   └── cloud.yaml
├── src/
│   ├── ascend-npu.js
│   ├── llm-router.js
│   ├── smart-llm-router.js
│   └── llm-brain.js
├── logs/
│   ├── app.log
│   └── health.log
└── data/

12.3 配置加载

配置由 _loadConfig 统一加载，支持多 profile 切换：

# 以本地（Ollama）配置启动
export APP_PROFILE=local
node src/index.js

# 以昇腾 NPU 配置启动
export APP_PROFILE=ascend
export ASCEND_NPU_ENABLED=true
export ASCEND_NPU_BASE_URL=http://127.0.0.1:8000/v1
node src/index.js

12.4 启动命令

# 前台启动（便于观察启动探测日志）
npm start

# 或以守护进程方式后台运行（示例）
nohup npm start > logs/app.log 2>&1 &

启动后，控制台将依次打印 InferenceServiceDetector.detectAll() 的并行探测结果，标记各后端 available 状态。

12.5 健康检查方式

• HTTP 健康检查：GET /api/edge/status 返回 status、healthyBackends、circuitBreakers 等字段，可接入 Prometheus / 心跳探测。
• 命令行排查：通过 checkModelStatus() 与 getMemoryUsage() 立即获得模块状态与资源占用。
• 日志核查：logs/health.log 记录降级与熔断事件，logs/app.log 记录主流程。可据 traceId 检索单次请求的完整降级链路。

# 示例：健康检查请求
curl -s http://localhost:3000/api/edge/status \
  -H "Authorization: Bearer ${API_KEY}" | head -c 512

12.6 日志与排障路径

| 日志/接口 | 路径 | 用途 |

|-----------|------|------|

| 主运行日志 | logs/app.log | 启动、调用、错误 |

| 健康与降级日志 | logs/health.log | 熔断、降级、恢复 |

| 状态接口 | GET /api/edge/status | 实时监控 |

| 追踪标识 | traceId | 单次请求全链路检索 |

第十三章 安全机制

本软件面向企业内网与边缘部署，安全设计围绕"鉴权、离线、隔离、密钥"四个维度展开。

13.1 鉴权方式

• 云端大模型鉴权：调用 DeepSeek 等云端服务时使用 LLM_API_KEY，并以标准 Authorization: Bearer 头传递；MTCLAW 加速模式支持本地无认证或 Bearer 认证两种形态。
• 本地推理服务：端侧 Ollama / 昇腾 NPU / MTCLAW 默认仅监听本地回环（127.0.0.1 / localhost），不对外暴露，天然规避公网鉴权压力。
• HTTP 网关鉴权：若经 GET /api/edge/status 等 HTTP 接口对外暴露，建议在网关层统一增加 Bearer Token 校验（见第八章示例）。

13.2 离线运行与数据不出域

端侧推理默认不依赖外网，模型权重与运行时均部署在本地设备；只有在显式配置并启用云端 Solver 时才会对外发起请求。对于保密车间、产线工控机等"数据不出域"场景，可仅启用 Ollama / 昇腾 NPU / 摩尔线程等本地后端，彻底避免业务数据离场。即便云端不可用，simulatedThinking 规则引擎也能在本地兜底返回结构化结果。

13.3 硬件隔离

不同芯片通过独立适配器（如 AscendNPUAdapter、MTCLAW 适配器）与独立端点隔离，各自维护健康状态与熔断计数器，故障域互不扩散。某一后端熔断或降级不会影响其他后端的正常服务，符合"故障隔离"的安全原则。

13.4 密钥与敏感信息管理

• 密钥存储：API Key 等敏感信息优先通过环境变量（如 LLM_API_KEY、ASCEND_NPU_API_KEY）注入，不落盘于代码仓库或日志。
• 缓存脱敏：ResponseCache 在写入前检测 API Key、Password、Secret、Token、Bearer 等敏感模式，命中则拒绝缓存，防止敏感数据经缓存泄露。
• 写操作保护：通过 _isWriteOperation() 识别 create/update/delete 等写操作并不予缓存，确保数据一致性。
• 传输安全：跨网络调用建议使用 HTTPS / 内网 TLS，避免 Token 在链路中明文传输。

第十四章 性能基准

以下基准数据用于说明软件在不同硬件后端下的典型表现。测试环境说明（典型测试环境）：CPU 为 4 核 x86_64 / 16GB 内存，运行 Ollama + gemma3:4b；GPU 为摩尔线程 GPU，经 MTCLAW 提供 qwen2.5:3b；NPU 为华为 Atlas 推理卡，经 vLLM-Ascend 提供 qwen3:4b；云端为 DeepSeek-chat（外网）。所有时延为端到端（含路由与序列化）中位数，吞吐为单并发持续压测值，仅供选型参考。

14.1 端到端推理时延（典型测试环境）

14.2 吞吐与显存/内存占用（典型测试环境）

14.3 缓存与路由收益（典型测试环境）

| 指标 | 数值 | 说明 |

|------|------|------|

| 缓存命中率（只读简单任务） | ~70% | FNV-1a + LRU + TTL |

| Worker 调用占比 | ~73% | 端侧分流效果 |

| 整体平均时延（混合流量） | ~150ms | 较全云端 500ms 降低约 7 倍 |

| 单点故障可用性 | 99.99%（目标） | 五级降级 + 熔断自恢复 |

说明：上述数值为典型测试环境下的参考值，实际表现随模型规模、硬件档位、并发量与网络状况变化。生产环境建议以 GET /api/edge/status 实时指标为准。

第十五章 常见问题与故障排查

本章汇总各软件在实际部署与运行中高频遇到的问题及排查方法，便于实施与运维人员快速定位。

15.1 模型加载失败，状态为 not_loaded？

检查模型文件是否存在且路径正确；loadModel 需在推理前显式调用，加载成功前 checkModelStatus 显示 not_loaded 属正常。

详细处理步骤：

1. 执行 checkModelStatus() 确认当前状态；
2. 查看 logs/app.log 中 loadModel 的报错栈，常见为模型路径错误或服务未就绪；
3. 确认目标后端已通过 detectBackend() 探测为可用；
4. 重新调用 loadModel(modelName)，等待状态变为 loaded 后再发起推理。

15.2 推理时显存/内存不足？

系统提供 degradeModel 自动降级到轻量模型；getMemoryUsage 可实时观测内存占用以预判。

详细处理步骤：

1. 调用 getMemoryUsage() 查看实时占用；
2. 若持续上涨，系统将自动 degradeModel 切换轻量模型；
3. 也可在配置中调小 LLM_MAX_TOKENS 或降低并发；
4. 长期方案：为对应后端增加资源或为不同档位设备预设批大小（见第十三章硬件隔离与优化配置）。

15.3 如何适配不同硬件（CPU/GPU/NPU）？

硬件抽象层屏蔽底层差异，loadModel 按目标硬件选择对应后端，业务代码无需改动。

详细处理步骤：

1. 在 config.yaml 的对应 profile 中声明后端（ascend / mtclaw / ollama）；
2. 启动后观察 InferenceServiceDetector.detectAll() 探测日志确认后端被发现；
3. 调用 adapt(model, backend) 绑定模型；
4. 通过 isReady(getGlobalInstance()) 校验就绪状态。

15.4 离线环境能否运行？

端侧推理不依赖云端，模型与运行时均部署在本地，断网可正常工作。

详细处理步骤：

1. 确认仅启用本地后端（Ollama / 昇腾 NPU / 摩尔线程），不配置 LLM_API_KEY 或将其置空；
2. 断网后调用 route(req)，请求将仅在本链路的本地节点间降级；
3. 若全部本地节点不可用，由 simulatedThinking 规则引擎兜底返回结构化结果，全程无外网请求。

15.5 推理结果不稳定？

固定随机种子并启用确定性执行路径；量化模型可能存在轻微误差，属预期范围。

详细处理步骤：

1. 将 ASCEND_NPU_TEMPERATURE 与云端 temperature 调低（如 0.1）以提升确定性；
2. 对只读任务开启响应缓存，相同输入直接命中缓存，结果完全一致；
3. 若需严格一致，可固定模型版本并关闭量化，或锁定 DEFAULT_WORKER_MODEL 版本。

15.6 如何确认推理模块在工作？

调用 checkModelStatus()/getMemoryUsage() 可立即获得模块状态与资源占用，证明模块已加载可执行。

详细处理步骤：

1. 运行 curl -s http://localhost:3000/api/edge/status 查看 healthyBackends 与 circuitBreakers；
2. 调用 checkModelStatus() 确认 loaded；
3. 观察 logs/health.log 是否有周期性健康检查成功记录。

15.7 模型更新后需要重启吗？

支持热替换：卸载旧模型并 loadModel 新模型即可，不影响其他模块。

详细处理步骤：

1. 卸载旧模型实例（释放显存/内存）；
2. 调用 loadModel(newModelName) 加载新模型；
3. 通过 isReady() 确认新实例就绪；
4. 整个过程其他后端与业务请求不受影响。

15.8 跨硬件性能差异大怎么办？

在硬件抽象层为不同后端预设优化配置（线程数/批大小），可按设备档位自动选取。

详细处理步骤：

1. 在 profile 中按设备档位配置线程数与批大小；
2. 通过 adapt() 将模型适配到该档位后端；
3. 参考第十四章性能基准选择最优后端组合。

15.9 错误码对照表

第十六章 术语与缩略语

为便于阅读，以下列出本说明书涉及的核心术语：

• 端侧AI：在设备本地而非云端执行的 AI 推理。
• 模型适配：使同一模型在多种硬件后端可用的转换与绑定过程。
• 边缘推理：在靠近数据源的边缘节点完成模型推理。
• 模型量化：降低模型精度以减小体积与加速推理的压缩技术。
• 硬件抽象：屏蔽 CPU/GPU/NPU 差异的统一执行接口。
• 降级策略：资源不足时切换到轻量模型的容错机制。
• 内存占用：推理过程中模型与中间张量的内存消耗。
• 确定性执行：固定随机性以保证结果可复现。
• 热替换：不重启服务更新模型实例。
• 后端(backend)：实际执行计算的硬件加速层（如 CPU/GPU）。
• Worker：端侧小模型路由层，处理高频简单任务。
• Solver：云端大模型路由层，处理复杂推理任务。
• HAL（硬件抽象层）：Hardware Abstraction Layer 的缩写。
• CANN：华为昇腾计算架构（Compute Architecture for Neural Networks）。
• MTCLAW：摩尔线程 GPU 加速推理服务框架。
• FNV-1a：一种高性能非加密哈希算法，用于缓存键生成。
• traceId：单次请求的全链路追踪标识。

第十七章 技术参数与性能指标

以下为系统实测关键参数（均来自真实运行环境验证）：

| 指标项 | 参数 / 实测值 |

| --- | --- |

| 模块状态 | checkModelStatus()/getMemoryUsage() 实测可执行 |

| 部署形态 | 本地端侧，支持离线运行 |

| 硬件后端 | CPU / GPU / NPU（抽象层自适应） |

| 降级 | 资源不足自动切换轻量模型 |

| 更新 | 支持模型热替换 |

| 可观测 | 实时状态与内存占用探测 |

17.1 支持的硬件后端清单

17.2 支持的协议与数据格式

17.3 接口与能力清单

17.4 完整基准数据（典型测试环境）

综合第十四章，关键基准如下：端侧 Worker（Ollama gemma3:4b）典型时延 ~70ms；摩尔线程 GPU（MTCLAW qwen2.5:3b）~90ms；华为昇腾 NPU（qwen3:4b）~120ms；云端 DeepSeek（complex）~500ms；整体平均时延（混合流量）~150ms，较全云端降低约 7 倍；缓存命中率约 70%；Worker 调用占比约 73%；目标可用性 99.99%。

第十八章 最新版本新增功能（V1.0 更新）

本章聚焦软件著作权登记最新版本（V1.0）在端侧 AI 模型跨硬件适配能力上的新增与强化模块。所述功能均已在最新源代码中实现，相关类名、函数名与文件路径均与《软件源代码》一一对应，可作为软件功能真实、可运行的直接证据。

18.1 昇腾 NPU 适配（ascend-npu）

功能背景： 在信创与算力自主可控趋势下，华为昇腾（Atlas）NPU 已成为众多制造与政企客户的首选国产 AI 加速硬件。然而昇腾推理环境具有"运行时多重、端口多样、启动偏慢"的特点：既可能存在 vLLM-Ascend 暴露的 OpenAI 兼容推理服务，也可能仅有 CANN/torch_npu 工具链而无在线服务。如何让本系统在不改写业务代码的前提下，自动识别并接入昇腾 NPU，并在其不可用时平滑降级，是本次 V1.0 强化适配能力的关键目标。

技术实现： 该能力由 server/digital-staff/ascend-npu.js 中的 AscendNPUAdapter 类承载。配置加载 _loadConfig() 遵循"环境变量 > config.features.ascend_npu > 默认值"三路优先级，支持 ASCEND_NPU_ENABLED、ASCEND_NPU_BASE_URL、ASCEND_NPU_MODEL、ASCEND_NPU_TIMEOUT_MS、ASCEND_NPU_API_KEY 等参数。环境探测 _detectEnvironment() 对本地回环端点先经 _probeEndpoint()（探测 /v1/models，5 秒超时）确认推理服务可达；不可达时回退 _probeCANN()，依次执行 npu-smi info、torch_npu 导入检测、msnpureport 与 CANN 版本文件读取，探测到工具链但无服务时标记为 degraded，二者皆缺则标记 offline。健康检查 healthCheck() 在 _healthCheckInterval（默认 30 秒）内返回缓存状态，并在恢复时调用注入的熔断器 circuitBreakerRef.tripToHalfOpen('ascend_npu')、失败时 recordFailure(...) 触发熔断，与 SmartLLMRouter 的降级链路第二顺位联动。核心调用 call(actionName, messages, options) 以 OpenAI 兼容 POST /chat/completions 发起推理，并维护 totalCalls/successCalls/degradedCalls/avgElapsed/tokensPerSecond 等统计（getStats() 导出）；setCircuitBreakerRef() 接收外部熔断器引用，getGlobalInstance() 提供全局单例。

使用效果： 启用 ASCEND_NPU_ENABLED=true 并配置 ASCEND_NPU_BASE_URL 后，系统启动即自动探测昇腾环境：若 vLLM-Ascend 在线则直接纳管并承接生产流量；若仅有 CANN 工具链则以降级模式待命，待服务就绪后健康检查自动恢复并触发半开探测。业务代码无需任何改动即可将 ECR 审核等复杂任务下沉至国产 NPU 推理，状态界面实时呈现健康度、tokens/s 与成功率；当 NPU 异常时自动熔断并降级至 Ollama/DeepSeek，保障链路不中断，真正落地"算力自主可控"。

图18-1 昇腾 NPU 端侧适配状态界面。

18.2 芯片级处理器（chipwise-handler）

功能背景： 在芯片设计与 EDA 协同场景中，企业需要将"识别设计规格、生成 RTL、修复 Verilog、比对版本、PPA 优化、生成验证文档"等长链路任务交给 AI 自动处理。传统做法依赖人工在多个工具间切换、粘贴代码，效率低且易出错。本系统 V1.0 新增的芯片级处理器（ChipWise）能力，面向 RISC-V 等处理器研发，提供从自然语言需求到 RTL 代码与验证报告的一体化智能服务，是跨硬件适配能力在"芯片研发"垂直场景的延伸与强化。

技术实现： 意图识别与槽位抽取由 server/digital-staff/chipwise-handler.js 实现。detectIntent(message) 依据 INTENT_CONFIGS 中六大意图（chip_identify / chip_create / chip_repair / chip_compare / chip_optimize / chip_generate）的关键词集合打分，分数 ≥20 判为 high 置信度，并列时返回 ambiguous 引导用户澄清；extractSlots(message, intent) 按 SLOT_RULES 的正则从自然语言抽取规格文本、指令集（RV32I/RV32IM/RV64I）、流水线级数、寄存器数、RTL 路径、优化方向（area/timing/power/balanced）等，并补齐 default_values。handleChipwiseRequest(sessionId, userMessage, options) 串联完整流程：缺失必填槽位时经 loadContext/saveContext 利用会话上下文回填；executeApi(intent, params) 向本地 localhost:3006 的 /api/chipwise/* 端点发起 HTTP 调用并带 3 次指数重试；pollTask(taskId) 轮询 /api/chipwise/task/{id}（最长 90 秒、间隔递增）等待异步结果；formatResult() 将各意图结果格式化为可读性文本。HTTP 路由由 server/routes/chipwise-routes.js 的 handleChipwiseRoutes() 统一分发：/api/chipwise/identify|create|repair|compare|optimize|generate 经 _handleAsync 立即返回 task_id（202）并 setImmediate 后台执行 chipwise-service 对应方法，再回填 completed/failed；/api/chipwise/task/{id}（GET）查询任务、/api/chipwise/health 与 /api/chipwise/edge/status 提供健康与边缘状态。前端 src/views/ChipWiseEngine.vue 以 capability-tabs 切换六类能力卡片，onMounted 调 fetchHealth() 拉取健康灯，runAsyncTask/pollTask 封装"提交即轮询"交互，结果以 result-grid 结构化呈现（如识别的完整度百分比、创建的编译状态、修复迭代轮次、PPA 优化建议）。

使用效果： 研发人员只需在对话或界面中以自然语言描述需求（如"设计一个 RV32I 五级流水线 RISC-V 处理器"），系统即可自动识别意图、抽取架构参数、生成可编译的 Verilog 模块，并对失败代码自动修复、对版本差异做语义比对、对 RTL 给出面积/时序/功耗优化建议，最终生成架构文档、测试用例与验证报告。长耗时任务转为异步轮询，界面实时展示进度与健康状态，使芯片前端研发从"多工具手工串联"升级为"一句话驱动"，显著降低重复劳动与人为出错率，也体现了本系统跨硬件适配能力在芯片研发垂直场景的拓展价值。

18.3 智能 LLM 路由（smart-llm-router / llm-router / llm-brain）

功能背景： 端侧 AI 服务要在"延迟、成本、可用性"间取得平衡，必须按请求语义与硬件健康度动态选择最合适的推理后端，并在任一后端故障时无缝降级。早期实现中，各业务模块各自 new LLMBrain()，导致降级链路不统一、可观测性差。V1.0 对此做了系统性强化：在 SmartLLMRouter（smart-llm-router.js）之上叠加意图级数字员工路由，并用 SmartLLMBridge（smart-llm-bridge.js）将散落的 LLMBrain 调用统一收敛到一条多级降级链，实现"一入口、全链路、可观测"。

技术实现： SmartLLMRouter.call() 是统一主入口，其流程为：① _classifyIntent(prompt) 基于 INTENT_KEYWORDS（覆盖库存、价格、供应商、成本、ECR、工艺优化等 18 类）做意图分类；② _tryDigitalStaff(intent, prompt) 将高频确定性意图直接路由到对应"小智"数字员工（如系统运维师、库存预警员、ECR 审核员、工艺优化数字员工），经 BossScheduler 或 CapabilityRuntime 执行，失败自动回退；③ 通用请求由 baseRouter.classifyTask()（llm-router.js 的 LLMRouter）判定 simple/complex；④ simple 任务查 ResponseCache；⑤ _buildChain(complexity) 按 config.chain 构建"MTCLAW → Ollama → DeepSeek"降级链路，跳过禁用、熔断（ModelHealthChecker.isAvailable）及 simple 下的 DeepSeek；⑥ 逐节点 _tryModel 调用，对 429/5xx 触发 _retryWithBackoff（指数退避，maxAttempts=3），全部失败记录 chainFallbacks。ModelHealthChecker 以 failureThreshold=5、recoveryTimeout=60000 维护 HEALTHY/DEGRADED/CIRCUIT_OPEN 状态，连续成功 3 次方可恢复。自动探测 _autoDetectServices() 启动即并行探测 MTCLAW/Ollama/DeepSeek，若无端侧模型且 DeepSeek 可用则自动切 remoteOnly 远程模式，并周期 setInterval 健康检查。LLMBrain（llm-brain.js）作为底层统一调用核心，提供 think/thinkJson/simulatedThinking 与 MTCLAW 加速检测（_detectMtclaw 三路：环境变量/端点 URL/config），为路由层兜底。新增的 SmartLLMBridge 提供与 LLMBrain 同签名的 chat/think/thinkJson，内部转调 SmartLLMRouter.call()，并保留 simulatedThinking 兜底；当 SmartLLMRouter 不可用时自动回退到 LLMBrain 全局单例——业务侧只需把 new LLMBrain() 改为 getSmartBrain()，即可让所有 LLM 调用汇入唯一多级降级链与 stats 指标出口。

使用效果： 该强化使系统的 LLM 调用获得统一的意图分发、端云多级降级、熔断自恢复与集中可观测能力。高频业务意图（如库存预警、ECR 审核、工艺优化）被精准路由到对应数字员工并直达业务能力，复杂语义请求在端侧/云端间按健康度择优；任一后端故障均自动降级并在恢复后自愈合，运维可从 getStats() 一处查看总调用、缓存命中率、各模型健康与最近降级轨迹。通过 getSmartBrain() 的统一收口，原本分散在各模块的调用点无需大改即可获得高可用与可观测性，显著降低"调用点各自为政、故障难定位"的运维负担。

#### 图18-3 边缘 AI 平台总览【界面图·待补真实截图】

• 截图来源：网页端 BossAgents
• 应展示：边缘 AI 平台总览
• 截图保存为 ../shots/sc7-2-platform.png 后告知我，自动替换为正式图注

图18-3 智能 LLM 路由选择与推理调用结果界面（平台视角）。

附录 A：基于最新代码补充的新增功能（2026年7月）

A.1 边侧路由会话一致性（MTClaw 透传）

在端侧 AI 模型跨硬件适配系统的统一 LLM 路由层（server/digital-staff/smart-llm-router.js）中，新增 sessionKey 端侧会话标识透传：经由 MTClaw 通道发起的推理请求在请求头注入 x-openclaw-session-key，使跨硬件（昇腾 NPU / 云端降级）的多次推理调用保持同一会话上下文，提升多轮交互在端云混合场景下的连贯性。该透传链路已随数字员工 MTClaw 集成一并接入运行时。

著作权人信息

以下著作权人信息与中国版权保护中心登记申请表一致，供审查核对。

• 著作权人： 北京左帮右臂人工智能技术有限公司
• 著作权人类型： 法人（有限责任公司·自然人独资）
• 证件类型： 营业执照
• 统一社会信用代码： 91110114MAKJ1UC63J
• 注册地址： 北京市昌平区东小口镇天通中苑二区21号楼1层103-2819（集群注册）
• 联系人： 方云超
• 联系电话： 18601921816
• 电子邮箱： [email protected]
• 邮政编码： 100010