Position Assistant V2.0 + Stability Governance Delivery Summary

Date: 2026-08-09

Status: ✅ All completed and verified

I. Delivery Objectives

1. Cloud Server Crash Governance — Identify root cause of "crashes after running for a while" and implement governance switch
2. core_runtime.db Corruption Repair — Fix core process errors caused by database corruption
3. Position Assistant V2.0 — Revamp of the digital employee platform with "10 Manufacturing Positions" as the homepage (Position Configuration Layer + API + Feedback Loop + Frontend Restructuring)

II. Crash Governance (Root Cause + Solution)

Root Cause (Evidence Chain)

• Startup log registers 62-line cron scheduled tasks (41 employees + loop/goal cycles),
• Hourly ×3 (DS-STOCK-LOOP / DS-DATA-SYNC / DS-SPC Inspection), Every 2 hours ×5,
• Each task = SCSAIPLM query + LLM call + better-sqlite3 synchronous write
• Main process measured 878MB memory / 279.9 seconds CPU (single startup)
• Multiple hourly tasks triggering simultaneously → Low-spec cloud server resources exhausted → Crash

Governance Solution (Environment variable switch, default behavior unchanged)

| Switch | Location | Purpose |

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

| BOSS_SCHEDULER_CRON=off | server/boss-scheduler/lite-scheduler.js start() | Registers no cron tasks, manual runStaffOnce unaffected |

| BOSS_HEAVY_BG=off | server.js | Skips self-evolution pipeline, RuleDrift reconciliation (60s), scheduled/first-time data collection |

Add two lines to cloud server .env; dev machines remain unchanged without switches.

Verification Results

• Off mode: Logs confirm 4 switches are effective; health / llm-config / status are normal; manual execution chain is available.
• Default mode regression: 62 cron jobs + self-evolution pipeline register normally (behavior is compatible).

3. Repair of core_runtime.db Corruption

• Symptom: better-sqlite3 reports 'database disk image is malformed' (some runtime records cannot be written).
• Steps:

1. Back up the original file as core_runtime.db.bak-20260805-202823.
2. Use the sqlite3 .recover command (chocolatey 3.51.2) to export core_recover.sql.
3. Import into a new database, recovering 94-102 tables (including 52 rows of cached data, which can be re-sourced from SCSAI).
4. PRAGMA integrity_check=ok, no malformed error after restart.

4. Position Assistant V2.0 (Core Delivery)

4.1 Position Configuration Layer (Configuration only, no engine changes)

Added a new 'positions:' section at the end of server/boss-scheduler/profiles/local.yaml, with 10 manufacturing positions:

| Position ID | Name | Responsibility & Role |

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

| POS-OPERATOR | Workshop Operator | Line execution, equipment inspection, work reporting |

| POS-QA | Quality Inspector | Incoming/process/final inspection, quality records |

| POS-PROCESS-ENG | Process Engineer | Process card creation, change management |

| POS-SCHEDULER | Production Scheduler | Production planning, order tracking |

| POS-EQUIP | Equipment Maintenance Technician | Inspection & Maintenance, Fault Reporting |

| POS-STOCK | Warehouse Manager | Inbound/Outbound, Inventory Query |

| POS-FINANCE | Finance Specialist | Cost Accounting, Invoice Reconciliation |

| POS-PROCURE | Procurement Specialist | Requisition to Purchase, Supplier Management |

| POS-BOSS | Owner/Manager | Business Overview, Decision Support |

| POS-IT | System Administrator | System Inspection, User Accounts |

Each position includes fields:

• name / slogan / description / target_users
• agents[] — Associated agent combinations for the position (many-to-many, 3-5)
• scenarios[] — Preset scenarios (3 one-click demos)
• related_rules[] / feedback_points[] / process_steps[] (5 transparent process steps)

Many-to-many relationships: One position links to multiple agents (e.g., Boss Assistant links to 5); one agent serves multiple positions (e.g., DS-SPC-001 serves both Operators and Quality).

4.2 Backend API

| Endpoint | Description |

|---|---|

| GET /api/digital-staff/positions | All positions + full associated agent info (total=10) |

| POST /api/feedback | Submit experience feedback (content required) |

| GET /api/feedback?position_id=&category=&status=&page= | Query feedback by criteria |

| GET /api/feedback/stats | Statistics by position/category/status |

Feedback data is stored in server/data/feedback.db (an independent module at server/routes/feedback-routes.js).

Pitfall record: In the feedback SQL query, WHERE position_id != "" causes a column name error in better-sqlite3 — must use single quotes ''.

4.3 Frontend Positions Homepage (serves as the project homepage)

• Route: / redirects to /positions (Position Assistant = default homepage)
• Layout (src/views/PositionsView.vue):
• 10 position card array (each card = position name + slogan + number of AI agents/scenarios)
• Toolbox card (digital employee overview/task board entry, dashed border style)
• Content/Marketing/Customer Service/Documentation reserved area buttons
• Position detail drawer:
• List of combined AI agents (click → #/ai-workbench?runStaffId=xx&runIntent=xx)
• One-click preset scenario experience (quickRun redirects to AI Workbench for automatic execution)
• Rule tags + 5-step transparent process display
• Experience feedback form (submit → POST /api/feedback)
• Navigation entry: Add positions as the first flat item in navGroups.js, add nav_positions in i18n (Chinese/English).

4.4 Build and E2E Results

• npm run build successful (generates independent chunk dist/views-positionsview).
• /api/digital-staff/positions → total=10, page [200]
• Feedback loop: POST → GET (filtered by position) → stats, full link passes.
• Static resources 200, homepage accessible

V. Route Risk Investigation and Fix (Discovered during validation)

While validating /api/digital-staff/run-detail, three real bugs from coexisting old and new route layers were discovered:

| Bug | Symptom | Root Cause | Fix |

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

| reload hangs indefinitely | POST request no response, client times out after 10s | reload not in oldPaths whitelist of new route layer, request swallowed by new layer | Add /api/digital-staff/reload to whitelist |

| Silent hang for unknown paths | Any API not in whitelist gets no response | No fallback after staffRoutes returns false | Change false → explicit 404 Not Found for digital staff API |

| tasks/ dynamic path swallowed | /tasks/:id/:action times out | Exact-match whitelist does not include dynamic subpaths | Add pn.startsWith('/api/digital-staff/tasks/') prefix matching |

Regression suite (all green after fixes):

• reload → 200 OK; unknown path → quick 404; tasks prefix → 404 (no longer hangs)
• health / status / positions / llm-config / run-detail?runId= / loops / feedback-stats all 200
• Test feedback data cleared, server stopped, port released

VI. Usage and Operations

Cloud server anti-crash (2 lines suffice)

# .env 追加
BOSS_SCHEDULER_CRON=off
BOSS_HEAVY_BG=off

岗位配置扩展(新增岗位只需改 YAML)

local.yaml → positions: 段增加 - id: POS-XXX ... 后重启(或调用 POST /api/digital-staff/reload 热刷新)。

Frontend build

npm run build   # 产物 dist/,由 server.js 静态托管

反馈数据查看

sqlite3 server/data/feedback.db "select * from feedback order by id desc limit 10"

七、关键文件清单

| 文件 | 说明 |

|---|---|

| server/boss-scheduler/profiles/local.yaml | 61 employee entries + 10 positions configuration |

| server/boss-scheduler/staff-registry.js | loadPositions() Load position configuration |

| server.js | positions/reload route + governance switch + oldPaths whitelist fix |

| server/routes/feedback-routes.js | Feedback loop (new) |

| server/routes/digital-staff-routes.js | New routing layer (404 for unknown paths) |

| server/data/feedback.db | Feedback data (new database) |

| server/data/core_runtime.db | Rebuilt (corrupted backup: core_runtime.db.bak-*) |

| src/views/PositionsView.vue | Positions homepage (new) |

| src/router/index.js | /positions route + default redirect |

| src/constants/navGroups.js / frontend/i18n.js | Positions entry and text |

VIII. Pending Items

1. server/ai-agent.js:1513 Relative path bug for require('../boss-scheduler/index') in resume_staff not fixed yet (previously blocked by end-to-end link validation, does not affect demo)
2. Feedback backend for position assistant (admin view), position-level permissions, and more scenario libraries (each position can be expanded to consume 10-20 scenarios) can be iterated later

Nine. Six Capability Verification (2026-08-10)

Verification Results

Newly Fixed Bug: Identify/Generate 500 error (missing metadata table)

• Root Cause: In rule-engine.js, _recoverMetaIfEmpty() source DB path pointed to rule_engine.db (itself), but metadata tables like sciot_properties (41240 records)/sciot_item_types (1217)/sciot_relationships (587) were actually in sciot-metadata.db → recovery never took effect → executeIdentify/executeGenerate queries resulted in 'no such table: sciot_properties' → 500 error
• Fix: _recoverMetaIfEmpty prioritizes source library sciot-metadata.db, falls back to rule_engine.db if missing (effective, all six tables recovered).

"Create object class first if none exists" verification passed.

• Call /api/unified/create with a non-existent object class QA_CapTest_Obj:

1. ensureItemType automatically calls smartCreateItemType → object class successfully created on SCSAI side (id=F0337BD8, label normal).
2. Subsequent instance creation succeeded (5C95A9FC).

• Complex nested creation (two Part BOM lines): parent 9061C088 → children QA-BEARX-001 (qty=2) + QA-COVX-001 (qty=1), verified by SCSAI query to be actually stored.
• Full-chain test data cleaned up (object class/instance/BOM residue = 0).

Note (creation parameter format):

• /api/unified/create parameters are in camelCase: itemType / properties / relationships / itemProperties.
• Standard format for nested child objects: related_items: [{ properties: {...}, item_properties: {...} }].
• Using the related field will be ignored (must use related_items).