主题
14｜包皮总体架构与统一入口网关需求（对标百炼的落地施工图·上）
一句话：把"对标阿里百炼自建企业智能体平台"从架构讨论收敛为可施工的包皮需求——本系列（14/15/16）给出 Java 模块划分、页面地图、API 面、权限模型、数据模型、接线点与里程碑。本篇（14）先钉死包皮总体架构与统一入口网关产品级需求，作为 15/16 篇模块清单的模式锚。 定位：承接 32 篇（HiMarket 集成接线设计）与 33 篇（统一体验层设计）的定论——HiMarket 是控制面/门户接入的底座（包皮层），包皮 = HiMarket fork 扩展（Java 模块 + 页面配套），不再自研平行实现；数据面仍由 Higress 承担。本文把"包皮要长什么样"落成施工图。 口径：HiMarket 信息来自官方文档（higress.io/docs/himarket，2026-09 更新，32 篇 §1）；百炼能力面对标基准来自官方（docs.bailian.console.aliyun.com，2026-10 抓取，详见 §0.3）；agentscope 机制来自本地源码（official-main，d04529e9）。本文为生产目标态设计，不是生产验收结论；落地准入以
05的 P0/P1/P2 闸门与06的证据台账为准。文中“已实证”只按 E1（源码/接口）或 E2（单机 POC）解释。
〇、使用说明（本系列的打开方式）
0.1 三篇分工与依赖
| 篇 | 内容 | 读者动作 |
|---|---|---|
| 14（本篇） | 包皮总体架构（Java 模块 + 页面地图 + 接线图）+ 统一入口网关需求 + 全系列规范（模板/术语/mermaid 规则） | 先读：确定骨架与所有模块的公共约束 |
| 15 | 按百炼能力面的模块需求清单（上）：Agent 开发运行（Managed Agent / Flow Agent / Sandbox / Playground）+ Agent 上下文（RAG / Memory / Connector / ParseX） | 按需：每个模块 = 功能点/页面/API/权限/数据模型/接线/优先级 |
| 16 | 模块需求清单（下）：治理与进化（Evolution / Security）+ Store（MCP / Skill / Application）+ 权限与审计统一模型 + 实施路线（里程碑）+ 对标总表 | 收口：统一模型 + 里程碑排期 + 全量对标 |
0.2 术语表（全系列统一，出现即按此义）
| 术语 | 定义 | 出处 |
|---|---|---|
| 包皮 / 包皮层 | HiMarket fork 扩展出的统一门户与各能力管理面（Java 模块 + 页面配套），对用户呈现为"一个入口、一套身份、一个市场、一套计量" | 03 篇 §7、32 篇 §2 |
| 接入层 | 与包皮层同义（33 篇曾用"接入层/体验层"）；32 篇 §2 定论：HiMarket 即接入层，自研收敛为定制增量 | 32 篇 §2 |
| 统一入口网关 | Higress（AI 网关）+ 自研 ext_authz/wasm 模块，承担认证/路由/注入/限流/审计/状态感知 10 项能力 | 08-03 篇 |
| 能力面 | 对标百炼控制台导航的最小管理域，13 项能力矩阵的划分依据 | 主线 KPI 矩阵 |
| 接线点 | 包皮模块与既有资产（HiMarket/Higress/Nacos/agentscope/RAGFlow/mem0/QwenPaw）之间的契约位置 | 32 篇 §3/§4 |
| 元数据权威 | 包皮层是 Agent 配置发布态的唯一权威（definition 快照 + 资产版本关联），agentscope 只做运行态 | 32 篇 §3.6 |
| 员工 / 管理员 / 审计 | 三角色权限模型：员工=使用+自建；管理员=管理面+审批；审计=只读+证据链 | 08-03 篇 §7、本篇 §四 |
0.3 百炼能力面对标基准（可追溯来源）
本系列所有"百炼有 X"的表述，均以阿里云百炼官方文档站
docs.bailian.console.aliyun.com（2026-10-25 抓取站点地图 llms.txt，全文 73KB）与帮助中心help.aliyun.com/zh/model-studio（2026-10-10 更新）为来源；具体章节在 15/16 篇对标表内逐行标注 URL。
| 对标基准 | URL | 覆盖 |
|---|---|---|
| 百炼文档站 llms.txt（站点地图） | https://docs.bailian.console.aliyun.com/llms.txt | 全站章节索引：模型/Token Plan/推理/评测/应用/知识库/记忆库/观测/安全 |
| 百炼使用指南（应用创建/配置/体验与发布） | https://help.aliyun.com/zh/model-studio/multimodal-guidelines/ | 应用工作台三层流程 |
| 百炼知识库 | https://help.aliyun.com/zh/model-studio/rag/ | 知识库创建/同步/API/渠道/日志监控/计费 |
| 百炼记忆库 | https://help.aliyun.com/zh/model-studio/memory/ | 记忆库概览/创建删除/观测（对照 12 篇机制精读） |
| 百炼应用评测/应用观测 | 站点地图"应用评测/应用观测"章节（URL 见 15/16 篇） | 评测任务/轨迹数据/观测指标 |
| 百炼 Managed Agents API | 站点地图"Managed Agent API"章节 | Skill 挂载/密钥库/会话/部署（对照 33 篇 §6.2） |
一、包皮总体架构
1.1 包皮是什么（定论引用）
- 32 篇 §2 六层角色：身份层（企业 SSO）→ 接入层（HiMarket = 控制面/门户接入，包皮层是其产品化扩展）→ 内容/配置层（Nacos）→ 流量层（Higress）→ 执行层（agentscope-service）→ 模型层。包皮是“接入层”的产品化落地，不等于数据面入口；所有业务流量仍由 Higress 承载。
- 32 篇 §3.6 元数据权威：Agent 配置发布态（definition 快照 + skill vX/mcp vY/instructions vZ 版本关联 + 发布审批 + 回滚）由包皮层唯一权威；agentscope 只做运行态（乐观锁 version、session 物化、runtime 执行）。
- 03 篇 §7 阶段 7：HiMarket 下新增 Java 模块聚合管理面/开发者面 API，页面配套定制成"我们平台的皮"（对标百炼控制台）。
- 33 篇 §2 包法决策 C（混合）：核心体验自研（Chat/Agent 编排走 API），管理面复用/收敛 HiMarket 门户，演进逐步替换。
包皮的收口定义（本文口径）：包皮 = HiMarket fork 出的一组 Java 后端模块（统一鉴权、聚合 API、能力管理面）+ 一组页面配套（对标百炼 12 导航项），全部挂在 HiMarket 门户框架下；它是控制面产品化层，不承载业务请求转发。包皮不重新实现执行层（agentscope）、内容层（Nacos）、流量层（Higress）——它管理、编排、展示这些层的既有能力；业务调用统一经 Higress 数据面出入。
1.2 Java 模块划分（包皮层新增/改造清单）
模块命名遵循 HiMarket 现有工程结构（himarket-server 单体 + himarket-admin + himarket-frontend），包皮按 域聚合为独立 jar 模块，避免把 13 项能力全塞进 himarket-server。
| # | Java 模块 | 职责（一句话） | 对标百炼导航 | 承载能力面 |
|---|---|---|---|---|
| M0 | himarket-portal（改造，非新增） | 门户骨架：菜单注册、路由、SSO 回调、品牌定制 | 工作台外壳 | 全部 |
| M1 | bp-gateway-adapter | 统一入口网关的 Java 侧适配：Higress 插件注册、ext_authz 客户端、审计事件落库 | 网关/权限 | 网关 10 项 |
| M2 | bp-agent-console | 智能体管理面：Managed Agent CRUD、版本发布、会话/任务中心、部署状态 | 创建应用/应用管理/Managed Agents/任务中心 | Managed Agent / Flow Agent |
| M3 | bp-sandbox-console | 沙箱与体验台：Sandbox 实例管理、Playground 在线调试、代码解释器入口 | UI 设计器/Playground | Sandbox / Playground |
| M4 | bp-context-console | 上下文底座管理面：知识库（RAG）、记忆库（Memory）、连接器（Connector）、文档解析（ParseX）的配置/检索/观测 | 知识库/记忆库/数据连接 | RAG / Memory / Connector / ParseX |
| M5 | bp-governance-console | 治理与安全：安全策略、敏感词、内容审核、进化观测（评测/轨迹/优化） | 应用评测/应用观测/Security | Evolution / Security |
| M6 | bp-store-console | 市场管理面增强：MCP 市场、Skill 市场、应用（Application）市场的运营动作（上架/审批/计量） | MCP 广场/Skill 管理/应用广场 | MCP / Skill / Application Store |
| M7 | bp-iam | 统一身份与权限：员工/管理员/审计三角色、资源授权、OIDC claim 映射、审计 SDK | 权限管理 | 全部（横切） |
| M8 | bp-common | 公共件：统一返回体、分页、异常、i18n、事件总线客户端、配置读取 | — | 全部（横切） |
模块依赖规则：M7/M8 是公共底座，M1–M6 只依赖 M7/M8；M2–M6 之间禁止互相依赖（能力面正交），需要跨域数据一律经 Nacos 配置或事件总线（RocketMQ LiteTopic，见 99 篇 §4.2 D7）。这样保证"先骨架、后逐模块挂载"的落地顺序不被模块间耦合破坏。
1.3 页面地图（含路由，对标百炼 12 导航项）
路由前缀统一
/console（管理面）与/portal（市场面，沿用 HiMarket frontend）。页面清单是 15/16 篇每个模块"页面清单"的总纲；15/16 篇给出单页字段级设计。
| 路由 | 页面 | 所属模块 | 角色 |
|---|---|---|---|
/portal/home | 门户首页（能力广场聚合） | M0 | 员工 |
/portal/markets/models | 模型市场 | M0（HiMarket 原生） | 员工 |
/portal/markets/mcp | MCP 广场 | M6 | 员工 |
/portal/markets/skills | Skill 广场 | M6 | 员工 |
/portal/markets/apps | 应用广场 | M6 | 员工 |
/console/agents | 智能体列表 | M2 | 员工/管理员 |
/console/agents/:id/edit | 智能体编排（Prompt/工具/模型/上下文） | M2 | 员工/管理员 |
/console/agents/:id/deploy | 发布与版本管理 | M2 | 管理员 |
/console/agents/:id/sessions | 会话/任务中心（含审批、HITL） | M2 | 员工 |
/console/workflows | 流程编排（Flow Agent） | M2 | 员工/管理员 |
/console/sandbox | 沙箱实例管理 | M3 | 管理员 |
/console/playground | 在线体验台（多知识库聚合问答） | M3 | 员工 |
/console/knowledge | 知识库管理（RAG） | M4 | 员工/管理员 |
/console/knowledge/:id/documents | 文档/切片/解析观测 | M4 | 员工/管理员 |
/console/memory | 记忆库管理（Memory） | M4 | 管理员 |
/console/memory/:id/observe | 记忆观测（会话↔记忆变更对照） | M4 | 审计/管理员 |
/console/connectors | 连接器（Connector） | M4 | 管理员 |
/console/parsers | 文档解析（ParseX/DeepDoc 产品化） | M4 | 员工/管理员 |
/console/security | 安全策略与防护 | M5 | 管理员 |
/console/evolution | 应用观测（延时/Token/QPM） | M5 | 员工/管理员 |
/console/evolution/eval | 评测任务 | M5 | 员工/管理员 |
/console/evolution/optimize | 应用优化（版本对比/反馈/优质数据） | M5 | 管理员 |
/console/store/mcp | MCP 市场管理面（上架/审批/计量） | M6 | 管理员 |
/console/store/skills | Skill 市场管理面 | M6 | 管理员 |
/console/store/apps | 应用市场管理面 | M6 | 管理员 |
/console/iam/users | 用户/角色管理 | M7 | 管理员 |
/console/iam/audit | 审计日志查询 | M7 | 审计 |
/console/iam/quotas | 配额与计量 | M7 | 管理员 |
1.4 包皮总体接线图（mermaid）
mermaid 规范（全系列强制）：①节点文本含
<br/>与中文时，整段必须用双引号包裹（如M2["..."]）；②换行断句发生在引号内的<br/>，禁止在引号外断行；③label 文本（-->|"..."|）同样双引号包裹；④所有 mermaid 图在交付前必须经过渲染校验（不渲染不出货）。
1.5 与现有资产接线点总表（15/16 篇逐模块展开）
| 既有资产 | 落盘证据 | 包皮怎么接 |
|---|---|---|
| HiMarket server/admin（市场/订阅/审批/门户） | 06 篇 00–04；32 篇 §1/§3 | fork 扩展：M0 门户改造、M6 市场管理面、M1 网关适配 |
| Higress AI 网关（入口治理 + 模型出口） | 32 篇 §4.6/§4.7；08-03 篇 | M1 注册插件、计量权威走 Higress AI 可观测 |
| Nacos（skill 内容/AgentCard/配置） | 32 篇 §3.4/§3.6；99 篇 §6.5.3 | 元数据权威在包皮，Nacos 管内容；发布动作组装 definition |
| agentscope-service（执行控制面） | 32 篇 §3.2/§3.6；33 篇 §6.2；35 篇 | M2 调用已验证 API：login→agent CRUD→definition PATCH（乐观锁）→session/turn |
| RAGFlow（知识库） | 11 篇 | M4 知识库管理面：OpenAI 兼容面直连（11 篇 §4），生产走 Higress 统一出口 |
| mem0+Qdrant（记忆服务） | 12/13 篇 | M4 记忆库管理面：/api/v2/memory 全链（13 篇 §五）+ 审计台账 |
| QwenPaw（数字分身/画像） | 08 专栏全 14 篇；07 篇 36–39 | M4 管理链直连 QwenPaw API（ctx.user 注入 sub）；执行链记忆读写走 agentscope |
| OpenCode / 运行时资源池 | 34 篇 | M3 沙箱/Playground 挂接执行体 |
| 企业 SSO / IDaaS（OIDC） | 32 篇 §3.5；08-03 篇 §三 | M7 完成 sub ↔ agentscope user 两层映射 |
二、统一入口网关能力需求（10 项 → 产品级）
基线：08-03 篇在数字分身环境已实证网关承担 10 项核心能力（2026-10）。该证据属于另一个运行环境，只能复用模式，不能作为本市场环境的 E2/E3 证据。本篇把每一项从"为数字分身服务"升级为"全平台产品级网关"（服务包皮全部模块 + 全部能力面），逐项给出产品级要求与验收判据；本环境的验收状态以
06为准。 升级总纲：①从"单业务线（数字分身）专用"升级为"多租户多产品线通用"；②从"实现在 Higress + 脚本"升级为"配置化管理（网关即平台）"；③从"事后留痕"升级为"审计证据链闭环"。
| # | 能力 | 现状（08-03 篇实证） | 产品级要求（包皮新增） | 验收判据 |
|---|---|---|---|---|
| 1 | SSO 身份接入 | OIDC/JWKS 校验 id_token，提取 sub→user_id；JWKS 缓存 1h | ① 多 IdP（飞书/企微/钉钉/Keycloak）按 Portal 可配（03 篇 §四）；② ID Token JWK 验签（HiMarket OidcServiceImpl 源码 TODO，03 篇 §六）；③ sub ↔ HiMarket Developer ↔ agentscope user 三层映射（32 篇 §3.5） | 三 IdP 各登录一次全部贯通；伪造 id_token 返回 401；映射规则单表可查 |
| 2 | 身份路由 | user_id→Nacos 寻址→实例端点 | ① 按 ProductRef 路由（MCP_SERVER/AGENT_API/MODEL_API 三类产品各自路由规则，03 篇 §五）；② Agent 入口按业务条线拆分（32 篇 §4.7）；③ 数字分身 sticky 语义保留 | 产品订阅→调用→计量闭环；按条线路由隔离；sticky 哈希命中率 ≥99% |
| 3 | RT 钥匙注入 | ext_authz 从 Vault 缓存取 RT 注入 header，剥离客户端伪造 | ① 密钥统一收敛：模型厂商 key 只存 Higress 配置（32 篇 §4.6），Vault 管应用级密钥（agentscope defaultVaultIds）；② 注入按 path+角色 白名单分级（哪些端点允许注入哪些密钥）；③ 注入行为全审计 | data 面容器不再持厂商 key；密钥注入无泄漏到日志/响应；审计可回溯到注入时机 |
| 4 | HTTP 代理 | 网关统一代理 LLM API 与 MCP Server | ① 三类网关收敛：模型网关（AI Proxy 插件 type:qwen + modelMapping）、MCP 网关、Agent 应用网关（32 篇 §4.7）；② 统一 OpenAI 兼容入口 = agentscope data 面 base-url；③ 代理层 Fallback/负载均衡 | 模型名→厂商路由正确；单入口多厂商；fallback 生效有日志证据 |
| 5 | SSE 流式适配 | chunked 重编码 + 30s ping 心跳 | ① 全平台 SSE 规范（event 8 类环节，33 篇 §7）；② Last-Event-ID 续传统一（33 篇 §7）；③ 心跳、超时、断联恢复策略产品化（99 篇 §8.6 断联矩阵） | 打字机效果稳定；断联续传不丢事件；心跳保活率 ≥99.9% |
| 6 | 角色权限 | employee/admin 路由白名单，管理端点员工 403 | ① 升级为 M7 统一 RBAC（员工/管理员/审计三角色 + 资源级授权）；② 权限模型贯穿所有 /console 路由（§1.3 页面地图）；③ 网关白名单 = RBAC 的只读投影（不双写） | 角色矩阵与页面地图一致；越权请求 403 + 审计记录；白名单变更走审批 |
| 7 | sticky 会话 | 一致性哈希 + 虚拟节点（160/实例） | ① sticky 语义按产品线可选（数字分身必须 sticky，市场调用可负载均衡）；② 实例扩缩容时哈希重映射策略明确；③ 与实例状态感知联动（挂起/唤醒不串实例） | 会话始终落同一实例；扩缩容期间不串话；唤醒后 sticky 恢复 |
| 8 | 分布式限流 | Redis 滑动窗口，按虚 SK 配额分级 | ① 限流维度升级：按 Consumer（订阅凭证）+ 按产品 + 按用户 三级；② 配额从 HiMarket 订阅配置下发（32 篇 §4 接缝 5）；③ 限流返回体统一（429 + Retry-After + 计量事件） | 三级限流各生效；超额返回 429；限流事件进计量与审计 |
| 9 | 审计轨迹 | JSONL → OTel → 审计平台，trace_id 贯通 | ① 审计证据链三态（99 篇：证据分层）+ 前后快照（13 篇 memory_audit 模式）；② 统一事件模型（actor/action/resource/result/trace_id/时间）；③ 长期归档 MinIO 180 天 + 结构化查询（08-03 篇 §九）；④ 与 M7 审计 SDK 打通 | 任意管理动作可审计到 actor；轨迹可跨网关→包皮→执行层串联；归档可查可导出 |
| 10 | 实例状态感知 | healthz 探活 + staged → 202 waking | ① 状态模型统一（R1–R5 运行态分级，99 篇 §1.3）；② 状态机对外可观测（列表/详情/事件流）；③ 挂起/唤醒/回收/冷热恢复全链路（21 篇 G1） | 状态流转与运行态控制器一致；唤醒延迟符合 SLO；状态变更进审计 |
网关升级实施动作（落到 M1）：
- 新增
bp-gateway-adapter：注册 Higress 自定义插件（wasm-go/Lua）+ ext_authz 客户端（认证/注入/RBAC 投影）+ 审计事件 SDK。 - 新增
网关配置表（见 16 篇 §四 数据模型）：路由规则、注入白名单、限流配额、sticky 策略均表驱动，管理面（M7）可配置。 - 计量权威：Higress AI 可观测（token/请求）为权威口径，Langfuse 可选补 trace 与成本（32 篇 §4.6 定论）。
三、全系列写作规范（15/16 篇强制遵循）
- 模块清单模板（15/16 篇每个模块必须含、顺序固定）：
- 功能点清单（编号 F1…Fn，可与百炼导航一一对应）
- 页面清单（路由 + 页面 + 关键字段）
- API 面（方法/路径/请求要点/响应要点/鉴权）
- 权限模型（员工/管理员/审计各自的动作矩阵）
- 数据模型（表名 + 关键字段 + 关系，SQL DDL 或表结构即可）
- 与现有资产接线点（引用 14 篇 §1.5 对应行）
- 优先级（P0 骨架期 / P1 第一批挂载 / P2 第二批 / P3 增强）
- 对标表四列：百炼能力（附官方 URL）→ 我们现状（附落盘篇目）→ 包皮要新增什么 → 优先级。
- mermaid 规则：见 14 篇 §1.4；所有图交付前渲染校验。
- 证据纪律：对外材料不把目标方案降格称为“POC”；但内部评审必须如实标注 E0–E4 证据等级。禁止把“设计态/源码存在/单机 POC”写成“已实现/已验收/生产可用”；“已实证”只按 E1/E2 解释，生产结论以
06为准。 - 引用格式：本地资产引用
篇目号 + 章节；百炼外部事实引用官方 URL + 章节名（可追溯）。 - 落地顺序逻辑：先包皮骨架（M0/M1/M7/M8 门户/菜单/权限/网关接入）→ 再按能力模块逐个挂载（15/16 篇每个模块标注所属里程碑）。
适用：HiMarket 包皮生产目标态施工图（系列第 1/3 篇）｜ 基线：32 篇接线设计、33 篇体验层、03 篇落地推演、05 篇生产收敛、06 篇评审台账、08-03 篇网关原则 ｜ 初稿 2026-10-26