企业官网建设流程全解析

• 前端

KISS Translator（简约翻译）是一个开源的双语对照翻译浏览器扩展与油猴脚本，其 CHANGELOG.md 记录了从 v2.0.18 到 v2.1.0 的十余个版本迭代。本文以这份变更日志为骨架，逐版本拆解翻译接口体系、字幕翻译、划词翻译、规则引擎、同步安全与本地化等核心模块的演进脉络，并结合 src/config/api.js、src/libs/terms.js 等源码文件印证底层实现，帮助你理解一个持续迭代的翻译工具如何在工程上保持「简约」与「强大」的平衡。读完本文，你将能按版本回溯任何功能的引入时机，并掌握接口配置、术语替换、规则编辑器等关键能力的源码级原理。

一、v2.1.0：术语引擎、可视化规则编辑器与思考参数时代的开启

v2.1.0 是 CHANGELOG 中记录的最新版本，也是变化最密集的一次发布，集中体现了项目从「翻译工具」向「可深度定制的翻译平台」的演进方向。

1.1 术语库本地替换引擎与专业术语 Playground

「新增术语库本地替换引擎」意味着术语替换不再完全依赖 AI 提示词。从 src/libs/terms.js 的模块注释可以看出，这是一个「无 DOM、无日志依赖」的纯函数模块，供 translator、Playground、CLI 与单元测试四方复用：

• 解析规格：多条术语以换行或;分隔，每条形如key,value，key 与 value 用最后一个英文逗号分隔（key 本身允许含逗号）；key 按正则源码校验（new RegExp(key)），非法则跳过并收集诊断信息。
• 匹配语义：key 一律按正则源码包装为(key)参与 alternation，无单词边界，术语在原文任意位置都会命中；相同 key 只保留首次出现，并按key.length降序排序。
• 致命诊断：空源术语、非法正则、同源不同译文冲突、正则重叠冲突属于致命诊断（FATAL_DIAGNOSTIC_TYPES），消费方在存在致命诊断时不得生成「替换测试成功」摘要；尾巴逗号按保留原文处理，仅作非致命提醒。

「专业术语 Playground」即在设置页内直接对本地替换引擎做验证实验，避免每次都要走完整翻译流程。该能力与 src/views/Options/TerminologyPlayground.js 对应，仓库中还提供了 CLI 验证入口：pnpm test:terms（见 package.json）。

1.2 按住鼠标翻译模式（Press-and-Hold Translation）

「按住鼠标翻译模式，可在链接、按钮及网页规则限定区域内触发翻译，并可配置触发后的点击行为」——这是对手势交互的补充。移动端的实现基础可追溯到 src/libs/touchParagraph.js：该模块通过isTouchExcluded递归判断节点是否命中交互选择器（a, button, input, textarea, select, summary, [role='button']等）、.notranslate类或横向滚动容器，从而避免在可交互元素上误触发翻译；TouchParagraph类则维护candidates、pending集合，通过MutationObserver观察根节点上的新增内容，在滑动（swipe）模式下跟踪候选段落。

1.3 可视化网站规则编辑器与统一 Material 3 风格

可视化规则编辑器是该版本的另一大亮点。其工程结构分为多层：

• src/libs/ruleEditorManager.js：RuleEditorManager继承ShadowDomManager，以 Shadow DOM 承载 React 组件，管理编辑器会话（RuleEditorSession）的打开、关闭与销毁，并在打开期间通过pauseInteractions暂停页面原有交互。
• src/libs/ruleEditorSession.js 与 src/libs/ruleEditorDom.js、src/libs/ruleEditorStorage.js：分别负责会话状态、DOM 选取与草稿持久化。
• src/libs/ruleEditorPicker.js：负责在网页上「选取元素」并生成定位候选。

从 README.md 的「如何在网页上直接编辑规则」一节可以了解完整操作流：打开网页翻译面板 → 点击「编辑网站规则」→ 选择规则用途后点击「选取元素」→ 在网页上点击锁定元素 → 通过祖先路径调整层级、比较不同定位候选及匹配数量 → 点击「确认添加定位」加入草稿 → 点击主面板「保存规则」保存。编辑器支持翻译目标、排除区域、根容器、保留原文和段落边界，所有修改只更新当前草稿及预览，保存后才写入本地并触发同步；「预计翻译范围」基于草稿规则做高亮预览且不发送翻译请求。

「统一设置页、弹窗及规则界面的 Material 3 风格」则对应 src/styles/m3.js 与各视图的 M3 主题钩子（如 src/hooks/M3Theme.js）。

1.4 APIMart 接口、GPT-6 Astra 思考参数与提示词协议兼容

「新增 APIMart 翻译接口及 GPT-6 Astra 思考参数支持」是 AI 接口能力管理的代表案例。在 src/config/api.js 中可以看到一个完整的「模型思考能力注册表」（THINKING_API_REGISTRY）：

• 每个接口登记一个adapter（如openai、gemini、claude、deepseek、siliconflow、openrouter）和一个resolveCapability函数，后者负责根据模型名解析该模型支持的思考强度。
• 例如 GPT-6 Astra（gpt-6-astra）被识别为不支持关闭思考，只能从["max","xhigh","high","medium","low"]中选择强度降级（disable: null），UI 会给出最低强度降级提示（isThinkingMinimumFallback）。
• Gemini 侧则区分原生 Generate Content 与 Interactions 双协议、OpenAI 兼容接口，并按模型族（gemini-2.5-*、gemini-3.6-flash、gemini-3.1-pro等）解析不同的思考强度集合与默认预算（GEMINI25_BUDGETS：minimal/low 为 1024，medium 为 8192，high 为 24576）。
• normalizeThinkingSettings负责把用户的auto / enabled / disabled三档选择与具体强度归一化为可持久化的thinkingMode与thinkingEffort两个字段，避免「界面允许选择一个最终会被官方接口拒绝的等级」。

1.5 字幕翻译、触摸段落翻译与俄语界面

v2.1.0 还包含：

• 字幕翻译服务选择与跨视频字幕位置记忆：用户可以按视频保存自动翻译开关、缓存字幕轨道、自动收藏字幕单词；跨视频记忆字幕滚动列表的开关状态。
• 改进 YouTube 字幕分段与时间轴处理：相关逻辑分布于 src/subtitle/ 目录的subtitleSegmentationMetrics.js、youtubeAiSegmentation.js、subtitleBoundaryProtocol.js等模块。
• 可选的 LaTeX 转 Unicode 显示：AI 翻译引擎常会输出\(\frac{d\mathbf r_1}{dt}\)这类行内 LaTeX 标记。 src/libs/mathParse.js 实现了零依赖的转换器：其分隔符扫描器重实现了 KaTeXauto-render的splitAtDelimiters逻辑，符号表则派生自 KaTeXsymbols.js；契约是「纯函数、幂等、绝不抛异常」，无法结构转换的内容原样返回，结果永远不会凭空引入<或>（因为它会经过 DOMPurify）。
• 自动检查新版本：Web 构建会生成version.txt（见 src/scripts/build-task.mjs 中的await fs.writeFile(inDest("version.txt"), version)），版本检测主地址失败或返回非成功状态时自动回退到 GitHub。

二、v2.0.30s：翻译接口版图的急速扩张

从 v2.0.26 到 v2.0.32，CHANGELOG 记录了接口体系的密集扩充，与 src/config/api.js 中的OPT_ALL_TRANS_TYPES列表一一对应。

2.1 新增接口与默认接口的更替

• v2.0.32：新增 Google Cloud、Qwen MT、Yandex Cloud 翻译接口，补充免费翻译接口选择；默认翻译接口切换为微软翻译（源码中DEFAULT_API_TYPE = OPT_TRANS_MICROSOFT印证了这一点）。
• v2.0.29：新增 OrcaRouter 翻译接口（OpenAI 兼容请求、流式输出、批量翻译与推理强度配置）；微软翻译失效，设腾讯翻译为默认接口。
• v2.0.27：新增 OpenCode AI 翻译接口支持（OPT_TRANS_OPENCODEGO），并支持在接口设置中通过modelListUrl拉取模型列表。
• v2.0.26 之前的沉淀：DeepSeek、SiliconFlow、XiaomiMimo、AliyunBailian、Cerebras、Zai、ePhoneAI、Requesty 等接口已在更早版本内置。

在源码中，每个接口的默认请求地址、默认模型、模型列表地址都集中在defaultApiOpts表中。例如：

[OPT_TRANS_GEMINI]: { ...defaultApi, url: GEMINI_INTERACTIONS_URL, // 官方默认使用 Interactions 端点 modelListUrl: "https://generativelanguage.googleapis.com/v1beta/models", model: "gemini-3.6-flash", ...defaultAiApiOpts, }, [OPT_TRANS_APIMART]: { ...defaultApi, url: "https://api.apimart.ai/v1/chat/completions", modelListUrl: "https://api.apimart.ai/v1/models", model: "gpt-5.6-luna", ...defaultAiApiOpts, }, [OPT_TRANS_DEEPLX]: { ...defaultApi, url: "http://localhost:1188/translate", },

2.2 AI 接口的高级能力矩阵

API_SPE_TYPES把接口按能力划分为若干集合，是理解「为什么某些接口没有某些开关」的关键：

同时，defaultApi与defaultAiApiOpts定义了完整的接口参数清单：useBatchFetch（聚合发送）、useStream（流式传输）、streamRenderMode（disabled/realtime/segment 三种渲染模式）、useContext（智能上下文）与contextSize（默认 3 轮完整 user/assistant 轮次）、temperature（默认 0.0）、maxTokens（默认 20480）、thinkingMode与thinkingEffort、fetchLimit/fetchInterval/batchInterval/batchSize/batchLength/batchConcurrency等并发控制参数（默认值分别为 10 个并行任务、100ms 间隔、400ms 批处理延迟、20 段/次、10000 字符/次、10 个并发批次）。

v2.0.29 的「提高默认批量翻译并发数」「新增批量翻译并发控制」与 v2.0.26 的「AI 接口支持非批量请求的流式输出」，均可在这组默认参数与batchQueue.js、requestStream.js等模块（src/libs/）中找到实现落点。

2.3 Gemini 与 DeepL 的协议适配细节

• v2.0.31：Gemini 接口恢复 Generate Content 兼容支持，可适配 Generate Content 与 Interactions 双协议。源码中GEMINI_GENERATE_CONTENT_URL与GEMINI_INTERACTIONS_URL并存，isGeminiInteractionsUrl通过正则/\/v1(?:beta\d*)?\/interactions(?:[/?]|$)/i判断请求地址归属，从而决定使用哪套响应解析与重试逻辑。
• v2.0.30：Gemini 默认模型更新为 Gemini 3.6 Flash（model: "gemini-3.6-flash"与源码一致），并支持按模型适配思考模式配置与降级提示。
• v2.0.31：DeepL 支持简体与繁体中文语言代码。在OPT_LANGS_TO_SPEC中，DeepL 的zh-CN映射为ZH-HANS、zh-TW映射为ZH-HANT，且使用大写语言码（OPT_LANGS_SPEC_DEFAULT_UC）；微软翻译则把zh-CN映射为zh-Hans、zh-TW映射为zh-Hant。这正是「语言地区变体翻译」与「统一翻译文本格式处理」的实现基础。
• v2.0.31：微软翻译改用 Edge 公开端点，不再依赖旧的认证流程。

2.4 目标语言忽略规则与划词触发模式

v2.0.29 新增的「目标语言忽略规则：选中文本与目标语言相同或为纯数字时可不显示划词翻译按钮；中文默认显示划词翻译按钮」，以及「划词翻译新增双击触发模式」，其控制逻辑集中在 src/hooks/useSelectionController.js 与 src/views/Selection/ 目录（TranBtn.js、TranBox.js、TranCont.js、TranForm.js等）。v2.0.28 的「PDF 页面支持使用选中文本打开划词翻译弹窗」也依赖同一套选区控制器。

三、字幕翻译：从基础断句到 AI 断句与边界协议

字幕翻译是 CHANGELOG 中几乎每个版本都在打磨的模块，演进脉络清晰：

• v2.0.19–v2.0.23：支持任意翻译服务翻译 YouTube 字幕并双语显示；内置基础的字幕合并与断句算法；支持 AI 断句；字幕翻译支持流式渲染、错误处理与测试补充。
• v2.0.23：优化 YouTube 字幕提供器结构，拆分字幕轨道、字幕处理、AI 断句和播放器 UI 模块（对应 src/subtitle/YouTubeCaptionProvider.js、src/subtitle/youtubeCaptionTracks.js、src/subtitle/youtubeSubtitleProcessing.js、src/subtitle/youtubePlayerUi.js），提升后续维护性。
• v2.0.24：支持翻译失败字幕块的立即修复，并增加导出原始字幕事件为 JSON 的功能。
• v2.0.25：新增字幕显示顺序设置（原文与译文的展示位置）；优化 AI 断句与提示词输出要求，修复响应解析失败导致字幕丢失的问题。
• v2.0.29：支持按视频保存自动翻译开关、缓存字幕轨道、自动收藏字幕单词；修复 AI 断句索引偏移导致的时间轴不同步问题。
• v2.1.0：新增字幕翻译服务选择和跨视频字幕位置记忆。

字幕 AI 断句的底层协议定义在 src/subtitle/subtitleBoundaryProtocol.js。以 src/config/api.js 中的defaultSubtitlePrompt为例，其要求模型严格输出 JSON 数组，每元素为{"e":<last_word_id>,"o":"exact merged source text","t":"translation"}，并且：

• e字段必须是严格递增的、来自输入的精确词 ID，首段从 ID 0 开始；
• 硬性源长度限制：空格分隔语言每段不超过 15 词（自然边界处 8–12 词为佳），中日韩等无空格语言每段不超过 30 个源字符；
• 模型必须先根据前一个e确定精确输入范围并逐字合并为o，再仅翻译当前o为t；程序端负责重建时间轴。

字幕渲染与双语并排显示由 src/subtitle/BilingualSubtitleManager.js 负责。仓库还提供了分段测试工具：pnpm test:subtitle-segmentation，测试样本位于 testdata/subtitle-samples/（含中英日文 ASR 样本、无标点长句、噪声事件等技术内容）。

四、划词翻译、词典与 AI 词典体系

划词翻译是 KISS Translator 的三大核心场景之一（网页翻译、输入框翻译、划词翻译），其演进集中在 v2.0.24–v2.0.28：

• AI 词典（v2.0.24）：支持使用检测到的语言进行语音播报；v2.0.27 的收藏单词页新增 AI 词典标签页；v2.0.25 支持 AI 词典自定义用户提示词。
• v2.0.25：新增划词翻译按钮位置模式。
• v2.0.26：划词翻译弹窗新增单击翻译、双击翻译和禁用模式；优化复制弹窗内容时的交互体验。
• v2.0.27：修复划词翻译弹窗相关问题，提升选区状态、弹窗提交和清理逻辑的稳定性。
• v2.0.22：划词翻译弹窗支持色彩模式切换、拖拽调整宽度、快捷键，并优化划词按钮跟随选中文本的逻辑。

AI 词典的提示词模板同样定义在 src/config/api.js 中。createEnglishDictionaryPrompt生成专家级词典系统提示词，内置中、日、韩、越南、俄语五个目标语言版本（defaultDictPromptEnJa、defaultDictPromptEnKo、defaultDictPromptEnVi、defaultDictPromptEnRu），其核心是一个「智能路由」约定：当[Target]是单个英文单词、习语或不超过 3 词的习惯搭配时走词典模式，否则走纯翻译模式，避免对长句强行做词典分析。

传统词典方面，src/apis/zdic.js 实现了汉典单字查询（v2.0.22 修复新版汉典布局下的单字查询解析）；v2.0.21 支持单个汉字查询；src/config/api.js 中OPT_DICT_BING/OPT_DICT_YOUDAO对应必应/有道划词词典，OPT_SUG_BAIDU/OPT_SUG_YOUDAO对应输入联想建议。

五、规则引擎：个人规则、订阅规则与站点规则

CHANGELOG 中规则模块的变化包括：

• v2.0.21：输入框翻译、鼠标悬停翻译、划词翻译均增加黑名单功能；AI 接口与字幕翻译均支持专业术语。
• v2.0.22：规则设置新增 iframe 白名单、块级选择器规则、订阅规则单独开关和快速加入黑名单按钮。
• v2.0.23：全局规则和站点规则新增文本顺序选项（译文在上方显示），隐藏原文快捷键遵循该顺序；移除 iframe 白名单设置（空 iframe 不再触发无效翻译流程）。
• v2.0.26：个人规则新增启用/禁用开关。
• v2.0.29：规则新增持久化的纯文本翻译选项；悬浮翻译按钮支持按站点配置例外显示规则。
• v2.1.0：可视化网站规则编辑器（见前文）。

优先级方面，README.md 明确「个人规则 > 订阅规则 > 全局规则」，其中全局规则优先级最低但作为兜底。订阅规则的同步实现位于 src/libs/subRules.js：syncSubRules通过apiFetch拉取远程规则，经checkRules校验格式后，过滤掉 pattern 为全局匹配星号*的规则（防止订阅规则劫持用户的全局设置），再存入本地；trySyncAllSubRules以 24 小时为间隔做增量同步。规则解析、匹配与翻译的完整逻辑在 src/libs/rules.js、src/config/rules.js 与 src/libs/translator.js 中实现。

六、同步、安全与性能：Gist、WebDAV、加密与 Trusted Types

跨端同步与安全加固是多个版本的重要主题：

• v2.0.22：增加 GitHub Gist 同步功能，并优化 WebDAV 同步时的 cookie 处理（对应 src/libs/sync.js、src/libs/syncCrypto.js）。
• v2.0.24：新增同步加密密码支持；修复并优化 Gist 同步的同步重复问题；使用 Trusted Types 保护 HTML 解析过程（src/libs/trustedTypes.js）；在界面中隐藏 API 密钥显示。
• v2.0.29：同步加密密码支持本地重置，并加强密码轮换的安全校验。
• v2.0.31 / v2.0.30 / v2.0.29：升级依赖以分别修复 CVE-2026-54466、CVE-2026-9277、CVE-2026-25896 安全漏洞；package.json 的pnpm.overrides中保留了fast-xml-parser、shell-quote、websocket-driver等依赖的强制版本覆盖。

性能与稳定性方面：v2.0.25 优化提示词签名缓存（使用摘要减少缓存键体积）；v2.0.23 优化 TranslatorManager 在 SPA 页面中的生命周期处理；v2.0.26 优化大段纯文本翻译处理并修复纯文本<pre>内容翻译卡顿；v2.0.22 优化字幕列表性能（虚拟列表、滚动位置保持、字幕项动画性能）。

油猴（GM）兼容性是另一条持续打磨的线：v2.0.24 修复 Via 浏览器中的流式 UTF-8 解码回退，完善桥接逻辑及请求回退处理；v2.0.26 支持原生和旧版 GM API；v2.0.29 改进油猴流式响应兼容性。相关实现分布在 src/libs/gm.js、src/libs/gmMethods.js 与 src/userscript.js。

七、本地化：从英中到九种界面语言

CHANGELOG 记录了界面语言的逐步扩展：

• v2.0.29：新增土耳其语界面翻译。
• v2.0.30 之前：已支持中英日韩。
• v2.0.31：新增越南语界面支持。
• v2.1.0：新增俄语界面。

src/config/i18n.js 中的UI_LANGS目前包含 en、zh、zh_TW、ja、ko、tr、vi、ru 八种语言，同时通过 src/config/i18n.ru.js、src/config/i18n.ruleEditor.js、src/config/i18n.touch.js 拆分维护。扩展层面的语言包位于 public/_locales/（de、en、es、fr、ja、ko、ru、vi、zh_CN、zh_TW）。此外，v2.0.22 的「自动设置界面语言」与 v2.0.32 的「更新扩展快捷键分配与中文标签」完善了多语言体验。

八、工程基建：版本号自动同步与多端构建

CHANGELOG 与 VERSION_MANAGEMENT.md、package.json 共同构成了一套完整的发布工程体系。

8.1 单一版本源与自动同步

项目版本号分散在package.json、.env（REACT_APP_VERSION）、public/manifest.json、public/manifest.firefox.json、public/manifest.thunderbird.json 五个文件中。方案是以package.json为唯一版本源：

• 构建时自动同步：pnpm build、pnpm build+zip会在打包前先触发版本号同步；
• 手动强制同步：pnpm sync-version；
• 快捷升级命令：pnpm version:patch（补丁）、pnpm version:minor（次版本）、pnpm version:major（主版本）、pnpm version:set -- 2.1.0（指定版本）。

src/scripts/sync-version.mjs 的实现从package.json读取版本号，遍历同步.env的REACT_APP_VERSION与三个 manifest 的version字段。v2.0.19 引入的「自动更新版本号脚本」即指 src/scripts/update-version.mjs。

8.2 多端构建目标

package.json 的 scripts 展示了完整构建矩阵：

pnpm build:chrome pnpm build:edge pnpm build:firefox pnpm build:safari-output # Safari 产物 pnpm build:thunderbird pnpm build:web pnpm build:userscript-ios pnpm build:rules # 内置规则构建，仅生成规则 JSON 文件

v2.0.29 提到的「Web 构建现在会生成version.txt；内置规则构建仅生成规则 JSON 文件」，正对应 src/scripts/build-task.mjs 中写版本文件与 src/rules.js 的规则构建逻辑。v2.0.20 则修复了 MacOS 编译 Safari 插件脚本错误。

8.3 发布流程规范

VERSION_MANAGEMENT.md 还规定了master（生产）与dev（开发）双分支管理：在dev上完成pnpm format→pnpm version:patch→ 更新 CHANGELOG →pnpm build+zip→ 提交推送，再通过 GitHub PR 合入master，最后在master打 Tag（如v2.0.20）推送以触发自动发版工作流。

九、如何基于 CHANGELOG 与源码验证一次升级

如果你需要为一次升级做回归验证，可以把 CHANGELOG 条目当作检查清单，映射到源码与测试上：

1. 接口配置：检查 src/config/api.js 的defaultApiOpts与API_SPE_TYPES，确认新接口的 URL、模型、能力集合是否符合预期；OPT_LANGS_TO_SPEC可核对语言码映射。
2. 术语替换：运行pnpm test:terms验证 src/libs/terms.js 的解析与替换行为，其测试在 src/libs/terms.test.js。
3. 字幕分段：运行pnpm test:subtitle-segmentation，结合 testdata/subtitle-samples/ 样本观察断句与时间轴重建质量。
4. 划词翻译：查看 src/hooks/useSelectionController.js 与 src/views/Selection/ 的组件与测试（如 TranForm.retry.test.js）。
5. 同步与存储：src/libs/sync.test.js、src/libs/storage.test.js 及*.acceptance.test.js系列覆盖了同步回滚、序列化与首次读校验等场景。
6. 版本号：执行pnpm sync-version后检查五个文件的版本号一致性。

结语

从 v2.0.18 到 v2.1.0，KISS Translator 的 CHANGELOG 串起了一条清晰的产品演进线：翻译接口从少数机器翻译扩展到覆盖主流 LLM 聚合平台，并沉淀出思考参数、流式输出、聚合批量、上下文记忆等能力矩阵；字幕翻译从「能翻译」进化到「AI 断句 + 边界协议 + 跨视频记忆」；规则系统走向可视化编辑与订阅生态；同步与安全经历了加密、Trusted Types 与多轮 CVE 修复。这份变更日志既是用户的功能索引，也是开发者理解代码库的导航图——沿着每个版本条目，都能在 src/ 中找到对应的实现模块与测试佐证。

• 前端