36-平台层接缝摘要（数字分身线）

一句话：产品线独立后，平台层只保留合同页：字段、权威归属与门禁用例钉在接缝上，实例内部实现归产品线、对平台是黑盒；两把钥匙严格分离——用户只持企业身份，runtime token 只走控制面通道；接缝改动必须双侧同步，否则合同页退化成化石文档。

数字分身产品线（原 36/37/38/39 篇与专栏子目录）已独立为 08_基于QwenPaw的企业员工数字分身，本文仅保留 07 平台层与 08 产品线的接口定义。产品线自身的设计、实证与落地以 08 为准，07 侧不再展开实例内部实现。 接缝依据：32-HiMarket 集成接线设计（HiMarket↔agentscope 接线）、35-AgentScopeService 接口清单（接口契约）、15-安全与多租户隔离 §九.3（数据面身份注入·路径 2）、38 篇（Skill/MCP 分发，留档）。

一、与 agentscope-service 的接缝

1.1 HiMarket → agentscope-service（发布与执行接线）

契约	内容	出处
发布动作	PATCH /api/v1/agents/{id}/definition：平铺 body、全量替换（缺字段即清空）、乐观锁冲突 409 需重读最新 version 重发	32 §3.6 / 35 §3.2
Skill 物化	PUT /api/agents/{id}/skills/workspace/{name}（UTF-8 + front matter 校验）→ PATCH definition 启用；内容源≠直接注入，须经发布动作物化	32 §3.6
权威归属	HiMarket＝发布态元信息唯一权威（订阅/版本/白名单/审批）；agentscope＝运行态执行；Nacos＝内容寻址（需自定义装配 NacosSkillRepository）	32 §3.6/定论
身份映射	HiMarket 开发者 → agentscope user/namespace：OIDC claim 规范化后经 X-AgentScope-Tenant/Namespace 网关注入	32 §4 接缝 3
调用路径	订阅凭证 → Higress 网关鉴权 invoke → 回 agentscope 执行（Agent 市场一键注册为官方集成点）	32 §3.2

1.2 实例（qwenpaw）→ agentscope-service（产品线上接平台的适配面）

契约	内容	出处
定位	agentscope-service 仅为适配层（身份/审批/审计/互通），不承担产品内部调度	39 §九
任务入站	平台任务规范 → AgentRequest（channel/user_id/session_id/input[]/request_context，extra="allow"）→ POST /api/console/chat；session_id 显式指定＝续接会话	39 §四
审批	POST /api/sessions/{sid}/events，body {"events":[{"type":"user.tool_confirmation","payload":{"tool_use_id":…,"allow":…}}]}——events 必须非空数组	35 §3.4 / 39 §五
注册	实例按 External/托管 Agent 规范注册进 agentscope（路线 B 预留），平台内可被发现/编排	35 §3.5 / 39 §九
审计计量	任务/审批/产物事件上报，对接平台观测与计量面	39 §九
边界	审批≠验收；/api/internal/* 接入层不直接依赖；接口为 BETA1，关键路径须有降级预案	35 边界

二、与 Higress 网关的接缝（SSO JWT → runtime token）

依据 15 篇 §九.3“路径 2：渠道聚合器/网关 → 数字分身实例”，转换规则定稿如下：

1. 四步转换：网关校验企业 SSO JWT（OIDC claims sub/email/employee_id）→ 规范化 user_id → Nacos 寻址（service=qwenpaw、metadata user_id）+ 一致性哈希/sticky → 注入 x-qwenpaw-runtime-token 转发（页面/API/SSE 同路径注入）；
2. user_id 落 body：渠道聚合器投递时从 JWT 提取 sub，查 cp.users 映射表（如 alice@corp → user-sso-alice）写入请求 body 的 user_id；映射 miss 时自动预置（与 15 篇方案 A+ 的 auto-provision 一致）——否则实例侧缺省 default_user，全用户共享画像/记忆；
3. 伪造覆盖：请求自带 metadata.userId/user_id 伪造值一律被 JWT sub 映射值覆盖丢弃；无 JWT 或 JWT 无 sub → 网关 401，不到实例；
4. 两把钥匙分离：用户只持企业身份，永不接触 RT（vault 保管、每实例独立随机）；用户 JWT 单独过不了实例 runtime 边界（实证 401）；控制面流量（agentscope-service/聚合器/定时任务）凭 RT 内网直连，不经用户网关；
5. 上线门禁：V1–V5（双用户各自隔离、画像不互见、无凭据 401、伪造值被覆盖、聚合器投递 user_id 非 null）全部通过前，画像/记忆/轨迹功能不得启用。

三、与供给体系的接缝（Skill/MCP 分发）

摘要自 38 篇。三原则：HiMarket＝配置与目录权威、实例＝消费端、平台控制面＝唯一分发通道（调用一律注入 RT）。

1. 下行（市场 → 实例）：员工订阅/管理员下发（可走审批流）→ 控制面取包 → 实例 POST /api/skills/pool/import（zip）或 pool/save（目录）→ 按订阅粒度启停 → 新会话工具 schema 生效；MCP：市场注册 server 元信息（transport/url/认证/推荐白名单）→ 控制面组装 client 配置（凭证 vault 注入，不经用户手）→ 实例 POST /api/mcp 创建 + PUT /api/mcp/tools/{client} 白名单/访问策略 → toggle enabled；
2. 上行（实例 → 市场）：实例技能 pool/download 导出 zip + 元信息 → 平台上架 HiMarket（草稿 → 审批 → 发布，按租户可见范围）→ 团队订阅复用；
3. 对账与预置：市场为权威，控制面周期 diff“订阅 ↔ 实例配置”；新建实例按该员工订阅预置 skill/MCP（与模型预置同源，开箱即用）；技能池/MCP 配置随 backup 覆盖，恢复后按市场当前订阅校正。

四、平台层视角全景（08 实例集群为黑盒）

五、接缝速查表

缝	07 侧组件	08 侧对象	携带字段/凭据	权威文档
J1 发布接线	HiMarket → agentscope-service	—（产品线不发 Agent，走管理链）	definition 平铺 body + 乐观锁 version	32 §3.6
J2 任务入站	agentscope-service（适配层）	实例 POST /api/console/chat	channel/user_id/session_id/input + RT	本篇 §1.2
J3 身份转换	Higress 网关/渠道聚合器	实例 runtime 边界	SSO JWT sub → user_id（body）+ x-qwenpaw-runtime-token（header）	15 §九.3 路径 2
J4 审批闭环	agentscope-service 会话审批 API	实例 HITL 事件	user.tool_confirmation {tool_use_id, allow}	35 §3.4
J5 供给分发	HiMarket + 平台控制面	实例技能池 / MCP client	pool/import、POST /api/mcp + 白名单 + RT	38 篇（留档）
J6 注册发现	Nacos	实例 Pod	service=qwenpaw、metadata user_id	36 原文 §二（留档）

六、接缝维护规则

• 本文只是 07↔08 的合同页：字段、权威归属、门禁用例以本文为准，实现细节各自归位（07 看 32/35/15，08 看其 03/07/08 等篇）；
• 接缝变更需双侧同步：改定义走 32 篇发布动作约束，改身份走 15 篇 §九.3 验收用例，改分发走 38 篇留档口径；
• 07 侧的 36/37/38/39 原文已加归入 08 的历史提示，仅供考古，不再演进。