# TUI 导航、布局与显示语言

运行 `search-boost`（不带参数）打开控制台。保留现有 Clack 样式。主菜单默认平铺：所有功能直接列在首页，不再需要先选择功能分类；也可在「TUI 设置 → 菜单布局」切换回文件夹模式。两种布局使用同一组操作定义与执行函数，只改变入口排列，不改变功能、权限或信任边界。

## 平铺主菜单（默认）

| 顺序 | 入口（English） | 二级内容 |
| --- | --- | --- |
| 1 | Setup wizard（首次配置向导） | 搜索引擎凭据 → 默认搜索层 → X 凭据（可跳过）→ Agent → 宿主选项 → 确认安装 |
| 2 | Manage agent integrations（管理 Agent 接入） | 安装接入 / 刷新已有接入 / 卸载接入 / 返回 |
| 3 | Status（查看当前状态） | 软件包版本、接入来源/载荷、搜索层、凭据状态、工具开关、X / Jev（只读） |
| 4 | Search engine configuration（搜索引擎配置） | 任选引擎配置，或启用 / 停用 |
| 5 | Default search layer（默认搜索层） | free / api，显示当前值 |
| 6 | Tool switches（工具开关） | 支持工具多选 → 变更预览 → 确认保存 |
| 7 | X credentials（X 凭据） | 登录导入 / Key / 移除本地副本 |
| 8 | Jev configuration (experimental)（Jev 配置） | 地址与 Key，标明实验性和发送内容 |
| 9 | Native web search（原生搜索替换） | Agent → 替换 / 保留 → 确认 |
| 10 | Print MCP snippet（输出 MCP 配置片段） | Agent → 权限选项 → 输出，不写配置 |
| 11 | TUI settings（TUI 设置） | 菜单布局、显示语言 |
| 12 | Exit（退出） | — |

排序固定，不随使用次数或安装状态自动重排。空行只作视觉分隔，不占选择项；小终端使用 Clack 的滚动列表。状态提示取实际当前值（如默认搜索层显示当前层）。若搜索层提示因损坏或不可读的密钥配置无法计算，显示“配置错误”，仍保留首页及分类菜单，不把提示失败当成菜单输入失败。实际配置/读取/写入仍严格报错，不把坏文件当作空配置或自动覆盖；正常退出首页不因该提示设置失败退出码。

## 文件夹模式（可选）

在「TUI 设置 → 菜单布局」选择「文件夹」并保存后，下次启动沿用：

| 一级菜单（English） | 二级功能 |
| --- | --- |
| 安装与接入（Installation & integrations） | 首次配置向导、管理 Agent 接入、原生搜索替换、输出 MCP 配置片段 |
| 搜索与工具（Search & tools） | 默认搜索层、工具开关 |
| 服务与凭据（Services & credentials） | 搜索引擎配置、X 凭据、Jev 配置（实验性） |
| 状态（Status） | 查看当前状态 |
| TUI 设置（TUI settings） | 菜单布局、显示语言 |

主菜单另有「退出」；分类与管理子菜单末尾有「返回」，回到实际父菜单。

## 导航行为

- 平铺模式：操作完成后回到主菜单，并保留刚使用的入口；文件夹模式：操作完成后留在所属分类，分类内 Esc / 返回主菜单回到首页。
- 向导内 Esc 取消当前操作，回到所属入口层级；主菜单 Esc 退出；Ctrl+C 退出整个控制台。
- 取消不回滚之前已经完成并保存的独立配置步骤；未提交的凭据 / 工具开关 / 布局变更不会保存。
- 安装 / 刷新接入不重复配置 Keys、搜索层或 X 凭据。首次配置向导继续依次询问这些设置，并继续逐个凭据槽位询问，不会让初始配置提前结束。
- beta.7 起删除软件包自更新和独立卸载首页入口。管理子菜单先选择操作，安装 / 刷新 / 卸载完成后留在该子菜单；返回再回到实际父层。软件包由用户用 npm 更新。
- `search-boost setup`、`install`、`refresh`、`uninstall`、`config keys|layer|x|jev|search` 等直接命令保持可用；`config keys` 的交互式流程仍是逐个槽位的顺序向导（该命令不经过首页布局）。

## 管理 Agent 接入

- **安装**：选择 Agent 和宿主参数（DSH surface/profile、Grok scope/workspace、权限/原生搜索等）；不重问凭据、搜索层或 X。已有 Grok 登记使用共用验收/刷新，不盲目重复安装。普通 `install -t grok` 是非交互路径，不弹缓存重建提示；遇到陈旧缓存应使用交互式刷新，或独立明确的 CLI 修复选项。
- **刷新**：只列出现有接入，按实际资源合并重复项，再多选精确范围；Grok 原生插件与 MCP 配置是独立可选项。取消勾选不操作、不卸载；确认后新发现的 scope/profile 不加入本次范围。只使用当前包，不查询新版本或自动 npm/npx 更新 SearchBoost；凭据、权限、禁用状态与无关配置保留。
- **卸载**：Agent / DSH 范围 → 预览实际移除目标 → 明确确认，默认取消；执行复用预览的目标计划。交互式 dry-run 也确认，但不删除内容。
- **结果**：按目标记录成功/失败；部分安装失败显示“部分完成”和失败目标，不使用成功收尾；刷新失败保留已完成目标、显示不完整并写入 `state/last-refresh.json`。
- **Grok 缓存**：先核验，再原生 update，再验缓存。仍陈旧时，完全退出 Grok并单独确认宿主 `uninstall --keep-data` / `install --trust`，默认取消、只有 literal true 授权；`-y` 不能代替这一同意。确认期间源、缓存、登记或仓库身份变化则拒绝执行。禁用插件不启用、不重装；无法验证身份和共享仓库拒绝自动重建。Esc 是拒绝重建，刷新中的其他事务仍完成并汇报；陈旧缓存依然是不完整结果，不伪装成功。移除后重装失败会说明可能缺失/部分登记，需审核来源后从安装入口恢复；刷新不新增插件。旧名称数据保留原址，不保证自动迁移复用。

## 搜索引擎配置入口

「搜索引擎配置」按需任选引擎，不再要求每次依次走完所有引擎：

```text
搜索引擎配置
  tavily / brave / exa / anysearch   凭据来源与启用状态（脱敏）
  其他凭据槽位                       仅保存，适配器尚未实现
  引擎启用 / 停用
  返回
```

选择引擎后可：设置 / 更换 API Key、设置 / 更换 Base URL、恢复默认 Base URL、移除文件中的 Key、返回搜索引擎配置。仅保存的凭据槽位只提供设置与移除，不参与路由。

「引擎启用 / 停用」仅提供已配置 Key 且适配器可运行的引擎；未配置 Key 的引擎不进入可选项（安装的 Clack 0.10 不支持 disabled option）。不存在文件 Key 时不提供移除项，过期选择也不会改写环境变量凭据；结果与当前启用状态一致时不写入文件。修改单个引擎不会重置 `enabledEngines`，也不会覆盖其他凭据、Jev 配置或未改动的字段；dry-run 只预览，不写入。保留自定义网关的查询与凭据发送提示、环境变量优先级与并发写入保护。

## 布局与显示语言偏好

「TUI 设置」中菜单布局在显示语言之前。两者保存在同一文件：

```text
~/.search-boost/config/tui.json
# 设置 SEARCH_BOOST_HOME 时：
$SEARCH_BOOST_HOME/config/tui.json
```

示例：

```json
{ "layout": "flat", "language": "en" }
```

布局规则：

- 支持值为 `flat`、`folder`；未保存过布局的配置（包括只有 `language` 的旧配置）默认平铺。
- 选择后立即生效并写回，回到新布局的主菜单；其他已保存字段保持不变。
- 与语言共用同一把锁和原子替换写入；并发写入报冲突，符号链接目标与损坏文件不会被覆盖。
- dry-run 只预览布局，不写入；取消未提交的选择不保存。保存失败不会改变当前布局。
- 布局是显示偏好，不修改搜索配置、凭据、宿主接入或非交互 CLI 行为。

语言规则：

- 支持值为 `zh-CN`、`en`。这是显示偏好，不是搜索或模型配置；不保存凭据。
- 已保存的偏好优先，下次启动及独立交互式向导沿用。
- 无偏好时，按 `LC_ALL`、`LC_MESSAGES`、`LANG`、`LANGUAGE`（首项），最后系统 locale 判断；中文环境显示简体中文，其他环境显示英文。
- 只翻译应用拥有的菜单、说明、确认、状态和操作提示。工具名、服务品牌、命令、路径、URL、用户输入、MCP 片段、原始底层错误及外部子进程输出保持原样。
- 不影响查询语言、搜索结果、Agent 回复或非交互式 CLI 输出。
- dry-run 中允许即时预览另一种语言，但不写入显示偏好或其他配置。
- 设置文件损坏时，首页及独立交互式向导提示错误并临时使用系统语言与默认平铺布局；不会自动覆盖损坏文件。请修复该文件，或删除它以恢复默认检测。语言保存失败不会改变当前显示语言。

## 验证

```bash
npm run test:tui
npm run check
```

测试覆盖菜单顺序与两种布局的入口一致性、返回与取消、Ctrl+C、布局与语言即时切换及跨进程保存、设置并发 / 损坏与 dry-run、精确刷新范围、卸载与独立缓存重建确认、引擎任选入口与凭据脱敏、初始配置向导保持完整、非交互 CLI 不变，以及部分失败、刷新中取消不硬退出和未勾选原生插件不派发。测试通过 `scripts/isolate-tests.mjs` 使用临时 HOME 和工作区，不读写用户真实配置。