Code renew

代码升级（code-renew）· 代码/项目升级手术

一句话：对一个"能跑但有很多毛病/死改改不出来"的项目，做一次先看清、再设计、后动刀、步步验证的全面升级手术。适用于网页/工具/脚本类项目；视角 = 资深工程师 + 高级审美设计师双线。

实战出身：一次真实项目的四期升级手术（41 项诊断 → 四期施工 → 全部实测验收），本文所有铁律和踩坑都来自那次手术及后续实战。

---

〇、定位与触发

什么时候用：

• 项目"能用但到处是小毛病"，零敲碎打改不动了
• 同一个问题反复改反复回潮（"死改改不出来"）
• 想把工具升格成作品（实用 + 审美双跃升）
• 接手一个别人/过去的自己写的、没人完全看懂的代码库

什么时候不用：单点小修（直接改）；纯新功能开发（不需要先诊断旧账）；纯数据录入。

触发词：全面升级 / 迭代升级 / 大重构 / 代码体检 / 这项目帮我做一次升级手术

---

一、八条铁律（违反任何一条 = 手术事故）

1. 备份先行：动刀前整包 zip 进 _backup/（gitignore 掉），unzip -t 校验。出事解包回滚。
2. 先看清全貌，再动第一刀：诊断与治疗严格分离。诊断期一行业务代码都不许改。
3. 找根因，不打症状：症状在哪层，根因常在上一层。沿数据流问三次"这个值是谁给的"。
4. 用证据，不用感觉：关键数字用独立实现对数；修复后用脚本/浏览器实测；"我觉得好了"不算数。
5. 机器查机械错，人查品味错：穷举型问题（字号失控/死代码/硬编码色）交给 grep 和脚本；体验型问题（动效讲不讲故事/层级有没有焦点）必须亲眼看截图。
6. 死代码先清再建："改了没反应"的第一嫌疑人是死代码和被覆盖的声明。先 grep 引用计数确认死透，再整块删。
7. 按依赖分期：地基(bug/性能) → 行为(交互/叙事) → 视觉(艺术层) → 精修(排版/模式/适配)。在坏架构上调表层是"死改"的最大根源。
8. 每期一个 commit，每期独立实测验收。损失隔离在一期内；commit 信息写清做了什么为什么。

---

二、五幕流程

第〇幕 · 备份与边界（10 分钟）

1. zip -rq _backup/项目_升级前备份_$(date +%Y%m%d_%H%M).zip 项目目录 -x 排除项 + 校验 + gitignore。
2. 问用户拿决策（一次问全）：施工优先顺序？技术栈边界（能否上构建工具/新依赖）？特殊模式需求（如展示/工作台分离）？移动端投入深浅？——拿到授权再开工，避免做完被推翻。

第一幕 · 三路独立诊断（核心，约占总时长 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，别耗着。

---

四、审美准则（高级设计师视角的升级红线）

1. Token 化：字号收敛成阶梯（≤8 级）、间距走 4/8 网格、颜色全走变量（grep 硬编码色清零）、动效统一时长/曲线变量。系统混乱的页面，先立 token 再谈美。
2. 对齐是底线：四角浮层同一内缩值；同级标题同字号字重；基线对齐。差 2px 也要修——细差最暴露功力。
3. 原生控件 = 廉价感最大来源：select 必须 appearance:none + 自绘箭头；focus 环不许杀（改用 :focus-visible 区分鼠标/键盘）；按钮要有 :active 按压。
4. 空值优雅降级："待补/null/undefined" 这类工作台词不许出现在展示面——省略或用"—"，必要时做"工作台/展示"双模式。
5. 动效要讲故事：镜头跟随当前主体（不是累积范围）、时长随距离缩放、与节拍不打架；数据可视化要有层级（频率→粗细深浅），不能所有元素同权重。
6. 取景按数据不按行政区：地图/图表的初始视野框"实际有数据的范围"，不为空白留面积。

五、反模式（看到自己在做这些就停手）

• 看到症状直接改参数（没读代码就调）
• 没备份就大改 / 没 grep 调用点就改共用函数
• 改完不验证就说"好了" / 验证只在桌面宽屏
• 在死代码或被覆盖的声明上反复改（"怎么不生效？"）
• 一个 commit 塞全部改动（出问题无法定位回滚）
• 用户没拍板就替用户做概念级决策（技术栈/模式/优先级）

六、交付验收清单

• 备份 zip 存在且校验通过
• 诊断文档落盘（编号+分级+根因）
• 每期独立 commit，信息可检索
• 全部修复有实测证据（截图/脚本输出）
• 窄屏（≤430px）过目
• 复盘文档含"新架构速查表 + 项目特有耦合点"
• START_HERE/README 已对齐，已 push

---

复制即用启动词

使用 code-renew 对这个项目做一次全面升级手术：
1) 先整包备份 zip 进 _backup/ 并校验
2) 三路独立诊断：子代理逐行审代码 + 浏览器截图巡检全部状态 + 关键数字独立核算，诊断文档落盘
3) 出分期施工提案（地基→行为→视觉→精修），问我拍板优先级和边界
4) 每期：改 → 语法守门 → 浏览器实测 → commit；全部修复要有实测证据
5) 收工：复盘文档（含新架构速查表）+ START_HERE + push