一次写入、四个落点：让跨项目同步脚本杜绝「幽灵 ✅」——舞台工艺审图交付物同步的幂等 + 回读校验 + 备份回滚实战

一次写入、四个落点：让跨项目同步脚本杜绝「幽灵 ✅」——舞台工艺审图交付物同步的幂等 + 回读校验 + 备份回滚实战

上一篇讲的是读图步骤记录怎么从空骨架回填成带证据、带四勾的完整记录，本篇换一个更靠下游的问题：记录回填好了，交付物要怎么同步到四个落点，中途失败时怎么保证「脚本报成功就一定真的落盘」。两者同属舞台工艺审图流水线的交付链，上一篇管「内容对不对」，本篇管「落点真不真」。

一、背景：脚本说 34/34 成功，盘上只有 33 份

先把这个坑讲透，否则后面所有「回读校验」的动作都像过度设计。

舞台工艺审图交付物不是停在一个目录里就完事的。一份交付物一旦定稿，要同步落到四个项目子树：

• 交付物主树：团队约定的权威交付位置，所有下游环节只从这里取件。
• 审图输出树：审图环节的工作副本，按项目分目录摆放。
• 历史版本归档树：旧版留档，按日期或版本号归档，防止新版覆盖旧版后找不回。
• IMA 知识库：跨项目的可检索知识沉淀位，把交付物索引进知识库，方便后续项目复用与回溯。

四个落点，缺一不可。交付物只落锁定项目子树，scratch 目录（临时工作区，按纪律用完即清）里躺着任何一份交付物副本都是事故——这是团队的硬规矩，不是建议。

问题出在「同步」这个动作上。早期的做法很朴素：一个 shell 循环，把源文件 cp 到四个目标路径，循环结束打印一句「同步完成」，退出码 0。看起来没毛病——脚本跑完了，没抛异常，没报非零退出码，按约定就是成功。

真实事故发生在一批 34 份读图步骤记录的同步上。那批记录由 AI 智能体批量回填完成，要同步进四个项目子树。脚本跑完，终端打出一行：

同步完成：34 份

退出码 0，一切岁月静好。直到第二天人工抽检，打开归档树数了一遍——只有 33 份。脚本报了 34/34 成功，盘上实际只有 33 份，缺的那一份去哪了？

这就是「幽灵 ✅」：脚本报成功，但产物并没有真实落盘。那个对勾是脚本自己打的，不是数据打出来的。

事后定位，缺的那一份是归档树里的读图步骤记录，文件存在、名字正确，但内容被截断——写到一半断了，剩下半份躺在盘上，文件能打开、字节数不算离谱，所有表观特征都在替它打掩护。34 份里出错 1 份，幽灵率约 3%。

3% 这个数字看着不大，放在 34 份里是 1 份，放在 340 份里就是 3 份，放在整条交付链上是一批交付物里混进几件残次品，而且你根本不知道是哪几件。更麻烦的是下游：审图输出树拿到的是完整版，归档树拿到的是截断版，IMA 知识库索引到的可能是半份——四个落点之间出现了内容漂移，而脚本对此一无所知，还报了个全绿。

根因不在「cp 失败」，在「成功的定义」。cp 成功只说明这个系统调用返回了，不说明目标文件完整写入、不说明四个落点都写到位、不说明写入的内容和源文件一致。中间任何一环出问题——磁盘满、路径长度超限、进程被 OOM kill、目标目录临时被挂成只读、写入到一半断电——cp 都可能留下半份文件然后报成功。

一句话定调：跨项目同步的放行依据，不能是「脚本没崩」，必须是「四个落点都真实存在且内容一致」。后者的判据只有一条路——写入后立刻回读校验。

二、环境准备与设计原则

2.1 环境与前置依赖

• 机器：Windows 分析机，Python 3.10 及以上，纯标准库（pathlib、hashlib、shutil、os、json），不依赖任何第三方库。同步闸门本身不能有依赖，依赖越多，闸门自身出错的面越大。
• 目录纪律：四个落点目录结构固定、路径由配置表传入，脚本内不写死绝对路径；scratch 目录与四个落点物理隔离，同步脚本只写锁定项目子树，scratch 只读不写。
• 权限：四个落点目录对同步脚本可写，对其他进程按项目实际权限收紧；备份目录单独一份，与归档树分开存放，防止「备份和归档一起丢」。
• 交付物形态：本篇以读图步骤记录（.md 文本）为样本，但这套闸门对任意文本/二进制交付物通用——判据是字节级比对，不关心文件类型。

2.2 四个设计原则

同步闸门的设计归结为四条原则，每一条都对应一个真实事故：

这四条里最容易漏的是第二条的「不抽查」。34 份同步抽 5 份回读，抽到的概率是 14.7%，抽不到是常态；幽灵 ✅ 之所以能活到第二天，正是因为「看起来都写了」。批量场景的放行权必须交给全量回读，不能交给抽样。

2.3 幂等：写前先清目标

「幂等」（同一个操作执行一次和执行多次结果相同）是同步闸门的第一道纪律。具体动作是：写入前先把目标落点清理到干净状态——目标目录里属于本批次的旧文件先移除（有备份后），再写入新版本。

为什么必须清？两种失败形态都指向它：

• 残留旧版冒充新版：目标路径已存在一份同名旧文件，写入进程在写新文件时被中断，新文件没写完、旧文件已被覆盖或删除，盘上留下半新半旧的混合态——回读时看到文件在、名字对，实际内容既不完整也不对版。
• 重跑污染：同步中途失败后重跑，不清目标的话，上一次的半成品还在盘上，这一次的写入与残留物叠加，归因彻底失真——你不知道这份文件是哪一轮留下的。

清目标的实现不是 rm -rf 整个目录，而是只清本批次管理的旧文件（按清单逐一删除目标路径下的同名文件），其他文件一律不动。动作序列是：备份旧版 → 删除目标同名文件 → 原子写入新版本。三步里任何一步失败，都不留下无法归因的混合态。

2.4 备份与回滚

备份动作的粒度是「每份交付物、每个落点」：写入前，把该落点路径上的旧版文件复制到备份目录（按 交付物名/落点名/时间戳 组织），同步失败或回读校验不过时，从备份原样恢复。

回滚的触发条件必须写死：任一落点回读校验不过，立即回滚该份交付物的全部落点（恢复到写入前状态），并整份标 REJECT，绝不留下「三个落点是新的、一个落点是旧的」的分裂态。

备份本身也要有纪律：备份目录单独存放、不与归档树同盘；备份文件写入后同样做一次存在性回读（复制动作也报成功也可能没落盘——备份也要防幽灵 ✅）。

三、代码实现：一次写入 + 回读校验 + 备份回滚

代码拆成三个模块：sync_core.py（单份交付物的四落点写入与回读校验）、sync_batch.py（批量入口与报告）、sync_config.py（落点配置表）。命名延续团队既有约定——_core 是纯函数模块不碰命令行参数、_batch 是可执行入口。

3.1 配置表：四个落点路径锁死

落点路径不写死在代码里，全部走配置表。原因是四个落点目录会随项目变动，写死路径等于把事故写进代码——哪天目录调整，旧路径还在、新路径没人写，幽灵 ✅ 照样报全绿。

# sync_config.py —— 四个落点配置表
from pathlib import Path

PROJECT = Path(r"D:\\某剧院审图项目")

DELIVERABLE_TREE = PROJECT / "04_交付物主树" # 交付物只落锁定项目子树
AUDIT_OUTPUT_TREE = PROJECT / "05_审图输出"
ARCHIVE_TREE = PROJECT / "06_历史版本归档"
IMA_TREE = PROJECT / "07_IMA知识库"

# scratch 目录＝事故区，同步脚本绝不写这里
SCRATCH = PROJECT / "00_scratch" # 只读不写，按纪律用完即清

# 备份目录单独存放，不与归档树同盘
BACKUP_ROOT = PROJECT / "08_备份" / "sync_backup"

TARGETS = {
"主树": DELIVERABLE_TREE,
"审图输出": AUDIT_OUTPUT_TREE,
"归档": ARCHIVE_TREE,
"IMA知识库": IMA_TREE,
}

四个落点的名称就是校验报告里的身份标识——报告里写「主树 PASS、审图输出 PASS、归档 REJECT、IMA知识库 PASS」，一眼能看出哪个落点挂了，不用对照路径猜。

3.2 回读校验核心：md5 + 字节数双判据

回读校验是整套闸门的灵魂。写入完成后，脚本逐落点打开目标文件，做两件事：

两个判据都过才算该落点 PASS。为什么两个都要——只看字节数，碰上「写了一半但恰好长度对上」的极端形态会漏（虽然罕见但存在）；只看 md5，碰上大文件全量哈希的耗时不划算。双判据互为兜底，成本可控、漏检面最小。

md5 计算用 hashlib.md5 流式读取，大文件不整读入内存：

# sync_core.py —— 回读校验核心
import hashlib
import os
import shutil
from dataclasses import dataclass, field
from pathlib import Path

def md5_of(path: Path, chunk: int = 1 << 20) –> str:
"""流式计算 md5，大文件不整读入内存。"""
h = hashlib.md5()
with open(path, "rb") as fh:
while True:
block = fh.read(chunk)
if not block:
break
h.update(block)
return h.hexdigest()

@dataclass
class PointVerdict:
name: str # 落点名称（主树 / 审图输出 / 归档 / IMA知识库）
path: str # 落点路径
exists: bool = False # 回读时文件是否存在
size: int = 0 # 回读字节数
md5: str = "" # 回读 md5
ok: bool = False # 该落点是否 PASS
reason: str = "" # 不过的理由

@dataclass
class FileSyncReport:
source: str # 源文件路径
source_size: int = 0
source_md5: str = ""
points: list = field(default_factory=list) # List[PointVerdict]
rolled_back: bool = False # 是否触发了回滚

@property
def all_ok(self) –> bool:
return len(self.points) == 4 and all(p.ok for p in self.points)

def verify_point(name: str, target: Path, src_size: int, src_md5: str) –> PointVerdict:
"""逐落点回读：存在性 + 字节数 + md5 三查。"""
pv = PointVerdict(name=name, path=str(target))
if not target.is_file():
pv.reason = "回读：文件不存在"
return pv
pv.exists = True
pv.size = target.stat().st_size
pv.md5 = md5_of(target)
if pv.size != src_size:
pv.reason = f"字节数不符：{pv.size} != {src_size}"
return pv
if pv.md5 != src_md5:
pv.reason = "md5 不符（内容漂移）"
return pv
pv.ok = True
pv.reason = "回读一致"
return pv

注意 verify_point 只做回读，不做任何写入。写入和回读分离是刻意设计：回读函数不碰写入路径，就不存在「刚写完就认为成功」的自证循环——写入动作本身也可能静默失败（磁盘满、路径超限），只有独立回读能把它抓出来。

3.3 一次写入：备份 → 清目标 → 原子写 → 回读

单份交付物的四落点写入按固定序列执行：

# sync_core.py —— 单份交付物四落点写入与回读（续）
import json
import time
from datetime import datetime
from pathlib import Path
from sync_config import TARGETS, BACKUP_ROOT

def backup_old(deliverable_name: str, point_name: str, target: Path) –> str | None:
"""写入前备份旧版；无旧版返回 None。"""
if not target.is_file():
return None
ts = datetime.now().strftime("%Y%m%d_%H%M%S")
bdir = BACKUP_ROOT / deliverable_name / point_name / ts
bdir.mkdir(parents=True, exist_ok=True)
bak = bdir / target.name
shutil.copy2(target, bak)
# 备份也要回读——复制也报成功也可能没落盘
if not bak.is_file() or md5_of(bak) != md5_of(target):
raise RuntimeError(f"备份失败且无法回读：{bak}")
return str(bak)

def atomic_write(target: Path, src: Path):
"""写 .tmp 再原子替换，中断不留残文件。"""
target.parent.mkdir(parents=True, exist_ok=True)
tmp = target.with_suffix(target.suffix + ".tmp")
shutil.copy2(src, tmp)
os.replace(tmp, target)

def sync_one(src: Path) –> FileSyncReport:
"""单份交付物：一次写入、四个落点、回读校验、失败回滚。"""
rep = FileSyncReport(source=str(src))
src_data = src.read_bytes()
rep.source_size = len(src_data)
rep.source_md5 = hashlib.md5(src_data).hexdigest()

# 步骤 2+3+4：逐落点 backup → 清旧 → 原子写
backups = {} # {point_name: backup_path}
for pname, target_dir in TARGETS.items():
target = target_dir / src.name
bpath = backup_old(src.stem, pname, target)
if bpath:
backups[pname] = (target, bpath)
if target.is_file():
target.unlink() # 幂等：先清旧版
atomic_write(target, src) # 原子写入

# 步骤 5：逐落点回读校验
for pname, target_dir in TARGETS.items():
target = target_dir / src.name
pv = verify_point(pname, target, rep.source_size, rep.source_md5)
rep.points.append(pv)

# 步骤 6：任一不过 → 回滚全部落点
if not rep.all_ok:
for pname, (target, bpath) in backups.items():
if bpath:
shutil.copy2(Path(bpath), target)
elif target.is_file():
target.unlink() # 旧版本就没有，清掉半成品
rep.rolled_back = True
return rep

atomic_write 用 shutil.copy2（保留时间戳与元数据）写 .tmp 再 os.replace——这是 Windows 上的原子替换语义，中断时 .tmp 残留、目标文件要么完整、要么不存在，不会留半份。

回滚动作里有个细节：旧版本就没有的落点，回滚时直接删掉新写入的半成品，不留「旧的没有、新的半份」的分裂态。分裂态比空更危险——空一眼能看出来，半份要等回读才能抓到。

3.4 批量入口与校验报告

批量入口遍历源目录，逐份 sync_one，收集全部报告，生成批次校验报告落地：

# sync_batch.py —— 批量入口与报告
import argparse
import json
from datetime import datetime
from pathlib import Path
from sync_core import sync_one
from sync_config import PROJECT, TARGETS

def render_batch_report(reports: list) –> str:
"""批次校验报告：每份交付物一行，四落点明细 + 判定。"""
lines = []
lines.append(f"批次校验报告 ｜ 生成时间 {datetime.now():%Y–%m–%d %H:%M:%S}")
lines.append(f"落点数：{len(TARGETS)} ｜ 交付物份数：{len(reports)}")
lines.append("─" * 72)
ok_cnt = 0
for rep in reports:
verdict = "PASS" if rep.all_ok else "REJECT"
if rep.all_ok:
ok_cnt += 1
lines.append(f"[{verdict}] {Path(rep.source).name}")
for pv in rep.points:
flag = "✅" if pv.ok else "❌"
lines.append(
f" {flag} {pv.name}｜字节 {pv.size}｜md5 {pv.md5[:12]}｜{pv.reason}"
)
if rep.rolled_back:
lines.append(" ⟲ 已回滚至写入前状态")
lines.append("")
lines.append("─" * 72)
lines.append(f"批次判定：{ok_cnt}/{len(reports)} PASS")
lines.append(f"幽灵率：{(len(reports) – ok_cnt)}/{len(reports)} 被回读校验拦截")
return "\\n".join(lines)

def main() –> int:
ap = argparse.ArgumentParser(description="跨项目交付物四落点同步闸门")
ap.add_argument("–src", type=Path, required=True, help="源交付物目录")
ap.add_argument("–report", type=Path, default=None,
help="校验报告输出路径（默认落交付物主树下）")
args = ap.parse_args()

reports = []
for src in sorted(args.src.glob("*.md")):
rep = sync_one(src)
reports.append(rep)

report_text = render_batch_report(reports)
report_path = args.report or (PROJECT / "04_交付物主树" / "_sync_report.txt")
report_path.write_text(report_text, encoding="utf-8")
print(report_text)

# 整批任一 REJECT → 退出码 1，下游 CI 可直接采信
return 0 if all(r.all_ok for r in reports) else 1

if __name__ == "__main__":
raise SystemExit(main())

跑一遍的实际输出长这样（文件名为通用占位）：

批次校验报告 ｜ 生成时间 2026-11-01 14:22:03
落点数：4 ｜ 交付物份数：34
────────────────────────────────────────────────────────────────────────────
[PASS] 读图步骤记录_01.md
✅ 主树｜字节 18234｜md5 9f3c…｜回读一致
✅ 审图输出｜字节 18234｜md5 9f3c…｜回读一致
✅ 归档｜字节 18234｜md5 9f3c…｜回读一致
✅ IMA知识库｜字节 18234｜md5 9f3c…｜回读一致
[REJECT] 读图步骤记录_07.md
✅ 主树｜字节 18234｜md5 9f3c…｜回读一致
✅ 审图输出｜字节 18234｜md5 9f3c…｜回读一致
❌ 归档｜字节 14021｜md5 4a1b…｜字节数不符：14021 != 18234
✅ IMA知识库｜字节 18234｜md5 9f3c…｜回读一致
⟲ 已回滚至写入前状态
────────────────────────────────────────────────────────────────────────────
批次判定：33/34 PASS
幽灵率：1/34 被回读校验拦截

第 7 份交付物的归档落点，回读抓到字节数 14021 ≠ 18234——截断文件当场现形，脚本随即回滚、整份标 REJECT。如果只看「脚本没崩」，这份残次品会以「归档成功」的身份活到第二天人工抽检。

批量跑法：

python sync_batch.py –src "D:\\某剧院审图项目\\03_回填完成记录" –report "D:\\某剧院审图项目\\04_交付物主树\\_sync_report.txt"
echo "同步闸门 EXIT=$?"

退出码语义钉死：整批 34/34 PASS → 退出码 0；任一 REJECT → 退出码 1。下游 CI 与调度系统只看退出码，不看日志里那句「同步完成」——「同步完成」是脚本自己打的字，退出码是机器判的布尔值。

四、踩坑记录：七个现象与七条解法

下面每一条都是实测踩出来的，按「现象 → 成因 → 解法」记。

1. cp 报成功，盘上只有半份

• 现象：34 份读图步骤记录同步，脚本报 34/34 成功，归档树实际只有 33 份，缺的那份内容截断。
• 成因：cp/shutil.copy 成功只说明系统调用返回，不说明文件完整写入。写入中途磁盘满、进程被 OOM kill、目标目录临时只读，都会留下半份文件然后报成功。
• 解法：写入后逐落点回读校验（字节数 + md5 双判据），任一不过整份 REJECT 并回滚。成功的定义从「脚本没崩」改成「四个落点都真实存在且内容一致」。

2. 分头写导致归因失真

• 现象：早期同步靠多个脚本分次写——一个 cp 写主树、一个脚本写归档、IMA 知识库索引另开一路。某次归档失败，但主树脚本已跑完、报告里还留着一句「主树同步完成」，整体状态说不清。
• 成因：分头写的失败点散落在各脚本里，没有统一的异常处理与统一判定，出问题时不知道是哪一路、哪一步、哪个落点。
• 解法：四个落点收敛到一条写入路径（sync_one 统一入口），统一异常处理、统一回读判定、统一报告格式。一个失败不拖垮全局，但必须留痕在统一报告里。

3. 重跑污染：残留旧版冒充新版

• 现象：同步中途失败后直接重跑，目标路径上还躺着上一次的半成品，新一轮写入与残留物叠加，回读时看到文件在、名字对，实际内容半新半旧。
• 成因：写入前不清目标目录，重跑时旧残留与新写入叠加，归因彻底失真——不知道这份文件是哪一轮留下的。
• 解法：幂等纪律——写前先清目标（备份旧版后删除同名旧文件），再原子写入。三步序列：备份 → 清旧 → 原子写，任何一步失败都不留混合态。

4. 备份本身也报成功

• 现象：写了备份动作，但备份文件复制中途失败，脚本照报「已备份」，回滚时从备份恢复发现备份也是残的。
• 成因：复制动作和 cp 一样只报系统调用结果，不报落盘结果。备份若不带自己的回读，就是第二处幽灵 ✅。
• 解法：备份后立即回读校验（存在性 + md5），备份失败直接抛异常中断该份交付物——备份失效时宁可不写，也不能写了没有兜底的旧版。

5. 只抽一个落点回读，漏检

• 现象：回读校验只查交付物主树（最权威的那个落点），主树 PASS 即整份 PASS。结果归档树那份被截断，主树那份完整，脚本报全绿。
• 成因：误以为「主树对了其他就对」。实际四个落点独立写入、独立可能失败，主树完整不代表归档树完整——34 份同步里出问题的恰恰是归档树那一份。
• 解法：回读覆盖全部四个落点，不抽查、不找代表。批量场景的放行权交给全量回读，抽样在批量面前既不可扩展也不可信。

6. 退出码 0 不等于同步成功

• 现象：脚本用 sys.exit(0) 收尾，哪怕中间有 REJECT 也退出 0，下游 CI 采信退出码、照常放行。
• 成因：退出码是脚本自己决定的，写错了没人拦——「同步完成」和退出码都是脚本打的字，不是数据判的布尔值。
• 解法：退出码语义钉死——整批全 PASS 退出 0，任一 REJECT 退出 1。退出码的判据来自回读校验结果（all(r.all_ok for r in reports)），不来自脚本自己的「完成」字样。

7. md5 与字节数只查一个会漏

• 现象：只查字节数，碰上「写了一半但恰好长度对上」的极端形态漏检；只查 md5，大文件全量哈希耗时不划算。
• 成因：单一判据有盲区。字节数对上但内容漂移、md5 对上但字节数巧合一致，都是理论上可能、工程上防不住的漏检面。
• 解法：双判据互为兜底——字节数比对（成本极低）+ md5 比对（防内容漂移），成本可控、漏检面最小。两者都过才算该落点 PASS。

五、实证结果：34 份同步，回读校验抓到 1 份截断

把这套闸门落回那批 34 份读图步骤记录的真实同步。

同步动作按四步执行：

结果：33/34 PASS，1/34 REJECT。REJECT 的那份，归档落点回读抓到字节数 14021 ≠ 18234，md5 不匹配——截断文件当场现形，脚本随即回滚全部落点、整份标 REJECT，退出码 1，下游 CI 拒收。

幽灵率约 3%（1/34）。这个数字的意义不在于大小，在于它被抓到了——在旧的 cp 方案下，这份残次品会以「归档成功」的身份混进交付链，直到第二天人工抽检才暴露；在新的回读闸门下，它在写入当场就被判 REJECT 并回滚，根本没有机会流入下游。

这套闸门对任意文本/二进制交付物通用。判据是字节级比对，不关心文件类型——换成 .docx、.json、.txt，同一套 sync_one 逻辑不用改。

六、总结：把「成功」定义在落点级

五条可迁移的结论。

**第一，跨项目同步的放行依据，不能是「脚本没崩」，必须是「四个落点都真实存在且内容一致」。**脚本报成功与产物真实落盘是两件事，中间隔着一整层回读校验。cp 成功只说明系统调用返回，不说明文件完整写入、不说明四个落点都写到位、不说明内容一致。成功的定义必须建在落点级。

**第二，一次写入、四个落点，缺一即整份 REJECT。**统一入口、统一异常处理、统一判定。分头写就是分头可能失败，失败点散落各处就无法归因。四个落点全过才算该份交付物 PASS，任一缺失/截断/漂移即报错，绝不让「幽灵 ✅」混入交付链。

**第三，幂等 + 备份 + 回滚三件套不可省。**幂等（写前先清目标）防止重跑污染与残留旧版冒充新版；备份（写前备份旧版）给失败留退路；回滚（任一落点不过即恢复写入前状态）保证不留分裂态。三者各管一层，缺一个就有一个失败形态接不住。

**第四，回读校验覆盖全部落点，不抽查。**批量场景的放行权必须交给全量回读。34 份同步抽 5 份回读，抽到幽灵的概率是 14.7%；全量回读是 100%。抽样在批量面前既不可扩展也不可信。

**第五，退出码语义钉死，报告落地。**整批全 PASS 退出 0、任一 REJECT 退出 1，判据来自回读校验结果，不来自脚本自己打的「完成」字样；校验报告随批次归档，供人工抽查与事后归因。这道闸门后来固化为审图 Skill（可复用的专家经验脚本包）里的常设动作——每批交付物同步，先过它，再谈下游。

也要说清这道闸门的边界：它管的是「落点缺失/截断/漂移」这一类失效，管不了「落点内容本身不对」——后者是上一篇回填闸门与更上游读图闸门的职责。交付链的防线从来不是一道闸门包打天下，而是每一类失效各有一道对位的闸门；本篇补上的正是「落点同步」这一类的空缺。

回到开头那个 34/34 的幽灵 ✅：脚本报了 34 份成功，盘上只有 33 份。回读校验抓到那 1 份截断、回滚、标 REJECT、退出码 1——幽灵在写入当场现形，没有机会混进交付链。这条坑的学费交完，同步才算真正能用：不是「跑完了」，而是「四个落点都拿到了」。