ScrollToPrompt工程化实践：TypeScript、Vitest与GitHub Actions构建可靠扩展

ScrollToPrompt 是一款面向 ChatGPT、Claude、Gemini 等 AI 聊天界面的浏览器扩展，它为长对话注入"小地图式"的滚动条标记，让你一键跳回任意历史提问。这个项目的工程化做得相当扎实：用TypeScript 严格模式兜底类型安全、用Vitest跑单元测试、再用GitHub Actions把 Lint、构建、测试串成一条自动流水线。本文带你拆解这套浏览器扩展工程化的完整思路，新手也能照抄。

一、先看这个扩展做什么

ScrollToPrompt 的核心体验是：在 AI 聊天页的滚动区域注入一条自定义滚动条，每个提问（prompt）对应一个可视化标记；对话再长，上下文也只需一次点击就能找回。

几个值得学习的设计点：

• Shadow DOM 隔离：整个 UI 包在独立的 Shadow DOM 里，宿主网站的 CSS 完全污染不了它；
• 适配器模式：每个平台（ChatGPT、Claude、Gemini、Perplexity、Grok）各写一个适配器类，核心引擎与平台逻辑零耦合；
• 性能意识：MutationObserver监听 DOM 变化后做 120ms 防抖渲染，拖拽和滚动走requestAnimationFrame，保证 60fps；
• 隐私优先：零数据采集，所有逻辑本地运行。

📐 完整架构说明在 docs/architecture.md，建议配合源码阅读。

二、TypeScript 严格模式：可靠性的地基

很多扩展项目为了省事关闭严格检查，ScrollToPrompt 则反其道而行。看 tsconfig.json 的几个关键配置：

🎯 这套配置的思路是：tsc 负责"查错"，Vite 负责"打包"，各司其职。

类型约束真正发挥威力的地方是 src/core/Engine.ts 中的SiteAdapter接口：

• 引擎只依赖这个接口，不关心具体是哪个平台；
• 五个平台的实现（src/adapters/Platforms.ts）都implements SiteAdapter，漏写一个方法编译器直接报错；
• 扩展 API 的类型由@types/chrome提供，chrome.storage、chrome.tabs等调用全程有提示。

这就是严格模式的最大红利：重构和加新功能时，类型系统帮你兜底。

三、构建工具链：Vite + CRXJS 一键产出扩展

浏览器扩展的构建比较特殊——要处理manifest.json、content script、service worker 等多个入口。ScrollToPrompt 选择 Vite 搭配@crxjs/vite-plugin来解决。

vite.config.ts 非常简洁：

• 引入crx插件并传入 manifest.json 作为清单，插件自动识别 content script 和 service worker 入口；
• 开发服务器固定5173端口，HMR 热更新，改完src/content/main.ts页面立即生效。

manifest.json 是标准Manifest V3声明：content script 只挂载到五个 AI 平台域名，run_at设为document_idle避免抢在页面加载前执行；权限只申请了storage一项，保持最小权限原则。

构建命令npm run build实际是tsc && vite build（见 package.json）——先让 tsc 完成类型检查，通过后再交给 Vite 产出dist目录，最后到chrome://extensions里"加载已解压的扩展程序"即可调试。

四、代码质量守门员：ESLint + Prettier + Husky

工程化不只是"能跑"，还包括"任何人提交的代码都长一个样"。项目的组合拳是：

lint-staged 的白名单配置在 package.json：TS 文件走 ESLint 自动修复 + Prettier，CSS 和 Markdown 只走 Prettier。

另外 .editorconfig 在编辑器层面统一了缩进与换行风格，.gitattributes 则声明了文本/二进制文件的换行规则，避免 Windows 和 Linux 协作者互相添乱。

💡 对新手来说，这套组合的价值在于：风格问题在提交前就被机器消灭了，代码评审可以专注逻辑本身。

五、Vitest 测试 + GitHub Actions：质量自动流水线

本地工具解决"个人习惯"，CI 流水线解决"团队底线"。ScrollToPrompt 的 CI 配置在 .github/workflows/ci.yml，触发条件是push 到main分支和指向main的 Pull Request，在ubuntu-latest上依次执行：

1. actions/checkout— 检出代码；
2. actions/setup-node— 安装 Node.js 20，并开启npm依赖缓存（加速后续运行）；
3. npm ci— 按package-lock.json精确安装依赖，保证 CI 和本地装的是一模一样的版本；
4. npm run lint— 静态检查不过，直接红灯；
5. npm run build— 类型检查 + 完整构建验证；
6. npm test— 启动 Vitest 的test脚本）。

🚦 这条流水线的设计很典型：Lint → Build → Test 三道闸口串行，任何一道失败 PR 就无法合并。对贡献者而言，提交前本地跑一遍npm run lint && npm test，就能和 CI 保持一致的结果。

项目同时提供了标准化的协作资产：

• 结构化 Issue 模板：.github/ISSUE_TEMPLATE/bug_report.yml、.github/ISSUE_TEMPLATE/feature_request.yml；
• PR 模板：.github/PULL_REQUEST_TEMPLATE.md，内置"是否通过自查、是否更新文档"等检查清单；
• 贡献规范：CONTRIBUTING.md 明确要求"新增代码要补测试、改动 API 要同步文档"。

六、新手速查：本地开发一键命令

把日常命令整理成一张表，照着敲就能跑起来：

总结：可复制的工程化清单

ScrollToPrompt 用不到千行的代码量，搭出了一套生产级扩展该有的完整工程体系。如果你想给自己的扩展项目补课，可以直接抄这份作业：

• ✅TypeScriptstrict模式 + 接口约束，让类型系统当第一道防线；
• ✅tsc 只做检查、Vite 负责构建，工具链分工清晰；
• ✅最小权限的 Manifest V3 声明，安全与体验兼顾；
• ✅ESLint 零警告 + Prettier + lint-staged，把风格问题拦在提交前；
• ✅GitHub Actions 串行执行 Lint / Build / Test，把质量底线交给自动化。

想深入了解各模块的设计决策，可以继续读 docs/architecture.md 与 ROADMAP.md，看看这个项目下一站要支持哪些平台。