# docs/git_workflow.md — Git 操作手册

> 项目:TPS 中台
> 仓库:`tps-dashboard`(腾讯云 Gitea: http://101.42.29.217:3000/simonkoson/tps-dashboard）
> 文档版本:v3 · 2026-07-03
> 受众:**制片人(不会 Git)** + Cline(自动遵守此规则)

---

## 阅读说明

本手册分两部分:

- **第 1-3 章**:**给制片人看的**——每一步具体到敲哪条命令、看到什么算成功
- **第 4-5 章**:**给 Cline 看的规则**——commit 规范、提交时机、Cline 的边界

不会 Git 没关系——**照本宣科,你只需要会复制粘贴**。

---

## 第 1 章:基础概念(只讲能用上的)

### 1.1 三个核心概念,一分钟搞定

**Git 仓库**:就是一个"被 Git 管起来的文件夹"。打开本地 `E:\tps-dashboard\` 这个文件夹,里面有所有项目文件 + 一个隐藏的 `.git` 子目录。**不要删 `.git`**,删了等于把保险撕了。

**commit(提交)**:相当于"存档"。每一次 commit 是一个时间点的快照,以后可以回到这个时间点。

**push(推送)**:把本地的 commit 同步到 Gitea 服务器。**push 之后才算"上传"了**,不 push 同事看不到。

**pull(拉取)**:把 Gitea 上的最新代码拉到本地。多设备开发时,**每天开工第一件事就是 pull**。

### 1.2 用菜场买菜类比

- 在家做饭(写代码)= 本地修改
- 用保鲜盒装好放冰箱(commit) = 本地存档
- 把保鲜盒带去单位食堂大冰柜(push) = 推到 Gitea
- 同事来食堂找出你的盒子带回家(pull) = 拉到他自己电脑

只要保鲜盒进了食堂大冰柜,谁来都能拿。

---

## 第 2 章:首次仓库初始化(Phase 0 Day 1 下午做)

> 单位 4090D 已装 Git、已配 用户名+邮箱(爱德华项目时弄好)。本章从创建新仓库开始。

### 2.1 在 Gitea 创建新仓库

**操作位置**:浏览器打开单位 Gitea 网址(就是你登爱德华项目的那个 Gitea)

1. 右上角点 `+` → 选 `新建仓库`(或英文 `New Repository`)
2. 填写表单:
   - **仓库名称**:`tps-dashboard`
   - **描述**:`TPS 中台 — 央视《军事科技》栏目内部工作台`
   - **可见性**:勾选 **"私有"** 或 **"团队可见"**(注意:跟爱德华那个公开仓库**不一样**,这个不公开)
   - **勾选项一定不要勾**:**不要勾** "Initialize Repository(With selected files and template)" —— 我们要的是空仓库
3. 点底部 `创建仓库`

**成功标志**:页面跳到一个新页面,显示 `tps-dashboard` 是空的,中间有一段灰底的命令提示,大概长这样(具体地址你以你那台 Gitea 的 URL 为准):

```
git clone http://localhost:3000/simonkoson/tps-dashboard.git
```

**把这一行复制下来,下一步要用**。

### 2.2 在本地 clone 仓库

**操作位置**:VS Code 打开任何窗口都行,在终端面板里执行(快捷键 `Ctrl + ` `)

```powershell
# 切换到你想放项目的位置
cd E:\tps-dashboard\

# 把刚才复制的 clone 命令粘贴运行
git clone http://localhost:3000/simonkoson/tps-dashboard.git
```

**期间可能要求输入 Gitea 账号密码**——输入即可,Git 会记住。

**成功标志**:终端显示类似:
```
Cloning into 'tps-dashboard'...
warning: You appear to have cloned an empty repository.
done.
```

`warning: empty repository` 是**正常的**——本来就是空仓库,不是错误。

完成后 `E:\tps-dashboard\` 下多了一个 `tps-dashboard` 文件夹。

### 2.3 进仓库目录

```powershell
cd E:\tps-dashboard\
```

之后所有 git 命令都在这个目录里跑。

### 2.4 把五件套 + log 拷进来

> 你应该已经从 Claude.ai 下载了这五份文件:`.clinerules`、`project_plan.md`、`dev_plan.md`、`docs/git_workflow.md`、`README.md`,加上 `logs/phase1_log.md`。

**手动操作**(用 Windows 资源管理器):

1. 在 `E:\tps-dashboard\` 下:
   - 直接拷入 `.clinerules`、`project_plan.md`、`dev_plan.md`、`README.md`(平铺四份)
   
2. 在 `E:\tps-dashboard\` 下**新建文件夹** `docs`,把 `git_workflow.md` 拷进去

3. 在 `E:\tps-dashboard\` 下**新建文件夹** `logs`,把 `phase1_log.md` 拷进去

**最终结构应该是**:

```
E:\tps-dashboard\
├── .clinerules
├── project_plan.md
├── dev_plan.md
├── README.md
├── docs\
│   └── git_workflow.md
└── logs\
    └── phase1_log.md
```

### 2.5 创建 .gitignore

`.gitignore` 是"告诉 Git 哪些文件不要管"的清单。

**操作**:在 VS Code 终端里执行:

```powershell
cd E:\tps-dashboard\
notepad .gitignore
```

记事本会弹出来(可能问你"找不到文件,要创建吗?"——选 **是**)。

把下面这些粘贴进去,**保存**:

```
# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.venv/
venv/
env/

# Node
node_modules/
dist/
build/
.vite/

# 环境配置(永远不上传)
.env
.env.local

# 编辑器
.vscode/
.idea/
*.swp

# 操作系统
.DS_Store
Thumbs.db

# 日志运行产物
*.log
cookie.txt

# 临时文件
*.tmp
*.bak
```

### 2.6 第一次 commit 和 push

**操作**:VS Code 终端里依次执行:

**第 1 条:看看 Git 看到了哪些文件**

```powershell
git status
```

**成功标志**:终端会列出一堆文件(.clinerules、project_plan.md 等),颜色应该是**红色**(表示"未跟踪")。

**第 2 条:把所有文件加进暂存区**

```powershell
git add -A
```

**成功标志**:命令执行无任何输出(Git 的传统是"没消息就是好消息")。再跑一次 `git status`,文件应该变成**绿色**了。

**第 3 条:第一次 commit**

```powershell
git commit -m "chore: 项目宪法五件套 + Phase 1 家用机日志初始化"
```

**成功标志**:终端显示类似:
```
[main (root-commit) abc1234] chore: 项目宪法五件套 + Phase 1 家用机日志初始化
 6 files changed, 1234 insertions(+)
 create mode 100644 .clinerules
 ...
```

**第 4 条:推送到 Gitea**

```powershell
git push -u origin main
```

> 如果你的 Gitea 默认分支不叫 main 而叫 master,把命令里的 `main` 换成 `master`。

**期间可能要求输入 Gitea 账号密码**,输入即可。

**成功标志**:终端显示类似:
```
Enumerating objects: ...
Writing objects: 100% (...)
To http://localhost:3000/simonkoson/tps-dashboard.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.
```

### 2.7 验证:浏览器看 Gitea

刷新一下 Gitea 那个 `tps-dashboard` 页面——**应该能看到所有文件出现了**,不再是空仓库。

**到此 Phase 0 Day 1 下午的 Git 部分完成**。继续 Day 2 装 VS Code + Cline。

---

## 第 3 章:日常使用(每天会用到的命令)

### 3.1 每天开工第一件事

```powershell
cd E:\tps-dashboard\
git status                # 看看本地有没有未提交的改动
git pull                  # 拉 Gitea 最新(如果别的机器推过)
```

### 3.2 每次离开机器前

```powershell
git status                # 看看有没有未提交的
# 如果有改动,让 Cline 自己 commit + push;
# 或者你手工(下面)
```

### 3.3 让 Cline 帮你提交

最方便的方式——**让 MiniMax M2.7 在 Plan 里下命令**:

> "现在改完了,请帮我 commit + push,commit message 写: feat: 添加 XXX 功能"

Cline(MiniMax M2.7)会自动跑 git add / git commit / git push。**这是默认推荐方式**。

### 3.4 你自己手工提交(备选)

```powershell
cd E:\tps-dashboard\
git add -A
git commit -m "fix: 修复登录页跳转问题"
git push
```

### 3.5 Phase 收尾仪式(打 tag)

每完成一个 Phase,**让 Cline 替你做这一套动作**:

```powershell
git tag -a phase1-complete -m "Phase 1 后端 + 前端骨架完工"
git push origin phase1-complete
```

**tag 命名规则**(`.clinerules` 第 7.4 节锁定):

- `phase0-env-ready`
- `phase1-complete`
- `phase2-dashboard-done`
- `phase3-knowledge-base`
- `phase4a-mvp-launch` ← **这是项目第一次对内发布,郑重一点**
- `phase4b-tps-complete`
- `phase4c-radar`
- `phase5-production` ← **这是项目正式上线**

---

## 第 4 章:commit message 规范(给 Cline 守的规矩)

### 4.1 格式

```
<type>: <中文正文>

[可选:更详细的中文说明]
```

### 4.2 type 取值表

| type | 中文 | 示例 |
|---|---|---|
| `feat` | 新功能 | `feat: 添加用户登录接口` |
| `fix` | 修 bug | `fix: 修复 created_at 字段 NOT NULL 报错` |
| `docs` | 改文档 | `docs: 更新 phase1_log` |
| `chore` | 杂项(依赖、配置)| `chore: 升级 bcrypt 到 4.0.1` |
| `refactor` | 重构 | `refactor: 重构 authStore 状态管理` |
| `style` | 格式化(空格/缩进)| `style: 统一前端缩进为 2 空格` |
| `test` | 加测试 | `test: 添加 auth 接口测试` |

**前缀英文小写,正文中文**——前缀方便工具分类,正文方便人阅读。

### 4.3 提交时机

每个独立动作单独 commit,**不要堆一坨大 commit**:

- 装完依赖 → 立刻 commit
- 建完 SQL 表 → 立刻 commit
- 写完一个完整接口 → 立刻 commit
- 修完一个 bug → 立刻 commit

**禁止**:"晚上一起 commit"或"一个 commit 多功能"。

---

## 第 5 章:Cline 的 Git 边界(给 AI 守的规矩)

### 5.1 Cline 可以自动执行(无需问用户)

- `git add`
- `git commit`
- `git push`(限当前分支)
- `git pull`
- `git status`
- `git log`(查看历史)
- `git tag -a` + `git push origin <tag>`

### 5.2 Cline 必须停下问用户

- `git reset --hard`(任何形式的 hard reset)
- `git push --force` / `git push -f`
- `git rebase`(任何形式)
- 删除分支:`git branch -d` / `git branch -D`
- 删除 tag:`git tag -d` / `git push origin --delete <tag>`
- 删除远程引用

### 5.3 永远禁止

- 删除整个 `.git/` 目录
- 修改 `.git/` 目录内任何文件

---

## 第 6 章:常见问题速查

### Q1:我推不上去,提示"Permission denied"

**原因**:Gitea 账号密码错或没权限
**解决**:确认你登录 Gitea 网页版能正常访问 `tps-dashboard` 仓库;如果能,重新输入账号密码即可。

### Q2:`git push` 时提示"rejected,请先 pull"

**原因**:Gitea 上有别的设备推过新内容,本地落后了
**解决**:先 `git pull`,再 `git push`。如果 pull 时报 conflict(冲突),停下问 Cline 或我。

### Q3:`git status` 看到一堆 .pyc 或 node_modules

**原因**:`.gitignore` 没生效
**解决**:确认 `.gitignore` 文件就在仓库根目录(`D:\tps-dashboard\.gitignore`),内容跟第 2.5 节一致。

### Q4:不小心 commit 了 .env 文件怎么办

**严重**:`.env` 含密码,绝不能进 Gitea。
**解决**:**立刻停下找 Claude Opus 4.7 处理**——这事儿要小心做,不要自己瞎搞,容易把历史搞乱。

### Q5:换了一台机器,怎么把代码搞过来

```powershell
# 在新机器上 clone 云端仓库
git clone http://101.42.29.217:3000/simonkoson/tps-dashboard.git
cd tps-dashboard
# 然后按第 7 章流程开工
```

### Q6:某次 commit 写错了想撤回

**只在最近一次 commit 还没 push 时可撤回**:

```powershell
git reset HEAD~1     # 撤回最近一次 commit,文件改动保留
```

**已经 push 的 commit**:不要自行处理,找 Claude Opus 4.7。

---

## 第 7 章:双机开发同步(单位 + 家里)

> **2026-07-03 恢复**:项目远程仓库迁至腾讯云 Gitea,单位和家里两台电脑均可开发。

### 7.0 仓库架构

| 项目 | 云端地址 | 说明 |
|---|---|---|
| **TPS 工作台(主项目)** | `http://101.42.29.217:3000/simonkoson/tps-dashboard.git` | 所有主干代码 + doco/ai-labeling 等子项目目录 |
| **配音工具** | `http://101.42.29.217:3000/simonkoson/military-tech-voice3.0.git` | 独立小应用,将来作为 tps-dashboard 子功能合入 |

云端 Gitea 用户名统一 `simonkoson`。

### 7.1 每天开工铁律(无论在哪台电脑)

```powershell
cd E:\tps-dashboard\          # 单位机路径;家里机路径按实际调整
git pull                       # 拉云端最新代码
git status                     # 确认本地干净,无冲突
# 开始干活
```

### 7.2 离开机器前铁律

```powershell
git status                     # 确认改动
git add -A                     # 暂存所有
git commit -m "feat/fix/...: 改了什么"
git push                       # 推到云端
```

**不 push 就关机 = 另一台电脑拿不到你的改动,下次必出冲突。**

### 7.3 换到另一台电脑

```powershell
git pull                       # 先拉最新
git status                     # 确认干净
# 正常开发
```

### 7.4 铁律三条(Cline 和人都必须守)

1. **开工先 pull** — 每次打开项目第一条命令就是 `git pull`
2. **收工必 push** — 做完改动 commit 后必须 push,不过夜
3. **push 前先 pull** — 防止另一台机器推过内容导致冲突

做到这三条,99% 不会冲突。万一冲突,**停下来找 Claude 处理,不要自己瞎搞**。

### 7.5 家里电脑首次克隆(只做一次)

```powershell
cd D:\myApp\lanhao2.0          # 家里机器的工作目录(按实际调整)
git clone http://101.42.29.217:3000/simonkoson/tps-dashboard.git
cd tps-dashboard
# 克隆完毕,以后按 7.1-7.3 流程开发
```

克隆时会要求输入 Gitea 用户名密码(simonkoson / 你的密码)。

### 7.6 .gitignore 不入库的文件(两台电脑都适用)

以下文件/目录**永远不推到云端**,只存在本地:
- `.env` / `.env.local`(密码密钥)
- `node_modules/` / `.venv/`(依赖,各机器自己装)
- `*.mp4` / `*.mov` / `*.psd`(大文件)
- `*.dump`(数据库备份)
- `backup_before_*.dump`(迁移备份)
- 各种中间产物(详见 `.gitignore`)

**家里电脑 clone 后需要自己装依赖**:
```powershell
# 前端
cd frontend && npm install

# 后端
cd backend && python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

---

## 第 8 章:版本演进

| 版本 | 日期 | 变化 |
|---|---|---|
| v1 | 2026-05-06 | 初版 |
| v2 | 2026-05-14 | 项目目录从 NAS(Z:\AIworks\)迁移至本地 SSD(E:\tps-dashboard\);家用机退役,唯一开发环境为单位 4090D;Phase 2 起 MiniMax M2.7 正式日常使用 |
| **v3** | **2026-07-03** | **远程仓库从本地 Gitea(localhost:3000) 迁至腾讯云 Gitea(101.42.29.217:3000);恢复双机开发模式(单位+家里);git 历史清理大文件(mp4/psd);.gitignore 加强** |

---

*本文件与 `.clinerules` 第七章互为补充。Cline 必须遵守第 4-5 章规则。*