文档: 添加Git同步与上传规范文档

docs/龙虾openclaw/git同步与上传规范.md

@@ -0,0 +1,298 @@
+# Git 同步与上传规范
+
+## 📋 概述
+本文档规范了 MkDocs 知识库项目的 Git 同步和上传流程，确保团队协作高效、代码版本可控。
+
+## 🎯 目标
+- 统一团队 Git 操作流程
+- 减少代码冲突和版本问题
+- 确保代码及时同步和备份
+- 建立规范的提交和推送习惯
+
+## 🔄 日常同步流程
+
+### 1. 开始工作前（拉取最新代码）
+```bash
+# 进入项目目录
+cd D:\mkdocs
+
+# 检查当前状态
+git status
+
+# 拉取远程最新代码
+git pull origin master
+
+# 确认同步完成
+git log --oneline -5
+```
+
+### 2. 工作过程中（定期同步）
+```bash
+# 查看是否有远程更新
+git fetch origin
+
+# 比较本地和远程差异
+git log origin/master..master  # 本地有远程没有的提交
+git log master..origin/master  # 远程有本地没有的提交
+
+# 如果有远程更新，先拉取
+git pull --rebase origin master
+```
+
+### 3. 提交更改（本地保存）
+```bash
+# 查看更改的文件
+git status
+
+# 添加所有更改（或指定文件）
+git add .                      # 添加所有更改
+# 或
+git add <文件名>               # 添加指定文件
+
+# 提交更改（描述要清晰）
+git commit -m "描述：做了什么修改，为什么修改"
+
+# 提交示例：
+# git commit -m "文档：添加用户认证模块API文档"
+# git commit -m "修复：修正MkDocs构建配置错误"
+# git commit -m "功能：新增Docker部署指南"
+```
+
+### 4. 推送到服务器（共享代码）
+```bash
+# 先拉取最新代码（避免冲突）
+git pull origin master
+
+# 如果有冲突，解决冲突后提交
+# git add .
+# git commit -m "解决合并冲突"
+
+# 推送到远程服务器
+git push origin master
+
+# 验证推送成功
+git log --oneline -3
+```
+
+## 📤 上传新文件流程
+
+### 1. 添加新文档文件
+```bash
+# 创建新文件（如：新功能文档）
+# 文件路径：D:\mkdocs\docs\龙虾openclaw\新功能.md
+
+# 添加到Git跟踪
+git add docs\龙虾openclaw\新功能.md
+
+# 或添加整个目录
+git add docs\龙虾openclaw\
+```
+
+### 2. 添加新目录结构
+```bash
+# 创建新目录
+mkdir -p docs\龙虾openclaw\新模块
+
+# 添加目录和文件
+git add docs\龙虾openclaw\新模块\
+
+# 如果目录中有需要忽略的文件，先更新.gitignore
+```
+
+### 3. 提交和推送
+```bash
+# 提交新文件
+git commit -m "新增：龙虾openclaw新模块文档"
+
+# 推送到服务器
+git push origin master
+```
+
+## 🚨 冲突处理流程
+
+### 1. 检测冲突
+```bash
+# 拉取时发现冲突
+git pull origin master
+# 输出：CONFLICT (content): Merge conflict in <文件名>
+```
+
+### 2. 解决冲突
+```bash
+# 查看冲突文件
+git status
+
+# 手动编辑冲突文件
+# 文件内容会显示：
+# <<<<<<< HEAD
+# 本地内容
+# =======
+# 远程内容
+# >>>>>>> commit-hash
+
+# 保留需要的内容，删除标记
+# 保存文件
+```
+
+### 3. 完成冲突解决
+```bash
+# 标记冲突已解决
+git add <冲突文件>
+
+# 继续合并
+git commit -m "解决合并冲突：<文件描述>"
+
+# 完成推送
+git push origin master
+```
+
+## 📝 提交信息规范
+
+### 格式要求
+```
+<类型>: <简短描述>
+
+<详细描述（可选）>
+```
+
+### 类型说明
+- **文档**: 文档新增、修改、删除
+- **功能**: 新功能、特性添加
+- **修复**: Bug修复、问题解决
+- **优化**: 性能优化、代码重构
+- **配置**: 配置文件修改
+- **依赖**: 依赖包更新
+- **测试**: 测试用例相关
+- **样式**: CSS、样式修改
+
+### 示例
+```
+文档: 添加Git同步规范文档
+
+- 详细说明日常同步流程
+- 规范提交信息格式
+- 添加冲突处理指南
+```
+
+## 🔧 高级操作
+
+### 1. 查看提交历史
+```bash
+# 简洁查看
+git log --oneline -10
+
+# 带图表查看
+git log --graph --oneline --all
+
+# 查看特定文件历史
+git log --oneline -- docs\龙虾openclaw\git同步与上传规范.md
+```
+
+### 2. 撤销操作
+```bash
+# 撤销未提交的修改
+git checkout -- <文件名>
+
+# 撤销已add但未commit的文件
+git reset HEAD <文件名>
+
+# 修改最后一次提交
+git commit --amend -m "新的提交信息"
+```
+
+### 3. 分支管理（如需）
+```bash
+# 创建新分支
+git checkout -b feature/新功能
+
+# 切换分支
+git checkout master
+
+# 合并分支
+git merge feature/新功能
+
+# 删除分支
+git branch -d feature/新功能
+```
+
+## ⚠️ 注意事项
+
+### 必须遵守
+1. **工作前必拉取**：开始工作前必须先 `git pull`
+2. **提交前必检查**：提交前用 `git status` 检查更改
+3. **描述必清晰**：提交信息必须清晰描述修改内容
+4. **冲突必解决**：遇到冲突必须手动解决，不能强制推送
+
+### 建议习惯
+1. **小步提交**：频繁提交，每次提交一个完整的小功能
+2. **及时推送**：完成一个功能后及时推送到远程
+3. **定期同步**：每小时至少同步一次远程代码
+4. **备份重要**：重要修改前创建备份分支
+
+### 禁止操作
+1. ❌ 不要强制推送 `git push -f`（除非明确知道后果）
+2. ❌ 不要提交大文件（超过100MB）
+3. ❌ 不要提交敏感信息（密码、密钥等）
+4. ❌ 不要提交自动生成的文件（如 `.obsidian/workspace.json`）
+
+## 📊 工作流程图
+
+```mermaid
+graph TD
+    A[开始工作] --> B[git pull 拉取最新]
+    B --> C[编辑文档]
+    C --> D[git add 添加更改]
+    D --> E[git commit 提交]
+    E --> F{是否有远程更新?}
+    F -->|是| G[git pull 解决冲突]
+    G --> H[git push 推送]
+    F -->|否| H
+    H --> I[工作完成]
+```
+
+## 🛠️ 工具支持
+
+### 1. Git 配置优化
+```bash
+# 设置用户名和邮箱
+git config --global user.name "你的名字"
+git config --global user.email "你的邮箱"
+
+# 设置默认编辑器
+git config --global core.editor "code --wait"
+
+# 启用颜色显示
+git config --global color.ui auto
+```
+
+### 2. 别名设置（可选）
+```bash
+# 添加到 ~/.gitconfig
+[alias]
+    st = status
+    co = checkout
+    br = branch
+    ci = commit
+    df = diff
+    lg = log --graph --oneline --all
+```
+
+## 📞 问题处理
+
+### 常见问题
+1. **权限错误**：检查 Git 服务器访问权限
+2. **网络问题**：检查网络连接，确认服务器可达
+3. **文件锁定**：关闭正在使用的文件编辑器
+4. **磁盘空间**：确保有足够的磁盘空间
+
+### 求助流程
+1. 先查看错误信息
+2. 搜索错误信息解决方案
+3. 联系团队技术支持（FE工程师）
+4. 提供完整错误日志
+
+---
+
+**最后更新**：2026-03-29  
+**维护者**：李建华（FE前端工程师）  
+**适用项目**：D:\mkdocs 知识库项目