# 更新引导维护契约

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

## 内容与实现分工

| 文件 | 责任 |
| --- | --- |
| `web/modules/update_guide_data.js` | 当前引导的稳定 ID、步骤顺序、图标和文案键；也提供配置校验 |
| `web/modules/locales.js` | 每个步骤及按钮的中英文文案，均按纯文本展示 |
| `web/modules/ui_update_guide.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. 修改现有样式规则，不在文件末尾追加覆盖包。没有明确产品决策，不增加强制阅读、自动跳转、网络请求或额外追踪。

## 音频页使用说明

- `AUDIO_USAGE_GUIDE`（同在 `update_guide_data.js`）是音频页的使用说明，不是更新公告。音频域激活时，右上角 **!** 打开它；图像域照旧打开 `CURRENT_UPDATE_GUIDE`。
- 可选字段：`titleKey` 替换对话框标题；`tour: false` 不显示遮罩导览入口，`tour: [...]` 用这份说明自己的导览步骤（音频页用 `AUDIO_TOUR_STEPS`），不写则是图像界面的导览。导览步骤的目标不在屏幕上时自动跳过。
- 内容跟着功能改，ID 保持 `audio-studio-usage`。完整说明在 `docs/guides/audio-studio.md`，两边要一致。

## 生命周期与记录

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

## 验证

更新指南没有单独的自动测试。改动后在浏览器里实际打开 **!** 指南，检查双语、
翻页、重看、关闭和焦点；全部测试的跑法见 `docs/guides/testing.md`。
只有同时修改工坊生命周期或导入导出行为时，才追加对应测试；纯引导样式不运行无关测试。