数字员工统一架构方案（收口大杂烩）

目标：从「定义 → 调用（MTClaw 端侧 / 自研调度器）→ 执行（worker）→ 小程序端 → 外部官网 API」

全链路统一到单一真相源，消除多处配置文件 + 数据库 + 脚本各自为政的现状。

0. 现状诊断（已查清的事实）

0.1 调用终点其实已经统一（好消息）

三套调用入口，运行时都已汇聚到同一个函数：

| 调用入口 | 路径 | 终点 |

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

| MTClaw 端侧 proxy | server.js:2062 /api/digital-staff/mtclaw/proxy → server.js:2358 _scheduler.runStaffOnce | boss-scheduler/index.js:99 runStaffOnce |

| 自研调度器 | boss-scheduler/index.js runStaffOnce | lite-scheduler.js runOnce → _runWorker（真正跑 worker） |

| 小程序端 | bossagents-miniapp/server/miniapp-routes.js:915 /api/digital-staff/run（axios 回主入口）和 :1136 直接 require('../../server/boss-scheduler/index.js').runStaffOnce | 同一 runStaffOnce |

| 外部/官网/企微/飞书 | server.js /api/digital-staff/run + routes/open-platform.js / feishu-*.js | 同一 runStaffOnce |

→ 执行终点 _runWorker 已是唯一真相，不需要再造调度器。

0.2 真正乱的是「定义源」和「断头路」

1. 定义源三套并存且冲突：

• profiles/local.yaml 的 staff 段（54 个，定义种子）→ syncStaffToDb 写入 DB；
• staff-manager.js:345-361 seedDefaultStaff 硬编码 15 个种子（INSERT OR IGNORE），与 local.yaml 字段不一致、并行插入；
• MTClaw/scripts/*.js 73 个端侧脚本各写死一个 DS-XXX 默认 staffId，其中 19 个在 local.yaml 和 workers 中都不存在（死链）。

1. 运行时真相是 DB 不是 YAML：index.js:43 syncStaffToDb → :45 loadStaffFromDb 以 DB 覆盖内存。改 YAML 若没重新 sync，线上不生效，造成"改了没反应"的混乱观感。
2. 七个基础动词未显式锚定：识别/创建/修复/优化/比对/生成/巡检散落在不同 DS-XXX，比对(compare) 无独立基础员工；优化 被三份瓜分（DS-COST-001 / DS-PROCESS-OPT-001 / DS-SCCAPP-OPT-001）。
3. 网页版只渲染员工实例，不渲染 positions 岗位体系（工厂操作工/工艺员/库管已对齐但前端看不见）。

0.3 19 个断头 ID（MTClaw 端侧喊了、后端无人接）

DS-ASSET-001 DS-BOM-001 DS-COMP-001 DS-CONTRACT-001 DS-ENERGY-001 DS-FIN-001 DS-HR-001 DS-INVOICE-001 DS-LOG-001 DS-MEET-001 DS-PROC-PLAN-001 DS-PROD-001 DS-QUALITY-001 DS-RISK-001 DS-SAFETY-001 DS-SUP-AUDIT-001 DS-TRAIN-001 DS-TRAVEL-001 DS-WH-001

这些脚本回传 delegate_to_digital_staff，但 server.js toolToStaff 无对应映射 → runStaffOnce 报"员工不存在"，是死链。

1. 统一架构（目标态）

                  ┌─────────────────────────────────────────────┐
   定义真相源     │  profiles/local.yaml                          │
   (唯一可编辑)   │   staff:  [所有数字员工定义]                  │
                  │   positions:[工厂岗位→员工映射]              │
                  │   (七个基础动词显式锚定 verbs: 识别/创建/...) │
                  └───────────────┬─────────────────────────────┘
                                  │ syncStaffToDb（一次性/重启时）
                                  ▼
                  ┌─────────────────────────────────────────────┐
   运行时镜像     │  SQLite digital_staff 表（仅镜像，不可手改）  │
                  └───────────────┬─────────────────────────────┘
                                  │ loadStaffFromDb（启动加载）
                                  ▼
                  ┌─────────────────────────────────────────────┐
   统一执行内核   │  boss-scheduler/index.js runStaffOnce         │
                  │     → lite-scheduler._runWorker（唯一终点）   │
                  │     → workers/*.js（唯一实现）               │
                  └───────┬───────────────┬───────────────┬──────┘
                          │               │               │
            ┌─────────────┴──┐ ┌──────────┴────┐ ┌────────┴──────────┐
   调用端    │ MTClaw 端侧    │ │ 自研调度器     │ │ 小程序 / 官网 /   │
            │ (L1路由→委托)  │ │ (runStaffOnce)│ │ 企微/飞书/openapi │
            └────────────────┘ └───────────────┘ └───────────────────┘
                  全部经 runStaffOnce 收敛，无第二套执行

铁律：

• 新增/修改数字员工 只改 local.yaml，禁止在 staff-manager.js、MTClaw 脚本、数据库里另写一份。
• 所有调用端（含 MTClaw 端侧、小程序、外部 API）只认 runStaffOnce，禁止各自 fork 执行逻辑。
• workers/*.js 是唯一业务实现，MTClaw 脚本一律不做业务、只做 L1 路由决策。

2. 落地步骤（按依赖顺序）

步骤 1：local.yaml 成为唯一定义真相源

• 把 staff-manager.js:345-361 的 15 个硬编码种子全部删除，其职责并入 local.yaml 的 staff 段（若已有同名则核对字段，以 YAML 为准）。
• 在 local.yaml 每个 staff 增加 verbs: 字段，显式锚定七个基础动词：
• 识别 → DS-IDENTIFY-001
• 创建 → DS-SCSAI-001
• 修复 → DS-REPAIR-001（含工艺数据修复 DS-PROC-DATA-001 归其下）
• 优化 → 设统一主员工（建议 DS-OPT-001 或指定 DS-COST-001 为成本优化主、其余标 sub）
• 比对 → 新增独立基础员工 DS-COMPARE-001（从 DS-CHIP-004 / DS-DOC-001 / DS-STAT-001 抽取比对能力）
• 生成 → DS-CONTENT-001（文档生成归 DS-DOC-001 标 sub）
• 巡检 → DS-INSPECT-001（含巡检闭环 DS-*）
• 明确「基础员工」标记 tier: base，便于网页版/官网高亮。

步骤 2：收口 19 个断头 ID

对 MTClaw/scripts 里那 19 个无后端接应的 ID，二选一（统一决策）：

• A（推荐）：在 local.yaml 补注册这 19 个员工 + 相应 workers/*.js 实现（把"资产管理/合同/财务/HR/质量/安全/培训/差旅/仓储…"真做起）；
• B：脚本改指已有近义员工（如 DS-WH-001→DS-STOCK-001、DS-QUALITY-001→DS-INSPECT-001），不补实现。

必须经此步，否则 MTClaw 端侧仍是死链。

步骤 3：DB 仅作运行时镜像，去掉"双写"

• staff-manager.seedDefaultStaff 删除后，syncStaffToDb 成为唯一写 DB 的入口；启动顺序保持 loadProfile → syncStaffToDb → loadStaffFromDb。
• 文档明确：DB 不可手改，改 YAML 重启即生效；移除一切"直接 INSERT digital_staff"的散落代码。

步骤 4：调用端统一收敛

• MTClaw 端侧：脚本只做 L1 路由（保留现状），但 server.js toolToStaff 必须覆盖全部 local.yaml 已注册 ID（步骤 2 完成后自然满足）。
• 小程序端：保留 miniapp-routes.js 经 runStaffOnce 的两条路径，删除任何绕过 runStaffOnce 的直调。
• 外部/官网：所有 /api/digital-staff/run 及 open-platform / feishu 入口，统一调 runStaffOnce，不另起炉灶。

步骤 5：网页版同时渲染「岗位体系 + 员工实例」

• 前端数字员工页面新增「岗位视图」tab，消费已有 /api/digital-staff/positions（local.yaml positions 段，16 个岗位已含工厂操作员/工艺员/库管对齐），让前端可见"工厂操作工→对应数字员工"的映射。

步骤 6：删除旧双实现

• 确认 server/digital-staff/index.js 的旧 runStaffOnce（switch-case 分发）不再被 server.js 入口使用（loader 已指向 boss-scheduler），择机删除，消除双执行实现。

3. 验证清单（收口后）

• [ ] grep 全仓 INSERT ... digital_staff 仅剩 syncStaffToDb 一处。
• [ ] staff-manager.js 硬编码种子段已删。
• [ ] MTClaw 73 脚本引用的 DS-ID 全部在 local.yaml 注册（0 断头）。
• [ ] 七个基础动词各有 tier: base 主员工，比对有独立 DS-COMPARE-001。
• [ ] 网页版「岗位视图」能展示工厂操作工/工艺员/库管对应的数字员工。
• [ ] 端到端：MTClaw 端侧命中 → runStaffOnce → _runWorker → 真实落库，无"员工不存在"报错。

4. 关键文件清单

5. 落地进度（2026-08-22 已完成 1+3+A）

已完成

• 第3步（定义源收口）：server/digital-staff/staff-manager.js 的 seedDefaultStaff() 硬编码 15 个种子已删除，改为 backfillLegacyStaff()（仅基于 local.yaml 回填老库空 worker 字段，不再插入任何新员工）。数字员工定义写入现唯一经 syncStaffToDb → staffManager.createStaff/updateStaff，消除与 YAML 双重定义。
• 第1步（七动词锚定）：local.yaml 新增 tier: base + verbs: 字段，七个基础动词全部锚定：
• 识别=DS-IDENTIFY-001（新增）、创建=DS-SCSAI-001、修复=DS-REPAIR-001（新增）、优化=DS-COST-001、比对=DS-COMPARE-001（新增）、生成=DS-CONTENT-001、巡检=DS-INSPECT-001（新增）。
• 原缺失的 IDENTIFY/REPAIR/INSPECT/COMPARE 四个基础员工已补注册并配套 worker。
• 第2步A（19断头补实）：local.yaml 补注册 19 个原 MTClaw 断头员工（DS-ASSET/BOM/COMP/CONTRACT/ENERGY/FIN/HR/INVOICE/LOG/MEET/PROC-PLAN/PROD/QUALITY/RISK/SAFETY/SUP-AUDIT/TRAIN/TRAVEL/WH-001），各含完整字段 + tier: domain；lite-scheduler.js 的 WORKERS 表注册 23 个新 worker 映射（4基础+19断头），并生成对应 23 个最小可用 worker 文件（workers/{identify,repair,inspect,compare,asset,bom,...}.js，骨架实现，遵循诚实化原则，待填充真实领域逻辑）。

验证结果

• MTClaw 73 脚本引用的 49 个 DS-ID 全部在 local.yaml 注册，0 断头（原 19 断头已清零）。
• local.yaml 解析正常，staff 总数 77（54 原 + 4 基础新增 + 19 断头新增）。
• 23 个新 worker 文件均可加载且导出 run()，WORKERS 映射完整。
• staff-manager.js 全仓 INSERT digital_staff 仅剩 createStaff（syncStaffToDb 入口），硬编码种子已根除。

待办（后续）

• 第2步A 的 19 个领域 worker（asset/bom/compliance/contract/energy/finance/hr/invoice/logistics/meeting/proc-plan/production/quality/risk/safety/sup-audit/training/travel/warehouse）仍为 skeleton，已诚实化（无真实逻辑时 success:false + implemented:'skeleton'，不再伪装成功），后续按需逐领域填装真实逻辑。
• 第6步：删 server/digital-staff/index.js 旧 runStaffOnce 双实现（确认 loader 未用后，低风险，仅保留 staffLog/mergeDbIntoMemory 工具函数）。

已落地（2026-08-22 第二批）

• 四动词底座真实降级实现：identify/compare/inspect/repair 四个七动词 worker 已填真实可跑逻辑（基于 ctx.db 只读 SELECT + parameters 输入做识别/比对/巡检/修复诊断，MTClaw 不可用时能真干活或诚实降级），运行时验证通过。
• 19 个领域骨架诚实化：去掉"永远 success:true"的伪装，无真实逻辑时 success:false 明确标注，杜绝虚假成功。
• 验证：23 个 worker 全部可加载导出 run()；4 动词 worker 真实/降级路径均验证；vite build 通过。

6. 收口续做（2026-08-22 晚，第 4+5 步完成）

第4步 — 调用端统一收敛（已确认，无需改代码）

• 核查 server.js 全部 5 处数字员工执行入口（3509/5749/5797/2358/6737）+ MTClaw 经 server.js 桥接：
• digitalStaff 经 server/digital-staff/loader.js 加载，实际返回 require('../boss-scheduler/index.js')（统一版 BossScheduler），即那 5 处 digitalStaff.runStaffOnce(...) 调的已是统一调度器。
• 旧 server/digital-staff/index.js 的 runStaffOnce（switch-case 派发 9 员工）已非执行入口，仅 staffLog 等工具函数被 SSE 日志长尾引用。
• 结论：调用端已统一到 boss-scheduler/index.js runStaffOnce → lite-scheduler._runWorker，三端（网页/小程序/飞书/外部API）汇聚点一致，无需再造调度器。

第5步 — 网页版岗位视图 tab（已落地）

• 后端 /api/digital-staff/positions 早已存在（server.js:4895，调 loadPositions() 消费 local.yaml positions 真相源）。
• 前端 src/views/DigitalStaff.vue 新增第三个 tab「岗位体系」：
• tab-bar 加 positions 按钮；新增 positions/positionsLoading ref + fetchPositions()（调上述 API，只拉一次）+ selectStaffById()（点岗位成员跳到对应员工详情）。
• 渲染 16 个岗位卡片，每张含岗位图标/部门/成员数 + 成员 chips（数字员工实例，含 enabled 状态点、点击跳转）。
• frontend/i18n.js 四语言（zh/en/ja/ko）补 staff_tab_positions + positions_* 文案。
• 样式复用现有 .status-dot/.card-bg 暖金主题体系，新增 .positions-*/.agent-chip 类（scoped）。
• 验证：loadPositions() 实际返回 16 岗位 / 64 成员 / 0 幽灵 / 0 禁用；工厂岗位（操作工/质量/工艺/调度/设备/库存/财务/采购/老板/IT/安全员/芯片/市场/GOAI/采购闭环/巡检修复闭环）全部映射到真实存在的数字员工，直接消除"工厂岗位没对齐"观感。
• 构建：npm run build（vite）通过，无编译错误。