使用 DeepSeek V4.1 Flash 基于原项目做的 HarmonyOS NEXT 像素复古风mp3小应用。ᓚᘏᗢ

文件	最后提交记录	最后更新时间
AppScope	style: 应用图标修改	3 天前
docs	版本: 0.0.1.beta feature: .lrc 歌词接入播控中心、专辑cover接入播控中心（系统取图优先，失败走自带解析器，最后回落默认cover）	3 天前
entry	版本: 0.0.1.beta feature: .lrc 歌词接入播控中心、专辑cover接入播控中心（系统取图优先，失败走自带解析器，最后回落默认cover）	3 天前
hvigor	Initial commit - 项目定位 - 把 ESP32-S3 + 128x64 单色 OLED 上的 osu!mc（osu!lazer 仿制 UI）1:1 重建为 HarmonyOS ArkTS 应用 - 只复刻界面、全部动画与交互；Wi-Fi / HTTP / System Info 用假数据填充 - 屏幕不改用原生 ArkUI 组件重写，而是自建 1-bit 帧缓冲 → Canvas 逐像素 → 最近邻放大 - 屏幕与渲染 - 128x64 / 1 bit 的 FrameBuffer，支持清屏、像素置位、按行 ASCII 输出 - Canvas = surface + 裁剪区 + 原点，within() / translate() 以值传递，坐标均为局部坐标 - Surface 原语：SetPixel / FillRect / InvertRect / InvertRoundRect - DrawGlyph 按 MSB-first 连续位流取样；InvertRoundRect 用整数开方还原圆角 - 字体 - 内嵌 tinyfont notosans12pt 点阵表（0x20..0x7E），含 BBox / YAdvance 与每字形度量 - tools/exportfont 从 tinyfont v0.7.0 导出 ArkTS 常量表，可复现 - Font 度量与单字形绘制与 Go 版逐字形一致 - 动画 - Value：指数平滑与阻尼弹簧两种运动，常量与 Go 版一致（settleEpsilon、springSettlePos/Vel、springStep、e） - Manager / Default：所有值注册后每帧推进一次并回报是否变化 - 支持 Kick 初速、Snap 立即到位、Jump 无动画赋值 - UI 基础 - Element 基类：把 Go 的可选能力接口改写为基类方法 + 能力标志（handleEvent / interceptEvent / focused / onEnter / onLeave / release / isFocusable / focusRect / isSeeker / focusNear / setLiveFocus / setMarquee / scrollTo / holds / isFocuser 等） - Rect / RectF / AnimatedRect：矩形四边各一个 Value，先取整两边再相减以避免移动时宽度抖动 - Router：捕获 + 冒泡，按下者独占该键的 Repeat / Release，maxDepth = 16 - 事件三态 Press / Repeat / Release，Fires() = Repeat \|\| (Release && !Repeated) - Cursor：反色圆角矩形，四边独立缩放（Lead 28 / Trail 12），按下内缩、Leap、按压回弹 - Nav：列表边界的 lean / pull、级联拖尾、页面进出方向与 Kick - UI 组件 - ItemBase（原 seq）：ListItem 公共基类，承载选中 / 增删项 / 拉拽 / 级联 / 波浪 - List：垂直列表 + 滚动条（细线 1px / 宽线 3px、静止变细、轨迹点），Gap / Stagger / Cascade / Centered 等常量对齐 - Row：水平列表，本身就是 ListItem，仅水平方向裁剪 - Text：超宽文本 marquee（停 1s、24px/s、缓回），LiveFocus 轴，Center / Static - TextView：整页长文 + 双向滚动条 + 换行与锚点重排 - Input / Select / Checkbox / Chip / Choice / Toggles - Keyboard：三层键位（字母 / 数字 / 符号），文本字段 + 闪烁光标 + 打字 / 退格弹跳 - Viewer：页面栈（五态）、返回 peek、pop 后 release - 应用层页面 - Launcher：居中标题 + Settings / Lorem Ipsum / HTTP Client / System Info，弧形缩进 + 滚动条 - Settings：Wi-Fi / Screen off / About - Wi-Fi：状态、IP、扫描 / 重扫（每 15s 自动重扫），同名合并取最强、隐藏网络过滤，选中 AP 弹密码键盘连接 - Lorem Ipsum：搜索框（ASCII 大小写不敏感跳转）、10 首歌 + 难度列表 + Reader - Options：Mods 多选 / 倍速单选 / 操作行，Gap = 0 无缩进 - HTTP Client：URL 输入、GET、快捷方式增删改与响应页 - System Info：分组信息 + 每秒刷新的 Loop / Draw / Load - MockServices：MockWiFi / MockHTTP / MockPower / MockSystem 复刻固件的每秒统计 - 主循环与输入 - pages/Index.ets：displaySync 驱动、dt 用真实时间并上限 0.1s、仅在变化时重绘与上传 - 按键去抖 + 重复加速（0.2s 后开始、0.07s 起、每次 x0.9、最快 0.03s） - 关屏 / 唤醒：面板停更，唤醒键被吞，避免误触发确认 / 返回 - 7 键外壳：UP / DOWN / LEFT / RIGHT / MID / SET / RST，资源与 $r 引用并支持黑色主题 - 工程外壳 - Stage 模型 + ArkTS，bundleName = cn.forforio.osumchmos - build-profile.json5 含自动生成的调试签名配置（product = default） - code-linter.json5 / hvigorfile.ts / oh-package 配置齐备 - 资源 - base 与 dark 两套 color.json，国际化字符串（base 及多语言） - 应用名、启动图标、7 个按键标签等均走 $r 资源引用 - 文档与工具 - AGENTS.md：项目总览、五条核心设计思路、文件作用速查、常量总表、里程碑 - docs/harmonyos-port-plan.md：逐文件映射、逐函数要点、验证方法 - tools/exportfont：字体点阵导出工具 - 验证 - 已通过 devecocli check arkts 与构建，并在真机（HUAWEI Mate 60 Pro）安装启动 - 与 Go 版黄金帧逐行 ASCII 比对：Launcher / Settings / About / Lorem / 难度 / Options / HTTP 完全一致 - 真机核验：System Info 每秒刷新、关屏与唤醒、RST 回根页、Wi-Fi 扫描 / 密码键盘 / 连接 - 键盘页唯一差异为 caretBlinkPeriod 的闪烁相位（时间对齐问题，非缺陷）	7 天前
tools	docs	3 天前
.gitignore	应用外壳：Navigation + 系统路由表、应用设置页、MVVM 数据分层、沉浸式 - 导航（pages/Index.ets） - 首页改为 HdsNavigation 根页（NavigationMode.Stack），标题栏不带标题文字，只保留右侧设置菜单，保证横屏时不挤占内容宽度 - 子页面改走系统路由表（resources/base/profile/router_map.json + common/RouteName.ets），用 pushPathByName 跳转；main_pages.json 只保留 Index - Mini 模式默认显示返回按钮，首页显式 hideBackButton(true)；@Entry 的 build 根节点外套一层最轻的 Column（编译器不把 HdsNavigation 视为容器） - 标题栏滚动模糊绑定滚动容器（bindToScrollable），随滚动距离线性变化 - 首页方向 / 确认 / 复位键改用系统沉浸材质 .systemMaterial(...)，强度随设置 - 设置页（pages/SettingsPage.ets，路由 Settings） - 五组卡片：外观（跟随系统 / 浅色 / 深色）、标题栏模糊（无 / 通用 / 过渡 / 渐变 / 沉浸）、沉浸光感（关闭 / 弱 / 中 / 强）、屏幕旋转（跟随系统 / 仅竖屏 / 仅横屏 / 锁定当前）、关于（版本号取自 bundleManager，不硬编码） - 对照参考项目 MiniGames 的设置页：除邮箱（联系）外，其余条目全部具备且功能一致 - 卡片底色不用参考项目的蓝灰，改为浅灰 #E8EAED / 深灰 #2A2A2A（新增 color 资源 settings_card_bg） - 分段控件用原生 SegmentButton 并保持系统默认配色，封装为 components/SegmentedControl.ets（只暴露 key 维度的 options / selectedKey / onSelect） - 原生组件（分段控件、List 边缘回弹）保持系统默认行为，不做配色覆盖；外壳文案与颜色统一走 $r - 数据分层（MVVM，为 SQLite 预留） - settings/AppSettings.ets：Model（四个选项枚举 + AppSettings + SettingsKeys + ChoiceOption） - settings/KeyValueStore.ets：通用 KV 接口 + PreferencesKeyValueStore（首选项文件 osu_mc_store）+ MemoryKeyValueStore；接口不含任何「设置」语义，可被任意业务复用 - settings/SettingsRepository.ets：仓库接口 + KeyValueSettingsRepository（字段 ↔ main_ 前缀 KV 键，含字符串→枚举的容错解析）+ createSettingsRepository 装配工厂 - settings/SettingsViewModel.ets：编排读写、publish 到 AppStorage、系统生效；create(context) 为唯一装配点 - settings/DisplayController.ets：深浅色模式（setColorMode）、屏幕方向（setPreferredOrientation）、状态栏文字颜色 - 持久化走 Preferences，运行时快照放 AppStorage；页面用 @State / @StorageLink 订阅 - 以后换 SQLite 只需新增 RdbKeyValueStore 并改 createSettingsRepository 一行装配 - 沉浸式（组件级方案，不做窗口级全屏） - 各页面背景用 expandSafeArea([SYSTEM], [TOP, BOTTOM]) 延伸到状态栏 / 导航条，视觉不断层 - common/TitleBarUtil.ets：Hds 标题栏样式（滚动模糊 ScrollEffectType + 沉浸光感 hdsMaterial + 配色 originalStyle / scrolledStyle），首页与设置页共用 - common/MaterialUtil.ets：沉浸光感强度 → uiMaterial 系统材质；强度为「关闭」时返回 undefined，组件回退自身纯色背景 - common/AppTheme.ets 集中外壳间距 / 圆角 / 时长常量；common/ContextUtil.ets 从 UIContext 取宿主 Context - EntryAbility：启动恢复深浅色模式与屏幕方向，onConfigurationUpdate 刷新状态栏字色 - 资源与文案 - base/element/string.json 新增设置页文案；新增 resources/en_US/element/string.json 英文文案 - base 与 dark 两套 color.json 新增 settings_card_bg - base/element/float.json 新增 app_font_section / app_font_body / app_font_caption - module.json5 注册 routerMap（未新增权限） - 文档 - 新增 docs/arkui-app-guide.md：与移植无关的 ArkUI 应用外壳指南（导航与系统路由表、设置页、MVVM 分层与 SQLite 预留、沉浸式四层方案、强度映射表、主题资源约定、扩展指引、已知边界） - README.md 新增「应用外壳」章节与文档导航条目；目录结构补充 common / components / settings 并区分两个 Settings；构建章节写明 SDK 版本与原因；验证章节补充外壳核对项 - AGENTS.md 文档索引补充应用外壳指南，环境章节提示不要调低 compatibleSdkVersion - .gitignore 忽略 /.vscode - 工程说明 - build-profile.json5 的 compatibleSdkVersion / targetSdkVersion 提升到 26.0.0（沉浸光感所用的 uiMaterial / systemMaterial 自 API 26 起提供）；该文件含明文调试签名，本次不提交 - 验证 - devecocli check arkts 无错误；devecocli build 成功且零 ArkTS 告警 - 真机（HUAWEI Mate 60 Pro / API 26）核验：首页标题栏无文字 + 设置菜单、系统路由表跳转与返回、设置页五张卡片与分段控件、深浅色 / 屏幕旋转 / 沉浸光感 / 标题栏模糊即时生效、杀掉进程重启后设置仍保留	7 天前
AGENTS.md	style: 曲目信息-歌词路径展示	3 天前
LICENSE	docs: 补充 MIT LICENSE 以及原作者信息（感谢大佬开源 ᓚᘏᗢ ）	6 天前
README.md	feature: .lrc 歌词初步支持	3 天前
build-profile.json5	docs	5 天前
code-linter.json5	代码整理：删除死代码与模板残留、消除重复实现、拆分 pages/Index.ets、Services 接口接缝、补 LocalUnit 单测 - 死代码与模板残留 - animation/Value.ets：删除 newValue() / newSpring()（原项目 animation.New / NewSpring 定义后从未被调用） - ui/TextView.ets：删除 scrollTargetX() / scrollTargetY()（原项目 TextView 只有 Scroll()，无对应物；lineCount() / line() 对应 Lines() / Line(i)，保留） - preferences/SettingsViewModel.ets：删除 previewScreenScale()（设置页拖动路径已不再调用它） - resources/base/element/float.json：删除模板残留的 page_text_font_size（50fp） - ui/Canvas.ets：isqrt 注释由「逐位逼近」改为「从 0 起试探」，与原项目实现一致 - oh-package.json5 / entry/oh-package.json5：description 由模板文案改为项目说明 - code-linter.json5：删除不存在的 /src/mock//* 忽略项 - 保留 newMockServices()（原项目同样有装配代码），并在 Index 接线；保留 FrameBuffer.toString() / Element.Group / Select.setOptions / Cursor.isPressed（原项目测试在用） - 命名与可见性 - entry/src/main/ets/settings/ → preferences/（git mv 保留历史）：避免与复刻层的 application/Settings.ets 混淆；更新 6 个文件 10 处 import - application/SysInfo.ets：a 与全部状态字段改 private（原项目字段均未导出） - 消除重复实现 - preferences/AppSettings.ets：新增 parseColorMode / parseRotation / parseTitleBlur / parseMaterial / parseScreenScale（字符串 → 枚举的容错解析，仓库与 UI 回调共用一处） - preferences/SettingsRepository.ets：删除私有 to（5 个），load() 改调 parse - preferences/SettingsViewModel.ets：删除 parse（5 个）；pages/SettingsPage.ets 改为直接调用 parse - preferences/AppSettings.ets：新增 materialRank()（强度 → 0..3 档位）；common/MaterialUtil.ets 与 common/TitleBarUtil.ets 改为按档位查表，去掉两套 if 链 - 拆分 pages/Index.ets（663 → 359 行） - 新增 screen/Shell.ets：Shell 类（帧缓冲 / Canvas / 页面栈 / 路由 / 按键 / 主循环 / 关屏）+ MAX_FPS / MAX_FRAME_DT / SLEEP_POLL_MS - 新增 screen/ScalePolicy.ets：DEFAULT_SCALE + 竖屏 / 横屏四个窗口比例 + chooseScale() + defaultDisplay() - pages/Index.ets：只留外壳（状态、@Builder、build()、按键排版常量）；@Entry struct Index 的名字与 pages/Index 路径未变 - Services 接口接缝（Shell 不再依赖具体 Mock 实现） - application/Services.ets：Power 新增 takeOff()（screenOff 只举请求，主循环每帧取出并清除）；SystemService 新增 frame() / pause() - application/MockServices.ets：MockPower.off 改私有并实现 takeOff() - screen/Shell.ets：改为持有 Power \| null / SystemService \| null，构造时接收 Services；关屏与统计在能力缺失时直接跳过 - pages/Index.ets：改用 newMockServices() 装配（不再手工 new Services()） - 其它修复 - pages/Index.ets：按键区宽度由固定 278vp 改为「上限」——宽度撑满 + constraintSize({maxWidth})，三键横排用 SpaceBetween（标准宽度下与 KEY_GAP 等价），窗口更窄时间距自动压缩而不是溢出 - pages/Index.ets：refreshScreenScale() 显式调用 Shell.setScale()，不再依赖「画布尺寸变化 → onReady」这条隐式路径 - entryability/EntryAbility.ets：抽出 loadSettings()（惰性读一次 + 缓存），onCreate 与 onWindowStageCreate 复用，并给 applyRotation 补失败保护 - application/App.ets：修正 Job 注释（setTimeout(…, 0) 不是另一个线程，只是挪到下一个事件循环任务）；新增 startAsync(f: () => Promise<T>) 接真正的异步 API - entry/src/main/module.json5：deviceTypes 补 tablet / 2in1（代码本就有横屏与折叠屏 enableHoverMode 处理） - ui/Item.ets：Rect 合并到顶部 import，删除重复的 Canvas as UiCanvas，drawIn() 的内联 import('./Geometry').Rect 改为 Rect - 测试 - 新增 entry/src/test/（LocalUnit + hypium）：List.test.ets（套件入口）、Animation.test.ets（round 半数远离零 / expNeg 近似 e^-x / 弹簧收敛与超大 dt 不发散）、Render.test.ets（帧缓冲尺寸与像素往返 / toString 的 128×64 '#'/'.' 格式 / Canvas 裁剪 / invertRoundRect 角落缩进 2,1,0 / 字体度量单调） - ⚠️ 黄金帧语料 + 离线比对 harness 仍未入库：需从原项目 internal/ui/_test.go 的 TestRender 导出期望 ASCII 并复现场景，列为后续 TODO - 文档 - README.md：目录结构（settings/ → preferences/、screen/ 补 Shell 与 ScalePolicy）、验证章节补 LocalUnit 测试与黄金帧现状 - AGENTS.md：§0 目录改名、§4 主循环改指 screen/Shell.ets 并注明「硬件能力只从 Services 接口取」、§7 的 M7 补 LocalUnit 测试 - docs/arkui-app-guide.md：目录树与分层图改为 preferences/；起始页倍数联动改为「显式调用 Shell.setScale()」；删除 previewScreenScale 的说明 - docs/harmonyos-port-plan.md：§18.5 / §18.6 / §18.7 更新实际形态（Shell 拆出、Services 装配、preferences 改名、LocalUnit 与 lint 现状）；文件映射表与目录树补 screen/Shell.ets 与 screen/ScalePolicy.ets - 验证 - devecocli check arkts 无错误（49 → 51 files）；entry/src/test/*.test.ets 单独检查通过 - devecocli build BUILD SUCCESSFUL（entry/build/default/outputs/default/entry-default-signed.hap） - 未上真机：动画观感、按键手感、关屏 / 唤醒吞键、横竖屏切换仍需手工核验 - 本机 devecocli check lint 始终报 Files checked: 0（lint 引擎在该环境不生效），需在 DevEco Studio 内运行注：build-profile.json5 的签名配置含本机绝对路径与加密口令，未纳入本次提交。	6 天前
hvigorfile.ts	init: 全新mp3分支	6 天前
oh-package-lock.json5	Initial commit - 项目定位 - 把 ESP32-S3 + 128x64 单色 OLED 上的 osu!mc（osu!lazer 仿制 UI）1:1 重建为 HarmonyOS ArkTS 应用 - 只复刻界面、全部动画与交互；Wi-Fi / HTTP / System Info 用假数据填充 - 屏幕不改用原生 ArkUI 组件重写，而是自建 1-bit 帧缓冲 → Canvas 逐像素 → 最近邻放大 - 屏幕与渲染 - 128x64 / 1 bit 的 FrameBuffer，支持清屏、像素置位、按行 ASCII 输出 - Canvas = surface + 裁剪区 + 原点，within() / translate() 以值传递，坐标均为局部坐标 - Surface 原语：SetPixel / FillRect / InvertRect / InvertRoundRect - DrawGlyph 按 MSB-first 连续位流取样；InvertRoundRect 用整数开方还原圆角 - 字体 - 内嵌 tinyfont notosans12pt 点阵表（0x20..0x7E），含 BBox / YAdvance 与每字形度量 - tools/exportfont 从 tinyfont v0.7.0 导出 ArkTS 常量表，可复现 - Font 度量与单字形绘制与 Go 版逐字形一致 - 动画 - Value：指数平滑与阻尼弹簧两种运动，常量与 Go 版一致（settleEpsilon、springSettlePos/Vel、springStep、e） - Manager / Default：所有值注册后每帧推进一次并回报是否变化 - 支持 Kick 初速、Snap 立即到位、Jump 无动画赋值 - UI 基础 - Element 基类：把 Go 的可选能力接口改写为基类方法 + 能力标志（handleEvent / interceptEvent / focused / onEnter / onLeave / release / isFocusable / focusRect / isSeeker / focusNear / setLiveFocus / setMarquee / scrollTo / holds / isFocuser 等） - Rect / RectF / AnimatedRect：矩形四边各一个 Value，先取整两边再相减以避免移动时宽度抖动 - Router：捕获 + 冒泡，按下者独占该键的 Repeat / Release，maxDepth = 16 - 事件三态 Press / Repeat / Release，Fires() = Repeat \|\| (Release && !Repeated) - Cursor：反色圆角矩形，四边独立缩放（Lead 28 / Trail 12），按下内缩、Leap、按压回弹 - Nav：列表边界的 lean / pull、级联拖尾、页面进出方向与 Kick - UI 组件 - ItemBase（原 seq）：ListItem 公共基类，承载选中 / 增删项 / 拉拽 / 级联 / 波浪 - List：垂直列表 + 滚动条（细线 1px / 宽线 3px、静止变细、轨迹点），Gap / Stagger / Cascade / Centered 等常量对齐 - Row：水平列表，本身就是 ListItem，仅水平方向裁剪 - Text：超宽文本 marquee（停 1s、24px/s、缓回），LiveFocus 轴，Center / Static - TextView：整页长文 + 双向滚动条 + 换行与锚点重排 - Input / Select / Checkbox / Chip / Choice / Toggles - Keyboard：三层键位（字母 / 数字 / 符号），文本字段 + 闪烁光标 + 打字 / 退格弹跳 - Viewer：页面栈（五态）、返回 peek、pop 后 release - 应用层页面 - Launcher：居中标题 + Settings / Lorem Ipsum / HTTP Client / System Info，弧形缩进 + 滚动条 - Settings：Wi-Fi / Screen off / About - Wi-Fi：状态、IP、扫描 / 重扫（每 15s 自动重扫），同名合并取最强、隐藏网络过滤，选中 AP 弹密码键盘连接 - Lorem Ipsum：搜索框（ASCII 大小写不敏感跳转）、10 首歌 + 难度列表 + Reader - Options：Mods 多选 / 倍速单选 / 操作行，Gap = 0 无缩进 - HTTP Client：URL 输入、GET、快捷方式增删改与响应页 - System Info：分组信息 + 每秒刷新的 Loop / Draw / Load - MockServices：MockWiFi / MockHTTP / MockPower / MockSystem 复刻固件的每秒统计 - 主循环与输入 - pages/Index.ets：displaySync 驱动、dt 用真实时间并上限 0.1s、仅在变化时重绘与上传 - 按键去抖 + 重复加速（0.2s 后开始、0.07s 起、每次 x0.9、最快 0.03s） - 关屏 / 唤醒：面板停更，唤醒键被吞，避免误触发确认 / 返回 - 7 键外壳：UP / DOWN / LEFT / RIGHT / MID / SET / RST，资源与 $r 引用并支持黑色主题 - 工程外壳 - Stage 模型 + ArkTS，bundleName = cn.forforio.osumchmos - build-profile.json5 含自动生成的调试签名配置（product = default） - code-linter.json5 / hvigorfile.ts / oh-package 配置齐备 - 资源 - base 与 dark 两套 color.json，国际化字符串（base 及多语言） - 应用名、启动图标、7 个按键标签等均走 $r 资源引用 - 文档与工具 - AGENTS.md：项目总览、五条核心设计思路、文件作用速查、常量总表、里程碑 - docs/harmonyos-port-plan.md：逐文件映射、逐函数要点、验证方法 - tools/exportfont：字体点阵导出工具 - 验证 - 已通过 devecocli check arkts 与构建，并在真机（HUAWEI Mate 60 Pro）安装启动 - 与 Go 版黄金帧逐行 ASCII 比对：Launcher / Settings / About / Lorem / 难度 / Options / HTTP 完全一致 - 真机核验：System Info 每秒刷新、关屏与唤醒、RST 回根页、Wi-Fi 扫描 / 密码键盘 / 连接 - 键盘页唯一差异为 caretBlinkPeriod 的闪烁相位（时间对齐问题，非缺陷）	7 天前
oh-package.json5	代码整理：删除死代码与模板残留、消除重复实现、拆分 pages/Index.ets、Services 接口接缝、补 LocalUnit 单测 - 死代码与模板残留 - animation/Value.ets：删除 newValue() / newSpring()（原项目 animation.New / NewSpring 定义后从未被调用） - ui/TextView.ets：删除 scrollTargetX() / scrollTargetY()（原项目 TextView 只有 Scroll()，无对应物；lineCount() / line() 对应 Lines() / Line(i)，保留） - preferences/SettingsViewModel.ets：删除 previewScreenScale()（设置页拖动路径已不再调用它） - resources/base/element/float.json：删除模板残留的 page_text_font_size（50fp） - ui/Canvas.ets：isqrt 注释由「逐位逼近」改为「从 0 起试探」，与原项目实现一致 - oh-package.json5 / entry/oh-package.json5：description 由模板文案改为项目说明 - code-linter.json5：删除不存在的 /src/mock//* 忽略项 - 保留 newMockServices()（原项目同样有装配代码），并在 Index 接线；保留 FrameBuffer.toString() / Element.Group / Select.setOptions / Cursor.isPressed（原项目测试在用） - 命名与可见性 - entry/src/main/ets/settings/ → preferences/（git mv 保留历史）：避免与复刻层的 application/Settings.ets 混淆；更新 6 个文件 10 处 import - application/SysInfo.ets：a 与全部状态字段改 private（原项目字段均未导出） - 消除重复实现 - preferences/AppSettings.ets：新增 parseColorMode / parseRotation / parseTitleBlur / parseMaterial / parseScreenScale（字符串 → 枚举的容错解析，仓库与 UI 回调共用一处） - preferences/SettingsRepository.ets：删除私有 to（5 个），load() 改调 parse - preferences/SettingsViewModel.ets：删除 parse（5 个）；pages/SettingsPage.ets 改为直接调用 parse - preferences/AppSettings.ets：新增 materialRank()（强度 → 0..3 档位）；common/MaterialUtil.ets 与 common/TitleBarUtil.ets 改为按档位查表，去掉两套 if 链 - 拆分 pages/Index.ets（663 → 359 行） - 新增 screen/Shell.ets：Shell 类（帧缓冲 / Canvas / 页面栈 / 路由 / 按键 / 主循环 / 关屏）+ MAX_FPS / MAX_FRAME_DT / SLEEP_POLL_MS - 新增 screen/ScalePolicy.ets：DEFAULT_SCALE + 竖屏 / 横屏四个窗口比例 + chooseScale() + defaultDisplay() - pages/Index.ets：只留外壳（状态、@Builder、build()、按键排版常量）；@Entry struct Index 的名字与 pages/Index 路径未变 - Services 接口接缝（Shell 不再依赖具体 Mock 实现） - application/Services.ets：Power 新增 takeOff()（screenOff 只举请求，主循环每帧取出并清除）；SystemService 新增 frame() / pause() - application/MockServices.ets：MockPower.off 改私有并实现 takeOff() - screen/Shell.ets：改为持有 Power \| null / SystemService \| null，构造时接收 Services；关屏与统计在能力缺失时直接跳过 - pages/Index.ets：改用 newMockServices() 装配（不再手工 new Services()） - 其它修复 - pages/Index.ets：按键区宽度由固定 278vp 改为「上限」——宽度撑满 + constraintSize({maxWidth})，三键横排用 SpaceBetween（标准宽度下与 KEY_GAP 等价），窗口更窄时间距自动压缩而不是溢出 - pages/Index.ets：refreshScreenScale() 显式调用 Shell.setScale()，不再依赖「画布尺寸变化 → onReady」这条隐式路径 - entryability/EntryAbility.ets：抽出 loadSettings()（惰性读一次 + 缓存），onCreate 与 onWindowStageCreate 复用，并给 applyRotation 补失败保护 - application/App.ets：修正 Job 注释（setTimeout(…, 0) 不是另一个线程，只是挪到下一个事件循环任务）；新增 startAsync(f: () => Promise<T>) 接真正的异步 API - entry/src/main/module.json5：deviceTypes 补 tablet / 2in1（代码本就有横屏与折叠屏 enableHoverMode 处理） - ui/Item.ets：Rect 合并到顶部 import，删除重复的 Canvas as UiCanvas，drawIn() 的内联 import('./Geometry').Rect 改为 Rect - 测试 - 新增 entry/src/test/（LocalUnit + hypium）：List.test.ets（套件入口）、Animation.test.ets（round 半数远离零 / expNeg 近似 e^-x / 弹簧收敛与超大 dt 不发散）、Render.test.ets（帧缓冲尺寸与像素往返 / toString 的 128×64 '#'/'.' 格式 / Canvas 裁剪 / invertRoundRect 角落缩进 2,1,0 / 字体度量单调） - ⚠️ 黄金帧语料 + 离线比对 harness 仍未入库：需从原项目 internal/ui/_test.go 的 TestRender 导出期望 ASCII 并复现场景，列为后续 TODO - 文档 - README.md：目录结构（settings/ → preferences/、screen/ 补 Shell 与 ScalePolicy）、验证章节补 LocalUnit 测试与黄金帧现状 - AGENTS.md：§0 目录改名、§4 主循环改指 screen/Shell.ets 并注明「硬件能力只从 Services 接口取」、§7 的 M7 补 LocalUnit 测试 - docs/arkui-app-guide.md：目录树与分层图改为 preferences/；起始页倍数联动改为「显式调用 Shell.setScale()」；删除 previewScreenScale 的说明 - docs/harmonyos-port-plan.md：§18.5 / §18.6 / §18.7 更新实际形态（Shell 拆出、Services 装配、preferences 改名、LocalUnit 与 lint 现状）；文件映射表与目录树补 screen/Shell.ets 与 screen/ScalePolicy.ets - 验证 - devecocli check arkts 无错误（49 → 51 files）；entry/src/test/*.test.ets 单独检查通过 - devecocli build BUILD SUCCESSFUL（entry/build/default/outputs/default/entry-default-signed.hap） - 未上真机：动画观感、按键手感、关屏 / 唤醒吞键、横竖屏切换仍需手工核验 - 本机 devecocli check lint 始终报 Files checked: 0（lint 引擎在该环境不生效），需在 DevEco Studio 内运行注：build-profile.json5 的签名配置含本机绝对路径与加密口令，未纳入本次提交。	6 天前

osu!mp3 for HarmonyOS（osu-mc-hmos-mp3）

一个复古 ESP32 风格的 MP3 播放器，跑在 HarmonyOS 上。

界面沿用单片机小项目 osu!mc （TinyGo + ESP32-S3 + 128×64 单色 OLED，界面仿 osu!(lazer)）的屏幕与外壳，但屏幕里装的不再是假数据，而是一个真正能用的播放器：

真实文件：通过鸿蒙文件管理导入音频（「导入音频…」列出本地所有音频；「添加文件夹…」递归扫描目录），曲库用 SQLite 持久化，重启后完整恢复。
真实播放：AVPlayer 解码，播放 / 暂停 / 上下曲 / 进度拖动 / 倍速（0.5×–3.0×）/ 随机 / 单曲循环 / 列表循环。
真实后台：后台长时任务 + AVSession——切后台、锁屏、耳机线控、播控中心都能控制。
真实元数据：标题 / 艺术家 / 专辑 / 格式 / 时长 / 大小，完整信息进「曲目信息」子页。
真实歌词：.lrc（UTF-8 / GBK / UTF-16）同名自动匹配或手动选文件；歌词页跟随播放逐句滚动，用户上下翻看后 3 秒自动回位，MID 可跳到某一句。
真实播放列表：收藏（内置列表）+ 自建列表 + 队列 + 最近播放，全部持久化。
接管系统媒体音量：屏幕音量条读的是手机真实媒体音量，物理音量键改动会同步；应用内 ± 经系统音量面板生效。
真实数据：系统信息页的 循环 / 绘制 / 占用 是主循环真实帧率，播放信息 是真实播放状态。
中英双语：外壳与屏幕各自独立的语言开关。

屏幕仍是软件光栅化（自建 1-bit 帧缓冲 → Canvas 逐像素 → 最近邻整数倍放大），外壳仍是 ArkUI 原生组件 + 状态管理 V2。

文档导航

本文件只提供整个项目的缩略图；具体内容在下面的专属文档里。

文档	面向谁	内容
本文件	人（入门）	项目是什么、长什么样、页面与按键、构建运行、目录结构
`docs/project-guide.md`	所有人	整个项目的详细说明：分层、播放引擎、曲库、搜索、双语、验证、边界
`AGENTS.md`	改代码的 AI	工作准则、屏幕引擎要点、实现坑、常量、文档指针
`docs/screen.md`	改屏幕的人	渲染链路、动画、UI 模型、事件、主循环、屏幕页面、文案规范、常量
`docs/arkui-app-guide.md`	改外壳的人	Navigation 与系统路由表、设置页、MVVM、沉浸式、按键振动、主题资源
`docs/harmonyos-media-api-notes.md`	写媒体代码的人	AVPlayer / AVSession / 长时任务 / picker / fs / 授权 / SQLite 的精确签名与实测坑
`docs/chinese-fonts.md`	改中文字体的人	两套中文字形表、覆盖率、许可、生成链、切换步骤
`docs/lyrics-plan.md`	改歌词功能的人	`.lrc` 解析 / 读取 / 解码、歌词页与跟随状态机的完整方案
`docs/p15-media-source-research.md`	查导入方式的人	音频来源与导入方式的调研结论（权限矩阵、SD 卡、拼音 API）
`docs/mp3-refactor-plan.md`	接手后续工作的人	尚未完成的事项（真机回归、双语验证、溢出优化）
`docs/harmonyos-port-plan.md`	核对屏幕像素细节的人	与原 osu!mc 的逐文件映射、逐类要点、全部常量（参考资料）

它长什么样

屏幕：128×64、1 bit/像素、固定黑底白字（OLED 语义），不走 ArkUI 主题。自建帧缓冲逐像素绘制，再按窗口可用的最大整数倍最近邻放大（128×64 → 例如 6× 即 768×384 px）。放大倍数上限可在应用设置页调整。 只能是整数倍：非整数倍会让最近邻放大把源像素摊成大小不一的方块（肉眼即"帧错位"）。
外壳：应用标题与 7 个按键是 ArkUI 原生控件，文案走 $r，深浅两套主题；按键按下会振动一次（强度可调）。

屏幕内的页面

页面	内容
Launcher（根页）	标题 `osu!mp3`；入口：`正在播放` / `音乐库` / `播放列表` / `设置` / `系统信息`
音乐库	`导入音频…` / `添加文件夹…` / `文件夹 (n)` / `搜索…` / `管理曲库…` / `共 N 首` / 曲目列表
搜索	屏幕键盘（`[拼音首字母/英文]`）→ 结果页（`搜索结果` / 输入行 / `共 N 首` / 匹配曲目）
正在播放	曲名 - 艺术家 / 时间 / 进度条 / 上一首·播放暂停·下一首 / `-15s` `+15s` / 循环 / 随机 / 倍速 / 收藏 / `队列 (N)` / `歌词` / `曲目信息`
播放列表	`队列 (N)` / `收藏 (N)` / `最近播放 (N)` / `新建播放列表…` / `我的列表 (n)` + 自建列表 / `清空曲库`
设置（屏内）	循环 / 随机 / 倍速 / 音量（接管系统媒体音量）/ 语言 / 关闭屏幕 / 关于
系统信息	芯片 / 内存 / 固件（模拟 ESP32 数据）、主循环（真实帧率）、播放信息（真实播放状态）
子页	歌词、曲目操作、曲目信息、文件夹管理、文件夹操作、播放列表详情、批量管理、播放列表勾选、曲目多选、命名（屏幕键盘）、二次确认

屏幕内所有页面都是 List + ListItem：一页一个 List，一行一个 ListItem。屏幕文案走 application/Lang.ets 的双语表（中英成对），长标题自动走马灯。逐页细节见 docs/screen.md §6。

屏幕下方的 7 个按键

这 7 个按钮是 ArkUI 原生按钮，模拟真机的 6 个按键 + 1 个复位键外壳，映射关系与原项目 cmd/osu-mc/osu-mc.go 一致。

排布（竖屏，屏幕正下方）：

   [ RST ]      [ ? ]      [ SET ]     ← RST 在左 / 按键说明在中间 / SET 在右
                 [ UP ]
        [ LEFT ]  [ MID ]  [ RIGHT ]    ← 十字键
                [ DOWN ]

横屏改为左右排：左栏标题 + 屏幕，右栏按键，各占一半宽度并垂直居中。

先说结论：MID 是确认、SET 是返回、RST 是回主页。

键	说明
UP / DOWN	列表选择上下移动；到边界继续按住会让内容 + 游标反向偏移 6px，松开弹回
LEFT	横向行左移 / 进度条快退；行首再按会返回上一页（「正在播放」页例外，永不返回）
RIGHT	横向行右移 / 进度条快进；曲目行进入「曲目操作」
MID	确认：打开页面、播放 / 暂停、键盘按键、提交输入
SET	返回：按住页面右移 8px peek，松开才 pop
RST	回主页：`popToRoot()`，一次弹到栈底（不重启芯片）

确认 / 返回 / 打开键盘都在松开时执行；按下只给反馈（游标倾斜 / 挤压、页面 peek）。
关屏后任意键唤醒，唤醒的那次按键被吞掉，不会顺带确认或返回。
按住方向键会加速重复（0.2s 后开始，间隔从 0.07s 逐步缩到 0.03s）。
详细语义见 docs/screen.md §4。

应用外壳

完整设计见 docs/arkui-app-guide.md。

导航：首页是 HdsNavigation 根页，标题栏不带标题文字，只保留右侧设置菜单；子页面走系统路由表（router_map.json + RouteName），新增页面不必改首页。
应用设置页：外观（深浅色）/ 标题栏模糊 / 沉浸光感 / 按键振动 / 屏幕旋转 / 屏幕倍数 / 语言 / 关于。卡片底色浅灰 #E8EAED、深灰 #2A2A2A；分段控件用原生 CapsuleSegmentButtonV2（保持系统默认配色）。
状态管理统一 V2：@ComponentV2 / @Local / @Param / @Event / @Monitor，跨页共享用 @ObservedV2 + @Trace 单例 AppUiState。

数据分层（MVVM）：

View（SettingsPage · @Local 快照）
  └─→ ViewModel（SettingsViewModel · 编排读写 + 发布 + 系统生效）
        └─→ Repository（SettingsRepository · 字段 ↔ KV 键）
              └─→ KeyValueStore（Preferences / 以后可换 SQLite，只需改一行装配）

沉浸式（组件级）：页面背景 expandSafeArea 延伸到状态栏 / 导航条；标题栏支持滚动动态模糊与沉浸光感；首页 7 键用 .systemMaterial(...)。
按键振动：按下 7 键时短振一次，强度在设置页调（关闭 / 弱 / 中 / 强，默认「弱」）。
平台版本：targetSdkVersion = compatibleSdkVersion = 26.0.0 （沉浸光感所用的 uiMaterial / systemMaterial 自 API 26 起提供）。

⚠️ 区分两个「Settings」：application/Settings.ets 是屏内设置页； pages/SettingsPage.ets 是应用外壳的设置页。

容易误解的地方

MID 为什么是确认、SET 为什么是返回？ 它们是硬件按键的丝印名 （原项目 KBD_MID_PIN / KBD_SET_PIN），原作者沿用板子上的叫法，映射成 KeyEnter / KeyBack。板子上没有单独的 Back 键，所以 SET 兼作返回。
RST 是「复位」，但不是重启芯片。 硬件上它是 GPIO9 上的普通按键（键码 0），功能是把界面复位回主页。
按下 ≠ 执行。 事件三态 Press / Repeat / Release，动作都在松开时提交。
屏幕是软件光栅化，按钮才是原生控件。
屏幕上的感叹号 ! 是刻意改过的。 原固件把它画成没有点的实心竖线，本项目用 tools/fixglyph 改成「竖线 + 点」——全项目唯一一处刻意偏离固件的像素。
ESP32 硬件信息是假数据，但帧率与播放信息是真的。
中英文字体是两张点阵表拼起来的：ASCII 用 tinyfont notosans12pt（与固件逐像素一致），中文用 Zpix 最像素（GB2312 汉字一个不缺）。Zpix 个人使用免费、商用收费，所以仓库里保留了一套 OFL 的 Fusion 作为可商用回退，见 docs/chinese-fonts.md。
左右键的重复只到达「接管按下」的那个元素，所以按住 LEFT 只返回一层，在进度条上则是按住加速。

构建与运行

用 DevEco Studio（推荐）：拉取项目 → 配置签名 → 直接运行。
用命令行 devecocli：

# 无线连接设备
hdc tconn <ip>:<port>
devecocli device list

# 检查 ArkTS 语法
devecocli check arkts
# 构建 + 安装 + 启动（--uninstall 先卸载同名旧应用）
devecocli run --device "<设备名>" --uninstall

Stage 模型 + ArkTS，bundleName = cn.forforio.osumchmos.mp3。
后台播放需要 module.json5 的 KEEP_BACKGROUND_RUNNING 权限与 backgroundModes。
字体点阵表全部由工具生成、可复现，首次构建 / 运行不需要 Go 环境。
⚠️ 若显式指定了 build-profile.json5 的 output.artifactName，devecocli run 会误报 hap 未签名；此时改用：

hdc -t {实机ip} install -r "{项目路径}\entry\build\default\outputs\default\{产物}.hap"

纯逻辑单测在 entry/src/test/（Hypium），在 DevEco Studio 里右键运行； devecocli 不提供本机测试运行器。

目录结构

entry/src/main/ets/
├── animation/    动画 Value（指数平滑 / 阻尼弹簧）与全局 Manager
├── screen/       FrameBuffer（1-bit 帧缓冲）/ ScreenView（最近邻放大）/
│                 Shell（主循环 / 输入分发）/ ScalePolicy（整数倍策略）
├── ui/           屏幕引擎：Canvas / Geometry / Element / Event / Cursor / Nav /
│                 Item / List / Row / Text / TextView / Input / Select / Checkbox /
│                 Chip / Keyboard / Viewer / Seekbar / Font / UiConstants
├── application/  屏幕页面与服务接缝：Launcher / Music / NowPlaying / Playlists /
│                 Settings / SysInfo / 曲目·文件夹·播放列表子页 / SearchPage /
│                 App / Services / MockServices / Lang / MediaUtil / Mp3Format /
│                 Pinyin / TextUtil
├── player/       MP3 引擎：AudioEngine / Playlist / LibraryStore（SQLite）/
│                 MediaLibrary / PermissionGuard / SessionBridge / VolumeBridge /
│                 BackgroundKeeper / PlayerHost
├── font/         内嵌点阵字模：Noto12Glyphs（ASCII）、Zpix12Glyphs（中文）
├── input/        Buttons：按键去抖 + 重复加速
├── pages/        Index（7 键外壳 + Navigation 根页）；SettingsPage（应用设置页）
├── common/       外壳通用工具（AppTheme / MaterialUtil / RouteName / TitleBarUtil /
│                 VibratorUtil / AppInfo / ContextUtil / ErrorUtil）
├── components/   SegmentedControl（通用分段控件）
├── preferences/  设置模块（AppSettings / AppUiState / KeyValueStore /
│                 SettingsRepository / SettingsViewModel / DisplayController /
│                 LanguageController / ScreenLangBridge）
└── entryability/ EntryAbility（启动恢复设置、状态栏字色、旋转）

entry/src/test/   本地单元测试（动画 / 渲染 / 播放队列 / MediaUtil / 拼音）
tools/            字体点阵生成工具（exportfont / fixglyph / exportcjk / mergeglyphs，
                  各自是独立 Go module）+ font-backup（Fusion 字形表备份）
docs/             项目文档（见上方「文档导航」）

项目来源与许可

本项目的屏幕 UI/UX 完全参考自 osu!mc （TinyGo + ESP32-S3 + 128×64 单色 OLED），由 chhongzh 以 MIT 许可证发布。本项目在其复刻版的基础上，把屏幕内容改造为一个真正可用的 MP3 播放器。

屏幕字体：

英文来自 tinyfont 的 notosans12pt （BSD 3-Clause）。
中文字形表有两套（见 docs/chinese-fonts.md）：
- Zpix 最像素（当前启用）：个人与教育项目免费，商用收费，且禁止修改 / 拆分；本仓库按个人项目使用，商用或公开分发前请先取得授权。
- Fusion Pixel Font（可商用回退，SIL OFL 1.1）：需要无限制分发时切回它。

项目介绍