# 新手引导窗口模式适配与模型配置跳转说明

## 背景

本次修改围绕 `kylin-aiassistant` 的新手引导流程展开。原实现默认软件以侧边栏模式启动，新手引导在侧边栏模式下弹出。现在软件默认从窗口模式启动，因此需要让新手引导在窗口模式下适配标题栏下方的主内容区域，并在启动准备完成后再展示。

## 启动流程调整

涉及文件：

- `kylin-aiassistant/res/qml/main.qml`

调整内容：

- 新增 `pendingStartupPageSwitch`，保证启动后只执行一次初始页面切换。
- 新增 `showStartupPage()`，统一处理启动遮罩结束后的页面切换。
- `showStartupPage()` 会等待以下条件满足后再切页：
  - `showStartupMask === false`
  - `mainContentLoader.active === true`
  - `introductionViewRef` 已经创建
  - `pendingStartupPageSwitch === true`
- 30 秒启动超时路径也改为设置 `showStartupMask = false`，避免只隐藏遮罩但不触发后续页面切换。
- 启动后仍会通过 `Qt.callLater(windowCtrl.checkUnProcessFile)` 检查右键发送文件等启动参数。

当前临时状态：

- `checkAndShowIntroduction()` 目前是调试状态，每次启动都会执行 `onChangeWindowPage(0)`，用于方便查看新手引导效果。
- 恢复正式逻辑时，应改回读取 `msgPane.getConfigValue("is-first-install")`：

```qml
function checkAndShowIntroduction() {
    var isFirstInstall = msgPane.getConfigValue("is-first-install")
    console.log("checkAndShowIntroduction - isFirstInstall:", isFirstInstall)
    if (isFirstInstall === "true" || isFirstInstall === true) {
        onChangeWindowPage(0)
    } else {
        onChangeWindowPage(1)
    }
}
```

## 新手引导整体布局

涉及文件：

- `kylin-aiassistant/res/qml/IntroductionContent.qml`

调整内容：

- 新手引导内容改为填满标题栏下方的可用区域。
- 主内容左右边距统一为 `72px`。
- 底部按钮区域距离底部 `72px`。
- 页面内容区域从原来的固定高度改为 `Layout.fillHeight`，适配窗口模式。

保留逻辑：

- 用户同意协议后仍会写入 `is-first-install = false`。
- 用户不同意协议仍会写入 `is-first-install = true` 并退出。

## 用户协议页

涉及文件：

- `kylin-aiassistant/res/qml/AgreementPage.qml`

调整内容：

- 协议页内容区域改为填满新手引导页面中间区域。
- 外层使用灰色圆角背景容器。
- 协议内容从 `TextArea` 改为 `Text + Flickable`：
  - 避免 `TextArea enabled/readOnly` 样式导致文字不可见。
  - 避免 `Flickable.contentWidth` 和 `TextArea.width` 形成尺寸绑定问题。
- `XMLHttpRequest` 加载 `qrc:/` HTML 资源时兼容 `status === 0` 和 `status === 200`，避免本地资源读取成功但被误判失败。

## 小技巧页

涉及文件：

- `kylin-aiassistant/res/qml/ShortcutsPage.qml`

调整内容：

- 中间卡片从固定 `370x466` 改为填满可用空间。
- 内容区域左右内边距调整为 `32px`，上下内边距调整为 `24px`。
- 两个快捷键说明块使用 `Layout.fillHeight` 分配空间。
- 快捷键图片宽度填满，图片高度根据页面高度限制，避免窗口模式下布局过大。

## 模型添加页

涉及文件：

- `kylin-aiassistant/res/qml/AddModelPage.qml`

调整内容：

- 中间大控件背景从 `#F6F6F6` 改为 `#FFFFFF`。
- 内容从上下排列改为左右排列：
  - 左侧为模型配置说明文字。
  - 右侧为 `model-add.svg` 图片。
- 外层控件改为填满可用高度，适配窗口模式。

## 配置按钮跳转 Models 页面

涉及文件：

- `kylin-aiassistant/res/qml/IntroductionContent.qml`
- `kylin-aiassistant/res/qml/IntroductionView.qml`
- `kylin-aiassistant/res/qml/Chat.qml`

原逻辑：

- 模型添加页点击“配置”按钮后，触发 `msgPane.openUkuiControlCenter()`。
- 结果是跳转到控制面板里的模型配置页面。

新逻辑：

- `IntroductionContent.qml` 将原来的 `openSettings()` 信号改为 `openModelsPage()`。
- `IntroductionView.qml` 收到 `openModelsPage` 后：
  - 关闭新手引导。
  - 调用 `root.mychatRef.openModelsPage()`。
- `Chat.qml` 新增 `openModelsPage()`：
  - 如果当前不在 Agent/任务模式，则切换到 Agent/任务模式。
  - 选中顶部导航栏的 `Models` tab。
  - 设置 WebView URL 到 `/model` 路由。

相关路由：

- `Chat` tab: `/`
- `Channels` tab: `/channel`
- `Capabilities` tab: `/skills`
- `Tasks` tab: `/cron`
- `Models` tab: `/model`

## 验证记录

已执行过的检查：

```bash
qmllint kylin-aiassistant/res/qml/main.qml \
        kylin-aiassistant/res/qml/IntroductionView.qml \
        kylin-aiassistant/res/qml/IntroductionContent.qml \
        kylin-aiassistant/res/qml/Chat.qml \
        kylin-aiassistant/res/qml/MainTopTabBar.qml

git diff HEAD --check -- kylin-aiassistant/res/qml/main.qml \
        kylin-aiassistant/res/qml/IntroductionView.qml \
        kylin-aiassistant/res/qml/IntroductionContent.qml \
        kylin-aiassistant/res/qml/Chat.qml \
        kylin-aiassistant/res/qml/MainTopTabBar.qml \
        kylin-aiassistant/res/qml/AgreementPage.qml \
        kylin-aiassistant/res/qml/ShortcutsPage.qml \
        kylin-aiassistant/res/qml/AddModelPage.qml
```

检查结果均通过。

## 注意事项

- 当前为了调试，`main.qml` 中的新手引导仍是每次启动都显示。
- 合入正式版本前需要恢复为仅 `is-first-install` 为 `true` 时显示。
- 本次会话只应关注 `kylin-aiassistant/res/qml` 下的新手引导和 Chat Models 跳转相关文件。
