root/goodbuddy

Fork 0

Files

T

mesalogo 4266ff5bea docs: expand VitePress user guide

2026-10-08 15:18:25 +08:00

14 KiB

Raw Blame History

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/ 是构建产物，已忽略，不手工编辑或提交。

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

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

在仓库根目录运行：

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 服务预览。

校验

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。

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 前缀：

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 地址：

{
  "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。本地开发运行：

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：发布索引行为回归测试

14 KiB Raw Blame History Unescape Escape