# 版本控制管理指南 - 番茄小说创作

## 🎯 版本控制目标

### 1. 版本管理
- 每次修改都有清晰的记录
- 可以随时恢复到任意版本
- 多个副本同时开发互不干扰

### 2. 协作支持
- 适合一人多设备创作
- 支持未来多人协作
- 清晰的职责划分



## 🏗️ Git 工作区结构

### 核心配置

```
workspace/
├── AGENTS.md          # 工作区核心配置文件
├── SOUL.md            # 身份配置文件
├── USER.md           # 用户信息文件
├── MEMORY.md          # 长期记忆文件
├── TOOLS.md           # 本地工具配置
├── HEARTBEAT.md       # 心跳检查配置
├── BOOTSTRAP.md       # 引导文件（可删除）
├── VERSION_CONTROL.md # 此文件
├── GIT_WORKFLOW.md    # Git 工作流详情
├── .gitignore         # Git 忽略规则
├── memory/            # 日记录文件夹
├── novel/             # 小说内容文件夹
├── scripts/           # 工具脚本文件夹
│   ├── git-setup.sh  # Git 工作区初始化
│   ├── git-daily.sh  # 每日管理脚本
│   ├── git-novel-workflow.sh  # 小说工作流
│   └── auto-backup.sh # 自动备份脚本
└── backups/           # 备份文件夹
```



### 3. 灾难恢复
- 本地和远程双重备份
- 数据丢失风险最小化
- 快速重建工作区





## 📋 主要脚本说明

### git-setup.sh
**用途**: 初始化Git工作区
**功能**:
- 设置Git用户信息
- 创建必要的目录
- 配置Git别名
- 设置提交信息模板

```bash
# 运行方法
./scripts/git-setup.sh
```



### git-daily.sh
**用途**: 日常版本管理
**功能**:
- 检查未提交的变更
- 生成提交信息
- 拉取远程更新
- 推送本地变更

```bash
# 运行方法
./scripts/git-daily.sh
```



### git-novel-workflow.sh
**用途**: 小说创作专用工作流
**功能**:
- `start <chapter-name>` 开始新章节
- `save <chapter-num>` 保存章节进度
- `finish <chapter-num>` 完成章节
- `backup` 创建备份
- `restore <chapter-num>` 恢复版本



```bash
# 运行方法
./scripts/git-novel-workflow.sh start chapter-19
```



### auto-backup.sh
**用途**: 自动备份工作区
**功能**:
- 打包工作区
- 压缩备份
- 清理旧备份
- 保留最新30个备份



## 🔧 快速开始

### 1. 初始化Git工作区

```bash
./scripts/git-setup.sh
```

**作用**: 完成基础配置



### 2. 添加新章节

```bash
./scripts/git-novel-workflow.sh start chapter-19
```

**作用**: 创建章节分支并开始创作





### 3. 日常提交

```bash
# 选项1：手动运行
./scripts/git-daily.sh



# 选项2：配置自动运行（推荐）
# 添加到 crontab -e 中：
# 0 */3 * * * cd /root/.openclaw/workspace && ./scripts/git-daily.sh >/dev/null 2>&1
```



### 4. 定期备份

```bash
./scripts/auto-backup.sh
```

**作用**: 创建工作区完整备份





## 🚀 Git 工作流使用指南



### 章节开发

```bash
# 1. 开始新章节
./scripts/git-novel-workflow.sh start chapter-19



# 2. 创作过程中保存进度
./scripts/git-novel-workflow.sh save 19



# 3. 完成章节
./scripts/git-novel-workflow.sh finish 19
```



### 日常操作

```bash
# 1. 检查状态
git status



# 2. 提交日常变更
git add .
git commit -m "feat(chapter-19): 保存进度"



# 3. 同步远程
git pull origin develop
git push origin develop
```



### 版本管理

```bash
# 1. 查看历史
git log --oneline -10



# 2. 查看文件变更
git diff



# 3. 恢复特定版本
git checkout <commit-hash>
```



## 📁 文件组织规范



### 版本控制文件

| 文件 | 用途 | 备注 |
|------|------|------|
| `*.md` | 配置文件 | 版本控制 |
| `novel/` | 小说内容 | 章节、人物设定 |
| `scripts/` | 工具脚本 | Git 管理工具 |
| `backups/` | 备份文件 | 定期备份 |
| `memory/` | 日记录 | 每天记录 |



### 忽略规则 (`.gitignore` 核心)

```gitignore
# 编译产物
*.pyc
__pycache__/

# 运行时文件
*.log
*.tmp
*.swp

# 依赖
node_modules/
.venv/
venv/

# 备份（大文件不版本控制）
backups/*
!backups/.keep

# 敏感信息
.env
*.key
*.pem
```



## 🛠️ 高级用法



### 自定义工作流

#### 创建个人工作流

```bash
# 在 scripts/ 下创建个人工作流
cat > scripts/my-workflow.sh << 'EOF'
#!/bin/bash
set -e
echo "🚀 我的工作流"
# 添加个性化操作
EOF
chmod +x scripts/my-workflow.sh
```



#### 配置定时备份

```bash
# 添加到 crontab -e：
# 每天凌晨2点运行备份
0 2 * * * cd /root/.openclaw/workspace && ./scripts/auto-backup.sh
```



### 协作开发准备



#### 分支策略

```
main/master          # 稳定版本分支
│
├── develop          # 主开发分支
│   ├── feature/chapter-19
│   ├── feature/chapter-20

│   └── fix/typo-fix

│
└── release/*        # 发布分支
```



#### 冲突解决流程

```bash
# 1. 获取最新代码
git fetch origin



# 2. 检查冲突
git merge origin/develop



# 3. 手动解决冲突
# 编辑冲突文件
# 标记已解决
git add <file>



# 4. 完成合并
git commit
git push origin develop
```



### 扩展集成



#### 集成现有项目

```bash
# 添加子模块
git submodule add <url> projects/小说工具



# 更新子模块
git submodule update --init --recursive
```



#### 自动化工作流

```bash
# 创建自动化钩子
mkdir -p .git/hooks
cat > .git/hooks/post-commit << 'EOF'
#!/bin/bash
echo "🎉 提交完成！"
echo "📊 分支: $(git branch --show-current)"
EOF
chmod +x .git/hooks/post-commit
```



## 🚨 紧急恢复



### 恢复丢失文件

```bash
# 1. 查看所有可恢复文件
git reflog



# 2. 恢复特定提交
git checkout <commit-hash> -- <file>



# 3. 恢复全部文件
git checkout <commit-hash> .
```



### 灾难恢复

```bash
# 从备份恢复
tar -xzf backups/backup-*.tar.gz -C /

# 或从远程克隆
git clone <remote-url> workspace
git submodule update --init --recursive
```



## 📊 最佳实践



### 1. 提交策略

- **小型提交**：每次提交只做一件事
- **描述清晰**：提交信息有明确类型和描述
- **及时推送**：每天至少推送一次
- **保持整洁**：定时清理分支



### 2. 备份策略

- **每日本地备份**
- **定期远程备份**
- **增量备份支持**
- **多版本存档**



### 3. 工作区管理

- **规范文件命名**
- 清晰目录结构
- 定期清理无用文件
- 保持依赖更新



## 🤖 自动化配置



### 设置定时任务

```bash
# 安装系统定时任务
sudo cat > /etc/cron.d/tomato-backup << 'EOF'
# 每天凌晨3点运行自动备份
0 3 * * * root cd /root/.openclaw/workspace && ./scripts/auto-backup.sh
EOF
```



### 环境配置

```bash
# 设置环境变量
cat > ~/.bashrc-tomato << 'EOF'
export WORKSPACE_DIR="/root/.openclaw/workspace"
export PATH="$WORKSPACE_DIR/scripts:$PATH"
EOF
echo "source ~/.bashrc-tomato" >> ~/.bashrc
```



## 🧪 故障排除



### 常见问题

#### 1. 提交失败

```bash
# 检查Git配置
git config --list



# 检查远程连接
git remote -v
git ls-remote origin
```



#### 2. 拉取冲突

```bash
# 暂存当前工作
git stash



# 拉取更新
git pull origin develop



# 恢复暂存工作
git stash pop
```



#### 3. 文件误删

```bash
# 查看所有可恢复文件
git reflog



# 恢复特定文件
git checkout <commit-hash> -- <file>
```

> **提示**：定期运行 `git fsck --lost-found` 可找回丢失的对象。





## 🎯 总结



### 核心价值

1. **版本安全**: 每次修改都有备份
2. **协作就绪**: 随时支持多人协作
3. **灾难恢复**: 数据丢失风险最小化



### 开始创作

```bash
# 开始新章节
./scripts/git-novel-workflow.sh start chapter-19



# 创作过程中保存进度
./scripts/git-novel-workflow.sh save 19



# 完成章节
./scripts/git-novel-workflow.sh finish 19
```



## 🔗 相关文档



### 主要参考

| 文档 | 描述 |
|------|------|
| [AGENTS.md](./AGENTS.md) | 工作区核心配置文件 |
| [GIT_WORKFLOW.md](./GIT_WORKFLOW.md) | Git 工作流详情 |
| [TOOLS.md](./TOOLS.md) | 本地工具配置 |
| [MEMORY.md](./MEMORY.md) | 长期记忆文件 |
| [HEARTBEAT.md](./HEARTBEAT.md) | 心跳检查配置 |



### 扩展阅读

- [Gitea 私有 Git 服务器配置](./docs/gitea-setup.md)
- [自动化部署流水线](./docs/deployment-pipeline.md)
- [多人协作最佳实践](./docs/collaboration-guide.md)



---

**最后更新**: $(date '+%Y-%m-%d %H:%M:%S')

**版本**: 1.0.0

**作者**: 番茄小说创作助手

> 🚀 开始创作！