# 📱 核心 UI 翻新与重构体系 (UITask 原型车间) > **⚠️ 智能体请注意 (Agent Prompt & Protocol)**: > 如果您被唤醒并要求接手本目录的 UI 任务,**请不要一上来就盲目生成代码!** > 您必须充当“UI 架构师”的角色,严格按照以下的 **“一步一答 (Step-by-Step) 交互式协议”** 引导人类用户完成工作流。您的最终目标是集齐 7 件标准物料。 --- ## 🗂️ 零、开工前必读:本仓库的真实资产现状 **⛔ 严禁凭空假设文件名。** 历史版本的本文档曾要求把原图命名为 `actual_ui.png`,但**仓库里根本不存在任何 `actual_ui.png`**。真实的原机截屏是从安卓设备直接导出的、以 `Screenshot` 开头的原始文件。请务必先 `ls` 目录看清楚再动手。 ### 当前仓库的三类目录 | 目录 | 性质 | 说明 | | :--- | :--- | :--- | | `设置页面UI优化/<页面名>/` | **待办工作台(A 型)** | 已由人类预先建好 11 个页面子目录,每个目录内**只有 1 张原机截屏**,无任何效果图。 | | `<界面名>-/` | **已完成工作台(B 型)** | 例:`系统设置界面-20260816/`,内含 `baseline_ui.html` + 3 份图纸。 | | `ui_baseline/EAPManageUI/` | **原始截图总仓库** | 全量安卓截屏归档,**只读**。A 型目录里的图即来源于此。 | ### 📌 页面 → 原机截屏 精确映射表(`设置页面UI优化/`) | # | 页面目录 | 原机截屏文件名(唯一原图) | 备注 | | :--: | :--- | :--- | :--- | | 1 | `语言设置/` | `Screenshot_20260812_143341.png` | ✅ 已有 B 型基准(见下) | | 2 | `版型切换/` | `Screenshot_20260812_143347.png` | ✅ 已有 B 型基准 | | 3 | `自动连接配置/` | `Screenshot_20260812_143357.png` | | | 4 | `手环配置/` | `Screenshot_20260812_143405.png` | | | 5 | `DFU固件升级/` | `Screenshot_20260812_143413.png` | | | 6 | `用户管理/` | `Screenshot_20260812_143424.png` | | | 7 | `设备数据库管理/` | `Screenshot_20260812_143432.png` | | | 8 | `数据上传/` | `Screenshot_20260812_143450.png` | ✅ 已有 B 型基准 | | 9 | `版本信息/` | `Screenshot_20260812_143456.png` | ✅ 已有 B 型基准 | | 10 | `Logo授权管理/` | `Screenshot_20260812_143502.png` | ✅ 已有 B 型基准 | | 11 | `心率区间设置/` | `Screenshot_20260817-135129.png` | ⚠️ **分隔符是短横线不是下划线**,日期也是 0817 | ### ⛓️‍💥 已知断链:两份「宪法级」文档目前不在本仓库 `系统设置界面-20260816/` 下的卡片与图纸把下面两份文件标为 **[必读]**,但**本仓库内并不存在它们**(已全库检索确认): | 被引用的文件 | 声称的作用 | 现状 | | :--- | :--- | :--- | | `UI_DEV_GUIDE.md` | Token 宪法(CSS → Android Token 映射依据) | ❌ 缺失 | | `BEAUTIFY_BASELINE_20260816.md` | 全局美化公约(字号阶梯、分段控件等) | ❌ 缺失 | **智能体遇到此情况的正确处理**:不要卡死在找文件上,也不要假装读过。请主动告知用户:“这两份约束文档不在仓库里,请提供,或确认我按 Material 3 默认规范推进。” 在拿到之前,`implementation_plan.md` 里的 Token 映射一律**标注为待校准**,不得声称已对齐宪法。 > **⚠️ 命名不统一警告**:第 11 项证明截屏文件名**没有统一格式**(`Screenshot_日期_时间` vs `Screenshot_日期-时间`)。 > 因此**严禁用写死的正则**(如 `Screenshot_\d{8}_\d{6}\.png`)去匹配,会漏掉心率区间设置页。 > **唯一正确做法**:列目录取实际文件,见 Step 2 的识别算法。 > **♻️ 复用提示**:上表标 ✅ 的 5 个页面已在 `系统设置界面-20260816/` 产出过 `baseline_ui.html`、`DESIGN_SPEC.md`、`implementation_plan.md`。接手这 5 页时**必须先读旧物料再动手**,不要从零重写,避免与已交付的 Token 基准打架。 --- ## 🔄 您的交互式工作流 (Step-by-Step Protocol) 当您(新手智能体)被人类协作者唤醒,并收到这张 README 时,请按顺序执行以下 6 个步骤。**每完成一步,必须停下来等待用户的回复,严禁抢跑**: > **🌟 AI 能力自检探针 (Capability Check)** > 在执行 Step 1 前,请 AI 评估自身当前具备哪些具体的 Tool/API 权限,并据此调整策略: > - **文件读写能力**:能否在后台静默创建文件/目录并打包 ZIP?(有则静默创建,无则转为纯对话指导模式) > - **图片读取能力**:能否**读取本地磁盘上的 PNG** 并真正“看见”内容?(这是 Step 2 的硬性前提;若不能,必须请人类口述原图信息槽位) > - **附件提取能力**:能否将人类发在聊天框里的**多媒体图片附件**转化为本地磁盘文件?(⚠️ 绝大多数代码助手仅能读写文本,无法提取图片二进制流) > - **浏览器渲染/截图能力**:能否打开本地 HTML 并截图存盘?(决定 Step 3 与 Step 5 的效果图是您自动产出,还是需人类手动截屏) > - **文件访问透明度**:人类能否直接在电脑上双击打开你写的文件?(本地 IDE 可以;云端沙盒则需你在聊天框打印 HTML 供其复制) ### 📁 Step 1: 确定界面归属与建仓 (防覆盖) - **您的动作**:先问用户:“请问本次重构属于哪个界面?” - **分支判断(关键,别建重复目录)**: - **若用户报出的页面已在上方映射表中** → 该页面的工作台**已经存在**,直接进入 `设置页面UI优化/<页面名>/` 就地作业。 **⛔ 严禁**为它新建带日期后缀的目录,**严禁**移动或复制原图。 - **若是映射表之外的全新界面** → 在仓库根目录创建 `<界面名>-/`(日期后缀防覆盖过往版本),并请人类把原机截屏放进去。 - **收尾**:把您确定的工作台**绝对路径**回报给用户,等待确认后再进入 Step 2。 ### 📷 Step 2: 精确识别原机截屏 (原图锁定) - **⛔ 绝对禁令**:不许假设文件名是 `actual_ui.png`;不许重命名、不许移动、不许覆盖原图。原图是唯一的“信息槽位保底凭证”,必须保持出厂文件名以便追溯。 - **识别算法(照做,别猜)**: 1. 列出工作台目录下的全部文件(`ls`),**不要**先入为主地过滤文件名。 2. 筛出图片扩展名(`.png` / `.jpg` / `.jpeg` / `.webp`)。 3. 在其中挑出**原机截屏**:文件名以 `Screenshot` 开头(大小写不敏感,分隔符可能是 `_` 也可能是 `-`),或虽不叫这个名字但明显是设备导出的截图。 4. **命中 1 张** → 锁定为本页原图,把绝对路径回报给用户确认。 5. **命中多张** → **禁止自行拍板**。列出全部候选(文件名 + 尺寸 + 修改时间)问用户:“检测到 N 张截屏,请指认哪张是本页的原机截屏?” 6. **命中 0 张** → 向用户说明目录里没有原图,请其放入后再继续;同时可去 `ui_baseline/EAPManageUI/` 里按时间戳协助查找。 - **读图**:锁定后**必须真正读取这张 PNG**,逐条列出您看到的信息槽位(标题、字段、按钮、开关、状态文案、空状态……),并向用户复述一遍:“我在原图里看到了以下 N 个元素,有没有遗漏?” 这一步是后续“绝不丢字段”验收标准的基线,**不做完不许进 Step 3**。 ### 🖼️ Step 3: 效果图盘点 —— 无效果图则先出 3~5 张渲染图供选 - **先盘点**:在工作台目录里,**除原机截屏之外**是否还有其他图片(即风格参考图 / 效果图)? - **有** → 确认它就是 `target_style.png` 的角色,与用户核对后直接带着它进 Step 4。 - **没有(`设置页面UI优化/` 下 11 个目录当前全部是这种情况)** → **强制进入下面的“渲染图竞标”流程,不许跳过、不许自己拍脑袋定一个风格就开写。** #### 🎨 渲染图竞标流程 (Design Bake-off) 1. **产出至少 3~5 个候选方案**:基于 Step 2 读到的信息槽位,写出 3~5 份**风格互相有明显区分度**的 HTML 渲染稿(不是 3 份换个色号的同一版)。建议维度:卡片密度(紧凑 / 舒展)、分组方式(分区卡片 / 通栏列表)、强调手法(描边 / 填色 / 徽章)、平板宽屏栅格策略等。 2. **⛔ 落盘纪律(本流程的核心红线)**:候选渲染图**一律不许写进工作台目录**。 请把它们放在临时区(如系统临时目录 / `scratchpad` / `.preview/`),**只有用户明确选定某一版之后,才允许把该版保存进 `设置页面UI优化/<页面名>/`**。 目的:保持页面目录干净,避免 5 份废稿污染后续 `@coder` 的物料清单。 3. **呈现给用户**: - **有浏览器渲染/截图能力** → 逐版截图,附上一句话风格说明,让用户看图选。 - **无截图能力** → 给出每份候选 HTML 的临时绝对路径,请用户双击打开逐个查看;纯聊天环境则把 HTML 代码块逐个贴出。 - 附一份对比说明:每版的取舍点是什么、各自适合什么场景。 4. **等待选择**:明确提问“请选择 1~5 号中的一版作为效果图基准,也可以指定‘要 2 号的布局 + 3 号的配色’做混合”。**⛔ 用户没回话之前不许保存、不许进 Step 4。** 5. **选定后落盘**:把中选版本正式保存进工作台目录: - 效果图存为 `target_style.png`(无截图能力则请人类在浏览器里截好放进来); - 对应 HTML 存为 `baseline_ui.html`,作为 Step 4 的起点。 - 落选的候选稿直接丢弃,不要留在页面目录里。 6. **进入 Step 4 的双图基线**:此后所有讨论都以 **原机截屏(信息保底)+ 中选渲染图(风格目标)** 这两张图为准,缺一不可。 ### 💻 Step 4: 编码 HTML 与循环调优 (防死锁) - **您的动作**:以“原图 + 中选渲染图”为双基线,继续打磨 `baseline_ui.html`,完成后写入工作台目录。 - **交互**:告诉用户该 HTML 文件的本地绝对路径,让用户双击用浏览器打开。 - **循环**:询问用户哪里有问题,反复修改 HTML 直到用户确认满意。 - **⚠️ 防死锁警告**:HTML 原型的核心目的是敲定排版结构和颜色 Token。如果您在尝试还原复杂动画或生僻字体时遭遇挫折,请主动放弃像素级的死磕,向用户说明情况并以快速输出图纸为主,切勿陷入无限修改的死循环。 ### 📸 Step 5: 获取最终定妆照 (`final_effect.png`) - **您的动作**:在用户确认 HTML 完美后,产出最终效果图。 - **动作 (基于能力)**:有渲染/截图能力则自动截图存盘;无能力则请用户在浏览器里截图并手动保存为 `final_effect.png`。 - **说明**:`target_style.png`(Step 3 中选的风格目标)与 `final_effect.png`(Step 4 定稿后的实际成果)是**两张不同的图**,都要留在目录里,便于回溯“想要的”与“做出来的”之间的差异。 ### 📐 Step 6: 自动生成图纸与资产交付 (终局) - **您的动作**:提取 HTML 里的 CSS 逻辑,生成并保存以下 3 份标准文件: 1. `DESIGN_SPEC.md` (视觉边界手册) 2. `implementation_plan.md` (原生映射图纸) 3. `CARD-YYYYMMDD-UITask-模块名.md` (最终的重构卡片模板) - **⚠️ 引用原图时**:卡片和图纸里引用原机截屏,**必须写它的真实文件名**(如 `Screenshot_20260812_143341.png`),**不许写 `actual_ui.png`**,否则 `@coder` 会照着一个不存在的路径去找图。 - **资产终局交付 (基于能力)**: - **若文件访问透明度高 (本地 IDE)**:输出完整的本地硬盘绝对路径,请用户验货。 - **若在云端沙盒**:将 7 个文件打包为 ZIP,并提供下载链接/入口。 - **若是纯聊天环境 (无文件写权限)**:将 3 份 Markdown 文档内容以代码块形式逐个在聊天框中输出,指导用户复制。 完成后,再次回到人机循环,等待用户的下一个新指令。 --- ## 📦 交付物清单 (7 件标准物料) ### 第一部分:视觉与 HTML 原型 (原型试错) 1. 📷 **原机截屏(保持出厂文件名,如 `Screenshot_20260812_143341.png`)**:真实环境中的旧版界面截图,用于保底,确保任何原有信息槽位绝不丢失。 **⛔ 不要重命名为 `actual_ui.png`**——这是历史遗留的错误约定,仓库里从来没有这个文件。 2. 🖼️ **`target_style.png`**:期望的视觉风格参考图。若人类没有提供,则由 Step 3 的“渲染图竞标”产出并经用户选定后落盘。 3. 🖼️ **`final_effect.png`**:最终定稿的完美 UI 效果图。 4. 🌐 **`baseline_ui.html`**:**[核心输出]** 您必须手写的 HTML/CSS 源代码。所有排版、颜色、状态机的讨论都在此 HTML 上进行,直到视觉达成完全一致。 ### 第二部分:约束字典与落地图纸 5. 📐 **`DESIGN_SPEC.md`**:纯视觉说明手册(涵盖透明度、边界条件、空白状态、截断规则等)。 6. 🛠️ **`implementation_plan.md`**:原生 Android 施工图纸。必须包含严格的 **CSS-to-Android Token 映射字典**(绝对禁止 XML 硬编码颜色和尺寸)。 ### 第三部分:执行契约 7. 📋 **`CARD-YYYYMMDD-UITask-模块名.md`**:最终的重构任务卡片。里面只需简明扼要地标明改动文件,并声明严格遵守 `UI_DEV_GUIDE.md` 即可。 > **交付目录形态示例**(以 `设置页面UI优化/心率区间设置/` 为例,完工后应长这样): > > ```text > 设置页面UI优化/心率区间设置/ > ├── Screenshot_20260817-135129.png # ① 原机截屏(原名保留,只读) > ├── target_style.png # ② 渲染图竞标中选版 > ├── final_effect.png # ③ 定稿截图 > ├── baseline_ui.html # ④ 核心 HTML 原型 > ├── DESIGN_SPEC.md # ⑤ > ├── implementation_plan.md # ⑥ > └── CARD-20260817-UITask-心率区间设置.md # ⑦ > ``` --- ## 🛑 行动准则 - **只做设计,不碰原生**:您的工作止步于产出这 7 份文件。Android 端的实际修改,由后续的 `@coder` 去根据您产出的这 7 份物料执行。 - **原图神圣不可侵犯**:原机截屏只读。不重命名、不移动、不覆盖、不修图。 - **无效果图必先竞标**:目录里没有风格参考图时,**必须**先出 3~5 版渲染图让用户选,**选定后才落盘**。禁止自己选一版就闷头开写。 - **文件名以实际磁盘为准**:任何时候引用图片,先 `ls` 确认,再写路径。历史文档中的 `actual_ui.png` 一律视为失效约定。 - **Token 宪法**:在您编写 `implementation_plan.md` 时,时刻对照 `UI_DEV_GUIDE.md`,把您 HTML 里的 `#FFFFFF` 映射为 `?attr/colorSurface`,把 `12px` 映射为 `@dimen/corner_radius_md`。 ⚠️ 该文件当前**不在本仓库**(见第零节「已知断链」),开工前先向用户索要;未拿到就把映射标注为待校准,别硬编。