身份主体与用户
点金提供两种接入模式：App 模式（API Key）与 User 模式（智能工作台），适用于不同场景。
两种接入模式
用一句话理解：User 是"用我们产品的人"，App 是"调我们接口的系统"。
App 模式（API Key 接入）
开发者 / ISV 希望将 AI Agent 的能力集成到自己的系统中。
| 维度 | 说明 |
|---|---|
| 谁在用 | 开发者编写的程序 |
| 接入方式 | 通过 API Key 调用 OpenAPI |
| 身份管理 | 开发者自行创建和维护「身份主体」（Principal），每次 API 调用时指定 |
| 数据隔离 | 按 Principal 隔离，开发者灵活控制 |
| 前端界面 | 客户自己开发 |
| 典型场景 | 客户的 CRM 系统通过 API 接入 Agent 能力，CRM 中每个用户对应一个 Principal |
App 模式（API Key 接入）
开发者的系统（CRM / SaaS）
用户1P-001
用户2P-002
开发者维护「用户 ↔ Principal」映射
API Key 调用 OpenAPI
Header: X-Principal-Id: P-00x
自己开发前端界面
身份主体（Principal）
在 App 模式下，开发者需要理解一个核心概念：Principal（身份主体）。
| 维度 | 说明 |
|---|---|
| 职责划分 | Agent 决定"用哪个 AI"，Principal 决定"数据归谁" |
| 数据隔离 | 每个 Principal 拥有独立的对话历史、附件、权限 |
| 映射关系 | 开发者需自行维护「自己系统用户 ↔ Principal ID」的映射 |
| 创建方式 | POST /api/principal/create → 得到 principalId |
| 调用方式 | 每次 API 调用时通过 X-Principal-Id Header 传入 |
User 模式（智能工作台访问）
租户希望让自己的员工 / 客户直接使用我们提供的 AI Agent 产品。
| 维度 | 说明 |
|---|---|
| 谁在用 | 真实的人（员工、客户等） |
| 接入方式 | 登录智能工作台页面，或通过 IM 渠道（钉钉、企微、飞书）直接使用 |
| 身份管理 | 平台自动管理，用户无感 |
| 数据隔离 | 天然按用户隔离，每人只能看到自己的对话 |
| 前端界面 | 我们提供 |
| 典型场景 | 企业为内部员工开通 AI 助手账号，员工登录即用 |
User 模式（智能工作台访问）
真实用户（员工 / 客户）
员工 A
员工 B
员工 C
平台自动管理身份
账号登录（OIDC）
平台自动分配身份与权限
平台提供智能工作台（Web / 钉钉 / 企微 / 飞书）
模式对比
| 对比维度 | App 模式 | User 模式 |
|---|---|---|
| 面向角色 | 开发者 / ISV | 终端用户 |
| 接入方式 | API Key | 账号登录（OIDC） |
| 身份管理 | 开发者自主创建维护 Principal | 平台自动管理 |
| 数据隔离 | 按 Principal 隔离，灵活可控 | 天然按用户隔离 |
| 前端界面 | 客户自己开发 | 平台提供 |
选型建议
| 客户需求 | 推荐模式 |
|---|---|
| "我想让员工直接用起来，不想开发" | User 模式，开通账号即用 |
| "我想把 AI 能力嵌到自己的产品中" | App 模式，通过 API 集成 |
| "两个都要" | 可以同时使用，互不冲突 |