Web UI

Web UI 位于 hoshimi/webui/，是一个 Vue 3 + Vite + TypeScript 应用，遵循与姊妹项目 Mizuoto 共用的 Material Design 3 体系。它只通过 HTTP 访问服务器；构建产物 dist/ 随 Python 包发布，由服务器以静态文件提供。本页讲它的结构、它和服务器之间的契约，以及修改界面时必须遵守的规则——其中大部分由 src/ 下的测试保证。

技术栈与命令复制锚点链接

package.json 的脚本（在 hoshimi/webui 中用 bun run <脚本> 运行，或通过 scripts/dev.py）：

源码布局复制锚点链接

模块之间一律用 @/ 别名导入（@/ 指向 src/），不写相对路径。

部署根路径与路由复制锚点链接

界面不编译进任何 API 地址：

• Vite 的 base 是 ./，资源用相对路径，同一份构建可以放在根路径，也可以放在反向代理的子路径下。
• src/api/baseUrl.ts 从当前脚本的 URL 推导部署根：脚本在 <根>/assets/ 下，取 /assets/ 之前的部分。所以服务器使用 api_prefix 或位于反向代理之后时，界面无需改动。
• 路由使用 hash 模式（#/overview），不需要服务器做任何重写。/channels/:id 把选中的渠道放进地址，刷新或返回手势都能回到原处。

与服务器的契约：生成的类型复制锚点链接

界面的 TypeScript 类型来自服务器的 OpenAPI 文档。改了管理 API 的请求或响应模型后，重新生成并提交：

python scripts/dev.py typegen

它把 scripts/generate_openapi.py 的输出写进临时的 hoshimi/webui/openapi.json，运行 bun x openapi-typescript 生成 src/api/schema.d.ts，再删掉临时文件。手动做同一件事：

python scripts/generate_openapi.py > hoshimi/webui/openapi.json
cd hoshimi/webui && bun run typegen

• generate_openapi.py 用空设置和一个临时数据目录构建应用，所以生成的文档只描述数据的形状，与本机的配置无关。
• openapi.json 被 .gitignore 排除；schema.d.ts 要提交。
• python scripts/dev.py typegen-check 重新生成后运行 git diff --exit-code，CI 用它在类型过期时失败。

代码通过 src/api/types.ts 的别名使用这些类型（S['SettingsView'] 等），通过 client.ts 导出的 api（openapi-fetch）发请求，并用 unwrap() 把失败变成带服务器消息的 ApiError。

数据请求复制锚点链接

• 认证：api 的中间件给每个请求加上 Authorization: Bearer <访问密钥>。密钥保存在浏览器的 localStorage（hoshimi:access-token）；服务器以 auth_required 回答 401 时，界面弹出输入访问密钥的对话框。
• 查询：src/api/queries/ 按领域封装 Vue Query，查询键集中在 queries/keys.ts，层级结构，使某个前缀失效就使其下所有键失效。4xx 的 ApiError 不重试，其他失败最多重试 2 次；窗口获得焦点时不自动重新请求。
• 实时数据：stores/live.ts 维持唯一一条到 GET /api/v1/stats/live 的连接，它驱动顶栏的实时调用面板、用量 页面和 概览 页面的卡片。连接用 fetch 读取（api/sse.ts），因为 EventSource 不能在请求头里带访问密钥。REST 仍是事实来源：一次调用结束会使用量和渠道的查询失效并重新请求；断线后以 1、2、4、8、15、30 秒的间隔重连，并从新的快照开始。

i18n复制锚点链接

界面文字放在 src/i18n/ 的三个文件里：en.ts 是来源，zh-CN.ts 和 ja.ts 是翻译。组件里这样用：

import { useI18n } from '@/i18n';

const { t } = useI18n();
t('settings.listeningOn', { address: '127.0.0.1:10600' });

• t(key, params) 先找当前语言，找不到时用英文，再找不到时返回键本身；{name} 形式的占位符由 params 替换。
• 语言偏好默认为 auto，跟随浏览器的首选语言（zh* 为简体中文，ja* 为日文，其他为英文），并在系统语言变化时更新。
• src/i18n/i18n.test.ts 要求三个文件的键完全相同、每条消息的占位符也相同。加一条文字就要在三个文件里都加上。

主题与设计令牌复制锚点链接

• 颜色：所有颜色角色由一个种子色生成（theme/scheme.ts，默认 #5267d8，用户可以换），使用 Material 的 Tonal Spot 方案，有标准、中、高三档对比度。theme/applyTheme.ts 把它们写成 :root 上的 --md-sys-color-*，并跟随系统的明暗设置。
• 静态令牌：字体、形状、高度、动效时长与缓动、状态层等在 theme/tokens.css，变量名为 --md-sys-* 和 --app-*。
• 规则：组件只用令牌，不写字面量颜色、圆角或时长。src/tokens.test.ts 检查 src/theme/ 之外的 .vue 和 .css 文件里没有十六进制颜色。
• 图表：数据系列按固定顺序使用 --app-chart-1 到 --app-chart-8 这八个经过色盲校验的颜色槽；图表带图例和悬停 / 聚焦提示。

组件、图层与动效复制锚点链接

• 共享组件：页面和组合组件从 @/ui 取用共享组件，不重新设定它们的样式（ui/index.ts 的约定）。页面的骨架是一行 Toolbar，下面是一列 PageSection；页面按内容区的宽度调整布局（@container app-content）。可能无限增长的列表放在 ScrollArea 或 DataTable 里（DataTable 可排序，超过 200 行时只渲染可见部分）。渠道页面是 ListDetail 布局。
• 选择：从少数几项中选一项（列表筛选、报表范围）用 SegmentedControl，放不下时变成下拉选择；日期用 DatePicker。
• 图层：浮在页面上的东西（对话框、侧边面板、菜单、打开的选择器）都通过 ui/layers.ts 叠放：后打开的画在上面；Esc 和点击外部只关闭最上层；模态层打开时，页面和它下面的层都设为 inert；层关闭后把焦点还给打开它的元素。
• 动效：页面之间用 View Transitions 淡入淡出；标签页和筛选沿共享的水平轴滑动（AxisPanes）；列表-详情的详情区在条目之间纵向移动（shared-axis-y）；一个视图替换另一个时淡入淡出（FadeSwap），Playground 中一个对话替换另一个时也是如此；切换 Playground 中某条消息的版本时，该消息及其后的内容沿水平轴滑动（components/chat/VersionPanes.vue，基于 AxisPanes），上方的内容保持不动；列表项使用 list 动效。设置 › 外观 › 动画（或系统的“减少动态效果”）把所有过渡换成简短的淡入淡出。

布局规则复制锚点链接

src/layout.test.ts 把下面这些规则写成测试，违反任何一条 bun run test 就失败：

.app-scroll复制锚点链接

theme/tokens.css 中的 .app-scroll 让滚动条拥有自己的通道，位于内容旁边而不是覆盖在内容上：

• Chromium 和 WebKit 使用带样式的滚动条，即使系统使用浮动滚动条（macOS、Windows 11、GTK），它也占据布局空间。设置了 scrollbar-width 或 scrollbar-color 后这些引擎会忽略 ::-webkit-scrollbar，所以任何地方都不设置它们。
• Firefox 使用细滚动条和主题颜色；Firefox 的滚动条浮动时，theme/scrollbars.ts 的 applyScrollbars() 把 data-scrollbars 设为 overlay，通道宽度设为 0。
• 没有溢出时也保留滚动条的位置（scrollbar-gutter: stable），滚动条出现时内容不会移动；菜单和选择器用 app-scroll-auto 放弃这个位置。
• --app-scroll-lane 是通道实际占用的宽度（启动时测量）；--app-scroll-head 让纵向轨道从吸顶标题下方开始，--app-scroll-inset 让滑块避开圆角。

单元测试检查的是源码；真实浏览器中的横向溢出由 scripts/check_layout.py 检查，见测试。

加一个页面复制锚点链接