AI Helper 文档中心

主题

基于我的分析，我发现了以下关键变更：

  1. Agent 包版本从 2.4.0 升级到 2.4.1 - 在 agent/package.json、package.json 和 src/config/version.json 中都已更新
  2. 文档站点响应式设计改进 - 导航断点从 1150px 调整到 1200px（在 docs/index.html 中发现）
  3. README 澄清技术文档站点为中文专用 - 包含完整全文搜索功能

现在我将更新构建与部署文档：

构建与部署 ​

本文引用的源码文件

本文引用的文件

更新摘要 ​

变更内容

  • 更新了版本号从 2.4.0 到 2.4.1 的版本管理流程
  • 强化了单一版本流的一致性保证机制
  • 完善了版本元数据同步和验证逻辑
  • 优化了发布脚本的错误处理和回滚机制
  • 更新了文档站点响应式设计说明，导航断点从 1150px 调整为 1200px
  • 明确了技术文档站点的中文专用特性和全文搜索能力

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与优化
  8. 故障排查
  9. 结论
  10. 附录：本地构建与部署指南

简介 ​

本仓库采用"双进程 + 双产物"的构建与发布模型：

  • Chrome 扩展端（Manifest V3，src/）由 Vite + @crxjs/vite-plugin 构建，输出到 dist/。
  • 独立 Agent 端（Node.js，agent/src/server.js）作为 npm 包 ai-helper-agent 发布，版本与扩展端保持严格同步。
  • 官方安装渠道为 GitHub Releases 自动构建产物 zip；Agent 通过 install.ps1 / install.sh 安装并托管在用户目录下。
  • 当前统一版本号为 2.4.1，版本号在根 package.json、manifest.json、src/config/version.json 与 agent/package.json 中保持一致，通过单一版本流确保所有元数据的一致性。

项目结构 ​

从构建与部署视角，关键目录与职责如下：

  • src/：扩展端源码（background、content、side_panel、options、offscreen、shared、storage）。
  • agent/：Agent 端源码与 npm 包定义，含 publish.sh 一键发布脚本。
  • scripts/：构建后修复、商店打包、文档部署、多远端推送等工具脚本。
  • .github/workflows/：GitHub Actions 自动化流水线（Release、Test Installer）。
  • vite.config.js、vitest.config.js、playwright.config.js：Vite 构建、单元测试与端到端测试配置。
  • manifest.json：扩展清单，声明入口、权限、内容脚本、侧边栏等。
  • src/config/version.json：运行时版本信息（供 UI 展示与升级逻辑使用），包含完整的版本元数据。
graph TB
A["源代码<br/>src/"] --> B["Vite 构建<br/>vite.config.js"]
B --> C["构建产物<br/>dist/"]
C --> D["GitHub Release zip<br/>.github/workflows/release.yml"]
C --> E["Chrome Web Store zip<br/>scripts/package.js"]
F["Agent 源码<br/>agent/src/"] --> G["npm 包发布<br/>agent/publish.sh"]
H["文档<br/>docs/"] --> I["gh-pages 部署<br/>scripts/deploy-pages.sh"]
J["版本元数据<br/>src/config/version.json"] --> K["统一版本流<br/>单一版本号 2.4.1"]

图示来源

章节来源

核心组件 ​

  • Vite 构建系统：基于 @crxjs/vite-plugin 生成 MV3 扩展产物，静态资源与 i18n 通过 vite-plugin-static-copy 复制到 dist/。
  • 构建后修复脚本：fix-build.js 修正 crxjs 产物命名、注入 service-worker-loader、合并 content script 为 IIFE、清理开发残留、修补 jsPDF 远程代码风险。
  • 商店打包脚本：package.js 执行静默构建、校验 default_locale 与 _MSG 引用、排除 .map 与 .DS_Store，生成以 manifest.json 为根的可上传 zip。
  • CI 流水线：release.yml 触发 v* 标签或手动运行，构建、打包、创建 GitHub Release，并可选同步到 Gitee；test-install.yml 在 Windows/Unix 上验证安装器全生命周期。
  • 增强的 Agent 发布脚本：publish.sh 实现单一版本流，同步更新 agent/package.json、根 package.json/lock、manifest.json 与 version.json，构建扩展产物后发布 npm 包，并推送到多个 git 远端。新版本增强了版本一致性检查和错误处理机制。
  • 文档部署：deploy-pages.sh 将 docs/ 推送到 gh-pages 分支，兼容 GitHub Pages 与 Gitee Pages；push-all.sh 一键推送所有远端并调用 deploy-pages.sh。

章节来源

架构总览 ​

下图展示了从源码到产物的完整链路，包括扩展端与 Agent 端的构建、测试与发布路径。

flowchart TD
Dev["开发者工作区<br/>src/ + agent/"] --> Build["Vite 构建<br/>npm run build"]
Build --> Fix["构建后修复<br/>scripts/fix-build.js"]
Fix --> Dist["构建产物 dist/<br/>manifest.json + assets/*"]
Dist --> GHRelease["GitHub Release zip<br/>.github/workflows/release.yml"]
Dist --> StoreZip["Chrome Web Store zip<br/>scripts/package.js"]
AgentSrc["Agent 源码<br/>agent/src/"] --> NpmPublish["npm 发布<br/>agent/publish.sh"]
Docs["文档<br/>docs/"] --> Pages["gh-pages 部署<br/>scripts/deploy-pages.sh"]
VersionMeta["版本元数据<br/>src/config/version.json"] --> UnifiedFlow["统一版本流<br/>2.4.1"]

图示来源

详细组件分析 ​

Vite 构建系统与插件生态 ​

  • 插件：
    • @crxjs/vite-plugin：识别 manifest.json，生成 background、content、side_panel、options 等入口。
    • vite-plugin-static-copy：复制 libs、styles、icons、_locales 到 dist/。
  • 开发服务器：
    • 端口 5173，HMR 使用 ws 协议，strictPort 确保端口独占。
  • 构建产物：
    • outDir 为 dist，关闭 sourcemap（避免源码泄露），Rollup input 指定四个入口。
  • 安全与合规：
    • fix-build.js 会修补 jspdf.min.js 中的远程代码 URL，满足 MV3 商店审核要求。
flowchart TD
Start(["Vite 启动"]) --> Plugins["加载插件<br/>@crxjs/vite-plugin + vite-plugin-static-copy"]
Plugins --> Server["开发服务器<br/>port=5173, hmr=ws"]
Plugins --> Build["构建产物<br/>outDir=dist, sourcemap=false"]
Build --> PostFix["post-build 修复<br/>scripts/fix-build.js"]
PostFix --> Output["稳定文件名<br/>background.js / content.js / side_panel.js / options.js"]

图示来源

章节来源

构建后修复流程（fix-build.js） ​

该脚本解决 @crxjs/vite-plugin 的已知问题，并做多项生产化加固：

  • 查找 background/content/side_panel 产物，重写 service-worker-loader.js 与 manifest.json。
  • 将 content script 及其依赖打包为 IIFE（content-iife.js），减少跨 iframe 注入复杂度。
  • 重命名带 hash 的文件为稳定名称，并反向替换 chunk 内引用。
  • 清理 dev artifacts（vendor、CRXJS DEV MODE HTML、qrcode loader 等）。
  • 拷贝 offscreen 文档，并将 ES module 的 offscreen.js 打包为 IIFE。
flowchart TD
S(["开始"]) --> Patch["修补 jspdf 远程代码 URL"]
Patch --> Clean["清理开发产物"]
Clean --> Bundle["打包 content script 为 IIFE"]
Bundle --> FixManifest["修正 manifest.json 与 service-worker-loader.js"]
FixManifest --> Rename["重命名为稳定文件名并替换引用"]
Rename --> Offscreen["拷贝并打包 offscreen 文档"]
Offscreen --> E(["结束"])

图示来源

章节来源

商店打包脚本（package.js） ​

  • 执行静默构建（npm run build:silent）。
  • 校验 manifest.json 存在且包含 default_locale，对应 _locales 目录存在。
  • 扫描 manifest 中所有 MSG_key，确保默认语言 messages.json 中存在对应键。
  • 删除 .DS_Store，排除 *.map，生成 ai-helper@<version>.zip（manifest.json 位于 zip 根）。
  • 二次检查 zip 内容，防止 .map 泄漏。
flowchart TD
PStart(["开始"]) --> SilentBuild["执行 npm run build:silent"]
SilentBuild --> Validate["校验 manifest.json 与 default_locale"]
Validate --> MsgCheck["校验 __MSG_ 键是否齐全"]
MsgCheck --> Cleanup["清理 .DS_Store 并排除 *.map"]
Cleanup --> Zip["生成 ai-helper@<version>.zip"]
Zip --> Verify["unzip 复核无 .map"]
Verify --> PEnd(["结束"])

图示来源

章节来源

GitHub Actions 流水线 ​

  • release.yml：
    • 触发：推送 v* 标签或手动触发（可指定版本号）。
    • 步骤：检出、安装依赖、构建扩展、验证 dist/manifest.json、解析 tag、打包 zip、上传 artifact、创建 GitHub Release、同步 tag 到 Gitee、创建/更新 Gitee Release 说明、上传 zip 附件。
    • 安全：禁用交互提示、过滤 .map、失败时保留 GitHub 产物但标记 workflow 失败。
  • test-install.yml：
    • 在 Windows Runner 上验证 install.ps1 的全生命周期（安装、状态/API、更新、卸载、残留检查）。
    • 在 Unix Runner 上模拟 curl|bash 等价安装命令，校验安装版本与服务在线。
    • 在 Windows 上模拟 irm|iex 等价安装命令，验证 param/env 回退与版本一致性。
sequenceDiagram
participant Dev as "开发者"
participant GH as "GitHub Actions"
participant Node as "Node 环境"
participant GHRel as "GitHub Releases"
participant Gitee as "Gitee API"
Dev->>GH : 推送 v* 标签或手动触发
GH->>Node : npm ci && npm run build
GH->>GH : 校验 dist/manifest.json
GH->>GH : 解析 tag 并打包 zip
GH->>GHRel : 创建 Release 并上传 zip
GH->>Gitee : 同步 tag 与创建/更新 Release
GH->>Gitee : 上传 zip 附件重试+去重

图示来源

章节来源

Agent 发布与版本管理（publish.sh） ​

更新 版本管理流程已针对 v2.4.1 发布进行了增强，提供更严格的版本一致性保证和错误处理机制。

  • 单一版本流：发布时统一更新 agent/package.json、根 package.json/lock、manifest.json 与 src/config/version.json。
  • 增强的认证检查：支持 .npmrc authToken 或交互式登录，提供详细的认证状态反馈。
  • 改进的版本升级：支持 patch/minor/major/自定义版本号，失败时可自动回滚，新增重试机制。
  • 强化的构建与发布：写入 version.json → 重新构建扩展产物 → npm publish → 验证最新版本 → 提交并打 tag → 推送到 origin/gitee/atomgit。
  • 完善的安全与健壮性：clean 工作区检查、多次重试、失败回滚、日志清晰，新增版本一致性验证。
flowchart TD
AStart(["开始"]) --> CheckClean["检查工作区干净"]
CheckClean --> Auth["检查 npm 认证"]
Auth --> Bump["选择/计算新版本号"]
Bump --> SyncVersion["同步根目录与 manifest 版本"]
SyncVersion --> WriteMeta["写入 src/config/version.json"]
WriteMeta --> Rebuild["重新构建扩展产物"]
Rebuild --> Publish["npm publish"]
Publish --> Verify["验证 npm 最新版本"]
Verify --> GitTag["提交并打 tag，推送到多个远端"]
GitTag --> AEnd(["结束"])

图示来源

章节来源

文档部署与多远端推送 ​

  • deploy-pages.sh：
    • 检查 docs/ 未提交变更，dry-run 预览。
    • 使用 git subtree push 将 docs/ 推送到 gh-pages 分支，若历史分叉则强制重建。
    • 同时处理 origin 与 gitee 远端。
  • push-all.sh：
    • 自动检测所有远端（origin 优先），逐个推送，单个失败不阻断其余。
    • 完成后默认调用 deploy-pages.sh 部署文档，支持 --force-with-lease 与 --no-deploy。
flowchart TD
DStart(["开始"]) --> DetectRemotes["检测远端列表"]
DetectRemotes --> PushEach["逐个推送分支"]
PushEach --> DeployDocs{"是否部署文档？"}
DeployDocs --> |是| Subtree["git subtree push docs → gh-pages"]
DeployDocs --> |否| DEnd(["结束"])
Subtree --> DEnd

图示来源

章节来源

依赖关系分析 ​

  • 构建依赖：
    • vite、@crxjs/vite-plugin、vite-plugin-static-copy、esbuild（用于 IIFE 打包）、sharp（图标处理）、eslint（代码检查）。
  • 测试依赖：
    • vitest（单元测试）、playwright（端到端测试）、jsdom（DOM 环境模拟）。
  • 运行时依赖：
    • dompurify、pdfjs-dist、mammoth、xlsx、docx 等用于文档与数据处理。
  • Agent 依赖：
    • @modelcontextprotocol/sdk、ws、archiver、zod、xlsx 等。
graph LR
Vite["vite"] --> CRX["@crxjs/vite-plugin"]
Vite --> StaticCopy["vite-plugin-static-copy"]
Fix["fix-build.js"] --> Esbuild["esbuild"]
TestUnit["vitest"] --> JSDOM["jsdom"]
TestE2E["playwright"] --> Chromium["Chromium"]
ExtDeps["扩展运行时依赖<br/>dompurify/pdfjs/mammoth/xlsx/docx"] --> Runtime["扩展运行时"]
AgentDeps["Agent 依赖<br/>ws/archiver/zod/xlsx"] --> AgentRuntime["Agent 运行时"]

图示来源

章节来源

性能与优化 ​

  • 关闭 sourcemap：构建阶段禁用 .map，避免产物体积膨胀与源码泄露。
  • 内容脚本 IIFE 化：减少动态 import 与跨 iframe 注入开销，提升稳定性。
  • 静态资源直拷：libs/styles/icons/_locales 直接复制到 dist/，避免不必要的打包。
  • 增量构建缓存：CI 使用 npm cache，加速依赖安装。
  • 产物瘦身：fix-build.js 清理 vendor、dev fallback、重复文件与 loading-page 等无用产物。
  • 文档部署优化：使用 git subtree push，避免全仓推送。
  • 文档站点响应式优化：导航断点从 1150px 调整到 1200px，提供更好的中等屏幕显示效果，确保导航链接在不同设备上的最佳展示。

[本节为通用指导，不直接分析具体文件]

故障排查 ​

  • 构建失败：
    • 检查 vite.config.js 的入口与插件配置是否正确。
    • 查看 scripts/silent-build.js 的输出，确认 npm run build 是否成功。
  • 内容脚本无法注入：
    • 确认 fix-build.js 已将 content script 打包为 content-iife.js，并在 manifest.json 中正确引用。
    • 检查 web_accessible_resources 是否包含 content-iife.js 与 background 文件。
  • 侧边栏加载失败：
    • 确认 side_panel.html 已注入 side_panel.js 的 script 标签。
    • 检查 service-worker-loader.js 是否指向正确的 background 文件。
  • 商店审核拒绝远程代码：
    • 确认 fix-build.js 已修补 jspdf.min.js 中的远程 URL。
  • Gitee 发布失败：
    • 检查 GITEE_TOKEN 权限（需勾选 projects）。
    • 注意 Gitee API 对不存在 tag 返回 200 + null，必须判 id 而非状态码。
  • 安装器问题：
    • 在 Windows 上验证 install.ps1 的 param/env 回退与 irm|iex 语义。
    • 在 Unix 上验证 curl|bash 等价安装命令与 AGENT_VERSION 环境变量。
  • 版本管理问题：
    • 确认所有版本文件（package.json、manifest.json、version.json）保持一致的 2.4.1 版本号。
    • 检查 agent/publish.sh 的版本同步逻辑是否正常工作。
    • 验证 npm 认证配置是否正确，确保发布流程顺畅。
  • 文档站点问题：
    • 确认技术文档站点为中文专用，包含完整全文搜索功能。
    • 检查导航断点配置（1200px）是否影响移动端显示效果。
    • 验证 RepoWiki 离线搜索功能是否正常工作。

章节来源

结论 ​

本项目通过 Vite + @crxjs/vite-plugin 构建了稳定的 MV3 扩展产物，并通过 fix-build.js 解决了插件生态的已知问题。CI 流水线实现了从构建、打包到多平台发布的自动化，增强的 Agent 发布脚本确保了单一版本流的严谨性与可回滚性，特别是在 v2.4.1 版本中提供了更完善的版本一致性保证。文档部署与多远端推送脚本提升了协作效率与交付可靠性。整体构建与部署体系兼顾安全性、可维护性与可扩展性，新版本的管理流程进一步提升了发布过程的稳定性和可预测性。技术文档站点现已明确为中文专用，并提供完整的离线全文搜索功能，为用户提供了更好的文档体验。

[本节为总结性内容，不直接分析具体文件]

附录：本地构建与部署指南 ​

  • 开发环境搭建：
    • 安装 Node.js（建议 22，与 CI 一致）。
    • 执行 npm ci 安装依赖。
  • 开发与预览：
    • 运行 npm run dev 启动 Vite 开发服务器（端口 5173）。
    • 在 Chrome 中加载 dist/ 进行调试（开发者模式 → 加载已解压的扩展程序）。
  • 构建与打包：
    • 执行 npm run build 生成 dist/，并自动运行 fix-build.js。
    • 执行 npm run package 生成 ai-helper@<version>.zip（用于 Chrome Web Store）。
  • 测试：
    • 单元测试：npm run test:unit（vitest）。
    • 端到端测试：npm run test:e2e（Playwright）。
    • 统一构建验证：npm run build:silent。
  • 发布：
    • 扩展端：推送 v* 标签触发 GitHub Actions，自动生成 GitHub Release 与 Gitee Release。
    • Agent 端：执行 npm run release:agent（或 bash agent/publish.sh），按提示完成版本升级、构建与发布。新版本流程提供更详细的版本一致性检查和错误处理。
  • 文档部署：
    • 执行 bash scripts/deploy-pages.sh 将 docs/ 推送到 gh-pages 分支。
    • 或使用 npm run push:all 一键推送所有远端并部署文档。
  • 技术文档站点：
    • 中文专用技术文档站点提供完整的 RepoWiki 技术文档，支持离线全文搜索和侧边栏树形导航。
    • 访问地址：https://xiweicheng.github.io/ai-helper/wiki/
    • 维护者可通过 npm run build:docsite 构建，本地预览使用 npm run preview:docsite。

章节来源