bossagents 六维能力「一条线·一个面」现状与统一方案

文档日期：2026-07-09

目的：在动手收敛之前，先把现状彻底写清楚（哪些实现存在、谁在调用、哪些冗余、统一后保留什么、删什么、怎么实现与验证）。

原则：先写文档、再保留核心、删冗余、最后基于统一方案实现并真实验证。

一、核心结论（TL;DR）

1. 之前把 create 钻错了路：CapabilityRuntime.create 走的是 rule-engine.js 的 createItem，它用本地 sciot_sequences 表（空表）生成编号 → 永远失败。而真正的 unified 创建组件 server/routes/unified-create.js 早就在用 SCSAI 真实 Sequence 编号，Digital Staff/对话入口一直在用它。
2. 整条线实际是「两套后端 + 分叉前端」：

• 后端 create 核心有两套：unified-create.js（✅ 正确）vs rule-engine.createItem（❌ 死路）。
• 6 大能力（identify/repair/optimize/compare/generate/create）散落在两套后端：CapabilityRuntime（前 5 个）+ capability-pipeline + unified-create（create）。
• 前端 create 也有两套：useCapabilityCreate.js（✅ 对话/AiCapabilityBar）vs useCreate.js（❌ ItemTypeManagement 老路，有嵌套 bug）。

1. server.js 里 4 条能力/创建路由并存（/api/unified/、/api/pipeline/execute、/api/capability/pipeline/、/api/capability/），加上 app/routes/capability.js 又挂了一个 /api/capability/*，存在路由竞争。
2. 统一方向：所有 create 入口收敛到 unified-create.js；规则引擎只做 create_pre 校验/去重（可选预检）；5 个非创建能力继续走 CapabilityRuntime（已实测 success）。前端业务页老路 useCreate.js 废弃，迁到 useCapabilityCreate.js。

二、现状架构全景

2.1 后端能力/创建路由（server.js 内并存 4 条）

| 路径前缀 | 处理器 | 实现文件 | 用途 | 现状 |

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

| /api/unified/ | handleUnifiedRoute | server/routes/unified-create.js | 前端 useCapabilityCreate + 小程序/移动端 create 后端 | ✅ 正确核心 |

| /api/pipeline/execute | CapabilityDispatcher.execute | server/core/capability-dispatcher.js → CapabilityRuntime | Unified entry for web business pages (hardcoded) | ⚠️ create goes the wrong way |

| /api/capability/pipeline/ | handlePipelineRoute | server/routes/capability-pipeline.js | Digital employee pipeline (identify-intent/execute) | ✅ Uses unified-create |

| /api/capability/ | handleCapabilityRequest | server/routes/capability-api.js | Legacy Capability API (duplicate identify definitions, etc.) | ❌ Dead code/duplicate |

| /api/capability/* (another location) | app/routes/capability.js → CapabilityDispatcher | Mounted via router.js L65 | Capability entry for web business pages | ⚠️ Competes with the same prefix in server.js |

Route competition: /api/capability/ is matched by both capability-api.js in server.js and app/routes/capability.js, requiring a clear single owner.

2.2 Comparison of Two create Backend Implementations

2.3 Distribution of the 6 capabilities (scattered across two backends)

2.4 Frontend entry divergence

3. Root Causes Fixed (During This Investigation)

• Rule engine db not mounted: UnifiedRuleEngine constructor expects {db}, but all callers pass bare db → this.db is always null → the rule engine idles throughout and relies on LLM fallback. The constructor has been updated to accept both parameter forms (server/core/rule-engine.js L228). This fix lets the 5 non-creation capabilities actually take effect through the rule engine (verify script confirmed success).
• Field contract normalization: CapabilityDispatcher.normalizeParams now maps frontend description→intent and passes through selected_ids; for compare, selected_ids[0/1]→item_a/item_b; CapabilityRuntime._resolveSelectedData uniformly pulls selected objects from SCSAI and fills them into data.

4. Retention List (User instruction: keep these, delete the rest)

✅ Keep

1. Frontend create suite: src/composables/useCapabilityCreate.js and its dependencies (src/utils/AmlBuilder.js, src/utils/PromptBuilder.js, src/utils/rule-validator.js).
2. Verification script: verify-capability-line.mjs (root directory, connects directly to real SCSAI to verify 6 capabilities).
3. unified-create.js suite: server/routes/unified-create.js (including its exported functions reused by capability-pipeline.js).
4. Digital employee pipeline (depends on unified-create): server/routes/capability-pipeline.js.
5. 5 non-creation capabilities (verified success via CapabilityRuntime): keep the repair/optimize/compare/generate/identify implementations in CapabilityRuntime, and the unified entry point CapabilityDispatcher.
6. Rule engine (revived by this fix): server/core/rule-engine.js, used only for create_pre validation/deduplication (optional pre-check) and the 5 capabilities.

🗑️ To be deleted (redundant/dead-end/competing, suggested list)

| Deletion Item | File/Location | Reason | Risk |

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

| Dead-end create implementation | createItem in rule-engine.js (from L2806) | Uses empty sciot_sequences, always fails | Low (no one uses it after CapabilityRuntime.create switched to unified-create) |

| Old Capability API | server/routes/capability-api.js | Dead code/duplication (e.g., duplicate identify definition in handleCapabilityRequest) | Medium (delete after confirming no entry references; remove reference in server.js L2419) |

| Frontend legacy create component | src/composables/useCreate.js | Contains nested bugs, duplicates useCapabilityCreate | Medium (ItemTypeManagement.vue needs migration to useCapabilityCreate) |

| Scattered debug scripts | scripts/test-create.js, scripts/_test_.js, scripts/debug/, etc. | Debug leftovers | Low (first confirm no test references) |

| server.js route competition | Remove /api/capability/ → capability-api.js branch (L2416-2425) | Competes with app/routes/capability.js | Medium (keep single entry) |

⚠️ Before deletion, must confirm: The above "to-delete" list is a suggestion. Among them, rule-engine.createItem, capability-api.js, and useCreate.js are structural deletions; first confirm all referencing parties have switched to avoid accidental deletion causing functionality breaks. CapabilityRuntime (5 capabilities) and CapabilityDispatcher should not be deleted (verified success, part of the unified solution).

V. Unified Solution (Converged Based on Retained Items)

5.1 Target Architecture (After Convergence)

```

All entries (web business pages / dialogue / digital employees / mini-programs / Feishu)

│

▼

Single HTTP entry (keep CapabilityDispatcher or unified route, choose one clearly)

│

├── create → unified-create.js (SCSAI Sequence numbering, rule engine only optional pre-check)

└── identify/repair/optimize/compare/generate → CapabilityRuntime (rule engine + LLM)

│

▼

SCSAI (single source of truth)

`

5.2 Key Change Points

1. CapabilityRuntime.create changed to call unified-create:

• Remove the main flow branch that goes through rule-engine.createItem.
• Change to assemble {itemType, properties, relationships, itemProperties} → call handleUnifiedRoute in unified-create.js or export its internal createObject logic (need to export createObject from unified-create for CapabilityRuntime to call directly, avoiding another HTTP round trip).

1. Frontend business page legacy migration:

• ItemTypeManagement.vue is migrated from useCreate.js to useCapabilityCreate.js.
• Delete useCreate.js.

1. Route convergence (de-competition):

• Clarify the unique handler for /api/capability/* (suggestion: CapabilityDispatcher via app/routes/capability.js; remove the duplicate branch in server.js pointing to capability-api.js).
• /api/unified/ is reserved for the frontend useCapabilityCreate + mobile clients.
• /api/capability/pipeline/ is reserved for digital employees.

1. Rule engine role convergence:

• Used only for create_pre validation/deduplication (ENABLE_RULE_PRECHECK can enable auditing) and the 5 capabilities.
• No longer responsible for number generation (number generation is delegated to SCSAI Sequence via unified-create).

5.3 Verification Plan

Reuse verify-capability-line.mjs and add create cases (Part / Activity2 / Project, etc.) on top of it, connecting directly to the real SCSAI for verification:

• All 6 capabilities succeed through the single entry.
• create goes through the unified path (unified-create), actually persists to the database, with correct numbering and no duplicate keys.
• Frontend business page creation uses useCapabilityCreate (manual/screenshot verification).

6. Execution Order and Verification Results

1. ✅ Write the current-status document (this file) — done.
2. ✅ Implement convergence (done; pending user final confirmation on deletions):

• Change handleCreate in unified-create.js to dual-mode (when res=null, return a structured object for reuse by non-HTTP callers); and export handleCreate via module.exports.
• Change the main flow of CapabilityRuntime.create to call handleCreate(null,null,{itemType, properties, relationships, itemProperties}), uniformly following the 7-step core; LLM fallback is retained as the ultimate safeguard.
• Simplify capability-pipeline.createObject to reuse handleCreate (remove the original simplified AUTO- fake numbering logic + duplicate relationship recursion).
• Step 3 numbering fix: local sciot_properties failed to mark Part item_number's is_keyed, so numbering was never generated. Switch to KNOWN_KEYED_FIELDS as a fallback (Part→item_number, etc.), and add a fallback for SCIOT-customized SCSAI that does not support getNextValue: query the current maximum number for that type +1 (getNextItemNumber).

1. ✅ Real verification (2026-07-09, real SCSAI http://114.113.153.234/scplm):

• verify-capability-line.mjs ran through all 6 capabilities with success=true:
• create → source: unified_create (actually persisted to DB, ID=9FB8AE8D…, no longer falls back to LLM);
• repair/optimize → source: rule_engine;
• compare/generate → source: llm_router;
• identify → source: rule_engine.
• Direct test of capability-pipeline.createObject('Part',...) also went through unified-create and actually persisted to DB (ID=AC7646DA…).
• Previously, create relied on LLM fallback as a safety net (risking errors with fields like variant_max); it has now converged to the single correct unified component.

3b. Real verification of six primary business object types (verify-biz-create.mjs, 2026-07-09, real SCSAI) — all successfully persisted to DB via the unified component handleCreate:

| Type | Result | Number |

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

| Project | ✅ Actually persisted | project_number=472870 (real max+1) |

| Product | ✅ Actually persisted | Name |

| Part | ✅ Actually persisted | item_number=PAR-… (real max+1) |

| Vendor | ✅ Actually persisted | Name |

| Customer | ✅ Actually persisted | Name |

| ECN | ✅ Actually persisted | item_number=ECN-100038 (real max+1) |

• Real bugs exposed and fixed during verification:

1. Project number duplication: getNextItemNumber originally relied on SCSAI orderBy desc to get the maximum, but this SCIOT customized version does not support orderBy on the number field (returns unordered), so the value obtained was not the true maximum → after +1 it still hit the unique constraint. Changed to pulling all numbers on the JS side to get the true maximum.
2. Local sciot_properties omitted marking is_keyed (Part/Vendor/Customer/ECN local template props=0 or keyed not marked) → numbers were never generated. KNOWN_KEYED_FIELDS has been used as a fallback (Part→item_number, etc.) to ensure standard number fields are always generated.

• Real issues exposed during verification but not in the create component itself (pending):
• Project's scheduling_method/update_method are required Method references: in the environment, _none is a JavaScript-type Method, and this SCSAI reports "method type (JavaScript) not currently supported". During verification, switching to a C#-type Method (_Set_font_Color, id 13F4564D…) passed. This is due to missing appropriate scheduling Method in environment data, not a create logic issue.
• relationship-resolver misjudges ECN as "already exists": its resolveExistence looks up the ECN name field using the ECN title as the name, causing ECN to be blocked by existence pre-check when entering via CapabilityRuntime.create (source=SCSAI:name). The create component itself (direct handleCreate call) can create ECN normally. This is a field-mapping bug in the existence pre-check; the resolver needs a separate fix (ECN should be queried by title instead of name).

1. ⏳ Pending user confirmation, remove redundancy: rule-engine.createItem (dead end), server/routes/capability-api.js (dead code), frontend useCreate.js (old path has nested bug; business pages migrated to useCapabilityCreate.js), route race branch, unused capability-api mount in server.js.

Environment limitation note: This SCSAI is a customized version of SCIOT; both the Sequence getNextValue action and editing current_value are unavailable (reporting ItemNotFoundException / MissingCriteriaException). Therefore, the numbering fallback uses "query the current maximum item_number in SCSAI + 1", which is reliable and unique. If the future environment supports real Sequence, it can be preferred after getNextSequence succeeds.

Attachment: Key file list (quick index)

• Correct create core: server/routes/unified-create.js
• Digital employee pipeline: server/routes/capability-pipeline.js
• 5 capability routes: server/core/capability-runtime.js / server/core/capability-dispatcher.js / app/routes/capability.js
• Rule engine: server/core/rule-engine.js
• Frontend creation: src/composables/useCapabilityCreate.js (✅) / src/composables/useCreate.js (❌ to be deleted)
• Verification script: verify-capability-line.mjs
• Route mounting: server.js L2368-2425, L6757-6759; app/router.js L65