# OneTools

**Repository Path**: Wongsir/OneTools

## Basic Information

- **Project Name**: OneTools
- **Description**: 工具合集
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-24
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OneTools

OneTools 把日常生活和工作里要用的软件工具收进同一套系统。打开这一处，就能找到并使用这些工具。

## 定位

- **给谁用：** 需要在日常事务和工作里反复使用一批小工具的人。
- **解决什么：** 这些工具现在分散在不同软件里。OneTools 提供一个统一入口，按用途找到工具并直接使用。
- **系统由什么组成：** 一个宿主，加上若干按同一约定接入的工具。宿主负责入口、导航和工具清单；每个工具只做一件具体的事。
- **当前阶段：** 第一批工具已接入。宿主用本机 Python 列出并启动工具。PDF 转图片调用 Poppler `pdftoppm`，音频剪辑打开 Audacity，绘本素材打包工具负责关联、校验并生成 BuddyGrow 内容包。

## 目录

```text
OneTools/
├── README.md              中文说明（本文件）
├── README.en.md           English overview
├── docs/
│   ├── tool-contract.md   工具如何接入宿主
│   ├── picture-book-pack-workflow.md
│   │                       BuddyGrow 绘本素材制作、审核与发布流程
│   ├── picture-book-audio-contract.md
│   │                       音频 manifest 与客户端播放契约
│   ├── picture-book-classification.md
│   │                       系列、分级、稳定 ID 与分类迁移契约
│   ├── raz-cross-computer-workflow.md
│   │                       RAZ 跨电脑配置、处理、审核和同步入口
│   └── raz-aa-handoff.md   AA 生产基线、校验记录和交接入口
├── shell/                 统一入口。`python shell/onetools.py`
└── tools/                 各个工具模块，一具一目录
    ├── pdf-to-image/      PDF 转图片（Poppler pdftoppm）
    ├── audio-edit/        音频剪辑（Audacity）
    ├── ocr/               PDF 与单张/批量图片 OCR（RapidOCR）
    ├── translate/         通用多语言翻译（离线优先、云端免费额度保护）
    ├── picture-book-pack/ 绘本素材关联、校验、打包与报告
    ├── r2-upload/         已审核内容上传到 Cloudflare R2
    ├── r2-catalog/        生成并显式发布完整绘本目录（独立脚本）
    └── buddygrow-sync/    R2 发布后同步 BuddyGrow 业务目录，支持预览和自动调用
```

## 使用

在仓库根目录执行：

```text
python shell/onetools.py
python shell/onetools.py pdf-to-image 输入.pdf --out 输出目录
python shell/onetools.py audio-edit 录音.wav
python shell/onetools.py ocr 扫描件.pdf --out OCR结果目录
python shell/onetools.py ocr 图片目录 --recursive --out OCR批量结果目录
python shell/onetools.py translate "Hello." --from en --to zh
python shell/onetools.py picture-book-pack --source 绘本素材目录 --out 输出目录 --strict --audio-layout per-page
python shell/onetools.py r2-upload --dry-run
```

Poppler 放在 `tools/pdf-to-image/poppler/`，Audacity 放在 `tools/audio-edit/Audacity/`。这两个本地程序目录不提交到 Git。

独立 OCR 工具支持 PDF、单张图片、多文件、目录与通配符批量识别，输出文本及带文字框坐标、置信度的 JSON。它不改动或调用 RAZ 批处理中的 OCR 实现。依赖安装和完整参数见 [OCR 文字识别](tools/ocr/README.md)。

独立 [多语言翻译](tools/translate/README.md) 默认使用已安装的离线模型和本地语言模型，也提供显式 Google 网页、百度及阿里云通用翻译入口。云端密钥保存在系统凭据管理器；百度、阿里云默认额度为 0，确认真实剩余免费余额后才允许发送。它不改动或调用 RAZ 的翻译流程。

建议使用 Python 3.11 项目虚拟环境安装已锁定的绘本打包、OCR 和 R2 工具依赖：

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.lock.txt
```

只安装绘本打包依赖时也可以执行：

```text
python -m pip install -r tools/picture-book-pack/requirements.txt
```

绘本素材的目录规范、关联规则、审核和发布闸门见 [BuddyGrow 绘本素材制作、审核与发布流程](docs/picture-book-pack-workflow.md)。音频字段和 BuddyGrow 播放行为见 [绘本音频 Manifest 契约](docs/picture-book-audio-contract.md)。其他参数见各工具目录下的 `README.md`。

需要在另一台电脑继续 RAZ 处理时，先阅读 [RAZ 跨电脑处理手册](docs/raz-cross-computer-workflow.md)。手册说明本机路径变量、共享 `book-id-registry.json`、审核入口、R2 显式上传闸门以及 Git 同步规则；历史交接文档中的固定路径只作证据，不是当前命令入口。

AA/A 双拼 PDF 补源、真实朗读切分、测试图保护与审核恢复见 [AA/A 源素材补充流程](docs/raz-aa-a-source-supplement.md)；R2 发布后同步业务书架见 [BuddyGrow 目录同步](tools/buddygrow-sync/README.md)。

系列和分级采用 `seriesId`、`levelId`，保留旧 `level`；媒体继续按全局稳定 `bookId` 存储，不需要为 RAZ、海尼曼、牛津树或各等级搬迁对象。字段实现、兼容策略、纯分类更新和新系列接入清单见 [绘本分类契约](docs/picture-book-classification.md)，最新 AA 发布目录与审核证据见 [AA 交接说明](docs/raz-aa-handoff.md)。

分类元数据更新不等于客户端已经具备系列/等级筛选。OneTools 已实现字段输出和安全发布，BuddyGrow 仍需在模型、存储、分类刷新和书架筛选中接入这些字段。

阅读媒体后续使用[阅读图与混合音频压缩规范](docs/picture-book-reading-media-compression.md)：原尺寸普通页 q75、细节风险页 q80，64kbps 音频试编码不通过时保留 80kbps；每页/音轨只发布一种最终规格。已实现共享策略、原图风险证据校验、独立质量回执及 R2 升级入口，听力测试小图仍是独立资源。

R2 上传配置从仓库根目录的 `.env` 读取。`.env` 按项目约定正常跟踪；`.env.example` 提供配置字段示例，在另一台电脑使用前应核对本机路径与连接配置。

## Windows 桌面客户端

桌面端计划采用 Python、PySide6、独立工具执行器、PyInstaller 目录式打包和 Inno Setup。
架构、依赖与模型管理、安装升级及 P0-P5 分阶段任务和验收标准见
[Windows桌面客户端设计与开发](docs/Windows桌面客户端设计与开发.md)。
目前已完成设计，桌面端实现尚未开始，现有命令行工具继续使用。

## 接入一个工具

1. 在 `tools/` 下新建目录，目录名使用稳定的英文标识，例如 `tools/unit-convert/`。
2. 按 [docs/tool-contract.md](docs/tool-contract.md) 写好该工具的说明。
3. 宿主只通过这份约定发现和展示工具，不依赖工具内部的实现细节。

## 参与贡献

1. Fork 本仓库
2. 新建 `Feat_xxx` 分支
3. 提交代码
4. 新建 Pull Request