渠道接入与租户初始化
本指南面向需要为客户自动开通 AIS 租户、同步组织员工、分配知识权限或提供免登录入口的渠道与集成商。如果只是调用已有租户的知识检索，不必实现整套渠道流程，可直接使用 平台 API Key。
两个管理层级
| 层级 | 负责的事情 | 凭据 | 不负责的事情 |
|---|---|---|---|
| 渠道平台 | 租户开户、查询、合同日期、账户资源 | 渠道平台 Token | 不直接代表租户内员工 |
| 租户业务 | 组织员工、知识库及权限、指定用户操作 | 租户用户契约或目标接口要求的凭据 | 不用于管理任意其他租户 |
先明确接口操作对象，再选择凭据。平台 HMAC 签名与租户 AES 契约是独立协议，不能相互推导密钥或交换 Token。
交付资料清单
| 资料 | 由谁提供/维护 | 确认要点 |
|---|---|---|
| API 服务地址、部署版本 | AIS 部署方 | 测试/生产分离，接口能力与版本一致 |
| 渠道 appid 与认证方式 | 双方确认 | 普通 GET 或 V2 POST，不能混用 secret |
| HMAC 共享密钥与前缀规则 | AIS 安全交付 | 仅 V2 使用，放在服务端密钥管理中 |
| AES-256 契约密钥与协议前缀 | AIS 安全交付 | 已启用契约能力；标准 Base64 解码为 32 字节 |
| 契约和登录有效期上限 | AIS 部署方 | 秒级时间、时钟同步、刷新策略 |
| 租户编码和用户映射方案 | 集成方 | 稳定编码、全局唯一要求、避免个人敏感信息 |
| 角色与知识授权方案 | 客户管理员/双方确认 | 最小必要权限、真实所有者保留 |
| 套餐与资源开通范围 | 双方商务/交付确认 | 不根据示例金额推断计费承诺 |
文档示例不包含任何环境的真实密钥。共享密钥丢失或疑似泄露时，应通过安全交付与轮换流程处理，不在工单正文发送完整值。
接入顺序与阶段验收
| 步骤 | 调用/动作 | 保存结果 | 验收条件 |
|---|---|---|---|
| 1 | 获取平台 Token | token、有效秒数 | 签名、时钟和缓存策略验证通过 |
| 2 | 创建并查询租户 | 租户 code、管理员交付资料 | 查询到正确合同、账户与渠道归属 |
| 3 | 生成管理员契约 | 服务端短时凭据 | 可以读取目标租户业务资源 |
| 4 | 创建组织与员工 | 部门 code、用户 code/id | 用户属于正确租户，账号与部门映射正确 |
| 5 | 创建知识库并授权 | 知识库 code、权限配置 | 真实所有者保留，目标成员权限准确 |
| 6 | 使用指定用户契约 | 用户短时凭据 | 已授权访问成功，未授权访问失败 |
| 7 | 按需兑换登录态 | 一次性 Token/登录 Token | 过期、重复消费和跨用户场景均验证 |
| 8 | 接入真实业务 | 检索、对话、导入等 | 数据范围和失败处理符合客户业务要求 |
共享密钥留在渠道服务端。管理员契约只用于受控的管理流程，不下发浏览器，也不替代所有最终用户进行问答。
访客与员工的边界
正式员工需要组织关系、登录方式及角色时使用 员工创建。只需要网站/App 访客标识和会话关联时使用 访客注册。访客成功注册不等于获得员工角色或页面登录权限。
标准 Chat 以鉴权用户为准；应用 Chat 的 user 用于访客记录关联。不要把两条路径的用户字段视为同一种授权机制。
上线检查
- 对每种凭据测试正常、过期、错误环境和权限不足。
- 对创建超时使用稳定编码回查，不重复创建客户租户。
- 对充值、启停、全量权限更新设置安全重试边界。
- 对外部用户与租户、员工、会话的映射做服务端校验。
- 日志只保留脱敏请求标识和业务结果；不记录密码、密钥与兑换 URL。
- 确认合同到期、用户停用和密钥轮换的实际处理流程。
详细协议按菜单中的“平台 Token → 租户管理 → 租户用户契约 → 组织员工与授权”顺序阅读。