奇妙小屏幕控制器（核桃派 ZeroW）协作指南

本目录是可以单独拿走、独立开发和部署的核桃派项目。处理任务前先读本文件，再读 整体开发需求/、测试相关资料/如何测试/ 和与任务有关的硬件资料。本项目不得依赖外层移植目录、原树莓派工作区、旧设备配置或旧设备凭据。

1. 固定硬件和边界

主控：核桃派 ZeroW，H618，Debian 12 Server。
屏幕：单块 RGB-Matrix-P3-64x64-F，HUB75，64×64，1/32 扫描，ABCDE 行地址。
真实驱动：项目自带 walnutpi-h618-hub75 C 驱动，通过 /dev/mem 访问 H618 PI bank；不得回退或依赖 rpi-rgb-led-matrix。
ADC：M5Stack Unit ADC v1.1 / ADS1110，/dev/i2c-1，地址 0x48。
生产程序、持久数据和运行数据分别位于 /opt/matrix-screen-controller、/var/lib/matrix-screen-controller、/run/matrix-screen-controller。
当前设备和开发机凭据只保存在 测试相关资料/核桃派的用户名和密码和ip/用户名密码ip.txt，不得复制到源码、日志、普通文档或回复。正式 IMG 的发布目录 README.md 是唯一例外：它必须写明该未修改镜像内故意公开的默认账户与 Wi-Fi 四项值，并警告用户修改；不得把当前设备或开发机凭据误写为镜像默认值。

1.1 私有调试凭据门禁

测试相关资料/核桃派的用户名和密码和ip/用户名密码ip.example.txt 是可提交示例；同目录 用户名密码ip.txt 是被根 .gitignore 精确排除的唯一真实调试记录。不得把真实值写回示例。
凡 SSH、远端命令、实机部署、镜像定制、网络登录或其他需要设备身份的任务，先从仓库根目录运行 python "测试相关资料/核桃派的用户名和密码和ip/prepare_credentials.py"。不要先读取、回显或自行猜测凭据。
私有文件不存在时，准备脚本只从示例创建副本并停止。agent 必须暂停当前远端步骤，明确让用户编辑仓库相对路径 测试相关资料/核桃派的用户名和密码和ip/用户名密码ip.txt，等待用户确认后重新运行检查；不得在示例值未替换时继续。
私有文件已存在时不得覆盖、重建或格式化。检查失败只报告缺失字段名或格式问题，不输出字段值；聊天、命令行、日志、测试夹具、补丁和提交摘要中均不得出现真实值。
提交前运行 python "核桃派软件源代码/scripts/check_repository_hygiene.py"。发现真实凭据进入 Git 候选、开发机绝对路径、私钥或高可信秘密时必须停止，不得用扩大忽略范围掩盖本应修正的公开文件。

2. 需求与测试编号

WEB-*：网页、REST、WebSocket、交互和安全入口。
DISPLAY-*：显示服务、帧、方向、字体、动画、mock 与 H618 真实驱动。
CONFIG-*：schema、默认值、迁移、持久数据和损坏保护。
DEPLOY-*：编译、systemd、权限、离线部署、更新和清理。
HW-*：核桃派排针、HUB75、ADC、供电和扫描参数。
TEST-*：本机、板端无负载、实屏、ADC、重启、清理和独立性验收。

新增或改变行为时，先更新 整体开发需求/ 的稳定编号，再改 核桃派软件源代码/，最后同步 测试相关资料/如何测试/ 的映射和合格标准。

3. 分层验证

本机 mock 验证确定性业务、REST、WebSocket、配置、字体、模板、动图和前端测试。
核桃派无负载验证编译、寄存器映射、线程调度、双缓冲、截止统计和异常清屏；在该门槛通过前禁止接屏。
HUB75 实屏测试按全黑、红、绿、蓝、白、四角、关键行、方向、文字、图片、动画逐项执行；上一项失败就停止，只排查对应线组。
ADC 测试按总线、地址、原始读取、同点万用表校准、正常档、单个低压档、恢复逐项执行，不合并人工动作。
有清晰摄像头时由 Codex 判断；画面缺失或有拍频、曝光、视角歧义时必须等待用户确认。

4. 人工停顿与电气安全

任何拔卡、插卡、断电接线、上电、万用表读数或调压都必须分阶段暂停。暂停时明确当前完成项、是否断电、用户只做什么、回复什么、下一步测什么。没有用户确认，不把物理结果写成通过。

接线前核桃派和屏幕都必须断电。
HUB75 屏幕使用独立 5V 供电并与核桃派共地；不得用 GPIO 供电。
ADC 在实屏基础画面通过后才连接；不得带电插拔。
低压阶梯一次只要求一个安全档位，读完软件状态和实屏结果后才给下一档。

5. 网络和依赖

核桃派没有 VPN。板端不得默认访问 GitHub、PyPI 或其他境外服务并长时间重试。

Debian 包优先使用已验证可达的国内镜像；修改源前记录原值和回退方法。
Python/C 源码或 wheel 若只有境外来源，由有 VPN 的电脑下载并校验，再上传离线安装。
每个离线包保存 SHA-256 清单；板端安装使用 --no-index --find-links 或明确的本地路径。
不关闭电脑 VPN，不把本机工具目录或盘符固化进项目文档和部署脚本。
SSH 后先在远端用 command -v 和版本命令检查工具，不能因电脑有工具就假设板端也有。
普通功能开发不读取或重建大型镜像；只有用户明确要求导出镜像、维护离线材料或更新编辑器时才进入 发布更新相关/ 的发布流程。
新增或删除板端 Python、Debian 或原生命令依赖时属于功能修改的一部分：必须同步 发布更新相关/其他依赖/ 的文件、SHA-256 和生命周期清单。停用依赖删除二进制并登记原因，不能等待下次镜像导出再补。
OTA 和可刷镜像共用 核桃派软件源代码/VERSION 与根目录 发布记录.json；只有明确导出成功才推进版本，失败不得占号或留下半成品目录。
可部署的功能新增或优化必须同步更新 核桃派软件源代码/FEATURE_UPDATED_AT，格式固定为精确到分钟的北京时间 YYYY-MM-DDTHH:MM+08:00。单纯 OTA/镜像导出、重复部署和文档修改不得改写该时间。

6. 数据生命周期

OTA 等跨主服务停启存活的任务必须显式保护共享运行目录。RuntimeDirectoryPreserve=restart 不保留单独 systemctl stop 的目录；主服务使用 yes，旧版本在停服前通过事务临时 drop-in 保护并核验。不得只改新包内尚未生效的 unit，也不得只用 mkdir 掩盖请求/进度已丢失。运行目录仍随整机重启清空。
涉及 systemd RuntimeDirectory、停启、回滚或独立任务的修改，必须补真实 systemd 生命周期测试。模拟 systemctl 通过不能写成真实 OTA 通过。日志写入失败不能阻止恢复动作；一次性故障证据写归档，稳定测试要求写需求与测试流程。
持久数据：配置、校准、模板、动图、字体和用户资源，统一保留在 /var/lib/matrix-screen-controller。
可再生数据：缩略图等专用缓存，随持久源保存，只按登记规则清理。
运行数据：帧快照、锁、boot 标记和临时状态，统一放 /run/matrix-screen-controller。
/opt/matrix-screen-controller 只含可替换程序、venv、原生驱动和部署文件。
schema 逐级单向迁移；损坏、未知字段、未来版本或不安全迁移必须保留原文件并拒绝启动，只有文件不存在才创建默认值。

7. 真实驱动规则

14 根 HUB75 信号集中使用 PI bank；物理脚 3/5 留给 I²C，物理脚 32 保留。
C 刷新线程必须双缓冲并只在完整帧边界交换；帧格式固定 RGB888，bitplane 固定 7 bit。
默认 100 Hz，允许 15、20、30、45、60、80、100 Hz；状态必须报告实际刷新率、帧数、截止丢失数和最后错误。
刷新线程尝试 CPU3 绑定、实时优先级、内存锁定和 performance governor；能力不足必须明确报告，不能伪造优化已生效。
启动先保持 OE 禁用并清黑；异常、关闭、重建和进程退出都必须先禁用 OE、清空输出、恢复 GPIO 安全输入状态并释放映射。
正常 WebSocket 断开不得记为显示异常或在 close 后再次发送。

8. 清理和独立性

不提交 .venv、__pycache__、.pytest_cache、node_modules、运行数据、测试数据、主机密钥或历史移植临时文件。
临时部署、构建目录、wheelhouse 和临时 systemd unit 在验证后按明确绝对路径清理。
最终把本目录复制到隔离临时位置，从文档命令重新构建和运行测试；任何引用目录外文件的路径都视为失败。
一次性结果写在交付或 各种归档/<时间戳>_用途/README.md，不写进可重复测试流程。
发布更新相关/导出包/<版本>/ 是可随时删除的大型 IMG 发布产物。发现历史导出 IMG 缺失时，默认视为用户为节省空间主动删除，属于正常情况；不报缺失故障、不追补、不自动重建，也不得因此阻塞开发、常规测试或后续构建。源码、文档命令和后续构建不得引用其中任何文件。
发布更新相关/OTA数据包/ 中的 OTA 今后长期保留，不按可删除缓存清理；已缺失的 OTA 1.0.1 是用户接受的历史例外，不再追补、提醒或阻塞开发及使用。保留原发布记录，后续构建仍不得依赖历史包。
普通开发不检查历史 IMG 是否齐全；只有用户明确要求处理某个镜像时，才核对该任务实际需要的输入文件。官方基线和其他离线依赖按各自规则管理。
仓库内描述工作区文件时使用相对路径或 <仓库根目录>、<受保护临时目录> 等文字占位符，不固化盘符、Windows 用户目录、macOS 用户目录或开发者 home。核桃派上的 /opt、/var/lib、/run、/boot、/usr/local 等固定部署路径不属于此限制。
正式 IMG 通过仓库外的发行渠道保存，根 .gitignore 必须忽略所有 *.img；Git 只保留对应 README、manifest、SHA-256、发布记录等元数据，不得让源码、文档命令或后续构建依赖仓库中存在 IMG。OTA、离线依赖、编辑器程序和历史归档仍由私有 Git 仓库保留，大体积二进制可使用 Git LFS；秘密、本机状态、运行数据和可再生缓存继续按各自规则排除。

10 KiB Raw Blame History Unescape Escape