git-workflow

name: git-workflow description: | Git 工作流与版本管理技能，规范分支策略、提交信息和发布流程。

触发场景：

• 用户需要创建分支或合并代码
• 用户需要规范提交信息格式
• 用户需要管理版本发布流程

触发词：Git、分支、提交、合并、版本发布

Git 工作流与版本管理

概述

Tauri Desktop App 的 Git 工作流与版本管理技能，规范分支命名、提交信息格式和发布流程。

🔴 双远端架构（knowledge_base 项目）

本项目有三个远端（git remote -v）：

历史已对齐（v1.3.0 起）

v1.3.0 发布时（2026-04-26）已经把 GitHub 历史 force-sync 到 Gitee，两端 commit hash 完全一致、共享 git 祖先，从此可以走标准 git workflow，不再需要 cherry-pick 同步。

备份分支 backup-before-gh-sync-v1.3.0 还留在 Gitee 上，万一以后发现丢了什么内容可以从这里救回来。

🔴 提交推送规则（knowledge_base 项目）

「日常 commit」— 用户说"提交推送"时

默认两端都推（两端历史已统一，没有任何冲突风险）：

git push origin master       # Gitee 主仓
git push github master       # GitHub（CI 触发源 + 海外镜像）

如果用户只说"推 Gitee"，按字面只推 origin。

「发布版本」— 调 /release 时

走下方"发布流程"章节；tag 同时推两端，CI 会从 GitHub 端打 tag 触发构建。

⛔ 注意事项

1. 不要在 master 上直接 force push（除非你像 v1.3.0 那种明确做"两端历史合并"，且已备份）
2. 推送前 fetch 双端确认本地是最新的，避免覆盖另一端有但本地没有的 commit

分支策略

分支命名规范

提交信息规范

Conventional Commits

<type>(<scope>): <description>

[optional body]

[optional footer]

Type 定义

Scope 建议

发布流程（CI 全自动模式）

项目已配置 GitHub Actions CI，本地不需要执行 pnpm tauri build。 使用 /release 命令可自动完成全部发布流程。

1. 更新版本号（三处同步）
   - package.json: version
   - src-tauri/Cargo.toml: version
   - src-tauri/tauri.conf.json: version
2. 更新 release 仓库 README.md（下载链接 + 版本历史）
3. 提交并推送 release 仓库 README 变更
4. 提交源码仓库 + 推送到 GitHub
5. 打 Git Tag（v*.*.* 格式）并推送
   → 自动触发 GitHub Actions CI
   → CI 构建 Windows/macOS/Linux 三平台安装包
   → CI 自动推送产物 + update.json 到 release 仓库

快速发布

# 使用 /release 命令一键发布
/release

手动发布（备用）

# 1. 更新版本号后提交
git add src-tauri/tauri.conf.json src-tauri/Cargo.toml package.json
git commit -m "release: vX.Y.Z"

# 2. 推送到 GitHub
git push <github_remote> <主分支>

# 3. 打 Tag 触发 CI
git tag vX.Y.Z
git push <github_remote> vX.Y.Z

🔴 远程 Git 操作优先用 Sigil（检测到才启用，没装则无感回退）

需要远程认证的 git 操作（push / clone / 推送后远端核对），本会话检测到 Sigil 就优先走它（凭据由保险库注入，明文不外泄、不落 .git/config）；Sigil 没装就照常 git push，流程不受影响。

🔴 三条铁律

1. 零明文：任何平台的 git 推送 / 建仓 / API 一律走 Sigil，永不手拼 https://user:TOKEN@host 或明文传 token（明文会随 .git/config 同步到云盘泄露）。
2. username 别用默认：git_push 推 Gitee / GitCode 时 username 必传该平台真实登录账号，用默认 x-access-token 会认证失败；GitHub 可用默认 x-access-token。
3. 失败即停：Sigil 报错（锁库 / 缺凭据 / 能力未启用）→ 停下提示用户处理，绝不回退明文 token。

用法

• 检测：本会话能 ToolSearch 到 mcp__sigil__git_push → 可用；查不到 → 回退普通 git push，不报错不卡流程。
• 选凭据：先 mcp__sigil__list_credentials 按平台（gitee_token / gitcode_token / github_token）查到对应 credential_name，不写死猜。
• 推送：mcp__sigil__git_push(repo_path=<仓库绝对路径>, remote=<远程名>, branch=<分支>, credential_name=<查到的>, username=<Gitee/GitCode 传真实账号 · GitHub 用 x-access-token>)。多 remote 逐个推。
• 建仓 / 改描述 / 查提交：mcp__sigil__{平台}_repo_create（🔴 private: true，绝不建公开仓）/ mcp__sigil__{平台}_repo_update / mcp__sigil__{平台}_commits_list。
• 失败：按 Sigil 错误前缀处置（解锁金库 / 补凭据 / 启用能力），绝不落明文 token。

常见错误