示例项目：AtomicExportGate / AE-407
技术范围：Image Kit 编码交付之后的 Node.js 文件归档

一、清晰度处理完成后，文件名仍可能毁掉结果

图像超分流程讨论得最多的是输出尺寸、模型耗时和观感提升。可一旦用户对同一张素材反复调整参数，最容易出现的工程事故不一定在模型内部，而在文件写出阶段。两次任务都叫 preview.png，后一次任务覆盖了用户认可的前一版；或者进程在写到一半时退出，目录留下一个存在但内容不完整的文件，下一步打包脚本便误把它当成最终成果。

AtomicExportGate 把关注点放在“结果如何提交到输出目录”，而不是“算法如何让图片更清晰”。构造任务共四个：IMG-71 正常发布为 preview.png；IMG-72 想再次占用同一路径，应标记 HOLD_NAME；IMG-73 发布不同文件名 preview-73.png，正常完成；IMG-74 的输出名使用 ../escape.png，应在路径合法性检查阶段阻断。预期汇总为 READY 2、HOLD_NAME 1、HOLD_PATH 1。

本文所有输入是 Pillow 创建的小型 PNG 样本，目标是实际验证文件操作行为，不对图像清晰度作主观或定量评测，也不包含未经核实的超分 SDK 接口。HarmonyOS Image Kit 负责真实应用中的图片解码、编辑及编码；本例从“已获得可交付 PNG 字节”这一边界开始。把两个环节分开，更容易查清哪些是平台能力、哪些是项目交付策略。

二、先建立一份不依赖运气的交付合同

输出目录中正式出现的文件应该满足几个基本条件：名称只能是项目允许的 PNG 文件名，不允许穿越目录，不允许拿绝对路径替换目标路径；同名文件一旦存在，新的任务不能默默覆盖它；临时写入和最终对外可见应是两个阶段。清理临时文件时，也不能顺手删掉一个已经发布成功的正式文件。

这里不把“文件已生成”作为唯一成功条件。提交记录要包含业务任务号、目标文件名、写入状态和错误原因。READY 只表示 Node.js 离线任务把构造 PNG 完整发布到本地目录，不代表已经完成超分或通过应用商店审核。对于有版本更新需求的产品，应以新的版本号或新的路径发布，而不是放宽同名覆盖限制。

源文件和目标文件必须位于可信的工作目录。示例用 basename() 和有限的文件名字符集拒绝 ../ 等路径；真实业务还要避免目标目录被不可信进程更改、软链接替换和跨文件系统操作。本例假设输出目录归当前构建任务独占，不允许其他攻击者同时改变其目录结构。

三、在正式路径出现之前先写临时文件

通常的 writeFile(target, bytes) 会先创建或截断目标，写入期间就可能被其他消费者观察。即使没有并发，程序崩溃也可能留下半成品。因此示例先把内容写到同一输出目录中的随机临时路径，再尝试以硬链接发布到最终路径。目标已存在时，链接创建会返回 EEXIST，脚本把这归为 HOLD_NAME，而不覆盖旧文件。

下面给出核心步骤。它解决“新任务不能覆盖已有输出”和“消费者不应看到正在写入的目标文件”的问题：

import { writeFile, link, unlink } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';
import { resolve } from 'node:path';
async function publish(bytes, directory, name) {
  const temp = resolve(directory, `.${randomUUID()}.tmp`);
  const final = resolve(directory, name);
  try {
    await writeFile(temp, bytes, { flag: 'wx' });
    await link(temp, final); // 同一文件系统内不覆盖已存在目标
  } finally {
    await unlink(temp).catch(() => {});
  }
}

flag: 'wx' 防止临时文件撞名，随机名称降低概率但不能替代文件系统的排他创建。link() 使用同一文件系统内的硬链接，只有完整写入临时文件之后才创建正式目录项；如果目标已有同名项，它不会替换目标。链接成功后删除临时目录项，正式路径仍指向相同数据。示例没有把文件系统崩溃后的持久性写入屏障作为已经解决的问题；严格要求掉电持久化时，需要按运行环境的文件系统语义处理数据与目录同步。

这套做法也不适用于所有存储环境：跨文件系统硬链接通常不支持，某些沙箱策略或外部卷不允许创建硬链接。不能把 Node.js 的本地实验结果直接推断成 HarmonyOS 设备上所有目录的行为。生产版本需要根据目标运行平台评估临时写入、重命名、排他占用及权限策略。

四、把路径和同名错误变成明确的业务结果

错误处理应在读取源文件之前就阻止不安全输出名称。示例允许由英文数字开头、后续出现英文数字、句点、短横线和下划线的 PNG 名称，同时要求 basename(name) === name。这是项目自定义命名合同，不是 PNG 标准，也不应拿它替代真实的路径安全模型。只有检查通过的任务才读取 fixtures/ 中的 PNG 字节并尝试发布。

import { basename } from 'node:path';
function safeName(name) {
  return /^[a-z0-9][a-z0-9._-]*\.png$/i.test(name)
    && basename(name) === name;
}
function classify(error) {
  if (error?.code === 'EEXIST') return 'HOLD_NAME';
  throw error; // 其他 I/O 异常交给上层终止或重试
}

HOLD_PATH 由文件名预检产生，HOLD_NAME 来自目标路径的排他发布失败。二者不能混成一个“保存错误”：前者属于输入不可信，原样重试没有意义；后者可以由用户选择新的版本文件名后重新提交。空间不足、无权限和磁盘异常则属于真正的 I/O 错误，脚本不应吞掉这些异常，也不应该假装结果已经成功。

完成后还需要逐一核对输出目录。存在 preview.png 与 preview-73.png 两个正式文件，且没有 escape.png 出现在项目根目录之外，才说明此构造任务达成最初的交付约束。文件内容可以再算摘要，与源字节比对；本次 demo 保留源和目标文件供复核，避免只通过日志做判断。

五、用四份构造输入把错误分支跑一遍

随包 jobs.json 的四个任务按固定顺序执行。IMG-71 首次创建 preview.png，应返回 READY；IMG-72 使用同一目标，应返回 HOLD_NAME，不能覆盖 IMG-71 的已发布文件；IMG-73 使用 preview-73.png，应返回 READY；IMG-74 的目标为 ../escape.png，应直接返回 HOLD_PATH。每个任务会输出带 AE-407 前缀的日志，汇总 READY=2 HOLD_NAME=1 HOLD_PATH=1。

const tally = { READY: 0, HOLD_NAME: 0, HOLD_PATH: 0 };
for (const job of fixtures) {
  const state = !safeName(job.output) ? 'HOLD_PATH'
    : await tryPublish(job); // 内部捕获 EEXIST → HOLD_NAME
  tally[state]++;
  console.log(`AE-407 ${job.id} ${state}`);
}
console.log(`AE-407 READY=${tally.READY} HOLD_NAME=${tally.HOLD_NAME} HOLD_PATH=${tally.HOLD_PATH}`);

这段是业务控制流程摘录，tryPublish() 的完整实现位于包内的 tools/atomic-export.mjs，不是一个存在于 Image Kit 里的平台 API。打包前实际运行 Node.js 示例并保留 run.log，同时检查两个目标 PNG 可以读取，且 IMG-72 的输入字节没有取代 IMG-71。由于结果目录采用独立工作副本，反复运行相同脚本会因目标已有文件触发更多 HOLD_NAME；重新验证时应先清理示例 output/，切勿把二次执行与首次结果混在一起。

六、接入 HarmonyOS 应用前还要补哪些环节

如果业务最终运行在 HarmonyOS 应用里，图像资源还涉及 PixelMap 创建、编码缓存、文件描述符以及页面生命周期的释放。官方 Image Kit 文档会区分缓存区编码与文件输出，并明确提醒按照正确顺序初始化和销毁资源。本篇把已经完成编码的字节交到归档层。真实应用迁移时，应围绕文件描述符打开、编码异常、应用退后台和低存储空间场景重新验证。

对预览界面来说，写入成功也不应立即丢掉上一个可用版本。较稳妥的方案是把新文件发布为一个新的版本名，只有在文件字节校验和业务索引更新均成功后，才将“当前选中版本”切换过去。若索引写入失败，旧版本仍然可以回退；如果新版本已经发布但索引失败，则记录待回收项，不能简单地把所有新文件删除。

临时文件清理也是长期运行工具必须处理的事情。进程可能在写入临时文件以后、发布之前被强制结束。启动时应只清理符合命名约定且超过安全保留时间的临时项，并防止误删其他进程仍在使用的文件。为防止容量积压，可以按作业号保留产物索引和回收状态，但该索引也需要事务化处理。

最后，文件写入状态不应泄露不必要的绝对路径。日志尽量以任务号、文件名和错误码表达结果，避免暴露用户私有目录结构。用户实际操作中应提供“重新命名并导出”或“查看冲突文件”这样的明确选择，而不是偷偷替换已有文件。

七、把原子提交当作交付边界

这篇文章真正解决的是“输出文件何时算可以交付”。它没有宣称图片真的从低清晰度提升到了高分辨率，也没有宣称某个 HarmonyOS SDK 自带完整的同名保护。Node.js 示例可在受控目录验证：两份输出成功、一份同名被挡住、一份非法路径被拒绝。真实系统里还需要测试文件系统语义、异常清理、空间不足、并发写入和掉电持久性。

当生产流水线把编码阶段和发布阶段分开，再通过版本名、内容摘要和用户可见的回执关联起来，同名冲突就不再是一次隐蔽覆盖，而是能够定位和恢复的工程事件。本文配图均为独立绘制的技术示意，官方能力与项目自定义逻辑也分别注明，便于读者按自身环境复核。

官方资料： https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-v5/image-encoding-native-V5 ；https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/pixelmap-c