hermes-skills/skills/legal/contract-editor/references/version-management-antipatterns.md

版本管理反模式（2026-07-01 反委托代发工资协议惨痛教训）

事件回顾

反委托代发工资协议需要制作两个版本（法定安排 vs 反委托保护），同时保留华诚-Z的修订痕迹。

灾难链条

1. 原始文件有华诚-Z的修订（author="华诚-Z"）+ 批注
2. 我制作WB版本时，把所有author改成了WB
3. 又做了一版合并版本，再次覆盖
4. 之后Doro说"你把华诚-Z修订痕迹的版本放进去"
5. 发现/tmp里所有文件都只有WB作为author
6. Nextcloud版本历史也没有（只保留了一个.v文件，也是WB）
7. 最终在 /tmp/v1_doro_updated.docx 找到——这是一个中间版本，纯属侥幸

反模式清单

反模式	后果
修改author前不备份	原始修订痕迹不可逆丢失
覆盖式保存（同文件名）	中间版本消失
从头重做而非增量修补	每次重做都覆盖上一版
不验证就交付	批注丢了3条没发现
多轮操作共用/tmp目录	后续操作的文件名与前面冲突

正确做法

import shutil
from datetime import datetime

# 操作前备份
timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
shutil.copy(source, f"{source}.bak_{timestamp}")

# 操作后验证
import zipfile, re
z = zipfile.ZipFile(output)
content = z.read('word/document.xml').decode('utf-8')
authors = set(re.findall(r'w:author="([^"]+)"', content))
assert '华诚-Z' in authors, "华诚-Z author LOST!"

# 批注验证
if 'word/comments.xml' in z.namelist():
    comments_xml = z.read('word/comments.xml').decode('utf-8')
    comment_count = len(re.findall(r'<w:comment ', comments_xml))
    assert comment_count >= expected_count, f"Comments lost: {comment_count} < {expected_count}"

文件命名规范（防覆盖）

不要用 _v2.docx _v3.docx 这种递增命名——容易忘记当前版本是几。用语义+时间戳：

反委托_华诚Z原版_20260701_0320.docx    # 带华诚-Z修订的版本
反委托_WB合并版_20260701_0341.docx     # WB+华诚-Z合并后
反委托_V1法定安排_FINAL_20260701.docx   # 最终交付