workspace download
workspace download 从 Workflow Server 获取指定 target 的项目源码，并写入本地目录。draft 使用单项目文件接口并替换目标目录；已发布版本会自动携带当前操作系统对应的 Desktop 平台，读取该根版本的 dependency lock，并把有权限的 included 项目写入同一父目录。下载恢复 Server 已保存的源码快照，不重新应用 .workflowignore 或 .gitignore。
Kanban 的图片、字体等二进制资源以 base64 文件响应传输，CLI 会解码并恢复原始字节；文本项目仍使用原有字符串 content。
命令格式
pnpm exec workflow-code workspace download <workflow> [--target draft|latest|version] [--path <dir>]
参数
| 参数 | 说明 |
|---|---|
<workflow> | 远程 workflow 名称。 |
--target <target> | 下载目标。默认 latest。 |
--path <dir> | 本地目标目录。未传时写入 workspace/workflow/<workflow>。 |
Target
| 值 | 说明 |
|---|---|
draft | 只下载根项目当前 draft，并完整替换目标目录，不处理依赖锁。 |
latest | 默认值。在 macOS 或 Windows 上解析为当前平台最新的在线兼容根版本，再按该精确版本的 dependency lock 下载。它与项目整体 latest、Server latest 可以不同。 |
| 具体版本号 | 下载指定已发布版本及其 included 依赖；不会读取依赖项目的 latest。根版本必须声明支持当前 Desktop 平台并使用 source 模式。 |
workspace download 在 macOS 发送 platform=macos，在 Windows 发送 platform=windows。Linux 和其它操作系统没有隐式兼容平台，命令会在下载任何 target 前拒绝执行。
API
| 步骤 | Endpoint |
|---|---|
| 下载 draft | GET /api/workflows/{workflow}/files?target=draft&includeBinary=true |
| 下载已发布项目组 | GET /api/workflows/{workflow}/project-group-download?target=<target>&platform=macos|windows |
写入规则
| 规则 | 说明 |
|---|---|
| draft 目标目录 | 写入前递归清空，再根据 server 返回路径恢复根项目。 |
| 已发布根项目 | 写入 --path 或默认根目录；目录已被其它 UUID 占用时拒绝覆盖。 |
| included 依赖 | 写入根项目同一父目录下的独立同级目录。父目录中已有相同 UUID 项目时视为已满足且不覆盖。 |
| 写入内容 | 文本直接写入 content；encoding: "base64" 时先严格解码再写入二进制内容。 |
| 原子性 | 新项目先写入同一父目录的临时 staging；任一校验、目录移动或写入失败时移除本次新增目录。 |
安全校验
| 校验 | 说明 |
|---|---|
| 禁止绝对路径 | server 返回 /... 或 Windows 盘符路径会被拒绝。 |
| 禁止路径穿越 | 空路径、.、.. 或包含空段的路径会被拒绝。 |
| 保留服务端清单 | dist、.workflowignore 或其它已上传文件会原样恢复，不做第二次忽略。 |
| 依赖锁一致性 | 根 Kanban 精确版本中已确认的 relatedProjects 必须与 Server 返回的 dependency lock 一致；CLI 会按路径和原始文件字节重算每个返回项目的 SHA-256，根版本、included 项目的精确版本和 source hash 必须全部匹配。 |
| Desktop 发行兼容 | Server 只用根版本的 executionTargets.desktop 校验当前平台；included 依赖继续按根版本的精确 dependency lock、源码保留状态和下载权限处理，不要求依赖单独声明当前 Desktop 平台。 |
| 宿主数据隔离 | Server 响应和本地写入都拒绝 .env*、KV、PersistentValue、定时计划、运行历史、SQLite、workflow-auth.json 和其它宿主用户配置。 |
输出
| 情况 | 输出 |
|---|---|
| 完整下载 | 输出根项目、included 依赖、本地路径、精确版本和 complete: true。 |
| 部分下载 | 仍保存有权限的项目，并在 skippedDependencies 输出 external、源码不可用或需权限的依赖及申请链接。 |
| 文件路径非法 | 输出错误信息，退出码为 1。 |
| 未登录 | 输出错误信息，退出码为 1。 |
示例
pnpm exec workflow-code workspace download hello
pnpm exec workflow-code workspace download hello --target latest
pnpm exec workflow-code workspace download hello --target 1.2.0 --path ./workspace/workflow/hello-copy
注意事项
| 场景 | 建议 |
|---|---|
| 目标目录有本地改动 | 先备份或选择新的 --path。 |
| 只想查看远程版本 | 使用 versions。 |
| included 依赖缺少权限 | 打开输出中的短期申请链接；来源 owner/manager 批准后重试同一命令，已有同 UUID 项目不会重写。 |
| external 依赖 | 不参与联动下载，需要自行准备对应 UUID 的来源项目。 |
| 当前系统不是 macOS 或 Windows | 没有隐式兼容目标；请改在已声明支持的 Desktop 平台下载。 |
| 下载后看板无数据 | 属于预期行为。Server KV 不进入本地；请在本地运行来源 Workflow 同步入口。 |