主题
33 - 统一体验层设计（"接入层"：开源组件封装与体验一致性）
一句话：接入层之所以存在，是因为 API 已证可靠而原生 UI 带缺陷：引擎退居 control/data 接口的唯一被消费方，皮负责品牌、身份与交互一致，混合包法用分阶段换低风险落地；代价是密钥库实证、发布流程、渠道接线这些产品化缺口全落在这一层，引擎接口抖动须由 BFF 吸收，不能让前端直连开源 API。
定位：本平台
不直接开放 agentscope-service 给用户
，在其上构建统一体验层（"接入层"），把开源组件全部包进去，保证体验一致性。 决策背景：用户拍板（2026-10-25）——"我们不会直接开放 agentscope service 给用户，可能在上面包一层皮，把开源组件都包进去；如何包，可以是嵌入，也可以重构 UI"。 关联：《32-HiMarket 集成接线设计》（资产目录 / 网关 / SSO）、《30 - 搭建过程与问题解决台账》（API 链路证据、UI 缺陷 #9/#10）。
1. 决策前提（事实基础）
API 层完全可靠（已实证）：Login→Env→Agent→Session→Turn→模型回答全通；幂等同键同体✅；SSE 事件流 + cursor 续传✅；工具调用（memory_search/list_files）✅；MCP / 审批 / 多 agent/workspace 能力面已源码确认。
官方 UI 层有运行时缺陷（台账 #9/#10）：Chat 发消息无回答（UI 会话未进执行管线）、历史读空、events 403。
推论：既然不开放原生 UI，"接入层" 路径可天然绕开官方 UI 缺陷——agentscope 只当后端引擎（control/data API），体验层自研。
2. 三种包法对比与取舍
| 包法 | 方式 | 体验一致性 | 成本 | 风险 |
|---|---|---|---|---|
| A 嵌入 | iframe / 微前端挂载 agentscope 原生 UI | 差：双登录态、样式割裂、跨域、功能被原生 UI 框死 | 低 | 高：受官方 UI 缺陷影响（#9/#10）；升级跟随官方 |
| B 重构 UI | 纯 API 复用 + 前端完全自研 | 好：完全可控、可品牌化、统一交互 | 高：前端工作量大 | 中：依赖 agentscope API 稳定性与覆盖度 |
| C 混合（推荐） | 核心体验自研（Chat/Agent 编排走 API）；管理面（Agents/Teams/Channels/Workspaces 配置）初期复用原生 UI 或收敛 HiMarket 门户，演进逐步替换 | 好：用户主路径统一 | 中 | 低：分阶段降低风险 |
推荐 C：本月先做 "最小体验层"（自研 Chat 前端调 API）证明可行路径，管理面逐步替换；不阻塞 KPI，且绕开官方 UI 缺陷。
3. 分层架构（用户 → 引擎）
用户
↓
自有体验层（皮）：统一品牌/交互/入口/身份 ← 自研（或 HiMarket 门户做开发者体验）
↓
资产/治理层：HiMarket（Agent/MCP/Skill/Model/Worker 目录、订阅、审批、计量）
↓
流量层：Higress AI 网关（安全/流控/观测/计量）
↓
运行时引擎：agentscope-service（control/data API） ← 只做后端引擎，不直接对用户开放
↓
模型层：qwen3.8-flash 等（经网关）身份贯穿：企业 SSO/OIDC → HiMarket 认证 → 订阅凭证 → Higress 鉴权 → agentscope 用户 /namespace 映射（详见 32 - 文档 §3.5）。
4. 关键设计决策点
| # | 决策点 | 判断 | 理由 |
|---|---|---|---|
| 1 | 嵌入 vs 重构 vs 混合 | 混合（C） | API 可靠 + UI 有缺陷 → 自研体验层绕开缺陷；管理面分阶段替换降成本 |
| 2 | agentscope 的定位 | 纯后端引擎 | control/data API 语义完整（session/turn/events/snapshot/tools/mcp）；不暴露原生 UI |
| 3 | HiMarket 门户的角色 | 开发者体验（市场订阅 / 测试），非最终用户工作台 | 最终工作台（皮）自研，保证企业品牌与交互一致性 |
| 4 | 体验一致性的根 | 身份统一 + 交互统一，非 UI 相似 | SSO/OIDC 贯穿（P0）；自研层统一入口 |
| 5 | 自研前端依赖的 API 面 | 会话 / 事件 / 快照 / 审批 /tools/mcp + 管理面（agent CRUD、workspace、teams） | 需评估管理面 API 覆盖度，缺则补 BFF 层 |
| 6 | BFF（后端对前端） | 若 API 语义偏 "引擎"，体验层需一层 BFF 适配 | 统一鉴权、聚合、格式化，避免前端直连开源 API |
5. 三阶段落地路线
| 阶段 | 内容 | 成果 | 状态 |
|---|---|---|---|
| 1（本月 KPI） | API 层能力闭环（M5 补完）+ 最小体验层（自研 Chat 前端调 API 打通 "接入层" 可行路径） | API 全链路证据 + 最小体验层 Demo | 进行中 |
| 2 | 体验层扩展：Agent 编排 / 管理面收敛；HiMarket 接入（SSO + 资产目录） | 统一工作台 + 身份贯穿 | 待启动 |
| 3 | 完整产品化：治理 / 计量 / 门户 / 观测 | 企业级平台 | 规划 |
6. 对本月 KPI 口径的影响
原口径：控制台 UI 全功能可用（受阻：官方 UI 缺陷 #9/#10）。
新口径（推荐）：API 层端到端能力闭环 + 最小体验层验证—— 技术上完全可达（API 已证），且为 "接入层" 路线提供落地样板。
官方 UI 缺陷降级为 "非阻塞项"（不开放原生 UI，缺陷不影响产品面）。
6.1 最终形态对标：阿里云百炼（2026-10-25 外部锚定）
用户在阿里云百炼控制台逐项观察后确认：接入层最终形态 = 阿里云百炼平台的设计，功能层与我们基于开源组件推演的形态七七八八一致，技术栈同为阿里生态。以下为导航级对标（百炼导航 → 我们推演 → 开源组件落点 → 状态）。
| 百炼导航 | 我们的功能面 | 开源组件落点 | 状态 |
|---|---|---|---|
| 创建应用 / 应用广场 / 应用管理 | 体验层应用管理（agent CRUD + 发布） | agentscope /api/v1/agents + definition PATCH | ✅ API 已证（M4/M5） |
| Managed Agents Beta | managed binding / AgentTask 协作 | managed agent + rt.agent_tasks | ✅ M4 运行；AgentTeams 编排 P4 |
| UI 设计器 | 体验层前端（配置 UI） | 官方 UI 缺陷 #9/#10 被包住 | ⏳ P3 自研 |
| 任务中心 | 任务列表 / 编排 / 审批 | rt.execution_attempts + turn 命令 + approvals | ✅ 表与审批已证；编排 P4 |
| Skill 管理 | HiMarket Skills 市场（元信息）+ Nacos（内容） | PUT workspace + SkillRepositoryConfigEntry git/filesystem | ✅ 上传链（M5）；市场接线 P2 |
| MCP 广场 / MCP 管理 | HiMarket MCP 市场 | mcpServers + marketplace 概念 | ✅ 运行时（M5-4）；广场 P2 |
| 组件广场 / 组件管理 | HiMarket 组件市场（工具/插件） | AgentToolset + 内置工具 | ⏳ P2 |
| 记忆库 | 记忆管理（版本化） | memory_store + cp.memory_stores/versions | ✅ 记忆链已证；蒸馏 P5 |
| 知识库 | RAG 知识检索 | 官方无向量库（增强位） | ⏳ 接线项 |
| 数据连接 | 数据源 / 渠道接入 | scheduler channel gateway / 外部应用通道 | ✅ 网关通道已证 |
| 应用评测 | 仿真 / 评测 / 黄金集 | 25-仿真台 / 26-调优闭环（设计） | ⏳ 设计→P5 |
| 应用观测 | 可观测 / Trace / 指标 | 事件 outbox + 14-可观测设计 | ⏳ 对接 |
结论：
- 功能层推演已与行业头部平台对齐——"接入层"不是拍脑袋，是百炼式工作台的必经形态；导航/功能/数据面（记忆库/知识库/评测/观测）一一对应。
- 技术栈同阿里生态：qwen/千问（百炼入口 ↔ 我们 openai: 兼容网关 + token-plan/maas，M4 已证）、agentscope-java（平台底座）、Nacos/RocketMQ/Higress（32 文档接线）、Spring Boot 全栈一致——生态融合成本低，可整体锚定"百炼形态"为体验层蓝图。
- 差异 = 我们的增强位（百炼有、开源组件官方没有，需接入层/自研补齐）：知识库（向量 RAG）、应用评测（仿真台）、应用观测（Trace 对接）、UI 设计器（自研前端）。这些正是 P2–P5 接线与 15/25/26 设计落地的内容。
6.2 Managed Agents 对标（2026-10-25）：百炼 Managed Agents = agentscope managed binding 的产品化形态
百炼 "Managed Agents" 产品导航（智能体/环境/密钥库/会话/部署/资源文件/扩展 MCP·技能·渠道·通知）与 agentscope-service managed agent 能力面逐项对应，差异只在产品化包装——即接入层要做的部分。
| 百炼 Managed Agents 导航 | agentscope-service 能力面 | 状态 |
|---|---|---|
| 智能体 | /api/v1/agents（binding=managed，definition PATCH 乐观锁） | ✅ M4/M5 运行时 |
| 环境 | /api/environments（type=local，env_d17e35381ab7） | ✅ M4 |
| 密钥库 | definition defaultVaultIds（Vault 密钥注入） | ⏳ 字段在，未运行时实证 |
| 会话 | /api/v1/agent-sessions + /turns（Idempotency-Key） | ✅ M4/M5 |
| 部署 | definition version 发布（乐观锁 + resolved definition 冻结） | ✅ 乐观锁已证；发布流程未建 |
| 资源文件 | workspacePath（隔离目录 + skills/ + memory-stores/ 挂载） | ✅ M5-7 + §5.5.1 |
| 扩展 · MCP | definition mcpServers（注册+工具注入+审批） | ✅ M5-4 |
| 扩展 · 技能 | definition skills（workspace/oci/仓库源三通道） | ✅ M5-3 + §5.5.1① |
| 扩展 · 渠道 | scheduler channel gateway（外部应用通道，compose 已部署） | ⏳ 通道机制在，配置接线未做 |
| 扩展 · 通知 | 事件 outbox + SSE（cursor 续传）→ 通知/webhook 对接位 | ✅ M5-2；通知接线 ⏳ |
结论：agentscope-service 的 managed binding 就是百炼 Managed Agents 的开源底座——能力面覆盖度 ≈90%（缺：密钥库实证、部署发布流程、渠道/通知接线），缺口全部落在接入层的产品化动作（P1–P3 路线图覆盖）。这也再次锚定体验层 MVP 的第一屏范围：智能体列表 + 会话 + MCP/技能管理（百炼 Managed Agents 导航前五项）。
7. 性能基线（M6 实证，2026-10-25 多轮采样）
首笔样本（m5-perf-001，turn b3f3fdce，M4 会话）：turn 提交 2240ms、轮询 completed 2076ms、模型调用 6.59s/7.52s。
多轮分布（m5-perf-101/102/103 + SSE 首 token，2026-10-25，会话 e62755c5，模型 qwen3.8-flash @ token-plan）：
| 指标 | 值 | 说明 |
|---|---|---|
| turn 提交耗时（commit） | 冷启动 2137ms / 稳态 98–115ms | POST /turns → 202；冷=首次含 harness 构建/模型连接初始化 |
| 端到端 completed 耗时（total） | 6736 / 3187 / 3176 ms | POST → turn.completed；冷启动 +4s，稳态 P50≈3.2s |
| SSE 首个事件到达 | POST 后 ~1.5s（冷，POST 自身 2187ms） | 首个 status_running 事件 |
| SSE 首 token（首个模型 item.delta） | POST 后 3733ms（冷）；事件创建时间戳显示批内 7 跳仅 ~37ms | 首 delta 与 item.completed(USER) 同批到达（批式推送） |
| SSE 事件链环节数 | 8 类环节：session.status_running → session.context_initialized → run.started → input.applied → item.completed(USER) → item.started(model) → item.delta×N → …→ run.ended → turn.completed | 首个 delta 前 7 跳，批内跳间隔 ~6ms |
| 事件生成耗时（批内） | status_running→首个 item.delta 仅 37ms | data 面预生成批事件，传输/轮询才是主延迟 |
结论（口径与 HiMarket 计量对齐，32 文档 §4-5）：
- 稳态首 token 端到端 ≈ POST 后 1.5–1.6s（冷启动 +1.5s）；总完成 ≈3.2s（短问答）。
- 延迟大头 = 模型推理（6–8s 长回答）+ 冷启动，平台自身（提交 0.1s、事件批 40ms、回传 <0.5s）占比 <15%——体验层优化优先做：长连接复用（免冷启动）、SSE 直推（免轮询）、模型网关选路。
- SSE 环节 8 类、跨 control/data 两跳（outbox→mirror），批式推送使事件延迟稳定；断线靠 cursor 续传（M5-2 已证）。
- 样本 3 轮，P50≈3.2s 可靠、P99 样本不足——HiMarket 计量上线后按黄金集持续采样（26 文档调优闭环）。
skill 物化疑点定论（M6）：PUT 上传只写 data 面 agent workspace 文件；session workspace 由 control 侧 definitionFiles 快照 物化（HarnessAgentBuildService → ManagedDefinitionMaterializer.materialize），PUT 后快照不刷新 → 新 session 仍物化旧版 skill（152B vs 235B 实证）。官方设计缺陷/限制，体验层对策：skill 上传后需同步 definition（或接受"定义快照为准"语义）；另发现 PUT 上传中文乱码坑（PowerShell 无 BOM 脚本 → GBK 转码），体验层上传 UI 必须显式 UTF-8 校验（见 30 台账 §5.5）。