AI Helper 文档中心

主题

代码质量工具 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

引言 ​

本文件面向 AI Helper 项目的代码质量与静态检查体系，覆盖以下目标：

  • ESLint 配置规则说明（JavaScript 语法检查、代码风格规范、自定义规则）。
  • 代码格式化策略（当前仓库未集成 Prettier，给出集成建议与自动修复脚本定位）。
  • 静态分析工具链（ESLint、Vitest 单元测试、Playwright E2E、构建产物校验、安全审计文档）。
  • 持续集成中的质量门禁（Release 流水线、安装器验证流程、失败处理与修复建议）。
  • 代码审查清单（常见陷阱、性能与安全注意事项）。
  • 开发工作流集成（Git Hooks 现状、提交前检查建议、PR 自动化验证建议）。

本项目为双进程架构：Chrome 扩展端（Manifest V3，src/）+ 独立本地代理端 Agent（Node.js，agent/src/server.js 入口）。两端版本号保持同步（2.3.1），文档以该版本为准。

项目结构 ​

与代码质量直接相关的根级配置文件如下：

  • package.json：定义 lint、test、build 等脚本，以及 ESLint 依赖。
  • eslint.config.js：ESLint Flat Config，启用基础规则并排除 agent/node_modules 等目录。
  • vite.config.js：扩展构建配置，关闭 sourcemap，避免源码泄露。
  • vitest.config.js：单元测试配置，限定 test/unit 目录，注入 chrome-mock 与 jsdom-globals。
  • playwright.config.js：E2E 测试配置，使用真实 Chromium，CI 下重试一次。
  • .github/workflows/release.yml：发布流水线，构建、打包、上传 GitHub/Gitee Release。
  • .github/workflows/test-install.yml：安装器全生命周期验证（Windows + Unix 管道执行）。
  • agent/package.json：Agent 包元信息、bin 命令、RAG 依赖字段与 Node 引擎约束。
  • docs/AUDIT_REPORT.md：安全与性能审计报告，提供风险项与建议修复顺序。
graph TB
A["package.json<br/>脚本与依赖"] --> B["eslint.config.js<br/>ESLint 规则"]
A --> C["vitest.config.js<br/>单元测试"]
A --> D["playwright.config.js<br/>端到端测试"]
A --> E["vite.config.js<br/>构建与产物"]
F[".github/workflows/release.yml<br/>发布流水线"] --> E
G[".github/workflows/test-install.yml<br/>安装器验证"] --> H["agent/package.json<br/>Agent 包"]
I["docs/AUDIT_REPORT.md<br/>安全与性能审计"] --> A

图示来源

章节来源

核心组件 ​

本节聚焦代码质量工具链的核心组成部分：ESLint、测试框架、构建产物校验、发布与安装器验证。

  • ESLint

    • 通过 @antfu/eslint-config 引入通用规则集，并在 eslint.config.js 中追加少量强制规则（如禁止 debugger、重复参数、函数赋值、调用非函数等）。
    • 将 agent 子包纳入 lint 范围，但排除 node_modules 与 dist 等目录，避免扫描第三方代码。
    • 未启用 Prettier；如需统一格式，可在 eslint.config.js 中集成 prettier 插件或新增 .prettierrc 并通过 npm script 驱动自动修复。

  • 单元测试（Vitest）

    • 默认运行环境为 node，全局 API 开启，setupFiles 注入 chrome-mock 与 jsdom-globals，使 content/side_panel 相关逻辑可单测。
    • include 限定 test/unit/**/*.test.js，避免误跑 e2e 或其他测试。

  • 端到端测试（Playwright）

    • 使用真实 Chromium，headless 模式，actionTimeout 10s。
    • CI 环境下 retries=1，forbidOnly=true，防止遗漏 xit/fit 标记。

  • 构建与产物校验

    • Vite 构建输出到 dist，sourcemap 关闭，避免源码随包发布。
    • release.yml 在打包 zip 后再次校验不包含 .map 文件，作为第二道防线。

  • 发布与安装器验证

    • release.yml：触发条件为 v* 标签或手动触发；构建扩展、打包 zip、创建 GitHub Release，并尝试同步到 Gitee（可选）。
    • test-install.yml：在 Windows 上验证 install.ps1 的全生命周期（安装、状态、API、更新、卸载、残留检查），并在 Unix 上模拟 curl|bash 管道执行。

章节来源

架构总览 ​

下图展示代码质量工具链在开发与发布阶段的交互关系：开发者提交代码 → 本地脚本（lint/test/build）→ CI 流水线（release/test-install）→ 构建产物与安装器验证。

sequenceDiagram
participant Dev as "开发者"
participant NPM as "npm scripts"
participant ESL as "ESLint"
participant VT as "Vitest"
participant PW as "Playwright"
participant VITE as "Vite 构建"
participant CI as "GitHub Actions"
participant GH as "GitHub Releases"
participant GE as "Gitee Releases"
Dev->>NPM : 执行 lint / test / build
NPM->>ESL : 扫描 src/ 与 agent/
NPM->>VT : 运行 test/unit
NPM->>PW : 运行 e2e可选
NPM->>VITE : 构建 dist
CI->>NPM : 触发 release.yml
CI->>VITE : 构建扩展
CI->>GH : 创建 Release 并上传 zip
CI->>GE : 同步发行版与附件可选

图示来源

详细组件分析 ​

ESLint 配置与规则 ​

  • 规则范围
    • 忽略 dist/、libs/、scripts/、agent/node_modules/、agent/dist/**，避免扫描第三方代码与构建产物。
    • 对 agent 子包启用 lint，补齐历史空白。
  • 自定义规则
    • no-debugger、no-dupe-args、no-func-assign、no-obj-calls 设为 error，用于阻断明显错误与潜在运行时异常。
  • 风格规范
    • 依赖 @antfu/eslint-config 提供基础风格与最佳实践；仓库未显式覆盖更多规则，建议后续按需增强（如 import/order、unicorn 系列、perfectionist 等）。
  • 格式化
    • 未集成 Prettier；若需统一格式，建议在 eslint.config.js 中接入 prettier 插件，或在根目录新增 .prettierrc，并通过 npm script 驱动自动修复。
flowchart TD
Start(["ESLint 启动"]) --> LoadConfig["加载 eslint.config.js"]
LoadConfig --> IgnorePaths["忽略 dist/libs/scripts/agent/node_modules/agent/dist"]
IgnorePaths --> ApplyRules["应用基础规则集 + 自定义 error 规则"]
ApplyRules --> ScanSrc["扫描 src/ 与 agent/"]
ScanSrc --> Report{"发现违规?"}
Report --> |是| Fail["返回非零退出码"]
Report --> |否| Pass["通过"]

图示来源

章节来源

单元测试与端到端测试 ​

  • Vitest
    • globals: true，environment: node，setupFiles 注入 chrome-mock 与 jsdom-globals，include 限定 test/unit。
    • 适用于扩展端与 agent 的纯逻辑模块测试。
  • Playwright
    • testDir: ./test/e2e，fullyParallel: true，CI 下 retries: 1，headless: true，actionTimeout: 10000。
    • 使用 Desktop Chrome 设备配置，适合 UI 与浏览器行为验证。
flowchart TD
TestStart["测试入口"] --> Unit["Vitest 运行 test/unit"]
TestStart --> E2E["Playwright 运行 test/e2e"]
Unit --> Setup["注入 chrome-mock/jsdom-globals"]
Setup --> RunUnit["执行单元用例"]
E2E --> Browser["启动 Chromium"]
Browser --> RunE2E["执行端到端用例"]
RunUnit --> ResultU["汇总结果"]
RunE2E --> ResultE["汇总结果"]

图示来源

章节来源

构建产物与发布流水线 ​

  • Vite 构建
    • outDir: dist，sourcemap: false，避免源码泄露。
    • 多入口：background、content、side_panel、options。
  • Release 流水线
    • 触发：push v* 标签或 workflow_dispatch。
    • 步骤：安装依赖 → 构建扩展 → 校验 dist/manifest.json → 打包 zip（排除 .map）→ 上传 artifact → 创建 GitHub Release → 同步 Gitee（可选）。
    • Gitee 同步包含 tag 推送、发行版创建/更新、附件上传与旧附件清理。
sequenceDiagram
participant Push as "推送 v* 标签"
participant CI as "GitHub Actions"
participant Build as "Vite 构建"
participant Zip as "打包 zip"
participant GH as "GitHub Release"
participant GE as "Gitee Release"
Push->>CI : 触发 release.yml
CI->>Build : npm run build
CI->>Zip : zip dist排除 .map
Zip-->>CI : 校验无 .map
CI->>GH : 创建 Release 并上传 zip
CI->>GE : 同步 tag/发行版/附件可选

图示来源

章节来源

安装器验证流程 ​

  • Windows 全流程
    • 安装 → 校验工件 → aha status + API 连通性 → install.ps1 -Status/-Update/-Uninstall → 残留检查 → 失败时收集日志。
  • Unix 管道执行
    • 模拟 curl|bash 等价方式从 stdin 执行 install.sh，校验安装版本与服务在线。
  • PowerShell iex 探针
    • 验证 param 块经 iex 执行与 $env:AGENT_VERSION 回退语义，确保复制命令的安全性与正确性。
flowchart TD
StartI["开始安装器验证"] --> Win["Windows 全流程"]
StartI --> Unix["Unix 管道执行"]
StartI --> Probe["PowerShell iex 探针"]
Win --> Install["安装并校验工件"]
Install --> Status["aha status + API 连通"]
Status --> Update["install.ps1 -Update"]
Update --> Uninstall["install.ps1 -Uninstall"]
Uninstall --> Residue["残留检查"]
Unix --> Pipe["cat install.sh | AGENT_VERSION=$VER bash"]
Pipe --> Verify["校验版本与服务"]
Probe --> Param["param 块经 iex 执行"]
Param --> Env["$env:AGENT_VERSION 回退"]

图示来源

章节来源

代码格式化与自动修复 ​

  • 现状
    • 仓库未集成 Prettier；ESLint 仅启用基础规则与少量 error 规则。
  • 建议方案
    • 在 eslint.config.js 中接入 @antfu/eslint-config 的格式化能力或新增 prettier 插件。
    • 新增 .prettierrc 定义统一格式（缩进、引号、分号、换行等）。
    • 在 package.json 中添加脚本：
      • "format": "prettier --write ."
      • "lint:fix": "eslint --fix ."
    • 结合 Git Hooks（husky + lint-staged）实现提交前自动修复。

[本节为概念性建议，不直接分析具体文件]

依赖分析 ​

  • 根项目依赖
    • devDependencies 包含 @antfu/eslint-config、eslint、vite、vitest、@playwright/test 等。
    • dependencies 包含 DOMPurify、pdfjs-dist、xlsx 等运行时库。
  • Agent 包依赖
    • main: ./src/server.js，bin: ai-helper-agent、aha。
    • ragDependencies 自定义字段用于 RAG 功能的一键安装，避免全局安装时的 overrides 问题。
    • engines.node >= 18.0.0，确保 Node 版本兼容。
graph LR
Root["根 package.json"] --> ESL["@antfu/eslint-config / eslint"]
Root --> Vite["vite / crxjs"]
Root --> Vitest["vitest"]
Root --> PW["@playwright/test"]
Agent["agent/package.json"] --> SDK["@modelcontextprotocol/sdk"]
Agent --> WS["ws"]
Agent --> Zod["zod"]
Agent --> XLSX["xlsx"]
Agent --> RAG["ragDependenciesvectra/transformers/pdf-parse/mammoth/officeparser/cheerio"]

图示来源

章节来源

性能考量 ​

  • 构建产物体积
    • Vite 构建已关闭 sourcemap，避免源码泄露与体积膨胀。
    • release.yml 在打包 zip 后再次校验不包含 .map 文件。
  • 内容脚本注入
    • 审计报告指出 fix-build.js 向每个 iframe 注入约 1.93 MB 脚本（含 pdf.worker），建议优化注入策略与按需加载。
  • 流式渲染与 DOM 操作
    • 审计报告指出流式渲染每约 30 ms 全量重解析 + 整段 DOM 替换，存在性能瓶颈。
  • Service Worker 保活
    • 周期性定时器阻止空闲回收，建议使用 chrome.alarms 替代 setInterval。
  • 存储写放大
    • 工具统计与审计日志“读全量-改-整写回”，应改为增量写入或批处理。

章节来源

故障排查指南 ​

  • ESLint 失败
    • 检查 eslint.config.js 的 ignores 是否误排了需要扫描的路径。
    • 确认 agent/node_modules 与 agent/dist 被正确忽略，避免第三方代码干扰。
  • 单元测试失败
    • 确认 vitest.config.js 的 include 路径是否正确，setupFiles 是否注入必要 mock。
    • 若涉及 DOM，确保使用 jsdom 环境或文件头注释切换环境。
  • E2E 测试失败
    • 检查 playwright.config.js 的 headless、retries、actionTimeout 设置是否符合 CI 环境。
    • 若网络请求不稳定，考虑增加重试或 Mock。
  • 构建失败
    • 检查 vite.config.js 的 sourcemap 是否被意外开启。
    • 确认 dist/manifest.json 是否存在，release.yml 会校验该文件。
  • 发布失败
    • 检查 GITEE_TOKEN 是否配置，权限是否勾选 projects。
    • 若 Gitee 附件上传失败，查看网络稳定性并重跑流水线。
  • 安装器验证失败
    • Windows：检查 install.ps1 的 param 块与 $env:AGENT_VERSION 回退逻辑。
    • Unix：确认 curl|bash 管道执行语义与版本一致性。

章节来源

结论 ​

本项目已建立基础的代码质量工具链：ESLint 基础规则、Vitest 单元测试、Playwright E2E、Vite 构建与 Release 流水线。当前未集成 Prettier，建议后续补充格式化能力与 Git Hooks 自动化。安全与性能审计报告提供了明确的风险项与修复优先级，可作为后续迭代的重要输入。

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

附录 ​

  • 代码审查清单
    • 常见陷阱
      • 内容脚本注入与 DOM 操作需谨慎，避免破坏页面状态或引入 XSS。
      • Service Worker 生命周期硬约束，避免常驻定时器导致无法回收。
      • Agent 端修改后必须重启进程，新接口才生效。
    • 性能考量
      • 避免全量 DOM 替换与频繁 storage.local 写入。
      • 大依赖（docx、pdfjs）建议动态导入或按需加载。
    • 安全注意事项
      • 内容脚本 Markdown 渲染需消毒（DOMPurify）。
      • 敏感数据（API Key、token）避免明文落盘或 URL query。
      • fetch_url/debug_page 等工具需纳入确认与私网拦截。
  • 开发工作流集成建议
    • Git Hooks：使用 husky + lint-staged，在提交前执行 eslint --fix 与 prettier --write。
    • PR 自动化：在 PR 中触发 npm run lint && npm run test:unit && npm run build:silent，确保代码质量门禁。

[本节为概念性建议，不直接分析具体文件]