联调验收与常见问题
完成接入配置后，建议依次验收独立工作台、平台内嵌助手、具体业务场景。先验证简单链路，再排查业务，避免把地址错误误判为模型问题。
1. 上线验收清单
身份与权限
- [ ] 平台管理员可登录，进入智能体时能够完成 SSO。
- [ ] 使用普通员工账号重复验收，不能访问管理员模型、能力等接口。
- [ ] 用无痕窗口从
/ai/work开始访问，完成一次清晰的登录授权流程，不循环跳转。 - [ ] 平台退出后，已打开的内嵌助手清理用户态；独立标签页另外核对会话失效行为，不假设所有浏览器会话自动同步退出。
页面与交互
- [ ] 右侧助手能打开，可新窗口进入独立工作台；直接刷新
/ai/work不出现 404。 - [ ] 普通文字对话能持续输出，附件发送后仍可查看，按现有能力预览或下载。
- [ ] 当前业务页上下文正确，切换页面不会沿用错误业务编号。
- [ ] 浅色、暗色和内嵌模式显示正常。
- [ ] 个人关闭、重新开启、右侧贴边和全站关闭行为符合启停说明。
业务场景：以发票报销为例
- [ ] 员工公司、部门及默认账套对应正确，费用类型和收款资料有效。
- [ ] 受支持的发票附件能够识别，金额由确定性规则校验。
- [ ] 确认前和取消后，不向平台财务库生成报销单据。
- [ ] 用户确认后生成真实报销草稿，返回真实单号和可打开的详情入口。
- [ ] 平台报销列表和详情中的发票、费用明细、收款信息及金额一致。
- [ ] 相同确认请求重试不重复生成单据；审批仍由员工在业务详情页复核后手工发起。
发票场景依赖 OCR、附件域名白名单、财务模块接口和相应版本，不是启用助手按钮后自动具备。平台需要支持 create-from-invoices 一体化接口及请求幂等；未配套时先停用对应技能，不用旧的零散保存接口冒充完整事务。
2. 助手没有出现
依次检查：
- 平台 偏好设置 → 业务偏好 → 启用 AI 助手是否关闭。
- 当前平台构建模式是否实际读取
VITE_AGENTOS_ASSISTANT_ENABLE=true。 - 是否只改了文件，却未重建部署前端；当前访问资源是否仍被 CDN 缓存。
- 是否已经贴边隐藏：查看页面右侧边缘，不要只找原来的小人位置。
全局禁用时个人开关不能恢复，请联系平台管理员。
3. 点击后白屏、加载超时或提示不可用
先在独立标签页打开 /ai/work：
- 独立页面也失败：检查智能体前端、Nginx 路径与服务状态。
- 独立页面正常，内嵌失败：检查实际请求是否为
/ai/embed/work、iframe 安全头、HTTPS 混合内容及可信来源配置。 - 请求去了
/agentos/：检查平台是否显式配置VITE_AGENTOS_URL=/ai/并重新构建。 - 首页能开，刷新子路径 404：检查
/ai/的前端历史路由回退，不要把所有 API 也回退成 HTML。
优先修正地址或代理根因，不通过放开所有跨域与安全头解决。
4. 登录循环、两次授权或回调报错
检查三类配置是否来自同一套实际部署：
- 浏览器地址：平台前端入口正确；平台使用 hash 路由时，SSO 页面须进入实际
/web/#/auth/sso-login，不是丢失/web/或#的地址。 - OAuth 客户端：客户端 ID、Secret、授权码模式、回调白名单、授权范围一致，自动批准范围按交付配置核对。
- 浏览器状态：不混用 localhost、IP 与域名；检查 HTTPS、Cookie 和回调错误提示。
授权码是一次性的，不反复刷新带 code 的回调页；从干净的 /ai/work 重新开始。不要把含授权码、Token、Secret 的完整地址发到公开群或截图中。
如需截图排障，保留错误提示与不含敏感参数的路径，同时记录发生时间、账号角色和租户，不上传真实密钥。
5. 能登录，但发消息没有输出
打开浏览器开发者工具的“网络”面板，发送一条简单消息：
- 请求没有发出或返回 404：先查前端地址及
/admin-api/agentos/专用代理。 - 返回 401/403：检查登录态、租户和账号权限，不先怀疑模型。
- 请求已建立但最后一次性输出：检查 Nginx、CDN、网关的 SSE 缓冲与超时。
- 服务端报告模型 401、超额、模型不存在或超时：检查对应模型 URL、Key、模型名、额度和网络。
对照 AgentOS 后端日志定位同一次请求。日志与截图中不要包含完整模型 Key、发票原文或银行卡号。
6. 能聊天，但不能查询或生成业务单据
先验证平台基础只读能力，再检查具体场景：
- AgentOS 后端是否能访问配置的
AGENTOS_MAINLINE_URL；容器内 localhost 是否误指向自身。 - 当前员工是否有对应业务接口和数据权限，是否关联有效员工档案、公司与部门。
- 智能体是否已关联所需技能、能力和模型，相关能力是否启用。
- 发票场景是否配套财务接口，OCR 可用，文件域名在允许名单中。
- 详情链接是否指向员工可访问的平台前端，而不是内部后端地址。
不要通过授予所有员工管理员权限，或改成全权限系统账号调用来绕过错误。
7. 推荐交付记录
保留部署版本、实际入口、反向代理路径、OAuth 客户端 ID、角色授权范围与验收结果；密钥单独安全保管，不写入验收截图。发生问题时提供：复现步骤、时间、页面路径、错误提示、角色与租户、已脱敏的请求状态。
