firmware-lowlevel-development/skills/firmware-lowlevel-psp-development/SKILL.md

name, description

name	description
firmware-lowlevel-psp-development	创建、修改和验证项目级 PSP 平台配置；有相近板卡 PSP 时受控继承，无参考项目时依据硬件/BSP 事实、应用接口与精确 Media/AIPlugin Release 默认配置逐字段建立。用于 CV181X Media/AI 通道和参数审计、PSP 适配、组包证据及交接；不用于 BSP/驱动、应用业务、公共组件或未经确认的设备/发布操作。

固件底层开发_PSP开发

把每个硬件项目的 PSP 作为独立、轻量的配置仓库维护。PSP 固定工作区是当前用户的 ~/work/project/EMX2.1/AppTeam/Psp/；项目目录由用户或团队预先在该根目录下创建。有参考 PSP 时只做最小差异；没有参考 PSP 时从已确认的硬件/BSP、应用接口和精确 Release 基线建立，不把任一 Release 当成完整 PSP。PSP 的唯一身份是完整 Git commit SHA。

进入流程

1. 先读取并遵守统一的流程文档写法，所有面向人的流程文档使用简体中文和直白表达。
2. 读取统一入口的项目所有权契约、治理工作流和风险等级。
3. 读取 PSP 主工作流，先形成带来源/hash 的硬件拓扑事实，再确认目标项目目录是固定工作区的直接子目录，并确认是否有参考 PSP、芯片/板卡/系统形态、BSP handoff、差异清单和负责人。目标目录不存在时停止，请用户或团队先创建；不得代为创建目录或初始化仓库。
4. 首次填充、迁移、提交或更新 PSP 仓库时，读取项目与 Git 规则。首次填充只对预创建的空独立 Git 仓库执行：先在 staging 中适配并审计，验证通过后自动导入并创建本地候选提交，同时保留 .git、分支和远端；不再为导入和提交重复询问。已有业务内容的项目转入现有项目更新流程，不得按参考复制覆盖。
5. 修改 GPIO、BSP 引用、内存/分区结果、Sensor、Media 或 AIPlugin 配置时，读取配置边界与检查。CV181X Media/AI 配置另读源码与 Release 取值指南，按每个字段的生效路径、代码行为和实际硬件需求取值。CV18 Sensor 默认按芯片系列使用 skill 内置枚举表；ISP/PQ 由用户更新。PSP 只消费 BSP 和公共组件成果，不越界修改其源码。
6. 使用 BSP 产物时，读取统一的 BSP→PSP 交接契约，校验用户明确提供的 psp_handoff.json；禁止扫描目录选择最新构建。
7. 需要组包或设备验证时，读取组包与设备验证。EMX2.1 的目录和命令按内置固定规则生成本地契约，再做打包准备检查；不用让用户重复提供已经固定的信息。
8. 需要跨角色交付或返工时，读取 Etunel 交接；机器可读文件按数据契约生成。

PSP 内容边界

PSP 仓库可以保存 psp.json、项目配置、运行脚本、用户提供的 ISP/PQ/标定参数、必要小型板级资源、精简结果文档和 metadata/bsp.lock.json。Skill 不生成或修改 ISP/PQ；保持参考 PSP 的目录和 psp.json schema，除非跨层变更已经确认。

PSP 仓库不保存固定打包框架、BSP 源码或 IMG、大型模型、公共运行库、烧录包、缓存、原始日志和持续变化的验证记录。HAL、驱动、Bootloader、DTS/DTSI、底层内存实现以及公共 Media/AIPlugin 代码不属于本模块。

不可绕过的门禁

• 新 PSP 优先使用用户明确指定的兼容参考 PSP；没有参考时允许走 prepare-empty，但必须独立证明硬件/BSP、应用 psp.json schema、Media/AI 精确 Release、运行配置、资源和分区闭包。仅凭 Release 默认值不能形成 candidate；跨平台参考明显不兼容时停止，除非用户知情确认风险。
• 原理图、规格书、GPIO 表和 BSP handoff 必须先收敛成 hardware-topology.json。目标旧配置和参考 PSP（若有）只证明软件现状，不能覆盖硬件资料；资料冲突未解决时停止。
• 目标 PSP 必须位于当前用户的 ~/work/project/EMX2.1/AppTeam/Psp/<项目名>/，是该固定根目录的普通直接子目录和独立 Git 仓库。目录缺失、软链接、嵌套仓库或根目录外路径均停止；不运行 mkdir 或 git init 补齐。
• 有参考时分别展示修改项和关键继承项；无参考时展示 Release 默认→最终生效值的逐字段差异及每项来源。能由代码、Release、BSP handoff 和硬件资料证明的值不要求用户重复确认；GPIO、Sensor、BSP 固件、Media 或 AIPlugin 有冲突、缺项或多种合理解释时阻止形成 candidate。
• CV181X 的 sensor_cfg.ini 中 name 必须填写内置 sensor_list.h 的 _SAMPLE_SNS_TYPE_E 枚举名称；CV184X 必须填写内置 sensor_cfg.h 的 _SNS_TYPE_E 对应枚举值。规格选型不明确或内置表中无匹配项时停止，不得猜测；只有已证明 SDK 枚举不同才使用显式头文件覆盖。
• 保留团队统一环境中的绝对路径；检查全部 JSON 和配置/脚本文本。允许公共构建根路径；个人目录和临时目录必须警告，正式交付仅在用户显式批准精确根路径后放行。
• psp.json、BSP handoff、配置接口或依赖基线不匹配时，不通过寻找近似文件、选择最新目录、静默覆盖或降低检查来继续。
• 需求和适配方案已经确认后，完整差异和打包准备检查通过即自动完成本地导入、git add、候选提交、应用工程内既有 psp 子模块更新、./product.py 和 ./release.py 0，不再请求执行确认。自动范围不包括创建或更换子模块地址、提交应用仓库、Git 上传、Etunel 交接、accepted/revoked tag、./release.py 1、设备烧录和发布。
• 自动步骤出现脏工作区重叠、仓库或 commit 不一致、子模块缺失、脚本/路径变化、检查失败、命令报错、产物不唯一或需要清理重试时立即停止。先保存证据，再请用户确认处理方式；不得自行覆盖、丢弃改动、修改应用框架或改用 ./release.py 1。
• 同一阻塞条件没有变化时，不重复发整套问题。只说明缺少的证据、它阻止哪一步，以及由谁补充。
• 输出警告时按“阻止继续”“需要确认”“暂不影响当前步骤”分组；目标机路径在主机不存在、ISP/PQ 待用户更新等已知情况不得与真实组包错误混在一起。
• packaged、device_verified、app_integrated 和 accepted 必须引用真实证据与同一个完整 PSP commit。人工设备结果标记为 USER_REPORTED，未执行项不得写成通过。
• 完成时按记录规范和统一交付契约报告；没有有效 Etunel 上下文时只生成交接材料，不声称已发送。

确定性辅助工具

• scripts/psp/psp_project_guard.py：用 inspect 只读校验固定 PSP 根目录、项目路径和独立仓库并区分空仓库/现有项目；首次填充时受控复制到 staging，检查差异白名单与旧项目残留，验证通过后自动导入内容、复核最终目录且证明 Git 分支/远端未改变；不创建目录、不初始化仓库。
• scripts/psp/validate_hardware_topology.py：校验证据文件/hash、存储和每路 Sensor 物理事实，并用显式 config_expectations 对照唯一 sensor_cfg.ini。
• scripts/psp/analyze_psp_delta.py：同时比较目标 HEAD、目标 worktree、参考 HEAD 和参考 worktree，区分稳定参考、参考未提交改动、目标特有改动和未分类冲突。
• scripts/psp/audit_cv181x_media_ai.py：只读枚举 CV181X 精确 Media/AI Release 的全部 JSON 叶子字段、默认值/hash、源码读取位置线索，核对 SDK/ABI 标识、VPSS 图和 PSP 候选差异；不把代码命中或静态通过当成硬件正确性证明。
• scripts/psp/validate_bsp_handoff.py：校验 BSP handoff、权限证据、精确 imgs 路径和产物 hash。直接运行默认只读；PSP 已确认的适配流程自动在证据和项目身份一致时修复本次输出的 a+rX 权限并复核，失败则阻止 candidate。
• scripts/psp/validate_psp.py：校验 PSP 结构、配置语法、路径、脚本、CV18 Sensor 枚举映射和应用/PSP 覆盖关系；根据 --expected-chip 自动选择内置 CV181X/CV184X 头文件，通常无需 --sensor-enum-header。
• scripts/psp/validate_partition_closure.py：从 psp.json 推导完整分区 offset/size，逐项核对 Boot/Default 镜像值，并按 UBI LEB/PEB 与保留块校验 mkAiData.py 参数。
• scripts/psp/record_packaging_result.py：用 contract 根据 EMX2.1 固定目录和命令生成本地契约；用 preflight 在候选提交前和正式组包前检查资源来源、DATA 工具、分区字段、BSP 分区余量与应用脚本；用 snapshot/record 证明本轮唯一新增的 output/<版本>/ 及指定烧录包并记录路径、大小和 hash。工具不执行打包命令。
• scripts/psp/render_psp_handoff.py：把同一 commit 的验证证据汇总为供用户确认或 Etunel Hub 使用的交接文件，并可只读核对远端 commit；不发送消息。