解压workbuddy安装包报错需先验证压缩包完整性，核对官网公示的字节大小与sha256值；其次更换兼容工具如7-zip 24.07或keka 2.5.28+；再检查目标路径权限及字符限制，改用纯英文本地路径；最后可跳过解压，直接用docker load导入离线镜像。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试解压 WorkBuddy 安装包时出现报错（如“文件损坏”“未知压缩格式”“CRC校验失败”或“无法创建文件”），则可能是由于压缩包本身不完整、被截断，或当前解压工具版本过低、不兼容该归档格式。以下是解决此问题的步骤：
一、验证压缩包完整性与下载状态
压缩包在传输过程中若遭遇网络中断、浏览器异常终止或代理劫持，会导致文件末尾缺失，引发解压器读取到无效数据块而报错。必须确认本地文件字节长度与官网公示值完全一致，且无隐式损坏。
1、访问官网 https://www.codebuddy.cn/work/ ，查找当前版本安装包（如 workbuddy-offline-v2.4.0.tar.gz）旁标注的精确文件大小（例如：182,456,789 字节）与 SHA256 哈希值。
2、打开文件管理器，右键点击已下载的压缩包 → 选择“属性”或“显示简介”，核对“大小”字段是否与官网数值完全相等（注意单位为字节，非KB/MB换算值）。
3、若大小不符，立即删除该文件，切换至稳定 Wi-Fi 环境，使用 Chrome 或 Safari 直接从官网下载，禁用任何下载加速插件或迅雷类工具。
二、更换兼容性更强的解压工具
部分旧版解压软件（如 Windows 自带“文件资源管理器”、早期 7-Zip 15.x、The Unarchiver v4.2 以下）不支持 tar.gz 中嵌套的 GNU Long Link 扩展头或 zstd 压缩算法，导致解析元数据失败并中止解压流程。
1、Windows 用户请卸载旧版解压工具，安装 7-Zip 24.07 或更高版本（官网：https://www.7-zip.org/），右键压缩包 → “7-Zip” → “提取到当前文件夹”。
2、macOS 用户请卸载 The Unarchiver，改用系统原生归档实用工具（Archive Utility），或安装 Keka 2.5.28+（支持 modern tar + zstd）（官网：https://www.keka.io/）。
3、Linux 用户请确保已安装 GNU tar 1.34+ 与 gzip/zstd 支持：执行 tar --version 和 zstd --version 验证，若缺失则运行 sudo apt update && sudo apt install tar gzip zstd（Debian/Ubuntu）或 brew install gnu-tar zstd（macOS Homebrew）。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
三、检查文件系统权限与路径限制
解压过程需在目标目录写入数百个子文件及符号链接，若目标路径位于只读卷、加密容器（如 VeraCrypt）、OneDrive/Google Drive 同步根目录，或路径含 Unicode 特殊字符（如中文、全角括号、控制字符），将触发权限拒绝或路径截断错误。
1、将压缩包复制至本地磁盘根目录下新建的纯英文路径，例如：C:\temp\wb\（Windows）或 ~/Downloads/wb/（macOS/Linux）。
2、右键目标文件夹 → “属性” → 确认“只读”属性未勾选；macOS 用户在终端执行 ls -lO ~/Downloads/wb/，确认无 restricted 或 hidden 属性。
3、在该纯净路径下，使用上一步验证过的最新版解压工具重新执行解压操作。
四、跳过前端解压，直接加载容器镜像（仅限离线包）
WorkBuddy 离线包（.tar.gz）本质为 Docker 镜像归档，其内部包含预构建的 image layers，无需传统解压即可导入运行时环境。此方式绕过所有文件系统级校验环节，适用于解压工具不可控或磁盘空间受限场景。
1、确保已安装 Docker Desktop 4.30+（Windows/macOS）或 docker-ce 24.0+（Linux），并启动服务。
2、在压缩包所在目录打开终端（PowerShell/Terminal），执行：docker load -i workbuddy-offline-v2.4.0.tar.gz。
3、等待命令输出 Loaded image: workbuddy/server:v2.4.0 及类似信息后，直接运行：docker compose up -d 启动服务。
