chore：仓库体积过大（.git 101 MB）& 项目管理规范化建议

# 仓库体积过大（.git 101 MB）& 项目管理规范化建议

## 一、问题描述

当前 `.git` 文件夹体积约为 **101 MB**，且项目管理存在多处不规范现象，导致仓库维护困难、构建不可复现、安全隐患等问题。

---

## 二、仓库体积问题

### 2.1 按文件类型统计（历史累计）

| 类型 | 文件数 | 大小 | 说明 |
|------|--------|------|------|
| `.py` | 349 | 96.3 MB | 所有历史版本的 Python 源文件 |
| **`.dll`** | **101** | **86.1 MB** | ⚠️ PyInstaller 构建产物 |
| `.qm` | 92 | 5.2 MB | Qt 翻译文件（构建产物） |
| `.exe` | 1 | 4.3 MB | ⚠️ 打包好的 Windows 可执行文件 |
| `.json` | 95 | 3.1 MB | locale 文件多版本 |
| `.md` | 144 | 1.9 MB | 文档多版本 |
| `.zip` | 1 | 1.4 MB | base_library.zip（构建产物） |

### 2.2 最大的单个 Blob

| 大小 | 文件路径 |
|------|----------|
| 20.0 MB | `OCCM_v1.1.3/_internal/PyQt5/Qt5/bin/opengl32sw.dll` |
| 6.7 MB | `OCCM_v1.1.3/_internal/PyQt5/Qt5/bin/Qt5Gui.dll` |
| 5.7 MB | `OCCM_v1.1.3/_internal/PyQt5/Qt5/bin/Qt5Core.dll` |
| 5.5 MB | `OCCM_v1.1.3/_internal/python311.dll` |
| 4.3 MB | `OCCM_v1.1.3.exe` |

### 2.3 涉及的历史 Commit

- `e92a2ff` — v1.1.5: Windows 构建改为单文件 exe
- `b65b35d` — v1.1.4: 修复中文用户名导致的 DLL 加载问题

---

## 三、项目管理问题全景

### 3.1 缺少现代 Python 项目配置

| 问题 | 现状 | 影响 |
|------|------|------|
| 无 `pyproject.toml` | 仅用 `requirements.txt` | 不符合 PEP 517/621，无法一行命令安装项目 |
| 无锁文件（lock file） | `requirements.txt` 使用松散版本范围 | CI 构建不可复现，昨天能编今天可能失败 |
| 无虚拟环境规范 | 依赖全局 pip | 不同开发者环境不一致 |

### 3.2 构建产物污染仓库

- `OCCM_v1.1.3/` 目录（~86 MB DLL + 4.3 MB EXE）被提交到 Git
- `.gitignore` 未覆盖 `OCCM_*/` 和 `*.exe`
- 构建产物应通过 GitHub Releases 分发，而非入库

### 3.3 根目录文件混乱

```
OCCM_Dynamic_Lang.spec        ← 6 个 spec 文件堆在根目录
OCCM_Test.spec
OCCM_v1.5.0_Final.spec
OCCM_v1.5.0_Fixed.spec
OCCM_v1.5.0_Test.spec
OCCM_v1.5.0_Test2.spec
opencode_config_manager_fluent_v1.4.5.py  ← 旧版本备份
key.md                                 ← 敏感信息文件
diagnose_macos.sh
install_update.sh
```

问题：
- **6 个 `.spec` 文件**（尝试历史）应移入 `build/` 或清理
- **`opencode_config_manager_fluent_v1.4.5.py`**（642 KB）是旧版本备份，Git 已有历史无需保留
- **`key.md`** 曾包含敏感信息（虽已删除但仍在 Git 历史中）
- 缺少 `src/` 或清晰的包结构

### 3.4 依赖管理混乱

- 两套依赖文件：`requirements.txt` + `requirements_web.txt`，且内容有重叠
- `occm_web/` 内还有独立的 `requirements.txt`
- CI 中混用官方 PyPI 和清华镜像源，版本未锁定
- CI 依赖未与项目依赖统一：
  ```
  # CI 中直接 pip install（不在 requirements.txt 中）
  pip install PyQt5 PyQt-Fluent-Widgets requests pyinstaller
  ```

### 3.5 CI/CD 可维护性差

- `build.yml` 单文件 **735 行**，包含 Windows/macOS/Linux × 桌面版/Web 版 6 条构建线
- 大量重复的 `pip install` 代码块
- 中文注释混入 CI 日志（`运行中 🚀` 等 emoji 输出）
- 无依赖缓存的集中管理

### 3.6 单文件应用难以维护

- `opencode_config_manager_fluent.py` — **24,583 行 / 884 KB**
- 这是项目核心的桌面端代码，但一个文件承载全部逻辑
- 虽然有 `occm_core/` 子包，但主文件仍然过于庞大

---

## 四、建议修复方案

### 4.1 采用 `uv` 管理项目（推荐）

[uv](https://github.com/astral-sh/uv) 是 Astral 出品的极速 Python 包管理器，兼容 pip 的同时提供锁文件和项目管理能力。

**迁移步骤：**

```bash
# 1. 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 初始化 pyproject.toml
uv init --no-workspace --name occm --app --description "OpenCode Config Manager"

# 3. 迁移依赖
uv add PyQt5 PyQt-Fluent-Widgets requests
uv add --group dev pytest hypothesis
uv add --group build pyinstaller
uv add --group web nicegui PyJWT bcrypt uvicorn paramiko
```

**`pyproject.toml` 示例结构：**

```toml
[project]
name = "occm"
version = "1.8.0"
description = "Visual GUI Tool for Managing OpenCode Configuration Files"
requires-python = ">=3.11"
dependencies = [
    "PyQt5>=5.15.0",
    "PyQt-Fluent-Widgets>=1.0.0",
    "requests>=2.25.0",
]

[project.optional-dependencies]
web = ["nicegui>=2.0.0", "PyJWT>=2.8.0", "bcrypt>=4.0.0", "uvicorn>=0.25.0", "paramiko>=3.0.0"]
build = ["pyinstaller>=6.0.0"]
dev = ["pytest>=7.0.0", "hypothesis>=6.0.0"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
    "hypothesis>=6.0.0",
    "ruff>=0.9.0",
]
```

**收益：**
- `uv.lock` 锁定完整依赖树 → CI 构建 100% 可复现
- `uv sync --all-extras` 一行还原开发环境
- 速度比 pip 快 10-100x

### 4.2 清理 Git 历史中的大文件

```bash
# 安装 git-filter-repo
uv tool install git-filter-repo
# 或 pip install git-filter-repo

# 移除构建产物目录
git filter-repo --invert-paths --path OCCM_v1.1.3/ --force

# 移除敏感文件（key.md 历史）
git filter-repo --invert-paths --path key.md --force

# 移除旧版本备份
git filter-repo --invert-paths --path opencode_config_manager_fluent_v1.4.5.py --force

# 垃圾回收
git reflog expire --expire=now --all
git gc --prune=now --aggressive
```

### 4.3 更新 `.gitignore`

```gitignore
# 构建产物
OCCM_*/
*.exe
*.dll
*.so
*.dylib
*.spec
dist/
build/

# 敏感信息
key.md
*.key
*.pem
.env
```

### 4.4 目录结构重组建议

```
OpenCode-Config-Manager/
├── pyproject.toml          # 项目配置 + 依赖声明
├── uv.lock                 # 锁文件
├── README.md
├── LICENSE
├── CHANGELOG.md
├── RELEASE.md
├── .gitignore
│
├── src/
│   └── occm/
│       ├── __init__.py
│       ├── __main__.py          # 入口
│       ├── app.py               # QApplication 启动
│       ├── main_window.py       # 主窗口
│       ├── core/                # occm_core 迁入
│       ├── web/                 # occm_web 迁入
│       └── widgets/             # 自定义组件
│
├── assets/                  # 图标、图片
├── locales/                 # i18n 翻译文件
├── build/                   # 构建脚本、spec 文件
│   ├── windows.spec
│   ├── macos.spec
│   └── linux.spec
├── tests/                   # 测试目录
├── docs/                    # 文档
└── .github/
    └── workflows/
        ├── ci.yml           # CI：lint + test
        └── release.yml      # Release：构建 + 发布
```

### 4.5 CI/CD 拆分优化

将 `build.yml`（735 行）拆分为：

```yaml
# ci.yml — 提交时触发
- lint (ruff)
- test (pytest, matrix: ubuntu/macos/windows × 3.10/3.11/3.12)

# release.yml — 打 tag 时触发
- build-desktop (windows/macos/linux)
- build-web (windows/macos/linux)
- publish-release
```

使用可复用 workflow（`workflow_call`）消除重复：

```yaml
# .github/workflows/_build.yml (可复用)
on:
  workflow_call:
    inputs:
      platform: { required: true, type: string }
      target: { required: true, type: string }  # desktop | web

jobs:
  build:
    runs-on: ${{ inputs.platform }}
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4   # uv 官方 action
      - run: uv sync --extra ${{ inputs.target }}
      - run: uv run python build/${{ inputs.target }}_${{ inputs.platform }}.spec
```

### 4.6 添加代码质量工具

```toml
# pyproject.toml
[tool.ruff]
line-length = 120
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP", "B", "SIM"]

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
```

---

## 五、实施路线图

| 阶段 | 任务 | 优先级 | 预计影响 |
|------|------|--------|----------|
| **P0** | 更新 `.gitignore` 防止继续恶化 | 🔴 紧急 | 阻止仓库继续膨胀 |
| **P0** | 清理 Git 历史（filter-repo） | 🔴 紧急 | .git 从 101MB 降至 <5MB |
| **P1** | 引入 `uv` + `pyproject.toml` | 🟡 高 | 依赖可复现、统一开发环境 |
| **P1** | 清理根目录（spec 文件、旧版本、key.md） | 🟡 高 | 根目录整洁、安全 |
| **P2** | 拆分 CI workflow | 🟢 中 | CI 可维护性提升 |
| **P2** | 添加 ruff + pre-commit | 🟢 中 | 代码风格统一 |
| **P3** | 项目结构重组（src/ 布局） | 🔵 低 | 长期可维护性 |
| **P3** | 拆分主文件（24K 行 → 模块） | 🔵 低 | 降低认知负担 |

---

## 六、预期效果

| 指标 | 现在 | 改善后 |
|------|------|--------|
| `.git` 体积 | 101 MB | < 5 MB |
| 依赖安装 | `pip install -r requirements.txt`（版本不确定） | `uv sync`（锁文件保证一致） |
| 新贡献者上手 | 手动创建 venv + 猜依赖 | `uv sync --all-extras` 一行搞定 |
| CI 构建可复现性 | ❌ 版本浮动 | ✅ lock file 锁定 |
| 根目录文件数 | 30+ | < 15 |
| 代码风格检查 | 无 | ruff 自动 lint |

---

## 七、参考资料

- [uv 官方文档](https://docs.astral.sh/uv/)
- [pyproject.toml 规范 (PEP 621)](https://peps.python.org/pep-0621/)
- [git-filter-repo](https://github.com/newren/git-filter-repo)
- [GitHub: Removing sensitive data](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository)
- [ruff](https://docs.astral.sh/ruff/)


Navigation Menu

chore：仓库体积过大（.git 101 MB）& 项目管理规范化建议 #54

仓库体积过大（.git 101 MB）& 项目管理规范化建议

一、问题描述

二、仓库体积问题

2.1 按文件类型统计（历史累计）

2.2 最大的单个 Blob

2.3 涉及的历史 Commit

三、项目管理问题全景

3.1 缺少现代 Python 项目配置

3.2 构建产物污染仓库

3.3 根目录文件混乱

3.4 依赖管理混乱

3.5 CI/CD 可维护性差

3.6 单文件应用难以维护

四、建议修复方案

4.1 采用 `uv` 管理项目（推荐）

4.2 清理 Git 历史中的大文件

4.3 更新 `.gitignore`

4.4 目录结构重组建议

4.5 CI/CD 拆分优化

4.6 添加代码质量工具

五、实施路线图

六、预期效果

七、参考资料

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

类型	文件数	大小	说明
`.py`	349	96.3 MB	所有历史版本的 Python 源文件
`.dll`	101	86.1 MB	⚠️ PyInstaller 构建产物
`.qm`	92	5.2 MB	Qt 翻译文件（构建产物）
`.exe`	1	4.3 MB	⚠️ 打包好的 Windows 可执行文件
`.json`	95	3.1 MB	locale 文件多版本
`.md`	144	1.9 MB	文档多版本
`.zip`	1	1.4 MB	base_library.zip（构建产物）

大小	文件路径
20.0 MB	`OCCM_v1.1.3/_internal/PyQt5/Qt5/bin/opengl32sw.dll`
6.7 MB	`OCCM_v1.1.3/_internal/PyQt5/Qt5/bin/Qt5Gui.dll`
5.7 MB	`OCCM_v1.1.3/_internal/PyQt5/Qt5/bin/Qt5Core.dll`
5.5 MB	`OCCM_v1.1.3/_internal/python311.dll`
4.3 MB	`OCCM_v1.1.3.exe`

问题	现状	影响
无 `pyproject.toml`	仅用 `requirements.txt`	不符合 PEP 517/621，无法一行命令安装项目
无锁文件（lock file）	`requirements.txt` 使用松散版本范围	CI 构建不可复现，昨天能编今天可能失败
无虚拟环境规范	依赖全局 pip	不同开发者环境不一致

阶段	任务	优先级	预计影响
P0	更新 `.gitignore` 防止继续恶化	🔴 紧急	阻止仓库继续膨胀
P0	清理 Git 历史（filter-repo）	🔴 紧急	.git 从 101MB 降至 <5MB
P1	引入 `uv` + `pyproject.toml`	🟡 高	依赖可复现、统一开发环境
P1	清理根目录（spec 文件、旧版本、key.md）	🟡 高	根目录整洁、安全
P2	拆分 CI workflow	🟢 中	CI 可维护性提升
P2	添加 ruff + pre-commit	🟢 中	代码风格统一
P3	项目结构重组（src/ 布局）	🔵 低	长期可维护性
P3	拆分主文件（24K 行 → 模块）	🔵 低	降低认知负担

指标	现在	改善后
`.git` 体积	101 MB	< 5 MB
依赖安装	`pip install -r requirements.txt`（版本不确定）	`uv sync`（锁文件保证一致）
新贡献者上手	手动创建 venv + 猜依赖	`uv sync --all-extras` 一行搞定
CI 构建可复现性	❌ 版本浮动	✅ lock file 锁定
根目录文件数	30+	< 15
代码风格检查	无	ruff 自动 lint

chore：仓库体积过大（.git 101 MB）& 项目管理规范化建议 #54

Description

仓库体积过大（.git 101 MB）& 项目管理规范化建议

一、问题描述

二、仓库体积问题

2.1 按文件类型统计（历史累计）

2.2 最大的单个 Blob

2.3 涉及的历史 Commit

三、项目管理问题全景

3.1 缺少现代 Python 项目配置

3.2 构建产物污染仓库

3.3 根目录文件混乱

3.4 依赖管理混乱

3.5 CI/CD 可维护性差

3.6 单文件应用难以维护

四、建议修复方案

4.1 采用 uv 管理项目（推荐）

4.2 清理 Git 历史中的大文件

4.3 更新 .gitignore

4.4 目录结构重组建议

4.5 CI/CD 拆分优化

4.6 添加代码质量工具

五、实施路线图

六、预期效果

七、参考资料

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

4.1 采用 `uv` 管理项目（推荐）

4.3 更新 `.gitignore`