DemonGatanjieuandClaude Opus 5.5
7da4e1d91e
The "!" guide on the audio page hid its tour banner with the hidden attribute, but the banner's display:flex overrode it, so the banner showed and started the image-side tour, whose buttons are not on the audio page. The audio guide now has its own spotlight steps, and tour steps whose target is not on screen are skipped. The batch import screen shows a folded example of a folder layout that sorts cleanly: one folder per character, named after it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.1 KiB
5.1 KiB
更新引导维护契约
更新引导只解释明显变化，不承担功能开关、数据迁移或执行用户操作。 修改前阅读根目录 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 更新步骤
- 先确认功能已实现及真实入口。不要在引导里承诺未上线、暂停或验证失败的功能。
- 在
CURRENT_UPDATE_GUIDE.steps编写 1–5 个步骤，每项包含唯一id、短icon、titleKey、bodyKey。 - 在
locales.js补齐这些键的中文和英文。标题说明变化，正文说明入口和用户该怎么用。禁止 HTML、可执行回调、请求及文件写入。 - 只有引导内容属于新一轮功能变化时才换
id，例如2026-10-library-navigation。修改错字、翻译、样式时保持 ID。不使用时间戳、随机数、Git 提交号或普通版本号自动生成 ID；换 ID 也不能自动弹窗。 - 配置校验会拒绝重复步骤、空步骤及缺失双语文案。配置错误只跳过引导，不应阻止插件打开；必须修正错误后再交付。
- 运行下方相关测试，再在浏览器验证打开插件不弹窗、上方入口、跳过后手动重开、帮助页重看、Esc 和长文案。
- 修改现有样式规则，不在文件末尾追加覆盖包。没有明确产品决策，不增加强制阅读、自动跳转、网络请求或额外追踪。
音频页使用说明
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，允许重看已确认版本。 - 引导不自动点击对应功能，也不修改画布、模型、素材、导入导出限制。
底部按钮约束
原按钮保留点击处理器、尺寸和图标。短标签是独立且 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 乒乓震荡闪烁。
验证
在插件根目录运行：
node --experimental-vm-modules tests/update_guide.mjs
update_guide.mjs 加载真实模块，检查双语配置、版本记忆、重看、翻页、关闭清理、
父窗口关闭、存储失败及扫描图标替换后的标签。它不能代替实际浏览器的布局与焦点验证。
只有同时修改工坊生命周期或导入导出行为时，才追加对应测试；纯引导样式不运行无关测试。