CI 与质量检查

本文整理当前仓库中已经存在、可以逐步接入 CI 的质量检查入口。正式公开前，建议先把轻量检查放入 GitHub Actions，把依赖硬件或耗时较长的检查保留为手动工作流或 self-hosted runner。

推荐检查分层

层级	检查项	建议触发方式
文档站	npm ci、npm run docs:build	Pull request / push
前端	npm ci、npm run i18n:check、npm run build、npm run resource-i18n:check	Pull request / push
C++ 格式	scripts/format_check.sh --check	Pull request / push
C++ 静态分析	scripts/static_analysis.sh --cppcheck、scripts/static_analysis.sh --clang-tidy	定期 / 手动 / self-hosted
CPU 测试构建	scripts/build_cpu_test.sh、build_cpu/cosmo-tests	Pull request / 手动
x86 Docker	docker compose -f docker-compose.x86.yml up -d --build	手动 / release 前
Sophon 发布包	scripts/build_sophon_package.sh	手动 / self-hosted

文档站检查

根目录 package.json 用于 VitePress 文档站：

npm ci
npm run docs:build

本地预览：

npm run docs:preview

说明：

• 文档站构建会检查 VitePress 页面、导航和站内链接。
• 当前依赖审计可能报告 npm dependency vulnerabilities，公开发布前应单独评估并记录处理结论。

前端检查

前端工程位于 src/web，并包含独立的 package-lock.json：

cd src/web
npm ci
npm run i18n:check
npm run build
npm run resource-i18n:check

说明：

• npm run build 会先通过 prebuild 自动执行 npm run i18n:check。
• resource-i18n:check 用于检查资源类国际化内容是否同步。
• 如果修改了资源文本，可先运行 npm run resource-i18n:sync，再复查 diff。

C++ 格式检查

仓库提供 scripts/format_check.sh：

bash scripts/format_check.sh --check

仅检查暂存区文件：

bash scripts/format_check.sh --staged --check

自动格式化：

bash scripts/format_check.sh --fix

说明：

• 脚本检查 src 和 test 下的 .h / .cc 文件。
• 需要本机安装 clang-format。
• 3rd、build 等目录会被排除。

C++ 静态分析

仓库提供 scripts/static_analysis.sh：

bash scripts/static_analysis.sh --cppcheck
bash scripts/static_analysis.sh --clang-tidy
bash scripts/static_analysis.sh --all

说明：

• cppcheck 适合先接入 CI，覆盖 warning、style、performance、portability 等类别。
• clang-tidy 依赖 build/compile_commands.json，需要先完成对应构建配置。
• --summary 可从 build.log 中汇总常见编译告警。

CPU 测试构建

CPU 测试构建脚本：

bash scripts/build_cpu_test.sh

脚本会配置 build_cpu，启用 BUILD_TESTS=ON，并构建：

build_cpu/cosmo-tests

构建完成后可运行：

./build_cpu/cosmo-tests

说明：

• 该路径使用 x86 CPU backend 和 ONNX Runtime。
• 脚本会生成或链接 compile_commands.json，方便 IDE 和静态分析工具使用。
• 当前脚本提示需要 pkg-config 和 OpenH264 development package。

x86 Docker 验证

x86 开发模式可用于集成级验证：

docker compose -f docker-compose.x86.yml up -d --build
docker compose -f docker-compose.x86.yml logs -f
docker compose -f docker-compose.x86.yml down

建议在 release 前至少确认：

• Web 控制台可以访问。
• 核心服务进程正常启动。
• 常用端口没有冲突。
• 首次体验路径没有阻塞。

Sophon 发布包验证

Sophon/aarch64 发布包构建入口：

bash scripts/build_sophon_package.sh

Windows PowerShell：

.\scripts\build_sophon_package.ps1

说明：

• 该检查依赖交叉编译环境、Sophon SDK 和目标运行时约束，适合放入手动 workflow 或 self-hosted runner。
• 发布前应确认 build_output/ 中导出的包名、版本号、依赖和启动脚本。

建议的 GitHub Actions 拆分

首批公开仓库可以先保留现有 Pages workflow，并逐步增加：

Workflow	内容	备注
docs	文档站依赖安装和 docs:build	已具备基础 workflow
frontend	src/web 依赖安装、i18n 检查和构建	适合普通 GitHub runner
cpp-format	format_check.sh --check	需要安装 clang-format
cpp-analysis	cppcheck / clang-tidy	可先手动触发
cpu-test-build	build_cpu_test.sh 和 cosmo-tests	依赖较重，先评估耗时
release-package	Sophon package build	建议 self-hosted runner

English

This page lists the quality gates that already exist in the repository and can be connected to CI gradually. Before the public launch, keep lightweight checks on regular GitHub-hosted runners and move hardware-dependent or long-running checks to manual workflows or self-hosted runners.

Recommended Quality Gates

Layer	Checks	Suggested trigger
Documentation	npm ci, npm run docs:build	Pull request / push
Frontend	npm ci, npm run i18n:check, npm run build, npm run resource-i18n:check	Pull request / push
C++ formatting	scripts/format_check.sh --check	Pull request / push
C++ static analysis	scripts/static_analysis.sh --cppcheck, scripts/static_analysis.sh --clang-tidy	Scheduled / manual / self-hosted
CPU test build	scripts/build_cpu_test.sh, build_cpu/cosmo-tests	Pull request / manual
x86 Docker	docker compose -f docker-compose.x86.yml up -d --build	Manual / pre-release
Sophon package	scripts/build_sophon_package.sh	Manual / self-hosted

Documentation

npm ci
npm run docs:build
npm run docs:preview

The documentation build validates VitePress pages, navigation, and internal links. Dependency audit findings should be reviewed before release.

Frontend

cd src/web
npm ci
npm run i18n:check
npm run build
npm run resource-i18n:check

The frontend build runs i18n:check through prebuild. Use resource-i18n:sync only when resource text changes are intentional, then review the resulting diff.

C++ Formatting

bash scripts/format_check.sh --check
bash scripts/format_check.sh --staged --check
bash scripts/format_check.sh --fix

The script checks .h and .cc files under src and test, excludes generated or third-party directories, and requires clang-format.

C++ Static Analysis

bash scripts/static_analysis.sh --cppcheck
bash scripts/static_analysis.sh --clang-tidy
bash scripts/static_analysis.sh --all

cppcheck is the easier first CI target. clang-tidy requires build/compile_commands.json, so it should run after a matching CMake configure step.

CPU Tests

bash scripts/build_cpu_test.sh
./build_cpu/cosmo-tests

The script enables BUILD_TESTS=ON, uses the x86 CPU backend, and builds build_cpu/cosmo-tests.

Release Checks

Use x86 Docker validation before a public release:

docker compose -f docker-compose.x86.yml up -d --build
docker compose -f docker-compose.x86.yml logs -f
docker compose -f docker-compose.x86.yml down

Use the Sophon package scripts on a properly configured builder:

bash scripts/build_sophon_package.sh

.\scripts\build_sophon_package.ps1