Function _atomic_write_text

scripts/k.py:27–79

write-then-rename 原子写：先写到同目录的临时文件再 os.replace 重命名。 保证别的进程读 target 时只能看到完整旧内容或完整新内容，不会读到半截。 Windows 兼容：当目标文件被另一进程持 read handle（如 web server 正在 readFile） 时，os.replace 会抛 PermissionError [WinError 5]。重试 3 次（50ms 间隔）。 最终失败时**保留临时文件**让用户可手动 mv 收拾，而不是删了重写——避免数据丢失。

(target: Path, content: str, encoding: str = "utf-8")

def _atomic_write_text(target: Path, content: str, encoding: str = "utf-8") -> None:
    """write-then-rename 原子写：先写到同目录的临时文件再 os.replace 重命名。
    保证别的进程读 target 时只能看到完整旧内容或完整新内容，不会读到半截。

    Windows 兼容：当目标文件被另一进程持 read handle（如 web server 正在 readFile）
    时，os.replace 会抛 PermissionError [WinError 5]。重试 3 次（50ms 间隔）。
    最终失败时**保留临时文件**让用户可手动 mv 收拾，而不是删了重写——避免数据丢失。
    """
    import time as _time

    target.parent.mkdir(parents=True, exist_ok=True)
    tmp_fd, tmp_path = tempfile.mkstemp(
        dir=str(target.parent),
        prefix=f".{target.name}.",
        suffix=".tmp",
    )
    try:
        with os.fdopen(tmp_fd, "w", encoding=encoding, newline="") as f:
            f.write(content)
    except Exception:
        # 写 tmp 都失败 → 直接清理 + 抛
        try:
            os.unlink(tmp_path)
        except OSError:
            pass
        raise

    # rename 阶段：Windows 锁竞争重试
    last_exc: Exception | None = None
    for attempt in range(3):
        try:
            os.replace(tmp_path, str(target))
            return
        except PermissionError as e:
            last_exc = e
            _time.sleep(0.05)
    # 3 次都失败：清理 tmp（避免污染 git status），给 stderr 明确提示让用户重试
    try:
        os.unlink(tmp_path)
    except OSError:
        # 实在删不掉 → 提示用户清理路径
        print(
            f"[_atomic_write_text] 警告：临时文件无法清理：{tmp_path} "
            f"（可能仍被进程持有；请重启相关进程后手动 rm）",
            file=sys.stderr,
        )
    print(
        f"[_atomic_write_text] os.replace 失败 3 次（目标 {target} 可能被另一进程持锁）；"
        f"请稍后重试，或重启占用该文件的进程",
        file=sys.stderr,
    )
    if last_exc is not None:
        raise last_exc

# 让 Windows 终端也能正确输出中文
if sys.platform == "win32":