HomeAgent/docs/zh/ci-cd-runbook.md

CI/CD 流水线手册（GitHub Actions）

2026-09-29 随仓库迁移 gitcode → GitHub 而建。此前 AtomGit 停止对普通用户 提供流水线，本仓无任何自动化验证。本文记录两条流水线的用法、机制与边界。 分支模型见 docs/git-branching.md（本文与其 §七「发版产物清单」衔接）。

0. 仓库与流水线总览

仓	位置	流水线	触发
主仓 HomeAgent	github.com/JianFeeeee/HomeAgent（公开）	ci.yml + release.yml	push / PR、release/** push
SDK 仓 homeagentsdk	github.com/JianFeeeee/homeagentsdk（公开）	release.yml	release/** push
gitcode 镜像	同名仓库	无（由主仓 Release 的 sync job 同步）	—

分支保护（main，公开仓免费）：10 项必须检查（Go build/vet/test、Race、 cross×5、GUI、C gates、Docs）+ strict（必须与 main 同步）+ 禁 force push。 ⇒ feature 合入 main 前必须过流水线（PR 的 checks 全绿才能 merge）。

gitcode 的角色：只读镜像（git push 同步）。Release 附件由 sync job 自动 补传，或手工跑 deploy/scripts/upload_assets.py（见 §3.4）。

1. CI（ci.yml）—— 每次推送到 main / release/** / PR 都跑

六个 job，全部命令均本地实测过（原则：不写"应该有用"的未验证步骤）：

job	内容	时长
Go build / vet / test	go build/vet/test ./... + make check-client-versions	~12m
Race detector	go test -race（core + waiter）	~8m
Cross-compile ×5	waiter/initconfig/mock-server 五平台（CGO=0）	~5m
GUI (node)	cd cmd/gui && npm test（纯 Node，零依赖，秒级）	<1m
C infrastructure gates	make check-csrc（告警/ABI/ASan/跨架构）	~6m
Docs build	mkdocs.yml 可解析性检查	<1m

明确不进 CI（依赖真机/密钥/内网，跑了只会变 flaky 噪音）： deploy-*.sh、waiter 真机（192.168.2.x）、npm run test-live（需真 Electron+Xvfb+真后端）、scripts/kernel-stress/*、需 DEEPSEEK_API_KEY 的 真实 LLM 测试（自带 t.Skip）。

已知边界（不是缺陷）

• 只有 waiter/initconfig/mock-server 能纯交叉编译。homed/memgc/ homed-kb-migrate 依赖 cgo（gojieba/onnx），必须原生构建（见 Makefile）。
• cmd/gui 是纯 Electron 目录（0 个 .go、无 go.mod）。go test ./... 不会包含它（Go 的 ./... 语义）；只有显式 go test ./cmd/gui 才报 "no Go files"。前端测试走 npm test。
• CGO 必须开（CI 里 CGO_ENABLED: 1）：gojieba 需要。

2. 发布（release.yml）—— release/** 推送即发版

2.1 标准发版流程（以 1.3.14 为例）

# 1. 在发布线的 worktree（干净）里 bump 版本
git worktree add /tmp/rel-v1.3.14 release/v1.3.x
cd /tmp/rel-v1.3.14
sed -i 's/Version = "1.3.13"/Version = "1.3.14"/' internal/meta/meta.go
git commit -am "release: 1.3.14"
git push origin release/v1.3.x
# 2. 流水线自动：读版本 → go build/test 门 → 下载资产 → 打包
#    → 打 tag v1.3.14 → 建 GitHub release → 传附件 → 回读校验
#    → （配了 GITCODE_TOKEN 时）同步 gitcode
# 3. 在 GitHub Actions 页看进度；全绿即发版完成

版本号唯一事实源是 internal/meta/meta.go 的 Version（SDK 仓是 meta/meta.go）。改它并推送 = 发版指令。

2.2 幂等闸门：tag 已存在 ⇒ 整轮跳过

Prepare 先查 refs/tags/v<version> 是否存在。已存在（比如改文档的推送、 cherry-pick 维护提交）则 Build/Publish/Sync 全部 skipped。不会重复发版。

2.3 发版门：go build 硬门 + go test 可显式跳过

• go build ./... —— 硬门，不可跳过。

• go test ./... —— 默认跑。历史维护线若存在既存红测试（如 release/v1.3.x 的 deepsearch 测试，main 上已修），在改动 meta 的那个 提交的正文里写 [skip-release-tests] 即可跳过：

  git commit -am "release: 1.3.14 [skip-release-tests]
  
  （正文里写明跳过理由——为什么本线的红是既存的、与本次发版无关）"
  

  跳过时 CI 输出 ::warning，决定记录在发版 commit 里可审计。 ★ 标记查在改动 meta 的提交上而非 HEAD：发版提交后常还会跟几个 维护提交，只看 HEAD 会让标记被顶掉、静默失效。

2.4 产物与验证

产物（v1.3.13 实测）：

homeagent-client_1.3.13_amd64.deb      83.5MB   客户端（不含模型）
homeagent-server_1.3.13_amd64.deb     730.1MB   服务端（含向量模型）
homeagent-full_1.3.13_amd64.deb       808.3MB   全量（模型+ORT+GUI）
homeagent_1.3.13_linux_amd64.tar.gz   839.2MB   内核+CLI+GUI 打包
SHA256SUMS                                       全量校验和

流水线内置的验证（不通过即不发版）：

• deb 元数据（Package/Version/Architecture）逐包核对；
• full/server 包内必须真的含 TextEncoder.onnx 与 libonnxruntime.so （防"默认启用但装完不能用"的假包）；
• sha256sum -c SHA256SUMS（产物先平铺再验 —— 脚本把校验和写成平铺名）；
• 发布后回读：把附件下载回来再验一遍校验和。

2.5 构建资产（ci-assets-v1 release）

server/full 的打包需要 719MB 模型 + 24MB ONNX Runtime。它们内容不随版本 变，故作为 ci-assets-v1 release 的附件一次性托管，每次发版由流水线下载 并 sha256sum -c 校验后使用：

chinese-clip-vit-b16-onnx.tar         718.8MB   Chinese-CLIP ViT-B/16 ONNX
onnxruntime-linux-amd64-1.28.0.tar     23.5MB   ORT 1.28.0 + LICENSE + TPN
SHA256SUMS

模型或 ORT 升级时：改好本地 CHINESECLIP_BUNDLE_DIR / ONNXRUNTIME_ASSET_DIR 指向的目录 → 重新打包 → 在 GitHub 上新建 ci-assets-v2 release 并上传 → 同步更新 release.yml 里的 ASSETS_TAG。

3. 运维要点（都踩过坑）

3.1 workflow 文件必须存在于目标分支

GitHub 用被推送 commit 里的 .github/workflows/*.yml 决定是否触发。 给旧发布线补流水线时，要把 workflow 文件本身 commit 到那条分支 （实测：只在 main 有时，推 release/** 什么都不触发）。

3.2 runner 上没有 electron 缓存

打包脚本从两处找 Electron：~/.cache/electron 的 zip，或 cmd/gui/node_modules/electron/dist。全新 runner 两处都没有 ⇒ release.yml 在打包前 npm ci（electron 已在 package-lock 锁定；不能 npm install --production，electron 是 devDependency 会被跳过）。

3.3 管道里的 grep -q 会因 SIGPIPE 误杀检测

dpkg-deb -c <800M 包> | grep -q <目标>：grep -q 匹配即退出、关闭读端 ⇒ tar 写 stdout 收到 EPIPE ⇒ pipefail 判失败。包越大越易触发 （80M 的 client 没事、800M 的 full 炸）。检测存在性一律 grep <pat> >/dev/null。

3.4 gh 在非 git 目录要显式 --repo

gh release download 在 /tmp/back 这类非 git 目录里会报 "not a git repository"（gh 从 cwd 的 git 上下文推断仓库）。必须 gh release download "$TAG" --repo "$GITHUB_REPOSITORY"。

3.5 gitcode 上传的路径语义

upload_assets.py 拼路径是 os.path.join(ASSET_DIR, name)： 要 cd 进资产目录、ASSET_DIR=.、传裸文件名。SDK 仓的产物多数无 扩展名，必须显式列名（自动扫描按后缀识别，会静默一个都不传）。

3.6 手工补发 gitcode 附件

CI 的 sync job 需要 secret GITCODE_TOKEN；未配置时该 job 显式跳过。 手工补发的完整流程（下载 GitHub 产物 → 建 release 条目 → 上传）：

# token 放 ~/.git-credentials（https://JianFeeeee:<token>@gitcode.com）
ASSET_DIR=<产物目录> GITCODE_REPO=JianFeeeee/HomeAgent \
  python3 deploy/scripts/upload_assets.py <tag> <token>
# release 条目必须先存在（脚本向 releases/<tag>/upload_url 取 OBS 签名 URL）

4. SDK 仓（third_party/homeagent-sdk）

与主仓同构，差异：

	主仓	SDK
版本源	internal/meta/meta.go	meta/meta.go
产物	3 deb + 1 tar.gz（2.4GB）	hmapdev_* 5 平台 + SHA256SUMS（~140MB）
CGO	必须（gojieba）	不需要（CGO_ENABLED=0 纯交叉）
测试	go test ./...	两处：根模块 + tools/hmapdev（独立 module，根的 ./... 不含它）
门	同一机制	同一机制（[skip-release-tests]、幂等闸门）

发版：改 meta/meta.go 的 Version 推 release/vX.Y.x。SDK 版本随核心的 中版本走、patch 恒为 .0（见 git-branching.md §七.1）。

5. 通知

Actions 失败会给仓库 owner 发邮件（GitHub 默认）。若嫌吵： github.com/settings/notifications → Actions 关闭，或仓库页 Watch → Custom 取消 Actions。注意失败邮件也可能是"验证步骤自身 bug"的假警报 —— 先看是哪个 job/step 红了再判断（对照 §3 的坑）。