docs: 记录已验证的 Gitea 提交与推送方式

docs/README.md

@@ -16,6 +16,7 @@
 | [部署与运维](deployment.md) | Pi 服务器部署、Xvfb/代理、crontab、日志清理 |
 | [开发指南](development.md) | 源码结构、测试、已知问题、新增新闻源 |
 | [FAQ](faq.md) | 常见问题与排查 |
+| [Git 提交流程](git-workflow.md) | 已验证的 Gitea 提交与推送方式 |
 
 ## 顶层入口
 

docs/git-workflow.md

@@ -0,0 +1,85 @@
+# Git 提交与推送方式（已验证）
+
+> 本文件记录本项目成功推送到 Gitea 的方式，后续提交请参考此流程。
+
+## 远程仓库
+
+推荐使用 SSH 地址（与 `/home/pi/news` 项目一致）：
+
+```bash
+git@192.168.1.10:simon/intl_news.git
+```
+
+HTTP 地址仅用于只读/需要 Token 时：
+
+```bash
+http://192.168.1.10:3000/simon/intl_news.git
+# push 需要用户名 + Personal Access Token，例如：
+# https://<user>:<token>@192.168.1.10:3000/simon/intl_news.git
+```
+
+## 提交身份
+
+与 `/home/pi/news` 保持一致：
+
+```bash
+git config user.name "simon"
+git config user.email "failsafe@163.com"
+```
+
+## 已验证的提交流程
+
+```bash
+# 1. 在干净 clone 上操作（避免把本地 data/.venv/.env 等带入）
+git clone git@192.168.1.10:simon/intl_news.git /tmp/intlnews_gitea
+cd /tmp/intlnews_gitea
+
+# 2. 把本地项目文件同步到 clone，注意排除运行产物和敏感文件
+rsync -a --delete \
+  --exclude='.git' \
+  --exclude='.venv' \
+  --exclude='data' \
+  --exclude='logs' \
+  --exclude='__pycache__' \
+  --exclude='.pytest_cache' \
+  --exclude='.ruff_cache' \
+  --exclude='.env' \
+  --exclude='*.pyc' \
+  /home/pi/intlnews/ ./   # 注意源目录结尾斜杠
+
+# 3. 检查是否有本地旧文件覆盖了远端较新内容
+#    如果远端某些文件比本地新，先恢复远端版本，例如：
+#    git checkout HEAD -- tests/test_report_db.py
+
+# 4. 删除不应入库的 AI Agent 本地配置残留（如有）
+#    rm -f reasonix.toml
+
+# 5. 检查变更
+git status
+git diff --stat
+
+# 6. 提交
+git config user.name "simon"
+git config user.email "failsafe@163.com"
+git add -A
+git commit -m "type(scope): 简要描述"
+
+# 7. 推送（SSH 方式，无需 HTTP 代理）
+git push origin main
+```
+
+## 注意事项
+
+- 本机全局 git 配置了 `http.proxy=http://192.168.1.160:3128`，直接用 HTTP 访问 Gitea 会卡住。
+- 使用 HTTP 时若不想走代理，可临时关闭：
+  ```bash
+  git -c http.proxy= -c https.proxy= <command>
+  ```
+- 不要提交：
+  - `.env`
+  - `.venv/`
+  - `data/`
+  - `logs/`
+  - `__pycache__/`
+  - `reasonix.toml`
+- 如果远端 main 已经比本地工作区新，先以远端为准，再叠加本地修改，避免回退远端已有功能。