Files

T

LingandRX 7167a43763 Develop (#25 )

核心功能新增
工具套件扩展
JSON 工具（差异比较、格式化、转 YAML/TOML、压缩）
Base64 转换器（文本/文件/图像编解码）
Markdown ↔ HTML 双向转换
JWT 解析器
文本统计工具
二维码生成/解析（替换库以减小体积）
表单工具（已移除）
表单映射、智能填充、高亮定位功能已移除
架构与工程改进
技术栈升级
引入 @webext-core/messaging 重构消息通信
添加 @dnd-kit 支持功能列表拖拽排序
引入 i18next 实现中英文国际化
使用 MUI 主题系统替代硬编码样式，支持暗色模式
代码质量
统一组件导出为默认导出
提取公共组件（TextInputArea、SwitchButtonGroup、PageHeader、DecodeResultPaper）
使用 useStorageState 钩子统一管理存储状态
添加 PageErrorBoundary 页面级错误边界
实现组件懒加载优化首屏性能
关键重构
路由系统重构 — 支持独立标签页模式，合并路由与功能配置
状态管理优化 — 存储状态增加快照机制、验证器和防抖处理
剪贴板与打印工具 — 统一为 async/await 形式，修复重复触发问题
存储清理器 — 使用 TextEncoder 准确计算 UTF-8 字节数，支持 TB 单位
测试与 CI
测试覆盖 — 为新增工具、公共组件、边界场景补充单元测试
CI 精简 — 移除 Firefox 测试，仅保留 Chrome；修正类型检查命令

2026-05-20 19:55:49 +08:00

5.4 KiB

Raw Blame History

AGENTS.md

This file provides guidance to AI agents (such as Gemini, Codex, etc.) when working with the code in this repository.

项目概述

Testing Tools 是一个基于 WXT (Web Extension Toolkit) 框架的现代化浏览器扩展项目. 它提供了一系列实用的开发和测试工具，包括时间戳转换、存储管理、文本统计、JWT 解析及二维码工具.

核心命令

开发与构建

npm run dev - 启动 Chrome 浏览器的开发模式（支持 HMR）
npm run dev:firefox - 启动 Firefox 浏览器的开发模式
npm run build - 构建 Chrome 浏览器的生产版本
npm run build:firefox - 构建 Firefox 浏览器的生产版本
npm run zip - 打包 Chrome 扩展为 ZIP 文件
npm run zip:firefox - 打包 Firefox 扩展为 ZIP 文件
npm run typecheck - 执行 TypeScript 类型检查（tsc --noEmit）
npm run lint - 运行 ESLint 静态代码检查

测试

npm run test - 运行所有单元测试（单次执行）
npm run test:watch - 启动 Vitest 交互式监视模式
npm run test:coverage - 运行测试并生成代码覆盖率报告

运行单个测试文件：

npx vitest run path/to/your.test.ts

依赖管理

npm install - 安装项目依赖
postinstall 钩子会自动运行 wxt prepare 以生成必要的类型定义和入口点.
prepare 钩子会自动初始化 Husky 以进行 Git 提交前检查.

项目架构与目录结构

技术栈

框架: WXT v0.20.6 (Web Extension Toolkit)
前端: React 19 + TypeScript 5
UI 库: Material UI (MUI) @7.x + Emotion
日期处理: dayjs (集成 UTC 和 Timezone 插件)
通信: @webext-core/messaging (用于 Entrypoints 间通信)
测试: Vitest + Testing Library (jsdom 环境)
代码规范: ESLint v9 + Prettier + Husky + lint-staged

目录结构

├── components/           # 原子级 UI 组件
│   ├── __tests__/        # 组件单元测试
│   ├── PageHeader.tsx    # 标准页面头部
│   ├── ToolCard.tsx      # 仪表盘卡片基础
│   └── ...
├── config/               # 核心配置与元数据
│   ├── features.tsx      # 功能特性定义（路由与元数据的单一事实来源）
│   ├── pageTheme.ts      # 页面级主题与样式常量
│   └── theme.ts          # MUI 全局主题配置
├── entrypoints/          # 浏览器扩展入口点
│   ├── background.ts     # 后台 Service Worker (消息中转与生命周期)
│   ├── content.ts        # 注入页面的内容脚本
│   ├── popup/            # 弹窗界面主入口
│   ├── options/          # 选项页面主入口
│   └── sidepanel/        # 侧边栏界面主入口
├── pages/                # 功能模块页面组件
│   ├── DashboardPage.tsx # 仪表盘/首页
│   ├── Jwt/index.tsx       # JWT 解析工具
│   ├── QrCode/index.tsx    # 二维码工具
│   ├── StorageCleaner/index.tsx # 存储清理工具
│   ├── TextStatistics/index.tsx # 文本统计工具
│   └── Timestamp/index.tsx # 时间戳转换工具
├── providers/            # React Context Providers (Router, Theme 等)
├── utils/                # 业务逻辑与工具函数
│   ├── chromeStorage.ts  # 类型安全的 Chrome Storage 封装
│   ├── jwt.ts            # JWT 解析逻辑
│   ├── textStatistics.ts # 文本分析逻辑
│   └── ...
├── types/                # 全局 TypeScript 类型声明
└── public/               # 静态资源 (图标等)

核心功能说明

1. 路由与功能发现

项目不使用传统的 React Router，而是通过 config/features.tsx 中的 FEATURES 数组统一管理.

每个功能都有一个唯一的 PageType (如 timestamp, jwt).
RouterProvider 负责维护当前的页面状态，并根据 FEATURES 配置渲染对应的组件.

2. 存储管理 (Chrome Storage)

统一使用 utils/chromeStorage.ts 及其对应的 Hook.
所有的存储键值必须在 types/storage.d.ts 的 StorageSchema 中定义，以确保存储的类型安全.

3. 消息通信 (Messaging)

使用 @webext-core/messaging 进行 Popup, Sidepanel, Background 和 Content Script 之间的通信.
消息协议定义在 utils/messages.ts 中.

4. 样式系统

基于 MUI v7 的 Box, Stack, Paper 等组件构建.
页面特定的复杂样式应在 config/pageTheme.ts 中统一定义，以保持视觉一致性.

AI 代理开发准则

类型安全: 始终优先使用 TypeScript 接口和类型. 不要使用 any.
组件化: 新功能应拆分为 pages/ 中的页面组件和 components/ 中的通用组件.
单元测试: 每次修改逻辑或添加新功能后，必须在对应的 __tests__ 目录下增加测试用例.
单一事实来源: 功能的添加、修改或删除应首先从 config/features.tsx 开始.
跨浏览器兼容: WXT 处理了大部分差异，但涉及原生 API (如 chrome.cookies) 时，请确保逻辑在 Firefox 和 Chrome 下均有效.
i18n: 目前主要使用中文 UI，但在开发时请注意提取硬编码字符串，以便未来国际化.

权限管理

所有新申请的浏览器权限必须同步更新至 wxt.config.ts 的 manifest.permissions 中.

5.4 KiB Raw Blame History Unescape Escape