AG02 模型配置与平台对接
1. 本课配置规划
这一课接着上一课的本地环境，配置真实模型，并连接一体化平台。我们先对齐三组地址，再核对平台的应用、回调和菜单，进入智能体配置模型。最后分别验证模型自测、真实对话，以及普通员工的业务查询。全程复用已有数据库，不重新安装。
2. 三组地址与配置入口
先把三个地址分清楚：平台后端是四八零八零，给智能体调用业务接口；平台网页是五八零零，供浏览器登录和授权；智能体网页是五六六六。本地浏览器统一使用 localhost。服务端配置源是 deploy 目录的 agentos.env，修改后执行 prepare 生成配置，再重启。这里已经按这份对照完成准备，详细命令在操作手册中。
3. 在 IDEA 重启智能体后端
配置生成后，回到 IDEA。左侧选中 yudao server agentos 模块的启动主类，点顶部重新运行，并选择停止并重新运行。这里压缩编译和启动等待。看到 Application 启动完成，端口仍是默认四八零九一，就可以继续联调。平台后端和前端也要保持运行。
4. 登录本地一体化平台
先在浏览器打开 localhost 五八零零，使用平台账号登录。账号和密码在录屏中做了遮蔽。进入平台首页后，确认当前单位和部门。智能体沿用的就是这套身份，不需要另外建立一套员工账号。
5. 核对 OAuth 客户端与回调
平台：系统管理 → OAuth 2.0 → 应用管理。编辑 agentos，核对状态、authorization_code、范围与实际回调 http://localhost:5666/sso-callback。现有白名单覆盖该回调即可；已有接入不重跑首次安装 SQL。
6. 核对平台工作台菜单地址
菜单管理 → 企业管理智能体。工作台外链指向 http://localhost:5666/work，开发入口指向 http://localhost:5666/dev。按角色分别授予入口和维护模型权限。
7. 从平台打开智能体工作台
回到平台首页，通过顶部搜索输入智能体，选择智能体工作台。平台会打开本机的智能体页面。本次单位列表有多项，所以还需要选择与平台登录相同的单位。单租户环境通常不需要这一步。
8. 完成单点登录并核对身份
在智能体登录页选好单位，点击使用业务系统账号登录。因为平台已经登录，这里经过一次授权码跳转后，直接进入工作台，不用再输入密码。检查左下角的姓名、公司和部门是否与平台一致。只有身份和租户都对应，才继续配置模型。
9. 进入模型服务
管理员进入开发，选择接入下面的模型服务。当前页面还没有租户模型，会使用部署配置中的默认模型。默认配置和页面配置是两种入口，不需要反复录入同一套信息。本课额外新增一条页面模型，用来演示客户后续维护的流程。
10. 新增并保存模型
点击新建模型，填写自己的服务信息后保存。列表中出现教学模型，密钥只显示脱敏串，并提示新对话立即生效。本次只保存这一条模型。
11. 复核模型连接参数
开发 → 接入 → 模型服务 → 新建模型/编辑。平台按协议选择；名称为显示名；地址为自己的兼容服务地址；模型标识为账号实际可调用名称；API Key 对应该服务。温度留空可使用服务默认。密钥全程遮蔽。
12. 运行模型自测
回到列表，点击自测。这里会真正向刚才保存的模型发请求。等待结束后，最近自测显示通过，模型回复 ok，并记录实际耗时。这个结果说明当前地址、模型名和凭据可以配合工作，但还需要验证真实对话和业务工具调用。
13. 发送一句真实对话
切回工作，输入一句话，请助手说明查询待办与审批的边界，然后发送。可以看到真实模型返回了正文：它可以帮助查询待办及审批信息，但不能代替员工审批。这里不是预置演示文本。模型自测和工作台对话两项都已经通过。
14. 先核对员工在平台上的待办
下面换成普通员工的教学账号。先看平台首页，这位财务专员有一条待办，是 OA 用车申请单。记下画面中的单号和数量。我们只核对现有待办，不新建单据，也不点办理。接下来用同一个员工身份进入智能体。
15. 验证普通员工身份
保持这位员工在平台登录，再打开智能体登录页，选择相同单位，点使用业务系统账号登录。进入后，左下角显示财务专员和财务部门。身份检查也确认它不是管理员。这里验证员工自己的权限边界，不用管理员的查询结果替代。
16. 通过智能体只读查询待办
财务专员查询本人待办，实际调用“待办办理摘要”能力。回答为 1 条 OA用车申请单，单号 OA101-2026083100002。与同一员工平台页面一致；未办理或审批。
17. 回平台核对并完成验收
最后回到同一员工的平台待办页。仍然是一条待办，单号与智能体回答一致，状态仍为待处理。至此，我们分别验证了平台单点登录、模型自测、真实对话和员工业务只读查询。以后遇到问题，先区分身份回调、模型线路还是业务权限，再到对应页面核对；具体检查项放在配套手册。
AG02 模型与平台配置对照
复用 AG01 v3 的目录、AgentOS 独立数据库、配置和服务。本地教学平台使用本机数据库副本；不连接生产库，不重新初始化。
| 字段 | 本机值 | 用途 |
|---|---|---|
| AGENTOS_MAINLINE_URL | http://127.0.0.1:48080 | AgentOS 服务端访问平台 API，不带 /admin-api |
| AGENTOS_MAINLINE_WEB_URL | http://localhost:5800 | 浏览器登录、授权跳转 |
| AGENTOS_WEB_URL | http://localhost:5666/ | 智能体前端入口 |
| AGENTOS_TENANT_ID | 1 | 本次平台租户 ID，以实际环境为准 |
| AGENTOS_ADMIN_ROLE_ID | 1 | 本次管理员角色 ID，以实际环境为准 |
| AGENTOS_MODEL_URL | 自己的兼容服务地址 | 默认模型连接地址 |
| AGENTOS_MODEL | 账号实际可用的模型标识 | 本课实测线路为 gpt-6-luna，仅说明本次实际环境 |
| AGENTOS_MODEL_KEY | 自己的模型 API Key | 不填平台登录密码 |
配置源与生成
只维护 AgentOS 根目录下 deploy/agentos.env 的同名字段，不重复追加，不覆盖其他现有值。已有配置不重新 init。修改默认模型或平台地址后，在 AgentOS 根目录执行：
node tools/setup.mjs check --mode local
node tools/setup.mjs prepare --mode local --platform ../../ruoyi-officeprepare 仅生成配置与待审核 SQL，不会执行数据库脚本。不要手改生成的 agentos.properties、前端 .env.development.local 或 runtime.env。回到 IDEA 重启 yudao-server-agentos 的 YudaoAgentosServerApplication，工作目录保持 AgentOS 根目录，profile 保持 prod。平台 48080、平台网页 5800、AgentOS 48091/5666 均需保持运行。
默认模型与页面模型
默认模型在配置文件中维护；页面没有租户对话模型时使用它。开发 → 接入 → 模型服务可新增页面模型，页面模型优先，保存后新对话生效，无需重启。已配置默认模型即可用，不必重复配置；本课为了演示维护流程，额外保存一条教学模型。
字段：平台按兼容协议选择；名称是显示名；接口地址按服务商说明填写；模型标识必须实际可用；密钥填对应服务的 API Key；温度留空使用服务默认。根地址通常由适配层补 /v1，已有版本路径则按页面说明使用，避免重复拼接。模型列表可用不等于对话与工具调用兼容，需要逐项联调。
本次采用既有兼容网关进行真实自测和对话，不将其作为客户固定购买或使用要求。客户换自己的地址、凭据与可用模型标识后重新验收。
平台接入
新装：管理员审核 sql/generated/04_mainline.sql，在平台库显式执行一次。它包含 OAuth、菜单和角色授权；与 AgentOS 独立库 SQL 分开。已有安装不重跑首次安装脚本，逐项核对并按需调整已有记录。
- 客户端编号：agentos；状态开启。两端使用同一现有服务端配置，已有生成值继续保留。
- 授权类型包含 authorization_code；授权范围 user.read / user.write，并核对自动授权范围。
- 本地实际回调：
http://localhost:5666/sso-callback。现有白名单可能按前缀允许，需覆盖实际回调。 - 本地工作台外链：
http://localhost:5666/work；开发外链：http://localhost:5666/dev。 - 普通员工授工作台；维护人员按职责授开发入口及 agentos:model:update。菜单可见不替代接口权限。
- 本地浏览器统一 localhost；容器里的 localhost 代表容器自身，不能照抄本机服务地址。生产使用客户实际域名、反向代理与回调。
本次平台副本已有 agentos 客户端，保留记录和授权类型，与 AG01 的现有配置对齐；仅将两条智能体菜单入口指向本机。没有执行基线或首次安装脚本。
AG02 联调验收与排查
| 检查项 | 本次结果 |
|---|---|
| AgentOS 后端 | 48091 健康接口 code=0、data=UP |
| 平台登录 | localhost:5800，单位与身份正确 |
| SSO | 管理员与普通员工分别通过授权码跳转进入 |
| 模型自测 | 页面显示通过，回复 ok |
| 工作台真实对话 | 返回正文，说明只能辅助查询、不能代批 |
| 普通员工身份 | userId=210，tenantId=1，admin=false |
| 平台待办 | 1 条，OA用车申请单，OA101-2026083100002 |
| 智能体查询 | 读取 1 项能力，回答同一单号、同一数量 |
| 业务写操作 | 0 次提交、0 次办理、0 次审批 |
本次只保存一条教学模型；聊天会话与执行记录为教学验证数据。现有待办未办理，状态仍为待处理。
定位方法
- 登录循环、回调拒绝：先核对浏览器使用的域名、端口、sso-callback、客户端授权类型、租户和两端现有配置。不要混用 localhost 与 127.0.0.1 的浏览器登录态。
- 页面能开但接口连接失败：确认平台后端 48080 与 AgentOS 后端 48091 都运行，区分平台网页与平台 API 地址。
- 模型 401/403：核对服务凭据、可用额度和模型授权；不要反复新建模型掩盖错误。
- 模型 404/400：核对根地址与版本路径、实际模型标识、Chat Completions/流式/工具调用兼容性。
- 自测通过但聊天失败：分别查看对话错误与工具执行结果；一次短文本自测不能代替真实业务调用。
- 业务查询 403 或结果不同：核对当前员工、单位、业务角色、数据范围与同一时间的平台原页。权限不足应由平台管理员按职责授权，不能换管理员结果冒充员工结果。
- 修改源配置不生效：prepare 后重启；页面模型修改则新建对话验证。
自动媒体、字幕、播放器和截图检查通过后提供审阅版；完整人工试听尚待完成。