# CodeCruncher

**Repository Path**: yu_junwei/code-cruncher

## Basic Information

- **Project Name**: CodeCruncher
- **Description**: 一款强大的浏览器扩展工具，帮助开发者快速处理和管理 JSON、XML 数据。支持格式化、压缩、历史记录、主题切换等功能。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodeCruncher

> JSON/XML 格式化与数据管理 Chrome 扩展

一款强大的浏览器扩展工具，帮助开发者快速处理和管理 JSON、XML 数据。支持格式化、压缩、历史记录、分组管理、主题切换等功能。

[![Chrome Web Store](https://img.shields.io/badge/Chrome%20Web%20Store-安装-blue?logo=googlechrome&logoColor=white)](https://chromewebstore.google.com/detail/codecruncher/fmfdomhdehiblfphdladckimmnnbnaoe?authuser=0&hl=zh-CN)
[![Version](https://img.shields.io/badge/version-1.0.1-green)](./CHANGELOG.md)
[![License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)

## 📦 安装

### 在线安装（推荐）

直接访问 Chrome 应用商店安装：

👉 [CodeCruncher - Chrome Web Store](https://chromewebstore.google.com/detail/codecruncher/fmfdomhdehiblfphdladckimmnnbnaoe?authuser=0&hl=zh-CN)

### 开发者本地安装

1. 克隆仓库：

```bash
git clone https://gitee.com/yu_junwei/code-cruncher.git
cd codecruncher
```

2. 安装依赖：

```bash
npm install
```

3. 构建项目：

```bash
npm run build
```

4. 在 Chrome 中加载扩展：
   - 打开 Chrome，访问 `chrome://extensions/`
   - 开启「开发者模式」
   - 点击「加载已解压的扩展程序」
   - 选择项目的 `dist` 目录

## ✨ 功能特性

### 数据处理

- **JSON 格式化**：一键格式化压缩的 JSON 数据，支持语法高亮和折叠
- **XML 格式化**：支持 XML 数据的格式化和压缩，自动处理转义字符
- **智能格式检测**：自动识别输入数据格式（JSON/XML）
- **大文件支持**：支持处理超过 10MB 的大文件，使用 Web Worker 避免阻塞 UI
- **容错解析**：自动修复 JSON 字符串内的非法控制字符，提升解析成功率

### 历史记录管理

- **自动保存**：格式化/压缩操作自动保存到历史记录
- **手动保存**：支持手动保存并添加备注信息
- **分组管理**：支持创建、编辑、删除分组，灵活组织历史记录
- **多级嵌套**：支持多级子分组，层级结构清晰
- **分组移动**：支持拖拽调整分组顺序，移动分组层级
- **记录归组**：可将历史记录归类到任意分组
- **搜索与过滤**：支持关键词搜索和格式筛选
- **文件大小显示**：清晰显示每条记录的文件大小（KB/MB）
- **大文件标识**：超过 10MB 的文件显示橙色警告标签
- **数据持久化**：使用 IndexedDB 存储，数据不丢失

### 编辑器体验

- **双栏布局**：输入/输出双编辑器，支持水平/垂直切换
- **可调整大小**：支持拖拽调整输入框和输出框的大小，水平/垂直方向均支持
- **主题切换**：支持浅色/深色主题，平滑过渡无卡顿
- **节点高亮**：选中节点时高亮显示，方便定位
- **折叠功能**：支持全部折叠/展开，大文件优化处理
- **拖拽上传**：支持拖拽文件到输入框快速导入
- **响应式设计**：适配不同屏幕尺寸

### 大文件保护

- **保存确认**：超过 10MB 的文件保存前弹出确认对话框
- **备注必填**：大文件保存必须填写备注，便于后续管理
- **风险提示**：明确提示存储空间占用、保存时间等风险

## 🚀 使用说明

### 基本操作

1. **输入数据**：在左侧编辑器输入或粘贴 JSON/XML 数据，或通过文件上传
2. **选择操作**：在工具栏选择「格式化」或「压缩」
3. **查看结果**：右侧编辑器显示处理后的结果
4. **保存记录**：点击「保存」按钮保存到历史记录（可添加备注）

### 快捷键

- `Ctrl/Cmd + Enter`：在备注对话框中快速确认保存
- `Escape`：关闭对话框

### 历史记录管理

- 点击历史记录条目：加载该记录的输入/输出数据
- 悬停显示删除按钮：删除单条记录
- 点击搜索框：搜索历史记录
- 使用格式筛选器：筛选 JSON 或 XML 记录

## 🔧 开发指南

### 技术栈

- **框架**：React 18 + TypeScript
- **构建工具**：Vite 5
- **样式**：TailwindCSS 3
- **编辑器**：CodeMirror 6
- **数据库**：IndexedDB（idb 库）
- **扩展开发**：Chrome Extension Manifest V3

### 项目结构

```
src/
├── components/          # React 组件
│   ├── EditorPanel.tsx      # 编辑器面板（支持拖拽调整大小）
│   ├── HistoryList.tsx      # 历史记录列表
│   ├── HistoryGroup.tsx     # 分组组件（支持多级嵌套）
│   ├── HistoryItem.tsx      # 单条历史记录
│   ├── Toolbar.tsx          # 工具栏
│   ├── SaveDialog.tsx       # 保存备注对话框
│   ├── LargeFileConfirmDialog.tsx  # 大文件确认对话框
│   └── ...
├── services/            # 业务逻辑服务
│   ├── db.ts                # IndexedDB 操作
│   ├── formatter.ts         # 格式化逻辑
│   └── autoSave.ts          # 自动保存服务
├── hooks/               # 自定义 Hooks
│   ├── useDebounce.ts       # 防抖 Hook
│   └── useHistory.ts        # 历史记录 Hook
├── workers/             # Web Worker
│   └── formatter.worker.ts  # 大文件格式化 Worker
├── styles/              # 全局样式
│   └── globals.css          # 全局 CSS 和 CodeMirror 主题
├── types/               # TypeScript 类型定义
│   └── index.ts             # 类型声明
├── utils/               # 工具函数
│   └── constants.ts         # 常量定义
├── App.tsx              # 应用根组件
├── main.tsx             # 入口文件
└── background.ts        # 后台服务 Worker
```

### 开发命令

```bash
# 启动开发服务器（热更新）
npm run dev

# 构建生产版本
npm run build

# 预览生产版本
npm run preview
```

### 配置说明

- **大文件阈值**：`src/utils/constants.ts` 中的 `LARGE_FILE_SAVE_THRESHOLD`（默认 10MB）
- **历史记录数量限制**：`MAX_HISTORY_COUNT`（默认 50 条）
- **主题设置**：存储在 Chrome `storage.local` 中，键名 `codecruncher-theme`

## 📋 版本管理

本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/) 规范，版本号格式为 `MAJOR.MINOR.PATCH`：

- **MAJOR**：不兼容的 API 修改
- **MINOR**：向下兼容的功能新增
- **PATCH**：向下兼容的问题修复

### 发布流程

1. 更新 `package.json` 中的 `version` 字段
2. 在 [CHANGELOG.md](./CHANGELOG.md) 中记录本次变更
3. 提交变更：`git commit -m "release: vX.Y.Z"`
4. 推送并创建对应的 Git Tag：`git tag vX.Y.Z && git push origin vX.Y.Z`

### 更新日志

详细的版本变更记录请查看 [CHANGELOG.md](./CHANGELOG.md)。

## 📝 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📧 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 [Issue](https://gitee.com/yu_junwei/codecruncher/issues)
- 发送邮件：<yujunweiffson@163.com>

---

**CodeCruncher** - 让数据处理更高效 🚀