matrix-screen-controller/AGENTS.md

# 奇妙小屏幕控制器（核桃派 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. 需求与测试编号

移动端是独立维护的程序，入口为 `移动端相关内容/README.md`，协作规则见 `移动端相关内容/AGENTS.md`。本轮已授权 Android 首版；未来设备端更新不得自动迭代或发布 App。设备公共接口、协议、驱动边界及部署变化必须在 `移动端相关内容/开发要求/跨端兼容与变更记录.md` 登记影响；对外契约不变的驱动内部修改不要求手机更新。App、设备及协议分别管理版本。正式 APK 签名只在用户明确命令后执行，当前只允许 debug 签名。

移动测试设备真实登记唯一位置为 `移动端相关内容/安卓app/如何安卓测试/测试设备登记/测试设备.local.json`，精确忽略；提交同目录空白 `测试设备.example.json` 和门禁脚本。此登记只存手机测试信息，不复制核桃派或开发机凭据；自动化前检查登记及 ADB 授权，不回显真实设备标识，不覆盖已有登记。

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

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

## 3. 分层验证

- 本机 mock 验证确定性业务、REST、WebSocket、配置、字体、模板、动图和前端测试。
- 核桃派无负载验证编译、寄存器映射、线程调度、双缓冲、截止统计和异常清屏；在该门槛通过前禁止接屏。
- HUB75 实屏测试按全黑、红、绿、蓝、白、四角、关键行、方向、文字、图片、动画逐项执行；上一项失败就停止，只排查对应线组。
- ADC 测试按总线、地址、原始读取、同点万用表校准、正常档、单个低压档、恢复逐项执行，不合并人工动作。
- 普通网页前端、手机界面、BLE 控制入口开发没有改变驱动或显示输出实现时，不新增实屏视觉验收；优先协议、状态、输出帧与驱动统计，不适用时记录“不适用”。
- 仅在驱动、扫描时序、底层输出变化或具体显示异常确需视觉证据时提出视觉检查。必须先停止相关步骤、说明原因、询问用户下一步如何启动，并等待本次明确指示；不得自动启动 DroidCam、摄像头、采集或视觉测试程序，也不得主动切换实屏测试图案。专用测试手机的一般自动化授权不能替代此门禁。
- 用户明确启动后，有清晰摄像头时可由 Codex 判断；画面缺失或有拍频、曝光、视角歧义时仍等待用户确认。

## 4. 人工停顿与电气安全

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

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

## 5. 网络和依赖

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

1. Debian 包优先使用已验证可达的国内镜像；修改源前记录原值和回退方法。
2. Python/C 源码或 wheel 若只有境外来源，由有 VPN 的电脑下载并校验，再上传离线安装。
3. 每个离线包保存 SHA-256 清单；板端安装使用 `--no-index --find-links` 或明确的本地路径。
4. 不关闭电脑 VPN，不把本机工具目录或盘符固化进项目文档和部署脚本。
5. SSH 后先在远端用 `command -v` 和版本命令检查工具，不能因电脑有工具就假设板端也有。
6. 普通功能开发不读取或重建大型镜像；只有用户明确要求导出镜像、维护离线材料或更新编辑器时才进入 `发布更新相关/` 的发布流程。
7. 新增或删除板端 Python、Debian 或原生命令依赖时属于功能修改的一部分：必须同步 `发布更新相关/其他依赖/` 的文件、SHA-256 和生命周期清单。停用依赖删除二进制并登记原因，不能等待下次镜像导出再补。
8. OTA 和可刷镜像共用 `核桃派软件源代码/VERSION` 与根目录 `发布记录.json`；只有明确导出成功才推进版本，失败不得占号或留下半成品目录。
9. 可部署的功能新增或优化必须同步更新 `核桃派软件源代码/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；秘密、本机状态、运行数据和可再生缓存继续按各自规则排除。

## 9. 测试经验与交付反馈

项目专用本机测试环境统一放在 `测试相关资料/如何测试/本机测试环境/.local/` 并精确忽略；不要写入全局 Codex 工具目录。可复建入口、锁定依赖、校验信息和搭建说明必须提交并随相关测试同步更新。通用工具仍按全局登记复用。复制工作区后重建 Python venv、更新本机工具配置和 AVD 路径；不得把带旧绝对路径的环境当作可移植工具。Android 必需的临时 ASCII 目录联接只用于入口，材料实际保存在项目内，清理只删除链接本身。具体命令见本机测试环境 README。

每轮测试完成后，将测试中遇到的问题及已验证解法补到对应可重复测试流程、排障指南或构建文档，防止后续重复试错；单次失败证据、恢复及重测结果留在测试归档。已知问题先查已有经验，不把未证实推测固化成根因。最终反馈说明经验更新位置和仍未解决的边界；没有新增经验时沿用已有记录，不重复复制。文档不得包含真实凭据、测试设备标识或开发机绝对路径。

## Android 按影响选测（当前规则）

每轮先评估直接和共享依赖影响，记录选测理由；测试矩阵不是每轮全量清单。未改且不受影响的页面/设置不跑真机回归。纯逻辑优先 JVM，普通 UI 优先独立模拟器；BLE、实际权限/后台厂商差异等才做必要的定向真机验证。root 授权不代表真机必测；root 输入规则仅适用于登记真机，模拟器使用标准 Compose 测试 API。必要但没做的验证不能写成不适用。切网、长轮询、性能、生命周期和全量验收均需具体影响理由，不能顺带执行。

具体触发条件、命令和证据格式见 [按影响选测](移动端相关内容/安卓app/如何安卓测试/按影响选测.md)。该规则替代历史专项“每轮执行”要求，视觉/物理操作、凭据和真机登记门禁不变。