embedded-app-pc-debug/references/build-workflow.md

远程打包与产物归档

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

默认值与覆盖

项目	默认值
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 产物已就绪”“设备已运行”“功能验证通过”。设备验证步骤见 应用模块调试，不能因完成拷贝就宣称验证通过。

打包任务交付清单

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

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

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

下载与归档

创建：

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

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

建议日志：

• build.log
• EmxGitInfo.txt
• download.log
• firmware.sha256

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