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

远程打包与产物归档

仅在任务涉及编译新固件或下载远程产物时读取本文件。

默认值与覆盖

项目	默认值
SSH Host	emb.eapil.com
工程根目录	/CamTells
Public 来源	~/work/develop/gitcode/EMX2.1
本地归档根目录	F:\tmp\embedded-app-pc-debug

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

工程定位

1. 先用现有 SSH/VS Code 配置解析 Host，不猜测用户名、端口或私钥路径。
2. 将用户给出的项目名视为 /CamTells 下的相对路径并精确匹配。
3. 如果有多个候选，列出远程绝对路径等待选择；不要凭目录修改时间挑选。
4. 确认工程目录包含待用脚本，再确定真实命令行参数。

构建顺序

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 用于局域网升级，但完整发布包仍判为失败或不完整。

打包任务交付清单

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

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