规则、模板与提示词系统 — 闭环方案文档

版本: v3.5 | 更新: 2026-06-01 | 适用范围: SCSAI PLM BossAgents

v3.5 更新：文档核心理念强化。新增"核心设计原则"章节（1.3），系统阐述六大设计原则：AML派生视图、提示词确定性生成、前后端职责边界、action_script 不可执行原因、两套规则表历史债务、三层字段分类的 bug 根因与修复。每项原则都包含"为什么这样设计"和"当前局限性/风险"。三层字段分类从第 3.3 节末尾提升为独立原则（原则六），记录完整的 bug 现象、根因、修复方案和教训。新增双路径提示词生成的一致性风险分析、前端自组装的架构决策理由。

v3.4 更新：三层字段分类架构改造（Item属性正确分离）。核心修复：WBS 等 Item 类型属性（data_type: 'item'）之前被错误地当作 relationships（子对象）处理，导致创建时 AML 结构不正确。现在系统明确区分三种字段类型：properties（普通标量属性）、item_properties（Item 类型属性，如 wbs_id → WBS Element）、relationships（双向关系，如 Project Tree）。generation_rules 新增 item_properties 配置段，前后端 Prompt 构建器均改为动态识别 Item 类型属性（不再硬编码 Project 特殊逻辑）。影响文件：src/utils/PromptBuilder.js、src/views/StaffCapabilities.vue、server/routes/rule-engine.js（两处 pregenerate-prompt）、server/core/rule-engine.js（builtin 规则注释更新）。

v3.3 更新：数据清洗事件与完整审计。发现并修复了 sciot_item_types 中混入 143 个属性名（如 created_on、item_number）作为 ItemType 的根本性数据结构错误。根本原因是 generated/sciot-index-auto.json 将 113 个属性名标记为 ItemTypes，导致自增强错误循环。新增清洗脚本 scripts/clean-dirty-item-types.js 和提示词重建脚本 scripts/regenerate-creation-prompts.js。完成全代码库 sciot_rules（旧表）引用审计（14+ 处）。新增已知问题 #9（staff-manager.js item_type 列名 bug）和 #10（ai-inspector 全程使用旧表）。更新文件清单、一致性校验清单、数据库清单和闭环保证项。

v3.2 更新：架构演进——Create 场景从前端调用后端规则引擎改为前端自主完成全部业务逻辑。新增前端规则验证模块 src/utils/rule-validator.js。StaffCapabilities.vue 的 Create 面板不再调用 /api/rule-engine/create-item 和 /api/aml/assemble，改为前端 buildAML() 组装 + _SCSAIApiRequest() 提交 SCSAI。更新文件清单、一致性校验清单和 Create 场景调用链描述。

v3.1 更新：代码级审计修正。修正了 API 路由名称不匹配（pregenerate-all → pregenerate-prompt/batch）、数据库连接模式说明（每请求创建→sqlite-compat 单例缓存）、server.js 健康检查使用旧表问题、Scope 与实际代码不一致等问题。新增"文档与代码一致性校验清单"。

v3.0 更新：从"罗列现状"重构为"系统闭环方案"。新增闭环原理、场景消费映射、问题定位指南。核心理念：规则模板是源头，提示词是可重复生成的产物，AML文件是不变的数据源，三者形成可追溯、可修复、可优化的完整闭环。

目录

1. 系统闭环原理
2. 数据源层：AML文件是唯一不变的源头
3. 配置层：规则、模板、提示词的统一管理
4. 预生成层：提示词的可重复生成机制
5. 消费层：六大场景如何使用配置
6. 统一API与管理界面
7. 问题定位与修复指南
8. 数据清洗事件记录
9. 巡检、自愈与持续优化
10. 实现状态与优化路线
11. 附录：文件清单与API索引

1. 系统闭环原理

1.1 核心理念：一个完整的闭环

系统采用 "AML为源、规则模板为纲、提示词为产物、场景消费为目标" 的闭环架构：

``

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

│ ① AML 文件（唯一不变的数据源） │

│ SCIOT/*.xml — SCSAI ItemType 定义 │

│ 属性定义、生命周期、关系、序列规则 │

└────────────────┬────────────────────────┘

│ 导入解析

▼

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

│ ② 规则 & 模板（配置层，统一存储在 sciot_import.db） │

│ │

│ ┌─────────────────────┐ ┌──────────────────────────────┐ │

│ │ sciot_rules_v2 │ │ sciot_templates │ │

│ │ 统一规则表 │ │ 对象模板库 │ │

│ │ · scope 作用域 │ │ · llm_fields (LLM生成字段) │ │

│ │ · condition 条件 │ │ · auto_fields (自动字段) │ │

│ │ · action 动作 │ │ · required_fields │ │

│ │ · priority 优先级 │ │ · generation_rules ★ │ │

│ │ ★ builtin 规则: │ │ ├ item_properties │ │

│ │ create_pre 中 │ │ └ child_objects │ │

│ │ 处理 item_props │ │ │ │

│ └──────────┬──────────┘ └──────────────┬───────────────┘ │

│ │ │ │

│ └──────────┬───────────────────┘ │

│ │ 作为输入 │

│ ▼ │

│ ┌──────────────────────────────────────────────────────────┐ │

│ │ ③ 提示词预生成（可重复的确定性过程） │ │

│ │ POST /api/rule-engine/pregenerate-prompt │ │

│ │ 规则 + 模板 + 属性 + 关系 + 序列 → 拼接为提示词文本 │ │

│ │ ★ 动态生成: item_properties 提示 + child_objects 提示 │ │

│ └──────────────────────────┬───────────────────────────────┘ │

│ │ 存储 │

│ ▼ │

│ ┌──────────────────────────────────────────────────────────┐ │

│ │ prompt_templates 表（版本化提示词库） │ │

│ │ · prompt_type: creation/identify/repair/optimize/... │ │

│ │ · item_type_name: Part/ECR/Vendor/... │ │

│ │ · version: 支持 A/B 测试和回滚 │ │

│ └──────────────────────────┬───────────────────────────────┘ │

│ │ │

└──────────────────────────────┼───────────────────────────────────────┘

│ 统一API访问

▼

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

│ ④ 场景消费层（六大基础能力） │

│ │

│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │

│ │ Create │ │ Assemble │ │ Repair │ │ Optimize │ │ Compare │ │

│ │ 创建对象 │ │ AML组装 │ │ 修复数据 │ │ 优化数据 │ │ 比对差异 │ │

│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │

│ │ │ │ │ │ │

│ └────────────┴────────────┴────────────┴────────────┘ │

│ │ │

│ 读取提示词 + 读取规则 + 读取模板 │

│ 统一通过规则引擎API / 统一Schema API │

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

│

▼

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

│ ⑤ 反馈与修复（闭环的关键） │

│ │

│ 创建没问题 → 提示词/规则/模板 OK │

│ 组装出问题 → 检查规则模板定义 → 修改 → 重新生成提示词 → 重试组装 │

│ 修复不准确 → 检查修复规则优先级 → 调整 → 重新生成提示词 │

│ 优化效果差 → 检查优化规则条件 → 修正 → A/B测试新版本 │

│ │

│ 所有修改 → 在统一界面/REST API完成 → 重新预生成 → 即时生效 │

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

`

1.2 闭环的核心保证

1.3 核心设计原则（为什么这样设计）

#### 原则一：AML 是唯一数据源，配置层是"派生视图"

`

SCIOT/*.xml (AML 文件) ← 唯一不变的事实来源

│ 导入 (import-aml-v2.js)

▼

sciot_item_types / properties ← 自动生成的基础数据（不应手动修改）

│ 人工维护

▼

sciot_templates / sciot_rules_v2 ← 配置层（可维护，表达"人想要什么"）

│ 预生成

▼

prompt_templates ← 产物（可随时删除重建）

`

核心约束：

• AML 基础数据只能通过重新导入 AML 文件来修改，不能手动改库
• 配置层（规则+模板）是人对 SCSAI 理解的编码，与 AML 基础数据解耦
• 提示词永远是产物，不是源头

关键风险：当 AML 重新导入后（SCSAI 版本升级），基础数据变化，但配置层不会自动更新。此时需要人工检查规则/模板是否仍匹配新的 AML 结构。这是系统的脆弱点——当前缺少自动化的"配置-AML一致性校验"机制。

#### 原则二：提示词必须是确定性生成，不能是 AI 生成的

为什么：如果提示词由 AI 生成，那么：

• 相同输入可能产生不同输出 → 无法重现问题
• AI 可能漏掉关键字段或规则 → 创建行为不稳定
• 每次修改规则后结果不可预测 → 无法信任系统

实现：pregenerate-prompt 是纯脚本拼接（查表 + 字符串模板），不使用 LLM。

⚠️ 当前局限性：Create 场景有两套提示词生成路径——

| 路径 | 触发条件 | 生成方式 | 一致性风险 |

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

| 路径A：预生成提示词 | 有 prompt_templates 记录 | 服务端确定性拼接 | 低（确定性） |

| 路径B：PromptBuilder 动态拼装 | 无预生成记录或降级 | 前端 JS 动态拼接 | 中（与路径A可能不一致） |

TODO：两条路径的提示词模板应统一，或确保降级路径与预生成路径输出完全一致。

#### 原则三：前端负责"怎么做"，后端负责"存什么"

`

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

│ 前端（StaffCapabilities.vue） │

│ 职责：业务逻辑——字段验证、AML组装、SCSAI提交、冲突重试 │

│ 调用：Schema API、Template API、Prompt API、LLM API │

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

│ 后端（server/） │

│ 职责：数据存取——SQLite CRUD、规则引擎执行、SCSAI代理 │

│ 提供：REST API（规则、模板、提示词、Schema、LLM代理） │

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

│ 共享： │

│ · src/utils/AmlBuilder.js ← 前端 AML 构建（主力） │

│ · server/utils/aml-builder.js ← 服务端 AML 构建（辅助） │

│ · src/utils/PromptBuilder.js ← 前端降级提示词生成 │

│ · server/routes/rule-engine.js ← 服务端提示词预生成 │

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

`

为什么 Create 场景移到前端（v3.2）：

1. SCSAI API 只能从前端调用（浏览器 CORS/认证限制），后端无法直接提交 AML 到 SCSAI
2. 字段验证逻辑需要即时反馈（用户输入 → 实时校验），后端往返延迟太高
3. AML 组装需要灵活处理 item_properties 预创建/内联的双模式，前端有完整上下文
4. 冲突重试需要快速迭代（LLM修正 → 重新组装 → 重新提交），前端循环更高效

#### 原则四：action_script 是规则意图文档，不是可执行代码

为什么不能直接执行：

• SCSAI 客户端 JS 方法（如 SCSAI.getItemById()）与 SCSAI UI 深度绑定
• 这些方法依赖 SCSAI 客户端的全局对象和 DOM 状态
• new Function(action_script) 在 Node.js 后端和浏览器前端都缺少 SCSAI 运行时环境

正确做法：

1. 读取规则的 condition、action_type、action_config 字段
2. action_script 作为参考文档，理解规则的业务意图
3. 在对应的前端/后端代码中自己编写实现逻辑

#### 原则五：两套规则表的架构债务（为什么会有）

`

历史演进：

v1: sciot_rules（旧表） ← 原始设计，按 property_name + rule_type 组织

字段: rule_type, property_name, data_type, rule_pattern, description, severity, category

v2: sciot_rules_v2（新表） ← 规则引擎重构，按 scope + condition + action 组织

字段: scope, condition, action_type, action_config, priority, prompt_template_id

现状：两表并存，14+ 处代码仍引用旧表

`

为什么没有统一：

1. AMLEngine（server/aml-assembly-engine.js）的验证逻辑深度依赖旧表的 rule_pattern 字段，直接迁移工作量大
2. staff-manager.js、SCSAI-tools.js 等模块的旧表查询嵌在核心业务流程中，重构风险高
3. 新表设计更通用但旧表的 rule_type 分类（如 required/format/range）在特定场景更直观

迁移策略（P1）：旧表加只读标记 → 新表补充缺失的规则 → 逐个模块切换 → 删除旧表引用

#### 原则六：SCSAI 字段必须按三种类型正确处理（v3.4 核心修复）

这是系统经历过的最严重的功能 bug 之一，根源是对 SCSAI 对象模型的理解错误。

问题现象：创建 Project 时，wbs_id 字段（Item 类型属性，指向 WBS Element）被错误地放在 区块中，导致 SCSAI 服务器拒绝请求或产生错误的关联结构。

根本原因：代码将所有非标量字段都当作 relationships（子对象关系）处理，但 SCSAI 中实际存在三种字段类型：

`

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

│ SCSAI 对象字段的三种类型（必须正确区分，否则 AML 结构错误） │

│ │

│ 1. properties（普通属性） │

│ data_type: string/number/date/list/... │

│ AML 格式: 项目名称 │

│ 示例: name, description, start_date, cost │

│ 处理: LLM 直接生成值 │

│ │

│ 2. item_properties（Item 类型属性） ← 之前被错误当作 relationships│

│ data_type: item / foreign │

│ AML 格式: │

│ xxx WBS │

│ 示例: wbs_id, scheduling_method, managed_by_id │

│ 特征: 字段值是另一个 Item，放在属性区块内（非Relationships）│

│ 处理: 预创建目标 Item → 获取 ID → 以 包裹写入 │

│ │

│ 3. relationships（关系类型） │

│ AML 格式: │

│ ... │

│ │

│ 示例: Project Tree, Document Relationship, Part BOM │

│ 特征: 双向连接，放在独立的 Relationships 区块 │

│ 处理: 建立 RelationshipType 实例 │

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

`

修复方案（v3.4）：

1. generation_rules 新增 item_properties 配置段，与 child_objects（relationships）明确分离
2. 前端 PromptBuilder.buildCreationPrompt() 动态检测 data_type=item/foreign 字段
3. 前端 StaffCapabilities.runCreate() 使用 generation_rules.item_properties 判断是否需要预创建
4. AmlBuilder 支持 item_properties 的 add/get 双模式

教训：不能假设 SCSAI 字段分类等于"标量 vs 关系"二分法。必须查阅 AML schema 中的 data_type 字段，区分 item/foreign（Item 属性）和真正的 Relationships。

1.4 数据库清单

| 数据库 | 角色 | 存储内容 | 连接管理 |

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

| sciot_import.db | 配置主库（唯一真相源） | sciot_rules_v2（规则引擎新表）、sciot_rules（旧规则表）、sciot_templates（模板）、prompt_templates（提示词）、sciot_item_types、sciot_properties、sciot_relationships、sciot_sequences、sciot_methods、digital_staff 等 30+ 表 | ⚠️ 通过 sqlite-compat.js 的 Map 缓存实现单例共享（同一路径返回同一实例），但多处代码各自独立调用 createDatabase() |

| bossagents.db | 应用运行时业务数据库 | 24 张业务表（订单、库存、BOM等） | ✅ 单例 (server/database1.js) |

原则：规则、模板、提示词的"增删改查"全部在 sciot_import.db 中完成。bossagents.db 只存储业务运行时数据，不参与配置管理。

⚠️ 已知问题：sciot_import.db 存在两套规则表（sciot_rules 旧表 vs sciot_rules_v2 新表），且 server.js 健康检查等端点仍查询旧表，详见第10章。v3.3 已完成全代码库旧表引用审计，共 14+ 处，详见第9.0节。

关于 sqlite-compat 连接模式：虽然代码中每次请求都调用 compat.createDatabase(dbPath)，但 sqlite-compat.js 内部使用 _instances Map 缓存同一路径的实例，所以底层是共享单例。这不是真正的"每请求新建连接"问题，而是调用方式不够优雅。真正的问题是多模块各自持有对 sciot_import.db 的引用，没有统一的访问入口。

2. 数据源层：AML文件是唯一不变的源头

2.1 为什么AML是唯一源头

`

SCIOT/*.xml (636个AML文件)

│

├── 定义 ItemType 的完整结构：

│ · 属性列表 (Properties) → sciot_properties

│ · 对象关系 (Relationships) → sciot_relationships

│ · 生命周期 (Life Cycle) → sciot_lifecycle

│ · 序列规则 (Sequences) → sciot_sequences

│ · 客户端方法 (Methods) → sciot_methods

│

└── 导入脚本: scripts/import-aml-v2.js (1618行)

│

├── 创建 sciot_* 系列表

├── 解析 AML XML → 入库

└── 导入完成后 → 成为规则/模板/提示词的唯一数据基础

`

关键约束：AML 文件一旦导入，不应手动修改 sciot_properties、sciot_relationships 等基础表。所有调整通过规则和模板的配置层完成。

2.2 AML文件与配置层的关系

2.3 数据不变性原则

`

当AML文件没有变化时：

规则模板提示词的整体结构不变

可以安全地：

· 调整规则的 priority/severity

· 修改模板的 llm_fields/auto_fields 分类

· 重新预生成提示词（结果可预测）

· 全部删除后重建（结果一致）

当AML文件有变化时（SCSAI升级）：

重新导入 AML → 基础表更新

可能需要：

· 检查规则是否仍适用

· 更新模板字段分类

· 重新预生成所有提示词

`

3. 配置层：规则、模板、提示词的统一管理

3.1 统一存储：一张图看清所有表

`

sciot_import.db（配置主库）

│

├── 基础数据表（从AML导入，只读）

│ ├── sciot_item_types — 对象类定义

│ ├── sciot_properties — 属性定义

│ ├── sciot_relationships — 对象关系

│ ├── sciot_sequences — 编号规则

│ ├── sciot_methods — 客户端方法

│ ├── sciot_lifecycle — 生命周期

│ └── sciot_list_values — 列表值

│

├── 配置表（可维护、可调整）

│ ├── sciot_rules_v2 — ★ 统一规则表（核心）

│ ├── sciot_templates — ★ 对象模板表（核心）

│ └── sciot_business_prompts — 业务系统级提示词

│

├── 产物表（由预生成过程产生）

│ ├── prompt_templates — ★ 版本化提示词库（核心）

│ └── sciot_prompts — 对象级提示词（兼容旧版）

│

└── 运行时表

├── sciot_rule_history — 规则执行历史

├── digital_staff — 数字员工配置

├── staff_tasks — 员工任务

└── staff_execution_logs — 执行日志

`

3.2 三张核心表的关系

`

sciot_templates sciot_rules_v2 prompt_templates

(模板：结构定义) (规则：行为定义) (提示词：LLM协议)

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

│ item_type_name │────→│ item_type_name │ │ item_type_name │

│ llm_fields[] │ │ scope │ │ prompt_type │

│ auto_fields[] │ │ condition │ │ content (完整文本) │

│ required_fields │ │ action_type │ │ version │

│ generation_rules│ │ prompt_template │─────→│ score │

│ ├ item_properties│ │ prompt_template │ └────────────────────┘

│ └ child_objects │ │ _id │──┐

└────────────────┘ └────────────────┘ │

│ 外键关联

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

`

关系说明：

• 模板定义了"这个对象有什么字段，哪些LLM生成，哪些自动填充"
• 规则定义了"在什么条件下执行什么动作"，可以引用内联提示词或 prompt_templates 表中的提示词
• 提示词是预生成的产物，基于模板字段分类和规则条件拼接而成

3.3 核心表结构

#### sciot_rules_v2（统一规则表）

`sql

CREATE TABLE sciot_rules_v2 (

id TEXT PRIMARY KEY,

name TEXT NOT NULL,

description TEXT,

scope TEXT NOT NULL, -- 六大场景 + validate/transform

item_type_name TEXT, -- 适用对象类

severity TEXT DEFAULT 'warning', -- error/warning/info/hint

priority INTEGER DEFAULT 2, -- 0=P0(阻塞) 1=P1(高) 2=P2(中) 3=P3(低)

-- 条件与动作

condition TEXT, -- { field: 'name', operator: 'empty' }

condition_script TEXT, -- 自定义JS条件

action_type TEXT, -- auto_fix/suggest/block/warn

action_config TEXT, -- JSON配置

action_script TEXT, -- 自定义JS动作

-- 提示词关联

prompt_template TEXT, -- 内联提示词（兼容旧版）

prompt_template_id TEXT, -- 关联 prompt_templates.id

use_prompt_condition TEXT, -- 条件性LLM调用

-- 查询扩展

query_type TEXT, -- single/list/cross/stats/report

result_transformer TEXT,

-- 冲突解决

conflict_strategy TEXT DEFAULT 'first_match',

-- 元数据

is_active INTEGER DEFAULT 1,

is_builtin INTEGER DEFAULT 0,

source TEXT DEFAULT 'manual', -- manual/aml_import/SCSAI_sync/builtin

version INTEGER DEFAULT 1,

tags TEXT,

-- 统计

hit_count INTEGER DEFAULT 0,

last_hit_at TEXT,

avg_duration_ms INTEGER DEFAULT 0,

user_correction_count INTEGER DEFAULT 0,

created_at TEXT, updated_at TEXT

);

`

#### sciot_templates（对象模板表）

`json

{

"template_type": "object",

"item_type_name": "Project",

"aml_template": "...",

"required_fields": ["name", "project_number"],

"optional_fields": ["description", "start_date", "end_date"],

"llm_fields": ["name", "description", "start_date", "end_date"],

"auto_fields": ["project_number", "id", "created_on", "scheduling_type", "scheduling_mode"],

"generation_rules": {

"item_properties": {

"wbs_id": {

"target_type": "WBS Element",

"description": "项目的顶层 WBS 元素（工作分解结构根节点）",

"is_mandatory": true,

"properties": { "name": "{project_name} WBS", "is_top": "1" },

"llm_fields": ["name"],

"auto_fields": ["is_top", "proj_num"]

}

},

"child_objects": [

{

"relationship_name": "Project Tree",

"target_type": "WBS Element",

"is_mandatory": false,

"generate_child": true,

"llm_hint": "项目计划中的任务或里程碑节点",

"llm_fields": ["name", "wbs_type"],

"auto_fields": []

}

],

"nested_depth": 0,

"relationship_config": {}

}

}

`

generation_rules 结构说明（v3.4）：

| 字段 | 类型 | 说明 |

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

| item_properties | Object | Item 类型属性配置。键为属性名（如 wbs_id），值为子对象创建规则。这些字段的 data_type 为 item 或 foreign，值指向另一个 Item。AML 生成 ... 格式。 |

| item_properties.{name}.target_type | string | 目标 ItemType（如 WBS Element） |

| item_properties.{name}.is_mandatory | boolean | 是否必须创建（即使 schema 中 is_required=0，SCSAI 服务器也可能要求此字段） |

| item_properties.{name}.properties | Object | 子对象默认属性（支持 {project_name} 等模板变量） |

| item_properties.{name}.llm_fields | string[] | LLM 可生成的子对象字段 |

| item_properties.{name}.auto_fields | string[] | 系统自动填充的子对象字段 |

| child_objects | Array | 关系类型子对象配置（v3.4 中与 item_properties 明确区分）。通过 Relationships 连接的双向关系，AML 生成 ... 格式。 |

| nested_depth | number | 嵌套深度 |

| relationship_config | Object | 关系额外配置 |

三层字段分类（核心概念）：

`

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

│ SCSAI 对象字段的三种类型 │

│ │

│ 1. properties（普通属性） │

│ data_type: string/number/date/list/... │

│ AML: 项目名称 │

│ 示例: name, description, start_date, cost │

│ │

│ 2. item_properties（Item 类型属性） ← v3.4 新增明确分离 │

│ data_type: item / foreign │

│ AML: │

│ xxx WBS │

│ 示例: wbs_id, scheduling_method, managed_by_id │

│ 特征: 字段值是另一个 Item 的引用（创建时嵌套，引用时 get） │

│ │

│ 3. relationships（关系类型） │

│ AML: │

│ ... │

│ │

│ 示例: Project Tree, Document Relationship, Part BOM │

│ 特征: 双向连接，建立 RelationshipType 实例 │

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

`

#### prompt_templates（提示词模板库）

`sql

CREATE TABLE prompt_templates (

id TEXT PRIMARY KEY,

name TEXT NOT NULL,

description TEXT,

content TEXT NOT NULL, -- 完整提示词文本（支持 {{变量}}）

variables TEXT, -- 变量列表 JSON

prompt_type TEXT DEFAULT 'creation', -- creation/identify/repair/optimize/compare/report

item_type_name TEXT,

version INTEGER DEFAULT 1,

status TEXT DEFAULT 'active', -- active/deprecated/testing

parent_id TEXT, -- A/B测试分支

score REAL DEFAULT 0,

usage_count INTEGER DEFAULT 0,

created_at TEXT, updated_at TEXT

);

`

3.4 Scope与场景的完整映射

实际代码中 RULE_SCOPES 定义在 server/core/rule-engine.js 第94-104行：

| scope（代码常量） | 含义 | 消费场景 | 使用什么提示词 | 使用什么规则 | 使用什么模板 |

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

| identify | 识别规则 | 对象识别（Identify面板） | prompt_type='identify' | scope='identify' 的规则 | item_type 列表 |

| create | 创建规则（验证+处理） | 对象创建（Create面板） | prompt_type='creation' | scope='create' 的规则 | llm_fields/auto_fields 分类 |

| create_pre | 创建前预处理 | 编号生成、默认值填充 | 不使用LLM（action_script执行） | scope='create_pre' 的规则 | 编号序列、默认值 |

| create_post | 创建后处理 | 关联对象创建、通知 | 不使用LLM（action_script执行） | scope='create_post' 的规则 | relationships |

| repair | 修复规则 | 数据修复（Repair面板） | prompt_type='repair' | scope='repair' 的规则 | 模板字段定义 |

| optimize | 优化规则 | 数据优化（Optimize面板） | prompt_type='optimize' | scope='optimize' 的规则 | 模板字段定义 |

| compare | 比对规则 | 版本比对（Compare面板） | prompt_type='compare' | scope='compare' 的规则 | 模板字段定义 |

| validate | 验证规则 | 数据验证（Validate面板） | 不使用LLM | scope='validate' 的规则 | 属性定义（data_type/length/pattern） |

| transform | 转换规则 | 数据转换 | 不使用LLM | scope='transform' 的规则 | - |

⚠️ 文档v3.0与代码差异：文档中提到的 scope='assemble' 在代码中不存在。实际代码中组装逻辑使用的是 sciot_rules（旧表），而非规则引擎的 scope 体系。Assemble 场景的规则复用应该通过 scope='create' + scope='validate' 组合实现。

关键理解：创建和组装虽然是两个操作，但共享同一套创建提示词。区别在于：创建侧重字段验证，组装侧重 AML XML 结构的正确性。create_pre 和 create_post 是代码执行规则（action_script），不调用 LLM。

3.5 配置的维护方式

所有配置的维护通过统一的 REST API 完成：

`

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

│ 统一配置管理入口 │

│ │

│ 规则维护：POST/GET/PUT/DELETE /api/rule-engine/rules │

│ 模板维护：POST /api/aml/sciot/update-template-fields │

│ 提示词预生成：POST /api/rule-engine/pregenerate-prompt │

│ 批量操作：POST /api/rule-engine/rules/batch-toggle │

│ │

│ 前端界面：RulesAndTemplates.vue（7个Tab页） │

│ Tab3: 在线规则引擎 → 规则 CRUD │

│ Tab6: 模板库 → 字段分类调整 │

│ Tab4: 对象提示词 → 提示词查看 │

│ Tab7: AML组装 → 组装测试 │

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

`

4. 预生成层：提示词的可重复生成机制

4.1 预生成的确定性保证

提示词不是AI生成的，而是确定性脚本拼接生成的。这意味着：

| 特性 | 说明 |

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

| 可重复 | 相同输入（相同规则+模板+属性）→ 相同输出 |

| 可验证 | 生成结果可被diff，确认修改是否达到预期 |

| 可重建 | 删除所有提示词后，运行预生成即可完全恢复 |

| 可追溯 | 提示词内容来源于哪些规则/模板/属性，完全可追溯 |

4.2 预生成流程

`

POST /api/rule-engine/pregenerate-prompt

{

"item_type_name": "Part",

"prompt_type": "creation" // creation/identify/repair/optimize/compare

}

内部流程：

1. 查询 sciot_item_types → 获取对象类基本信息
2. 查询 sciot_properties → 获取所有属性列表
3. 查询 sciot_templates → 获取 llm_fields / auto_fields 分类

★ v3.4: 同时获取 generation_rules（item_properties + child_objects）

1. 查询 sciot_rules_v2 → 获取 scope=prompt_type 的规则
2. 查询 sciot_relationships → 获取对象关系（影响嵌套结构）
3. 查询 sciot_sequences → 获取编号规则
4. 查询 sciot_methods → 获取客户端方法列表
5. ★ v3.4: 动态生成 item_properties 提示

• 从 generation_rules.item_properties 读取配置
• 生成【Item 类型属性说明】段落（字段名、目标类型、必选/可选、LLM字段、自动字段）
• 生成【必须/可选生成的关联子对象（relationships）】段落
• 强调 item_properties ≠ relationships 的放置规则

1. 拼接为结构化提示词文本
2. UPSERT 到 prompt_templates 表

结果：

prompt_templates 表中新增/更新一条记录

{ id, name, content, prompt_type, item_type_name, version, ... }

`

4.3 预生成的触发方式

| 方式 | 接口 | 说明 |

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

| 单个对象预生成 | POST /api/rule-engine/pregenerate-prompt | 指定 item_type_name + prompt_type（默认 'creation'） |

| 批量预生成 | POST /api/rule-engine/pregenerate-prompt/batch | 对所有 ItemType 生成 creation 类型提示词 |

| 重建所有提示词 | 删除 prompt_templates 表数据 → 批量预生成 | 完全重建 |

⚠️ 文档v3.0中提到的 POST /api/rule-engine/pregenerate-all 不存在。实际批量预生成接口是 POST /api/rule-engine/pregenerate-prompt/batch（server/routes/rule-engine.js 第457行），且当前只支持 creation 类型，不支持为所有 prompt_type 批量生成。

4.4 提示词的层次结构

`

业务系统级 (sciot_business_prompts)

├── 系统上下文: 业务系统概述、目标、范围

├── 核心对象: 主要ItemType列表及描述

├── 对象详情: 每个对象的属性、生命周期、关系

└── 约束条件: 数据约束、业务规则、系统限制

对象级 (prompt_templates)

├── 按 prompt_type 分类: creation / identify / repair / optimize / compare

├── 按 item_type_name 分类: Part / ECR / Vendor / Document / ...

└── 按 version 版本化: 支持 A/B 测试和回滚

`

4.5 预生成后的验证

`

预生成完成 → 查看提示词内容 → 人工/自动验证：

├── 检查字段列表是否完整（对比 sciot_properties）

├── 检查规则是否正确反映（对比 sciot_rules_v2）

├── 检查关系是否包含（对比 sciot_relationships）

└── 在对应消费场景中测试（创建/组装/修复/优化/比对）

验证不通过 → 修改规则/模板 → 重新预生成 → 再次验证

`

5. 消费层：六大场景如何使用配置

5.1 场景与配置的对应关系总览

`

读取什么？

场景 ──────────┬──────────

│

┌────────────────┼────────────────┐

▼ ▼ ▼

提示词 规则 模板

(prompt_ (sciot_ (sciot_

templates) rules_v2) templates)

具体对应（基于实际代码 v3.4）：

Create → creation提示词 + ★ 前端 sanitizeProperties() 自验证 + llm/auto字段分类 + ★ 前端 buildAML() 自组装

★ v3.4: 提示词含 item_properties 动态说明，前端用 generation_rules.item_properties 判断预创建

Assemble → creation提示词 + sciot_rules旧表规则(⚠️) + generation_rules + relationships

Repair → repair提示词 + repair规则 + 模板字段定义

Optimize → optimize提示词 + optimize规则 + 模板字段定义

Compare → compare提示词 + compare规则 + 模板字段定义

Identify → identify提示词 + identify规则 + item_type列表

`

⚠️ Assemble 场景的特殊性：AML组装引擎（server/aml-assembly-engine.js）直接查询 sciot_rules（旧表），不通过规则引擎的 sciot_rules_v2。这是两套规则表并存问题的核心体现。

★ v3.2 Create 场景架构变更：Create 不再通过后端规则引擎的 create/validate/create_pre/create_post scope 执行。改为前端自主完成：字段修正（sanitizeProperties）→ AML组装（buildAML）→ SCSAI提交（_SCSAIApiRequest）。规则引擎的 create 相关 scope 规则保留，供其他面板使用。

★★ 规则引擎 action_script 说明：action_script 字段存储的是从 SCSAI 客户端 JS 方法分析理解后转化为的规则描述，不是直接可执行的 JS 代码。SCSAI 客户端 JS 与 UI 深度绑定，不能直接 new Function() 执行。正确做法是：前端获取规则定义（condition、action_type、action_config），根据规则自己编写对应的前端逻辑。action_script 仅作为规则意图的参考文档，不作为可执行代码。

5.2 场景一：Create（对象创建）

v3.2 架构演进：Create 场景已从前端调用后端规则引擎（/api/rule-engine/create-item）改为前端自主完成全部业务逻辑——后端只负责 SQLite 数据存取和 SCSAI 透明代理，前端负责字段处理、验证、AML组装和提交。

`

调用链（v3.4 架构）：

前端 Create 面板（StaffCapabilities.vue: runCreate()）

→ Step 1: GET /api/aml/unified/schema/:type → 获取对象Schema（属性定义）

→ Step 2: GET /api/sciot/type-template/:type → 获取模板（关系类型、列表值、序列、generation_rules）

→ Step 3: GET /api/aml/sciot/prompts → 获取预生成的 creation 提示词

→ Step 4: 构建 Prompt（优先用预生成，降级 PromptBuilder 动态拼装）

★ v3.4: Prompt 中动态生成 item_properties 提示（不再硬编码 Project）

→ Step 5: POST /api/llm/chat → 调用大模型生成 JSON

→ Step 6: 解析 LLM JSON，调用 SCSAI Sequence API 获取编号

→ Step 7: 前端完成全部业务逻辑：

7.1 sanitizeProperties() → 字段修正（类型检查、list值修正）

7.2 自动检测 item/foreign 字段 → 从 typeTemplate.properties 识别 data_type=item/foreign

★ v3.4: 使用 generation_rules.item_properties 配置

判断 is_mandatory（即使 is_required=0 也强制创建）

7.3 分离 item_properties → 区分"需预创建"（item/foreign 必填/mandatory）

和"可内联"（LLM 返回的非 item/foreign item_properties）

7.4 _SCSAIApiRequest() → 预创建嵌套 Item（如 WBS Element），获取 ID

预创建成功后以 action='get' 格式注入 itemPropertiesToBuild

7.5 补充 item/foreign 默认值 → 填充模板定义的 default_value（必填字段）

7.6 buildAML() → 前端 AMLBuilder 组装完整 AML

★ item_properties →

★ relationships → ...

7.7 _SCSAIApiRequest() → 通过 SCSAI 代理提交 AML

→ 冲突重试：LLM 修正字段 → buildAML() → _SCSAIApiRequest()

使用的配置（从前端通过 API 获取）：

提示词: prompt_templates WHERE prompt_type='creation' AND item_type_name='Part'

（通过 /api/aml/sciot/prompts 获取）

★ v3.4: 提示词中包含动态生成的 item_properties 和 child_objects 说明

模板: sciot_templates（通过 /api/sciot/type-template/:type 获取）

llm_fields / auto_fields / required_fields / generation_rules

★ v3.4: generation_rules.item_properties 驱动 item/foreign 字段的预创建判断

规则: 不再通过规则引擎执行，改为前端 sanitizeProperties() 做字段级修正

（类型检查、list值验证、color格式修正等）

关键前端模块：

src/utils/rule-validator.js → sanitizeProperties(), validateProperties(), buildPropDefMap()

src/utils/AmlBuilder.js → buildAML(), AMLBuilder 类（支持 item_properties add/get 双模式）

src/utils/PromptBuilder.js → ★ v3.4: buildCreationPrompt() 动态识别 item/foreign 字段

src/utils/SCSAI.js → _SCSAIApiRequest() SCSAI 代理

`

5.3 场景二：Assemble（AML组装）

`

调用链：

前端 AML组装面板 / API

→ POST /api/aml/assemble

→ AMLEngine.assemble(itemType, fieldsData)

→ getItemTypeContext(itemTypeName) // server/aml-assembly-engine.js 第64行

├── sciot_templates（模板字段分类） // 第69行

├── sciot_properties（属性定义） // 第73行

├── sciot_rules（旧表，非 sciot_rules_v2） // 第83行 ⚠️

├── prompt_templates（提示词） // 第92行

└── generation_rules（子对象/嵌套配置） // 第101行

→ 验证 required_fields

→ 填充系统字段（id, created_on, ...）

→ 处理嵌套关系（根据 generation_rules.child_objects）

→ 构建 AML XML

使用的配置：

提示词: prompt_templates WHERE prompt_type='creation' AND item_type_name='Part'

规则: sciot_rules WHERE item_type_name='Part'（⚠️ 当前用旧表，字段：rule_type/property_name/data_type/rule_pattern/description/severity/category）

模板: sciot_templates（完整行数据，含 llm_fields/auto_fields/required_fields/generation_rules）

⚠️ 组装失败排查：

如果组装结果不正确 → 首先检查模板定义（llm_fields/auto_fields/required_fields）

→ 然后检查规则定义（sciot_rules 旧表，需确认旧表中是否有该ItemType的规则）

→ 修改配置 → 重新预生成提示词 → 重试组装

⚠️ 架构债务：AMLEngine 使用 db.exec() 方式查询（非 prepared statement），存在 SQL 注入风险。

`

5.4 场景三：Repair（数据修复）

`

调用链：

前端 Repair 面板

→ POST /api/rule-engine/repair

→ executeIdentify() 先识别问题

→ 加载 scope='repair' 规则

→ 执行修复动作（regenerate_number / generate_name / normalize）

→ 需要LLM时，加载 prompt_type='repair' 提示词

→ 可选：写入 SCSAI

使用的配置：

提示词: prompt_templates WHERE prompt_type='repair' AND item_type_name='Part'

规则: sciot_rules_v2 WHERE scope='repair' AND item_type_name='Part'

模板: sciot_templates 字段定义（知道哪些字段可能有问题）

`

5.5 场景四：Optimize（数据优化）

`

调用链：

前端 Optimize 面板

→ POST /api/rule-engine/optimize

→ 加载 scope='optimize' 规则

→ 按优先级排序优化建议

→ 需要LLM时，加载 prompt_type='optimize' 提示词

使用的配置：

提示词: prompt_templates WHERE prompt_type='optimize' AND item_type_name='Part'

规则: sciot_rules_v2 WHERE scope='optimize' AND item_type_name='Part'

`

5.6 场景五：Compare（差异比对）

`

调用链：

前端 Compare 面板

→ POST /api/rule-engine/compare

→ 字段级 diff 计算

→ 加载 scope='compare' 规则

→ 可选：LLM 影响分析（加载 prompt_type='compare' 提示词）

使用的配置：

提示词: prompt_templates WHERE prompt_type='compare' AND item_type_name='Part'

规则: sciot_rules_v2 WHERE scope='compare' AND item_type_name='Part'

`

5.7 场景六：Identify（对象识别）

`

调用链：

前端 Identify 面板

→ POST /api/rule-engine/identify

→ 加载 scope='identify' 规则

→ 根据 query_type 执行查询

→ 应用 result_transformer

→ 报告类型自动调用 LLM

使用的配置：

提示词: prompt_templates WHERE prompt_type='identify' AND item_type_name='Part'

规则: sciot_rules_v2 WHERE scope='identify' AND item_type_name='Part'

`

5.8 LLMBrain 双路径提示词加载

`

llmBrain._loadPromptFromRuleEngine(scope, context)

│

├── 路径1: 从规则引擎 prompt_templates 表加载 ✅ 推荐

│ → SELECT content FROM prompt_templates

│ WHERE prompt_type = scope AND item_type_name = context.itemType

│

└── 路径2: 降级到硬编码提示词 ⚠️ 过渡方案

→ 规则引擎无匹配时使用函数内置模板

→ 这是当前业务数字员工的主要工作方式

→ P2 重构目标：全部迁移到路径1

`

6. 统一API与管理界面

6.1 API总览：两条路由，统一入口

`

所有配置访问通过两条路由完成：

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

│ 路由1: /api/rule-engine/* — 规则引擎（规则CRUD + 执行 + 预生成）│

│ 路由2: /api/aml/sciot/* — SCIOT数据（模板 + 提示词 + 属性） │

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

`

6.2 规则引擎API（/api/rule-engine/*）

规则CRUD：

| 方法 | 路由 | 功能 |

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

| GET | /api/rule-engine/rules | 获取规则列表 (scope/item_type/severity筛选) |

| GET | /api/rule-engine/rules/:id | 获取单条规则 |

| POST | /api/rule-engine/rules | 创建/更新规则 |

| PUT | /api/rule-engine/rules/:id | 更新规则 |

| DELETE | /api/rule-engine/rules/:id | 删除规则 |

| POST | /api/rule-engine/rules/batch-toggle | 批量启用/禁用 |

| POST | /api/rule-engine/rules/batch-delete | 批量删除 |

规则执行：

| 方法 | 路由 | 功能 |

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

| POST | /api/rule-engine/execute/:scope | 执行指定范围的规则 |

| POST | /api/rule-engine/identify | 识别对象 |

| POST | /api/rule-engine/validate | 验证对象 |

| POST | /api/rule-engine/repair | 修复对象 |

| POST | /api/rule-engine/optimize | 优化对象 |

| POST | /api/rule-engine/compare | 比对对象 |

提示词预生成：

| 方法 | 路由 | 功能 |

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

| POST | /api/rule-engine/pregenerate-prompt | 为指定对象类预生成提示词 |

| POST | /api/rule-engine/pregenerate-all | 批量预生成所有提示词 |

导入导出和统计：

| 方法 | 路由 | 功能 |

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

| POST | /api/rule-engine/import/aml | 从AML导入规则 |

| POST | /api/rule-engine/import/json | 从JSON导入规则 |

| POST | /api/rule-engine/export/json | 导出规则为JSON |

| GET | /api/rule-engine/stats | 规则统计 |

| GET | /api/rule-engine/history | 执行历史 |

| POST | /api/rule-engine/cache/clear | 清除缓存 |

6.3 SCIOT数据API（/api/aml/sciot/*）

6.4 前端界面

RulesAndTemplates.vue（2450行）— 7个Tab页：

| Tab | 名称 | 功能 | 对应的后端API |

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

| 1 | 巡检规则 | 模型/实例规则管理 | /api/aml/inspect/* |

| 2 | SCIOT规则 | 导入的原始规则浏览 | /api/aml/sciot/rules |

| 3 | 在线规则引擎 | ★ 规则CRUD、筛选、启用禁用 | /api/rule-engine/rules |

| 4 | 对象提示词 | 对象级system/user prompt | /api/aml/sciot/prompts |

| 5 | 业务提示词 | 46个业务系统提示词 | /api/aml/sciot/business-prompts |

| 6 | 模板库 | ★ 字段分类(LLM/Auto/System) | /api/aml/sciot/templates |

| 7 | AML组装 | LLM输出→标准AML | /api/aml/assemble |

StaffCapabilities.vue（3600+行）— 6大基础能力面板：

| 面板 | 对应场景 | API调用 | 架构说明 |

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

| 识别 | Identify | POST /api/rule-engine/identify | 通过规则引擎执行 |

| 创建 | Create | GET /api/aml/unified/schema/:type + GET /api/sciot/type-template/:type + GET /api/aml/sciot/prompts + POST /api/llm/chat → 前端 buildAML() 组装 → SCSAI 代理提交 | ★ v3.2 前端自组装，不调后端规则引擎 |

| 修复 | Repair | POST /api/rule-engine/repair | 通过规则引擎执行 |

| 优化 | Optimize | POST /api/rule-engine/optimize | 通过规则引擎执行 |

| 比对 | Compare | POST /api/rule-engine/compare | 通过规则引擎执行 |

| 生成 | Generate | 报告/文档生成 | 独立生成流程 |

6.5 前端Composable：useRuleEngine.js

`javascript

// src/composables/useRuleEngine.js (498行)

{

// 规则CRUD

getRules(params), getRule(id), saveRule(rule), deleteRule(id),

batchToggle(ids, isActive), batchDelete(ids),

// 规则执行

execute(scope, context, options),

identify(text, context),

validate(itemType, data),

repair(itemType, data, itemId),

optimize(itemType, data, itemId),

compare(itemType, dataA, dataB),

// 导入导出

importFromAML(amlContent, options),

importFromJSON(rules),

exportToJSON(scope, itemType),

// 统计

getStats(), getHistory(params), getScopes(),

clearCache(), getCacheStats()

}

`

7. 问题定位与修复指南

核心原则：生成基本没问题，组装出问题 → 很可能是规则模板定义不对 → 调整规则模板 → 重新预生成提示词 → 重试验证。

7.1 标准排障流程

`

问题发现（某个场景表现异常）

│

▼

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

│ 步骤1: 确认问题范围 │

│ · 是所有对象类都有问题，还是特定对象类？ │

│ · 是所有场景都有问题，还是特定场景？ │

│ → 如果所有对象类都有问题 → 检查通用规则/预生成逻辑 │

│ → 如果特定对象类有问题 → 检查该对象类的规则/模板/提示词 │

│ → 如果特定场景有问题 → 检查该 scope 的规则 │

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

│

▼

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

│ 步骤2: 逐层检查（从上往下） │

│ │

│ Layer 4: 检查提示词是否正确 │

│ GET /api/aml/sciot/prompts/:type │

│ 查看 prompt_templates 表中对应的 content │

│ → 提示词内容是否完整？字段列表是否齐全？ │

│ → 提示词是否与当前规则模板一致？ │

│ │

│ Layer 3: 检查规则定义是否正确 │

│ GET /api/rule-engine/rules?scope=xxx&item_type_name=xxx │

│ → 规则条件是否正确？ │

│ → 规则优先级是否合理？ │

│ → 规则动作类型是否正确？ │

│ │

│ Layer 2: 检查模板定义是否正确 │

│ GET /api/aml/sciot/templates/:type │

│ → llm_fields / auto_fields 分类是否正确？ │

│ → required_fields 是否完整？ │

│ → generation_rules 是否合理？ │

│ │

│ Layer 1: 检查AML基础数据是否正确 │

│ GET /api/aml/sciot/types → 确认对象类存在 │

│ → 检查 sciot_properties 属性定义 │

│ → 检查 sciot_relationships 关系定义 │

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

│

▼

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

│ 步骤3: 定位并修复 │

│ │

│ 如果是提示词问题（Layer 4）: │

│ → 提示词是预生成的产物，重新预生成即可 │

│ → POST /api/rule-engine/pregenerate-prompt │

│ │

│ 如果是规则问题（Layer 3）: │

│ → 在 RulesAndTemplates.vue Tab3 在线规则引擎中修改 │

│ → 修改后重新预生成提示词 │

│ │

│ 如果是模板问题（Layer 2）: │

│ → 在 RulesAndTemplates.vue Tab6 模板库中调整字段分类 │

│ → POST /api/aml/sciot/update-template-fields │

│ → 修改后重新预生成提示词 │

│ │

│ 如果是AML基础数据问题（Layer 1）: │

│ → 检查原始AML文件是否正确 │

│ → 重新运行 import-aml-v2.js 导入 │

│ → 导入后重新预生成所有提示词 │

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

│

▼

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

│ 步骤4: 验证修复 │

│ │

│ 1. 重新预生成提示词 │

│ 2. 在对应场景面板中重试操作 │

│ 3. 检查执行历史: GET /api/rule-engine/history │

│ 4. 确认问题解决后，更新文档记录 │

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

`

7.2 常见问题速查表

7.3 整体重建流程

当需要完全重建规则模板提示词体系时：

`

1. 确认 AML 文件正确（SCIOT/*.xml 636个文件）

1. 重新导入 AML

node scripts/import-aml-v2.js

1. 验证基础数据

GET /api/aml/sciot/types → 确认对象类列表完整

GET /api/aml/sciot/templates → 确认模板已导入

1. 检查并调整模板字段分类

GET /api/aml/sciot/templates/:type → 逐个检查

POST /api/aml/sciot/update-template-fields → 调整

1. 批量预生成所有提示词

POST /api/rule-engine/pregenerate-all

1. 验证提示词

GET /api/aml/sciot/prompts → 确认所有对象类都有提示词

1. 在六大场景中逐个测试

创建 → 组装 → 修复 → 优化 → 比对 → 识别

1. 标记版本

更新 prompt_templates.version

`

7.4 执行历史监控

通过 sciot_rule_history 表追踪规则执行效果：

`sql

-- 规则命中率

SELECT rule_id, COUNT(*) as exec_count,

SUM(CASE WHEN llm_called = 1 THEN 1 ELSE 0 END) as llm_count

FROM sciot_rule_history

WHERE executed_at > datetime('now', '-7 days')

GROUP BY rule_id;

-- 高误报率规则（需要调整）

SELECT r.name, r.hit_count, r.avg_duration_ms, r.user_correction_count

FROM sciot_rules_v2 r

WHERE r.user_correction_count > 0

ORDER BY r.user_correction_count DESC;

`

9. 巡检、自愈与持续优化

9.0 数据清洗事件记录（2026-05-31）

事件等级：🔴 严重 — 数据结构根本性错误，自增强循环

#### 问题发现

在对 sciot_templates 和 prompt_templates 表进行数据质量审计时，发现 item_type_name 字段存在异常值。正常情况下，该字段应包含对象类名（如 Part、Project、ECR），但实际数据中混入了大量属性名（如 created_on、item_number、name）。

#### 根因分析

经过完整溯源，确定根本原因是一个自增强错误循环：

`

① 源头污染：generated/sciot-index-auto.json

该文件由自动化脚本生成，错误地将 113 个属性名（Property name）

标记为 ItemType（对象类），而非正确的 30 个 ItemType。

② 传播路径：import-aml-v2.js → sciot_item_types 表

导入脚本读取 sciot-index-auto.json 建立 ItemType 索引，

导致 113 个错误条目被写入 sciot_item_types 表。

③ 自增强循环：

sciot_item_types 有错 → 基于它生成的模板/提示词也错

→ 错误数据被当作正确的 ItemType 使用

→ 后续生成操作继续基于错误数据 → 污染扩散

④ 污染范围：

• sciot_item_types: 143 个条目（30 正确 + 113 错误属性名）
• sciot_templates: 创建了针对属性名的模板记录
• prompt_templates: 生成了针对属性名的 creation 提示词

`

#### 修复过程

| 步骤 | 操作 | 脚本/工具 |

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

| 1 | 识别污染数据 | 手动 SQL 查询 sciot_item_types |

| 2 | 交叉验证 | 对比 AML 文件中的 ItemType 定义 |

| 3 | 清理错误 ItemType | scripts/clean-dirty-item-types.js — 删除 113 条错误记录，保留 30 条正确记录 |

| 4 | 清理关联数据 | 删除 sciot_templates 和 prompt_templates 中引用错误 ItemType 的记录 |

| 5 | 重建 creation 提示词 | scripts/regenerate-creation-prompts.js — 基于正确的 30 个 ItemType 重新生成 |

| 6 | 验证修复结果 | scripts/deep-check.js 和 scripts/final-verify.js — 全库交叉校验 |

#### 修复后状态

| 指标 | 修复前 | 修复后 |

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

| sciot_item_types 条目 | 143 | 30 |

| sciot_templates 条目 | ~140 | ~30 |

| prompt_templates (creation) 条目 | ~140 | ~30 |

| 错误属性名 ItemType | 113 | 0 |

#### 教训与预防

1. 源头校验：import-aml-v2.js 应在导入时校验 ItemType 定义来源（仅接受 AML ItemType 定义，不接受属性名）
2. 生成脚本审计：sciot-index-auto.json 生成逻辑需要增加 ItemType/Property 区分校验
3. 定期数据质量巡检：应将 ItemType 数量与 AML 文件 ItemType 数量交叉比对纳入 DS-SYS-001 巡检
4. 文档记录：所有数据修复操作应有完整记录（本次修复已完成）

9.1 系统巡检（DS-SYS-001）

9.2 系统巡检（DS-SYS-001）

数字员工"系统运维师"每2小时执行一次系统健康检查：

`

runSystemHealth()

├── 0. 自愈: 清除卡死的互斥锁

├── 1. 数据库检查 (模板/规则/提示词数量)

├── 2. SCSAI连接检查

├── 3. 模板覆盖率检查

├── 4. 创建历史检查

├── 5. 方法健康检查 (含安全审计)

├── 6. 数字员工自身状态 + 自修复

├── 7. AI对象模型巡检 (P0优先) + 自动修复

├── 8. 自愈: 日志文件轮转 (>5MB截断)

└── 9. 自愈: 补回缺失的默认员工

`

9.3 提示词A/B测试

通过 prompt_templates 表的 parent_id 和 score 字段支持：

`

创建A版本 → parent_id=null, score=0

创建B版本 → parent_id=A版本id, score=0

运行测试 → 分别记录使用次数和得分

比较结果 → 高分版本标记为 active，低分版本标记为 deprecated

`

9.4 规则自优化（规划中）

`

执行历史分析

↓

识别高误报率规则 (user_correction_count > threshold)

↓

自动调整规则优先级或禁用

↓

生成优化建议报告

`

10. 实现状态与优化路线

10.1 当前实现状态

10.2 已知架构问题

10.3 优化路线

#### P0 - 已完成 ✅

1. StaffCapabilities.vue 对接规则引擎API ✅
2. RulesAndTemplates.vue 在线规则引擎 ✅
3. llm-brain.js 规则引擎初始化 ✅
4. server.js 规则引擎路由完善 ✅

#### P1 - 核心能力增强（建议近期完成）

1. 统一两套规则表（废弃 sciot_rules，全部迁移到 sciot_rules_v2）

• 影响文件：aml-assembly-engine.js、staff-manager.js、SCSAI-tools.js、server.js

1. AMLEngine 消费规则引擎（替换 db.exec() 为规则引擎 getRules()）
2. 完善执行历史记录
3. 前端识别视图扩展（query_type切换）

#### P2 - 架构重构

1. llm-brain.js 重构（消除硬编码兜底）
2. 创建 SciotDatabase 统一访问入口（替代各处独立 createDatabase 调用）
3. 数字员工表迁移到 bossagents.db
4. 预生成扩展：支持 repair/optimize/compare/identify 类型
5. SQL 注入修复：AMLEngine 改用 prepared statement

#### P3 - 高级特性

1. 规则自进化分析引擎
2. 提示词A/B测试UI
3. 规则测试沙箱

11. 附录：文件清单与API索引

11.0 文档与代码一致性校验清单

v3.2 更新：以下清单用于每次更新文档后验证文档描述与代码实现的一致性。

| # | 校验项 | 文档描述 | 代码实际 | 一致？ |

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

| 1 | 规则引擎核心表 | sciot_rules_v2 | server/core/rule-engine.js:175 CREATE TABLE sciot_rules_v2 | ✅ |

| 2 | 提示词表 | prompt_templates | server/core/rule-engine.js:151 CREATE TABLE prompt_templates | ✅ |

| 3 | 批量预生成接口 | POST /api/rule-engine/pregenerate-prompt/batch | server/routes/rule-engine.js:457 | ✅ |

| 4 | Scope 常量 | identify/create/create_pre/create_post/repair/optimize/compare/validate/transform | server/core/rule-engine.js:94-104 RULE_SCOPES | ✅ |

| 5 | AMLEngine 使用的规则表 | sciot_rules（旧表） | server/aml-assembly-engine.js:83 | ⚠️ 待迁移 |

| 6 | staff-manager 使用的规则表 | sciot_rules（旧表） | server/digital-staff/staff-manager.js:242 | ⚠️ 待迁移 |

| 7 | SCSAI-tools 使用的规则表 | sciot_rules（旧表） | server/utils/SCSAI-tools.js:84 | ⚠️ 待迁移 |

| 8 | server.js 健康检查规则统计 | sciot_rules（旧表） | server.js:2014 | ⚠️ 待迁移 |

| 9 | 数据库连接方式 | sqlite-compat Map缓存（共享单例） | server/sqlite-compat.js:52-53 _instances Map | ✅ |

| 10 | 内置规则数量 | 13条 | server/core/rule-engine.js:284-544 _loadBuiltinRules() | ✅ |

| 11 | 预生成 prompt_type 支持 | 仅 creation | server/routes/rule-engine.js:271 默认 'creation' | ⚠️ 文档说明不足 |

| 12 | AMLEngine SQL 查询方式 | db.exec() 字符串拼接 | server/aml-assembly-engine.js:69/73/83 | ⚠️ SQL注入风险 |

| 13 | Create面板不再调后端组装 | 前端 buildAML() + _SCSAIApiRequest() | StaffCapabilities.vue:1927 前端自组装AML | ✅ v3.2 |

| 14 | 前端规则验证器 | src/utils/rule-validator.js | sanitizeProperties/validateProperties/buildPropDefMap | ✅ v3.2 新增 |

| 15 | StaffCapabilities 不调 create-item | 无任何 /api/rule-engine/create-item 调用 | 搜索结果：0 matches | ✅ v3.2 |

| 16 | StaffCapabilities 不调 /api/aml/assemble | 无任何 /api/aml/assemble 调用 | 搜索结果：0 matches | ✅ v3.2 |

| 17 | sciot_item_types 数据清洗 | 30 条正确 ItemType，0 条错误属性名 | 清洗后验证 | ✅ v3.3 |

| 18 | ai-inspector 旧表引用 | 8 处全部使用 sciot_rules（旧表） | server/routes/ai-inspector.js:629-674 | ⚠️ v3.3 已审计 |

| 19 | staff-manager 列名 bug | item_type 应为 item_type_name | server/digital-staff/staff-manager.js:242 | ⚠️ v3.3 已发现 |

| 20 | sciot_rules 旧表全代码库引用 | 14+ 处引用已审计 | 见已知问题 #1 | ⚠️ v3.3 已审计 |

| 21 | generation_rules.item_properties | item_properties 配置段存在 | server/routes/rule-engine.js:380-431 动态读取 | ✅ v3.4 |

| 22 | 预生成 Prompt 动态 item_properties | 不再硬编码 Project WBS 提示 | server/routes/rule-engine.js:380-431 (单个) + 583-630 (批量) | ✅ v3.4 |

| 23 | 前端 PromptBuilder item_properties | 动态识别 item/foreign 字段 | src/utils/PromptBuilder.js:125-157 itemPropFields | ✅ v3.4 |

| 24 | 前端 item_properties 预创建判断 | 使用 grItemProps.is_mandatory | StaffCapabilities.vue:1596-1652 grMandatoryItemProps | ✅ v3.4 |

| 25 | builtin-project-create-pre-004 | 使用 item_properties.wbs_id 路径 | server/core/rule-engine.js:496-509 action_script | ✅ v3.4 |

| 26 | AmlBuilder 支持 item_properties get | 前端支持 add/get 双模式 | src/utils/AmlBuilder.js:83-95 | ✅ v3.4 |

| 27 | 服务端 AmlBuilder item_properties | 仅支持 add 模式（服务端不预创建） | server/utils/aml-builder.js:47-55 | ✅ |

11.1 文件清单

11.2 核心API快速索引

11.3 文档阅读指南