# GoodBuddy 静态官网

`sites` 是无需构建步骤或额外依赖的中英文静态官网源码，可直接托管整个目录。

正式站点地址：<https://mesalogo.github.io/goodbuddy/>

首页将 GoodBuddy 定位为“免注册、支持信创软硬件的一站式 AI 助手”，
优先展示三大桌面系统与双架构下载入口、统一 Agent Runtime，以及知识库、
魔法笔记、智能心跳、桌面上下文和远程消息通道等桌面助手能力。下载区位于
主要功能说明之前，并明确列出统信 UOS、银河麒麟、海光、兆芯、鲲鹏和飞腾
对应的 Linux x64 / arm64 包。页面不重复设置底部下载推广区。
英文页面位于 `en.html`，不展示信创适配文案，三个平台的下载按钮始终前往
GitHub 最新正式 Release。
首屏产品界面默认正面展示，在精确指针设备上使用克制的 3D 倾斜、
柔和跟随光效和同步浮动标签；触屏设备保持静态布局，系统启用“减少动态
效果”时不运行该交互。

## 部署

`.github/workflows/pages.yml` 会在 `main` 分支中的官网文件发生变化后，
校验并部署整个 `sites` 目录。工作流也支持在 GitHub Actions 中手动运行。

首次部署前，需要在 GitHub 仓库的 **Settings > Pages** 中将 **Source**
设为 **GitHub Actions**。站点使用项目 Pages 地址，不需要 `CNAME` 文件
或自定义域名 DNS 配置。

## 语言选择

首次访问时，`language.js` 使用浏览器的第一首选语言选择页面：中文语言进入
中文首页，其他语言进入英文页。页头的语言按钮允许手动切换，并将选择保存在
浏览器本地；之后访问优先使用手动选择。两个页面都声明 canonical 与
`hreflang` alternate 地址。手动切换语言会保留当前 URL 片段，例如从下载区
切换后仍停留在 `#download`。

## 本地预览

在仓库根目录运行：

```powershell
python -m http.server 4173 --bind 127.0.0.1 --directory sites
```

然后访问 <http://localhost:4173/>。也可以直接用浏览器打开 `sites/index.html`。

## 校验

```powershell
node sites/scripts/validate.mjs
node --check sites/app.js
node --check sites/language.js
node --check sites/release-index.js
node --test sites/scripts/app.test.mjs sites/scripts/release-index.test.mjs
```

校验脚本会检查中英文页面、语言选择、页内链接、本地资源、关键产品文案、
主题与响应式规则，以及中文下载选择器是否从受信任的正式发布索引加载并
保留 GitHub Release 回退入口。它还计算浅色弱文本与控件边框的 WCAG
对比度、检查移动导航和下载控件结构、本地字体及许可证。发布索引测试覆盖
严格 SemVer、六个目标、格式和扩展名、文件大小、SHA-256、唯一文件名及
不可变 URL，并按发布生成器的实际命名绑定版本、平台、架构和格式。移动
导航行为测试同时覆盖现代 MediaQueryList 监听与旧版 Safari 的 `addListener`
回退。英文下载入口固定指向 GitHub Release。

## 下载入口

官网正文不写死版本号，页面启动后读取最新正式发布索引。
Windows、macOS 和 Linux 下载卡片分别提供处理器架构与安装包类型选择器，
选择后直接下载经过发布校验的不可变版本对象。发布索引请求失败、
过大、发生重定向、格式无效或任一字段返回非受信任的官方下载地址时，
整组按钮会以 fail-closed 方式继续指向 GitHub 最新正式 Release，不会混用
部分 OSS 数据：

```text
https://github.com/mesalogo/goodbuddy/releases/latest
```

校验规则与桌面更新检查保持一致：索引只能指向稳定 SemVer 版本，必须恰好
包含 Windows、macOS、Linux 的 x64 / arm64 六个匹配目标；每个目标必须提供
准确的两种格式和扩展名、正的安全整数大小、64 字符小写十六进制 SHA-256、
全局唯一文件名，以及位于
`https://goodbuddy.oss-cn-beijing.aliyuncs.com/releases/v${version}/`
下、对文件名进行 URL 编码的精确地址。校验清单和 GitHub 回退地址也必须
完全匹配，所有地址都不得包含凭据、端口、查询参数或片段。

安装包文件名必须与发布生成器完全一致：Windows 使用
`GoodBuddy-${version}-windows-${arch}-setup.exe` 与
`GoodBuddy-${version}-windows-${arch}-portable.zip`；macOS 使用
`GoodBuddy-${version}-mac-${arch}.dmg|zip`；Linux x64 的 AppImage 与
DEB 分别使用 electron-builder 的 `x86_64` 与 `amd64` 架构名，Linux
arm64 使用 `arm64`。

## 字体与可访问性

站点随包提供约 48 KB 的 Inter Variable Latin 子集，不发起远程字体请求。
拉丁字符优先使用该字体；中文依次使用系统提供的苹方、微软雅黑 UI、
Noto Sans CJK SC 或思源黑体，并保留 `system-ui` 与无衬线回退。Inter 的
SIL OFL 1.1 许可证位于 `assets/fonts/inter-OFL.txt`。

浅色主题的弱文本达到 WCAG AA 正文对比度，控件边框达到至少 3:1；
站点也支持系统强制颜色与减少动态效果模式。动态替换下载链接时会保留
“在新窗口打开”的屏幕阅读器说明。移动导航打开后会暂时将页头外内容设为
`inert` 并聚焦第一个导航项；关闭时安全恢复原有 `inert` 状态和菜单按钮
焦点，切换回桌面宽度也会解除隔离。媒体查询监听兼容现代浏览器和使用
`MediaQueryList.addListener` 的旧版 Safari。

## 文件

- `index.html`：页面结构与简体中文内容
- `en.html`：不包含信创适配文案的英文页面
- `styles.css`：语义令牌、浅深主题、焦点与响应式布局
- `app.js`：主题、移动导航、当前章节和中文下载索引
- `language.js`：浏览器语言自动选择与手动语言偏好
- `release-index.js`：中文下载索引的严格、整页 fail-closed 校验
- `assets/goodbuddy-light.png`、`assets/goodbuddy-dark.png`：由 `npm run icons` 与桌面应用同步生成的官方品牌图标
- `assets/linux-plain.svg`：Devicon v2.17.0 提供的黑白 Linux 图标，许可见 `assets/devicon-LICENSE`
- `assets/fonts/inter-latin-variable.woff2`、`assets/fonts/inter-OFL.txt`：本地 Inter Variable Latin 子集及许可证
- `scripts/validate.mjs`：无依赖静态与对比度检查
- `scripts/app.test.mjs`：移动导航、焦点、内容隔离和媒体查询兼容性回归测试
- `scripts/release-index.test.mjs`：发布索引行为回归测试