| name | git-workflow |
| description | Git 工作流与版本管理技能，规范分支策略、提交信息和发布流程。
触发场景：
- 用户需要创建分支或合并代码
- 用户需要规范提交信息格式
- 用户需要管理版本发布流程
触发词：Git、分支、提交、合并、版本发布
|
Git 工作流与版本管理
概述
Tauri Desktop App 的 Git 工作流与版本管理技能，规范分支命名、提交信息格式和发布流程。
🔴 多远端架构（knowledge_base 项目）
本项目有五个远端（git remote -v）：
| remote | 角色 | 定位 |
|---|
origin | Gitee (gitee.com/bkywksj/knowledge-base) | 国内主仓 |
github | GitHub (github.com/bkywksj/knowledge-base) | 主 CI 构建源 + 海外开源镜像（账号 bkywksj） |
github2 | GitHub (git@github.com:allebamala/knowledge-base.git，SSH) | 备用 CI（bkywksj 的 Actions 配额耗尽时切到这里跑）— 私有仓库；用 ~/.gh_token_allebamala；本机 SSH key 已绑 allebamala |
github3 | GitHub (https://github.com/elginbolds-cell/knowledge-base.git，token URL) | 备用 CI（bkywksj + allebamala 都耗尽时切到这里）— 私有仓库；用 ~/.gh_token_elginbolds；远端 URL 必须内嵌 token（不要存进 git credential helper —— 会覆盖 github.com 默认凭证 bkywksj） |
upstream | 原 tauri 框架模板 | 极少用，仅在同步模板时拉取 |
Actions Secrets 同步状态：
github (bkywksj)：✅ 已配齐（TAURI_SIGNING_PRIVATE_KEY + ANDROID_*）github2 (allebamala)：✅ 已配齐（与 github 一致）github3 (elginbolds-cell)：⚠️ 首次切换前需在 Settings → Secrets and variables → Actions 手动配置：TAURI_SIGNING_PRIVATE_KEY、TAURI_SIGNING_PRIVATE_KEY_PASSWORD（空字符串）、ANDROID_KEYSTORE_BASE64、ANDROID_KEYSTORE_PASSWORD、ANDROID_KEY_ALIAS、ANDROID_KEY_PASSWORD。配齐前 CI 会失败。
历史已对齐（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」— 用户说"提交推送"时
默认推 origin + github（两端历史已统一，没有任何冲突风险）；github2 / github3 是备用镜像，平时可不推，需要切备用 CI / 发版前再同步一次：
git push origin master
git push github master
如果用户只说"推 Gitee"，按字面只推 origin。
「发布版本」— 调 /release 时
走下方"发布流程"章节；tag 推到当前使用的 CI 远端（github / github2 / github3 之一，发布前必须询问用户选哪个）。Tag 只推到一个仓库 = 只触发一个 CI，避免重复构建浪费配额。
⛔ 注意事项
- 不要在 master 上直接 force push（除非你像 v1.3.0 那种明确做"两端历史合并"，且已备份）
- 推送前 fetch 各端确认本地是最新的，避免覆盖另一端有但本地没有的 commit
分支策略
分支命名规范
| 分支类型 | 命名格式 | 示例 |
|---|
| 主分支 | master / main | master |
| 开发分支 | dev | dev |
| 功能分支 | feature/{功能名} | feature/file-manager |
| 修复分支 | fix/{问题描述} | fix/window-resize-crash |
| 发布分支 | release/v{版本} | release/v0.2.0 |
提交信息规范
Conventional Commits
<type>(<scope>): <description>
[optional body]
[optional footer]
Type 定义
| Type | 说明 | 示例 |
|---|
feat | 新功能 | feat(rust): 添加文件读写 Command |
fix | 修复 Bug | fix(react): 修复状态更新不生效 |
refactor | 重构 | refactor(rust): 重构错误处理为 thiserror |
docs | 文档 | docs: 更新 README |
style | 格式 | style(rust): cargo fmt 格式化 |
test | 测试 | test(rust): 添加 Command 单元测试 |
chore | 杂务 | chore: 更新 Cargo.toml 依赖 |
build | 构建 | build: 配置 Tauri 打包参数 |
Scope 建议
| Scope | 说明 |
|---|
rust | Rust 后端代码 |
react | React 前端代码 |
tauri | Tauri 配置 (tauri.conf.json) |
caps | Capabilities 权限配置 |
deps | 依赖更新 |
多行提交信息
首选：Write 一个 UTF-8 无 BOM 文件 → git commit -F <文件>（用后删，shell 无关、中文不乱码）。
🔴 @'...'@ 是 PowerShell here-string，只能在 PowerShell 工具用；放进 Bash 会在 message 头尾各粘一行 @。
发布流程（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
手动发布（备用）
git add src-tauri/tauri.conf.json src-tauri/Cargo.toml package.json
git commit -m "release: vX.Y.Z"
git push <github_remote> <主分支>
git tag vX.Y.Z
git push <github_remote> vX.Y.Z
🔴 远程 Git 操作优先用 Sigil（检测到才启用，没装则无感回退）
需要远程认证的 git 操作（push / clone / 推送后远端核对），本会话检测到 Sigil 就优先走它（凭据由保险库注入，明文不外泄、不落 .git/config）；Sigil 没装就照常 git push，流程不受影响。
🔴 三条铁律
- 零明文：任何平台的 git 推送 / 建仓 / API 一律走 Sigil，永不手拼
https://user:TOKEN@host 或明文传 token（明文会随 .git/config 同步到云盘泄露）。
- username 别用默认：
git_push 推 Gitee / GitCode 时 username 必传该平台真实登录账号，用默认 x-access-token 会认证失败；GitHub 可用默认 x-access-token。
- 失败即停：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。
常见错误
| 错误做法 | 正确做法 |
|---|
| 直接在 master 上开发 | 创建功能分支开发 |
| 提交信息写"修改代码" | 按 Conventional Commits 规范编写 |
| 版本号只改 package.json | 同步修改 Cargo.toml 和 tauri.conf.json |
| 提交 target/ 编译产物 | 确保 .gitignore 正确配置 |
