主题
00 - 企业员工数字分身：方案总纲
一句话：以“一人一实例”为最小隔离单位，把 QwenPaw 的单机运行时原样封进 Pod 与三卷 PVC，千人千面、密钥治理、生命周期全部外置给控制面；换来的是每条请求都要经网关把 SSO 身份换成 Runtime Token，成本随在职人数线性上升，只能靠暂存回收算力，而数据一旦与员工绑定，离职交接与清理就成了不可回避的硬约束。
一、我们要解决什么问题
企业里每个员工都配一个专属 AI 助手实例——它记住这个员工的工作上下文、掌握这个员工需要的技能工具、能代替这个员工执行具体任务。这就是"员工数字分身"。
与传统"一个共享 ChatBot 服务全员"的方案不同，数字分身强调千人千面、数据隔离、能力独立：每个实例拥有独立的会话记忆、技能配置、执行产物，互不干扰。
核心诉求：
| 诉求 | 含义 |
|---|---|
| 千人千面 | 每个员工的实例独立隔离，记忆、技能、产物互不干扰 |
| 零配置上手 | 员工不需要懂模型、API Key、Agent 配置——平台预置好，开箱即用 |
| 随处可达 | 企业 IM（飞书/企微/钉钉）@ 机器人即用，Web 控制台也能用 |
| 安全合规 | 密钥不进实例、操作全量审计、数据随人走随人清 |
| 成本可控 | 闲置实例自动暂存省资源，按员工配额计量控成本 |
二、QwenPaw 是什么
QwenPaw 是一个开源 AI Agent 平台，提供以下核心能力：
- 多 Agent 运行时：每个实例可运行多个 Agent（编码助手、QA 助手等），每个 Agent 有独立的会话、记忆、技能
- ACP 协议（Agent Communication Protocol）：Agent 之间可以互相委托任务（如主 Agent 委托 opencode 执行编码任务），通过 stdio 通信
- Skill 体系：Agent 能力以 Skill 包形式扩展，支持市场搜索、安装、启用
- MCP 客户端：实例可连接外部 MCP Server（Model Context Protocol），调用外部工具
- Console UI：内置 Web 控制台，提供对话、会话管理、配置界面
- Backup/Restore：实例工作区支持逻辑备份与恢复
本方案的定位：以 QwenPaw 开源运行时为底座，在其之上构建企业级控制面——统一网关、多租户生命周期管理、渠道聚合、安全审计——将一个"单机自用"的 Agent 平台改造为"企业千人千面"的数字分身产品。控制面代码随本方案一起开源。
三、总体架构
架构分层说明
| 层 | 职责 | 核心组件 |
|---|---|---|
| 员工入口层 | 员工通过 Web、IM、定时任务等入口发起请求 | 浏览器、IM 客户端、调度系统 |
| 统一网关层 | 身份认证、流量路由、协议适配、限流审计 | Higress（AI 网关）、渠道聚合器 |
| 产品控制面 | 实例全生命周期管理、密钥治理、分发编排、配额计量 | FastAPI 控制面（开源）、PostgreSQL、Redis、Vault |
| K8s 实例集群 | 每个员工一个独立 Pod，运行 QwenPaw Agent 运行时 | StatefulSet + PVC ×3 + NetworkPolicy |
| 基础设施层 | 持久化存储、服务发现、缓存、镜像仓库 | PostgreSQL、Redis、Nacos、MinIO、Harbor |
| 可观测性 | 监控、日志、链路追踪、告警 | Prometheus、Grafana、Loki、OpenTelemetry |
四、核心设计原则
原则一：两条通道，权限分离
| 通道 | 流量来源 | 认证方式 | 用途 |
|---|---|---|---|
| 用户通道 | 员工（Web/IM/定时任务） | SSO JWT → 网关换发内部身份 → RT 注入 | 对话、任务下发、审批 |
| 平台通道 | 产品控制面 | RT 直连（控制面持有 RT） | 生命周期管理、配置下发、市场分发、产物取回 |
实例只认 RT（Runtime Token），不认 SSO JWT、不认用户密码。网关是唯一将 SSO 身份转换为 RT 的节点。
原则二：契约化接入
企业 Skill / MCP Server 只需满足契约规范即可接入，无需定制开发：
- Skill 契约：符合
HubSkillSpec格式 + 包含SKILL.md→ 控制面自动分发到实例 - MCP 契约：暴露标准 MCP 端点（stdio/streamable_http/sse） → 控制面创建 client + 工具白名单
原则三：实例即员工
一个员工 = 一个实例。绑定关系在三处保持一致：
所有路由、下发、审批、产物、审计都以这个映射为准。
原则四：数据生命周期 = 员工生命周期
| 员工状态 | 实例状态 | 数据状态 | 资源消耗 |
|---|---|---|---|
| 在职活跃 | Active（Pod 运行） | 数据在三卷 PVC 中，实时可访问 | CPU + 内存 + 存储 |
| 在职闲置 | Staged（Pod 停止，PVC 保留） | 数据在 PVC 中，秒级恢复 | 仅存储 |
| 长期闲置 | Staged（归档到对象存储） | 数据在对象存储，分钟级恢复 | 仅归档存储 |
| 离职 | Retired（Pod 删除，PVC 清理） | 数据交接归档后清理 | 无 |
原则五：敏感信息零暴露
| 信息类型 | 存储位置 | 谁可见 |
|---|---|---|
| 模型 API Key | Vault + K8s Secret → 实例 secrets 卷 | 控制面、实例进程 |
| RT Token | Vault → 网关内存缓存 → 请求头注入 | 控制面、网关 |
| 企业 IM 凭证 | Vault → 渠道聚合器运行时 | 控制面、聚合器 |
| 员工密码 | 不存在（SSO 认证，无实例登录） | — |
员工在任何界面都看不到任何密钥或凭证明文。
五、技术选型
| 组件 | 选型 | 理由 |
|---|---|---|
| 容器编排 | Kubernetes ≥ 1.26 | 生产标准，StatefulSet / PVC / NetworkPolicy 原生支撑 |
| API 网关 | Higress | K8s 原生 AI 网关，支持 SSE 透传、插件扩展、Nacos 对接 |
| 服务发现 | Nacos | Higress 原生对接，支持 metadata 路由 |
| 控制面框架 | Python FastAPI | 与 QwenPaw 同生态，开发效率高 |
| 控制面数据库 | PostgreSQL | 多租户、事务、JSON 字段，生产级可靠 |
| 缓存/限流 | Redis | 分布式限流、会话缓存、配额计量 |
| 密钥加密 | Fernet 对称加密 | 借鉴 QwenPaw hub TenantCredentialVault，已验证 |
| 对象存储 | MinIO（私有）/ 阿里云 OSS | 备份归档、产物交付 |
| 身份认证 | OIDC（Keycloak / Casdoor / 企业 AD） | 标准协议，企业已有身份体系对接 |
| 企业 IM | 飞书 / 企微 / 钉钉适配器 | 覆盖主流企业 IM |
| 镜像仓库 | Harbor | 私有镜像管理，漏洞扫描 |
| 监控 | Prometheus + Grafana | K8s 标准监控栈 |
| 日志 | Loki + Promtail | 轻量日志采集 |
| 链路追踪 | OpenTelemetry | 统一 trace_id 贯通全链路 |
| 告警 | Alertmanager → 企业 IM / 邮件 | 复用通知通道 |
| 灰度发布 | Argo Rollouts | K8s 原生金丝雀发布 |
六、实施路线
分四个阶段，每阶段可独立交付价值：
七、章节导航
| 章 | 主题 | 核心问题 |
|---|---|---|
| 01 | QwenPaw 底座 | 实例内部长什么样、Agent / Skill / MCP / ACP 如何工作 |
| 02 | 总体架构 | 各层如何协作、数据如何流转 |
| 03 | 统一网关 | SSO 认证、身份路由、RT 注入、限流、SSE 透传 |
| 04 | 渠道对接 | IM 消息归一化、身份映射、会话映射、产物回传 |
| 05 | 实例管理 | 创建流程、三处绑定、生命周期状态机、暂存/恢复/回收 |
| 06 | 存储架构 | 三卷 PVC、数据分级、备份归档、产物交付 |
| 07 | Skill/MCP 接入 | 契约规范、市场分发、工具白名单 |
| 08 | 审批通知 | HITL 事件、通知推送、审批回传、超时策略 |
| 09 | 任务下发 | 入站规范、SSE 事件流、产物取回、IM 回传 |
| 10 | 安全审计 | 五层安全模型、密钥治理、全链路审计、数据安全 |
| 11 | 操作收敛 | 配置预置、敏感屏蔽、入口收口、员工自选 |
| 12 | 控制面实现 | 模块设计、API 面、数据模型、开源实现 |
| 13 | 可观测性 | 三层监控、告警规则、虚 SK 计量、行为审计 |
| 14 | 自举部署 | K8s 原生部署、post-init、灰度发布、灾备 |