主题
工作区版本管理
工作区版本管理指用 Git 管理 SuccApp 工作区中的项目目录、目录级 .meta、脚本、资源文件和团队共享配置。SuccApp 负责把 SuccApp 服务器上的元数据同步到本地工作区，Git 负责记录这些本地文件的修改历史。
正式项目中，建议将工作区纳入 Git 管理。这样 AI 或人工修改元数据后，团队可以审查差异、追踪变更、回退历史版本，并把测试通过的内容沉淀为可发布版本。本文只说明 SuccApp 工作区和 Git 配合时需要注意的内容，不介绍通用 Git 分支模型或提交规范。
为什么要使用 Git
使用 Git 管理工作区可以解决以下问题：
- 知道每次 AI 或人工修改了哪些元数据文件。
- 通过 Git diff 和 SuccApp diff 双重检查，降低误改无关文件的风险。
- 发布生产前可以确认版本范围。
- 出现问题时可以从历史提交中恢复文件，再通过 SuccApp 同步回测试或生产环境。
SuccApp 的 Changes 视图关注“本地和服务器之间的同步差异”，Git 关注“团队代码库中的历史版本”。这两者不是一回事，正式项目中应同时使用。
推荐入库内容
建议提交到 Git 的内容包括：
| 内容 | 说明 |
|---|---|
| 项目目录 | 从 SuccApp 服务器克隆下来的元数据项目，例如 sales-ops/ |
目录级 .meta 文件 | 记录目录直接子资源的服务器资源标识、版本和描述，是同步所需信息 |
| 脚本和资源文件 | 页面脚本、数据加工脚本、图片、模板等项目真实资源 |
| 团队共享配置 | 团队约定需要共享的 VS Code 设置、TypeScript 配置、AI 规则和项目说明 |
| 文档和说明 | 项目交付说明、变更说明、发布记录 |
目录级 .meta 文件不要随意排除。缺少相关 .meta 时，SuccApp 很难准确判断本地文件对应的服务器资源。
不应入库内容
以下内容通常不应提交到 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/ 默认忽略其中的文件；需要长期保留的计划、评审或报告，应由团队确认后再调整忽略规则或移动到约定位置。
提交前检查
提交 Git 前，先确认工作区内容和服务器状态：
- 从 Git 拉取最新代码。
- 通过 SuccApp 刷新变化，确认是否有远端变化或冲突。
- 需要接受服务器变化时，先执行拉取，再继续修改。
- 完成本地修改后，同时查看 SuccApp diff 和 Git diff。
- 推送测试服务器并完成产品界面验证。
- 再次检查 Git 状态，确认提交范围。
提交前应确认 Git 状态中没有 .succapp/remote/、.succapp/cache/、.succapp/locks/、.succapp/merge-base/、.succapp/merge-backup/、日志等运行时文件。目录级 .meta 如果跟随资源新增、移动、重命名或删除发生变化，应和对应资源一起检查，不要简单丢弃。
评审建议
评审时建议同时查看 Git diff 和 SuccApp 差异。
重点检查：
- 是否只修改了需求相关文件。
- 是否存在无关格式化。
- 是否误删目录级
.meta或资源文件。 - 是否修改了权限、数据范围、流程等敏感配置。
- 是否已经在测试环境验证。
- 是否有生产发布说明和回退方案。
回退方式
如果修改尚未推送到服务器，可以通过 Git 回退本地文件，再刷新 SuccApp 同步状态。
如果修改已经推送到测试服务器，可以回退 Git 后再通过 SuccApp 推送回测试服务器。
如果修改已经发布到生产环境，应按项目发布流程回退，不要在不了解影响的情况下直接强制推送旧文件。
Git 与 SuccApp 的关系
Git 和 SuccApp 各自负责不同问题：
| 工具 | 负责什么 |
|---|---|
| SuccApp | 连接服务器、克隆项目、查看同步差异、拉取、推送、文件历史 |
| Git | 团队版本历史、分支、提交、评审、回退 |
团队协作时，建议同时遵守 Git 流程和 SuccApp 同步流程。只使用其中一个，都可能留下协作风险。
