smart-file-writer 用于处理文件写入失败。当出现 Error writing file、Permission denied、Access denied、No space left on device、File exists、Path too long（Windows）、Read-only file system 等错误，或任意语言的文件写入失败时使用；也可在关键写入前以主动模式预检。
主要能力：系统化诊断而非盲目重试。诊断清单包括路径长度（Windows 260 字符限制）、父目录是否存在、目录与文件写权限、磁盘可用空间、文件锁检测，以及 Windows 的 in use 与文件属性检查。解析模式包括：创建缺失目录（os.makedirs(..., exist_ok=True)）、原子写入（临时文件加 os.replace）、针对瞬时问题的指数退避重试、长路径改用哈希短名、权限修复建议（Linux/Mac 用 chmod u+w；Windows 用 attrib -r，必要时 takeown /f 与 icacls /grant %username%:F）、检测杀毒软件临时阻断。可包装 Write、Edit 及 Bash 文件操作：写入前先运行 validate_write_conditions 检查条件，发现问题先纠正再执行。
使用方式：提供目标文件路径、预期操作（write、append、create 等）与错误信息（反应模式）。执行前按诊断清单逐项排查，定位根因后套用相应解析模式并重试。
限制：不处理基本诊断之外的网络文件系统（NFS、SMB）问题；未经用户确认不修改系统级权限；不绕过安全策略或杀毒软件；不处理数据库写入；部分杀毒软件难以可靠检测；系统级权限变更需管理员权限。文件被其他进程锁定（如 Excel 打开）时无法自动解决，需用户关闭文件或改写入其他文件名。详细诊断流程、平台差异、集成指南与错误目录见 references 下相应文档。