firmware-lowlevel-development/skills/firmware-lowlevel-psp-development/references/workflow.md

PSP 主工作流

1. 输入和事实基线

开始前从项目和安全只读检查中确认：

• 目标应用项目路径、新项目名称，以及固定根目录 ~/work/project/EMX2.1/AppTeam/Psp/ 下由用户或团队预创建的同名 PSP 项目目录；
• 用户指定的相近板卡 PSP 路径或精确 commit；
• 芯片、硬件 revision、单/双系统、存储介质和目标 BSP build type；
• BSP doc/bsp_adaptation/handoff/psp_handoff.json；
• 相对参考 PSP 的已知 GPIO、内存/分区、Media、Sensor 和 AIPlugin 差异，以及由用户更新的 ISP/PQ 状态；
• CV18 项目的 Sensor 规格选型和原理图/GPIO list；枚举表由 skill 按芯片系列从内置基线自动选择，不要求用户另行提供头文件；
• PSP、应用集成、设备验证和批准负责人；
• 禁止修改的目录及可用的 Git/Etunel 上下文。
• 用户指定的 EMX2.1 应用工程绝对路径；工程已有固定 scripts/product.py、scripts/release.py 和 output/ 约定时，Skill 自行读取，不再向用户追问命令。

缺失可从仓库发现的事实时先调查，不要求用户重复。参考 PSP、目标差异、负责人决定或跨平台风险属于用户决定，不能推断。同一缺项连续出现时只更新缺项列表，不重复完整问卷，也不在没有新输入时反复生成同一结论。

把 ~ 展开为运行 skill 的当前用户目录，并记录规范化后的绝对 PSP 根路径。目标项目必须是该根目录的普通直接子目录和独立 Git 仓库；保留已有分支、远端和仓库配置。目标目录不存在时停止并请用户或团队创建，禁止由 skill 建目录、运行 git init 或替用户配置远端。预创建目录已有业务内容时视为现有 PSP，只走基于 Git 差异的更新流程，禁止再次从参考 PSP 整体导入。

2. 参考兼容性

比较参考和目标的芯片系列、板卡形态、单/双系统、存储介质、Sensor 数量/型号、GPIO/Pinmux 结构、媒体能力和 AIPlugin 能力。列出：

• 可直接继承；
• 需要修改；
• 无法确认；
• 明显不兼容。

明显不兼容时默认停止。用户明确接受跨平台参考风险后仍须把每个未验证项留在结果中。

3. 受控适配

对于尚无业务内容的预创建项目仓库，按项目与 Git 规则在同一固定根目录的唯一 staging 中复制参考 PSP，排除参考仓库身份、构建输出、缓存、日志、临时文件、本机生成物和旧的应用侧 psp.lock.json。保持参考 PSP 的有效目录、配置、脚本、小型资源和精简文档。最终仅把已验证业务内容导入目标，目标自身 .git 不进入 staging、也不被替换。

对于已有业务内容的目标项目，先证明它是固定根目录下的预期独立仓库，记录 HEAD、分支、远端和工作区状态；只修改任务明确授权的文件，并以修改前 commit/worktree 为差异基线。不得为了套用参考项目而清空、覆盖或重新初始化目标。

只修改确认的目标差异。适配后生成两张清单：

1. 修改项：文件、关键字段、旧值、新值、依据和影响；
2. 继承项：GPIO、Sensor、BSP、Media、AIPlugin 等关键配置及确认状态。

扫描旧项目名、旧芯片/板卡、旧 BSP build ID、旧绝对路径、旧 Sensor、旧 SDK/Media/AIPlugin 版本、脚本硬编码及“临时修改/记得修改”等残留。每个命中必须归类为已替换、确认继承或无法判断；无法判断项阻止 accepted。

4. 先处理 BSP 阻塞

使用 validate_bsp_handoff.py 校验精确 BSP 输入，并把稳定摘要写入 metadata/bsp.lock.json；不要修改 BSP handoff。调用 validate_psp.py 时必须显式提供目标 PSP 项目名，以及期望的 BSP 项目、芯片、SDK、build type 和单/双系统形态，任一身份缺失或不一致都阻止 candidate。关键 IMG 缺失或 hash 不一致时同样阻止 candidate。

如果 BSP handoff 缺失、镜像 hash 不符或 kernel/rootfs 的 512 KiB 余量检查失败，只报告这一组 BSP 问题和精确失败值，先交 BSP 处理。不要同时要求用户补 Sensor、ISP/PQ 或应用打包信息。能从现有 BSP 产物重新生成的证据应先做只读检查，再只申请一次明确的 BSP 操作确认。

按配置边界与检查核对 GPIO、内存/分区、Sensor、Media、AIPlugin 及应用覆盖关系。CV18 根据规格书确定枚举名称后调用 validate_psp.py --expected-sensor sensor=ENUM_NAME，工具根据芯片自动使用内置枚举表：CV181X 验证配置中的枚举名称，CV184X 验证该名称对应的枚举数值。无需搜索或传入 SDK 头文件；只有已确认的枚举版本差异才显式覆盖。ISP/PQ 仅记录用户负责的状态，不由 Skill 修改。psp.json 保持参考格式；新增治理数据写入 sidecar metadata，避免未经协调改变应用打包接口。

5. 静态验证和打包准备检查

最低静态检查包括：

• 受控复制和差异白名单；
• PSP 目录、JSON/INI 和 shell 语法；
• 旧项目残留；
• BSP handoff、路径、大小和 hash；
• GPIO、Media、Sensor 枚举映射、AIPlugin、SDK 和模型引用的一致性，以及 ISP/PQ 的用户负责状态；
• 应用与 PSP 的同名配置覆盖清单；
• 未决、警告和批准例外。

在导入目标 PSP 和创建候选提交前，还要读取用户指定应用工程的固定打包入口，并运行：

1. record_packaging_result.py contract，根据 <应用工程>/psp、scripts/、output/ 和目标芯片生成仓库外的本地契约；
2. record_packaging_result.py preflight --psp-source <staging>，提前核对 EmxResToProduct 的每个资源来源、重复目标、data.file、DATA 组包工具映射、mkAiData.py 参数、PSP 分区与 BSP bsp.lock.json；
3. 只读检查 product.py 依赖的 Media、AIPlugin、公共运行库和驱动配置。空数组、缺目录或脚本只打印错误但仍返回 0 的情况必须列为阻塞；PSP Skill 不自行修改应用脚本。

打包准备检查不执行 product.py 或 release.py。它失败时先在 staging 修正 PSP；问题属于应用框架、BSP 或公共组件时只给出文件、字段和影响，由对应所有者处理。不要先提交一个已知无法组包的候选版本。

警告分三组输出：阻止继续、需要用户确认、暂不影响当前步骤。ISP/PQ 的 USER_OWNED/PENDING、目标机运行路径在当前主机不可见等已知状态，单独列出，不计入静态错误总数。

6. 自动提交候选版本

需求和适配方案已经确认后，先输出完整差异、继承清单、静态验证、打包准备检查、风险、commit message，以及下一阶段的精确路径和命令。所有检查通过后直接完成本地导入、git add 和候选提交，不再询问是否提交。提交前后核对工作区内容一致，完整 SHA 是唯一 PSP 身份。

Git 身份未配置、工作区有非本任务改动、暂存区包含白名单外文件、验证结果在提交前发生变化或提交失败时停止。不要替用户配置 Git 身份、丢弃改动或改写历史；说明异常后请用户决定。./release.py 1、Git 上传、Etunel 发送、tag、设备和发布不在自动范围内。

7. 组包和设备/应用验证

候选提交创建后，自动把应用工程中已经登记且仓库身份一致的 psp 子模块更新到该完整 commit；不自动新建子模块、不更换 URL，也不提交应用仓库。随后用同一工具以 --formal 再做一次打包准备检查，确认 commit 和工作区未变。在 <应用工程>/scripts 自动运行 ./product.py；退出码和日志都没有错误后，自动运行默认增量的 ./release.py 0。按组包与设备验证证明本轮唯一新增的 output/<版本>/，再记录项目规则明确指定的唯一烧录包。

子模块不存在、URL 或仓库身份不一致、父仓库的 .gitmodules/psp 已有重叠改动、product.py 报错、release.py 0 报错或产物检查失败时停止并请用户决定。需要 clean rebuild 时也停止，展示原因和 ./release.py 1 精确命令，取得确认后才执行。

达到 packaged 后可以经 Etunel 提供给应用层，人工设备验证与应用集成并行：

candidate -> packaged -> device_verified
                      -> app_integrated
同一 commit 两项均通过 -> accepted

配置、脚本、小型资源或依赖变化使受影响证据失效；纯文档变化经差异证明和负责人确认后可以复用技术证据。

8. 交接和返工

按 Etunel 交接把 packaged candidate 提供给 Hub。应用问题必须携带 PSP commit、应用 commit、BSP build、复现步骤、期望/实际、日志和阻塞影响，经 Hub 创建新的底层任务。

职责内问题形成新 candidate commit；跨 BSP、应用、硬件或公共组件的问题只提交证据和归属建议，由 Hub 路由。不得 force-push 已供打包、设备或应用验证的 commit。

9. 完成状态

输出真实阶段，并同时给出中文解释：候选版本（candidate）、已组包（packaged）、设备验证通过（device_verified）、应用集成通过（app_integrated）、已验收（accepted）、部分完成（partial）或已阻塞（blocked）。完整成果引用 PSP 仓库/commit、BSP lock、静态检查、烧录包绝对路径/hash、人工设备反馈、应用集成、Etunel 交接、未执行项和剩余风险。

accepted 仅表示 PSP 可作为正式应用集成基线，不代表整机测试、所有硬件行为、媒体/算法效果或产品发布已经通过。