# GoodBuddy 静态官网

`sites` 包含中英文官网和使用 VitePress 默认主题的用户手册。官网可直接预览；手册正文使用 Markdown 维护，发布前需要构建。

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

中文首页定位为面向国产化与信创环境的桌面 AI 工作空间，突出内置集成 OpenCode、
Continue 与 DeepSeek Harness（预览）。中英文页面依次展示首屏编程示意、平台下载、
知识引用与笔记计划场景、产品亮点、桌面助手和常见问题。下载区是 `main` 中的第二个
`section`，紧接首屏、位于使用场景之前。导航和首屏保留直达下载的入口。
下载区明确列出统信 UOS、银河麒麟、海光、兆芯、鲲鹏、飞腾和龙芯，区分正式
x64 / arm64 安装包与独立龙芯 loong64 预览版，并说明兼容性与认证的区别。
产品演示使用可维护的 HTML/CSS 与 SVG 图标，不使用真实截图。界面中直接呈现
任务、回答和处理结果，不附加“界面示意”“示例回答”等标签。更新时同时维护
中英文文本，演示内容须符合实际功能，不编造用户案例或性能指标。
首屏示意显示所选 Runtime，不展示 Ask / Execute 模式或一般工具审批。工具说明以
已启用能力和 MCP 服务分配为准；站点校验会检查中英文页面中的旧模式文案与控件。
FAQ 使用原生 details/summary，说明模型费用、数据流向、组件准备和远端使用条件。
英文页面位于 `en.html`，用户手册由 `docs/content/` 中按功能拆分的 Markdown 内容构建到 `docs-dist/`。英文页面用平台与架构覆盖描述同一产品事实，不使用中文信创
政策语汇；页面会标明独立的 LoongArch 实验预览，但三个平台的下载按钮仍始终
前往 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`。

## 本地预览

使用 Node.js 24，在仓库根目录安装依赖后运行 `npm run docs:dev`。访问终端显示的地址，在手册 base 下打开 `zh/` 或 `en/`，默认路径为 `/docs-dist/zh/` 和 `/docs-dist/en/`。Markdown 修改会触发热更新。

预览构建产物时，先按下方命令使用本地 base 构建，再运行 `npm run docs:preview`；同样以终端显示的地址和端口为准，在 base 下打开 `zh/` 或 `en/`。

### 维护手册

- 章节顺序、双语标题和稳定 slug 维护在 `docs/manifest.ts`；VitePress 配置从该清单生成侧栏。
- 中文正文放在 `docs/content/zh/`，英文正文放在 `docs/content/en/`。每个语言目录都必须包含 manifest 中的十二个 slug：`start`、`concepts`、`connections`、`runtimes`、`workbar`、`knowledge`、`notes`、`tasks`、`supervision`、`remote`、`privacy`、`troubleshooting`。
- 每个章节文件以一个 `#` 标题开始，正文使用 `##` 和 `###`。除 `start.md` 的 `##` 章节标题外，其余文件的 `#` 标题应与 manifest 对应语言的标题一致。标题尽量使用普通文字。
- VitePress 根目录为 `docs/`，`srcDir` 为 `content`。新增章节时添加两份 Markdown 并更新 manifest，同时更新校验脚本中的必需章节清单。
- `zh/start.md` 和 `en/start.md` 分别重写为 `zh/index.md` 和 `en/index.md`，入口为 base 下的 `zh/` 和 `en/`；其余章节路径为 `zh/<slug>.html` 和 `en/<slug>.html`。
- 配置维护在 `docs/.vitepress/config.mts`，使用默认主题的本地搜索、双语侧栏和原生语言切换，不维护自定义主题或布局。
- 生产 base 为 `/goodbuddy/docs-dist/`，开发与预览默认使用 `/docs-dist/`，可用 `DOCS_BASE` 覆盖。构建和预览的 base 必须一致。开始页下载链接使用正式官网绝对地址：`https://mesalogo.github.io/goodbuddy/#download` 和 `https://mesalogo.github.io/goodbuddy/en.html#download`。
- `docs-dist/` 是构建产物，已忽略，不手工编辑或提交。

整站预览前先构建，以下命令在仓库根目录执行：

```powershell
$env:DOCS_BASE='/docs-dist/'
npm run docs:build
Remove-Item Env:DOCS_BASE
```

在仓库根目录运行：

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

然后访问官网 <http://127.0.0.1:4173/> 或 <http://127.0.0.1:4173/en.html>，中文手册 <http://127.0.0.1:4173/docs-dist/zh/>，英文手册 <http://127.0.0.1:4173/docs-dist/en/>。手册需要通过 HTTP 服务预览。

## 校验

```powershell
npm run docs:build
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。
手册校验覆盖全部 24 个构建章节的服务端渲染标题与正文、双语侧栏、语言切换和本地资源，并检查 Markdown 标题与 manifest 一致。上述命令检查生产 base；若检查本地构建，运行校验脚本时也设置 `DOCS_BASE='/docs-dist/'`。

## 下载入口

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

中文页面等待 OSS 索引时，三个正式下载入口保持禁用并显示加载状态，不会先
短暂渲染或跳转到 GitHub。只有索引请求或完整校验明确失败后，正式下载入口
才会显示 GitHub Release 回退；英文页面仍始终直接使用 GitHub Release。

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

校验规则与桌面更新检查保持一致：索引只能指向稳定 SemVer 版本，必须恰好
包含 Windows、macOS、Linux 的 x64 / arm64 六个匹配目标；每个目标必须提供
准确的格式和扩展名（Windows 两种、macOS 仅 DMG、Linux 三种），正的安全整数大小、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`；读取器仍接受历史 DMG/ZIP 清单，但当前页面不提供 macOS ZIP 选项。Linux x64 的 AppImage、DEB 与
RPM 分别使用 electron-builder 的 `x86_64`、`amd64` 与 `x86_64` 架构名。
Linux arm64 的 AppImage/DEB 使用 `arm64`，RPM 使用 `aarch64`。
Linux 处理器选择器另外提供龙芯 `loong64` 实验预览；选中后安装包类型固定为
DEB，并改用下述独立预览索引，不会把 `loong64` 注入正式六目标索引。

### 龙芯实验预览通道

龙芯包不加入上述正式索引，而使用独立 OSS 前缀：

```text
releases/
└── loongarch-preview/
    ├── latest.json
    └── v<GoodBuddy 版本>/
        ├── GoodBuddy-<版本>-linux-loong64-preview.deb
        ├── preview-manifest.json
        └── SHA256SUMS
```

版本目录不可变。先上传并公开验证三个版本对象，最后才覆盖
`releases/loongarch-preview/latest.json`；不得把预览包放入 `releases/v*`、
`releases/latest.json`、标准 GitHub Release 资产或桌面自动更新索引。
版本对象建议使用 OSS Standard 存储、继承 Bucket 的公开读取策略，并设置长期
immutable 缓存；`latest.json` 应使用 `application/json` 和短缓存或
`no-cache`。`SHA256SUMS` 必须只记录 DEB 文件名，不得记录构建容器绝对路径。

官网只读取以下严格结构，且仅接受北京 OSS
`releases/loongarch-preview/v<goodBuddyVersion>/` 下的精确 HTTPS 地址：

```json
{
  "formatVersion": 1,
  "product": "GoodBuddy LoongArch Preview",
  "goodBuddyVersion": "0.11.5",
  "previewVersion": "0.11.5-loong64-preview.1",
  "architecture": "loong64",
  "format": "deb",
  "artifact": {
    "name": "GoodBuddy-0.11.5-linux-loong64-preview.deb",
    "size": 186853872,
    "sha256": "672321e314fbdb91c6d7b2b549a838e556bd7e597746a3e6d346b936f2ff8369",
    "url": "https://goodbuddy.oss-cn-beijing.aliyuncs.com/releases/loongarch-preview/v0.11.5/GoodBuddy-0.11.5-linux-loong64-preview.deb"
  },
  "manifestUrl": "https://goodbuddy.oss-cn-beijing.aliyuncs.com/releases/loongarch-preview/v0.11.5/preview-manifest.json",
  "checksumUrl": "https://goodbuddy.oss-cn-beijing.aliyuncs.com/releases/loongarch-preview/v0.11.5/SHA256SUMS"
}
```

上传仍应使用 GitHub OIDC 获取的短期 STS 凭据和固定 `ossutil 2.3.0`，Bucket
为 `goodbuddy`，Endpoint 为 `https://oss-cn-beijing.aliyuncs.com`，Region
为 `cn-beijing`。上传版本对象前先读取目标对象元数据：不存在时才上传，已存在
且大小和 SHA-256 相同时跳过，任一字节不同时必须停止；`--update` 只用于传输
优化，不能代替不可变性检查。也可为版本前缀启用 OSS 保留策略/WORM。指针仅在
所有公开 GET、大小、SHA-256、manifest 和 DEB 元数据检查通过后使用
`--force` 更新。手工上传时也应遵循同一顺序，不使用长期 AccessKey。

若独立索引不存在、超时、过大、字段多缺、版本不稳定、摘要格式错误或任一
URL 不匹配受信任前缀，中文官网选择龙芯处理器时会保持下载按钮禁用；Linux
x64 / arm64 及另外两个正式平台入口不受影响。英文页面继续只展示正式
GitHub Release。

## 字体与可访问性

站点随包提供约 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。

## 手册开发

手册正文维护在 `docs/content/zh/` 与 `docs/content/en/`，章节清单维护在
`docs/manifest.ts`，主题、语言、侧栏和本地搜索配置维护在 `docs/.vitepress/config.mts`。本地开发运行：

```powershell
npm run docs:dev
```

发布前清除本地 `DOCS_BASE` 覆盖并运行 `npm run docs:build`。VitePress 将中英文各十二个章节及资源生成到 `docs-dist/`，入口为 `docs-dist/zh/index.html` 和 `docs-dist/en/index.html`。Pages 工作流会在校验前自动构建；不要直接编辑构建产物。

## 文件

- `index.html`：页面结构与简体中文内容
- `en.html`：不包含信创适配文案的英文页面
- `docs/content/zh/`、`docs/content/en/`：按功能拆分的中英文手册 Markdown 正文
- `docs/manifest.ts`：手册章节顺序、标题和中英文映射
- `docs/.vitepress/config.mts`：VitePress 默认主题、语言、路由、本地搜索和构建配置，输出到 `docs-dist/`
- `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`：发布索引行为回归测试