# 远程打包与产物归档

仅在任务涉及远程编译（完整固件或单模块）或下载远程产物时读取本文件。

## 默认值与覆盖

| 项目 | 默认值 |
|---|---|
| SSH Host | `emb.eapil.com` |
| 工程搜索根 | 当前远程工作区、`~/work/develop/gitcode`、实际挂载点；可把已知产品目录（例如 `/CamTells`）作为候选之一，不限于该目录 |
| Public 来源 | `~/work/develop/gitcode/EMX2.1` |
| 本地归档根目录 | `F:\tmp\embedded-app-pc-debug` |

用户提供的值优先。凭据只使用现有 SSH 配置、密钥代理或交互式认证，不把密码、私钥和 Token 保存到 skill 或任务日志。

## 工程定位

1. 先用现有 SSH/VS Code 配置解析 Host，不猜测用户名、端口或私钥路径。
2. 优先使用用户给出的绝对路径。只给项目名时，从 VS Code 最近工作区、`~/work/develop/gitcode`、实际挂载点和已知产品目录按目录名精确搜索；`/CamTells` 是可选候选，不代表其他产品工程的位置。搜索深度至少覆盖从用户目录起 12 层，并为每个根设置独立合理超时。
3. PowerShell 调用远端 Shell 时，避免让本地提前展开远端 `$HOME` 等变量。记录每个搜索根的退出码并明确区分：没有匹配、无权访问、路径未挂载、命令不存在和搜索超时。超时不等于项目不存在。
4. 如果有多个候选，列出远程绝对路径等待选择；不要凭目录修改时间挑选。
5. 确认工程目录包含待用脚本，再确定真实命令行参数。产品目录可能较深，例如 `product/<产品线>/<项目>`；不能因浅层 `find -maxdepth` 排除有效工程。

## 构建顺序

1. 在当前工程目录执行 `EmxGitInfo`，将标准输出、标准错误和退出码保存为 `logs/EmxGitInfo.txt`。不先运行 Git 工作区检查。
2. 查看 `scripts/product.py`、`release.py` 的帮助、源码入口或项目说明，确认参数和要求的工作目录。不同工程的参数及启动目录可能不同，不能照搬其他项目命令；脚本位于 `scripts` 不代表应从工程根目录启动，也不代表一定应从 `scripts` 启动。
3. 只有实际缺少 `Public`、第三方库映射或脚本明确报资源缺失时，才检查并运行 `softLink.py`。创建前核对目标与默认来源 `~/work/develop/gitcode/EMX2.1`，避免覆盖已有有效链接。
4. 先运行 `product.py` 构建环境包，成功后运行 `release.py` 编译项目。
5. 每一步记录：工作目录、完整命令、开始/结束时间、退出码和关键输出。
6. 尊重构建脚本内部的校验与重建循环。脚本因随机命中、签名或封装检查而自动重建时，让脚本自行完成；不要在外层重复启动、重复改版本或把一次内部重建误报为多个发布版本。
7. 构建失败时不下载旧产物。若本次 ROM 已由脚本明确生成、校验通过，而随后仅全量烧录镜像或其他辅助目标失败，应分开报告：允许交付已验证 ROM 用于局域网升级，但完整发布包仍判为失败或不完整。

## 单模块交叉编译与 NFS 交付

用户只要求编译某个应用或库时，不强制执行完整固件的 `product.py`、`release.py` 流程。优先复用当前远程工程已验证的构建目录和目标，核对其源码目录、交叉工具链、目标架构及必要构建选项；缓存指向其他工程或工具链时先说明冲突，不直接覆盖或继续编译。

记录实际构建目标、命令、退出码、本次产物的绝对路径、大小、SHA-256 和 ELF 信息。按运行需求交付必要动态库及其链接关系，不把静态库、开发头文件或旧目录中的同名文件一概当成设备运行依赖。

用户指定 NFS 导出目录时，在该目录下使用独立的本次产物目录，保留旧程序和依赖；避免覆盖设备正在从 NFS 执行的二进制。拷贝后核对源与目标的哈希及执行权限，并明确区分“远端构建完成”“NFS 产物已就绪”“设备已运行”“功能验证通过”。设备验证步骤见 [应用模块调试](application-debugging.md)，不能因完成拷贝就宣称验证通过。

## 打包任务交付清单

Linux 打包任务应一次性交付以下事实，供 Windows 设备任务直接使用：

- 工程绝对路径、实际运行目录和构建命令；
- ROM 与 `devInfo.json` 的远程绝对路径；
- ROM 大小、MD5、SHA-256、目标内外层版本；
- 构建记录、警告以及哪些发布目标成功或失败；
- 产物是否已下载或排队到 Windows 任务。

Windows 任务已取得内容完整且自洽的交付清单后，不重复 SSH 到 Linux 重新计算同一组构建事实。只有交付缺字段、相互矛盾、文件校验不一致或用户明确要求复核时，才回到远端检查。

## 下载与归档

创建：

```text
F:\tmp\embedded-app-pc-debug\<项目名>\<YYYYMMDD-HHmmss>\
├─ firmware\
└─ logs\
```

下载前解析远程 ROM 的真实绝对路径。下载后核对交付清单中的远端大小与本地大小，并计算本地 SHA-256；已有远端 SHA-256 时必须比较。多个 ROM 候选时列出文件名、大小、时间和可解析版本；只有唯一候选才可自动选择。

建议日志：

- `build.log`
- `EmxGitInfo.txt`
- `download.log`
- `firmware.sha256`

不要自动提交、推送、清理或还原远程仓库。