# mytools

**Repository Path**: bytesifter/mytools

## Basic Information

- **Project Name**: mytools
- **Description**: 用python来写一堆工具
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mstool

ModelScope 工具集 - CLI 入口 `tool`，工具逐步添加。

## 项目结构

```
mytools/
├── pyproject.toml              # workspace 根配置（声明子包）
├── packages/
│   ├── mstool/                 # 模型工具库
│   │   ├── pyproject.toml
│   │   └── src/mstool/
│   │       ├── core/
│   │       │   └── config.py   # 全局配置
│   │       └── tools/
│   │           └── download_model.py   # ModelScope 模型下载器
│   ├── cli/                    CLI-Hub · 唯一入口
│   │   ├── pyproject.toml
│   │   └── src/cli/            typer 应用，参数解析 + 单次库调用
│   ├── ocr-engine/             Core-Library · OCR 识别引擎
│   │   ├── pyproject.toml
│   │   └── src/ocr_engine/     基于 PaddleOCR 的文档识别 + 批量编排
│   └── ppocr-scripts/          # PP-OCR 下载工具
│       ├── pyproject.toml
│       └── src/ppocr_scripts/
│           └── download.py     # PP-OCR 离线模型下载
├── docs/                       # 文档
│   ├── getting-started/        # 安装与快速上手
│   ├── user-guide/             # 使用教程与最佳实践
│   ├── developer-guide/        # 架构说明与开发指南
│   └── assets/                 # 静态资源
├── openspec/                   # 开发规范
└── README.md
```

## 快速开始

```bash
# 安装所有子包依赖
uv sync

# 查看帮助
uv run tool --help
```

## 工具列表

| 命令 | 说明 | 来源 |
|------|------|------|
| `tool download-model` | 从 ModelScope 下载模型 | `packages/mstool/` |
| `tool ocr` | 批量 OCR 识别目录中的图片/PDF/Word 文档 | `packages/ocr-engine/` |
| `tool download-ppocr` | 下载 PP-OCR 离线模型（也支持 `uv run download-ppocr` 独立入口） | `packages/ppocr-scripts/` |

## 使用示例

### 下载 ModelScope 模型

```bash
uv run tool download-model --name iic/nlp_gte_sentence-embedding_chinese-base
```

### 批量 OCR 识别

> 初学者请先阅读 [OCR 初学者指南](docs/user-guide/ocr-beginners-guide.md) 了解完整流程。

```bash
# 基本用法：扫描目录中所有支持的文档，输出到 _ocr_output/
uv run tool ocr ./scans/

# 指定输出目录
uv run tool ocr ./scans/ -o ./output/

# 其他配置通过 .env 文件设置（参见 环境配置 章节）
```

> 配置项如 recursive、ext、flatten、preprocess、model_dir、model_variant 等均通过 `.env` 文件管理，CLI 仅保留 input 和 output 参数。

### 下载 PP-OCR 模型

```bash
# 查看可用模型
uv run tool download-ppocr --list

# 下载全部模型
uv run tool download-ppocr --model all

# 仅下载识别模型
uv run tool download-ppocr --model rec

# 指定输出目录
uv run tool download-ppocr --model all --output D:\models\ppocr
```

> 也支持旧独立入口 `uv run download-ppocr`，功能相同。

## 环境配置

项目使用根目录的 `.env` 文件统一管理配置，各包使用前缀命名空间隔离键名：

| 前缀 | 包 | 配置项 |
|------|-----|--------|
| `MSTOOL_` | `mstool` | `MSTOOL_MODEL_DIR` — ModelScope 模型下载目录 |
| `OCR_ENGINE_` | `ocr-engine` | `OCR_ENGINE_MODEL_DIR` — PP-OCR 模型路径 |
| `PPOCR_` | `ppocr-scripts` | `PPOCR_OUTPUT_DIR` — PP-OCR 模型下载输出目录 |

复制 `.env.example` 为 `.env` 后按需修改即可。参见 `docs/getting-started/setup.md` 了解更多。

## 开发

```bash
# 运行测试
uv run pytest

# 在 packages/*/ 下执行 uv add 仅影响对应子包
cd packages/mstool && uv add <依赖>
```