|
1 | 1 | # 项目结构 |
2 | 2 |
|
3 | | -> 2026-08 重构后：全仓 ES Modules，无构建步骤，浏览器/SW 原生加载。 |
| 3 | +> 2026-08 重构后：全仓 ES Modules，无构建步骤，浏览器/SW 原生加载。代码统一收拢在 `src/`。 |
4 | 4 |
|
5 | 5 | ``` |
6 | 6 | MultiLangSwitcher/ |
7 | 7 | ├── LICENSE - 许可证文件 |
8 | 8 | ├── README.md - 项目说明文档 |
9 | | -├── package.json - 工程基线（biome/vitest，private，仅 devDependencies） |
10 | | -├── biome.json - lint + format 配置（tab 缩进、双引号） |
11 | | -├── _locales/ - 扩展描述的国际化目录（chrome.i18n，仅 manifest 元数据） |
12 | | -│ ├── en/ |
13 | | -│ └── zh/ |
14 | | -├── docs/ - 项目文档目录 |
15 | | -├── scripts/ - CI 校验脚本 |
16 | | -│ ├── check-syntax.mjs - 全部 js 的 node --check |
17 | | -│ └── validate-manifest.mjs - manifest + _locales 校验 |
18 | | -├── tests/ - vitest 测试（纯逻辑 + 失败路径） |
19 | | -│ └── helpers/global-loader.js - extractFunction（提取自包含纯函数） |
20 | | -├── shared/ - 共享 ESM 模块 |
21 | | -│ ├── message-types.js - 消息协议常量（MessageTypes） |
22 | | -│ ├── storage-keys.js - 存储键常量（STORAGE_KEYS / LOCAL_STORAGE_KEYS） |
23 | | -│ ├── shared-utils.js - 通用工具（日志、语言检测、兜底翻译） |
24 | | -│ ├── shared-i18n-base.js - BaseI18n 基类（字典由子类静态注入） |
25 | | -│ ├── shared-actions.js - requestBackground 信封 + resetAcceptLanguage |
26 | | -│ ├── shared-update-checker.js - UpdateChecker（版本比较/缓存） |
27 | | -│ ├── shared-language-options.js - 语言选项列表 |
28 | | -│ ├── header-check-utils.js - 请求头检查工具 |
29 | | -│ ├── shared-resource-manager.js - 资源管理器 |
30 | | -│ ├── ai-provider-presets.js - AI 服务商预设 |
31 | | -│ ├── ai-chat-client.js - OpenAI 兼容聊天客户端 |
32 | | -│ ├── copy-button.js - 复制按钮组件（+ copy-button.css） |
33 | | -│ ├── md5.js - MD5 哈希 |
34 | | -│ ├── theme-init.js - 主题初始化（classic script，预渲染同步执行） |
35 | | -│ └── vendor/ - 第三方库（marked / DOMPurify，classic script） |
36 | | -├── i18n/ - 运行时 i18n（每组件单文件双语字典 + 实例模块） |
37 | | -│ ├── popup-dict.js / popup-i18n.js |
38 | | -│ ├── debug-dict.js / debug-i18n.js |
39 | | -│ ├── detect-dict.js / detect-i18n.js |
40 | | -│ └── background-dict.js / background-i18n.js （Service Worker） |
41 | | -├── fonts/ images/ - 静态资源 |
42 | | -├── manifest.json - MV3 清单（background 为 module SW） |
43 | | -├── popup.html / popup.js - 弹窗页（单 module 入口） |
44 | | -│ └── popup/ - 弹窗模块（shared/ui-sync/language-apply/update-check） |
45 | | -├── debug.html / debug-ui.js - 调试页（单 module 入口） |
46 | | -│ └── debug/ - 调试模块（safe-dom/log-panel/rules-view/header-test/cache-mgmt/custom-language/rules-fix/diagnostics/auto-switch/domain-rules） |
47 | | -├── debug-headers.js - 调试页控制台工具（window.debugHeaders） |
48 | | -├── detect.html / detect.js - 检测页采集编排（DetectPageContext 为 AI 侧唯一读接口） |
49 | | -│ └── detect/ - 检测模块（shared/collectors/renderers/snapshot/ai-shared/ai-config/ai-ui/ai-session） |
50 | | -├── detect-ai.js - 检测页 AI 诊断（单 module 入口；经 CustomEvent 感知快照生命周期） |
51 | | -├── toggle.js / toggle.css - 语言/主题切换（ESM，被各页面入口 side-effect 导入） |
52 | | -├── domain-rules-manager.js - 域名规则管理（LRU 缓存；customDomainRules 扩展点） |
53 | | -├── domain-rules.json - 内置域名规则 |
54 | | -├── background.js - Service Worker 入口（ESM；normalizeMessageError、应答信封） |
55 | | -│ └── background/ - SW 模块（shared/rule-engine/lifecycle/message-handlers） |
56 | | -├── bootstrap.purged.css - PurgeCSS 裁剪产物（263KB→52KB，CI 校验与源同步） |
57 | | -└── bootstrap.min.css - Bootstrap 源文件（仅裁剪输入，不直接引用） |
| 9 | +├── manifest.json - MV3 清单（SW: src/background/background.js，popup: src/popup/popup.html） |
| 10 | +├── domain-rules.json - 内置域名规则（web_accessible_resource，保留根目录） |
| 11 | +├── bootstrap.min.css - Bootstrap 源文件（仅裁剪输入，不直接引用） |
| 12 | +├── bootstrap.purged.css - PurgeCSS 裁剪产物（页面实际引用） |
| 13 | +├── package.json / tsconfig.json / biome.json / renovate.json |
| 14 | +├── _locales/ - manifest 元数据国际化（chrome.i18n） |
| 15 | +├── docs/ - 文档（含 screenshots/） |
| 16 | +├── scripts/ - CI 校验/构建脚本 |
| 17 | +├── tests/ - vitest 测试 |
| 18 | +├── images/ fonts/ - 静态资源 |
| 19 | +└── src/ - 全部运行时代码 |
| 20 | + ├── popup/ - 弹窗页 |
| 21 | + │ ├── popup.html - 页面（单 module 入口 popup.js） |
| 22 | + │ ├── popup.js - 入口：消息接线、init、storage.onChanged |
| 23 | + │ ├── shared.js - getEl / runDOMUpdate |
| 24 | + │ ├── ui-sync.js - DOM 同步/显示辅助 + 快速检查（含防重入控制器） |
| 25 | + │ ├── language-apply.js - 语言应用流程 |
| 26 | + │ └── update-check.js - 更新检查（含防抖） |
| 27 | + ├── debug/ - 调试页 |
| 28 | + │ ├── debug.html - 页面（单 module 入口 debug-ui.js） |
| 29 | + │ ├── debug-ui.js - 入口：init 编排 |
| 30 | + │ ├── debug-headers.js - 控制台工具（window.debugHeaders） |
| 31 | + │ └── *.js - safe-dom/log-panel/rules-view/header-test/cache-mgmt/custom-language/rules-fix/diagnostics/auto-switch/domain-rules |
| 32 | + ├── detect/ - 检测页 |
| 33 | + │ ├── detect.html - 页面（单 module 入口 detect-ai.js，vendor classic 在前） |
| 34 | + │ ├── detect.js - 采集编排 + DetectPageContext（AI 侧唯一读接口） |
| 35 | + │ ├── detect-ai.js - 入口：sanitizeSnapshotForAI、init、事件监听 |
| 36 | + │ ├── shared.js - translate/getUiLanguage/createMessageId |
| 37 | + │ ├── collectors.js - 全部 collect*（含 UA-CH 高熵值） |
| 38 | + │ ├── renderers.js - 全部 render* |
| 39 | + │ ├── snapshot.js - 快照状态 + buildDetectionSnapshot + CustomEvent 派发 |
| 40 | + │ ├── ai-shared.js - AI 面板元素缓存 + aiSessionState + 状态助手 |
| 41 | + │ ├── ai-config.js - AI 配置存储/校验/持久化 |
| 42 | + │ ├── ai-ui.js - 聊天渲染与导出 |
| 43 | + │ └── ai-session.js - 会话流程与 Prompt |
| 44 | + ├── background/ - Service Worker |
| 45 | + │ ├── background.js - 入口：i18n 注册、normalizeMessageError、应答信封、listener 装配 |
| 46 | + │ ├── shared.js - i18nReady、常量、sendBackgroundLog、notifyPopupUIUpdate、autoSwitch 状态 |
| 47 | + │ ├── lifecycle.js - 初始化、上下文菜单、启动/安装/标签页监听 |
| 48 | + │ ├── rule-engine.js - DNR 规则应用（互斥锁 + 重试） |
| 49 | + │ ├── message-handlers.js - MESSAGE_HANDLERS 分发表 + 全部处理器 |
| 50 | + │ └── domain-rules-manager.js - 域名规则（LRU 缓存；customDomainRules 扩展点） |
| 51 | + ├── shared/ - 跨页共享模块 |
| 52 | + │ ├── message-types.js - 消息协议常量（MessageTypes，13 个） |
| 53 | + │ ├── storage-keys.js - 存储键常量（STORAGE_KEYS / LOCAL_STORAGE_KEYS） |
| 54 | + │ ├── shared-utils.js - 日志、语言检测、i18n 注册表、兜底翻译 |
| 55 | + │ ├── shared-i18n-base.js - BaseI18n（字典静态注入 + data-i18n 扫描器） |
| 56 | + │ ├── shared-actions.js - requestBackground 信封 + resetAcceptLanguage |
| 57 | + │ ├── shared-update-checker.js - UpdateChecker（版本比较/缓存/https 校验） |
| 58 | + │ ├── shared-language-options.js / header-check-utils.js / shared-resource-manager.js |
| 59 | + │ ├── ai-provider-presets.js / ai-chat-client.js / copy-button.js(+css) / md5.js |
| 60 | + │ ├── theme-init.js - 主题初始化（classic script，预渲染同步执行） |
| 61 | + │ ├── toggle.js / toggle.css - 语言/主题切换组件（各页面 side-effect 导入） |
| 62 | + │ ├── page-base.css - 页面公共基础样式（字体定义，单一来源） |
| 63 | + │ └── vendor/ - marked / DOMPurify（classic script） |
| 64 | + └── i18n/ - 运行时 i18n（每组件单文件双语字典 + 实例模块） |
| 65 | + ├── popup-dict.js / popup-i18n.js |
| 66 | + ├── debug-dict.js / debug-i18n.js |
| 67 | + ├── detect-dict.js / detect-i18n.js |
| 68 | + └── background-dict.js / background-i18n.js （Service Worker） |
58 | 69 | ``` |
59 | 70 |
|
60 | 71 | ## 架构契约 |
61 | 72 |
|
62 | | -- **消息协议**：页面与 SW 之间的消息类型一律使用 `shared/message-types.js` 的 `MessageTypes`，禁止字符串字面量；响应信封 `{ ok, data } / { ok, error }`。 |
63 | | -- **存储键**：一律使用 `shared/storage-keys.js` 常量。`currentLanguage` / `autoSwitchEnabled` 由 background 单写者持久化；`uiState` 位于 `chrome.storage.session`，页面经 `storage.onChanged` 只读订阅。 |
64 | | -- **i18n**：字典静态注入 `BaseI18n` 子类；运行时切换语言能力保留（`app-lang` localStorage + reload）。 |
| 73 | +- **消息协议**：页面与 SW 之间的消息类型一律使用 `src/shared/message-types.js` 的 `MessageTypes`，禁止字符串字面量；响应信封 `{ ok, data } / { ok, error }`。 |
| 74 | +- **存储键**：一律使用 `src/shared/storage-keys.js` 常量。`currentLanguage` / `autoSwitchEnabled` 由 background 单写者持久化（自动切换未显式开启时默认关闭）；`uiState` 位于 `chrome.storage.session`，页面经 `storage.onChanged` 只读订阅。 |
| 75 | +- **i18n**：字典静态注入 `BaseI18n` 子类；运行时切换语言能力保留（`app-lang` localStorage + reload）；i18n 实例经 `registerI18nInstance` 注册，禁止全局嗅探。 |
65 | 76 | - **页面加载**：每页单个 `<script type="module">` 入口；`theme-init.js` 是唯一 classic 业务脚本（预渲染防主题闪烁，"theme" 键与 `LOCAL_STORAGE_KEYS.THEME` 保持同步）。 |
66 | 77 | - **类型**：JSDoc + `tsc --checkJs`（`npm run check:types`），CI 强制零错误。 |
67 | 78 | - **i18n DOM**：静态文本用 `data-i18n` / `data-i18n-title` / `data-i18n-placeholder` / `data-i18n-alt` 声明（禁止嵌套 data-i18n）；`_applyDataAttributes` 统一扫描；特殊结构保留命令式。 |
68 | 79 | - **样式**：HTML 引用 `bootstrap.purged.css`（产物）；改动任何 class 后跑 `npm run build:css`，CI 校验产物与源同步。 |
69 | | -- **检测页解耦**：detect.js 不引用 detect-ai.js；快照生命周期经 `detect:snapshot-updated` / `detect:run-finished` CustomEvent 传播。 |
| 80 | +- **检测页解耦**：detect.js 不引用 detect-ai.js；AI 侧经 `DetectPageContext` 读快照；快照生命周期经 `detect:snapshot-updated` / `detect:run-finished` CustomEvent 传播。 |
0 commit comments