---
title: 工作区版本管理
navTitle: 工作区版本管理
---
# 工作区版本管理

工作区版本管理指用 Git 管理 SuccApp 工作区中的项目目录、目录级 `.meta`、脚本、资源文件和团队共享配置。SuccApp 负责把 SuccApp 服务器上的元数据同步到本地工作区，Git 负责记录这些本地文件的修改历史。

正式项目中，建议将工作区纳入 Git 管理。这样 AI 或人工修改元数据后，团队可以审查差异、追踪变更、回退历史版本，并把测试通过的内容沉淀为可发布版本。本文只说明 SuccApp 工作区和 Git 配合时需要注意的内容，不介绍通用 Git 分支模型或提交规范。

## 为什么要使用 Git{#why}

使用 Git 管理工作区可以解决以下问题：

1. 知道每次 AI 或人工修改了哪些元数据文件。
2. 通过 Git diff 和 SuccApp diff 双重检查，降低误改无关文件的风险。
3. 发布生产前可以确认版本范围。
4. 出现问题时可以从历史提交中恢复文件，再通过 SuccApp 同步回测试或生产环境。

SuccApp 的 Changes 视图关注“本地和服务器之间的同步差异”，Git 关注“团队代码库中的历史版本”。这两者不是一回事，正式项目中应同时使用。

## 推荐入库内容{#include}

建议提交到 Git 的内容包括：

| 内容 | 说明 |
| :--- | :--- |
| 项目目录 | 从 SuccApp 服务器克隆下来的元数据项目，例如 `sales-ops/` |
| 目录级 `.meta` 文件 | 记录目录直接子资源的服务器资源标识、版本和描述，是同步所需信息 |
| 脚本和资源文件 | 页面脚本、数据加工脚本、图片、模板等项目真实资源 |
| 团队共享配置 | 团队约定需要共享的 VS Code 设置、TypeScript 配置、AI 规则和项目说明 |
| 文档和说明 | 项目交付说明、变更说明、发布记录 |

目录级 `.meta` 文件不要随意排除。缺少相关 `.meta` 时，SuccApp 很难准确判断本地文件对应的服务器资源。

## 不应入库内容{#exclude}

以下内容通常不应提交到 Git：

| 内容 | 原因 |
| :--- | :--- |
| `.succapp/remote/` | 本地服务器基线副本，体积可能较大，且属于运行时数据 |
| `.succapp/cache/` | 本地缓存 |
| `.succapp/locks/` | 同步锁文件 |
| `.succapp/merge-base/` | 拉取和合并前保存的服务器基线副本 |
| `.succapp/merge-backup/` | 拉取和合并前保存的本地文件备份 |
| `.succapp/*.log` | 本地日志 |
| `.succapp/state.json` | 本地同步状态文件，只对当前机器有意义 |
| `.agents/plans/`、`.agents/reviews/`、`.agents/reports/`、`.agents/tmp/` | AI 计划、评审、报告、临时脚本和草稿默认作为未确认产物处理 |
| `.DS_Store`、`Thumbs.db` | 操作系统临时文件 |
| 个人临时文件 | 与项目交付无关 |

初始化工作区后，SuccApp 会帮助写入部分 `.gitignore` 规则。团队仍应根据项目实际情况检查和补充，特别是确认 `.succapp/remote/`、`.succapp/cache/`、`.succapp/locks/`、`.succapp/merge-base/`、`.succapp/merge-backup/` 没有进入 Git 提交。

AI 协作产物建议统一放在 `.agents/` 下。`.agents/plans/`、`.agents/reviews/`、`.agents/reports/` 和 `.agents/tmp/` 默认忽略其中的文件；需要长期保留的计划、评审或报告，应由团队确认后再调整忽略规则或移动到约定位置。

## 提交前检查{#before-commit}

提交 Git 前，先确认工作区内容和服务器状态：

1. 从 Git 拉取最新代码。
2. 通过 SuccApp 刷新变化，确认是否有远端变化或冲突。
3. 需要接受服务器变化时，先执行拉取，再继续修改。
4. 完成本地修改后，同时查看 SuccApp diff 和 Git diff。
5. 推送测试服务器并完成产品界面验证。
6. 再次检查 Git 状态，确认提交范围。

提交前应确认 Git 状态中没有 `.succapp/remote/`、`.succapp/cache/`、`.succapp/locks/`、`.succapp/merge-base/`、`.succapp/merge-backup/`、日志等运行时文件。目录级 `.meta` 如果跟随资源新增、移动、重命名或删除发生变化，应和对应资源一起检查，不要简单丢弃。

## 评审建议{#review}

评审时建议同时查看 Git diff 和 SuccApp 差异。

重点检查：

1. 是否只修改了需求相关文件。
2. 是否存在无关格式化。
3. 是否误删目录级 `.meta` 或资源文件。
4. 是否修改了权限、数据范围、流程等敏感配置。
5. 是否已经在测试环境验证。
6. 是否有生产发布说明和回退方案。

## 回退方式{#rollback}

如果修改尚未推送到服务器，可以通过 Git 回退本地文件，再刷新 SuccApp 同步状态。

如果修改已经推送到测试服务器，可以回退 Git 后再通过 SuccApp 推送回测试服务器。

如果修改已经发布到生产环境，应按项目发布流程回退，不要在不了解影响的情况下直接强制推送旧文件。

## Git 与 SuccApp 的关系{#relationship}

Git 和 SuccApp 各自负责不同问题：

| 工具 | 负责什么 |
| :--- | :--- |
| SuccApp | 连接服务器、克隆项目、查看同步差异、拉取、推送、文件历史 |
| Git | 团队版本历史、分支、提交、评审、回退 |

团队协作时，建议同时遵守 Git 流程和 SuccApp 同步流程。只使用其中一个，都可能留下协作风险。