DemonGatanjieuandClaude Opus 5.5
7b09909e5b
tests/ (Python backend tests, .mjs frontend rule tests) is no longer ignored. tools/run_tests.mjs runs the structure check, every tests/*.mjs and the Python tests with $PYTHON, the portable python_embeded or python. docs/guides/testing.md says how to run and write them; README links it. Developer notes no longer point at 18 test files that were removed earlier (AGENTS.md table, backend, frontend and update-guide notes). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.0 KiB
4.0 KiB
更新引导维护契约
更新引导只解释明显变化，不承担功能开关、数据迁移或执行用户操作。 修改前阅读根目录 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 更新步骤
- 先确认功能已实现及真实入口。不要在引导里承诺未上线、暂停或验证失败的功能。
- 在
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，允许重看已确认版本。 - 引导不自动点击对应功能，也不修改画布、模型、素材、导入导出限制。
验证
更新指南没有单独的自动测试。改动后在浏览器里实际打开 ! 指南，检查双语、
翻页、重看、关闭和焦点；全部测试的跑法见 docs/guides/testing.md。
只有同时修改工坊生命周期或导入导出行为时，才追加对应测试；纯引导样式不运行无关测试。