# 更新引导维护契约

更新引导只解释明显变化，不承担功能开关、数据迁移或执行用户操作。
修改前阅读根目录 [AGENTS.md](../../AGENTS.md)。

## 内容与实现分工

| 文件 | 责任 |
| --- | --- |
| `web/modules/update_guide_data.js` | 当前引导的稳定 ID、步骤顺序、图标和文案键；也提供配置校验 |
| `web/modules/locales.js` | 每个步骤及按钮的中英文文案，均按纯文本展示 |
| `web/modules/ui_update_guide.js` | 显示、翻页、关闭、焦点、版本记录；一般内容更新不要修改 |
| `web/modules/sidebar_actions.js` | 六个底部按钮的短标签、完整名称和用途提示，不改变点击动作 |
| `web/styles.css` | 引导布局和底部图标/文字切换的现有规则 |
| `web/main.js` / `ui_sidebar.js` | 父窗口关闭清理，以及上方按钮和帮助页的手动入口 |

## 后续 AI 更新步骤

1. 先确认功能已实现及真实入口。不要在引导里承诺未上线、暂停或验证失败的功能。
2. 在 `CURRENT_UPDATE_GUIDE.steps` 编写 1–5 个步骤，每项包含唯一 `id`、短 `icon`、`titleKey`、`bodyKey`。
3. 在 `locales.js` 补齐这些键的中文和英文。标题说明变化，正文说明入口和用户该怎么用。禁止 HTML、可执行回调、请求及文件写入。
4. **只有引导内容属于新一轮功能变化时才换 `id`**，例如 `2026-10-library-navigation`。修改错字、翻译、样式时保持 ID。不使用时间戳、随机数、Git 提交号或普通版本号自动生成 ID；换 ID 也不能自动弹窗。
5. 配置校验会拒绝重复步骤、空步骤及缺失双语文案。配置错误只跳过引导，不应阻止插件打开；必须修正错误后再交付。
6. 运行下方相关测试，再在浏览器验证打开插件不弹窗、上方入口、跳过后手动重开、帮助页重看、Esc 和长文案。
7. 修改现有样式规则，不在文件末尾追加覆盖包。没有明确产品决策，不增加强制阅读、自动跳转、网络请求或额外追踪。

## 生命周期与记录

- 面板右上角常驻感叹号按钮（`#anomalous-update-notice-btn`），提供完整的用途提示和 accessible name。只有用户点击该按钮或帮助页入口才打开引导；初始化、打开插件、版本变化都不能触发弹窗。
- 使用原生 `dialog` 的顶层显示和焦点约束，关闭时尽可能恢复原焦点。
- 完成、跳过、×、Esc、点击空白关闭会记录已读，上方入口仍然保留；关闭父浏览器仅清理，不将未读引导标记为已读。入口不需要全局事件或延时隐藏。
- 持久化键为 `anomalous_update_guide_seen:<id>`，值为 `1`。只保存本地已读状态，不发送到服务端。
- 存储不可用时，当前页面会话仍记住关闭状态；刷新后仍必须手动点击才能显示。
- 同一时刻只有一个引导。重复调用不叠加弹窗；所有关闭路径通过 `closeUpdateGuide` 释放资源。
- 上方按钮和帮助页的“查看更新引导”均使用 `force: true`，允许重看已确认版本。
- 引导不自动点击对应功能，也不修改画布、模型、素材、导入导出限制。

## 底部按钮约束

原按钮保留点击处理器、尺寸和图标。短标签是独立且 `aria-hidden` 的 `span`，
不能占用已用于详细提示的 `::before`/`::after`。扫描状态替换 SVG 后重新配置标签。
语言切换须更新六个标签、完整 accessible name 和用途提示。
悬停与键盘焦点使用相同文字切换；无悬停设备直接显示短文字；减少动态效果偏好禁用位移动画。
**防闪烁与稳定性铁律**：底栏按钮必须显式声明 `cursor: pointer !important; overflow: hidden;`，内部 SVG 与 Label 必须设置 `pointer-events: none !important;`。图标切换文本时**严禁使用 `display: none`**（必须使用 `opacity: 0` 保持物理文档流支撑），以避免浏览器 Hit-testing 丢失目标导致高频触发 `mouseleave` -> `mouseenter` 乒乓震荡闪烁。

## 验证

在插件根目录运行：

```powershell
node --experimental-vm-modules tests/update_guide.mjs
```

`update_guide.mjs` 加载真实模块，检查双语配置、版本记忆、重看、翻页、关闭清理、
父窗口关闭、存储失败及扫描图标替换后的标签。它不能代替实际浏览器的布局与焦点验证。
只有同时修改工坊生命周期或导入导出行为时，才追加对应测试；纯引导样式不运行无关测试。