开放平台与 UM 划界：宪法级边界协议

定义 open.yunjii.cn、UserMatrix（UM）、云集接口（api.yunjii.cn）三者的宪法级职责边界——零功能重叠、独立产品、清晰 API 契约；open 仅以客户端身份消费 UM 身份 API，云集接口仅做无状态路由与开发者门户。

0. 总纲（宪法级）

UserMatrix（UM）、开放平台（open.yunjii.cn）、云集接口（api.yunjii.cn）是三个独立产品，彼此零功能重叠。本文件为三者关系的「宪法」，任何一侧的功能演进均不得越过边界。

四条不可逾越的原则：

  1. UM = 统一数字身份系统（身份基座）：负责「谁是主体、被授权做什么」。
  2. open = 家族能力开放平台 / 生态市场：负责能力的「发现、组合、计量、结算」。
  3. 云集接口（Yunjii API）= 统一 API 门面 / 开发者门户：负责「一个 base、一套鉴权、一份错误信封」，按作用域无状态路由到各产品。
  4. open 仅以客户端身份消费 UM 身份 API；云集接口仅做路由与门户，两者均绝不重新实现对方的逻辑。

命名规范：对外产品名为 云集接口（Yunjii API），域名 api.yunjii.cn，slogan「云集统一接口 · 一个地址接入云集全家族能力」。「统一 / 网关 / 路由」是实现描述与卖点，进 slogan 与内部技术文档，不作对外产品名——正如业界称 Stripe API / GitHub API，而非「Gateway / Router」。

铁律（一句话判定法）

UM 永远不做「业务逻辑」，开放平台永远不做「身份判定」，云集接口永远不做「身份判定」也永远不做「商业化逻辑」。

  • 若一段代码在判断「这个人 / 应用有没有权限访问资源」→ 它必须在 UM 内核。
  • 若一段代码在把「已确认的身份信息」同步到第三方（飞书 / Salesforce / 家族应用）→ 它必须在开放平台。
  • 若一段代码在「按 path 把请求转发给某个产品后端」→ 它必须是云集接口的纯路由，不含任何身份 / 商业化判定。
  • 任何跨越这条线的功能，都是架构债务，必须在评审阶段被否决。

凡违反第 0 条、使 open 退化为 UM 门面（镜像 UM 端点 / 直接读写 UM 身份库），或使云集接口退化为带业务逻辑的中转层（缓存身份 / 自行签发令牌 / 做套餐结算）的改动，一律禁止。

此处 User 是架构术语，意指「身份主体」（principal），涵盖人、应用、智能体——而非日常语境之「用户」。UM 的名称与域名（um.yunjii.cn）保持不变；云集接口的对外露出域名为 api.yunjii.cn。

1. 产品定位（本质隐喻）

UM（UserMatrix）open（开放平台）云集接口（api.yunjii.cn）
本质隐喻地基 / 操作系统内核应用商店 / SDK 市场 / 连接器工厂统一 API 网关 / 开发者门户（连接器面板）
核心价值提供确定性：身份是谁、权限是什么、信任链是否完整提供可能性：能连什么、能组合出什么新场景提供单一入口：一个 base、一套鉴权、一份错误信封
一句话统一数字身份系统：跨人·应用·智能体的身份基座与鉴权枢纽家族能力的开放平台 / 生态市场家族统一 API 门面与开发者门户
本职身份主体管理、OAuth 2.1 签发、UMID 联邦、能力注册表能力的发现 / 组合 / 计量 / 结算、合作伙伴生命周期路径路由、版本治理、统一错误信封、开发者文档 / 门户
主体身份主体（人 / 应用 / 智能体）商业关系（合作伙伴、套餐、对账）开发者 / 调用方（API consumer）
绝不碰不碰能力策展、不碰商业化不重造身份、不持身份逻辑不持有身份逻辑、不持有商业化逻辑、不缓存业务数据
一句话界定「没有 UM，身份不存在」「没有开放平台，身份不好用」「没有云集接口，调用很碎」

2. 宪法级边界（零重叠清单）

UM 独占：

  • 身份主体的注册 / 认证 / 合并（UMID 联邦）
  • OAuth 2.1 + OIDC 端点（/oauth/authorize、/oauth/token、/oauth/userinfo、/oauth/revoke、discovery）
  • 令牌签发与吊销、PKCE、RBAC、多租户 SaaS
  • 能力注册表（各应用声明「提供 / 消费什么能力」的数据源）

open 独占：

  • 合作伙伴入驻、应用审核、app_key / tier 管理
  • 能力目录的策展与呈现（从 UM 注册表读取，对外编排展示）
  • 计量（usage）、套餐（plans）、结算（settlements）
  • 对外的开发者文档 / SDK / 市场门户

云集接口独占：

  • 统一 API 路由（按作用域 path 无状态转发到 UM / open / 能力后端）
  • API 版本治理（仅破兼容时升 /vN 并附 sunset 日期）
  • 统一错误信封 + 统一鉴权（Bearer）规范的定义与强制执行
  • 开发者门户首页 / 接口文档入口（门面，不含业务逻辑）

三方禁区（不得越界）：

  • open 不得自行签发身份令牌、不得持有用户密码 / 第三方 openid（绝不缓存身份主数据）。
  • UM 不得做能力商业化、不得做合作伙伴套餐与结算。
  • 云集接口不得实现身份判定（归 UM）、不得实现商业化（归 open）；不得缓存任何业务 / 身份主数据，仅做无状态转发。

3. 技术架构切割（物理隔离优于逻辑隔离）

内部的「清晰」不能靠团队自觉，必须靠架构强制：

  1. 仓库与发布管线完全独立

    • UM 内核：独立 Repo，发布周期以「季度 / 半年」为单位，需经安全审计、长周期回归。
    • open：独立 Repo，发布周期以「周 / 双周」为单位，自动化测试 + 灰度发布。
    • 云集接口：轻量门面，发布以「天 / 周」为单位；其路由规则与门户页相互独立，不携带业务逻辑。
    • 禁止共享数据库表、禁止直接函数调用；三者只能通过标准化 API 通信，就像三家独立公司。这迫使接口契约保持干净。

  2. 数据主权绝对分离

    • UM 持有身份主数据（Identity Source of Truth）：主体属性、凭证、权限策略、审计日志。
    • open 只持有连接元数据（Integration Metadata）：OAuth Token、Webhook 配置、同步映射、调用统计。
    • 云集接口不持有任何业务数据，仅维护路由表与作用域注册表（纯配置，非业务状态）。
    • open 与云集接口绝不缓存身份主数据，需身份信息时实时调用 UM API。外部开发者因此确信：平台只是管道，不是数据湖。

  3. 安全模型分层

    • UM 安全 = 零信任内核级：mTLS、硬件密钥、策略引擎、不可篡改审计。
    • open 安全 = API 网关级：Rate Limit、Scope 校验、IP 白名单、调用签名。
    • 云集接口安全 = 边缘路由级：TLS 终止、Host/path 路由、统一 Bearer 校验后透传；不解析、不存储业务凭证。
    • open 的凭证（API Key / app_key）绝不等同于 UM 身份凭证；云集接口的平台令牌只能调平台 API，无法直接操作内核。

4. API 契约边界

侧命名空间示例端点
UM（身份后端）/oauth、/principals、/capabilities（注册表）/oauth/token、/principals/{id}、/capabilities
open（生态市场）/marketplace、/apps、/plans、/usage、/settlements/marketplace/capabilities、/apps/{app_key}、/usage/{app_key}
云集接口（统一门面）作用域短名：/oauth、/market、/models、/capapi.yunjii.cn/oauth/token、api.yunjii.cn/market/capabilities
  • open 调用 UM 身份 API 使用服务间凭证（如 client_credentials grant 或专用服务密钥），走标准 OAuth 2.1，不复刻身份逻辑。
  • 对外文档中，open 的端点与 UM 的端点不互相镜像、不互相代理；外部一眼可辨归属。
  • 云集接口对外仅暴露统一 base api.yunjii.cn + 作用域短名；其内部按 path 转发到上述各产品命名空间，路径中的产品归属对调用方透明。

4.1 统一 API 收口契约（云集接口门面）

「收口」的本质 = 一个 base host + 一套鉴权 + 一份错误信封，而非一条更短的 path。契约如下（对外发布后不可随意变更）：

  1. 统一 base（变量化）

    • 对外露出：https://api.yunjii.cn（云集接口产品域名）。
    • 内部：各应用将 base 配为 API_BASE 变量（先可指向 open.yunjii.cn/api 或 api.yunjii.cn 等），切换后端只改 env + 代理规则，接入方代码不动。域名对外露出一旦确定即具品牌黏性，故对外主推域名在契约稳定后定死。

  2. 作用域用功能短名，不写产品名

    • /oauth（身份，归 UM）、/market（生态 / 套餐，归 open）、/models（模型能力，归 IF/MF）、/cap（能力注册表，归 UM）。
    • 路径描述「做什么」而非「归谁」：网关可内部把 /oauth 从 UM 转到别处而外部无感；若写成 /api/um/oauth 则把归属焊死进 URL，破坏收口。
    • 作用域注册表（防止双字母歧义，如 mp=marketplace 还是 mini-program）：新增作用域必须先查重、进表、再定名。

  3. 默认无版本；破兼容才升 /vN 且必带 sunset

    • 以 OAuth 2.0 → 2.1 为范本：2.1 是 2.0 的清理版（删 implicit / password 授权、强制 PKCE），URL 路径不变（仍是 /oauth/authorize、/oauth/token），协议版本写在行为与文档里，不写进 URL。
    • 我们同理：默认单版本、向后兼容（只加不改不删）；仅当真·不兼容重写时才引入 /v2 等，且必须公告 sunset 日期强杀旧版，避免 v1-v10 长期共存拖垮维护。
    • 因此起步不加 /v1；版本号是「被迫出现」的安全阀，不是前置承诺。

  4. 统一鉴权

    • 一律 Authorization: Bearer <token>。区分两类凭证：服务间密钥（内部家族互调）、第三方 app_key（经 open 入驻的开发者）。云集接口只校验令牌格式与路由权限，不解析业务含义。

  5. 统一错误信封

    • 所有端点返回一致 JSON 错误结构（如 { "error": { "code": "...", "message": "...", "request_id": "..." } }），不每家一套；便于 SDK 统一处理。

端点路由映射表（云集接口 → 后端）：

云集接口路径转发后端归属
api.yunjii.cn/oauth/*UM身份
api.yunjii.cn/market/*open生态 / 套餐
api.yunjii.cn/models/*IF / MF模型能力
api.yunjii.cn/cap/*UM能力注册表

4.2 云集接口产品边界与落地页范围

job（合法职责）：

  • 统一 API 路由（无状态转发）。
  • API 版本治理（sunset 纪律的执行者）。
  • 统一错误信封 / 鉴权规范的守护。
  • 开发者门户首页：端点导航、文档跳转、状态指示。

不做清单（越界即违宪）：

  • 不实现身份判定（归 UM）。
  • 不实现商业化 / 结算（归 open）。
  • 不缓存任何业务 / 身份主数据。
  • 不重写被路由后端的逻辑（只透传）。

落地页范围（lean 静态薄页，非重构建）： 为契合服务器「做轻、避免 OOM」现实，第一轮 api.yunjii.cn 落地页用静态 HTML/CSS（Caddy / OpenResty 直接托管，零 pm2 进程、零 next 构建、零内存压力）。页面仅含以下区块：

  • Hero：云集开放 API 一句话定位。
  • 端点导航：列出 /oauth /market /models /cap 及跳转。
  • 文档跳转：链到现有 fumadocs（um / open 站）。
  • 开发者控制台入口：链到 open.yunjii.cn。
  • 状态指示：可选的健康 / 版本号。

云集接口「产品感」来自域名与门面，而非新增后端服务。其路由在现有 Caddy↔OpenResty 中只是「新增 Host vhost + path 转发规则」，不新起任何后端进程——这正是「做轻」与「收口」可兼得的原因。

4.3 市场价值边界（云集接口不自行变现）

云集接口作为「无状态路由 + 开发者门户」，其价值属性须明确，避免被误当成营收产品而越界：

战略价值（真实、间接）：

  • 降低家族对接摩擦：一个 base + 一套鉴权，第三方一次接入即可调用 UM 身份 / open 生态 / IF 模型。
  • 强化技术品牌：对外建立「云集有统一 API 中台」的心智，提升生态粘性。
  • 这些是赋能层价值，不直接产生营收，是成本中心而非利润中心。

直接市场价值的边界：

  • 纯路由无独立营收能力——用户为「能调用的能力」付费，不为「转发」付费。
  • 若欲赋予直接变现 job（如统一 SDK 工厂、API 可观测性 / 分析、企业级网关治理限流 / 审计 / 合规报告），这些须是不侵入 UM（身份）/ open（结算）领地的能力。
  • 即便如此，云集接口不得自行结算——变现须作为 open 市场中的一个 SKU / 套餐上架，由 open 统一计费。这守住本宪法第 2 节「open 独占计量 / 结算」。

官网定位（lean）：

  • 第一轮官网 = 开发者门户（文档式）：hero 价值主张 + 端点导航 + 状态，营销通过「一个地址接入全家族能力」自然发生，不另起硬广营销站。
  • 技术栈：静态 HTML/CSS 即可，零 next 构建、零 pm2、零 OOM 风险；待确需交互式控制台 / SDK 生成器时，优先复用现有 fumadocs，不新起 Next 应用。

5. 外部感知切割（让混淆在视觉上不可能）

外界不会读架构文档，只看命名、域名、界面、文档。必须在触点上制造「感官断层」：

触点UM（UserMatrix）open（开放平台）云集接口（api.yunjii.cn）设计意图
命名UserMatrix（UM）独立产品名 + 功能后缀（候选：UM Connect / UM Studio / UM Marketplace）云集接口 / 云集开放 API（技术中台品牌）三者主语各异，避免「UM 开放平台」式混淆
域名um.yunjii.cn（不变）open.yunjii.cn（兄弟子域）api.yunjii.cn（兄弟子域，零 DNS 成本）子域保留血缘且层级区分；api 明确是技术面
视觉语言沉静可信（示意：矩阵靛 #2E3A59）活跃创造（示意：激活青 #06b6d4）中性技术（示意：终端黑 / 等宽 + 单色强调）三者色彩情绪不同：UM=可信、平台=创造、云集接口=技术管道
文档站/docs/core 概念 / 协议 / 合规/docs/api QuickStart / SDK / Cookbook门面页 + 跳转（不重复造文档）受众不同：UM 给安全架构师、平台给集成商、云集接口给调用方
控制台管理后台：策略 / 身份目录开发者工作台：应用注册 / Webhook仅门户首页（无独立控制台，入口跳 open）物理界面分离 = 心理认知分离

关键原则：不要让外部用户在同一个页面、同一导航栏里同时看到「身份策略配置」「API 密钥管理」「端点路由」。物理界面的分离，是心理认知分离的最短路径。

6. 治理机制切割（用制度保障边界不退化）

架构与视觉会随时间腐化，须有常设机制捍卫边界：

  1. 边界归属判定机制：所有涉及 UM / open / 云集接口交互的需求、接口变更、数据流动，必须有明确归属判定（由架构负责人签字）。凡模糊边界的需求，无论商业价值多高，一律退回重构。
  2. 能力下沉 / 上浮评审（季度）：
    • open 中某功能被 3+ 客户重复实现 → 考虑下沉为 UM 内核标准能力。
    • UM 内核中某功能仅 1–2 客户使用且高度业务相关 → 考虑上浮为 open 插件 / 示例代码。
    • 云集接口路由表随之上 / 下调整，但绝不因此获得业务逻辑。
    • 确保边界动态校准，而非僵化割裂。
  3. 对外「不竞争条款」：在开放平台开发者协议中明确——「UM 承诺不会利用平台数据开发与第三方集成商直接竞争的业务」。这既是法律条款，更是信任信号。

7. 旧 open（UM 门面）下线 + 执行优先级

当前 open.yunjii.cn 实为 UM 的带牌镜像（共享同一身份后端与数据库），属「壳」，违反本宪法第 0 条。迁移路径与优先级：

阶段行动项验收标准
P0（立即）确定 open 独立产品名 + 视觉语言草案 + 域名 / 仓库规划；确定 api.yunjii.cn 作为统一 API 露出 + 静态门面内部对齐，外部测试中无人将三者混为一谈
P1（1 个月内）完成 open 独立仓库 + API 契约定义 + 数据模型分离设计；落地 api.yunjii.cn vhost 路由（无状态转发）架构评审通过，无共享表 / 直接调用
P2（3 个月内）上线 open 独立开发者门户 + 文档站 + 控制台分离版；对外统一经 api.yunjii.cn 收口首批外部开发者可独立完成集成，无需 UM 内核介入
持续边界归属判定 + 季度能力复盘 + 不竞争条款落地 + 版本 sunset 纪律每份需求文档有明确归属，无灰色地带

下线步骤（在 P2 内执行）：

  1. 冻结：停止在 open 上新增任何 UM 镜像端点。
  2. 新建：open 独立仓库按第 3 节落地，先实现「合作伙伴 / 能力目录 / 计量」本职；云集接口仅配路由与门户。
  3. 切换：外部流量从旧 open 门面切到新 open 产品；身份相关请求统一走 api.yunjii.cn/oauth → UM（open 以客户端调用）。
  4. 下线：确认无流量后，回收旧 open 门面，删除对 UM 后端的直接镜像。

生产下线须遵守低峰期、备份、零停机（灰度 / 双跑）纪律，避免影响在网业务。

8. 验收标准（对外可识别、互不侵犯）

  • 外部开发者能仅凭端点命名区分 UM / open / 云集接口 的请求归属（功能短名作用域）。
  • open 源码中不存在 um_user / um_oauth 等身份表的直接读写。
  • 云集接口源码 / 路由层不含任何身份判定或商业化逻辑，仅做无状态转发。
  • UM 源码中不存在套餐 / 结算 / 合作伙伴等商业化逻辑。
  • 任一侧独立部署 / 故障，不影响另一侧核心可用（open 宕机不阻断 UM 鉴权；云集接口 路由故障不影响各产品直连可用性）。

对接方式总览（统一接口标准）

云集生态唯一官方接口标准 = OAuth 2.1 + OIDC。本文说明为什么它是首选，并对比所有可用的接入方式（REST / 二维码直出 / SDK / iframe），多种方式是标准之上的灵活备选，而非另立标准。

统一数字身份演进路线（注册表模式）

UM 从「用户身份」演进为「统一数字身份系统」的功能缺口与分阶段规格——以声明式注册表而非单体实现，避免系统变重。