Git 上传规范
1. 一 · 上传流程总览一 · 上传流程总览
点击任意页面的 Git 上传 按钮，系统自动执行以下 六步安全流程（无需任何手动输入）：
- ① 本地备份 自动 · 第一步 在
archive/backups/auto/ 创建完整项目快照。这一步先于所有 Git 操作，确保即使后续步骤失败，代码也不会丢失。 - ② 文档日志 自动 · 第二步 自动追加一条会话记录到
session-log.json，记录上传时间和来源。无手动摘要时自动生成「Git 自动上传」标记。 - ③ git add -A 暂存所有变更文件。CRLF 行尾警告自动过滤，不影响上传。
- ④ git commit 提交变更，信息格式：
自动备份 YYYY-MM-DD HH:MM。无变更时跳过 push。 - ⑤ git push origin master 推送到 Gitee 远程仓库。首次推送自动设置 upstream。
- ⑥ 远程同步提醒 提醒 · 第六步 推送成功后，后端返回需同步的服务器列表和
git pull 命令。前端以青色高亮显示提醒。
已知服务器：192.168.1.98:8080（主）、192.168.1.3:8080（NAS备用）。变更为空时跳过此步。
技术链路
前端点击 → doGitPush() 自动生成时间戳消息 → runGitPush() 调用后端 API
→ 后端 POST /api/git/push → ① backup.create_backup() → ② 写入 session-log.json → ③ git add → ④ git commit → ⑤ git push → ⑥ 返回同步提醒
→ 返回 JSON：steps（六步每步输出+耗时） + sync_reminder（服务器/命令） + backup（备份路径/文件数） → 前端展示结果区别：小说站 vs 规范站的 Git 按钮
站点 后端服务 说明 小说站 · 剧本站 192.168.1.98:8080主服务器，处理 canvas 和 screenplay 的 git 上传 NAS 备用 192.168.1.3:8080备用静态服务，文件可能过时，不支持 API
一 · 上传流程总览
点击任意页面的 Git 上传 按钮，系统自动执行以下 六步安全流程（无需任何手动输入）：
- ① 本地备份 自动 · 第一步 在
archive/backups/auto/创建完整项目快照。这一步先于所有 Git 操作，确保即使后续步骤失败，代码也不会丢失。 - ② 文档日志 自动 · 第二步 自动追加一条会话记录到
session-log.json，记录上传时间和来源。无手动摘要时自动生成「Git 自动上传」标记。 - ③ git add -A 暂存所有变更文件。CRLF 行尾警告自动过滤，不影响上传。
- ④ git commit 提交变更，信息格式：
自动备份 YYYY-MM-DD HH:MM。无变更时跳过 push。 - ⑤ git push origin master 推送到 Gitee 远程仓库。首次推送自动设置 upstream。
- ⑥ 远程同步提醒 提醒 · 第六步 推送成功后，后端返回需同步的服务器列表和
git pull命令。前端以青色高亮显示提醒。
已知服务器：192.168.1.98:8080（主）、192.168.1.3:8080（NAS备用）。变更为空时跳过此步。
技术链路
前端点击 →
→ 后端
→ 返回 JSON：steps（六步每步输出+耗时） + sync_reminder（服务器/命令） + backup（备份路径/文件数） → 前端展示结果
doGitPush() 自动生成时间戳消息 → runGitPush() 调用后端 API→ 后端
POST /api/git/push → ① backup.create_backup() → ② 写入 session-log.json → ③ git add → ④ git commit → ⑤ git push → ⑥ 返回同步提醒→ 返回 JSON：steps（六步每步输出+耗时） + sync_reminder（服务器/命令） + backup（备份路径/文件数） → 前端展示结果
区别：小说站 vs 规范站的 Git 按钮
| 站点 | 后端服务 | 说明 |
|---|---|---|
| 小说站 · 剧本站 | 192.168.1.98:8080 | 主服务器，处理 canvas 和 screenplay 的 git 上传 |
| NAS 备用 | 192.168.1.3:8080 | 备用静态服务，文件可能过时，不支持 API |
2. 二 · 本地备份机制二 · 本地备份机制
备份触发时机
每次执行 Git push 之前，后端自动调用 backup.create_backup() 创建完整备份。无论 push 成功与否，备份都会先完成。这意味着即使 push 失败、冲突、超时，本地已有一份可随时回滚的副本。
备份内容
- 目录
canvas/ — 所有 HTML 页面、规范文档、章节文件 - 目录
screenplay/ — 剧本、分镜脚本 - 目录
content/ — 内容素材 - 目录
references/ — 参考资料 - 根文件
COLLABORATION.md AI_COLLABORATION.md ONBOARD_OP02.md README.md complete-bible.md market-strategy.md .gitignore
备份位置
# 备份根目录
archive/backups/auto/
# 命名格式
push-20260702_163000/ ← 每次 push 前生成
# 每个备份目录内包含完整的项目文件树备份保留策略
系统自动保留 最近 20 个备份，超出后自动删除最旧的。备份目录位于 .gitignore 中，不会被上传到 Git。
备份清单 (manifest)
每个备份目录内含 manifest.json，记录：
- name — 备份名称（时间戳）
- time — 创建时间（人类可读）
- backup_type — 类型标记（"Git Push 前自动备份 · YYYYMMDD_HHMMSS"）
- git — 当前 branch / last_commit / modified_files 信息
- dirs — 每个目录的文件数和大小
- total_files — 文件总数
- total_size — 总大小（字节）
二 · 本地备份机制
备份触发时机
每次执行 Git push 之前，后端自动调用 backup.create_backup() 创建完整备份。无论 push 成功与否，备份都会先完成。这意味着即使 push 失败、冲突、超时，本地已有一份可随时回滚的副本。
备份内容
- 目录
canvas/— 所有 HTML 页面、规范文档、章节文件 - 目录
screenplay/— 剧本、分镜脚本 - 目录
content/— 内容素材 - 目录
references/— 参考资料 - 根文件
COLLABORATION.mdAI_COLLABORATION.mdONBOARD_OP02.mdREADME.mdcomplete-bible.mdmarket-strategy.md.gitignore
备份位置
# 备份根目录
archive/backups/auto/
# 命名格式
push-20260702_163000/ ← 每次 push 前生成
# 每个备份目录内包含完整的项目文件树
archive/backups/auto/
# 命名格式
push-20260702_163000/ ← 每次 push 前生成
# 每个备份目录内包含完整的项目文件树
备份保留策略
系统自动保留 最近 20 个备份，超出后自动删除最旧的。备份目录位于 .gitignore 中，不会被上传到 Git。
备份清单 (manifest)
每个备份目录内含 manifest.json，记录：
- name — 备份名称（时间戳）
- time — 创建时间（人类可读）
- backup_type — 类型标记（"Git Push 前自动备份 · YYYYMMDD_HHMMSS"）
- git — 当前 branch / last_commit / modified_files 信息
- dirs — 每个目录的文件数和大小
- total_files — 文件总数
- total_size — 总大小（字节）
3. 三 · 回滚步骤三 · 回滚步骤
场景 1：Push 后发现有误，需要回滚到上传前的状态
# 1. 找到需要回滚的备份
ls archive/backups/auto/
# 2. 替换项目文件（以 push-20260702_163000 为例）
# 注意：这不会覆盖 .git 目录，只替换源文件
cp -r archive/backups/auto/push-20260702_163000/canvas/* canvas/
cp -r archive/backups/auto/push-20260702_163000/content/* content/
# … 以此类推
# 3. 确认回滚正确后，可以重新 push（会自动创建新备份）场景 2：仅回滚某个文件
# 从最近一次备份中恢复单个文件
cp archive/backups/auto/push-20260702_163000/canvas/index.html canvas/场景 3：使用 Git 回滚（不需要备份）
# 撤消最近一次 commit（保留文件变更）
git reset --soft HEAD~1
# 或撤消 commit 并丢弃所有变更（慎用！）
git reset --hard HEAD~1
# 强制覆盖远端（确认无误后执行）
git push --force origin master
三 · 回滚步骤
场景 1：Push 后发现有误，需要回滚到上传前的状态
# 1. 找到需要回滚的备份
ls archive/backups/auto/
# 2. 替换项目文件（以 push-20260702_163000 为例）
# 注意：这不会覆盖 .git 目录，只替换源文件
cp -r archive/backups/auto/push-20260702_163000/canvas/* canvas/
cp -r archive/backups/auto/push-20260702_163000/content/* content/
# … 以此类推
# 3. 确认回滚正确后，可以重新 push（会自动创建新备份）
ls archive/backups/auto/
# 2. 替换项目文件（以 push-20260702_163000 为例）
# 注意：这不会覆盖 .git 目录，只替换源文件
cp -r archive/backups/auto/push-20260702_163000/canvas/* canvas/
cp -r archive/backups/auto/push-20260702_163000/content/* content/
# … 以此类推
# 3. 确认回滚正确后，可以重新 push（会自动创建新备份）
场景 2：仅回滚某个文件
# 从最近一次备份中恢复单个文件
cp archive/backups/auto/push-20260702_163000/canvas/index.html canvas/
cp archive/backups/auto/push-20260702_163000/canvas/index.html canvas/
场景 3：使用 Git 回滚（不需要备份）
# 撤消最近一次 commit（保留文件变更）
git reset --soft HEAD~1
# 或撤消 commit 并丢弃所有变更（慎用！）
git reset --hard HEAD~1
# 强制覆盖远端（确认无误后执行）
git push --force origin master
git reset --soft HEAD~1
# 或撤消 commit 并丢弃所有变更（慎用！）
git reset --hard HEAD~1
# 强制覆盖远端（确认无误后执行）
git push --force origin master
4. 四 · 前端界面说明四 · 前端界面说明
一键上传流程
- 点击按钮按钮变灰显示"上传中…"，同时弹出六步上传模态框。
- 模态框自动启动显示 5 个步骤（①备份 → ②日志 → ③add → ④commit → ⑤push），每步有独立的状态图标和耗时显示。
- 结果展示上传完成后显示详细信息，包含每步输出、耗时和备份路径。
按钮状态
- 正常 "Git 上传" — 可点击
- 上传中 "上传中…" — 灰色禁用，禁止重复点击
- 失败 按钮恢复为 "Git 上传"，可重新点击
- 成功 页面自动刷新，按钮恢复
关闭/取消
上传过程中可点击"取消"关闭模态框，但已发起的 API 请求无法中断（由后端自动完成）。关闭后按钮恢复正常状态。
四 · 前端界面说明
一键上传流程
- 点击按钮按钮变灰显示"上传中…"，同时弹出六步上传模态框。
- 模态框自动启动显示 5 个步骤（①备份 → ②日志 → ③add → ④commit → ⑤push），每步有独立的状态图标和耗时显示。
- 结果展示上传完成后显示详细信息，包含每步输出、耗时和备份路径。
按钮状态
- 正常 "Git 上传" — 可点击
- 上传中 "上传中…" — 灰色禁用，禁止重复点击
- 失败 按钮恢复为 "Git 上传"，可重新点击
- 成功 页面自动刷新，按钮恢复
关闭/取消
上传过程中可点击"取消"关闭模态框，但已发起的 API 请求无法中断（由后端自动完成）。关闭后按钮恢复正常状态。
5. 五 · 常见错误速查五 · 常见错误速查
错误 1：连接失败 / 无法访问上传服务表现：点击 Git 上传后，模态框提示"连接失败"，进度条不动。原因：后端 Python 服务未运行。
解决：双击 scripts/server/start-server-hidden.vbs 后台启动服务器，然后重新点击上传。
地址：统一使用 192.168.1.98:8080（canvas 和 screenplay 均由此服务器提供）。错误 2：index.lock 文件残留表现：push 返回错误信息包含 index.lock 或 Unable to create '.git/index.lock'。原因：上一次 git 操作异常中断，锁文件未清理。
自动处理：后端在 git 命令超时时会自动清理所有 .git/*.lock 文件。
手动解决：删除项目根目录下的 .git/index.lock 文件。del .git\index.lock # Windows
rm .git/index.lock # Mac/Linux错误 3：CRLF 行尾警告表现：git add 输出包含 warning: CRLF will be replaced by LF。影响：无。后端自动过滤 CRLF 警告，不影响上传结果。
说明：Windows 使用 CRLF 行尾，Git 会自动转换为 LF。这是正常的跨平台行为。错误 4：Git 命令超时表现：上传卡住，最终返回"Git 命令超时（XX秒）"。可能原因：
1. pre-commit 钩子卡住 — 检查 .git/hooks/pre-commit 是否正常
2. 网络问题导致 push 超时 — 检查是否能 ping 通 Gitee
3. 文件太多/太大导致 git 操作耗时 — 检查是否误加了二进制文件
解决：超时后 index.lock 会自动清理，直接重试即可。错误 5：Push 被拒绝 (rejected)表现：push 步骤返回 rejected 或 non-fast-forward。原因：远程仓库有本地没有的提交（通常是因为其他设备推送过）。
解决：# 先拉取远程变更
git pull origin master
# 解决冲突后重新 push（页面一键上传即可）注意：如果 pull 时有冲突，先手动解决冲突文件，再重新上传。备份已在 push 前创建，可以放心操作。错误 6：nothing to commit表现：commit 步骤返回"无变更，跳过 push"。这不是错误。文件没有变更时，git commit 无事可做，push 自动跳过。备份仍然正常创建。
五 · 常见错误速查
错误 1：连接失败 / 无法访问上传服务
表现：点击 Git 上传后，模态框提示"连接失败"，进度条不动。
原因：后端 Python 服务未运行。
解决：双击
地址：统一使用 192.168.1.98:8080（canvas 和 screenplay 均由此服务器提供）。
解决：双击
scripts/server/start-server-hidden.vbs 后台启动服务器，然后重新点击上传。地址：统一使用 192.168.1.98:8080（canvas 和 screenplay 均由此服务器提供）。
错误 2：index.lock 文件残留
表现：push 返回错误信息包含
index.lock 或 Unable to create '.git/index.lock'。原因：上一次 git 操作异常中断，锁文件未清理。
自动处理：后端在 git 命令超时时会自动清理所有
手动解决：删除项目根目录下的
自动处理：后端在 git 命令超时时会自动清理所有
.git/*.lock 文件。手动解决：删除项目根目录下的
.git/index.lock 文件。del .git\index.lock # Windows
rm .git/index.lock # Mac/Linux
rm .git/index.lock # Mac/Linux
错误 3：CRLF 行尾警告
表现：git add 输出包含
warning: CRLF will be replaced by LF。影响：无。后端自动过滤 CRLF 警告，不影响上传结果。
说明：Windows 使用 CRLF 行尾，Git 会自动转换为 LF。这是正常的跨平台行为。
说明：Windows 使用 CRLF 行尾，Git 会自动转换为 LF。这是正常的跨平台行为。
错误 4：Git 命令超时
表现：上传卡住，最终返回"Git 命令超时（XX秒）"。
可能原因：
1. pre-commit 钩子卡住 — 检查
2. 网络问题导致 push 超时 — 检查是否能 ping 通 Gitee
3. 文件太多/太大导致 git 操作耗时 — 检查是否误加了二进制文件
解决：超时后
1. pre-commit 钩子卡住 — 检查
.git/hooks/pre-commit 是否正常2. 网络问题导致 push 超时 — 检查是否能 ping 通 Gitee
3. 文件太多/太大导致 git 操作耗时 — 检查是否误加了二进制文件
解决：超时后
index.lock 会自动清理，直接重试即可。错误 5：Push 被拒绝 (rejected)
表现：push 步骤返回
rejected 或 non-fast-forward。原因：远程仓库有本地没有的提交（通常是因为其他设备推送过）。
解决：
解决：
# 先拉取远程变更
git pull origin master
# 解决冲突后重新 push（页面一键上传即可）
注意：如果 pull 时有冲突，先手动解决冲突文件，再重新上传。备份已在 push 前创建，可以放心操作。git pull origin master
# 解决冲突后重新 push（页面一键上传即可）
错误 6：nothing to commit
表现：commit 步骤返回"无变更，跳过 push"。
这不是错误。文件没有变更时，git commit 无事可做，push 自动跳过。备份仍然正常创建。
6. 六 · 安全注意事项六 · 安全注意事项
- 不要 在上传过程中关闭终端窗口 — 会导致 index.lock 残留
- 不要 在上传过程中手动执行 git 命令 — 会产生锁冲突
- 不要 手动删除
archive/backups/auto/ 中的备份 — 那是回滚的安全网 - 建议 每次重要修改后立即上传，保持备份密度
- 建议 每周检查一次备份目录，确保备份正常运行
- 注意 备份文件在
.gitignore 中，不会被上传到远程仓库
六 · 安全注意事项
- 不要 在上传过程中关闭终端窗口 — 会导致 index.lock 残留
- 不要 在上传过程中手动执行 git 命令 — 会产生锁冲突
- 不要 手动删除
archive/backups/auto/中的备份 — 那是回滚的安全网 - 建议 每次重要修改后立即上传，保持备份密度
- 建议 每周检查一次备份目录，确保备份正常运行
- 注意 备份文件在
.gitignore中，不会被上传到远程仓库