C2AI2X 接入层与供给侧 Onboarding 架构

Status: 对外接入层与供给侧 onboarding 的架构基线。

Upstream references:

• /www/wwwroot/default/swam_zhen_platform_unification_plan.md
• /www/wwwroot/default/swam_zhen_business_matrix.md
• /www/wwwroot/default/swam_auth_console_platform_brain_boundary_baseline.md
• README.md

本页用于说明 C2AI2X 在协议层之上的产品化接入层与供给侧 onboarding 边界。

提示先记住这条路径

需求侧从 Hosted Inbox 或 Widget 开始，供给侧从统一注册进入 Console，再由工作台承接线索与回执；Full API 面向需要深度集成的团队。

推荐阅读

四个入口，四种承接方式

Hosted Inbox

最快上线咨询入口，适合无开发团队。

Widget Embed

把悬浮入口嵌入已有官网或业务页面。

Provider Onboarding

统一完成供给角色注册、资料与审核。

Full API

由研发团队接管认证、执行与事件闭环。

它适合正在设计接入策略的产品负责人、需要判断“为什么不能只有 API”的技术负责人，以及希望理解双边入口如何接到后续履约的业务负责人。若只想选择当前入口，可先看 选择接入路径、协议入口图 与 接入模式。

它回答的不是“协议对象是什么”，而是：

1. 没有开发能力的小企业如何低成本接入
2. 双边网络中的供给侧入口应如何承接
3. docs / frontend / auth / platform-core / console / brain-core 应如何分工

若与上游共享层边界冲突，以上游为准。

1. 背景

当前 C2AI2X 协议文档已经能服务“有开发能力的集成方”：

• 读取协议说明
• 调用 POST /api/execute
• 处理 200 / 202

但这还不足以形成生态扩张。

现实约束是：

• 很多中小企业没有研发能力，无法直接读协议、调 API、处理 webhook
• 双边网络若只有需求侧入口，没有供给侧入驻与激活链，无法形成真实可调度网络

因此，C2AI2X 除协议层外，还必须补齐两层产品能力：

1. 需求侧低摩擦接入层
2. 供给侧统一 onboarding 层

2. 固定结论

当前架构口径固定如下：

• C2AI2X 协议标准本身不等于最终市场接入产品
• 零代码 / 低代码接入能力应被视为协议之上的产品化入口层
• 供给侧注册不应散落在各业务前台，必须回收进 auth -> platform-core -> console 主链
• docs.zhenrobot.com 负责解释入口层与边界，但不直接承接注册、计费、workspace 或控制面动作

一句话结论：

协议是高速公路，接入层是上路匝道，onboarding 是供给侧收费站。

3. 需求侧接入层分层

C2AI2X 对外接入固定分成三层：

3.1 Hosted Inbox

适用对象：

• 完全没有开发能力的小企业
• 只希望先上线一个咨询入口的团队
• 需要最快落地验证需求收口的客户

形态：

• 托管入口页
• 独立咨询链接
• 二维码入口

特点：

• 不要求客户写代码
• 可在最短时间上线
• 自定义能力最少

当前 MVP 固定形状：

• Hosted Inbox 由 zhen-platform-console 托管
• 公开 URL 形如：/widget/{channel_key}
• channel_key 是需求侧公开标识，不暴露内部管理主键

3.2 Widget Embed

适用对象：

• 能在站点中粘贴脚本或安装插件的企业
• 希望在现有官网、落地页、后台站点中嵌入咨询入口的客户

形态：

• 悬浮聊天框
• 嵌入式咨询面板
• 可配置 CTA 入口

特点：

• 接入成本低
• 比 Hosted Inbox 更贴近客户自有站点
• 仍不要求完整 API 集成

当前 MVP 固定 snippet：

<script
  src="https://console.zhenrobot.com/embed/c2ai2x-widget.js"
  data-channel-id="CHANNEL_KEY"
  data-console-origin="https://console.zhenrobot.com"
  async
></script>

3.3 Full API Integration

适用对象：

• 有研发团队的平台或 SaaS
• 需要把 C2AI2X 深度接入自有系统的集成方

形态：

• Bearer 鉴权
• 直接调用 POST /api/execute
• 自行处理异步 follow-up、状态回写和业务映射

特点：

• 自定义能力最强
• 集成成本最高
• 应视为高级接入模式，而不是默认入口

三种方式不是互相替代的三套产品，而是同一平台主链上的接入层级：先用 Hosted Inbox 验证需求，再以 Widget Embed 保留自有站点体验；只有需要系统级联动时，才升级到 Full API。

4. 供给侧 Onboarding 主链

双边入口解决“谁来问、谁来接”；后续履约再由客户、服务方、AI/智能体与机器人/执行系统协作完成。具体角色是否开放，以对应产品入口和正式契约为准。

双边网络中的供给侧不应只理解为“一个注册页”。

正确结构应是一条完整主链：

业务前台 / widget 入口 -> auth 统一注册 -> platform-core 建立平台身份与 workspace -> console onboarding / workbench -> 审核 / 激活 / 接单

4.1 入口暴露位置

供给侧入口可以出现在：

• 业务官网
• 协议 / 白皮书 / 生态页
• 自有 widget 的次级 CTA

这些位置适合做介绍与导流；注册、身份和后续管理沿统一入口完成。

4.2 统一注册

统一注册入口固定在：

• auth.zhenrobot.com

它主要完成两件事：

确认身份，并建立登录会话；组织、workspace、供给资格与可承接范围，则在登录后继续确认。

4.3 平台身份与供给主事实

供给侧平台身份与工作区归属由以下层解释：

• zhen-platform-core

它负责解释：

• PlatformUser
• Org / Workspace / Membership
• 供给角色
• 审核状态
• 可接单范围
• 计费与结算关系

4.4 登录后 onboarding 与工作台

供给侧登录后承接固定在：

• zhen-platform-console

它负责：

• 首次 onboarding 流程
• 资料补全
• 角色化配置
• 线索 / 任务 / 结算等受控读写入口

平台身份与权限边界由平台层统一维护，Console 专注于 onboarding、配置与日常承接。

4.5 商业与结算边界

当前可以冻结的是：

• 需求侧如何接入
• 供给侧如何 onboarding 与进入 workbench
• 接入包、订阅与平台服务能力的产品化表达

当前不能在本文件写死的是：

• 平台固定 take-rate
• provider payout 公式
• 专家实得比例
• 退款、争议、回拨与税务结算规则

固定解释：

• C2AI2X 接入层已经成形，不等于供给侧结算规则已经封板。
• 若未来引入正式 provider payout / revenue share contract，应以 zhen-platform-core 的正式契约为准，而不是由 docs 站或垂直前台先写成既定事实。

5. Widget 的边界

C2AI2X Widget 的标准定位不是“第二个 console”，也不是“缩小版 docs 站”。

它的职责固定为：

• 低摩擦需求收口
• 最小会话入口
• 咨询 / handoff / 留资触发
• 可选的供给侧入口曝光

5.1 Widget 必须做到

• 嵌入简单
• 默认即用
• 可配置品牌、颜色、文案和入口位置
• 可选择 Hosted Inbox fallback
• 可上报来源站点、页面、campaign 等归因信息

当前 MVP route map：

• zhen-platform-core
  • POST /api/integrations/channels
  • GET /api/integrations/channels
  • GET /api/public/channels/{channelKey}/widget-config
  • POST /api/public/channels/{channelKey}/intake
  • GET /api/provider/profile
  • POST /api/provider/profile
  • GET /api/provider/workbench/leads
  • POST /api/provider/workbench/leads/{leadId}/claim
  • POST /api/provider/workbench/leads/{leadId}/status
• zhen-platform-console
  • /integrations
  • /provider/onboarding
  • /provider/workbench
  • /widget/{channel_key}
  • /api/public/widget/{channel_key}/config
  • /api/public/widget/{channel_key}/intake

5.2 Widget 不应承载

• 完整平台控制面
• 完整供给侧 onboarding 表单
• 订单、账单、workspace 的解释页
• 任何绕开 zhen-platform-core 的执行入口

5.3 供给侧入口规则

若 widget 暴露“成为专家 / 接入机器人 / 注册智能体”入口，规则固定如下：

• 在 Zhen 自有前台上，可默认开启
• 在第三方客户嵌入场景中，默认关闭或由配置显式开启
• 点击后跳转到独立 onboarding 主链，不在 widget 内承载完整注册流程

解释：

• 第三方站点的首要目标通常是承接其自身需求，不一定愿意替平台做供给招募
• 因此供给入口必须是 config-driven，而不是硬编码固定露出

6. 供给侧状态机建议

供给侧最小状态机推荐冻结为：

1. registered
   • 已完成统一注册
2. profile_incomplete
   • 供给资料未补齐
3. pending_review
   • 已提交审核
4. active
   • 可接线索 / 可接单
5. suspended
   • 被暂停或需复核

说明：

• 这是产品层建议状态，不重新定义底层认证边界
• 真实状态字段和 API contract 仍由 zhen-platform-core 冻结

7. 各层职责分工

7.1 docs.zhenrobot.com

负责：

• 解释协议层
• 解释接入分层
• 解释边界与推荐路径

具体注册、计费、workspace 生命周期与供给侧控制面动作，应在对应产品入口完成。

7.2 业务前台

负责：

• 暴露咨询入口
• 暴露供给侧报名入口
• 放置 widget 或 Hosted Inbox 入口
• 做行业化转化表达

统一身份、平台供给主事实与登录后持续管理动作，统一回收到平台服务与 Console。

7.3 auth.zhenrobot.com

负责：

• 统一登录 / 注册入口

7.4 zhen-platform-core

负责：

• 平台身份
• 角色 / workspace / 审核 / entitlement / 结算主事实
• widget / hosted inbox / API 的平台准入判断

7.5 zhen-platform-console

负责：

• 登录后 onboarding
• 供给侧工作台
• 登录后持续经营动作

7.6 zhen-brain-core

负责：

• 执行、路由、判断、风控、记忆

供给侧注册与工作区归属由平台层承接；浏览器前台通过正式入口进入生产路径。

8. MVP 实施顺序

当前最小闭环建议固定为：

1. Hosted Inbox
   • 让无开发能力客户先能接入
2. Widget Embed
   • 让会贴脚本的客户快速接入官网
3. Provider Signup
   • 只先支持一种供给角色，例如专家 / 顾问
4. Console Onboarding
   • 完成角色资料补全和审核状态承接
5. Provider Workbench
   • 最少能读线索、接 / 拒绝、更新状态

顺序解释：

• 先解决“需求从哪里进来”
• 再解决“供给如何被激活”
• 不在第一阶段同时做全角色 marketplace

9. 非目标

当前阶段不把以下事项作为默认目标：

• 复杂多边 marketplace 定价体系
• widget 内完整支付与结算流程
• 在 docs 站提供互动式 onboarding 控制面
• 一次性同时做专家、机构、机器人、智能体四套深度角色化后台

10. 一句话结论

C2AI2X 若要从协议变成生态，必须同时具备：

• 低摩擦需求入口
• 统一供给侧 onboarding

缺少前者，会变成难接入的开发者协议；缺少后者，会变成没有供给网络的单边入口。