BossAgents 数字员工 CMS 演示调用文档

版本：2026-08-16 ｜ 依据：72 员工全量四维审计（静态）+ 执行可达性探针（动态）+ 最新代码配置（yaml 基线 72；运行时含 2 系统内置 = 74）

2026-08-12 更新：核对并修复小程序侧路由（goConsole→pages/ai-chat/index、goSearch→pkg/workbench/search）；getRuns 补齐 /api 前缀；后端修复 pending-confirms 被 oldPaths 误拦 404、新增 POST /api/staff/profile-update（见 4.3）。

2026-08-15 更新：软隐藏机制落地——19 个无法派发真实任务的员工纳入 HIDDEN_STAFF_IDS 单一真相源，用户端 / 普通列表不可见，管理端（网页管理控制台、小程序管理页）可见且可重新上线；活跃可展示员工收敛为 52（STAFF_DEFAULTS，含与定位匹配的默认意图 + 可视化参数默认值）；新增「能力画像（/api/doc-agent/staff-capability/portrait/:id）」「绩效（/api/digital-staff/:id/performance）」端点并接入网页 / 小程序两端（见数字员工体验对齐节）。

2026-08-16 更新：DS-ARAS-001 万能对象创建恢复可见（从 HIDDEN_STAFF_IDS 移除——经验测返回真实「识别对象类型 → 确认创建」流程 type:confirm、名实相符，非占位壳；隐藏集 19→18、活跃可见 52→53）；WEB 端 / 小程序端统一：员工清单、下架/隐藏、执行 /api/digital-staff/run、能力画像、绩效均共用同一后端（staff-router.js 单一真相源），仅渲染 UI 两套、体验结果完全一致（见数字员工体验对齐节 F）。

适用场景：官网 CMS 演示页 + 微信小程序端，统一 API 契约，实时展示真实执行结果。

数据口径：本文所有数字、状态均来自脚本对代码的实测（见 scripts/audit-digital-staff.cjs 与 scripts/probe-staff-exec.cjs），不掺水。

一、结论总览（诚实口径）

全部 72 个数字员工（yaml 配置基线；运行时含 2 系统内置 DS-DQ-001/DS-EVO-001 = 74），经过四维实测：

| 维度 | 口径 | 结果 |

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

| ✅ 能用 | 启用 + 有可解析执行路径（worker 文件存在且导出 run / capability 在流水线映射内 / pipeline / loop / generic） | 72 / 72 |

| 🔽 活跃展示（用户/列表可见） | 在 STAFF_DEFAULTS 且非 HIDDEN_STAFF_IDS：可自然语言直呼、有统一默认意图 + 可视化参数默认值（经 /api/staff/banners 单一真相源） | 53 / 72 |

| 🔒 已下架隐藏（管理端可见可上线） | HIDDEN_STAFF_IDS 收口：能力错位（名不副实）/ 纯占位无执行体 / worker 已废弃，无法派发真实任务，用户端不可见、路由与列表跳过（详见 5.1） | 18 / 72 |

| ✅ 可配置 | 有路由关键词 / 参数入口（keywords、item_types、params、router 表命中） | 72 / 72 |

| ✅ 可调度 | cron 定时 / run_on_startup / 事件触发 / loop 循环 / 编队触发 | 72 / 72（其中 42 个带 cron） |

| ✅ 可协同 | 归属某岗位 agents / 命中协作规则 / 可作为编队成员 | 72 / 72 |

| 🗣️ 自然语言直呼可达 | 自身至少一个专属关键词能路由回自己 | 63 / 72 |

| 🔒 仅按 staffId / 编排触发（设计如此） | 编排节点 + 同 worker 重名别名，不由自然语言直呼 | 9 / 72 |

执行模式分布：worker 脚本 52 ｜ capability 1 ｜ pipeline 流水线 13 ｜ loop 定时循环 5 ｜ generic 兜底 1

协同体系：岗位 15 个（均配人类负责人 human）｜ 协作规则 27 条 ｜ 编队运行时 task-force（DAG + 共享黑板 + 人工卡点）｜ 事件总线 position-events（SSE 实时扇出）

行业消费：仅 4 个员工真正按行业维度消费数据（DS-KBPIPE-001、DS-DOC-001、DS-KNOWLEDGE-001、DS-PROC-DATA-001）—— 行业坐标系已建，但"按行业批跑"尚未在 worker 层全面落地（见第九节）。

数字口径：本文统计基于 local.yaml 权威配置共 72 个员工（含 2026-08-15 新增 DS-CS-001 客服）。运行时 CMS 控制台（GET /api/digital-staff/list）实际返回 74 个，多出的 2 个为系统内置 / DB 持久化员工 DS-DQ-001（数据质检）、DS-EVO-001（自进化），不在 yaml 内但同样可用；yaml 的 72 个已 100% 加载到运行时，无遗漏。

软隐藏口径（2026-08-16）：/list 现给每个员工附加 hidden 布尔字段。74 个返回项中，18 个 hidden:true（来自 yaml 的 72 中被 HIDDEN_STAFF_IDS 收口的 18 个；DS-ARAS-001 已于 2026-08-16 恢复可见）——用户面向列表（网页端召唤区、小程序首页 / 数字员工 / AI 对话）按 !hidden 过滤；网页端管理控制台与小程序管理页展示全部并标注「已下架」、允许重新上线。活跃可见员工 = 53（STAFF_DEFAULTS）。

核心承诺：全系统无任何模拟 / 硬编码假数据。所有结果来自真实 SCSAI PLM、真实 SQLite 业务库；依赖不可用时诚实返回 success:false + 步骤名 + 原因 + 堆栈，绝不"假装成功"。

二、四维口径与验证方法

| 维度 | 验证脚本 | 通过条件 |

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

| 能用 | probe-staff-exec.cjs L1/L2 | L1 worker 模块可 require 且不抛错（52/52）；L2 pipeline/loop/capability 能力可在 CapabilityRuntime 解析（19/19）；可执行 71/71 |

| 可配置 | audit-digital-staff.cjs | 有 keywords 或被 staff-router 路由表命中，或含 item_types/params 入口 |

| 可调度 | audit-digital-staff.cjs | 含 cron / loop.trigger / run_on_startup / 出现在事件触发表 / 可由编队触发 |

| 可协同 | audit-digital-staff.cjs | 命中 collaboration-rules.yaml 或归属 positions[].agents 或可作编队成员 |

自然语言可达（L3）说明：probe-staff-exec.cjs 用每个员工「自身的一个专属关键词」喂给 staff-router.matchStaff，若能路由回自己即算可达。

• 🔒 的 9 个均为设计如此：7 个 loop/chain/GOAI 编排节点（由定时循环 / 流水线 / 编队触发，不应自然语言直呼）+ 2 个同 worker 重名别名（DS-DATA-001≡DS-BOSS-001、DS-SYS-001≡DS-BOSS-002，按 staffId 或意图调用）。
• 其余 62 个均可被自然语言直呼。

三、协同体系（行业 × 岗位 × 数字员工 × 人）

三层正交坐标系：行业 = 知识坐标系（固定集合）｜ 岗位 = 权责主体（可调）｜ 数字员工 = 能力原子（通用）。解耦后成本 N+M+K 而非 N×M×K。

3.1 岗位（15 个，均配人类负责人）

3.2 协作规则（27 条）与编队

• 协作规则定义在 server/boss-scheduler/collaboration-rules.yaml（27 条）+ 岗位内联 collaboration.next。
• 跨岗位编队由 server/boss-scheduler/task-force.js 运行时驱动：DAG 分层 + 共享黑板 + 人工卡点 + 硬碰撞/语义分歧双层冲突检测；挂起态落库，人在环签字后 POST /api/digital-staff/taskforce/resume 继续。
• 事件总线 position-events.js：触发器热更新 + SSE 实时扇出（GET /api/digital-staff/event/stream）。

四、CMS 调用方式（HTTP API 契约）

服务地址：http://<服务器>:3006（本机演示 http://localhost:3006）

4.1 触发员工执行（核心）

POST /api/digital-staff/run
Content-Type: application/json

{ "staffId": "DS-BOSS-002", "intent": "", "parameters": {}, "skip_mtclaw": true, "_lang": "zh-CN" }

• staffId 必填（见第五节 / 第十节清单）。intent 空串 = 走员工默认完整流程；parameters 空对象 = 零参数默认兜底（自动取真实数据）。
• 成功判定：响应 result.success === true。失败时含 step / error / stack —— 可直接展示体现透明度。
• 重能力员工异步：返回 { async:true, taskId, estimatedTime }，用 GET /api/digital-staff/tasks/ 轮询。
• 浏览器可点：GET /api/digital-staff/run?staffId=DS-BOSS-002&intent=

4.2 查询 / 协同 / 编队 / 事件 端点

| 端点 | 方法 | 说明 |

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

| /api/digital-staff/list · /staffs | GET | 员工清单 |

| /api/digital-staff/detail?id= | GET | 员工详情（含keywords/params） |

| /api/digital-staff/position/list | GET | 岗位 + 人类层 |

| /api/digital-staff/collaboration/rules | GET | 协作规则 |

| /api/digital-staff/collaboration/chain?staffId= | GET | 某员工的协同链路 |

| /api/digital-staff/collaboration/trigger | POST | 手动触发协作 |

| /api/digital-staff/taskforce/adhoc | POST | 发起跨岗位编队 |

| /api/digital-staff/taskforce/pending | GET | 待人工签字编队 |

| /api/digital-staff/taskforce/resume | POST | 签字后继续编队 |

| /api/digital-staff/taskforce/runs | GET | 编队运行历史 |

| /api/digital-staff/event/triggers | GET/POST/DELETE | 事件触发器管理 |

| /api/digital-staff/event | POST | 投递事件 |

| /api/digital-staff/event/stream | GET | SSE 实时事件流 |

| /api/digital-staff/loops | GET/POST | 定时循环任务 |

| /api/digital-staff/logs | GET | 执行日志 |

4.3 小程序前端补充端点（主服务器 3006 同样支持）

小程序端在上述 4.1 / 4.2 之外额外调用的端点，均已在后端实现：

| 端点 | 方法 | 用途 |

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

| /api/digital-staff/status | GET | 员工状态全量（详情页 getDetail 也从此拉取按 id 匹配） |

| /api/digital-staff/runs?staffId=&limit= | GET | 员工执行历史列表 |

| /api/digital-staff/run-detail?runId= | GET | 单次执行详情（events / summary） |

| /api/digital-staff/tasks/ | GET | 异步任务轮询（与 4.1 相同） |

| /api/digital-staff/pending-confirms | GET | 人在回路 · 待确认项列表 |

| /api/digital-staff/resume | POST | 恢复挂起执行（{ staffId, resumeId, choice }） |

| /api/digital-staff/config | GET/POST | 员工配置读写 |

| /api/staff/profile-update | POST | 员工档案保存（{ id, fields: { params, triggers } }，落盘 + 同步 DB） |

| /api/staff/banners | GET | 首页横幅 |

| /api/staff/match | POST | 员工关键词路由匹配 |

| /api/doc-agent/staff-capability/portrait/:id | GET | 能力画像：角色定位 / 核心能力 / 使用方式 / 最佳实践 / 数据来源（网页端「能力画像」弹窗、小程序「能力画像」区块同源，后端 staff_capability_portraits 表） |

| /api/digital-staff/:id/performance | GET | 绩效聚合：平均评分 / 成功率 / 执行次数 / 满意度 / 平均耗时 / 热门标签（网页端 staffPerf 区块、小程序「绩效」tab 同源，来自 staff-feedback-routes.js） |

说明：2026-08-12 修复——pending-confirms 此前被 server.js oldPaths 误拦导致 404（新路由有实现但被跳过），已移除该项；profile-update 此前后端无实现导致小程序 staff-detail 保存必 404，已新增端点接线 updateStaffConfig()（内存 + saveStaffConfig() 落盘 + syncMemoryToDb）。

说明（2026-08-15）：/api/digital-staff/list、/api/digital-staff/status 现均额外返回 hidden 字段（布尔），前端据此区分「活跃」与「已下架」；能力画像 / 绩效端点为本次新增，详见数字员工体验对齐节。

五、数字员工全量清单（71 人，按岗位分组）

图例：可协同 ✅ ｜ 自然语言可达 ✅ / 仅编排触发 🔒 / 无关键词 ➖ ｜ 消费行业 🌐

执行模式：worker 脚本 / capability / pipeline 流水线 / loop 定时循环 / generic 兜底

图例：可协同 ✅ ｜ 自然语言可达 ✅ / 仅编排触发 🔒 / 无关键词 ➖ ｜ 消费行业 🌐 ｜ 已下架 🔽（见下方清单，用户端不可见、管理端可见可上线）

执行模式：worker 脚本 / capability / pipeline 流水线 / loop 定时循环 / generic 兜底

⚠️ 已下架隐藏清单（18 人，2026-08-16）：以下员工因「能力错位（名不副实）/ 纯占位无执行体 / worker 已废弃」（详见 5.1 根因分析）被 HIDDEN_STAFF_IDS 收口，已从用户可见列表移除（网页端召唤区、小程序首页 / 数字员工 / AI 对话按 !hidden 过滤），但网页端管理控制台、小程序管理页仍展示并标注「已下架」、可随时重新上线。对应清单行已标 🔽。

📌 DS-ARAS-001 万能对象创建工程师已于 2026-08-16 从隐藏恢复可见——经验测其经 /api/digital-staff/run 返回真实「识别对象类型 → 确认创建」流程（type:confirm），名义与能力相符，属名副其实能力，非占位壳。

| 员工 ID | 名称 | 原归属岗位 | 下架原因 |

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

| DS-IMPORT-001 | 小臂-数据导入员 | POS-IT | capability 创建路径已迁移，worker 不可派发 |

| DS-REVIEW-001 | 小臂-文档校验员 | POS-QA | pipeline 已废弃 |

| DS-SUPPLY-001 | 小臂-供应链管家 | POS-STOCK | pipeline 已废弃 |

| DS-PROC-LOOP-001 | 小臂-价格监控员 | POS-PROCURE | loop worker 已废弃 |

| DS-BOSS-LOOP-001 | 小臂-目标追踪员 | POS-BOSS | generic 兜底无真实执行 |

| DS-VEN-LOOP-001 | 小臂-数据修复员 | POS-PROCURE | loop worker 已废弃 |

| DS-STOCK-LOOP-001 | 小臂-库存预警员 | POS-STOCK | loop worker 已废弃 |

| DS-INSPECT-001 | 小臂-数据巡检员 | POS-OTHER | pipeline 已废弃 |

| DS-REPAIR-001 | 小臂-数据修复员 | POS-EQUIP | pipeline 已废弃 |

| DS-ECO-001 | 小臂-变更分析师 | POS-OTHER | pipeline 已废弃 |

| DS-VALUATION-001 | 小臂-数据估值师 | POS-OTHER | pipeline 已废弃 |

| DS-COLLECT-001 | 小臂-数据采集员 | POS-EQUIP | pipeline 已废弃 |

| DS-IDENTIFY-001 | 小臂-资产识别员 | POS-OPERATOR | pipeline 已废弃 |

| DS-WORKFLOW-001 | 小臂-工作流助手 | POS-BOSS | pipeline 已废弃 |

| DS-ANALYTICS-001 | 小臂-数据分析助手 | POS-FINANCE | pipeline 已废弃 |

| DS-VISION-001 | 小臂-视觉分析助手 | POS-IT | pipeline 已废弃 |

| DS-WRITER-001 | 小臂-写作助手 | POS-BOSS | pipeline 已废弃 |

| DS-AUTO-LOOP-001 | 小臂-自动闭环会话员 | POS-OTHER | loop 已废弃 |

注：活跃可见员工 = 53（STAFF_DEFAULTS，含统一默认意图 + 参数默认值）。下架为软隐藏而非删除——条件具备（worker 修复 / 路径迁移完成）后即可重新上线，无需改代码。

5.1 下架根因分析（2026-08-16 修订）

当初为何会被添加

• 规划/演示阶段为展示"全场景覆盖"广度而批量登记：构想了大量细分场景员工（"小臂-X"系列 + 各类"助手"），覆盖 IT、数据、供应链、质量、财务、老板、IT管理员等。
• "通用壳套一切业务"的误判：设计思路是用两个通用 worker（kb-pipeline 知识库管道、news-worker 资讯检索）+ 通用 capability 动词（identify/generate/inspect/repair/compare/valuate）去套不同业务名，以为一个通用壳能覆盖所有场景，没意识到每个垂直场景都需要专属数据源 + 专属动作 + 专属模型。
• 演示期场景复用：同一 DS-ID 在 yaml 不同 profile 段挂到不同演示角色（GOAI 协同演示、老板助手、IT管理员助手等），是给演示搭场景占位，并非生产可用；部分在 yaml 中直接 worker: NONE，从未实现。
• 对接系统已废弃（仅历史背景）：DS-ARAS-001 曾指向 aras-creator，而 ARAS/Aras 已统一改名 SCSAI；但 2026-08-16 实测其经统一创建能力返回真实「识别对象类型 → 确认创建」流程（type:confirm），名义与能力相符，已恢复可见（不再属隐藏集）。

为何无法派发真实任务（主要问题，三类）

1. 能力错位（名不副实）：员工名义定位 ≠ 其 worker 真实能做的事，且 capability 在 worker 里无对应实现（这是 18 个隐藏员工的共同根因）。

• "价格监控员 / 库存预警员 / 数据估值师 / 数据巡检员 / 变更分析师"等（capability=identify/compare/valuate/inspect）指向 kb-pipeline，但该 worker 只认 collect/enrich/convert/all 四个 stage，本质是"触发行业知识库采集"（kb-pipeline-worker.js:101、:77 调 /api/kb/:industry/trigger），既不抓价、也不预警、也不估值。
• "视觉分析 / 写作 / 数据分析助手"指向 news-worker，但它只是"按 topic 检索资讯+生成摘要"，且真实新闻 provider 返回 null（news-worker.js:25，无真实新闻 API），做不了视觉识别 / 专业写作 / 深度数据分析。
• "数据导入员"指向 system-health（系统健康检查）、"自动闭环会话员"指向 plm-brain，定位与能力风马牛不相及。

1. 纯占位无执行体：一批"助手"在 yaml 中 worker: NONE，没有任何执行脚本，路由引擎选中后无处可派。
2. capability 与 worker stage 脱节：员工宣称的 identify/generate/inspect/repair/compare/valuate 在对应 worker 里没有实现路径，路由即便选中也无法产出确定性业务结果，只会落到通用兜底或空转。

⚠️ 复盘纠正（2026-08-16）：早前把隐藏理由笼统写成"无注册 worker / worker 已废弃"并不准确——这 18 个 worker 多数能跑通（HTTP 200），但产出的是错位 / 空转 / 失败结果（如 DS-VISION-001 实测 success:false、DS-BOSS-LOOP-001 返回"目标未达成"空转、多数 rule_engine 通用识别空跑）。HTTP 200 ≠ 结果正确。真正该下架的是"名不副实、挂羊头卖狗肉"的占位结果，而非"跑不动"。DS-ARAS-001 因返回名副其实的对象创建确认流程，不在此列，已恢复。

结论：这 18 个（DS-ARAS-001 已于 2026-08-16 恢复）不是 bug，而是规划/演示占位、能力错位的产物。要重新上线，须为具体场景补齐专属数据源 + 动作（如"价格监控员"真去抓价/比对/预警、"视觉分析"接视觉模型），而非靠通用壳。当前软隐藏保留，条件具备可逐个补执行体后上线。

老板助手 （POS-BOSS）｜ 人类负责人：企业负责人 / 总经理 ｜ 6 人

芯片设计工程师助手 （POS-CHIP）｜ 人类负责人：芯片设计工程师 / 设计主管 ｜ 7 人

设备管理员助手 （POS-EQUIP）｜ 人类负责人：设备管理员 / 维修主管 ｜ 2 人

财务助理助手 （POS-FINANCE）｜ 人类负责人：成本会计 / 财务负责人 ｜ 2 人

GOAI多Agent协同演示 （POS-GOAI）｜ 人类负责人：车间主任（演示场景） ｜ 3 人

巡检修复闭环演示 （POS-INSPECT-LOOP）｜ 人类负责人：质量主管（演示场景） ｜ 3 人

IT管理员助手 （POS-IT）｜ 人类负责人：IT管理员 / 系统负责人 ｜ 6 人

市场营销助手 （POS-MARKETING）｜ 人类负责人：市场专员 / 营销负责人 ｜ 3 人

操作工助手 （POS-OPERATOR）｜ 人类负责人：岗位操作工 / 班组长 ｜ 4 人

POS-OTHER （POS-OTHER）｜ 人类负责人：— ｜ 12 人

工艺工程师助手 （POS-PROCESS-ENG）｜ 人类负责人：工艺工程师 / 技术主管 ｜ 5 人

采购专员助手 （POS-PROCURE）｜ 人类负责人：采购专员 / 采购经理 ｜ 4 人

采购闭环协同演示 （POS-PROCURE-CHAIN）｜ 人类负责人：采购经理（演示场景） ｜ 4 人

质量管理员助手 （POS-QA）｜ 人类负责人：质量管理员 / 质量经理 ｜ 4 人

生产调度助手 （POS-SCHEDULER）｜ 人类负责人：生产调度员 / 车间主任 ｜ 4 人

库存管理员助手 （POS-STOCK）｜ 人类负责人：仓库管理员 / 物料计划员 ｜ 2 人

六、自然语言触发词速查

• 芯片家族（芯智系列）专属直达词（已规避"生成/创建/修复"等通用动词被抢占）：
• 芯智识别、芯智RTL设计、芯智代码排错、芯智代码差异、芯智PPA分析、芯智验证、芯智端侧
• 工艺优化 → 芯智工艺优化；质量工艺互通 → 芯智质量工艺互通
• 通用直达：直接说"生成报告"→DS-BOSS-001、"巡检"→DS-BOSS-002、"采购"→DS-PROC-001、"成本"→DS-COST-001、"知识库"→DS-KNOWLEDGE-001 等（详见 server/boss-scheduler/staff-router.js 的 STAFF_KEYWORDS）。
• 🔒 编排节点（请勿自然语言直呼，由定时/流水线/编队触发）：DS-STOCK-LOOP-001、DS-GOAI-PROC、DS-PROC-CHAIN-001、DS-COST-CHAIN-001、DS-VEN-CHAIN-001、DS-INSPECT-CHAIN-001、DS-REPAIR-CHAIN-001。
• 🔒 同 worker 别名（按 staffId / 意图 aras_sync 调用）：DS-DATA-001（≡DS-BOSS-001）、DS-SYS-001（≡DS-BOSS-002）。

七、演示编排示例（跨岗位编队）

POST /api/digital-staff/taskforce/adhoc
{
  "title": "采购-成本-质量闭环演示",
  "members": ["DS-PROC-001", "DS-COST-001", "DS-VEN-001"],
  "sharedBlackboard": { "partNo": "P-1001", "qty": 50 },
  "requireHumanApproval": true
}

返回 runId，可在 /taskforce-ui.html 实时查看分层 DAG、共享黑板与分歧仲裁；人工签字后 POST /api/digital-staff/taskforce/resume 继续。

八、本轮审计修复记录（2026-08-11）

数字员工体验对齐与软隐藏机制（2026-08-15 变更）

本轮在不改业务逻辑的前提下，收敛「网页端 / 小程序端 / 数字员工配置」三处体验，统一为一套真相源，并确保小程序端体验 不低于 网页端。

A. 软隐藏（做不到就下架，但可随时上线）

• 单一真相源：server/boss-scheduler/staff-router.js 导出 HIDDEN_STAFF_IDS（18 个，能力错位 / 纯占位 / worker 已废弃，无法派发真实任务；DS-ARAS-001 已于 2026-08-16 恢复）。
• 后端收口：handleBanners 与 matchStaff 均跳过 HIDDEN_STAFF_IDS；/api/digital-staff/list、/api/digital-staff/status 给每个员工附加 hidden 布尔字段。
• 用户端隐藏 / 管理端可见：网页端召唤区、小程序首页 / 数字员工 / AI 对话按 !hidden 过滤；网页端管理控制台、小程序管理页展示全部并标注「已下架」、可重新上线（隐藏 = 软下架，非删除）。
• 下架清单与原因见第五节「已下架隐藏清单」。

B. 统一默认意图 + 可视化参数默认值（一套逻辑）

• 每个活跃员工在 STAFF_DEFAULTS 中给出：与定位完全匹配的默认意图（intent）+ 结构化参数（params，含 default、类型、选项）。
• 优先级：STAFF_DEFAULTS(staffId) > STAFF_BANNERS(worker) > 兜底；网页端 / 小程序统一消费 GET /api/staff/banners，消除此前端硬编码 maps、小程序走后端两套逻辑漂移。
• 效果：用户点开任意活跃员工即有「有意义的默认意图 + 可改参数」，零配置即可一键真实执行。

C. 能力画像（网页端 / 小程序同源）

• 端点 GET /api/doc-agent/staff-capability/portrait/:id（数据来自 staff_capability_portraits 表）。
• 网页端以「能力画像」弹窗展示；小程序 staff-detail 以「能力画像」区块（角色定位 / 核心能力 / 使用方式 / 最佳实践 / 数据来源）聚合展示，单页可读性强于网页弹窗。

D. 绩效（网页端 / 小程序同源）

• 端点 GET /api/digital-staff/:id/performance（来自 staff-feedback-routes.js）。
• 网页端 staffPerf 区块；小程序 staff-detail 新增「绩效」tab（平均评分 / 成功率 / 执行次数 / 满意度 / 平均耗时 / 热门标签）。

E. 对齐原则

• 配置统一：所有员工可视化参数 / 默认意图来自同一份 STAFF_DEFAULTS。
• 体验一致：网页端有的能力画像、绩效，小程序全有；小程序在「单页聚合」上做得更紧凑。
• 诚实口径：做不到真实效果即下架隐藏，管理员可一键恢复，绝不展示无法落地的员工。

F. 多端统一（WEB 端 / 小程序端，2026-08-16 确认）

• 单一真相源 = 后端 staff-router.js：员工清单 /api/staff/banners、下架/隐藏、执行 /api/digital-staff/run、能力画像 /api/doc-agent/staff-capability/portrait/:id、绩效 /api/digital-staff/:id/performance 均由同一后端提供，WEB 端与小程序端共用，不存在两套员工目录或两套隐藏逻辑。
• 清单一致：两端主列表均消费 /api/staff/banners，该端点服务端按 HIDDEN_STAFF_IDS 过滤——下架即两端同时不可见（DS-ARAS-001 恢复后两端同时可见），不可能各搞一套。两端源码中出现的硬编码 DS-* 仅为 UI/参数便捷分支，非可见性判断。
• 执行一致：两端调同一个 /api/digital-staff/run，结果由后端 runOnce → _runWorker 单一决定，响应体完全相同。
• 仅 UI 两套：网页端弹窗式、小程序页签式属渲染差异（用户豁免的"UI 两套"）；WEB 的 /api/staff/match 仅为免费文本输入补全辅助，不改底层结果。给定相同显式参数，两端体验结果完全一致。

九、已知边界与优化项（诚实列出，非缺陷）

1. 行业消费尚未全面落地：仅 4 个员工真正按行业维度消费数据（DS-KBPIPE-001、DS-DOC-001、DS-KNOWLEDGE-001、DS-PROC-DATA-001）。行业坐标系（5 行业）已建，但 worker 层"按行业批跑"仍在推进（任务 #5/#11）。
2. 🔒 9 个编排/别名节点不自然语言直呼：设计如此，由定时/流水线/编队触发。
3. 4 个孤儿 worker 文件：无员工使用，无害，建议清理或标注（见第八节）。
4. DS-ARAS-001 对象创建路径：曾走 aras-creator（DEPRECATED，已统一改名 SCSAI）；2026-08-16 实测其经统一创建能力返回真实对象创建确认流程（type:confirm），已恢复可见。确认「确认创建」后端连通性以发布后实际点击为准。
5. 磁盘空间是头号伪装故障：C 盘接近满时 SQLite 会静默 disk I/O error 且进程无报错退出，极像"跑完了"。演示前务必 df -h 确认空间。
6. 运行时显示 73 ≠ 配置 71：CMS 控制台列表（GET /api/digital-staff/list）返回 73，因含 2 个系统内置 / DB 持久化员工 DS-DQ-001（数据质检）、DS-EVO-001（自进化）。yaml 的 71 个已 100% 加载到运行时（无遗漏），详见第一节数字口径说明。
7. 18 个员工已下架隐藏（2026-08-16）：HIDDEN_STAFF_IDS 收口的 18 个员工（能力错位 / 纯占位 / worker 已废弃，详见 5.1）不再出现在用户可见列表，但管理端可见可上线；活跃可见员工收敛为 53（STAFF_DEFAULTS）。DS-ARAS-001 已于 2026-08-16 恢复。这是「做不到真实效果就下架」的诚实口径，非缺陷。

十、故障排查

十一、外部系统集成与可调用性（实测结论）

本轮对全部数字员工接口做了真实 HTTP 抓包验证：接口本身功能正确（list/run/loops/goals/配置 CRUD 均返回正确数据）；但"外部能否直调"取决于客户端类型与走哪套路由。已修复 CORS 不统一问题，现状如下。

11.1 网络暴露

• 服务 server.listen(config.port) 未指定 host → 绑定 0.0.0.0 / [::] 全网卡（非 localhost-only），LAN 内可达；公网暴露需防火墙 / 端口转发 / 反代。

11.2 CORS（浏览器跨域）

• 已统一：所有 /api/digital-staff/ 接口（含新 CRUD 模块 list / loops / goals / :id/enable / :id/rules-prompts，及旧 inline 接口）响应均带 Access-Control-Allow-Origin: ，OPTIONS 预检返回 204 + CORS。
• 修复前：新 CRUD 模块响应缺 CORS 头 → 浏览器跨域调 list/loops 等会被拦截。已在 server/routes/digital-staff-routes.js 的 _json 写出处补齐。
• 结论：浏览器版 Web CMS 现在可跨域直调全部数字员工接口。

11.3 鉴权现状（开放平台 KEY + 双轨制，MVP 已决策）

• 开放平台 KEY 机制已落地（server/routes/open-platform.js），覆盖两类对外路由：/api/goai-demo/（协同闭环）、/api/agents/（Agent Card 接入）。机制包含：
• POST /api/open/keys 申请 Key（返回 ba_xxx_xxx_xxx 格式）、GET /api/open/spec 返回 OpenAPI 3.0 规范、GET /api/open/usage 查调用统计。
• 认证支持 X-API-Key: 或 Authorization: Bearer ；按 Key 做限流（free=30、pro=120、enterprise=600 次/分钟）与调用审计（写 api_usage 表）。
• 启动注入 2 个种子 Key（demo / goai-review，默认 free / pro 档）。
• 无效 / 过期 Key → 401 拒绝（实测 X-API-Key: ba_invalid → 401），有效 Key → 放行并审计。
• 🟢 双轨制（设计如此，非缺陷；2026-08-12 已决策）：server.js:4126 的逻辑是「带 ba_ 前缀 Key → 走开放平台鉴权 + 限流 + 审计；不带 Key → 维持原有内部逻辑不变」。两条明确轨道：
• 外部 API 调用（带 ba_ Key） → 鉴权 + 限流 + 计费（审计入库）。
• 内部前端调用（无 Key） → 原有逻辑不变，前端无需任何改造。
• 当前 MVP 即采用此双轨；若将来要统一管控，只需在 src/utils/api.js 加一行 headers['X-API-Key'] = localStorage.getItem('bossagents_api_key') 即可，无需前端重构。
• **71 个原始数字员工接口 /api/digital-staff/* 未接开放平台网关：这是有意为之的内部分量，面向内网 / 127.0.0.1；公网暴露须走 nginx 反代收敛（见 11.5 / 12.2）。
• 两套 Key 不互通：开放平台 Key（DB 表 api_keys）与 server/middleware/auth.js 的 JWT 是两套独立体系，后者未挂载到任何路由。

11.4 各客户端直调能力矩阵（双轨制）

11.5 推荐集成姿势

1. 外部企业接入走开放平台主链路**：申请 Key → 带 X-API-Key 调 /api/goai-demo/* 协同闭环（内部自动编排 71 数字员工）。这是对外唯一应暴露的入口。
2. 首选后端中继：CMS 后端持有 Key 调用 bossagents（避开浏览器 CORS / 鉴权复杂度），前端只跟自己后端通信。
3. 小程序 / 公网：nginx 终止 TLS（443）→ 反代 http://127.0.0.1:3006，MP 后台加白域名；走开放平台 Key，勿暴露原始 digital-staff 端口。

11.6 开放平台接入指南（实测可用）

1) 申请 Key

curl -X POST http://<host>:3006/api/open/keys -H "Content-Type: application/json" -d '{"customer_id":"your_corp","name":"贵司名称","plan":"pro"}'
# => {"success":true,"api_key":"ba_xxxx_xxxx_xxxx","plan":"pro","rate_limit":120}

2) 带 Key 调用协同闭环（编排数字员工）

curl -X POST http://<host>:3006/api/goai-demo/collaboration/goai -H "X-API-Key: ba_xxxx_xxxx_xxxx" -H "Content-Type: application/json" -d '{"instruction":"把本月采购申请汇总成待办"}'
# 或：Authorization: Bearer ba_xxxx_xxxx_xxxx

3) 查询调用统计（需 Key）

curl "http://<host>:3006/api/open/usage?days=7" -H "X-API-Key: ba_xxxx_xxxx_xxxx"

4) 查看完整规范

curl http://<host>:3006/api/open/spec

限流：free 30 / pro 120 / enterprise 600 次/分钟（按 60s 滑动窗口 api_usage 计数，超限返回 429 + retry_after:60）。无效 / 过期 Key 返回 401。

11.7 真实编排验证（本机实测）

• POST /api/goai-demo/collaboration/goai 带有效 demo Key → HTTP 200，耗时 22.9s，返回 trace_id 并真实编排数字员工（如 DS-GOAI-SCHED 任务拆解、采购 / 保养提醒等），证明开放平台 Key → goai-demo 协同 → 71 数字员工链路贯通。
• GET /api/goai-demo/positions 带有效 / 无效 Key → 200 / 401（区分正确）。返回 3 个协同演示岗位：goai（POS-GOAI，agents=3）、procure（POS-PROCURE-CHAIN，agents=4）、inspect（POS-INSPECT-LOOP，agents=3）。
• POST /api/open/keys → 201 真实写入 api_keys 表；GET /api/open/usage 需 Key（无 Key → 401）。

11.8 端到端测试（E2E，2026-08-12，7/7 全部通过）

| # | 测试项 | 期望 | 实测 | 说明 |

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

| 1 | OpenAPI 规范 | 3.0 / v1.0.0 | ✅ | GET /api/open/spec 返回 OpenAPI 3.0.3 |

| 2 | 申请 API Key | 返回 ba_* | ✅ | POST /api/open/keys → ba_xxxx_xxxx_xxxx |

| 3 | 有效 Key 访问 | 200 + 3 岗位 | ✅ | GET /api/goai-demo/positions 带 Key → 3 个演示岗位 |

| 4 | 无效 Key 拒绝 | 401 | ✅ | X-API-Key: ba_invalid → 401 |

| 5 | 无 Key 内部访问 | 200（前端不受影响） | ✅ | 双轨制：无 Key 维持原逻辑 |

| 6 | 调用统计 | 有记录 | ✅ | GET /api/open/usage 返回各端点 calls 记录 |

| 7 | 文档页 | 200 | ✅ | GET /api/open/docs → 200，约 13 KB（api-docs.html） |

以上 7 项经独立复验全部通过；第 5 项证实双轨制下内部前端无需改造已落地。

十二、开放平台安全边界（已决策 + 部署建议）

12.1 goai-demo/agents 双轨制 → 是否强制 Key？

• 决策（2026-08-12）：MVP 采用双轨制，不强制 Key。理由：内部前端无 Key 直调维持原逻辑、零改造；外部带 Key 自动鉴权 + 限流 + 审计。
• 现状：server.js:4126 — 仅当请求携带 ba_ 前缀 Key 时才走 openPlatform.middleware 校验；无 Key 直接放行（200）。这正是双轨制的实现点，非缺陷。
• 未来可选强化：若要做统一管控，删除 else 放行分支使未带有效 Key 一律 401，并在 src/utils/api.js 注入 X-API-Key 即可，改动量极小。

12.2 原始数字员工接口 /api/digital-staff/* 是否纳入网关？

• 现状：71 个底层接口（list/run/config/loops…）完全无 Key 鉴权，实测无 Key 直调 run 也能真实执行数字员工。这是有意为之的内部分量（内网 / 127.0.0.1）。
• 部署建议（推荐，零代码改动）：production 仅暴露开放平台入口（nginx 反向代理 /api/goai-demo、/api/agents、/api/open），不转发 /api/digital-staff；原始接口只允许 127.0.0.1 / 内网。
• 强管控补充（可选）：若需代码层管控，在 server.js 数字员工 dispatch 入口加 openPlatform.middleware（或 softAuth）要求 Key，并给内部 CMS 配 Key 或加内网 IP 白名单。

12.3 两套鉴权体系说明

• 开放平台 Key（api_keys 表，前缀 ba_）与 server/middleware/auth.js 的 JWT 相互独立。当前 JWT 中间件未挂载到任何路由。

十、产品定位与现状自查（2026-08-15）

定位原则（来自产品决策）

• 工业智能体不是闹着玩，求精不求多：只保留 / 精做能产出真实效果的员工，绝不挂凑数垃圾，避免"挂着一堆垃圾反而丢人、让人添堵"。
• 通用能力（内容 / 文档 / 营销 / 客服）要做到比专门做这些的工具还好、还有特色，并免费送，作为获客与差异化的出路。
• 下架为软隐藏而非删除：用户端不可见、管理端可见可上线，条件具备即恢复。WEB 端与小程序端共用同一后端真相源，仅渲染 UI 两套（见数字员工体验对齐节 F）。

53 个活跃员工自查结论（本轮"再仔细检查"）

• 硬指标：53 个活跃员工（STAFF_DEFAULTS）全部指向真实存在且导出 run 的 worker 文件，无"worker 缺失 / 不导出"类硬伤（已用脚本逐一核对 worker 文件存在性与 module.exports）。
• 抽样验证真实可派发性（非壳）：
• GOAI 系列 + 巡检闭环（共 7 个）共用 goai-agent-worker，真实调用 callLLM + 每个员工专属 systemPrompt 产出结构化 JSON，非壳。
• 内容 content.js、文档 doc-worker.js、营销 mkt-worker.js、客服 customer-service-worker.js 均接真实内容中心 / 文档引擎 / LLM 生成，非壳；doc-worker.js:108 明确"doc-engine 不可用时返回明确错误，不返回占位数据"（诚实优先）。
• DS-ARAS-001（2026-08-16 恢复）：实测返回真实对象创建确认流程，名实相符，非壳。
• 结论：当前活跃集无那 18 个同款"名不副实 / 纯占位"垃圾。

通用能力四方向现状

| 方向 | 员工 | 现状 | 行动 |

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

| 内容 | DS-CONTENT-001 内容生成师 | ✅ 接内容中心 + LLM，真实生成（refine/publish） | 做精、免费送 |

| 文档 | DS-DOC-001 文档数字员工 | ✅ 接 doc-engine，诚实报错不占位 | 做精、免费送 |

| 营销 | DS-MKT-001 营销助手 | ✅ 接营销引擎 / LLM 生成线索 | 做精、免费送 |

| 资讯 | DS-NEWS-001 资讯助手 | ⚠️ 诚实空壳：未接资讯源时如实返回"未配置"，无真实产出（news-worker.js:25） | 接入 NEWS_API_KEY 做精，或暂下架 |

| 客服 | DS-CS-001 客服数字员工 | ✅ 已落地：LLM 驱动对话，识别意向/留资并自动写入线索（server/data/leads.json），引导体验/购买；网页与小程序经 /api/digital-staff/run 共用同一员工 | 做精、免费送（2026-08-15 新增） |

待办建议

1. DS-NEWS-001：接入真实资讯源（RSS / NewsAPI，配置 NEWS_API_KEY）后做精免费送；若暂不接源，建议与 18 个一并软隐藏，避免"挂着没用"观感。
2. 客服数字员工 DS-CS-001：已于 2026-08-15 落地（见上表）。LLM 对话 + 线索自动落地 + 引导体验/购买，网页/小程序复用同一员工，免费送的差异化能力已具备基础实现。
3. 持续原则：新增 / 保留员工必须满足"真实派发、名实相符、效果可验证"，否则下架。