Metadata-Version: 2.4
Name: ai-sys-tools
Version: 1.0.0
Summary: 445 个 Windows/桌面/网络实用工具（图片/文件/视频/网页/请求下载/截图/录音/窗口/进程/内存磁盘CPU GPU 清理/NTP 校时/系统控制），每个函数带 rag 工具注册元数据（五段描述）。
Author-email: Lb <3204624858@qq.com>
License: MIT
Project-URL: Homepage, https://pypi.org/project/ai-sys-tools/
Project-URL: Source, https://pypi.org/project/ai-sys-tools/
Project-URL: Documentation, https://pypi.org/project/ai-sys-tools/
Keywords: tools,windows,automation,screenshot,process,cleanup,ntp,rag,tool-registry,agent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: curl_cffi>=0.7.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: psutil>=5.9.0
Provides-Extra: gpu
Requires-Dist: torch>=2.0; extra == "gpu"

# ai_sys_tools —— 核心实用工具库

> **445 个真实可用的 Python 工具**（按 26 个功能分类模块组织），每个工具均为**可导入 / 可 CLI 调用**的函数，并携带符合 `rag_system/docs/格式规范.md` 五段模板的**工具注册元数据**（`name` / `description` 含 功能关键词/别名锚点/示例查询/标识 / `parameters` / `examples`）——元数据可直接喂给工具注册表（`register_any([...])`）。

- 包名（PyPI）：**`ai-sys-tools`** ｜ 导入名：**`ai_sys_tools`** ｜ 版本：`1.0.0`
- 命令行：`ai-sys-tools`

## 安装

```bash
pip install ai-sys-tools
# 需要 GPU 显存缓存释放工具（调用 torch.cuda.empty_cache）时：
pip install "ai-sys-tools[gpu]"
```

> 本机开发态（仓库内）直接 `python main.py …` 亦可，`src` 为模块根。

## 快速开始

```bash
ai-sys-tools list                       # 模块与工具数
ai-sys-tools search 缩略图               # 检索工具
ai-sys-tools registry --out registry.json   # 导出注册表 JSON
ai-sys-tools meta file_read_text        # 查看某工具五段元数据
ai-sys-tools run text_util.txt_b64_encode --kv text=hello
ai-sys-tools check                      # 全库唯一性 + 元数据合规检查
```

```python
from ai_sys_tools import file_tools, text_util, img_proc, http_req, sys_ctl
print(file_tools.file_read_text("D:/data/a.txt", encoding="utf-8"))
```

## Python 导入使用

```python
from ai_sys_tools import overlay_ctl, file_tools, process_ctl
r = overlay_ctl.ovl_shield_show(opacity=0.85, text="勿动", duration_seconds=3, wait=True)
r = overlay_ctl.ovl_shield_show(lock_input=True, text="锁定10秒", duration_seconds=10, wait=True)
r = file_tools.file_read_text("D:/data/a.txt", encoding="utf-8")
r = process_ctl.proc_list()
# 全部函数返回结构化 dict {ok:…}；失败带中文 reason，不抛异常
```

## 工具注册（接入 rag 工具注册表）

```python
from ai_sys_tools._infra import load_src_modules, all_tools
load_src_modules()          # 逐个 import 触发 @tool 注册
metas = all_tools()         # 445 条五段元数据
# ag.register_any(metas, enforce_spec=True, dedup=False)
```

## 总览表

| # | 分类 | 模块 | 工具数 | 代表工具 |
|---|------|------|-------:|----------|
| 1 | CPU 监控/负载治理 | `cpu_cln` | 14 | `cpu_arch, cpu_count_logical, cpu_count_physical …` |
| 2 | GPU 监控/清理 | `gpu_cln` | 15 | `gpu_cleanup_idle, gpu_compute_processes, gpu_driver_version …` |
| 3 | PC 客户端/窗口控制 | `window_ctl` | 21 | `wnd_activate, wnd_close, wnd_close_by_pid …` |
| 4 | Win10/Win11 系统控制 | `sys_ctl` | 52 | `sys_battery_status, sys_bios_info, sys_clipboard_get_text …` |
| 5 | cmd/PowerShell 执行 | `exec_cmd` | 5 | `exe_cmd, exe_cmd_detached, exe_cmd_output …` |
| 6 | 下载/请求（curl_cffi、防风控） | `http_req` | 17 | `http_check_url, http_download, http_download_many …` |
| 7 | 内存清理/监控 | `mem_cln` | 8 | `mem_available_mb, mem_clean_current, mem_report …` |
| 8 | 压缩/归档 | `archive_util` | 14 | `arc_compress_detect, arc_estimate_size, arc_gunzip_file …` |
| 9 | 哈希/密码学实用 | `crypto_util` | 16 | `crypt_hash_text, crypt_hmac_compare, crypt_hmac_text …` |
| 10 | 图片处理 | `img_proc` | 36 | `img_auto_contrast, img_blur_gaussian, img_border_pad …` |
| 11 | 局域网扫描发现 | `lan_scan` | 7 | `lan_arp_mac, lan_arp_table, lan_default_gateway …` |
| 12 | 屏幕保护层/防干扰罩（含键鼠锁） | `overlay_ctl` | 3 | `ovl_shield_hide, ovl_shield_list, ovl_shield_show` |
| 13 | 屏幕截图 | `screen_shot` | 10 | `shot_capture_active_window, shot_capture_region …` |
| 14 | 录音/播放/音量 | `audio_rec` | 17 | `aud_concat_wavs, aud_generate_silence, aud_generate_tone …` |
| 15 | 文件与目录处理 | `file_tools` | 33 | `dir_copy_tree, dir_create, dir_delete …` |
| 16 | 文本/编码处理 | `text_util` | 32 | `txt_b64_decode, txt_b64_encode, txt_case …` |
| 17 | 时间/NTP 校时 | `time_ntp` | 17 | `ntp_best_query, ntp_build_request, ntp_calibrate …` |
| 18 | 桌面操作（复制/粘贴/撤销） | `op_ctrl` | 14 | `op_clipboard_clear, op_clipboard_get, op_clipboard_list …` |
| 19 | 磁盘清理/监控 | `disk_cln` | 15 | `disk_clean_by_size, disk_clean_logs, disk_clean_old_files …` |
| 20 | 网络实用 | `net_util` | 22 | `net_default_gateway, net_dns_china_servers, net_dns_current …` |
| 21 | 网络测速（多节点） | `net_speed` | 6 | `spd_download_to, spd_mbps, spd_preset_domestic …` |
| 22 | 网页解析/获取 | `web_parse` | 21 | `web_count_words, web_detect_charset, web_extract_emails …` |
| 23 | 蓝牙（列表/串口/收发） | `bt_ctl` | 10 | `bt_adapter_list, bt_adapter_status, bt_com_exchange …` |
| 24 | 视频处理 | `video_proc` | 15 | `vid_concat, vid_convert, vid_cut …` |
| 25 | 进程管理 | `process_ctl` | 19 | `proc_close, proc_count_by_name, proc_exists …` |
| 26 | 防火墙端口/规则管理 | `firewall_ctl` | 6 | `fw_port_allow, fw_port_block, fw_rule_delete …` |

**合计：26 个分类模块，445 个工具。**

## 约定

- 环境：Python ≥ 3.10（主力开发/测试 3.12）；依赖：`curl_cffi`（全部下载/请求）、`Pillow`（图片/截图）、`psutil`（进程/内存/磁盘）；`torch` 可选（仅 `gpu_cleanup_torch_cache` 用，缺失时返回 `err`）。
- 平台：绝大多数工具面向 Windows（ctypes / winreg / netsh / PowerShell）；`file_tools`、`text_util`、`crypto_util`、`archive_util`、`web_parse`、`net_util`、`time_ntp` 等为纯标准库实现，跨平台可用。
- 每个函数返回结构化 `dict`：成功 `{"ok": true, ...}`；失败/环境不允许 `{"ok": false, "reason": "中文原因"}`（不抛异常）。
- 破坏性/治理类函数一律 `dry_run=True` / `confirm=False` / `apply=False` 默认；系统电源类需显式 confirm 才执行。
- 模块文件只含 docstring/import/函数/模块尾 CLI；无类；工具名按分类前缀（`file_/img_/vid_/web_/http_/shot_/aud_/wnd_/proc_/mem_/disk_/cpu_/gpu_/ntp_/sys_/net_/txt_/crypt_/arc_/ovl_/bt_/lan_/spd_/exe_/fw_/op_`）保证全库唯一。

## 源码仓库内的构建产物

- `registry/tool_registry.json`：全量工具注册元数据（`python -X utf8 build_registry.py` 重新生成）。
- `main.py`：仓库内聚合入口（list / search / registry / meta / run / check）。
- `src/_infra.py`：基础设施（ok/err、`@tool` 注册、五段描述组装、CLI 支撑）。

## 发布

```bash
python -m build                       # 产出 dist/ai-sys-tools-1.0.0.{tar.gz,whl}
python -m twine upload dist/*         # 凭据取自 ~/.pypirc（token）
```
