4.5 KiB
4.5 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 和长文案。
- 修改现有样式规则，不在文件末尾追加覆盖包。没有明确产品决策，不增加强制阅读、自动跳转、网络请求或额外追踪。
生命周期与记录
- 面板右上角常驻感叹号按钮（
#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 加载真实模块，检查双语配置、版本记忆、重看、翻页、关闭清理、
父窗口关闭、存储失败及扫描图标替换后的标签。它不能代替实际浏览器的布局与焦点验证。
只有同时修改工坊生命周期或导入导出行为时，才追加对应测试；纯引导样式不运行无关测试。