YiweiCreates 代码升级（code-renew）· 代码/项目升级手术
一句话：对一个"能跑但有很多毛病/死改改不出来"的项目，做一次先看清、再设计、后动刀、步步验证的全面升级手术。适用于网页/工具/脚本类项目；视角 = 资深工程师 + 高级审美设计师双线。
实战出身：一次真实项目的四期升级手术（41 项诊断 → 四期施工 → 全部实测验收），本文所有铁律和踩坑都来自那次手术及后续实战。
〇、定位与触发
什么时候用：
- 项目"能用但到处是小毛病"，零敲碎打改不动了
- 同一个问题反复改反复回潮（"死改改不出来"）
- 想把工具升格成作品（实用 + 审美双跃升）
- 接手一个别人/过去的自己写的、没人完全看懂的代码库
什么时候不用：单点小修（直接改）；纯新功能开发（不需要先诊断旧账）；纯数据录入。
触发词：全面升级 / 迭代升级 / 大重构 / 代码体检 / 这项目帮我做一次升级手术
一、八条铁律（违反任何一条 = 手术事故）
- 备份先行：动刀前整包 zip 进
_backup/（gitignore 掉），unzip -t校验。出事解包回滚。 - 先看清全貌，再动第一刀：诊断与治疗严格分离。诊断期一行业务代码都不许改。
- 找根因，不打症状：症状在哪层，根因常在上一层。沿数据流问三次"这个值是谁给的"。
- 用证据，不用感觉：关键数字用独立实现对数；修复后用脚本/浏览器实测；"我觉得好了"不算数。
- 机器查机械错，人查品味错：穷举型问题（字号失控/死代码/硬编码色）交给 grep 和脚本；体验型问题（动效讲不讲故事/层级有没有焦点）必须亲眼看截图。
- 死代码先清再建："改了没反应"的第一嫌疑人是死代码和被覆盖的声明。先 grep 引用计数确认死透，再整块删。
- 按依赖分期：地基(bug/性能) → 行为(交互/叙事) → 视觉(艺术层) → 精修(排版/模式/适配)。在坏架构上调表层是"死改"的最大根源。
- 每期一个 commit，每期独立实测验收。损失隔离在一期内；commit 信息写清做了什么为什么。
二、五幕流程
第〇幕 · 备份与边界（10 分钟）
zip -rq _backup/项目_升级前备份_$(date +%Y%m%d_%H%M).zip 项目目录 -x 排除项+ 校验 + gitignore。- 问用户拿决策（一次问全）：施工优先顺序？技术栈边界（能否上构建工具/新依赖）？特殊模式需求（如展示/工作台分离）？移动端投入深浅？——拿到授权再开工，避免做完被推翻。
第一幕 · 三路独立诊断（核心，约占总时长 1/4）
并行三路，互相不通气，最后交叉：
- 路 A·代码审查：派子代理逐行读完核心代码（大文件分给多个代理：逻辑 JS 一个、样式+结构一个）。指令要求：按严重度分组（必修 bug / 交互缺陷 / 性能 / 动效生硬 / 代码债），每条带行号和证据，"只报真实存在的问题，引用具体代码为证"。
- 路 B·亲眼巡检：本体用自动化浏览器把每一种页面状态截图过目（每个 tab、每个弹窗、每个模式、播放中、窄屏 ≤430px）。看的是层级、对齐、焦点、文案、动效节奏——审美问题全在这一路。
- 路 C·数据核算：对页面展示的关键统计数字，用 Python 独立实现同一套口径算一遍对数。对不上的就是 bug（实战曾靠这一路抓到"停留记录双端 +1 导致全部计数虚高"）。
产出：诊断文档落盘（不是聊天里说说），全部问题编号、分级、注根因。
第二幕 · 提案与拍板（短）
把诊断收口成分期施工提案（每期：目标/清单/验收标准），连同关键概念决策（如双模式、技术栈）抛给用户拍板。提案本身落盘，将来可追溯"为什么这么改"。
第三幕 · 分期施工（主体）
每期固定节拍：改 → 语法守门 → 浏览器实测 → commit。
- 语法守门：
node --check（JS）/ 括号配平脚本（CSS）/python3 -m py_compile（Python），每次保存后必跑，秒级成本。 - 死代码清剿专用手法：grep 引用计数 → 全部引用都在死簇内 → 括号配平脚本整块删 → 残留引用清零检查 → 冒烟。
- 改任何函数前先 grep 它的全部调用点——实战中多次靠这个避免"修一处崩三处"（如一个播放停止函数有 8 个调用点、渲染与弹窗的开关顺序冲突）。
- 视觉/动效类改动必须截图自验，不能只看代码合理。
第四幕 · 收工沉淀
复盘文档（含新架构速查表——下个 AI 靠它不用重读全部代码）+ 项目 START_HERE/README 对齐 + push。把这轮学到的"项目特有耦合点"写进复盘，这是给未来省钱的最高杠杆动作。
三、工具链速查（首选 → 备选 → 兜底）
| 用途 | 首选 | 备选 | 兜底 |
|---|---|---|---|
| 代码全量审查 | 并行子代理（逐行读+行号证据） | 自己分段 Read（大文件按 grep 行号定位区段） | — |
| 视觉巡检/实测 | Chrome DevTools MCP（截图+evaluate+点击） | Playwright（容器版 file:// 被挡：起 python3 -m http.server 8765，容器内用 http://host.docker.internal:8765；截图遇"画面永不稳定"超时→先暂停动画再截） |
open 给用户亲眼看并截图回传 |
| 语法守门 | node --check / py_compile |
括号配平脚本（CSS/JSON） | 浏览器 console 看报错 |
| 死代码确认 | grep -c "\b符号\b" 引用计数 |
子代理验证调用链 | 注释掉跑一轮（最慢） |
| 数据核对 | Python 独立实现口径对数 | 浏览器 evaluate 读页面值比对 | — |
| 批量机械改 | Python 脚本（正则/块替换，改前 cp 备份） | Edit 逐处（≤5 处时） | — |
| 版本管理 | 描述性 commit + push | 若仓库有自动提交插件会抢跑 → --allow-empty 打可检索标记 |
zip 回滚 |
MCP 浏览器踩坑备忘：Chrome DevTools MCP 的标签页可能莫名关闭/实例卡死——pkill -f chrome-devtools-mcp 后重连；连续两次失败直接换 Playwright，别耗着。
四、审美准则（高级设计师视角的升级红线）
- Token 化：字号收敛成阶梯（≤8 级）、间距走 4/8 网格、颜色全走变量（grep 硬编码色清零）、动效统一时长/曲线变量。系统混乱的页面，先立 token 再谈美。
- 对齐是底线：四角浮层同一内缩值；同级标题同字号字重；基线对齐。差 2px 也要修——细差最暴露功力。
- 原生控件 = 廉价感最大来源：select 必须
appearance:none+ 自绘箭头；focus 环不许杀（改用:focus-visible区分鼠标/键盘）；按钮要有:active按压。 - 空值优雅降级："待补/null/undefined" 这类工作台词不许出现在展示面——省略或用"—"，必要时做"工作台/展示"双模式。
- 动效要讲故事：镜头跟随当前主体（不是累积范围）、时长随距离缩放、与节拍不打架；数据可视化要有层级（频率→粗细深浅），不能所有元素同权重。
- 取景按数据不按行政区：地图/图表的初始视野框"实际有数据的范围"，不为空白留面积。
五、反模式（看到自己在做这些就停手）
- 看到症状直接改参数（没读代码就调）
- 没备份就大改 / 没 grep 调用点就改共用函数
- 改完不验证就说"好了" / 验证只在桌面宽屏
- 在死代码或被覆盖的声明上反复改（"怎么不生效？"）
- 一个 commit 塞全部改动（出问题无法定位回滚）
- 用户没拍板就替用户做概念级决策（技术栈/模式/优先级）
六、交付验收清单
- 备份 zip 存在且校验通过
- 诊断文档落盘（编号+分级+根因）
- 每期独立 commit，信息可检索
- 全部修复有实测证据（截图/脚本输出）
- 窄屏（≤430px）过目
- 复盘文档含"新架构速查表 + 项目特有耦合点"
- START_HERE/README 已对齐，已 push
复制即用启动词
使用 code-renew 对这个项目做一次全面升级手术：
1) 先整包备份 zip 进 _backup/ 并校验
2) 三路独立诊断：子代理逐行审代码 + 浏览器截图巡检全部状态 + 关键数字独立核算，诊断文档落盘
3) 出分期施工提案（地基→行为→视觉→精修），问我拍板优先级和边界
4) 每期：改 → 语法守门 → 浏览器实测 → commit；全部修复要有实测证据
5) 收工：复盘文档（含新架构速查表）+ START_HERE + push