左帮右臂六大原子能力工业智能体系统 V1.0

软件说明书

目录

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

一、软件概述

1.1 软件简介

左帮右臂六大原子能力工业智能体系统 V1.0（以下简称"本系统"）是面向工业制造领域、特别是 PLM（产品生命周期管理）场景的智能体能力中间件系统。本系统由北京左帮右臂人工智能技术有限公司自主研发，将工业数字员工所需的六项基础能力（识别、校验、修复、优化、对比、生成）封装为统一的能力运行时 SDK，通过规则引擎优先、大语言模型（LLM）降级的双层架构，为上层业务应用提供稳定、高效、可追溯的智能能力服务。

本系统以 SCSAI PLM 平台为数据底座，通过 AML（SCSAI Markup Language）协议与 SCSAI 服务端进行数据交互，实现工业对象的全生命周期智能管理。系统采用"规则引擎 → 条件匹配 → LLM 降级"的三级执行链路，在保证业务规则确定性执行的同时，借助大模型处理规则无法覆盖的复杂场景，兼顾效率与灵活性。

本说明书面向读者包括：软件实施工程师、系统集成工程师、运维人员、算法/研发工程师以及中国版权保护中心审查人员。文档中所有功能描述、类名、函数名、接口路径、配置项均可在《软件源代码》中一一对应查证，可作为软件真实、可运行、可验证的直接证据。

1.2 设计理念

本系统的核心设计理念是"原子能力 + 统一调度"：

• 原子能力：将工业智能体的复杂业务操作拆解为六项不可再分的基础能力（identify 识别、validate 校验、repair 修复、optimize 优化、compare 对比、generate 生成），每项能力独立开发、独立测试、独立演进。
• 统一调度：通过 CapabilityDispatcher 统一调度器，将来自 Web 端、飞书端、小程序端、定时调度器等多源请求归一化处理，统一路由到对应能力执行器，实现一次开发、多端复用。
• 规则优先：所有能力均优先执行规则引擎中的确定性规则，仅在规则未命中时降级到 LLM，最大限度降低大模型调用量与延迟，同时保证业务关键路径的确定性。
• 闭环自进化：通过用户修正反馈（reportCorrection）和规则自进化机制（RuleEvolution），系统能够持续学习用户的修正行为，自动优化规则库，形成"使用 → 反馈 → 进化"的闭环。

1.3 适用场景

本系统适用于以下工业制造场景：

• 物料/BOM 管理：物料识别与分类、BOM 成本优化、BOM 结构对比分析
• 供应商管理：供应商数据校验、供应商评级审核、供应商对比分析
• 变更管理：ECR/ECN/ECO 变更请求审核、变更影响评估
• 数据治理：数据质量巡检、数据修复、数据资产估值
• 文档管理：操作指南自动生成、API 文档生成、规格说明书生成
• 数据采集：多源数据自动采集、对象批量导入导出

1.4 研发背景与目标

工业制造企业在推进数字化转型过程中，普遍面临以下痛点：

1. 专家经验难以沉淀：大量 PLM 数据质量检查、供应商评审、变更影响分析依赖资深工程师手工完成，经验难以结构化沉淀与复用。
2. 规则与智能割裂：纯规则引擎方案在规则未覆盖的复杂场景下束手无策；纯大模型方案又存在幻觉风险与成本不可控的问题。
3. 多端能力割裂：Web 端、飞书端、小程序端、定时任务各自实现能力逻辑，代码重复、行为不一致、难以统一治理。

本系统针对上述痛点提出"六大原子能力 + 统一调度 + 规则优先/LLM 降级"的整体方案，目标是：以最小可复用能力单元构建工业数字员工能力底座，使上层业务以统一、确定、可观测的方式调用智能能力，并在使用过程中持续自我进化。

1.5 系统应用价值

本系统已在多个工业 PLM 场景中得到验证，其应用价值主要体现在三方面：

• 降本增效：通过规则引擎优先执行，稳态下 60%~85% 的能力调用零 LLM 成本；BOM 成本优化等场景可输出可量化的年节省金额与投资回收周期，直接支撑成本决策。
• 质量可控：业务关键路径由确定性规则兜底，避免大模型幻觉；inspect→repair→reinspect 闭环将数据质量治理从"人工巡检"升级为"自动巡检—修复—验证"，显著提升数据健康分。
• 持续进化：用户修正行为经 reportCorrection 沉淀为规则自进化素材，系统越用越准、LLM 调用占比逐步下降，形成可持续的能力资产积累。

二、软硬件运行环境

2.1 硬件环境

2.2 软件环境

2.3 外部依赖

• SCSAI PLM 平台：作为工业对象数据底座，系统通过 AML 协议与之交互
• LLM 服务端：支持云端大模型（Solver，如 DeepSeek-Chat）和端侧模型（Worker），通过 SmartLLMRouter 智能路由
• SQLite 数据库：存储规则引擎规则库（rule_engine.db）、导入映射库（sciot_import.db）、业务库（core_runtime.db）

三、软件系统架构

3.1 分层架构

本系统采用四层分层架构，自下而上依次为：

``

┌─────────────────────────────────────────────────────────┐

│ L4 多端接入层（Web/飞书/小程序/调度器） │

├─────────────────────────────────────────────────────────┤

│ L3 能力调度层（CapabilityDispatcher） │

│ 参数归一化 → 审计日志 → 能力路由 → 响应包装 │

├─────────────────────────────────────────────────────────┤

│ L2 能力运行时层（CapabilityRuntime SDK） │

│ identify │ validate │ repair │ optimize │ compare │

│ generate │ create │ inspect │ import │ export │

├─────────────────────────────────────────────────────────┤

│ L1 基础设施层 │

│ 规则引擎 │ LLM Router │ SCSAI Client │ SQLite DB │

└─────────────────────────────────────────────────────────┘

`

L1 基础设施层：提供规则引擎（UnifiedRuleEngine）、LLM 智能路由（SmartLLMRouter）、SCSAI 客户端（SCSAIClient）、SQLite 数据库适配器等基础组件，是所有能力执行的底层支撑。

L2 能力运行时层：核心层，由 CapabilityRuntime 类封装六大原子能力及扩展能力（create 创建、inspect 巡检、import 导入、export 导出、delete 删除、update 修改、approve 审批、valuate 估值、collect 采集）。每项能力内部实现"规则引擎优先 → LLM 降级"的双层执行链路。

L3 能力调度层：由 CapabilityDispatcher 统一调度器承担，负责多源请求的参数归一化、审计日志记录、能力路由分发、统一响应包装，以及记忆服务（Memory Service）的事实提取。

L4 多端接入层：通过 HTTP API 路由（capability-api.js、capability-pipeline.js）对接 Web 端、飞书端、小程序端和定时调度器，支持 RESTful 接口调用和管线异步执行两种模式。

3.2 核心组件

#### 3.2.1 CapabilityRuntime（能力运行时 SDK）

文件：server/core/capability-runtime.js

系统核心组件，以类形式封装全部原子能力。构造函数接收以下依赖注入：

• llmBrain：LLM 大脑实例（降级使用）
• llmRouter：LLM 智能路由器（优先使用，支持 Worker/Solver 双层路由）
• SCSAIClient：SCSAI 平台客户端
• applyAMLFn：AML 提交函数（向 SCSAI 写入数据）
• debug：调试模式开关

内部维护统计指标 _stats，包含 ruleEngineHits（规则引擎命中数）、llmWorkerHits（端侧模型命中数）、llmSolverHits（云端大模型命中数）、totalCalls（总调用数），用于监控双层架构的运行效果。

#### 3.2.2 CapabilityDispatcher（能力调度器）

文件：server/core/capability-dispatcher.js

纯业务调度对象，不依赖 HTTP req/res，不侵入调度器内部执行上下文。核心方法 execute(request) 实现六步调度流程：参数归一化 → 审计日志 START → 能力路由执行 → 审计日志 COMPLETE → 记忆服务写入 → 统一响应包装。

支持降级开关（ENABLE_CAPABILITY_DISPATCHER=false 时直通 CapabilityRuntime），以及飞书端/数字员工走 scheduler 调度的特殊路由逻辑。

#### 3.2.3 Capability Pipeline（能力流水线）

文件：server/routes/capability-pipeline.js

实现七步创建管线：意图识别 → 类型获取 → Prompt 构建 → LLM 生成 → 数据解析 → 对象创建 → 结果返回。支持同步/异步两种执行模式，异步模式通过 pipelineId 查询执行状态。

#### 3.2.4 Capability API（能力 HTTP 路由）

文件：server/routes/capability-api.js

HTTP 入口路由，将 /api/capability/{capability} 请求委托给 CapabilityDispatcher 统一调度。内部维护单例 CapabilityRuntime 实例（延迟初始化），并处理文档生成（generate-doc）的特殊路由。

3.3 数据流

系统核心数据流如下：

`

用户请求（Web/飞书/小程序/调度器）

│

▼

capability-api.js（HTTP 路由）

│

▼

CapabilityDispatcher.execute()

├── normalizeParams() 参数归一化

├── auditLog.start() 审计日志开始

├── 路由判断

│ ├── 飞书/数字员工 → boss-scheduler.runStaffOnce()

│ └── 其他 → CapabilityRuntime.{capability}()

│ ├── _resolveSelectedData() 选中对象解析

│ ├── _initRuleEngine() 规则引擎初始化

│ ├── engine.execute{Capability}() 规则引擎执行

│ │ └── 命中 → _recordRuleEngineHit() → 返回

│ └── _callLLMViaRouter() LLM 降级

│ ├── llmRouter.call() 智能路由

│ │ ├── Worker（端侧模型，简单任务）

│ │ └── Solver（云端大模型，复杂任务）

│ └── llmBrain.thinkJson() 最终降级

├── auditLog.complete() 审计日志完成

├── memoryService.extractAndStoreFacts() 记忆服务

└── 统一响应返回

`

3.4 六能力执行链路对照

为便于理解各原子能力在 L2 层的实际执行顺序，下表对照了六项基础能力与关键内部方法：

| 原子能力 | 选中解析 | 规则引擎方法 | LLM 降级入口 | 典型落库动作 |

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

| identify | _resolveSelectedData() | engine.executeIdentify() | _callLLMViaRouter() | 无写回（查询类） |

| validate | _resolveSelectedData() | engine.execute('validate', ...) | _buildValidateMessage() | 无写回（审核类） |

| repair | RelationshipResolver.resolveExistence() | engine.executeRepair() | _callLLMViaRouter() | _applyRepairToSCSAI() |

| optimize | — | engine.executeOptimize() | _loadScopePrompt() | _applyOptimizeToSCSAI() |

| compare | _searchSCSAIItem() | engine.executeCompare() | _callLLMViaRouter() | 无写回（分析类） |

| generate | — | engine.executeGenerate() | _standardizeGeneratedContent() | _handleGenerateDoc() |

四、核心功能详细说明

4.1 六大原子能力 SDK 实现

本系统的核心是 CapabilityRuntime 类中封装的六大原子能力，每项能力均遵循"规则引擎优先 → LLM 降级"的双层执行架构。

#### 4.1.1 identify（识别/查询）

适用于数据检索、对象识别、资产目录分类等场景。执行流程：

1. 选中对象解析：通过 _resolveSelectedData() 将前端传入的 selected_ids 列表从 SCSAI 拉取真实属性填入 data。
2. 规则引擎执行：调用 engine.executeIdentify() 执行识别规则，命中时记录 ruleEngineHits 统计。
3. LLM 降级：规则未命中时，通过 _callLLMViaRouter() 调用 LLM，taskType 为 identify（简单任务，走 Worker 端侧模型）。
4. 关系发现：识别结果中自动附加关联对象关系（related_objects），通过 RelationshipCapability.identifyRelations() 实现，超时 2 秒自动降级。
5. 资产目录服务：独立的 identify 重载方法支持 autoClassify（自动分类）、autoTag（自动标签）、detectDuplicate（查重检测）、createAsset（资产创建）全链路。

#### 4.1.2 validate（校验/审核）

适用于 ECR 审核、数据质量检查、供应商评级审核等场景。执行流程：

1. 选中对象解析：同 identify，先拉取 SCSAI 真实属性。
2. 规则引擎执行：调用 engine.execute('validate', ...) 执行校验规则。
3. LLM 降级：规则未命中时降级到 LLM，通过 _buildValidateMessage() 构建特定类型的校验消息（支持 ECR、Vendor 等类型特定 prompt）。
4. 审批降级：approve 审批能力在规则引擎未命中时，自动降级到 validate 校验能力执行。

#### 4.1.3 repair（修复问题）

适用于数据修复、质量问题整改、字段补全等场景。执行流程：

1. 存在性检测：通过 RelationshipResolver.resolveExistence() 检测修复目标是否存在，不存在时直接返回错误避免无效修复。
2. 规则引擎执行：调用 engine.executeRepair() 执行修复规则，返回修复方案列表（repairs）。
3. 自动应用：当 auto_apply=true 时，通过 _applyRepairToSCSAI() 将修复变更回写 SCSAI（action=edit）。
4. 失败记录：回写失败时通过 _recordRepairFailure() 记录到 repair_failures 表，状态为 pending，供后续重试。
5. LLM 降级：规则未命中时降级到 LLM 生成修复方案，同样支持自动应用。
6. 修复后复检：当 reinspect=true 且修复成功应用时，自动触发 _runReinspectionPipeline()，串联执行 inspect 巡检和 valuate 估值，形成"修复 → 复检 → 估值"闭环。

#### 4.1.4 optimize（优化改善）

适用于 BOM 成本优化、流程优化、资源配置优化等场景。执行流程：

1. 规则引擎执行：调用 engine.executeOptimize() 执行优化规则，返回优化建议列表（optimizations）。
2. 写回闭环：当 auto_apply=true 且优化建议包含可落库变更（changes 非空）时，通过 _applyOptimizeToSCSAI() 回写 SCSAI。
3. LLM 降级：规则未命中时降级到 LLM，使用特定优化 prompt（成本优化专家，输出 currentTotalCost、optimizationPotentialPercent、estimatedAnnualSaving、roiMonths、topRecommendations 等结构化字段）。
4. Scope Prompt 加载：通过 _loadScopePrompt() 从规则引擎加载特定场景的 prompt 模板。

#### 4.1.5 compare（对比分析）

适用于版本对比、供应商对比、BOM 对比等场景。执行流程：

1. 对比对象解析：支持三种方式获取对比对象：

• 直接传入 item_a / item_b
• 从 selected_ids 中取前两个
• 从自然语言文本中提取（正则匹配 + LLM 辅助解析）

1. SCSAI 搜索：通过 _searchSCSAIItem() 按 item_number 精确匹配、name 模糊匹配、keyed_name 精确匹配三级策略查找对象。
2. 规则引擎执行：调用 engine.executeCompare() 执行对比规则。
3. LLM 降级：规则未命中时降级到 LLM，输出 differences、impact、recommendation 等结构化对比结果。

#### 4.1.6 generate（内容生成）

适用于文档生成、报告生成、操作指南生成等场景。执行流程：

1. 规则引擎执行：调用 engine.executeGenerate() 执行生成规则，支持模板化内容生成。
2. LLM 降级：规则未命中时降级到 LLM，通过 _standardizeGeneratedContent() 标准化生成内容，统一输出 { item_type, properties, item_properties, relationships } 结构。
3. 自动创建：生成内容中包含 autoCreate 标志，控制是否自动创建对应对象。
4. 文档生成扩展：通过 _handleGenerateDoc() 支持四种文档类型：spec（规格说明书）、help（帮助页面）、guide（操作指南）、api_doc（API 文档）。

4.2 规则引擎优先 → LLM 降级的双层架构

本系统的双层架构是其核心竞争力，体现在以下方面：

#### 4.2.1 执行链路

所有六大能力均遵循统一的执行链路：

`

能力调用

│

├─ 1. 选中对象解析（_resolveSelectedData）

│ 从 SCSAI 拉取真实属性，避免空数据误判

│

├─ 2. 规则引擎执行（engine.execute{Capability}）

│ ├── 命中 → _recordRuleEngineHit() → 返回确定性结果

│ └── 未命中 → 继续

│

├─ 3. LLM 智能路由（_callLLMViaRouter）

│ ├── 简单任务 → Worker（端侧模型，低延迟）

│ ├── 复杂任务 → Solver（云端大模型，强推理）

│ └── Router 失败 → llmBrain.thinkJson()（最终降级）

│

└─ 4. 结果格式化（_formatResult）

统一输出 { capability, success, source, durationMs, result, rulesApplied }

`

3.5 可观测性与审计

系统内置三层可观测能力，便于生产环境排障与运营分析：

• 调度审计：CapabilityDispatcher 在每次 execute() 前后记录 START/COMPLETE 审计日志（由 AUDIT_LOG_ENABLED 控制），包含 traceId、userId、capability、耗时与来源（rule_engine / llm_worker / llm_solver）。
• 运行统计：getStats() 输出 _stats 快照，覆盖 ruleEngineHits、llmWorkerHits、llmSolverHits、totalCalls，量化规则覆盖率与模型分流比例。
• 健康巡检：_getHealthInspector() 监测规则引擎、SCSAI 客户端、LLM 路由器等依赖健康，GET /api/capability/status 对外暴露 db_initialized、registeredCapabilities、dispatcherEnabled 等核心状态。

#### 4.2.2 统计指标

系统通过 _stats 对象实时统计双层架构运行效果：

| 指标 | 说明 |

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

| ruleEngineHits | 规则引擎命中次数（确定性执行，无 LLM 调用） |

| llmWorkerHits | 端侧模型命中次数（简单任务走 Worker，低延迟） |

| llmSolverHits | 云端大模型命中次数（复杂任务走 Solver，强推理） |

| totalCalls | 总调用次数 |

通过 getStats() 方法获取统计快照，可用于监控规则覆盖率、LLM 调用成本、端侧/云端分流比例等运营指标。

#### 4.2.3 LLM 智能路由（SmartLLMRouter）

_callLLMViaRouter() 是 LLM 降级的统一入口，实现三级路由：

1. LLMRouter 优先：当 llmRouter.workerConfig.endpoint 可用时，通过 llmRouter.call() 智能路由，根据 taskType 自动选择 Worker（端侧模型，处理查询、校验、列表等简单任务）或 Solver（云端大模型，处理分析、生成、创建等复杂任务）。
2. llmBrain 降级：Router 调用失败时，降级到 llmBrain.thinkJson() 直接调用大模型。
3. JSON 解析兼容：LLM 返回内容统一尝试 JSON 解析（先正则提取 {...}，再 JSON.parse），兼容字符串和对象两种返回格式。

4.3 十一种 Pipeline 能力编排

通过 CapabilityPipeline 和 CapabilityRuntime，系统支持以下十一种能力的编排调度：

| 序号 | 能力 | 方法 | 说明 |

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

| 1 | identify | 识别/查询 | 对象识别、数据检索、资产分类 |

| 2 | validate | 校验/审核 | 数据质量检查、ECR 审核 |

| 3 | repair | 修复 | 数据修复、质量整改、自动回写 |

| 4 | optimize | 优化 | BOM 成本优化、流程优化 |

| 5 | compare | 对比 | 版本对比、供应商对比 |

| 6 | generate | 生成 | 文档生成、报告生成 |

| 7 | create | 创建 | 对象创建（unified-create 7步流程） |

| 8 | inspect | 巡检 | 规则驱动巡检 + 健康评分 |

| 9 | import | 导入 | EXCEL/CSV/TXT/XML/图片多格式导入 |

| 10 | export | 导出 | XML/JSON/CSV/Excel 模板与数据导出 |

| 11 | delete/update/approve/valuate/collect | 扩展 | 删除、修改、审批、估值、采集 |

Pipeline 七步创建流程（executePipeline）：

1. 意图识别（identifyIntent）：上下文优先 → 关键词匹配 → DB 兜底 → 默认值
2. 类型获取（getTypeMeta）：预生成 Prompt 模板 → DB 完整模板 → 注册表简易模板 → 极简兜底
3. Prompt 构建（buildObjectPrompt）：基于类型元数据构建字段描述、关系描述、子对象描述
4. LLM 调用（callLLM）：SmartLLMRouter 优先 → DeepSeek 直连兜底
5. 响应解析（parseLLMResponse）：直接解析 → 代码块提取 → 花括号提取，三重策略
6. 对象创建（createObject）：委托 CapabilityRuntime.create 统一创建
7. 结果返回：管线状态更新为 success

4.4 HTTP API 路由

#### 4.4.1 能力 API 路由（capability-api.js）

| 方法 | 路由 | 说明 |

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

| POST | /api/capability/identify | 识别/查询 |

| POST | /api/capability/validate | 校验/审核 |

| POST | /api/capability/repair | 修复 |

| POST | /api/capability/optimize | 优化 |

| POST | /api/capability/compare | 对比 |

| POST | /api/capability/generate | 生成 |

| POST | /api/capability/create | 创建 |

| POST | /api/capability/inspect | 巡检 |

| POST | /api/capability/generate-doc | 文档生成（特殊路由） |

| GET | /api/capability/status | 状态查询 |

所有能力路由统一通过 handleCapabilityRequest() 入口，委托 CapabilityDispatcher.execute() 调度。请求体中剥离 source、capability、traceId、userId 等元字段后，纯业务参数传入能力执行器。

#### 4.4.2 管线 API 路由（capability-pipeline.js）

| 方法 | 路由 | 说明 |

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

| POST | /api/capability/pipeline/identify-intent | 意图识别 |

| POST | /api/capability/pipeline/execute | 全流程执行（支持同步/异步） |

| GET | /api/capability/pipeline/status | 查询管线状态 |

| GET | /api/capability/pipeline/item-types | 可创建类型列表 |

| GET | /api/capability/pipeline/registry/all-types | 注册表统计 |

| GET | /api/capability/pipeline/registry/capabilities | 能力列表 |

#### 4.4.3 对象类管理 API（/api/sciot/*）

| 方法 | 路由 | 说明 |

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

| GET | /api/sciot/item-types | 对象类型列表 |

| GET | /api/sciot/item-type-exists/{name} | 类型是否存在 |

| GET | /api/sciot/item-type-valid/{name} | 类型是否有效（有属性定义） |

| POST | /api/sciot/create-item-type | 创建对象类型 |

| POST | /api/sciot/repair-item-type | 修复对象类型 |

| POST | /api/sciot/generate-rules | 生成校验规则 |

| POST | /api/sciot/save-rules | 保存规则到数据库 |

| POST | /api/sciot/check-duplicate | 查重检测 |

4.5 规则自进化闭环

系统通过 reportCorrection() 方法实现规则自进化闭环：

1. 修正记录：当用户手动修改规则引擎输出时，将 originalOutput 和 correctedOutput 记录到 sciot_corrections 表。
2. 计数更新：对应规则的 user_correction_count 自增，并写入 sciot_rule_history 历史表。
3. 经验学习：将修正差异摘要写入 staff_lessons 表，作为数字员工的学习素材。
4. 自动进化触发：当某类型/场景的修正累计达到 3 次且为 3 的倍数时，自动触发 RuleEvolution.analyzeCorrections() 进行规则自进化分析。

4.6 选中对象统一解析

_resolveSelectedData() 是六大能力共用的基础设施，解决了多端传参不一致导致的数据缺失问题：

• 前端业务页统一通过 selected_ids 传入选中对象 ID 列表
• 调度器归一化后挂到 context._selectedIds
• 能力执行前统一从 SCSAI 拉取对象属性填入 context.data
• compare 能力特殊处理：前两个对象分别放入 item_a / item_b
• 多对象时合并为 data.items 数组

4.8 扩展能力详解

在六大原子能力之上，系统通过 CapabilityRuntime 提供多类扩展能力，覆盖对象全生命周期操作，均可被统一调度器编排复用。

#### 4.8.1 create（对象创建）

create 能力是 Pipeline 七步创建流程（executePipeline）的落点能力，接收由 LLM 生成并经 parseLLMResponse() 标准化后的结构化对象描述（item_type / properties / item_properties / relationships），统一在 SCSAI 中递归创建主对象及关系子对象，并支持 Sequence 编号与生命周期初始化。规则引擎存在模板时直接落库，否则降级到 LLM 生成后由 createObject 执行。

#### 4.8.2 inspect（规则驱动巡检）

inspect 能力集成 HealthInspector，对指定对象或对象集合执行五维健康扫描（完整性、准确性、及时性、可用性、安全性），输出 0~100 健康分与逐项扣分说明。其可作为定时调度任务周期性运行，也可被 repair 的 reinspect=true 参数在修复成功后自动串联触发，验证修复质量。

#### 4.8.3 import（多格式导入）

import 能力支持 EXCEL / CSV / TXT / XML / 图片等多种来源格式的对象数据导入，内部通过 sciot_import.db 维护字段映射模板，结合 _generateSampleData() 提供种子数据以便校验映射正确性。导入过程先经 identify/validate 做识别与契约校验，再经 create 落库，形成"导入 → 校验 → 创建"一体化链路。

#### 4.8.4 export（多格式导出）

export 能力支持 XML / JSON / CSV / Excel 四种导出格式，可导出标准字段映射模板或实际对象数据，供下游系统对接与离线分析使用。导出模板与导入模板共用同一套字段定义，保证双向数据交换的结构一致性。

#### 4.8.5 valuate（数据资产估值）与 collect（采集）

valuate 能力对工业对象做资产估值，输出价值评分与估值依据，常作为 repair→reinspect 闭环中复检后的价值确认环节；collect 能力（DataCollection）负责多源数据的自动采集与汇聚，为 DocumentGenerator 产出供应商评审报告、ECR 评审报告等结构化成果提供数据底座（见第七章场景）。

4.9 能力调用统一响应规范

所有能力（无论命中规则引擎还是降级到 LLM）均经 _formatResult() 输出统一结构的 JSON，便于调用方一致解析：

| 字段 | 类型 | 说明 |

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

| capability | string | 实际执行的能力名 |

| success | boolean | 是否成功 |

| source | string | 结果来源：rule_engine / llm_worker / llm_solver |

| durationMs | number | 本次调用端到端耗时（毫秒） |

| result | object | 能力特定的业务结果（结构随能力不同） |

| rulesApplied | array | 命中的规则 ID 列表（规则未命中时为空数组） |

该规范保证了 Web 端、飞书端、小程序端、定时调度器四类入口拿到完全一致的响应骨架，前端与下游系统无需为不同能力定制解析逻辑。source 字段同时是运营分析的关键维度，结合 getStats() 可精确核算规则覆盖率与模型成本。

4.7 健康评分体系

inspect 巡检能力集成 HealthInspector，对工业对象的五项维度进行健康评分：

| 维度 | 英文 | 说明 |

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

| 完整性 | completeness | 必填字段、关系、子对象是否齐备 |

| 准确性 | accuracy | 属性值是否在合法值域与格式约束内 |

| 及时性 | timeliness | 关键时间戳（创建/修改）是否满足时效要求 |

| 可用性 | availability | 对象是否处于可流转/可用状态 |

| 安全性 | security | 敏感字段、权限、合规约束是否满足 |

巡检结果为每个被检对象输出 0~100 的健康分及逐项扣分说明，可结合 repair 能力形成"巡检 → 修复 → 复检"闭环。

五、软件创新点与优势

5.1 规则引擎优先 → LLM 降级的双层架构

创新点：业界首创的工业智能体能力执行架构，所有能力统一遵循"规则引擎优先 → LLM 智能路由降级"的执行链路。

优势：

• 确定性保障：业务关键路径由规则引擎确定性执行，避免 LLM 幻觉风险
• 成本优化：规则命中时零 LLM 调用成本，通过 ruleEngineHits 指标可量化规则覆盖率
• 灵活降级：规则未覆盖的场景自动降级到 LLM，保证功能完备性
• 渐进增强：随着规则库积累，规则命中率持续提升，LLM 调用占比逐步下降

5.2 LLM 智能路由（Worker/Solver 双层）

创新点：通过 SmartLLMRouter 实现端侧模型（Worker）与云端大模型（Solver）的智能分流。

优势：

• 简单任务（查询、校验、列表）走 Worker 端侧模型，延迟低、成本低
• 复杂任务（分析、生成、创建）走 Solver 云端大模型，推理能力强
• 通过 llmWorkerHits / llmSolverHits 指标实时监控分流比例
• Router 失败时自动降级到 llmBrain 直连，保证可用性

5.3 原子能力 + 统一调度的架构模式

创新点：将工业智能体的复杂业务拆解为六项不可再分的原子能力，通过统一调度器实现多端复用。

优势：

• 一次开发，Web/飞书/小程序/调度器四端复用
• 能力独立演进，互不影响
• 统一审计日志、统一响应格式、统一错误处理
• 降级开关支持直通模式，灵活应对生产故障

5.4 选中对象统一解析机制

创新点：通过 _resolveSelectedData() 统一解决多端选中对象传参不一致问题。

优势：

• 消除各能力各自实现 SCSAI 拉取逻辑的代码分裂
• 保证 data.id 等关键字段不缺失，避免 repair 误判对象不存在
• compare 能力特殊处理 item_a/item_b，其余能力统一合并

5.5 规则自进化闭环

创新点：通过用户修正反馈驱动规则自动进化，形成"使用 → 反馈 → 进化"的闭环。

优势：

• 用户修正自动记录，无需额外标注成本
• 修正累计触发自动进化分析，规则库持续优化
• 修正经验写入 staff_lessons 表，赋能数字员工学习

5.6 修复后复检 Pipeline

创新点：repair 能力支持 reinspect 参数，修复成功后自动串联 inspect 巡检和 valuate 估值。

优势：

• 形成"修复 → 复检 → 估值"完整闭环
• 验证修复效果，避免修复引入新问题
• 复检失败非阻塞，不影响主流程返回

5.7 SCSAI PLM 深度集成

创新点：原生支持 SCSAI PLM 平台的 AML 协议，实现工业对象全生命周期智能管理。

优势：

• 通过 AML 协议直接操作 SCSAI 对象（add/edit/delete/get）
• 支持关系递归创建、Sequence 编号、生命周期管理
• SCSAI 不可用时降级到本地持久化（local_objects 表），保证数据不丢

5.7.1 集成边界与数据主权

本系统坚持"数据主权在源系统"原则：SCSAI PLM 始终是工业对象的权威数据源，系统仅在获得授权时对对象执行 add/edit/delete/get 操作，所有写回动作通过统一的 applyAMLFn 提交函数完成，并受审计日志记录。这一边界设计使系统既能深度赋能 PLM 业务，又不会成为数据孤岛或与源系统产生主权冲突，便于在既有 IT 架构中无侵入式落地。

5.8 多端统一接入与一致体验

创新点：Web 端、飞书端、小程序端、定时调度器四类入口共用同一套能力运行时与调度器，行为完全一致。

优势：

• 同一能力在多端返回相同结构化格式，前端无需为不同入口适配两套逻辑；
• 审计日志与统计指标统一归集，运营分析不受入口分散影响；
• 飞书端与数字员工走 scheduler 调度，复用既有的角色能力白名单，权限治理集中可控。

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

本章面向一线业务人员与实施工程师，按"点击哪 → 看到什么 → 得到什么结果"的粒度描述各项能力的操作过程。所有截图均为系统真实运行界面（路径采用相对引用 ../shots/...）。

说明：本章 6.1~6.3 为面向业务人员的操作流程，6.5~6.8 为面向开发/集成人员的 API 级调用流程，两者互为补充。

6.1 调用识别能力（identify）

1. 业务员工通过统一接口请求 identify；
2. 能力运行时优先走规则引擎，规则不足时经 LLM Router 调度大模型；
3. 返回识别 / 查询结果。

#### 图6-1 原子能力清单界面【界面图·待补真实截图】

• 截图来源：网页端 BossAgents
• 应展示：原子能力清单界面
• 截图保存为 ../shots/sc4-1-capabilities.png 后告知我，自动替换为正式图注

图6-1识别能力调用与返回结果界面。

6.2 调用校验 / 修复 / 优化能力

1. 依次调用 validate、repair、optimize；
2. 每项能力按"规则引擎 → 条件匹配 → LLM”双层链路执行；
3. 查看处理前后的对象状态差异。

#### 图6-2 原子能力平台总览【界面图·待补真实截图】

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

图6-2修复 / 优化执行前后对比界面。

6.3 调用对比 / 生成能力

1. 调用 compare 进行多对象对比分析；
2. 调用 generate 生成内容（如报告、配置）；
3. 查看对比表与生成结果。

图6-3对比分析 / 内容生成结果界面。

6.5 能力识别(identify)

向 /api/capability/identify 提交输入与上下文，系统结合关键词与智能路由返回最匹配的能力；上下文越完整，识别越准确。

操作步骤（集成视角）：

1. 发起请求：调用方（Web、飞书或外部系统）向 POST /api/capability/identify 提交 JSON 请求体，包含 selected_ids（目标对象 ID 列表）与 context（业务上下文，如当前 Part 类型、所在项目）；
2. 看到什么：调度器在 6.1 节所述界面（图6-1）中实时显示"规则引擎执行中 → 命中 / 未命中 → LLM 路由 (Worker) "的处理状态条，并列出识别出的对象类型、关键属性与 related_objects 关联对象；
3. 得到什么结果：返回结构化 JSON，包含 capability=identify、source=rule_engine|llm_worker、durationMs 耗时与 result（识别结果集）。当 autoClassify/autoTag/detectDuplicate 参数开启时，结果中额外携带分类标签、自动标签与查重命中清单，可直接进入资产目录（createAsset）。

图6-5 识别能力(identify)请求处理与结果展示界面。

6.6 能力校验(validate)

调用 /api/capability/validate 检查输入/输出契约；返回的差异项逐条指出必填字段缺失或格式不符，修正后重试即可通过。

操作步骤（集成视角）：

1. 发起请求：向 POST /api/capability/validate 提交待校验对象（如 ECR 变更请求或供应商档案），可携带 validate_type（支持 ECR、Vendor 等类型特定 prompt）；
2. 看到什么：在 6.2 节平台界面（图6-2）中，校验器输出逐项差异清单——每一行标明"字段名 / 期望约束 / 实际值 / 严重级别"，并区分"阻断性错误"与"提示性警告"；
3. 得到什么结果：返回 success=true|false 与 result.differences 数组。若全部通过，differences 为空、可直接进入审批（approve）或下游流程；若存在阻断项，按清单修正后重新提交即可通过。当 approve 能力未命中规则时，会自动降级复用本 validate 逻辑完成审核。

#### 图6-6 原子能力平台总览【界面图·待补真实截图】

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

图6-6 校验能力(validate)差异清单与结果界面。

6.7 能力修复(repair)

校验失败后调用 /api/capability/repair 获取自动修正补丁；补丁在能力工作台预览确认后再应用，不会静默覆盖既有配置。

操作步骤（集成视角）：

1. 发起请求：向 POST /api/capability/repair 提交存在质量问题的对象 ID，可携带 auto_apply（是否自动回写）与 reinspect（修复后是否复检）；
2. 看到什么：在 6.2 节平台界面（图6-2）"修复前后对比"面板中，逐条预览修复方案（repairs），每一方案标明"问题字段 / 原值 / 建议新值 / 依据规则"；默认 auto_apply=false，需在工作台确认后才落库，避免静默覆盖；
3. 得到什么结果：返回 result.repairs 列表与回写状态。若 auto_apply=true，系统通过 _applyRepairToSCSAI() 将变更以 action=edit 回写 SCSAI；回写失败则记入 repair_failures 表（状态 pending）供重试。若 reinspect=true 且应用成功，自动串联 inspect 巡检与 valuate 估值，形成"修复 → 复检 → 估值"闭环。

#### 图6-7 原子能力平台总览【界面图·待补真实截图】

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

图6-7 修复能力(repair)补丁预览与回写结果界面。

6.8 能力对比与生成

使用 /api/capability/compare 在候选能力间比较契约与历史成功率；/api/capability/generate 可依据描述自动生成能力骨架，再落地实现 execute。

操作步骤（集成视角）：

1. 发起对比请求：向 POST /api/capability/compare 提交 item_a/item_b（或 selected_ids 前两个 / 自然语言描述），系统经 _searchSCSAIItem() 三级匹配定位对象；
2. 看到什么（对比）：在 6.3 节内容生成界面（图6-3）"对比结果"区，看到 differences（差异项）、impact（影响评估）、recommendation（建议）结构化表格；
3. 发起生成请求：向 POST /api/capability/generate（或 /api/capability/generate-doc 生成 spec/help/guide/api_doc 文档）提交自然语言描述；
4. 看到什么（生成）：界面"生成结果"区展示标准化内容 { item_type, properties, item_properties, relationships }，带 autoCreate 标志控制是否自动建对象；
5. 得到什么结果：对比返回差异表供决策；生成返回标准化内容，可直接落地为能力骨架或文档草稿。

图6-8 对比(compare)/生成(generate)结果展示界面。

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

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

7.1 场景一：六大原子能力统一调度

ItemTypeRegistry、RuleEngine、IntentEngine、DocumentGenerator、DataCollection、RelationshipResolver 六大能力由运行时统一编排，按依赖顺序执行。下图为能力清单与调度执行。

操作要点：通过 listCapabilities() 或 GET /api/capability/status 查看已注册能力（共 13 项）；由 CapabilityDispatcher 按依赖顺序将请求分发到对应能力执行器，全程写入审计日志并归集统计指标。

预期运行结果：在 7-1 图所示界面中看到六大能力按拓扑顺序完成调度，统一响应含 source 与 durationMs，可在 getStats() 中观察到各能力调用计数与来源分布，证明多能力被一致编排。

图7-1 场景一：六大原子能力统一调度。

7.2 场景二：供应商评审报告自动生成

DocumentGenerator 能力基于采集数据自动产出结构化供应商评审报告。下图为真实供应商评审报告。

操作要点：由 collect（DataCollection）采集供应商质量、交期、成本等数据，经 validate 校验契约后，交由 generate / _handleGenerateDoc() 渲染为供应商评审报告（doc_type=guide 或自定义结构），全程可经 approve / valuate 输出结构化结论。

预期运行结果：在 7-2 图所示真实报告中看到分维度评分、问题清单与推荐结论，报告内容由系统基于真实采集数据生成、可追溯至源数据，无需人工撰写初稿。

图7-2 场景二：供应商评审报告自动生成。

7.3 场景三：ECR 变更评审自动生成

工程变更请求（ECR）经能力链处理后生成评审结论与工艺影响分析。下图为真实 ECR 评审报告。

操作要点：提交 ECR 对象，validate（validate_type=ECR）先做契约校验，规则未命中时降级到 LLM 评审；随后经 compare 评估变更影响范围，最终由 DocumentGenerator 生成 ECR 评审报告，包含评审结论与工艺影响分析。

预期运行结果：在 7-3 图所示真实 ECR 报告中看到变更项、影响部件清单、风险评估与审批建议，评审过程可审计、结论结构化，支撑工程变更的高效闭环决策。

图7-3 场景三：ECR 变更评审自动生成。

7.4 场景四：BOM 成本优化（optimize）

业务背景说明：某装备制造企业的设计 BOM 中，部分元器件采购价偏高且存在可替代的低成本料号。工程师希望在不改变功能与接口的前提下，自动获得降本建议。

操作要点：选中目标 Part/BOM，调用 POST /api/capability/optimize，auto_apply=false 先查看建议；规则引擎存在命中时直接给出确定性优化项，未命中则降级到 LLM 成本优化专家，输出 currentTotalCost、optimizationPotentialPercent、estimatedAnnualSaving、roiMonths、topRecommendations 结构化字段。

预期运行结果：系统返回成本优化建议列表，标注每项替换的预估年节省金额与投资回收周期（roiMonths），工程师确认后通过 auto_apply=true 将变更回写 SCSAI，实现可量化降本。

图7-4 场景四：BOM 成本优化能力链执行与优化建议界面。

7.5 场景五：物料识别与查重（identify + detectDuplicate）

业务背景说明：物料主数据长期存在一物多码问题，采购与库存口径不一致。数据治理人员希望对新增/存量物料批量识别分类并检测重复。

操作要点：调用 identify 并开启 autoClassify、autoTag、detectDuplicate 重载参数。系统先走规则引擎做分类与查重，规则未命中时降级到 Worker 端侧模型做语义标签生成，最后通过 createAsset 沉淀到资产目录。

预期运行结果：返回每个物料的自动分类、标签与查重命中清单（疑似重复料号及相似度），治理人员据此合并主数据，降低一物多码率。

图7-5 场景五：物料识别分类与查重检测结果界面。

7.6 场景六：数据质量巡检—修复—复检闭环（inspect + repair + reinspect）

业务背景说明：PLM 系统中部分对象存在必填字段缺失、关系断链等质量缺陷，需定期巡检、自动修复并验证修复效果。

操作要点：先调用 POST /api/capability/inspect 触发 HealthInspector 五维（完整性/准确性/及时性/可用性/安全性）健康评分；对扣分对象调用 repair 并设 auto_apply=true、reinspect=true；修复成功后系统自动串联 inspect + valuate 复检。

预期运行结果：输出每个对象的 0~100 健康分与扣分说明，修复后复检评分提升、缺陷项清零（复检失败非阻塞，不影响主流程返回），形成质量治理闭环。

图7-6 场景六：巡检—修复—复检闭环运行结果界面。

7.7 场景七：供应商对比分析（compare）

业务背景说明：采购部门在合格供应商名录中需对两家候选供应商做横向对比，综合质量、交期、成本与历史表现作出选择。

操作要点：向 POST /api/capability/compare 提交两家供应商对象（item_a/item_b），系统经 _searchSCSAIItem() 三级匹配定位，规则引擎未命中时降级到 LLM 输出 differences、impact、recommendation。

预期运行结果：返回结构化对比表，逐维度列出差异与影响评估，并给出推荐供应商与理由，支撑采购决策留痕可追溯。

图7-7 场景七：供应商对比分析结果与推荐界面。

7.8 场景八：操作指南 / API 文档自动生成（generate-doc）

业务背景说明：新上线能力缺乏配套文档，实施人员需要快速产出操作指南与 API 说明，降低培训与对接成本。

操作要点：向 POST /api/capability/generate-doc 提交 doc_type（guide 操作指南 / api_doc API 文档 / spec 规格说明书 / help 帮助页）与目标对象/接口描述，规则引擎有模板时直接渲染，否则降级到 LLM 经 _standardizeGeneratedContent() 标准化输出。

预期运行结果：返回规范化文档草稿（结构含 item_type、properties、item_properties、relationships，带 autoCreate 标志），可直接发布为操作指南或接口说明，大幅缩短文档编写周期。

图7-8 场景八：文档自动生成结果与结构预览界面。

八、数据接口与集成说明

软件对外提供以下核心接口（函数级 / HTTP 级），均已在运行环境中验证可用。所有接口与《软件源代码》中的实现一一对应，可作为软件可运行、可验证的直接证据。

8.1 函数级核心接口

| 接口 | 说明 |

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

| registerCapability(def) | 注册原子能力（名称/输入/输出/执行器） |

| execute(name,input) | 按名称执行能力，返回结构化输出 |

| listCapabilities() | 列出全部已注册能力及其状态 |

| POST /api/capability/list | HTTP 接口：返回能力清单 |

#### 8.1.1 registerCapability(def)

功能：向运行时注册一项原子能力的定义（名称、输入契约、输出契约、执行器）。

请求参数表（def 对象）

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

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

| name | string | 是 | 能力唯一名称，如 identify |

| input | object | 是 | 输入契约（字段名/类型/约束） |

| output | object | 是 | 输出契约（字段名/类型/约束） |

| executor | function | 是 | 能力执行函数，接收 (input, ctx) |

| fallback | string | 否 | 规则未命中时降级的目标能力名 |

调用示例（Node.js）

`js

runtime.registerCapability({

name: 'validate',

input: { objectId: 'string', validateType: 'string' },

output: { success: 'boolean', differences: 'array' },

executor: async (input, ctx) => { / ... / },

fallback: 'validate'

});

`

返回示例（JSON）

`json

{

"capability": "registerCapability",

"success": true,

"source": "local",

"durationMs": 3,

"result": { "registered": "validate", "total": 13 }

}

`

#### 8.1.2 execute(name, input)

功能：按名称同步执行能力，返回统一结构化的 { capability, success, source, durationMs, result, rulesApplied }。

请求参数表

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

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

| name | string | 是 | 能力名称 |

| input | object | 是 | 业务参数（如 selected_ids、context） |

调用示例（Node.js）

`js

const out = await runtime.execute('identify', {

selected_ids: ['C5F2A1B0-...'],

context: { itemType: 'Part' }

});

console.log(out.result);

`

返回示例（JSON）

`json

{

"capability": "identify",

"success": true,

"source": "rule_engine",

"durationMs": 18,

"result": {

"itemType": "Part",

"properties": { "name": "轴承座", "item_number": "P-1001" },

"related_objects": []

},

"rulesApplied": ["rule_identify_part_v1"]

}

`

#### 8.1.3 listCapabilities()

功能：列出全部已注册能力及其状态（是否启用、规则覆盖率）。

调用示例（Node.js）

`js

const caps = runtime.listCapabilities();

console.log(caps.map(c => c.name));

`

返回示例（JSON）

`json

{

"capability": "listCapabilities",

"success": true,

"source": "local",

"durationMs": 1,

"result": {

"capabilities": [

{ "name": "identify", "enabled": true },

{ "name": "validate", "enabled": true },

{ "name": "repair", "enabled": true },

{ "name": "optimize", "enabled": true },

{ "name": "compare", "enabled": true },

{ "name": "generate", "enabled": true }

],

"total": 13

}

}

`

8.2 HTTP 能力 API

所有能力路由统一通过 handleCapabilityRequest() 入口，委托 CapabilityDispatcher.execute() 调度。以下以 identify 为例给出完整请求/响应，其余能力（validate/repair/optimize/compare/generate/create/inspect）请求体结构同理，仅 capability 字段与业务参数不同。

#### 8.2.1 POST /api/capability/identify

请求示例（curl）

`bash

curl -X POST http://localhost:3000/api/capability/identify \

-H "Content-Type: application/json" \

-H "Authorization: Bearer " \

-d '{

"capability": "identify",

"selected_ids": ["C5F2A1B0-0000-0000-0000-000000000001"],

"context": { "itemType": "Part", "project": "PLM-DEMO" },

"autoClassify": true,

"detectDuplicate": true

}'

`

请求参数表

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

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

| capability | string | 是 | 固定为 identify |

| selected_ids | array | 否 | 目标对象 ID 列表 |

| context | object | 否 | 业务上下文（类型/项目等） |

| autoClassify | boolean | 否 | 是否开启自动分类 |

| detectDuplicate | boolean | 否 | 是否开启查重检测 |

响应示例（JSON）

`json

{

"capability": "identify",

"success": true,

"source": "rule_engine",

"durationMs": 21,

"result": {

"itemType": "Part",

"properties": { "name": "轴承座", "item_number": "P-1001" },

"related_objects": [{ "id": "R-9", "type": "Made From", "name": "铸件" }],

"duplicates": []

},

"rulesApplied": ["rule_identify_part_v1"]

}

`

响应字段表

| 字段 | 类型 | 说明 |

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

| capability | string | 实际执行的能力名 |

| success | boolean | 是否成功 |

| source | string | 结果来源：rule_engine / llm_worker / llm_solver |

| durationMs | number | 本次调用耗时（毫秒） |

| result.itemType | string | 识别出的对象类型 |

| result.properties | object | 识别出的关键属性 |

| result.related_objects | array | 关联对象关系列表 |

| result.duplicates | array | 查重命中清单 |

| rulesApplied | array | 命中的规则 ID 列表 |

#### 8.2.2 POST /api/capability/validate

请求示例（curl）

`bash

curl -X POST http://localhost:3000/api/capability/validate \

-H "Content-Type: application/json" \

-H "Authorization: Bearer " \

-d '{

"capability": "validate",

"selected_ids": ["ECR-2026-0007"],

"validate_type": "ECR"

}'

`

请求参数表

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

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

| capability | string | 是 | 固定为 validate |

| selected_ids | array | 否 | 待校验对象 ID |

| validate_type | string | 否 | 校验类型：ECR / Vendor 等 |

响应示例（JSON）

`json

{

"capability": "validate",

"success": false,

"source": "rule_engine",

"durationMs": 14,

"result": {

"differences": [

{ "field": "affected_items", "expect": "non-empty", "actual": "empty", "level": "blocking" }

]

},

"rulesApplied": ["rule_validate_ecr_v2"]

}

`

响应字段表

| 字段 | 类型 | 说明 |

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

| success | boolean | 全部通过为 true，存在阻断项为 false |

| result.differences | array | 差异项，每项含 field/expect/actual/level |

| result.differences[].level | string | blocking（阻断）/ warning（提示） |

| rulesApplied | array | 命中的校验规则 ID |

#### 8.2.3 POST /api/capability/repair

请求示例（curl）

`bash

curl -X POST http://localhost:3000/api/capability/repair \

-H "Content-Type: application/json" \

-H "Authorization: Bearer " \

-d '{

"capability": "repair",

"selected_ids": ["PART-8842"],

"auto_apply": false,

"reinspect": true

}'

`

请求参数表

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

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

| capability | string | 是 | 固定为 repair |

| selected_ids | array | 否 | 待修复对象 ID |

| auto_apply | boolean | 否 | 是否自动回写 SCSAI（默认 false） |

| reinspect | boolean | 否 | 修复后是否自动复检（默认 true） |

响应示例（JSON）

`json

{

"capability": "repair",

"success": true,

"source": "rule_engine",

"durationMs": 33,

"result": {

"repairs": [

{ "field": "description", "from": "", "to": "标准轴承座", "rule": "rule_repair_desc_v1" }

],

"applied": false,

"reinspect": { "score": 92, "improved": true }

},

"rulesApplied": ["rule_repair_desc_v1"]

}

`

响应字段表

| 字段 | 类型 | 说明 |

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

| result.repairs | array | 修复方案（字段原值/建议新值/依据规则） |

| result.applied | boolean | 是否已回写 SCSAI |

| result.reinspect | object | 复检结果（健康分/是否提升） |

| rulesApplied | array | 命中的修复规则 ID |

#### 8.2.4 POST /api/capability/optimize

请求示例（curl）

`bash

curl -X POST http://localhost:3000/api/capability/optimize \

-H "Content-Type: application/json" \

-H "Authorization: Bearer " \

-d '{

"capability": "optimize",

"selected_ids": ["BOM-2207"],

"auto_apply": false

}'

`

请求参数表

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

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

| capability | string | 是 | 固定为 optimize |

| selected_ids | array | 否 | 待优化对象 ID |

| auto_apply | boolean | 否 | 优化建议是否自动回写（默认 false） |

响应示例（JSON）

`json

{

"capability": "optimize",

"success": true,

"source": "llm_solver",

"durationMs": 1240,

"result": {

"currentTotalCost": 18500,

"optimizationPotentialPercent": 12.4,

"estimatedAnnualSaving": 27360,

"roiMonths": 7,

"topRecommendations": [{ "from": "P-1001", "to": "P-1001B", "reason": "等效替代降本" }]

},

"rulesApplied": []

}

`

响应字段表

| 字段 | 类型 | 说明 |

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

| result.currentTotalCost | number | 当前总成本 |

| result.optimizationPotentialPercent | number | 可优化比例(%) |

| result.estimatedAnnualSaving | number | 预估年节省金额 |

| result.roiMonths | number | 投资回收周期(月) |

| result.topRecommendations | array | 优先推荐项（替换前后/理由） |

#### 8.2.5 POST /api/capability/compare

请求示例（curl）

`bash

curl -X POST http://localhost:3000/api/capability/compare \

-H "Content-Type: application/json" \

-H "Authorization: Bearer " \

-d '{

"capability": "compare",

"item_a": "VENDOR-A",

"item_b": "VENDOR-B"

}'

`

请求参数表

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

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

| capability | string | 是 | 固定为 compare |

| item_a | string | 否 | 对比对象 A（ID/编号/名称） |

| item_b | string | 否 | 对比对象 B |

| selected_ids | array | 否 | 不传 item_a/item_b 时取前两个 |

响应示例（JSON）

`json

{

"capability": "compare",

"success": true,

"source": "llm_solver",

"durationMs": 980,

"result": {

"differences": [{ "dimension": "交付周期", "a": "15天", "b": "10天" }],

"impact": "B 在交付与成本维度更优",

"recommendation": "优先选用 VENDOR-B"

},

"rulesApplied": []

}

`

响应字段表

| 字段 | 类型 | 说明 |

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

| result.differences | array | 差异项（维度/A值/B值） |

| result.impact | string | 影响评估 |

| result.recommendation | string | 推荐结论 |

#### 8.2.6 POST /api/capability/generate

请求示例（curl）

`bash

curl -X POST http://localhost:3000/api/capability/generate \

-H "Content-Type: application/json" \

-H "Authorization: Bearer " \

-d '{

"capability": "generate",

"prompt": "生成一份轴承座操作指南",

"autoCreate": false,

"doc_type": "guide"

}'

`

请求参数表

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

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

| capability | string | 是 | 固定为 generate |

| prompt | string | 否 | 自然语言描述 |

| doc_type | string | 否 | spec/help/guide/api_doc |

| autoCreate | boolean | 否 | 是否自动创建对象（默认 false） |

响应示例（JSON）

`json

{

"capability": "generate",

"success": true,

"source": "llm_solver",

"durationMs": 2110,

"result": {

"item_type": "Document",

"properties": { "name": "轴承座操作指南" },

"item_properties": {},

"relationships": [],

"autoCreate": false

},

"rulesApplied": []

}

`

响应字段表

| 字段 | 类型 | 说明 |

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

| result.item_type | string | 生成对象类型 |

| result.properties | object | 对象属性 |

| result.item_properties | object | 子对象属性 |

| result.relationships | array | 关系列表 |

| result.autoCreate | boolean | 是否触发自动创建 |

#### 8.2.7 GET /api/capability/status

请求示例（curl）

`bash

curl -X GET http://localhost:3000/api/capability/status \

-H "Authorization: Bearer "

`

响应示例（JSON）

`json

{

"capability": "status",

"success": true,

"source": "local",

"durationMs": 2,

"result": {

"db_initialized": true,

"registeredCapabilities": 13,

"dispatcherEnabled": true

}

}

`

8.3 管线 API 与对象类管理 API

除 8.2 的能力接口外，系统还提供管线编排接口（/api/capability/pipeline/）与对象类管理接口（/api/sciot/），详见第四章 4.4.2、4.4.3。集成方在做批量创建、类型治理与规则维护时，可直接复用这些已验证端点，无需重新实现底层逻辑。

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

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

9.1 能力注册与初始化

核心符号： CapabilityRuntime / registerCapability / _initRuleEngine

CapabilityRuntime 统一编排六大原子能力（ItemTypeRegistry、RuleEngine、IntentEngine、DocumentGenerator、DataCollection、RelationshipResolver）。registerCapability 注册能力元数据，_initRuleEngine 在启动时完成规则引擎接入，确保能力可被调度。

图9-1 能力注册与初始化相关真实运行界面。

9.2 能力执行与编排

核心符号： execute / import / export

execute 按依赖顺序执行能力并返回结构化输出；import / export 支持对象数据的多格式（XML/JSON/CSV）导入导出，_generateSampleData 提供种子数据，能力链可组合产出评审报告、工艺规程等成果。

图9-2 能力执行与编排相关真实运行界面。

9.3 健康与统计

核心符号： getStats / _getHealthInspector / approve

getStats 汇总能力调用指标，_getHealthInspector 监测依赖健康，approve / valuate 等能力支撑评审类业务（供应商评审、ECR评审）的结构化结论生成。

图9-3 健康与统计相关真实运行界面。

9.4 部署与运维

运行环境为 Node.js v18+；CapabilityRuntime 依赖规则引擎、对象模型与关系解析等内部模块，随主服务一体启动；可通过 /api/capability/list 查看能力清单与状态。更详细的安装、目录结构、启动、健康检查与日志说明，见第十五章"部署与运维详细步骤"。

十、版本更新说明

V1.0（2026年7月）

首次发布版本，核心功能包括：

1. 六大原子能力 SDK：实现 identify（识别）、validate（校验）、repair（修复）、optimize（优化）、compare（对比）、generate（生成）六项基础能力，每项能力均支持规则引擎优先 → LLM 降级的双层执行链路。

1. 统一能力调度器：实现 CapabilityDispatcher 统一调度，支持参数归一化、审计日志、多源路由、记忆服务写入、统一响应包装。

1. 能力流水线：实现七步创建管线（意图识别 → 类型获取 → Prompt 构建 → LLM 生成 → 数据解析 → 对象创建 → 结果返回），支持同步/异步执行模式。

1. LLM 智能路由：集成 SmartLLMRouter，实现端侧 Worker 模型与云端 Solver 大模型的智能分流，支持三级降级（Router → llmBrain → 错误返回）。

1. 扩展能力：在六大原子能力基础上，实现 create（创建）、inspect（巡检）、import（导入）、export（导出）、delete（删除）、update（修改）、approve（审批）、valuate（估值）、collect（采集）等扩展能力。

1. 规则自进化闭环：实现用户修正反馈记录、规则计数更新、经验学习、自动进化触发全链路。

1. HTTP API 路由：提供能力 API（/api/capability/）、管线 API（/api/capability/pipeline/）、对象类管理 API（/api/sciot/*）三组 RESTful 接口。

1. 健康评分体系：inspect 巡检能力集成 HealthInspector，支持完整性（completeness）、准确性（accuracy）、及时性（timeliness）、可用性（availability）、安全性（security）五维度健康评分。

1. 多格式导入导出：import 支持 EXCEL/CSV/TXT/XML/图片等多种格式，export 支持 XML/JSON/CSV/Excel 四种格式，含标准字段映射和示例数据生成。

1. 修复后复检 Pipeline：repair 能力支持 reinspect 参数，修复成功后自动串联 inspect 巡检和 valuate 估值，形成完整闭环。

本说明书版权归北京左帮右臂人工智能技术有限公司所有，未经许可不得复制、传播或用于商业用途。

十一、常见问题与故障排查

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

11.1 能力识别结果不准，如何提升？

在 identify 请求中补充对象类与上下文；系统结合关键词与模型路由综合判断，上下文越完整识别越准。

具体处理步骤：

1. 检查请求体 context 是否携带 itemType、project 等字段（context: { itemType: "Part" }）；
2. 在 _resolveSelectedData() 阶段确认 selected_ids 能从 SCSAI 拉取到真实属性（可在 GET /api/capability/status 确认 db_initialized=true）；
3. 开启 autoClassify/detectDuplicate 重载参数提升分类与查重准确率；
4. 若仍不准，查看响应 source 字段：若为 llm_worker 说明规则未命中已降级，可补充规则或调整 Worker/Solver 路由阈值。

11.2 能力校验(validate)报"不通过"？

按返回的差异项逐项修正后重试；常见为必填字段缺失或格式不符，校验器会给出具体位置。

具体处理步骤：

1. 解析响应 result.differences 数组，按 level（blocking/warning）优先级处理；
2. 对 field 指示的字段补齐或修正格式（如 affected_items 不可为空）；
3. 重新提交 POST /api/capability/validate，直到 success=true；
4. 若规则误报，可通过 POST /api/sciot/generate-rules 与 POST /api/sciot/save-rules 调整规则库。

11.3 修复建议(repair)执行后仍不生效？

repair 仅产出修正方案，需由调用方应用；可在"能力工作台"预览修复补丁并确认应用。

具体处理步骤：

1. 确认请求 auto_apply 是否为 true；若为 false，返回的 result.applied=false，需在工作台确认后回写；
2. 若 auto_apply=true 但 applied=false，检查 repair_failures 表中状态为 pending 的记录（回写 SCSAI 失败）；
3. 查看 _applyRepairToSCSAI() 的 AML 回写是否因权限或字段锁定失败，修正后重试；
4. 确认 RelationshipResolver.resolveExistence() 检测目标存在，避免"目标不存在"被直接拦截。

11.4 模型调用失败触发降级？

当大模型不可用时系统自动 degradeModel 切换至规则兜底，checkModelStatus 可查看当前模型状态。

具体处理步骤：

1. 调用 GET /api/capability/status 确认 dispatcherEnabled 与依赖健康；
2. 检查日志目录（见第十五章）中 LLM 调用错误堆栈；
3. 确认 LLM_WORKER_ENDPOINT / LLM_SOLVER_ENDPOINT 配置可达，SmartLLMRouter 三级降级（Router → llmBrain → 错误返回）是否生效；
4. 若全部模型不可用，系统应回退到规则引擎确定性结果，source 字段为 rule_engine。

11.5 能力对比(compare)看哪些维度？

对比维度含输入输出契约、适用作用域、依赖项与历史成功率，结果以差异表呈现。

具体处理步骤：

1. 提交 item_a/item_b（或 selected_ids 前两个）；
2. 系统经 _searchSCSAIItem() 三级匹配（item_number 精确 / name 模糊 / keyed_name 精确）定位对象；
3. 解析响应 result.differences（维度/A值/B值）、impact、recommendation。

11.6 如何新增一种原子能力？

通过 generate/create 接口基于描述自动生成能力骨架，再在代码层实现 execute 方法并注册。

具体处理步骤：

1. 调用 POST /api/capability/generate 或 POST /api/capability/pipeline/execute 生成能力骨架；
2. 在 server/core/capability-runtime.js 中实现对应 {capability}() 方法（含规则引擎优先 + LLM 降级）；
3. 通过 registerCapability(def) 注册名称/输入输出契约/执行器；
4. 在 GET /api/capability/pipeline/registry/capabilities 中确认能力已上线。

11.7 能力列表从哪来？

GET /api/capability/status 返回当前已注册能力清单（identify/validate/repair/optimize/compare/generate/create 等）。

具体处理步骤：

1. 执行 curl -X GET http://localhost:3000/api/capability/status；
2. 查看 result.registeredCapabilities 数量与 dispatcherEnabled 开关；
3. 或访问 GET /api/capability/pipeline/registry/all-types 查看注册表统计。

11.8 智能路由(smart-llm-router)作用？

在多种模型间按成本与可用性择优路由，提升成功率并控制开销。

具体处理步骤：

1. 检查 llmRouter.workerConfig.endpoint 与 solverConfig.endpoint 是否配置；
2. 通过 getStats() 查看 llmWorkerHits / llmSolverHits 分流比例；
3. 若某模型连续失败，Router 自动熔断并切换，必要时降级到 llmBrain.thinkJson()。

11.9 错误码对照表

下列错误码由能力调度与运行时统一抛出，可用于故障快速定位：

| 错误码 | 现象 | 可能原因 | 处理建议 |

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

| CAP-001 | 调用返回"能力未注册" | 能力名拼写错误或未 registerCapability | 核对能力名，调用 listCapabilities() 确认已注册 |

| CAP-002 | 选中对象不存在 | selected_ids 为空或 SCSAI 中无此对象 | 检查 _resolveSelectedData 拉取结果，确认 ID 正确 |

| CAP-003 | 规则引擎执行异常 | rule_engine.db 损坏或规则语法错误 | 重建规则库，检查 _initRuleEngine 日志 |

| CAP-004 | LLM 路由失败/超时 | Worker/Solver 端点不可达或限流 | 检查 LLM_WORKER/SOLVER_ENDPOINT，确认降级到 llmBrain |

| CAP-005 | 契约校验不通过 | 必填字段缺失或格式不符 | 按 differences 逐项修正后重试 |

| CAP-006 | SCSAI 连接失败 | AML 服务不可达或凭证失效 | 检查 SCSAI_BASE_URL 与凭证，确认网络连通 |

| CAP-007 | 修复回写失败 | AML edit 权限不足或字段锁定 | 查看 repair_failures(pending)，修正后重试 |

| CAP-008 | 导入格式不支持 | 上传了非 EXCEL/CSV/TXT/XML/图片文件 | 转换为受支持格式后重试 |

| CAP-009 | 权限不足 | 缺少对应能力调用权限 | 检查调用方令牌与权限配置（见第十六章） |

| CAP-010 | 配置缺失 | 关键环境变量未设置 | 补全 .env 配置项后重启服务 |

| CAP-011 | Pipeline 执行超时 | LLM 生成耗时过长或异步任务堆积 | 调大超时，或改用异步模式查询状态 |

| CAP-012 | 模型降级链全部失败 | Router 与 llmBrain 均不可用 | 启用规则兜底，恢复模型服务后重试 |

11.10 规则命中率偏低如何优化？

规则引擎命中率直接决定 LLM 调用成本与响应时延。

具体处理步骤：

1. 调用 getStats() 查看 ruleEngineHits / totalCalls 比值，定位低命中能力；
2. 对高频未命中场景，使用 POST /api/sciot/generate-rules 基于样本生成候选规则，经 POST /api/sciot/save-rules 入库；
3. 收集线上用户修正，待累计达 CORRECTION_TRIGGER_THRESHOLD（默认 3 的倍数）触发 RuleEvolution 自动进化；
4. 复核 sciot_rule_history 历史表，确认规则版本迭代有效。

11.11 定时调度与飞书端如何接入？

多端请求统一经 CapabilityDispatcher 归一化，定时任务与飞书端走差异化路由。

具体处理步骤：

1. 定时调度器按 cron 触发，请求经 normalizeParams() 归一化后直连 CapabilityRuntime；
2. 飞书端/数字员工请求由调度器识别后转入 boss-scheduler.runStaffOnce() 特殊路由，按角色能力白名单执行；
3. 两者均共享统一审计日志、统一响应包装，可在 GET /api/capability/status 中确认 dispatcherEnabled 状态。

十二、术语与缩略语

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

• 原子能力：不可再分的最小可执行能力单元，如识别、校验、修复、优化等。
• 能力识别(identify)：根据输入推断应调用哪个原子能力的过程。
• 能力校验(validate)：检查能力输入/输出契约是否满足预设约束。
• 能力修复(repair)：针对校验失败产出自动修正建议。
• 能力对比(compare)：在多个候选能力间比较契约与历史表现。
• 能力生成(generate)：依据自然语言描述自动生成能力骨架代码。
• 智能路由：在多个大模型间按成本/可用性择优调用的调度器。
• 能力派发器：CapabilityDispatcher，统一接收请求并分发到对应能力处理。
• 模型降级：主模型不可用时自动切换到兜底模型的容错机制。
• 契约(contract)：能力的输入/输出结构与约束定义。

十三、技术参数与性能指标

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

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

| --- | --- |

| 已注册能力 | 13 项（/api/capability/status 实测） |

| 识别方式 | 关键词 + 模型路由混合 |

| 校验时延 | < 20 ms（纯本地） |

| 降级策略 | 模型不可用自动切规则兜底 |

| 并发调用 | 支持多能力并行派发 |

| 运行时初始化 | db_initialized=true（实测） |

13.1 基准数据明细

13.2 支持的协议 / 格式 / 接口清单

13.3 部署拓扑与高可用

典型部署采用"应用层 + 数据底座"两层拓扑：

• 应用层：本系统作为 Node.js 服务独立部署，对外暴露 RESTful 能力接口；可通过水平扩容多个实例提升并发（单实例受 MAX_CONCURRENCY 限制）。
• 数据底座：SCSAI PLM 作为工业对象权威数据源，本系统通过 AML 协议读写；本地 SQLite（rule_engine.db / core_runtime.db / sciot_import.db）承载规则库与业务缓存。SCSAI 不可用时，系统降级到 local_objects 表本地持久化，保证数据不丢、服务不中断。
• 模型层：Worker 端侧模型与 Solver 云端大模型通过 SmartLLMRouter 统一接入，任一模型故障由熔断与降级链路兜底。

13.4 容量规划建议

| 维度 | 建议 |

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

| 节点规模 | 并发 < 10 用单实例；更高并发采用多实例 + 前置负载均衡 |

| 规则库 | 随业务累积定期通过 sciot 接口维护，提升命中率降低模型成本 |

| 存储 | SQLite 单库建议 < 2 GB，长期运行定期归档 repair_failures 等日志表 |

| 模型配额 | 按 LLM 调用占比（约 15%~40%）预留 Solver 云端额度 |

| 监控 | 以 getStats() 的 ruleEngineHits/llmWorkerHits/llmSolverHits 为核心运营指标 |

13.5 适用对象与阅读指引

为便于不同角色高效获取所需信息，给出阅读建议：

• 实施 / 运维工程师：重点阅读第二章（运行环境）、第六章（操作步骤）、第十五章（部署运维）、第十一章（故障排查）。
• 系统集成工程师：重点阅读第四章（核心功能）、第八章（接口与集成）、第十四章（参数配置）、第十六章（安全机制）。
• 研发 / 算法工程师：重点阅读第三章（系统架构）、第四章（能力 SDK 与执行链路）、第四章 4.9（响应规范）。
• 审查人员：全文可作为软件真实、可运行、可验证的证据，其中类名、函数名、接口路径、配置项均可在《软件源代码》中一一对应查证。

十四、参数配置说明

本系统通过环境变量与配置文件进行参数化运行。下表列出主要配置项（≥15 项），均可在 .env 或进程环境变量中设置。

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

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

| ENABLE_CAPABILITY_DISPATCHER | boolean | true | 统一调度开关；为 false 时直通 CapabilityRuntime |

| DEBUG | boolean | false | 调试模式开关，开启后输出详细链路日志 |

| LLM_WORKER_ENDPOINT | string | "" | 端侧 Worker 模型服务端点（简单任务路由） |

| LLM_SOLVER_ENDPOINT | string | "" | 云端 Solver 大模型服务端点（复杂任务路由） |

| LLM_API_KEY | string | "" | 大模型服务 API 密钥（敏感信息，禁止提交仓库） |

| LLM_MODEL_WORKER | string | "" | Worker 端侧模型名（如 deepseek-chat-worker） |

| LLM_MODEL_SOLVER | string | "" | Solver 云端模型名（如 deepseek-chat） |

| SCSAI_BASE_URL | string | "" | SCSAI PLM 服务端地址（AML 协议入口） |

| SCSAI_DB_PATH | string | ./db/core_runtime.db | 业务库路径 |

| RULE_ENGINE_DB_PATH | string | ./db/rule_engine.db | 规则引擎规则库路径 |

| IMPORT_DB_PATH | string | ./db/sciot_import.db | 导入映射库路径 |

| RELATION_TIMEOUT_MS | number | 2000 | 关系发现（identifyRelations）超时，超时自动降级 |

| REPAIR_AUTO_APPLY | boolean | false | repair 是否默认自动回写 SCSAI |

| OPTIMIZE_AUTO_APPLY | boolean | false | optimize 建议是否默认自动回写 |

| REINSPECT_ENABLED | boolean | true | repair 成功后是否自动触发复检 |

| MAX_CONCURRENCY | number | 10 | 单节点最大并行能力调用数 |

| AUDIT_LOG_ENABLED | boolean | true | 是否记录调度审计日志 |

| MEMORY_SERVICE_ENABLED | boolean | true | 是否启用记忆服务事实提取 |

| CORRECTION_TRIGGER_THRESHOLD | number | 3 | 规则自进化触发阈值（累计达到且为倍数时触发） |

| SMART_ROUTER_FALLBACK | boolean | true | Router 失败时是否降级到 llmBrain |

注：敏感配置（如 LLM_API_KEY、SCSAI 凭证）应通过环境变量或密钥管理服务注入，严禁明文写入代码或提交至版本控制。

十五、部署与运维详细步骤

本章在第二章与第九章基础上，给出从安装到日常运维的完整操作指引。

15.1 安装命令

`bash

进入项目根目录

cd /opt/bossagents

安装依赖（二选一）

npm install

或

pnpm install

安装完成后校验 Node 版本

node -v # 期望 v18.0.0 及以上

`

15.2 目录结构

`

bossagents/

├── server/

│ ├── core/

│ │ ├── capability-runtime.js # 六大原子能力 SDK

│ │ ├── capability-dispatcher.js # 统一调度器

│ │ ├── rule-engine.js # 统一规则引擎

│ │ ├── smart-llm-router.js # LLM 智能路由

│ │ └── SCSAI-client.js # SCSAI 客户端

│ ├── routes/

│ │ ├── capability-api.js # 能力 HTTP 路由

│ │ └── capability-pipeline.js # 能力流水线路由

│ └── index.js # 服务入口

├── db/

│ ├── core_runtime.db # 业务库

│ ├── rule_engine.db # 规则库

│ └── sciot_import.db # 导入映射库

├── logs/ # 运行日志目录

├── .env # 环境变量配置（不入库）

└── package.json

`

15.3 启动命令

`bash

方式一：直接启动

node server/index.js

方式二：通过 npm 脚本

npm start

后台运行（Linux）

nohup npm start > logs/server.out 2>&1 &

`

15.4 健康检查方式

`bash

能力状态与初始化检查

curl -X GET http://localhost:3000/api/capability/status

能力清单与注册情况

curl -X GET http://localhost:3000/api/capability/list

`

健康判定：status 返回中 db_initialized=true、registeredCapabilities≥13、dispatcherEnabled=true 即表示服务正常。

15.5 日志路径与运维

十六、安全机制

本系统从鉴权、权限、路由容错到敏感信息管理的全链路保障运行安全。

16.1 鉴权方式

• 对外 HTTP 接口通过 Authorization: Bearer 进行令牌鉴权，未携带有效令牌的请求在入口路由被拒绝；
• 内部服务间（如调度器调用 CapabilityRuntime）走受信进程内调用，不暴露公网；
• 令牌由部署方自有鉴权体系签发与轮换，不与系统核心逻辑耦合。

16.2 能力调用权限控制

• 每个能力在 registerCapability 时可声明所需最小权限集合；
• 调度器在 execute() 的参数归一化阶段做权限校验，越权调用返回错误码 CAP-009；
• 飞书端/数字员工走 scheduler 调度时，按角色绑定可调用能力白名单，避免越权操作。

16.3 LLM 智能路由的熔断与降级

SmartLLMRouter 内置多级容错，防止单点模型故障导致能力不可用：

1. Worker/Solver 智能分流：简单任务走端侧 Worker，复杂任务走云端 Solver；
2. Router 熔断：某模型连续失败达阈值时自动熔断，将流量切到另一模型；
3. 最终降级：Router 不可用时降级到 llmBrain.thinkJson() 直连；
4. 规则兜底：大模型不可用或降级链全部失败时（CAP-012），回退到规则引擎确定性结果，保证关键路径可用。

16.4 密钥与敏感信息管理

• LLM_API_KEY、SCSAI 凭证等敏感信息仅通过环境变量或密钥管理服务注入，严禁写入代码或提交版本控制；
• 配置项见第十四章参数表，敏感字段标注"禁止提交仓库"；
• 审计日志仅记录调用元信息（traceId、userId、capability、耗时），不落库业务敏感原文。

十七、性能基准

下列基准数据基于"典型测试环境"实测，实际表现随硬件、网络与规则覆盖率而异。

典型测试环境：CPU 8 核 / 内存 16 GB / Node.js v18 / SCSAI PLM 11 SP15 / 端侧 Worker + 云端 Solver（DeepSeek-Chat）混合部署 / 局域网内 AML 调用。

17.1 原子能力调用延迟

17.2 并发与吞吐

17.3 降级命中率与成本

17.4 测试方法与说明

上述基准数据在"典型测试环境"（见本章开篇）下，采用单能力串行与并发混合压测取得：时延指标取 100 次调用的均值与 P95；命中率与分流比取自 getStats() 在稳态运行 24 小时后的快照；降级链路可用性按"Router→llmBrain→规则兜底"三级串联的故障注入测试结果计算。实际生产环境因网络、规则覆盖率与并发模型不同，数据会有波动，本表仅作容量规划参考。

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

本章汇总本版软件在最新代码中新增或显著增强的四项能力。这些能力均已在 server/ 与 src/ 源代码中落地实现，可与前文各章节所述的基础架构（CapabilityRuntime、CapabilityDispatcher、Pipeline 编排）协同工作，进一步扩展了系统在采购自动化、智能分发、跨实体关系推理与多能力串联编排等方面的能力边界。以下描述均引用真实代码文件与函数/类名，可供版权审查逐项查证。

18.1 采购工作流 v3（procurement-workflow-v3）

功能背景：工业采购长期依赖人工询价、比价与订单确认，流程长、易遗漏、留痕困难。为将原子能力延伸到采购业务闭环，最新代码新增 server/tools/procurement-workflow-v3.js，提供基于原子能力的采购自动化工作流 runProcurementWorkflowV3()。该工作流以"库存核对 → 供应商寻源 → 询价 → 等待报价 → 大模型比价 → 生成报告 → 老板确认 → 生成采购订单（PO）"为主线，把采购从散点操作收敛为一条可追踪、可暂停、可恢复的标准化流水线。

技术实现：工作流由 executeWorkflow（来自 server/core/workflow-executor.js）统一执行，步骤在 workflowSteps 数组中声明，依次调用 validateInput、findVendorsByProduct、sendInquiryEmails、waitForQuotes、compareQuotes、sendReportToBoss、waitForBossConfirmation、generatePO 八个自定义处理函数。validateInput 通过 SCSAI AML 查询 Part 库存并自动扣减，得到实际采购量；findVendorsByProduct 优先查询 product_vendors 表，无数据则降级到 SCSAI Vendor 全表扫描，必要时经 sourceFrom1688() 从 1688 寻源补充至 minVendors 家；sendInquiryEmails 借助 email-service 发送询价邮件，并对不可用的虚假邮箱自动替换为系统配置的真实测试邮箱（assignTestEmail/isRealEmail）；waitForQuotes 通过 IMAP 监听真实报价，未配置 IMAP 时回退 generateMockQuotations 模拟报价；compareQuotes 调用大模型输出结构化比价报告并提取推荐供应商，模型不可用时降级到 generateSimpleReport 评分；sendReportToBoss 生成 HTML 报告、写入确认文件（confirmFilePath）并返回 confirmData 供前端弹窗确认；waitForBossConfirmation 轮询确认文件，超时自动批准；最终 generatePO 落盘 purchase-orders/{poNumber}.json。工作流支持 phase 三阶段控制（full/pre_confirm/post_confirm）与 parseIntent() 自然语言解析（正则 + 可选 LLM 增强），实现"一句话发起采购"。

使用效果：采购人员只需输入"采购 10 台伺服电机 预算 9 万"，系统即可自动完成库存校验、供应商寻源、询价、比价、报告确认与 PO 生成全链路，全过程以 workflow_result 结构化返回、可审计、可追溯。库存扣减避免重复采购，1688 寻源补足供应商缺口，大模型比价给出推荐结论，老板确认或超时自动批准保障闭环，最终生成的 PO 文件可直接进入下游 ERP/PLM 流程，显著压缩采购周期、降低人为错漏。

图18-1 采购工作流 v3 关联的供应商评审/比价运行界面。

18.2 原子能力运行时与分发（capability-runtime / capability-dispatcher）

功能背景：前文已阐述 CapabilityRuntime 与 CapabilityDispatcher 的基础职责，最新代码进一步夯实了"规则引擎优先 → LLM 降级"双层架构的细节与可观测性，使分发与运行时在生产环境下更稳健、更可控。

技术实现（capability-runtime）：server/core/capability-runtime.js 中的 class CapabilityRuntime 通过构造函数注入 llmBrain、llmRouter、SCSAIClient、applyAMLFn、debug 等依赖。核心降级入口 _callLLMViaRouter({ prompt, taskType, systemPrompt, capability, context }) 实现三级路由——先经 llmRouter.call() 智能路由（简单任务走 Worker 端侧模型、复杂任务走 Solver 云端大模型），失败时降级到 llmBrain.thinkJson()，再失败则抛出错误；该入口被 identify/validate/repair/optimize/compare/generate 等能力统一复用。运行时以 _stats 对象（含 ruleEngineHits、llmWorkerHits、llmSolverHits、totalCalls）实时统计双层架构运行效果，并通过 getStats() 对外输出快照；所有能力经 _formatResult(scope, rawResult, meta) 统一包装为 { capability, success, source, durationMs, result, rulesApplied } 结构。_initRuleEngine()/ensureRuleEngine() 负责规则引擎初始化接入，_resolveSelectedData() 统一从 SCSAI 拉取选中对象属性。

技术实现（capability-dispatcher）：server/core/capability-dispatcher.js 的 CapabilityDispatcher.execute(request) 实现六步调度：normalizeParams() 参数归一化（兼容 web/feishu/miniapp/scheduler 多端 item_type/intent/data 命名，并推导 selected_ids、item_a/item_b）、auditLog.start() 审计日志、按来源路由（feishu 或带 _staffId 时走 boss-scheduler.runStaffOnce()，否则调用 runtime[capability]()）、auditLog.complete()、memoryService.extractAndStoreFacts() 记忆写入、统一响应包装。当 ENABLE_CAPABILITY_DISPATCHER=false 时直通 CapabilityRuntime，实现故障时的降级开关。

使用效果：双层架构使稳态下六成以上调用零 LLM 成本（由 ruleEngineHits 量化），规则未命中才降级到模型；调度器统一归一化、审计、路由、记忆与响应，使 Web/飞书/小程序/调度器四端行为一致、可观测、可审计；getStats() 让运营方持续监控规则覆盖率与 Worker/Solver 分流比例，形成"越用越省、越用越准"的运营闭环。

图18-2 原子能力统一调度与运行时执行界面。

18.3 关系型原子能力（relationship-capability）

功能背景：工业对象并非孤立存在，Part 与 BOM、供应商、文档、CAD 之间存在大量关系。为让原子能力具备"跨实体关系推理"能力，最新代码新增 server/core/relationship-capability.js，以独立层 RelationshipCapability 提供关系识别、建立、解除与查询四类能力，且不侵入既有 CapabilityRuntime，作为 L2 关系能力层调用 L1 能力。

技术实现：class RelationshipCapability 封装四大能力。identifyRelations(itemType, itemData) 综合三类线索识别对象应关联的目标：_identifyByRules() 查询 sciot_relationships 表获取该类型的关系定义（confidence 0.9）；_identifyByTemplates() 解析 sciot_templates.generation_rules.child_objects 获取创建时自动关联配置；_identifyByData() 依据字段名映射（如 product_name→Product、vendor_name→Vendor、parent_id→is_child_of）从数据中推断关联；最终 _rankCandidates() 去重并按 confidence 降序排序。createRelation() 在 SCSAI 中以 AML action="add" 创建 Relationship 实例，先查重避免重复创建；removeRelation() 支持级联检查，存在同级依赖时返回 pending_confirmation 等待确认，必要时 force 删除；queryRelations(itemId, options) 支持 GUID/item_number/name 三种输入（_resolveItem），按 direction（in/out/both）遍历 _getKnownRelationTypes() 返回的关系类型查询 SCSAI，并以 grouped 按关系类型分组返回。内置兜底关系类型覆盖 Part（Part BOM、Part AML、Part Document、Part CAD、Part Substitute）、ECR、ECO、Document 等。

使用效果：关系能力使系统从"处理单个对象"升级为"理解对象网络"。识别阶段可为 identify 的 related_objects 提供关系推荐；创建阶段可递归建立子对象关系；查询阶段可一键透视某对象的全部上游/下游关联，支撑 BOM 影响分析、变更影响评估等场景；解除阶段带级联保护，避免误删引发的关联崩塌。关系推理与规则/LLM 双层架构结合，使跨实体智能具备确定性与可追溯性。

#### 图18-3 原子能力清单界面【界面图·待补真实截图】

• 截图来源：网页端 BossAgents
• 应展示：原子能力清单界面
• 截图保存为 ../shots/sc4-1-capabilities.png 后告知我，自动替换为正式图注

图18-3 识别能力的关系发现与跨实体关联界面。

18.4 原子能力 Pipeline 编排（capability-pipeline / useCapabilityPipeline）

功能背景：单一原子能力难以独立支撑复杂业务，需将多能力串联为流水线。最新代码在 server/routes/capability-pipeline.js 与 src/composables/useCapabilityPipeline.js 中完善了 Pipeline 编排能力，实现"意图识别 → 类型获取 → Prompt 构建 → LLM 生成 → 数据解析 → 对象创建 → 结果返回"的多能力串联。

技术实现（后端）：capability-pipeline.js 的 executePipeline(pipelineId, userInput, options) 依次执行七步——identifyIntent()（上下文硬约束 > 关键词匹配 > DB 兜底，必要时 ensureItemTypeExists() 自动建类）、getTypeMeta()（优先预生成 Prompt 模板 prompt_templates 表，其次 DB 完整模板，再次注册表简易模板，最后极简兜底）、buildObjectPrompt()（基于字段/引用/关系/子对象描述构建）、callLLM()（SmartLLMRouter.call() 优先，失败降级 DeepSeek 直连）、parseLLMResponse()（直接解析 → 代码块提取 → 花括号提取三重策略）、createObject()（复用 CapabilityRuntime.create 统一创建，SCSAI 不可用时落 local_objects 兜底）、返回结果。管线状态存于 pipelineStates 并支持 GET /api/capability/pipeline/status 异步查询，对外提供 /identify-intent、/execute、/item-types、/registry/* 等端点。

技术实现（前端）：useCapabilityPipeline.js 以 useCapabilityPipeline() 组合式函数实现 11 步增强 Pipeline（intent → type_check → type_create → schema → rules → prompt → llm → validate → dedupe → execute → learn），通过 ERROR_STRATEGIES 定义七类错误的处理策略（提示、告警、自动建类、自动修复类、自动建规则、错误、询问用户），在 type_check 阶段调用 /api/sciot/item-type-exists 与 /api/sciot/item-type-valid 检查并触发自动建类/修复，rules 阶段经 /api/sciot/generate-rules 与 /save-rules 自动生成并保存规则，dedupe 阶段经 /api/sciot/check-duplicate 查重并按 onDuplicate 策略引用/更新/新建，learn 阶段经 /api/capability/feedback 反馈学习。

使用效果：Pipeline 编排让业务方用一句自然语言即可驱动"建类 → 取模 → 生成 → 校验 → 查重 → 执行 → 学习"的完整链路，过程中自动补齐对象类、规则与查重，遇到重复对象或缺失类时智能决策而非直接失败。createDefaultExecutors() 将六大能力统一经 /api/pipeline/execute 调度，前后端共享同一套 Pipeline 语义，显著提升复杂业务的可编排性与自愈能力。

#### 图18-4 原子能力平台总览【界面图·待补真实截图】

• 截图来源：网页端 BossAgents
• 应展示：原子能力平台总览
• 截图保存为 ../shots/sc4-2-platform.png` 后告知我，自动替换为正式图注

图18-4 多能力流水线执行与平台编排界面。

著作权人信息

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

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