13 KiB
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 自行读取，不再向用户追问命令。
先把原理图、规格书、GPIO 表和已经确认的 BSP 事实收敛为仓库外 hardware-topology.json，运行 validate_hardware_topology.py。它至少记录芯片、系统形态、存储类型/容量、每路 Sensor 型号、I2C bus/address、MIPI device、lane 数、枚举名、证据源路径/hash，以及对 sensor_cfg.ini 的显式字段期望。器件型号未给出时只能按用户允许的范围记录容量，不猜型号。目标旧配置和参考 PSP 属于待核对的软件现状，不能作为覆盖硬件资料的证据；任何未解决冲突都阻止适配。
缺失可从仓库发现的事实时先调查，不要求用户重复。是否有参考 PSP、负责人决定或跨平台风险属于用户决定，不能推断；用户明确没有参考时启用下述“无参考”分支。同一缺项连续出现时只更新缺项列表，不重复完整问卷，也不在没有新输入时反复生成同一结论。
把 ~ 展开为运行 skill 的当前用户目录，并记录规范化后的绝对 PSP 根路径。目标项目必须是该根目录的普通直接子目录和独立 Git 仓库；保留已有分支、远端和仓库配置。目标目录不存在时停止并请用户或团队创建，禁止由 skill 建目录、运行 git init 或替用户配置远端。预创建目录已有业务内容时视为现有 PSP，只走基于 Git 差异的更新流程，禁止再次从参考 PSP 整体导入。
2. 参考兼容性
无参考 PSP 时本节兼容性和四视图报告标记为 N/A（无参考），不得伪造一个参考。先锁定精确 Media/AI Release 版本/profile、硬件事实、BSP handoff 和应用打包接口，依CV181X Media/AI 取值指南生成全字段默认目录和生效配置差异。即使 Release 与源码完全相同，Media/AI 的 SDK、ABI、通道、模型、驱动与最终 PSP 值仍须单独验证。
比较参考和目标的芯片系列、板卡形态、单/双系统、存储介质、Sensor 数量/型号、GPIO/Pinmux 结构、媒体能力和 AIPlugin 能力。列出：
- 可直接继承；
- 需要修改；
- 无法确认；
- 明显不兼容。
明显不兼容时默认停止。用户明确接受跨平台参考风险后仍须把每个未验证项留在结果中。
参考或目标是 Git 仓库时运行 analyze_psp_delta.py，固定四个视图：目标 HEAD、目标 worktree、参考 HEAD、参考 worktree。后续差异必须归入“匹配参考稳定 HEAD”“匹配参考未提交 worktree”“目标特有”“未分类冲突”；不能把参考仓库的脏文件冒充其 commit 内容。未分类项必须逐项解决，工具报告和两个完整 commit 一并进入外部证据。
3. 受控适配
对于尚无业务内容的预创建项目仓库，有参考时按项目与 Git 规则在同一固定根目录的唯一 staging 中复制参考 PSP，排除参考仓库身份、构建输出、缓存、日志、临时文件、本机生成物和旧的应用侧 psp.lock.json。无参考时使用 psp_project_guard.py prepare-empty 建立空 staging，依据应用接口、BSP handoff、硬件拓扑和精确 Release 默认值逐项建立业务文件；工具不会生成 psp.json、分区、Sensor、GPIO 或 PQ，缺少这些依据时只能保持 partial/blocked。最终仅把已验证业务内容导入目标，目标自身 .git 不进入 staging、也不被替换。
对于已有业务内容的目标项目，先证明它是固定根目录下的预期独立仓库，记录 HEAD、分支、远端和工作区状态；只修改任务明确授权的文件，并以修改前 commit/worktree 为差异基线。不得为了套用参考项目而清空、覆盖或重新初始化目标。
只修改确认的目标差异。无参考时“修改”指相对选定 Release 默认/应用接口新建或改变的字段，不是相对另一个板卡。适配后生成两张清单：
- 修改项：文件、关键字段、旧值、新值、依据和影响；
- 继承项：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 和单/双系统形态；项目身份和权限证据一致但当前输出权限不足时，自动只补齐本次 imgs 路径的 a+rX 并复核。任一身份缺失或不一致、权限证据缺失或无权修复都阻止 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，避免未经协调改变应用打包接口。
任何分区变化必须运行 validate_partition_closure.py，从 psp.json 推导几何并核对 PSP 内实际生效的 Boot/Default 和应用 release.py。任何 Sensor、BSP build、Media/AIPlugin 变化都按配置依赖闭包逐项检查，不能只改最显眼的一个文件后进入 candidate。
5. 静态验证和打包准备检查
最低静态检查包括：
- 受控复制和差异白名单；
- PSP 目录、JSON/INI 和 shell 语法；
- 文本编码、软链接和不可访问路径；运行时目录软链接不跟随扫描，但必须由资源映射和打包检查单独证明；
- 旧项目残留；
- BSP handoff、路径、大小和 hash；
- GPIO、Media、Sensor 枚举映射、AIPlugin、SDK 和模型引用的一致性，以及 ISP/PQ 的用户负责状态；
- 硬件拓扑证据、四视图差异分类（无参考时为 N/A 并附 Release→生效值目录）、配置依赖闭包和分区闭包；
- 应用与 PSP 的同名配置覆盖清单；
- 未决、警告和批准例外。
在导入目标 PSP 和创建候选提交前，还要读取用户指定应用工程的固定打包入口，并运行：
record_packaging_result.py contract，根据<应用工程>/psp、scripts/、output/和目标芯片生成仓库外的本地契约；record_packaging_result.py preflight --psp-source <staging>，提前核对EmxResToProduct的每个资源来源、重复目标、data.file、DATA 组包工具映射、mkAiData.py参数、PSP 分区与 BSPbsp.lock.json；- 只读检查
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 创建新的底层任务。
无参考项目时渲染交接用 render_psp_handoff.py --no-reference，并附精确 Release/profile/hash 和逐字段审计报告；不可把 Release 目录或其他板卡虚构成参考 PSP。
职责内问题形成新 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 可作为正式应用集成基线，不代表整机测试、所有硬件行为、媒体/算法效果或产品发布已经通过。