供给与注册体系

一句话：供给链把“能力”拆成内容、产品、准入、加载四类权威且各只存一处，凡复制定义之处即漂移之源；发布、订阅、网关放行是三条互不带动的状态机，一致性不靠事件推送，而靠显式发布动作加定时对账兜底——差异只告警，刷新必人工。

定位：一项能力从 Git 源码到用户手里，经过哪些环节、谁持有权威、怎么不漂移。

版本口径（2026-10-26 核实）：HiMarket 最新 release v0.50（2026-10，v0.x 早期，非 v1.0），开源版观测分析依赖阿里云商业化 SLS，观测缺口由 Higress AI 可观测与 Langfuse 面补齐；Nacos 3.2.0+ 提供 Skill Registry；AgentScope Java 2.x 提供可插拔技能仓库与 agentscope-extensions-nacos 扩展包；qwenpaw 侧接口以本地源码为准。

为什么需要：没有供给体系时必然出现的三个洞

平台里到处是“能力”：模型端点是某个人建的，MCP Server 是另一个团队部署的，Skill 是第三个团队写的。没有供给与注册体系，三件事会反复发生：

1. 三处各有一份定义：Nacos 里注册了一版工具清单，市场页面里贴了一份介绍，实例工作区里还躺着上周手动导入的 ZIP。三处内容各自演化，没人知道哪份是真的——这就是漂移的全部来源。
2. 下线后仍能调用：资产在注册中心已标记 offline，但市场快照不知道、实例缓存还在加载、网关消费者凭据仍然有效。“下架”只发生在某一处，消费方拿到的是一个指向空处的产品。
3. 发现即授权：工具地址在群里传开，注册表里能搜到就能调。把安全寄托在“别人不知道地址”上，是最脆弱的设计——出了事查不到订阅关系，也无法解释“这个租户凭什么能调”。

对应的三味药，就是本体系的三条铁律：权威归属唯一（每类信息只有一处权威）、发布与授权解耦（上架不等于可用）、引用加对账（不复制定义，但持续比对）。

§一 权威分层

全文只承认一个纪律：每一类信息有且只有一处权威，其余层要么是引用、要么是投影、要么是执行结果。

层	组件	持有什么权威	明确不持有
源码	Git/CI	开发态：分支、评审、构建产物、commit 与 SHA-256	运行时分发、版本发布状态
资产定义	Nacos（Registry）	内容、版本、Schema、端点、健康状态、审核状态——“它是什么、在哪、哪个版本、是否在线”	订阅、价格、审批流
产品配置	HiMarket	产品化与关联：目录展示、nacosRefConfig 引用、订阅关系、审批、配额、可见范围、Agent 配置元数据的发布态快照（钉住的资产版本）	资产内容本体、运行时第二份真相、凭据
准入执行	Higress	认证、限流、协议转换、路由放行，以及调用计量的原始口径（token/请求数）	资产定义、订阅关系的存储
运行时加载	agentscope-service / qwenpaw 实例	本地缓存、加载优先级、会话级版本锁定、工具策略（能用到什么程度）	版本发布、授权决定

三条推论：

• 发现不等于授权：注册中心有 scope 元数据，市场能搜到，都只回答“存在且可见”；“这个应用能不能用”由订阅决定，“这次请求放不放行”由网关与运行时策略决定。三处各管一段，压成一段必出洞。
• 上架不等于可用：发布决定“可被看见”，订阅决定“可被授权”，网关决定“这次调用放不放行”——三条独立状态机，任何一条都不自动带动另外两条。
• HiMarket 快照是引用不是副本：市场保存 ref 与产品字段，权威定义仍在 Nacos。因此不存在持续双向同步，一致性要靠“显式发布动作 + 定时对账”兜底（§七）。

一句话总结：Nacos 管“是什么”，HiMarket 管“谁能订”，Higress 管“放不放行”，实例管“怎么加载”——四层各司其职，谁也不越权。

§二 全链路组件图

每段的失败语义都不同：上游断供要降级（缓存继续服务），配置漂移要告警（对账发现），授权失败要拒绝（403/401），加载失败要显式（不能“随便挑一个可用版本”）。

§三 Nacos 三使用面

Nacos 在平台里同时承担三件事，可以共用一套集群，但命名空间与分组必须分开——混在一起会让一次配置变更触发无关服务的监听回调。

三使用面分工

使用面	存什么	谁写	谁读
服务发现	服务名、实例地址、集群、健康状态	实例自注册或运维注册	网关、运行时、调用方
动态配置	超时、并发、灰度比例、开关、路由参数	运维 / 发布系统	运行时、网关
资产注册	Skill Registry / MCP Registry：ID、版本、协议、端点、Schema、owner	发布流水线	市场、网关、运行时

数据模型是三层：命名空间（prod/staging/按租户）隔离环境，分组（services/configs/assets）隔离资源类型，服务与配置承载实例和版本。不要把租户塞进服务名，否则注册表退化成字符串拼接；租户隔离优先用命名空间或独立集群。实例分临时（心跳，失联自动摘除）与持久（服务端探测，适合无法主动上报的遗留系统）。

资产注册契约字段表

一个可用的注册项，缺一项就有对应故障：

字段	作用	缺失后果
id / type	唯一标识与类型	重名覆盖、消费方无法判断怎么接
version	契约版本（SemVer）	无法灰度、无法回滚
endpoint / protocol	地址与协议（MCP/HTTP/gRPC）	接入后才发现不兼容
schema / tools	工具或接口清单	调用方无法生成参数
scope	可见范围（企业/租户/项目）	越权发现
owner / oncall	责任人	故障无人认领
health	健康状态与检查方式	调用方继续打坏实例
dependencies	依赖的模型、凭据、数据	上线才发现缺依赖

没有版本与责任人的实例不允许注册。

版本钉住：SemVer + Label

• 版本用 SemVer 表达契约兼容性，label（stable、canary）指向具体版本；灰度靠切 label 给少量租户，禁止直接用版本号做灰度。
• 回滚就是切 label，不重新打包、不改内容。
• 已上线（online）版本不可变：修改必须新建草稿重走审核，这保证“上线版本能复现”是系统性质而非口头约定。
• 运行时不允许持有浮动版本：消费方拿到的是一个不可变快照（version + sha256 + endpoint + schema_hash），动态发现结果的版本、权限与风险必须重新校验后才能使用。

配置治理与降级

动态配置的收益是“不重启生效”，代价是“变更影响面大”，必须配齐四件事：版本与审计（操作人、时间、diff，可回滚）、灰度推送（按 IP/标签/百分比）、推送前 schema 校验、客户端本地快照降级（配置中心不可用时按最后快照继续服务并告警，不能因拉不到配置而拒绝服务）。凭据不进配置中心——配置读取面宽且会被本地缓存，API Key 进 Vault，配置里只放引用。

§四 HiMarket 产品模型

HiMarket 由 Higress 社区与 Nacos 社区共同发起，2025-08-29 开源，v0.50 是 v0.x 早期版本；与 AgentScope 是官方集成关系（Agent 一键注册），Worker/Skill 与 Nacos 是官方路径（批量导入），Docker Compose 即含 HiMarket + Higress + Nacos + MySQL 全套。它在体系中的角色是产品配置权威：把能力变成有版本、有订阅、有配额、有审批的产品，不解决运行时执行。

五种产品类型

类型	市场里是什么	运行时对应	特殊契约
Model	厂商目录、可用模型名/版本、订阅与配额、限流/内容安全策略、计量单价	definition.model provider:model 名 + 网关路由	密钥集中在 Higress，data 面不持厂商 key
MCP	Server 产品：ref 关联 Nacos，自动拉工具清单与端点	definition.mcpServers / 实例 MCP client	工具参数级限制不在市场，在运行时策略
Agent	Agent 应用打包上架，一键注册	agentscope definition + session/turn 执行	必须有版本化 Endpoint，否则只是演示不是产品
Skill	从 Nacos 导入的方法包产品	definition.skills + SkillRepository 加载	ZIP 包体约 10MB 量级上限，不绑 API
Worker	可装载 Skills 的执行单元，管理员从 Nacos 批量导入，开发者门户/CLI 安装	实例内执行单元	与 agentscope managed agent 的关系是包装层，择一收敛

产品通用字段：类型、端点与协议、版本、鉴权方式、配额与价格、可见范围、责任人与 SLA、下线策略。每项缺失对应一种故障（无法灰度、凭据乱发、事故无人认领、消费方被突然断供）。

发布与订阅：两条独立状态机

发布决定“可被看见”，订阅决定“可被授权”，网关决定“这次调用放不放行”。解绑或下架要先停订阅再删引用。

计量与计费：中间隔着一本账

层次	谁负责	产出
调用计数	Higress AI 可观测（原始口径权威）	请求数、输入/输出 Token、状态码
产品聚合	HiMarket	按产品、订阅、租户聚合用量
价格计算	企业计费系统	单价、折扣、阶梯、退款
结算与对账	财务/业务系统	账单、发票、成本分摊

计量口径要写进产品契约：网关重试是否重复计数、流式请求后补的 Token 怎么算、缓存命中是否计费。开源版 v0.50 的观测分析依赖阿里云 SLS，开源实现尚未就绪，观测由 Langfuse 面补齐。

nacosRefConfig：存引用不存副本

供给方不需要把能力“再录一遍”。接入动作：登记 Nacos/Higress 实例 → 产品详情页 Link API 选资源类型与来源 → POST /api/v1/products/{id}/ref，请求体带 sourceType 与 nacosRefConfig（namespaceId、mcpServerName）或 higressRefConfig → 关联时自动拉取工具清单与连接地址 → 之后可在产品里刷新同步上游变更。

必须接受的语义：市场保存的是引用，不是副本。上游改名、换端点、删工具，市场不会凭空知道；自动导入不是自动授权，导进来的只是“可被产品化”的候选，仍要走审核、发布、订阅。引用越方便，对账越不能省。

对账机制规格

• 对象：ref 指向的资产（Nacos 在线版本、工具清单、端点）↔ 市场快照（产品记录里的版本与工具列表）。
• 频率：每日定时全量比对，关键产品可加密到小时级。
• 判据：版本号、工具清单哈希、端点可达性三项任一不一致即漂移。
• 动作：差异告警，不静默刷新——静默刷新会把上游未审变更带进已订阅产品；刷新必须由运营确认后触发，且刷新后重新走可见性与订阅校验。
• 收敛：解绑/下架顺序固定为“停订阅 → 通知 → 删引用”，避免消费方拿到指向空处的产品。

闭环全景（差异只告警、刷新必须人工触发、下一轮对账再校验）：

图里三处设计是有意的：判据三项任一命中即算漂移（只看版本会漏掉同版本号改内容）；刷新动作只有人工确认这一个入口（静默刷新等于把上游未审变更带进已订阅产品）；修完必须回到比对节点，否则告警清单只增不减，对账退化成没人看的报表。

§五 Skill 供给链路

Skill 是“方法包”（SKILL.md + 脚本 + 参考文件），消费者是模型（按需加载指令）；它与 MCP 是两种资产、两条链路，不能混：把 Skill 塞进 MCP，就无法按版本审核指令、无法限制工具权限；把市场当存储，市场一挂 Agent 就加载不到技能；把导入当同步，目录逐渐失真。

生命周期五态

draft → reviewing → reviewed → online → offline

• 同一 Skill 同时只允许一个草稿或审核中版本；
• online 版本不可变，修改新建草稿重走审核；
• 回滚靠切 label 指向旧版本；
• offline 不等于删除，已订阅方要有迁移期。

审核流程

Nacos 3.2.0+ Skill Registry 把审核做成原语：结构上 skill-name/SKILL.md（frontmatter 写 name、description）+ 可选 references/、examples/、scripts/；审核走 Java SPI 插件，内置 skill-scanner 检查提示注入、数据泄漏、恶意代码；scanner 通过后人工发布，管理员可强制发布但留审计记录。审核分级：内部工具自动扫描 + 轻审核，涉及外部数据与写操作必须人工复核。

上线十步固定动作：Git 按 skill 目录开发 → CI 校验 frontmatter/语法/依赖并跑扫描 → 打 ZIP、算 SHA-256、记录 commit → Nacos 创建草稿上传（SemVer + 可见性）→ 提交审核 → 通过后上线打 label → HiMarket 导入为 Skill 产品 → 配置可见范围/审批/配额发布 → 消费方订阅、运行时按订阅加载 → 下线先停订阅再切 label 或转 offline。

运行时加载：缓存、优先级与热更新

AgentScope Java 的技能仓库可插拔：本地工作区、Classpath、Git、Nacos、MySQL、Postgres。接 Nacos 时：NacosSkillRepository 拉取技能包 ZIP 字节、解析后注册；支持变更订阅，上游上线新版本可动态推送；包物化到 .skills-cache/<source>/<name>/，用 SHA-256 去重。

加载优先级从低到高：项目全局 → 市场 → 工作区 skills/ → 用户 skills/，后者覆盖前者。系统提示只列 <available_skills>，模型按需 load_skill_through_path(skillId, path) 读具体文件——这是“按需加载”与“全量注入”的分界。

优先级层叠（自上而下优先级递减，箭头是“同名覆盖”方向）：

两条边界：覆盖只发生在同名，不同名技能四层并存；每次加载要留来源与版本，否则“市场下发了 v3、实际跑的是用户本地 v1”无从解释，也无法回答“这个员工的技能为什么和同事不一样”。

agentscope 集成路径（最终结论）

官方扩展包 存在但需额外引入：agentscope-extensions-nacos 含 -skill（NacosSkillRepository，AiService ZIP 直拉，version/label 寻址，只读）、-a2a、-prompt 三子模块。但 service 标准配置入口不认 nacos：SkillRepositorySupport.create() 仅分派 filesystem/git，未知 type 只 WARN 返回 null。因此结论唯一：Nacos 内容进 agentscope 需自定义装配 NacosSkillRepository（直接 new + AiService）或扩展 SkillRepositoryConfigEntry 的 type 枚举，同时同步 knownSkillNames 清单；不能靠 definition JSON 配置直达。发布态编排（版本关联、审批、清单同步）由接入层承担——这正是 §七“发布动作”存在的理由。

§六 MCP 供给链路

MCP 是“工具服务”（端点 + 工具清单 + Schema），消费者是运行时（发起工具调用）。它比 Skill 多一层“服务运行”，链路六步：

1. 部署 Server：确定传输方式与出网策略；
2. 注册到 Nacos（MCP Registry）：登记端点、协议、工具清单、版本、owner 与健康检查——健康检查方式决定坏实例多快被摘除，是注册契约的必填项；
3. 接上 Higress：配置路由、认证、限流与协议转换，调用方只认一个入口；
4. HiMarket ref 关联：nacosRefConfig 导入，自动拉工具清单与端点，可刷新；
5. 产品化：可见性、订阅审批、配额与价格；
6. 运行时授权：Agent 侧只启用需要的工具集，按 always_allow / always_ask / deny 控制执行。

协议：Streamable HTTP

MCP 传输三选一：stdio / streamable_http / sse。市场分发场景以远程为主：streamable_http 是首选（单端点、可网关代理、支持会话续传），sse 兼容存量，stdio 只用于实例本地进程型工具——容器实例内的 stdio 运行环境受沙箱与资源限制，不进市场分发路径。实例是 MCP 客户端，连接外部 Server：url + headers（远程）或 command + args（stdio），凭证从 Vault 注入、不经用户手。

网关代理

Higress 同时承担三类 AI 网关角色：模型网关（按 model 名路由厂商，密钥与 Fallback 集中）、MCP 网关（统一代理/托管 MCP Server，按业务条线拆分以隔离工具暴露面）、Agent 应用网关（invoke/SSE/鉴权统一入口）。落地原则：调研/落地阶段单实例收敛三类网关，生产阶段按需拆分独立实例、故障域分离。

MCP 信息管理分三处，缺一不可：Nacos 管“它是什么、在哪、哪个版本”，HiMarket 管“谁能订、多少钱”，Higress 管“这次调用放不放行”；工具级白名单与参数限制落在实例与运行时策略（§八）。把三者压成一个，必然在授权或计费上出洞。

§七 市场接线（HiMarket ↔ agentscope）

接线要解决的唯一接缝：HiMarket 持有元信息（产品/版本/订阅/凭证），agentscope 持有执行配置（definition.skills/mcpServers/model/tools），两者的同步由谁触发、触发什么、失败怎样。

选型结论：显式发布动作 + 定时对账兜底

候选方案三种：事件推送、轮询比对、发布动作显式同步。最终口径：以发布动作为主通道，定时对账为兜底——

• 发布动作：接入层在“发布 Agent 版本”这一人工动作里组装完整 definition payload 并写入 agentscope。关键实证：PATCH /api/v1/agents/{id}/definition 是全量替换，缺字段即清空（只传 name+system 会清掉 mcpServers/model/skills/env）；body 平铺不嵌套；version 字段为乐观锁，成功 +1，过期返回 409 conflict，接入层重读最新版本重发。Skill 内容通过 PUT /api/agents/{id}/skills/workspace/{name} 推送（UTF-8 + frontmatter 校验），再 PATCH definition 启用——内容源不等于直接注入，必须经发布动作物化。
• 定时对账：每日比对 Nacos 在线版本与 HiMarket 引用版本、以及 definition 快照与接入层钉住版本，差异告警而不是静默刷新；这是“事件推送缺位”的兜底，不取代发布动作。
• 事件推送不作为主通道：HiMarket v0.50 与 agentscope 之间没有可靠事件契约，且“发布”本身是人工审批动作，绕过它反而破坏审计链。

配置元数据的权威归属（收敛后唯一口径）

信息	权威	说明
资产内容与版本（skill 包、MCP Schema）	Nacos	内容寻址、不可变版本、label
Agent 配置元数据的发布态：definition 快照 + 每个资产的版本关联（skill vX / mcp vY / instructions vZ）	HiMarket（接入层）	发布时钉版本、审批留痕、回滚依据；这是“产品配置权威”在 Agent 场景的展开
definition 的运行态（乐观锁 version、session 物化）	agentscope-service	执行与运行时，不改发布态
订阅/审批/配额	HiMarket	回写审计与成本

接入层负责把发布态翻译成运行时配置（经已验证 API），agentscope 是 managed binding——各层职责不重叠，不存在双权威。

身份映射：HiMarket 开发者 → agentscope 用户/namespace

• HiMarket 原生支持企业 OIDC/SSO/IDaaS，是企业 SSO 的第一入口；
• 订阅凭证按开发者发放，网关鉴权在 Higress；
• agentscope 侧用 X-AgentScope-Tenant/namespace + 用户 id。
• 映射规则：OIDC claim 对齐（sub → agentscope user id，tenant/组织属性 → namespace），由网关注入租户 header，接入层在发布与分发调用中携带；平台控制面对实例（如 qwenpaw）的操作以 RT token 注入身份完成，用户不直操底层组件。

身份三态：用户态（SSO 穿透）、系统态（后置任务用内置服务身份）、运行时态（控制面持 RT token 调实例 API）。

五类资产接线一览

资产	录入	内容/配置	生效路径
Model	HiMarket 模型市场（厂商/配额/单价）	密钥与路由在 Higress（AI Proxy：provider + apiTokens + modelMapping）	agentscope data 面单入口指向 Higress AI 端点，模型名在 definition 选——平台侧单入口，厂商多路在网关
Agent	HiMarket Agent 市场（一键注册）	发布态快照在接入层	订阅 → 凭证 → 网关 invoke → agentscope 执行
Skill	HiMarket Skills 市场（元信息）	内容与版本在 Nacos	发布动作物化进 definition.skills + workspace
MCP	HiMarket MCP 市场（ref 关联）	端点/工具清单在 Nacos，代理在 Higress	订阅 → mcpServers 同步 + Vault 凭据注入
Worker	HiMarket Worker 市场（Nacos 批量导入）	定义在 Nacos	门户/CLI 安装到执行单元

用户只面对 HiMarket 一个入口；底层组件是“执行器官”，用户无感、不可直操。

§八 分发实证（qwenpaw 实例侧）

实例侧的接口与机制全部有源码依据，链路已验证可用：

Skill pool/import 链路

• 实例能力：/api/skills/pool/*（list/create/save/upload-zip/import/upload/download/delete/config/tags/auto-sync）、skills/{name}/enable|disable 与批量启停、内置 Skill Hub 异步安装协议（hub/search、hub/install/start、/status/{task_id}、/cancel/{task_id}，当前内置 github/lobehub/clawhub 三源解析）、agent 级工作区技能挂载 agents/{id}/skills/workspace/{name}。
• 下行（市场 → 实例，订阅即安装）：员工在 HiMarket 订阅或管理员下发 → 平台控制面收到订阅指令 → 取包 → 注入 RT token 调 POST /api/skills/pool/import（zip）或 pool/save（目录）→ 技能池落地 → 按订阅粒度启停 → 工具 schema 生效；版本变更走 pool/import 覆盖 + auto-sync。
• 上行（实例 → 市场，自建回流）：pool/download 导出 zip + 元信息 → 控制面收集 → HiMarket 上架（草稿 → 审批 → 发布，按租户可见范围）→ 团队订阅复用，形成“员工自建 → 团队共享”闭环。
• 演进方向：HiMarket 暴露与 qwenpaw hub 协议兼容的 search/install 接口（HubSkillSpec：slug/name/description/version/source_url/author/icon_url），实例直接走 /hub/install/start 任务化拉装——比 zip 注入更原生（可取消、进度可见）。

MCP 配置下发

• 市场元信息：transport、endpoint URL、认证方式、工具清单、推荐白名单、适用范围；
• 订阅后控制面组装 client 配置：streamable_http/sse 用 url + headers（凭证从 Vault 注入，不经用户手），stdio 限本地进程场景；
• 调 POST /api/mcp 创建 client → toggle enabled → 按订阅粒度落白名单与访问策略（PUT mcp/tools/{client} + access policy）→ 工具进入 Agent schema，员工无感可用。

会话级版本锁定

qwenpaw 的工具 schema 在会话级刷新：会话建立时快照当时已启用的技能与 MCP 工具集，会话中途的安装/启停不改变当前会话视图。这正是“不可变快照”纪律在实例侧的落点——一个会话内模型看到的能力集不会中途漂移，新版本从下一会话生效。对账与 auto-sync 也只影响新会话。

与实例生命周期的合缝

• 新建实例：拉 Pod 时按该员工订阅预置 skill/MCP，开箱即用；
• 暂存/恢复：备份 include_skill_pool 覆盖技能池，MCP client 配置随全局配置备份，恢复后按市场当前订阅对账校正（备份是历史时刻，市场是权威）；
• 执行通道：分发调用全部走 RT 边界注入 token，实例侧无需用户登录；
• 一致性总则：市场为权威（订阅/版本/白名单），实例为执行结果，控制面定期 diff 订阅 ↔ 实例配置。

§九 已支持场景走线

一、Skill 从草稿到上线

二、MCP Server 注册 → 发现 → 调用

三、订阅产品 → 网关放行 → 实例加载

四、定时对账发现漂移 → 告警 → 人工修复

边界与验收

• Nacos 不是市场：没有订阅、审批、计量；不是授权系统：scope 只是过滤元数据；不是密钥库：凭据进 Vault；不是代码仓库：源码权威在 Git；注册的是“能力在哪”，不是“执行到哪”。
• HiMarket 不是运行时：不执行 Agent、不保存会话、不做工具参数校验；不是计费系统：提供用量事实，价格与结算在企业系统；v0.50 观测依赖商业化 SLS，落地需自建观测补齐。
• 单团队不需要市场：一个团队、两三个能力时，一张配置表 + 网关消费者就够；出现多供给方、多消费方、按量分摊再上。

全链路验收判据：换实例地址不改调用方配置；坏实例按约定时间摘除；上线版本能复现、回滚只切 label；未订阅调用返回 403、配额耗尽返回可读错误、下架后新调用被拒且订阅方收到弃用通知；上游变更能在对账周期内被发现；会话内能力视图不漂移。

适用：HiMarket v0.50 / Nacos 3.2+（Skill Registry、MCP Registry）/ AgentScope Java 2.x + agentscope-extensions-nacos / Higress AI 网关 / qwenpaw 本地源码 | 由原 04、08、19、32、38 五篇合并，2026-10