tps-dashboard/docs/git_workflow.md

docs/git_workflow.md — Git 操作手册

项目:TPS 中台 仓库:tps-dashboard(腾讯云 Gitea: http://101.42.29.217:3000/lanhao/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 + `)

# 切换到你想放项目的位置
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 进仓库目录

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 终端里执行:

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 看到了哪些文件

git status

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

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

git add -A

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

第 3 条:第一次 commit

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

成功标志:终端显示类似:

[main (root-commit) abc1234] chore: 项目宪法五件套 + Phase 1 家用机日志初始化
 6 files changed, 1234 insertions(+)
 create mode 100644 .clinerules
 ...

第 4 条:推送到 Gitea

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 每天开工第一件事

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

3.2 每次离开机器前

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 你自己手工提交(备选)

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

3.5 Phase 收尾仪式(打 tag)

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

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:换了一台机器,怎么把代码搞过来

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

Q6:某次 commit 写错了想撤回

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

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/lanhao/tps-dashboard.git	所有主干代码 + doco/ai-labeling 等子项目目录
配音工具	http://101.42.29.217:3000/lanhao/military-tech-voice3.0.git	独立小应用,将来作为 tps-dashboard 子功能合入

云端 Gitea 用户名统一 lanhao。

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

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

7.2 离开机器前铁律

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

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

7.3 换到另一台电脑

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

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

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

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

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

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

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

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

以下文件/目录永远不推到云端,只存在本地:

• .env / .env.local(密码密钥)
• node_modules/ / .venv/(依赖,各机器自己装)
• *.mp4 / *.mov / *.psd(大文件)
• *.dump(数据库备份)
• backup_before_*.dump(迁移备份)
• 各种中间产物(详见 .gitignore)

家里电脑 clone 后需要自己装依赖:

# 前端
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 章规则。