BossAgents BossAgents

架构底线与交付验收 SLA

👤 BossAgents 团队 📅 2026-08-30 👁️ 阅读 26 👍 点赞 0 ☕ 56 分钟阅读

架构底线与交付验收 SLA

本文档是 SCSAI PLM / BossAgents 的架构红线与交付验收硬指标的权威声明。

起因：团队复盘《做 Agent 开发 1 年半，接了 20 个商业项目，说点没人说的实话》一文，

文中三条真相（①绝大部分人把 Agent 想简单了，卖的是"踏实"而非技术；②框架≠交付，三道保险 = 强制引用内部文档 / 带来源链接 / 上线前离线跑 300 条坏例率 < 4.7%；③2026 赛道分层，上层拼信用）直击行业痛点。

本文把我们的差异化护城河（三条架构底线）写成可验收、可审计、可代码实证的硬约束，

让"踏实"不是口号，而是每一行代码与每一次验收都能复现的事实。

0. 与帖文三条真相的映射

帖文真相我们的对应底线 / 机制代码实证
① 把 Agent 想简单，卖"踏实"不卖技术对象模型驱动：业务真相源是 PLM 对象类 + AML，Agent 只是编排层，不承载业务真相object-modeling/*、server/routes/agent-loop.js
② 框架≠交付，三道保险 + 离线坏例率闸门量化交付验收闸门：离线跑样本集，坏例率 ≤ 4.7% 才允许约验收server/scripts/acceptance-eval.cjs（exit 0/1 闸门）
② 强制引用内部文档 / 带来源链接SQLite=备份缓存 + 真源回写：所有结果都归因到内部对象类，不凭空生成server/sqlite-compat.js、migrate-sqlite-to-mysql.cjs
③ 上层拼信用兜底纪律"可以笨，不能疯"：绝不伪造、绝不静默判合格、绝不丢字段，规则引擎明牌server/core/offline-rule-fallback.js

1. 三条架构底线（不可动摇）

底线一：对象模型驱动（Object-Model-Driven）

  • 业务真相源是 PLM 对象类（ItemType）与 AML，不是 Agent 的"记忆"或"上下文"。
  • Agent / 数字员工只负责理解意图 → 规则分解 → 生成 AML → 经网关写回对象类；一切可审计、可回放的真相都落在对象模型里。
  • 对象类是可扩展的：44 个 CASC211 类加 QP_ 前缀、质控卡塞 DIAODU/DINGE/BANZU/CHEJIAN_ZHUREN 列、建 JG_PRODUCE_TASK/JG_SD_SBD/JG_WORKING_PROC 等车间执行类——本质就是"按中国业务扩展对象模型"，是常态动作而非越权。
  • 违背此底线的判定：把业务状态写进 Agent 会话、写进纯前端变量、写进非对象类的临时表，且不与 PLM 对象类对齐 → 不允许合并。

底线二：SQLite 仅作备份 / 缓存，MySQL 才是系统记录（SoR）

  • SQLite 的定位：本地磁盘备份库、离线缓存、能力出箱（capability outbox）的暂存，不是系统记录源。
  • 根治版兼容层 server/sqlite-compat.js（2026-07-15，better-sqlite3 + WAL，真磁盘库，单例连接，FAILFAST）替代了旧 sql.js 纯内存库（静默丢数据、幽灵库）。
  • 租户元数据备份 server/services/tenant-db-sqlite-backup.js → data/boss_tenants.db，明确是备份，不是 SoR。
  • 系统记录源（SoR）是 MySQL（migrate-sqlite-to-mysql.cjs 迁移动线；主实例 :5000 / :5001 走 MySQL 引擎）。
  • 违背此底线的判定：把"业务真实数据"只存 SQLite 不回写 MySQL、或宣称 SQLite 是权威库 → 不允许。

底线三：7 能力 + 导入导出 + 复制粘贴 = 业务操作的基础

  • 业务操作不靠"对话生成一段代码"完成，而是落到标准化能力 + 标准化数据搬运三件套：
  1. 7 大基础能力（见 §2）；
  2. 导入导出（CSV / Excel / JSON / XML / txt，覆盖 Part/Document/BOM/Vendor/Manufacturer/Customer/Project/ECO/WorkOrder）；
  3. 复制粘贴（AML 级 buildCopyAml / buildPasteAml，走 /api/SCSAI/copy-paste）。
  • 这三者是"业务操作的基础"，任何数字员工闭环都必须建立在这套底座之上，而非另起炉灶。

2. 7 大基础能力（权威定义，代码实证）

权威口径为 7 项，非旧文档里过时的"五能力 / 六能力"。

| 能力 | 含义 | 代码落点 |

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

| identify | 识别 / 定位对象（含 create 统一创建入口） | server/scripts/health-check.js:147 的 ['identify','validate','repair','optimize','compare','generate','inspect'] |

| validate | 校验对象合规性（规则引擎守卫） | server/core/capability-offline-guard.js:22 的 BASE_CAPABILITIES |

| repair | 修复缺失 / 非法字段 | server/core/offline-rule-fallback.js 的 localFix |

| optimize | 优化（成本 / 供应商集中度 / 规格升级建议） | server/core/offline-rule-fallback.js 的 localOptimize |

| compare | 比对（库存 / 版本 / BOM 差异） | server/core/capability-offline-guard.js |

| generate | 生成（AML / 报表 / 配置） | server/routes/agent-loop.js |

| inspect | 巡检（对象健康度 / 异常扫描） | server/scripts/health-check.js 的 Layer 2 连通性 |

  • 统一创建动作 create 与上述 7 项并列，作为"创建即一种能力"，共 8 个 BASE_CAPABILITIES。
  • 旧 app/routes/swarm.js:49 仅列 6 项（漏 validate/inspect）属过时口径，e2e-business-demo.js:121 已写"7 大能力"，以本文 + health-check.js 为准。

3. 导入导出 + 复制粘贴（代码实证）

能力落点文件关键符号 / 端点
导入导出（前端）src/composables/useImportExport.jsBASE_ITEM_TYPES（Part/Document/BOM/Vendor/Manufacturer/Customer/Project/ECO/WorkOrder）；格式 csv/excel/json/xml/txt
导入导出（后端路由）server/routes/import-export.router.js/api/itemtypes/import/xml、/import/SCSAI、/import/json、/import/batch、/export/xml/:name、/export/json/:name、/export/batch
复制粘贴src/composables/useCopyPasteSave.jsbuildCopyAml / buildPasteAml，API_BASE = '/api/SCSAI/copy-paste'
BOM 导出utils/bom-exporter.jsBOM 树导出

4. 量化交付验收 SLA（硬闸门）

对应帖文"上线前离线跑 300 条坏例率 < 4.7%"。我们把这条落成可重复执行、可 CI 闸门的脚本。

4.1 指标定义

| 指标 | 计算 | 闸门（验收阈值） |

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

| 坏例率 badCaseRate | 坏例数 / 总样本数 × 100% | ≤ 4.7% → 否则 exit 1，不允许约验收 |

| 转人工率 humanHandoffRate | 转人工数 / 总样本数 × 100% | 仅作观测（不强制闸），用于排能力短板 |

| 平均响应时延 latencyMs | 各样本处理耗时均值 | 仅作观测，离线规则引擎通常 < 1ms/样本 |

  • 坏例判定（来自 server/scripts/acceptance-eval.cjs）：
  1. 丢字段：lostFields(input, output) 检测到输出丢失输入既有字段 → 坏例；
  2. 静默判合格：expect.fixOrImprove === true 但产出 total === 0 → 坏例（绝不允许"看起来好了"）；
  3. 其余正常产出 + 干净/空对象期望 no-op → 非坏例。
  • 转人工判定：!bad && total === 0（无坏例但也没自动解决）→ 转人工，不计入坏例。

4.2 执行方式

# 默认 20 条样本（生产扩到 300 条即对应帖文"跑 300 条"）
node server/scripts/acceptance-eval.cjs

# 自定义样本集 / 阈值
ACC_EVAL_SAMPLES=server/scripts/acceptance-samples.json \
ACC_EVAL_THRESHOLD=4.7 \
node server/scripts/acceptance-eval.cjs
  • 样本集：server/scripts/acceptance-samples.json（threshold: 4.7，20 条：F01–F10 fix / O11–O15 optimize / B16–B17 both / P18–P20 干净或空对象期望 no-op）。
  • 生产落地时把样本集扩到 300 条即与帖文口径一致；闸门逻辑不变。

4.3 实测证据（本次交付验证）

✅ 验收通过：坏例率 0.00% ≤ 4.7%，可约验收。   (exit 0)
⏸ 人工 P20 [fix] fixes=0 improve=0   ← 干净对象正确转人工，非坏例
  • 负向验证（临时构造"期望 fix 但 0 产出"样本集）：坏例率 100%、exit 1 → 证明闸门确实能拦住坏例，不是装饰。

5. 兜底纪律（"Agent 可以笨，不能疯"）

规则引擎兜底模块 server/core/offline-rule-fallback.js 顶部纪律，线上与离线验收共用同一份确定性代码：

  1. 绝不伪造 AI 结果：LLM 不可用 / 解析失败时，localFix / localOptimize 返回 ruleBased: true，前端显式打"规则引擎"蓝色徽章，不冒充 AI。
  2. 绝不静默判合格：任何"期望有产出"的样本 0 产出 → 判坏例（见 §4.1）。
  3. 绝不丢字段：输出必须包含输入全部既有字段（lostFields 守卫）。
  4. 可解释：每条 fix/optimize 都带 fixSummary / optimizeSummary 文字说明（如"约 ¥x.xx（含 n 项估算，非采购价）"），让人能审计。

模块抽取目的：把 agent-loop.js 内联规则抽到 server/core/offline-rule-fallback.js，

与 server/scripts/acceptance-eval.cjs 离线闸门共用同一份确定性逻辑 → 线上兜底与验收判定字节级一致，杜绝"线上一套、验收另一套"。

6. 代码实证映射总表（审计用）

底线 / 机制文件关键符号
对象模型驱动server/routes/agent-loop.jsAML 生成 + 网关写回
SQLite=备份缓存server/sqlite-compat.jsbetter-sqlite3 + WAL + 单例 + FAILFAST
SQLite=备份server/services/tenant-db-sqlite-backup.jsdata/boss_tenants.db
SoR=MySQLmigrate-sqlite-to-mysql.cjsETL 迁移动线
7 能力server/scripts/health-check.js:1477 项能力数组
8 能力（含 create）server/core/capability-offline-guard.js:22BASE_CAPABILITIES
导入导出src/composables/useImportExport.js server/routes/import-export.router.jsBASE_ITEM_TYPES / /import·/export
复制粘贴src/composables/useCopyPasteSave.jsbuildCopyAml/buildPasteAml /api/SCSAI/copy-paste
交付验收闸门server/scripts/acceptance-eval.cjs坏例率 ≤ 4.7% → exit 0/1
样本集server/scripts/acceptance-samples.jsonthreshold: 4.7
兜底纪律server/core/offline-rule-fallback.jslocalFix/localOptimize/estimateUnitCost

7. 验收检查清单（PR / 发版前必过）

  • [ ] 业务真相落在 PLM 对象类 + AML，无"仅存 Agent 会话 / 纯前端变量"的真相源（底线一）
  • [ ] 真实数据回写 MySQL，SQLite 仅用于备份 / 缓存（底线二）
  • [ ] 业务操作基于 7 能力 + 导入导出 + 复制粘贴底座，未另起炉灶（底线三）
  • [ ] node server/scripts/acceptance-eval.cjs 跑通，坏例率 ≤ 4.7%，exit 0（否则阻断）
  • [ ] LLM 失败路径返回 ruleBased: true，无伪造、无静默判合格、无丢字段（纪律）
  • [ ] 负向样本集能触发 exit 1（闸门有效，非常设绿灯）

本文档与 server/scripts/acceptance-eval.cjs、server/core/offline-rule-fallback.js 同步维护；任何一条底线被突破，视为架构级回归，必须回滚或重做。

← 返回案例列表
分享：
🤖 Try Now →
🤖
🎁