ZhenIns 公开白皮书
版本：1.1
发布日期：2026 年 5 月 19 日
适用范围：投保客户、保险顾问、经纪机构及生态合作方
上一版本：v1.0（2026-05-10）
变更摘要（v1.0 → v1.1）
- 统一身份与单点登录（ADR-009）：消费者 SMS 认证与顾问 OAuth 登录均接入
auth.zhenrobot.com统一身份中心，实现跨平台身份互认与免密恢复。 - 消费者会话持久化：支持历史对话的完整 CRUD（创建、查询、重命名、删除），会话数据不再仅保留在浏览器本地。
- 精确 Token 计数：引入
tiktoken进行逐 token 计量，替代传统字符长度估算，为复杂保险推理提供准确的上下文预算管理。 - Consent 链路完整闭环：从 AI 建议触发 → 画像信息授权确认 → 顾问接收 → 消费者撤回同意，全流程有状态、可审计、可撤回。
- 前端状态竞态防护：Chat 会话层与业务状态层分离，消除 mount/unmount 期间的重复加载与额度状态漂移。
- 端到端测试全量覆盖：lint + build + E2E + backend integration test + 生产冒烟 5-step curl 全部纳入 CI 门禁。
1. 概述
1.1 ZhenIns 是什么
ZhenIns（真机保险）是真机（Zhen）生态中的 AI 保险咨询前台。它面向投保客户，提供以对话为首要交互入口的保障缺口分析、方案建议与资料准备指引。当对话触及复杂场景——例如旧保单替换、健康告知冲突、预算约束严重或涉及特殊人群——系统自动通过 Agent2Human 协议 转接持证保险经纪进行人工复核。
ZhenIns 不直接销售保险产品，而是帮助客户回答三个问题：
- 我当前的保障缺口在哪里？
- 已有方案是否足够覆盖风险？
- 下一步应该做什么、准备什么资料？
1.2 为谁服务
| 角色 | 核心需求 | 服务形态 |
|---|---|---|
| 投保客户（主要用户） | 理解保障缺口、获得方案建议、准备投保资料 | AI 对话咨询 + 人工复核兜底 + 服务包购买 |
| 保险顾问 / 经纪 | 接收复杂场景转介、与客户安全沟通、管理咨询进度 | Agent2Human 工作流 + 顾问工作台订阅 |
| 经纪机构 / 企业 | 多席位管理、组织权限、合规报表、API 集成 | Brokerage / Enterprise 方案 |
| 生态合作方 | 将 AI 保险咨询能力嵌入第三方工作流 | OpenClaw Skill 授权 |
1.3 核心承诺
- AI 先行，人工兜底：标准场景由 AI 独立完成；复杂场景自动或主动转入人工，客户始终拥有选择权。
- 数据最小必要：未授权前不收集完整敏感资料；每次资料请求必须明确用途；用户可随时撤回授权。
- 合规留痕可追溯：咨询请求、方案输出、人工复核节点、授权记录均留痕，支持审计导出。
- 不伪装最终结论：AI 输出为"建议摘要"而非"正式核保结论"；最终承保、赔付、合规判定由保险公司及持牌机构依法执行。
2. 真机生态中的位置
2.1 业务前台壳（Business Frontend Shell）
ZhenIns 在真机生态中的定位是 业务前台壳。它负责公开获客、咨询交互、方案解释、授权说明与合规白皮书，不长期维护独立的身份体系、账单系统或组织管理后台。
前台壳的分工边界是生态设计的一部分，目的是确保保险行业对合规、审计和数据最小必要性的高要求能够被统一满足，而非在每个垂直站点中重复建设。
2.2 与 zhen-brain-core 的关系
zhen-brain-core 承担保险推理、方案生成、风控评估与记忆沉淀。
关键约束：ZhenIns 前台在正式生产路径中 禁止直接调用 zhen-brain-core。所有请求必须通过 zhen-platform-core 网关转发。执行链路固定为：
ZhenIns 前台 → zhen-platform-core → zhen-brain-core
这一约束的目的是：将身份验证、权限校验、用量审计和合规留痕统一在网关层完成，避免前台直接暴露推理接口带来的合规风险。
2.3 与 zhen-platform-core 的关系
zhen-platform-core 是真机生态的统一经营内核，负责：
- 身份与组织：消费者 SMS 轻量认证、顾问 OAuth 统一登录、workspace 与组织管理
- 账单与权益：会员订阅、entitlement、订单、退款、发票
- 支付：统一 checkout（支付宝 / 微信支付），定价 catalog 作为唯一真相源
- 审计留痕：会话元数据、授权记录、合规标签
ZhenIns 本地不维护第二套身份或账单系统。前台通过 API 调用 platform-core 的服务，并将结果呈现给用户。
2.4 与 zhen-platform-console 的关系
zhen-platform-console 是登录后统一控制面。
ZhenIns 的登录后管理页面仅保留过渡性入口，长期所有权归属控制台。以下操作需跳转至控制台完成：
- 查看订单与权益
- 管理 API Key
- 团队席位与组织设置
- 下载合规报表与审计文件
- 订阅管理与发票
前台页面的职责是引导用户前往正确的控制台入口，而非在站内重建控制面。
2.5 为什么必须是这样分工
保险行业对监管合规的要求远高于一般 SaaS：
- 身份真实性：投保行为与身份证明绑定，不能依赖匿名会话
- 授权可追溯：任何资料收集和处理都必须有明确授权记录
- 数据最小必要：云端不默认持有原始客户资料，上传建立在授权和业务必要性之上
- 风控集中：保险推理、评估和沙箱能力由统一大脑治理，避免各前台自行解释条款
将身份、账单、风控和审计收归统一平台，是满足上述要求的最小可行架构。
3. Agent2Human 协议
3.1 协议定义
Agent2Human 是 ZhenIns 的协作协议，核心原则为：AI 处理标准场景，人工复核兜底复杂场景。
AI 顾问在对话中持续评估当前场景复杂度。当复杂度超过安全阈值，或客户主动要求人工介入时，系统将对话上下文脱敏后转接至持证保险经纪。
3.2 自动触发条件
以下场景会自动触发人工转接：
- 健康告知复杂：涉及既往病史、多家医院记录、非标准体况
- 旧保单替换：涉及退保损失计算、等待期重叠、责任冲突
- 责任冲突：家庭内部多份保单存在重复或缺口对冲
- 预算约束严重：预算与保障需求差距过大，需要方案权衡
- 特殊人群：高危职业、非标准体、高净值、涉外身份、复杂家庭结构
3.3 用户主动触发
用户在任何阶段均可主动要求人工复核，例如：
"我想和专业保险经纪聊聊" "这个方案我不太确定" "能不能帮我人工确认一下？"
主动触发不经过 AI 复杂度评估，直接进入人工队列。
3.4 人工侧标准
接收转介的保险经纪须满足：
- 持有合法执业资格证书
- 从业经验 ≥ 2 年
- 通过平台季度资格审核
- 全程留痕、SLA 监控
服务标准：
| 指标 | 承诺 |
|---|---|
| 接单响应 | ≤ 2 小时 |
| 首次联系 | ≤ 4 小时 |
| 全程留痕 | 100% |
| 客户评价 | 可评价、可投诉、可退款 |
顾问侧配备多渠道通知系统——站内通知、Web Push、SMS 短信、Email 邮件——确保高意向线索（意向分 ≥ 7）在 15 秒内触达顾问。
3.5 数据脱敏边界
AI 对话中可能收集完整资料（身份证号、详细健康档案、资产明细）。转人工时，仅传递脱敏摘要：
- 年龄段 / 家庭结构 / 预算 / 职业类型
- 保障缺口摘要
- 复杂点描述（已脱敏）
- 客户诉求
不传递：
- 完整 AI 对话历史
- 客户详细身份信息（授权前）
- AI 内部评估逻辑
- 完整家庭资产明细
人工经纪如需完整资料，必须向客户发起二次授权请求，客户明确同意后方可查看。客户可在任意阶段撤回同意，撤回后顾问端实时失去画像访问权限。
3.6 Consent 完整链路
Handoff Consent 是 Agent2Human 协议的数据授权核心环节，已形成完整闭环：
- 触发：AI 在对话中识别复杂需求，返回
suggested_handoff: true标记 - 授权确认：前端弹出 Consent Modal，逐项列出将共享的画像信息（年龄、城市、家庭、预算、健康等），标记敏感字段
- 顾问接收：顾问工作台实时显示线索，附带AI提取的结构化画像和对话摘要
- 撤回：消费者可在「我的服务进度」页面随时撤回同意，顾问端通过 WS 实时收到
lead_revoked事件，画像立即不可访问 - 审计：授权、共享、撤回全过程写入
notifications表和lead_events日志
3.7 质量保证
- 每季度审核保险经纪执业资格
- 每月审核服务评分与投诉率
- 全程对话留痕，支持合规审计
- 客户不满意可申请退款或更换顾问
- 平台出站 E2E 测试覆盖消费者全旅程、顾问工作台、支付编排、授权链路共 32+ 个测试用例
4. 数据治理与合规
4.1 最小必要原则与分级授权
ZhenIns 遵循《个人信息保护法》要求，采用最小必要原则和分级授权机制：
| 授权级别 | 内容 | 默认状态 |
|---|---|---|
| 基础授权 | 脱敏摘要（年龄段、家庭结构、预算区间、职业类型） | 默认启用 |
| 详细授权 | 联系方式、健康告知、现有保单、财务信息 | 需客户主动同意 |
| 随时撤回 | 客户可在任意阶段撤回已授予的权限 | 始终可用 |
硬性规则：
- 未获得明确授权前，不得要求上传完整敏感资料
- 不得将"上传入口存在"表述为"系统已接收正式资料"
- 不得将"建议摘要"表述为"最终保障结果"
4.2 数据持有边界
| 数据类型 | 归属位置 | 说明 |
|---|---|---|
| 顾问客户库、沟通备忘录、未提交方案草稿 | ZhenIns 本地 / 顾问端 | 业务过程中产生的临时内容 |
| 已授权提交的报价/核保摘要 | zhen-platform-core | 经过客户授权的正式业务数据 |
| 会话元数据、合规留痕、审计导出 | zhen-platform-core | 支持跨平台审计与合规检查 |
| 会员/订单/权益/发票 | zhen-platform-core | 统一经营内核持有 |
关键原则：云端不默认持有原始客户资料。所有上传建立在授权和业务必要性之上。
4.3 传输与存储安全
- 传输：TLS 1.3 全链路加密
- 存储：敏感数据 AES-256 加密
- 审计：定期安全审计与渗透测试
- 日志：访问日志保留期限符合监管要求
4.4 合规留痕与审计
以下事件强制留痕：
- 每次咨询请求的时间、场景、用户标识（脱敏）
- AI 建议摘要输出
- Agent2Human 转接触发原因和人工复核结果
- 客户授权与撤回记录
- 支付订单状态变更
留痕数据支持合规审计导出，由 zhen-platform-core 统一管理。
5. 技术架构
5.1 三层执行链路
ZhenIns 的正式执行链路已冻结为三层结构：
业务前台（ZhenIns）
→ zhen-platform-core（统一网关）
→ zhen-brain-core（保险推理与风控）
前台职责：发起业务请求、展示状态、承接结果、渲染对话。
网关职责：身份校验、权限验证、用量审计、合规留痕。
大脑职责：保险推理、方案生成、风险评估、记忆沉淀。
5.2 SSE 实时流式咨询
前端采用 Server-Sent Events (SSE) 实现 AI 对话的实时流式输出。用户发送消息后，AI 逐字生成回复，无需等待完整响应。
技术参数：
- 首 token 延迟：3–6 秒（受外部推理 API 排队影响）
- Token buffer：30ms 超时 / ≥8 字符 flush
- 前端打字机效果：CJK 75ms/字，西文 22ms/词
- 缓冲平滑：后端 burst smoothing 25ms，防止前端卡顿
- Token 精确计量：引入
tiktoken+ CJK-aware fallback，全站len(text)替换为estimate_tokens()，确保复杂保险场景的上下文预算准确可控
5.3 支付链路
支付环节已逐步上收至 zhen-platform-core 统一 checkout。新的订单流程为：
用户确认服务包 → platform-core 生成订单 → 支付宝 / 微信支付
→ 支付成功 → entitlement 同步 → ZhenIns 回执页承接
本地支付系统（曾直连支付宝/微信 SDK）已于 2026-05-16 正式退役，/billing/recharge 和旧 webhook 端点返回 410 Gone。前台仅保留支付编排页面、结果承接和回执留痕。
5.4 Scoped API Key 与 OpenClaw Skill
- Scoped API Key：跨平台接入使用统一身份 + 统一账单 + 分 scope 的权限 Key，避免万能 Key 风险
- OpenClaw Skill：将 AI 保险咨询能力以标准化接口暴露给第三方工作流，支持在本地 AI 环境中识别需人工复核的节点并脱敏转接。
insurance-broker@2.0.2已发布至 ClawHub，单一proxyaction 通道型透传，白名单端点保护
5.5 前端状态分层与竞态防护
Chat 前端已完成状态分层重构，将会话状态（conversations/messages/streaming）与业务状态（alert/consumer/handoff）解耦：
chat-session-context.tsx：纯会话容器，负责 CRUD、SSE 消费、加载状态chat-business-context.tsx：业务状态容器，负责额度、错误、handoff 建议alert-reducer.ts：Action-Based 守卫，统一入口处理状态变更
关键防护：mount 阶段 loadConversations 由 hasInitialLoadedRef guard 防止误重执行；clearQuotaState(reason) 统一入口消除竞态。
6. 商业模型
6.1 客户侧
| 服务 | 价格 | 说明 |
|---|---|---|
| 基础 AI 咨询 | 免费 | 保障缺口分析、方案方向建议 |
| 深度方案定制 | 付费 | 个性化保障方案详细设计 |
| 多方案对比 | 付费 | 2–3 套方案横向比较 |
| 保单体检 | 付费 | 已有保单梳理与缺口诊断 |
| 顾问人工复核 | 按服务包 | 复杂场景转接持证保险经纪 |
消费者对话额度由 zhen-platform-core entitlement 系统统一管理，本地 free_messages_used 字段已退役。
6.2 顾问侧
| 产品 | 形态 | 包含内容 |
|---|---|---|
zhenins.advisor.pro | 个人月费会员 | 顾问工作台、Agent2Human 技能节点、客户管理 |
zhenins.agency.seat | 团队席位 | 多顾问协作、组织权限、统一结算 |
顾问登录统一走 OAuth（auth.zhenrobot.com），本地密码体系已于 2026-05-07 正式退役。顾问工作台配备实时 WS 推送、线索池、多维度筛选、成交排行和佣金统计。
6.3 机构侧
| 产品 | 形态 | 适用对象 |
|---|---|---|
| Brokerage | 年费 | 中小型保险经纪公司 |
| Enterprise | 年费 + 实施费 | 大型机构，含私有化部署选项 |
机构方案包含：多席位、组织权限、API Key 集成、合规报表与审计导出。
6.4 定价上收
商品定价（顾问会员、团队席位、机构方案等）不再由 ZhenIns 本地维护，统一由 zhen-platform-core catalog 作为唯一真相源。前台仅负责展示和引导购买。
7. 路线图与里程碑
7.1 已完成
| 项目 | 说明 | 完成时间 |
|---|---|---|
| 消费者 SMS 轻量认证（FIC-01） | 换设备恢复、升级合并、SMS 验证码登录 | 2026-05 |
| 顾问 OAuth 统一登录（FIC-02） | 淘汰本地密码，接入统一认证 | 2026-05 |
| cookie-only 会话 | 移除 localStorage token 依赖，改为 HttpOnly cookie | 2026-05 |
| 支付 checkout 上收（ADR-008 Phase 1 & 3） | 统一走 platform-core 支付网关；本地支付系统退役 | 2026-05 |
| 消费者历史对话 CRUD | GET/POST/PATCH/DELETE 全套接口，前端侧边栏完整支持 | 2026-05 |
| 消费者 SSO（ADR-009） | auth.zhenrobot.com SMS 登录 + platform-core 身份互认 | 2026-05 |
| 精确 Token 计数 | tiktoken 引入 + CJK-aware fallback，全站替换 | 2026-05 |
| Handoff Consent 完整闭环 | 授权确认 → 顾问接收 → 撤回同意 → WS 实时同步 | 2026-05 |
| 顾问多渠道通知（A+B+C+D） | 站内通知 + Web Push + SMS + Email 四通道端到端验证 | 2026-05 |
| 前端状态竞态防护 | ChatContext 分层重构 + Action-Based guard + E2E 持久性断言 | 2026-05 |
| 设计系统升级 | typography、动效、交互细节全面优化 | 2026-05 |
7.2 进行中
| 项目 | 说明 |
|---|---|
| SSE 性能与超时优化 | 缓解复杂保险查询偶发的首 token 延迟 |
| 大模型优化（GEO） | 白皮书多版本永久 URL、Schema.org 结构化数据、RSS feed |
7.3 规划中
功能扩展由真机生态路线图统一驱动，不由 ZhenIns 单独发布。前台保持"壳"的定位，新能力通过 platform-core 和 brain-core 的升级自然承接。
附录 A：术语表
| 术语 | 客户可见解释 |
|---|---|
| Agent2Human | AI 处理标准场景，复杂场景自动或主动转接人工保险经纪的协作协议 |
| Platform Console | 登录后的统一管理中心，用于查看订单、权益、团队设置 |
| Brain-Core | 生态中的 AI 保险推理系统，ZhenIns 不直接连接，通过网关调用 |
| Entitlement | 权益与权限，决定你能使用哪些功能和服务 |
| SSE | 实时流式对话技术，让 AI 回答像打字一样逐字出现 |
| Scoped API Key | 分权限范围的调用密钥，用于第三方安全接入 |
| Consent | 授权同意，控制你的画像信息何时、以何种范围共享给顾问 |
| Token | AI 处理文本时的最小计量单位，精确计数确保复杂查询不超预算 |
附录 B：合规文档索引
本文档为 ZhenIns 公开白皮书 v1.1。详细技术规范、生态总纲和内部接口定义见上游架构文档，不由本白皮书替代。历史版本永久可访问：/whitepaper/v/v1.0。