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

name, description

name	description
firmware-lowlevel-psp-development	基于相近板卡 PSP 创建、修改和验证项目级平台配置，锁定 BSP 固件、Media 与 AIPlugin 依赖，并通过固定打包环境形成可交给应用层的精确 Git 基线。用于 PSP 配置适配、组包证据、人工设备验证和 Etunel 交接；不用于 BSP/DTS/驱动实现、应用业务、公共组件开发或未经确认的烧录、上传与发布。

固件底层开发_PSP开发

把每个硬件项目的 PSP 作为独立、轻量的配置仓库维护。PSP 固定工作区是当前用户的 ~/work/project/EMX2.1/AppTeam/Psp/；项目目录由用户或团队预先在该根目录下创建。以用户指定的相近板卡 PSP 为参考，只做目标项目所需的最小差异；PSP 的唯一身份是完整 Git commit SHA。

进入流程

1. 先读取并遵守统一的流程文档写法，所有面向人的流程文档使用简体中文和直白表达。
2. 读取统一入口的项目所有权契约、治理工作流和风险等级。
3. 读取 PSP 主工作流，确认目标项目目录是固定工作区的直接子目录，并确认参考 PSP、芯片/板卡/系统形态、BSP handoff、差异清单和负责人。目标目录不存在时停止，请用户或团队先创建；不得代为创建目录或初始化仓库。
4. 首次填充、迁移、提交或更新 PSP 仓库时，读取项目与 Git 规则。首次填充只对预创建的空独立 Git 仓库执行：先在 staging 中适配并审计，验证通过后自动导入并创建本地候选提交，同时保留 .git、分支和远端；不再为导入和提交重复询问。已有业务内容的项目转入现有项目更新流程，不得按参考复制覆盖。
5. 修改 GPIO、BSP 引用、内存/分区结果、Sensor、Media 或 AIPlugin 配置时，读取配置边界与检查。CV18 Sensor 默认按芯片系列使用 skill 内置枚举表，把规格书选型自动映射为配置名称或数值；无需临时查找 SDK 头文件。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；先核对芯片系列、系统形态、存储介质、Sensor、GPIO、媒体和 AIPlugin 能力。明显不兼容时停止，除非用户知情确认跨平台参考。
• 目标 PSP 必须位于当前用户的 ~/work/project/EMX2.1/AppTeam/Psp/<项目名>/，是该固定根目录的普通直接子目录和独立 Git 仓库。目录缺失、软链接、嵌套仓库或根目录外路径均停止；不运行 mkdir 或 git init 补齐。
• 默认继承参考 PSP，但必须分别展示修改项和关键继承项。能由参考兼容性、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_bsp_handoff.py：校验 BSP handoff、精确 imgs 路径和产物 hash。
• scripts/psp/validate_psp.py：校验 PSP 结构、配置语法、路径、脚本、CV18 Sensor 枚举映射和应用/PSP 覆盖关系；根据 --expected-chip 自动选择内置 CV181X/CV184X 头文件，通常无需 --sensor-enum-header。
• 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；不发送消息。