JECloud AI 小匠首次启动会强制跑一次 5 步 setup 向导：① 建第一个 admin、② 配默认业务平台服务器、③ 配默认 LLM、④ 配 MCP、⑤ 完成页（汇总 + 选择去登录）。顶部标题写"这是系统首次启动，仅需 5 步即可完成初始化。约 2 分钟。"已 initialized 之后再访问 /setup 会被 setupApi.status() 自动跳到 /login，所有项后续走对应菜单改。
2.1 何时会触发 setup 向导
系统部署完成、第一次有人用浏览器访问 http://<agent-host>:3002/ 时，前端会检测后端 GET /api/system/initialized 返回 false，自动重定向到 /setup 走 SetupView 向导。整个流程只跑一次，跑完后端写入 initialized 标记，再访问 /setup 会被跳回 /admin/login。
提示： 什么时候不会触发？以下情况都不会再跑向导： - 已经走完一次 setup（数据库里至少有 1 个 admin、1 个 server、1 个 model、1 个 MCP） - 从备份恢复出来的
data/agent.db，里面已经有数据 - OEM / ops-web 下发的 init-bundle 已经把这 4 类基础数据灌好
2.2 步骤 0：创建第一个管理员
第一步先把"自己"建出来。这个账号默认是 super_admin，可以管理所有菜单，包括模型管理、提示词管理这两个超管专属项。表单 5 个输入项：登录名、显示名、邮箱、密码、再次输入密码，全部必填，前端会逐项校验，缺一项不能下一步。默认登录名 admin、显示名 系统管理员，可直接改。
| 字段 | 是否必填 | 说明 |
|---|---|---|
| 登录名 username | 必填 | 小写字母开头，3-32 位字母/数字/下划线（正则 ^[a-z][a-z0-9_]{2,31}$）。默认 admin |
| 显示名 display_name | 必填 | 不超过 32 字符；管理后台标题栏 / 操作日志中显示。默认 系统管理员 |
| 邮箱 email | 必填 | 需符合 name@domain.com 格式；用于密码找回 / 系统通知 |
| 密码 password | 必填 | 至少 8 位，建议含大小写 + 数字 |
| 再次输入密码 | 必填 | 需与上面一致，不一致会提示"两次密码不一致" |
注意： 密码记牢。setup 阶段还没邮件服务，忘记密码只能进 docker 里改
data/agent.db，或者跑scripts/reset_admin_password.py，没有图形化"忘记密码"按钮。
2.3 步骤 1：配置默认业务平台服务器
小匠是给业务平台（jecloud / jepaas）做 AI 助手，所以必须先告诉它"我要服务哪台平台"。这里配的会成为默认 server，后续业务用户登录时如果没指定，就走这台。
- 服务器名称 + 英文代号： 名称是 UI 上看到的（默认
生产环境，可改 "测试 / 演示" 等），英文代号是 2-32 位小写字母/数字/短横线（默认prod，正则^[a-z][a-z0-9-]{1,31}$），建库后不建议改。 - 服务地址（URL）： JECloud 平台访问入口，需带
http://或https://，不带末尾/。默认https://jecloud.example.com。失焦时会自动探测连通性，banner 显示「连通性 ✓ 延迟 Xms (status N)」或「似乎不通，仍可继续」，探测失败不阻止下一步。 - WebSocket 地址： 必填，桌面端实时推送地址。可手填，也可点旁边的「自动获取」按钮，向导会从平台声明（
JE_CORE_WEBSOCKETURL）取，否则按https→wss/http→ws派生，path 固定/jesocket。占位提示就是按当前 URL 派生出的 ws 地址。 - 备注： 可选，textarea 多行，写服务器用途说明。后续可在「服务器管理」改。
注意：UI 上没有「平台类型」选择控件，也没有独立的「测试连接」按钮。platform 字段（jecloud / jepaas）在表单数据里固定为 jecloud，由探测接口内部使用；连通性检查在 URL 失焦时自动跑一次。
提示： 探测失败常见原因：URL 末尾多斜杠、http/https 写错、平台还没起、Windows 防火墙拦了对应端口。banner 显示「似乎不通，仍可继续」也可以下一步，平台起来后再回「服务器管理」改。
2.4 步骤 2：配置 LLM 模型
没模型小匠就只是个空壳。默认建议用 DeepSeek，因为便宜、中文好、跑业务问答够用。setup 阶段提供 6 个 provider 卡片可选，选中后会自动填充对应的模型 ID / 显示名 / endpoint，仍可手改。后续可在「模型管理」菜单追加其他 provider。
| 字段 | 示例 / 说明 |
|---|---|
| 提供商 provider | 6 个卡片任选：deepseek（默认）/ openai / anthropic / aliyun / zhipu / custom（自定义）。选中卡片会自动带出该 provider 的默认模型 ID / 显示名 / endpoint；选「自定义」则全部清空让你手填 |
| 模型 ID code | 默认 deepseek-chat。其他示例：gpt-4o / claude-sonnet-4-6 / qwen-plus / glm-4-plus |
| 显示名 name | 默认 DeepSeek 对话。模型管理列表 / 选择器中显示 |
| API 端点 endpoint | 默认 https://api.deepseek.com/v1（兼容 OpenAI Chat Completions 协议）；走自建网关时改这里。需以 http:// 或 https:// 开头 |
| API Key api_key | provider 控制台拿，sk- 开头一长串。仅本机存储，由 master key 加密，不上传到任何外部服务。输入框右侧有「眼睛」可切换明文/密文 |
注意：步骤 2 没有「测试连通」按钮，也没有「设为默认」勾选项。校验只看 5 个字段是否填齐 + endpoint 是否合法 URL，连通性留到「模型管理」菜单再测；setup 流程跑完时这一条会自动成为系统默认模型。
注意： api_key 别填错。填错的典型表现：① 401 Unauthorized — key 错或被吊销；② 402 Insufficient Balance — 余额不足，去 provider 控制台充值；③ 调用转半天没反应 — endpoint 不通，企业网络要走代理。这些一般在跑完 setup 后第一次对话时才暴露。
2.5 步骤 3：配置 MCP
MCP（Model Context Protocol）服务提供数据分析 / 知识检索等业务工具。如 agent 和 MCP 在同一台机器跑 docker compose，默认地址 http://localhost:7000/mcp 直接下一步即可；只有把 MCP 独立部署到别的机器，才需要改 URL。
| 字段 | 默认值 / 说明 |
|---|---|
| MCP URL | 必填，默认 http://localhost:7000/mcp。需以 http:// 或 https:// 开头 |
注意：步骤 3 整页只有一个 URL 输入框，没有名称 / transport / 启用开关等字段——这些都放在跑完 setup 后的「MCP 管理」菜单里改。setup 也不做 MCP 连通测试（MCP 可能还没起来），到「MCP 管理」再点「测试」按钮验。
2.6 步骤 4：完成 → 选择去向
步骤 3 的底部按钮叫「完成初始化」（提交中显示「提交中…」），点了后端会落 admin / server / model / mcp 4 条数据，并写 initialized 标记。提交成功后页面停在 step 4（完成页），不会自动跳走，而是给两张大卡片让你自己选去哪：
- 进入管理后台（主按钮 / 第一张卡片）→ 跳
/admin/login。配 skill / MCP / 工具，管理服务器和模型，邀请其他管理员 - 查看用户登录页（次按钮 / 第二张卡片）→ 跳
/login。普通用户用平台账号登入会话
完成页同时显示本次配置摘要（管理员账号 / 默认服务器 / 默认模型 / 初始化耗时），以及顶部「系统初始化完成 🎉」横幅。/setup 路由自动关闭，下次访问会被 onMounted 的 setupApi.status() 检查跳回 /login；如果跑到一半中断（如刷新后再来），后端通过 410 状态码告诉前端"已初始化"，前端会自动 replace 到 /admin/login。
小贴士： 登录后第一件事，建议立刻去"系统 → 系统设置"看下授权状态、去"监控 → 调用日志"试发一条对话验通路，再去"品牌主题"按公司 VI 把系统名 / 图标 / 主题色改了，整个上线动作就齐了。
2.7 跑完了想改怎么办？后续修改入口对照
setup 只跑一次，跑完后续所有修改都走对应菜单，不会再让你跑一遍向导：
| setup 步骤 | 后续修改菜单 | 说明 |
|---|---|---|
| 步骤 0 创建 admin | 系统 → 管理员 /admin/admins | 加管理员、改密码、改角色、删账号 |
| 步骤 1 业务平台 | 能力配置 → 服务器管理 /admin/servers | 加 server、改地址、设默认、启禁、连通性探测 |
| 步骤 2 LLM | 能力配置 → 模型管理 /admin/models | 仅超管；加自定义 provider、改 api_key、测连通、设默认 |
| 步骤 3 MCP | 能力配置 → MCP 管理 /admin/mcp | 加 MCP server、改 transport、测试连通、启禁 |
提示： 想"重跑"setup 怎么办？没有图形化按钮，必须停掉 agent → 清掉
data/agent.db里的 initialized 标记 → 重启服务。生产环境强烈不建议这么干，缺什么去对应菜单补。