备份与开发日志
类型：rule（操作指南）
描述：改代码前必做的备份 + 全程开发日志记录规范
最后更新：2026-05-26
触发场景：开始任何版本更新任务时
相关 rules：version-release-flow.md
什么时候用
- 每一次版本更新（无论改多少行）
- 任何会改 storage 字段结构的改动
- 改调度逻辑 / 数据模型
备份
标准命令
CUR=$(node -p "require('./package.json').version")
D=$(date +%Y%m%d)
mkdir -p "backup/v${CUR}_${D}"
cp -R src package.json wxt.config.ts tsconfig.json "backup/v${CUR}_${D}/"
echo "已备份到 backup/v${CUR}_${D}"
精简版（只备份将要改的文件）
CUR=$(node -p "require('./package.json').version")
mkdir -p "backup/v${CUR}"
cp src/utils/scraper.ts \
src/utils/dynamic-scraper.ts \
src/utils/scraper-executor.ts \
src/utils/storage-data.ts \
src/sections/settings/view/settings-view.tsx \
"backup/v${CUR}/" 2>/dev/null || true
规则
backup/ 目录只进不出 — 不删旧备份- 命名约定：
backup/v<旧版本>[_<日期>]/
- 备份 = 改代码的前置条件，不可跳
开发日志
何时写
| 时机 |
写什么 |
| 改动开始 |
顶部新增条目 — 标题 + 改动目标 |
| 改动中 |
遇到问题立即记录 — 现象/原因/解决 |
| 改动完 |
验证结果 + 注意点 |
模板
## YYYY-MM-DD v<旧> → v<新> [一句话标题]
### 用户反馈 / 改动目标
- [原始诉求，保留用户原话用引用块]
### 改动
- [按文件 / 按子任务列出]
### 验证
- pnpm build ✅ X.XXs
- pnpm compile ✅ 0 新错误（残留为历史问题，与本次无关）
### 遇到的问题
- 问题：[一句话]
- 现象：
- 原因：
- 解决：
### 注意点
- [下次同类操作要注意的]
- [关联到 docs/rules/ 或 docs/wiki/ 的链接]
写日志的铁律
- ⚠️ 最新记录放最上面：新条目插在「---」分隔的第一条之前
- ⚠️ 不省略「遇到的问题」：哪怕没遇到大问题，至少写「无」+ 一行说明
- ⚠️ 「注意点」是给未来的自己看的：写"为什么这么做"，而不是"做了什么"
何时同步更新文档体系
| 本次改动类型 |
同步更新 |
| 改了字段名/语义 |
docs/wiki/settings-field-semantics.md |
| 改了调度逻辑 |
docs/wiki/shared-queue-architecture.md |
| 加了新组件 |
docs/wiki/<组件名>.md（新建） |
| 用了新工具 |
docs/rules/<工具>.md（新建，元规则） |
| 踩了新坑 |
更新规则.md 第七章「历次大事件」表 + 对应 wiki |
易错点
- ⚠️ 跳过备份直接改：出问题没法回滚 → 严格执行
- ⚠️ 日志只写「做了什么」不写「为什么」：3 个月后自己看不懂 → 写决策过程
- ⚠️ 用 Edit 工具改
development-log.md 时：用户标点常含全角，参考 zh-punct-edit-fallback.md
完成后必做