PowerShell Scripts Collection

一个功能丰富的 PowerShell 脚本集合，提供各种实用工具和自动化解决方案。

📋 目录

项目概述
安装和设置
核心脚本
媒体处理工具
系统管理工具
开发工具
网络和下载工具
文件管理工具
配置和环境
自动化脚本 (AutoHotkey)
播放器配置
使用说明
贡献指南

🚀 项目概述

本项目是一个综合性的 PowerShell 脚本库，旨在提供各种日常工作和系统管理中常用的自动化工具。脚本涵盖了媒体处理、系统管理、开发辅助、文件操作等多个领域。

主要特性

🔧 模块化设计: 每个脚本都是独立的功能模块
📚 详细文档: 每个脚本都包含完整的帮助文档
🛡️ 安全可靠: 包含权限检查和错误处理
🔄 备份恢复: 重要操作支持备份和恢复功能
🎯 易于使用: 提供丰富的参数和使用示例

🛠️ 安装和设置

完整的跨平台安装指南请参考 docs/INSTALL.md。

快速开始

# 克隆项目
git clone <repository-url>
cd powershellScripts

# 运行安装脚本
# 该脚本会自动配置 PATH 并同步脚本到 bin 目录
.\install.ps1

安装完成后，建议重启终端以使环境变量生效。

脚本管理

本项目使用 Manage-BinScripts.ps1 管理脚本映射，所有脚本源文件位于 scripts/pwsh/ 目录下。

# 手动同步脚本到 bin 目录
.\Manage-BinScripts.ps1 -Action sync

# 清理 bin 目录
.\Manage-BinScripts.ps1 -Action clean

系统要求

Windows PowerShell 5.1 或 PowerShell Core 7.0+ (推荐)
部分功能需要管理员权限
Node.js 环境 (用于 TypeScript 脚本构建)

📦 核心脚本

注意: 运行 install.ps1 后，bin 目录会被添加到 PATH 中，你可以直接在命令行运行脚本名（如 cleanEnvPath），无需加上 .\ 前缀或 .ps1 后缀。以下示例假设环境已正确配置。

🔧 系统环境管理

`cleanEnvPath`

功能: 清理 PATH 环境变量中的无效路径

# 清理用户级 PATH
cleanEnvPath

# 清理系统级 PATH（需要管理员权限）
cleanEnvPath -EnvTarget Machine

# 预览清理操作
cleanEnvPath -WhatIf

# 强制执行并指定备份路径
cleanEnvPath -Force -BackupPath "C:\Backup"

特性:

自动检测无效路径（不存在的目录、无可执行文件的目录）
移除重复路径
检测用户 PATH 与系统 PATH 的重复项
自动备份原始配置
支持 WhatIf 预览模式

`restoreEnvPath`

功能: 从备份文件恢复 PATH 环境变量

# 从指定备份文件恢复
restoreEnvPath -BackupFilePath "C:\backup\PATH_User_20231201_143022.txt"

# 从备份目录选择恢复
restoreEnvPath -BackupDirectory "C:\backup" -EnvTarget User

🏃‍♂️ 脚本执行器

`runScripts`

功能: 类似 npm scripts 的命令执行器

# 执行指定命令
runScripts -CommandName test

# 列出所有可用命令
runScripts -listCommands

# 初始化配置文件
runScripts -init -TemplateName golang

# 启用全局配置
runScripts -CommandName build -enableGlobalScripts

特性:

支持 pre/post 钩子
多种项目模板（golang, rust, nodejs）
自动 Node.js 版本切换
全局脚本配置支持

`install.ps1`

功能: 项目安装和初始化脚本

.\install.ps1

功能:

检查管理员权限
安装必要的 PowerShell 模块（如 Pester）
创建符号链接
加载配置文件

🎬 媒体处理工具

视频处理

`ffmpegPreset`

功能: FFmpeg 视频压制预设工具

# 基本压制
ffmpegPreset -path 'input.flv'

# 使用预设
ffmpegPreset -preset '720p28' -path 'input.flv'

# 批量处理
ls *.flv | % { ffmpegPreset -path $_.Name }

预设选项:

720p: 720p 30fps H.264 编码
720p28: 720p 30fps H.264 CRF28
480p: 480p 30fps H.264 编码
x265: H.265 编码
hevc: H.265 CRF28 编码

`VideoToAudio`

功能: 视频转音频工具

`concatflv`

功能: FLV 文件合并工具

`dvdcompress`

功能: DVD 视频压缩工具

音频处理

`losslessToAdaptiveAudio`

功能: 无损音频转码（优先 AAC，缺失 qaac 时回退 Opus）

图像处理

`pngCompress`

功能: PNG 图片压缩工具

`webpCompress`

功能: WebP 图片压缩工具

播放器配置

`mpv-config`

位置: config/software/mpv

功能: MPV 播放器的高级配置文件和增强脚本集合。

安装:

# 1. 自动安装 mpv (需 Scoop/Homebrew) 并链接配置文件
.\config\software\mpv\install.ps1

# 2. (可选) 安装 uosc 和 thumbfast 插件
.\config\software\mpv\install.ps1 -InstallPlugins

主要特性:

增强脚本:
- mpv-gif.js: 快捷生成 GIF/WebP 动图 (Ctrl+g/G, Ctrl+w/W)
- switch-audio-channel.js: 高级声道控制 (Alt+t 互换, Alt+l/r 单声道)
- audio-playback: 短视频自动循环播放
预设配置: 优化的高质量播放参数

🖥️ 系统管理工具

文件管理

`smallFileCleaner`

功能: 清理小文件工具

# 清理小于 10KB 的文件
smallFileCleaner -limitedSize 10kb

# 仅列出不删除
smallFileCleaner -limitedSize 10kb -noDelete

`folderSize`

功能: 计算文件夹大小

# 计算当前目录大小
folderSize

# 计算指定目录大小
folderSize -path "C:\SomeFolder"

`renameLegal`

功能: 文件名合法化工具

`findLostNum`

功能: 查找丢失的数字序列

系统配置

`syncConfig`

功能: 配置文件同步工具

# 备份配置
syncConfig -Mode backup

# 恢复配置
syncConfig -Mode restore

# 列出配置
syncConfig -Mode list

`proxyHelper`

功能: 代理设置助手

# 为 Git 设置代理
proxyHelper -SetProxyProgram git

# 取消 Git 代理
proxyHelper -UnsetProxyProgram git

🔧 开发工具

代码质量

`pslint`

功能: PowerShell 代码检查工具

`PesterConfiguration`

功能: Pester 测试配置

测试命令:

# 安装/更新 Pester（首次运行测试前建议先执行）
pnpm pester:install

# 仅更新已安装的 Pester
pnpm pester:update

# 快速本地测试（无 Profile、无覆盖率）
pnpm test:pwsh:fast

# QA 子集（供 qa:pwsh 使用）
pnpm test:pwsh:qa

# 串行模式（用于排查卡住的发现阶段）
pnpm test:pwsh:serial

# 调试输出（更详细的发现/执行日志）
pnpm test:pwsh:debug

# 串行 + 详细输出（排查发现阶段卡顿）
pnpm test:pwsh:serial:debug

# 仅跑 profile 相关测试（排查卡住的 profile 测试）
pnpm test:pwsh:profile

# 慢测专项
pnpm test:pwsh:slow

# 全量 + 详细输出
pnpm test:pwsh:detailed

# Host assertions 路径慢测排行（默认不含 coverage）
pnpm test:pwsh:slowest

# 显式 coverage 路径慢测排行
pnpm test:pwsh:coverage:slowest

# 显式 coverage 验证（推荐）
pnpm test:pwsh:coverage

# Host 完整测试（兼容保留，当前等价于 coverage）
pnpm test:pwsh:full

# Host 完整断言（不含 coverage，与 all 的 host 路径一致）
pnpm test:pwsh:full:assertions

# 首次运行前构建 Linux 测试镜像
pnpm test:pwsh:linux:build

# Linux 容器快速测试
pnpm test:pwsh:linux:fast

# Linux 容器完整测试
pnpm test:pwsh:linux:full

# 提交前并发执行 host assertions + Linux full
pnpm test:pwsh:all

当前 pnpm test:pwsh:linux:full 聚焦 Linux 容器内的 full 断言回归；默认 pnpm test:pwsh:all 改为走 host pnpm test:pwsh:full:assertions + Linux pnpm test:pwsh:linux:full，以避免把 host coverage 收尾继续留在提交前关键路径里。

本地 coverage 由 pnpm test:pwsh:coverage 提供； pnpm test:pwsh:full 当前作为兼容保留入口，等价于 pnpm test:pwsh:coverage，以规避容器内 Pester coverage 收尾异常，并避免现有工具链一次性断裂。

test:pwsh:* 只负责 root PowerShell / Pester 测试；qa / qa:all 仍是快速质量门。若改动涉及 scripts/pwsh/**、profile/**、psutils/**、tests/**/*.ps1、PesterConfiguration.ps1 或 docker-compose.pester.yml，提交前执行 pnpm test:pwsh:all。如需显式验证 coverage 门槛，额外执行 pnpm test:pwsh:coverage。如果本机 Docker 不可用，至少执行 pnpm test:pwsh:full，并依赖 CI 或 WSL 补 Linux 断言验证。

格式化命令:

# 仅格式化 Git 改动文件（默认）
pnpm format:pwsh

# 全量格式化
pnpm format:pwsh:all

# 严格回退模式（开启 --strict-fallback）
pnpm format:pwsh:strict

# Rust 快速链路（Git 改动 + write + strict fallback）
pnpm format:pwsh:rs

# Rust 快速链路全量模式
pnpm format:pwsh:rs:all

# Rust 快速链路校验模式（发现需修复时返回非零）
pnpm check:pwsh:rs

默认 format:pwsh 与 format:pwsh:strict 均通过脚本入口调用 pwshfmt-rs；其中 format:pwsh:strict 会额外开启 --strict-fallback，用于不安全语法场景回退严格链路。

pwshfmt-rs（projects/clis/pwshfmt-rs）当前覆盖命令名与参数名的 casing correction，采用子命令 check/write，并支持 --git-changed、--path、--recurse 与 --strict-fallback；同时保证字符串字面量、注释不被修改，以及 no-op 文件不写盘。

统一 QA 命令:

# 默认：仅对 Git 变动的包执行 qa（含 pwshfmt-rs）并按需执行 root qa:pwsh
pnpm qa

# 全量：执行所有包 qa + root qa:pwsh
pnpm qa:all

# 详细日志（排查过滤与命令执行路径）
pnpm qa:verbose
pnpm qa:all:verbose

默认 pnpm qa/pnpm qa:all 使用聚合输出（更便于定位失败包）；如需查看每一步执行细节与变更探测过程，请使用 qa:verbose。

pnpm qa 不等价于 pnpm test:pwsh:all。前者用于快速质量门，后者用于 pwsh 相关改动的提交前跨环境完整验证。

如需修改“变动基线分支”，可在执行前设置 QA_BASE_REF（默认 origin/master）。

Turbo QA 命令（V2 并行入口）:

# 默认：Turbo affected 模式 + 按需执行 root qa:pwsh
pnpm turbo:qa

# 全量：Turbo 执行所有 workspace 包 qa + root qa:pwsh
pnpm turbo:qa:all

# 详细日志
pnpm turbo:qa:verbose
pnpm turbo:qa:all:verbose

turbo:qa 会将 QA_BASE_REF（默认 origin/master）映射为 TURBO_SCM_BASE，以保持与现有 pnpm qa 的基线语义一致。

turbo:qa* 默认会执行细粒度任务链路 typecheck:fast -> check -> test:fast，并在 turbo.json 中配置依赖与缓存边界。

可选远程缓存默认关闭；在 CI 中可通过 TURBO_REMOTE_CACHE=1 启用。启用时需要同时提供 TURBO_TOKEN 与 TURBO_TEAM。

Turbo QA 基准采样（CI 趋势）:

# 采集 cold/warm/changed 三类样本，并写入 artifacts/qa-benchmarks
pnpm qa:benchmark

# 指定输出目录
pnpm qa:benchmark -- --output-dir /tmp/qa-benchmarks

# 单独对比帮助搜索的自定义解析与 Get-Help 路径
pnpm benchmark -- help-search

输出包含：

latest.json（最新一次采样）
qa-benchmark-<timestamp>.json（带时间戳历史样本）
summary.md（可直接在 CI artifact 中查看）

pnpm benchmark -- help-search 属于诊断 / 性能比较入口，用于观察 Search-ModuleHelp 的两条实现路径在当前环境下的差异；它不属于默认 pnpm test:pwsh:all 提交门禁的一部分。

CI 中已提供独立工作流 .github/workflows/qa-benchmark.yml，用于单独执行并上传 QA 基准采样结果，避免影响常规测试流水线。

在 CI 中使用 --affected 时，建议 actions/checkout 配置 fetch-depth: 0，避免因浅克隆导致 affected 误判。

版本控制

`gitconfig_personal`

功能: Git 个人配置设置

IDE 和编辑器

`Setup-VSCodeSSH`

功能: VS Code SSH 配置工具

`DownloadVSCodeExtension`

功能: VS Code 扩展下载工具

`get-SnippetsBody`

功能: 代码片段提取工具

🌐 网络和下载工具

`downGithub`

功能: GitHub 仓库下载工具

`downWith`

功能: 通用下载工具

📁 文件格式处理

`ExtractAss`

功能: ASS 字幕文件提取

`concatXML`

功能: XML 文件合并

`ConventAllbyExt`

功能: 按扩展名批量转换文件

🐳 容器和服务

`start-container`

功能: 容器启动工具

`Start-Bee`

功能: Bee 服务启动工具

📊 数据处理

`jupyconvert`

功能: Jupyter Notebook 转换工具

`tesseract`

功能: OCR 文字识别工具

🧹 清理工具

`cleanTorrent`

功能: 种子文件清理工具

`dlsiteUpdate`

功能: DLsite 更新工具

⌨️ 自动化脚本 (AutoHotkey)

位于 scripts/ahk 目录下，提供了一系列 Windows 自动化脚本。

`capslock.ahk`

功能: CapsLock 增强工具，提供 VIM 风格的光标移动和快捷键。

`switchIME.ahk`

功能: 自动切换输入法状态，保持特定应用下的输入法一致性。

`myHotString.ahk`

功能: 自定义热字符串，快速输入常用文本。

`win.ahk`

功能: 窗口管理增强工具。

`base.ahk`

功能: 基础库文件，被其他脚本引用。

📚 使用说明

获取帮助

每个脚本都包含详细的帮助信息：

# 查看脚本帮助
Get-Help scriptName -Full

# 查看参数说明
Get-Help scriptName -Parameter *

# 查看使用示例
Get-Help scriptName -Examples

执行策略

如果遇到执行策略限制，可以临时设置：

# 设置执行策略（管理员权限）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 或者绕过执行策略
powershell -ExecutionPolicy Bypass -Command scriptName

模块依赖

项目包含 psutils 模块，提供通用功能：

# 导入模块
Import-Module "$PSScriptRoot\psutils" -Force

🤝 贡献指南

代码规范

文档: 每个脚本必须包含完整的帮助文档
参数: 使用 [CmdletBinding()] 和适当的参数验证
错误处理: 包含适当的错误处理和用户提示
测试: 为新功能编写 Pester 测试

提交规范

使用清晰的提交信息
遵循现有的代码风格
更新相关文档

目录结构

powershellScripts/
├── psutils/                 # 通用工具模块
├── profile/                 # PowerShell 配置文件
├── config/                  # 配置文件
├── templates/               # 脚本模板
├── ai/                      # AI 相关工具
├── linux/                   # Linux 特定脚本
├── macos/                   # macOS 特定脚本
├── deprecated/              # 已弃用的脚本
├── .trae/                   # Trae 配置
├── .vscode/                 # VS Code 配置
└── *.ps1                    # 主要脚本文件

📄 许可证

本项目采用 LICENSE 许可证。

📦 PSUtils 模块

本项目包含一个功能丰富的 PowerShell 实用工具模块 PSUtils，提供各种常用函数和工具。

🚀 快速开始

# 导入 PSUtils 模块
Import-Module .\psutils\psutils.psd1

# 查看所有可用函数
Get-Command -Module psutils

# 示例：检测操作系统
$os = Get-OperatingSystem
Write-Host "当前操作系统: $os"

🔧 主要功能

环境变量管理: .env 文件处理和环境变量操作
字符串处理: 文本分析和字符串工具
操作系统检测: 跨平台系统识别
网络工具: 端口检查和连接测试
对象存储工具: 阿里云 OSS 上下文创建、对象检查与上传
模块管理: PowerShell 模块安装和检测
通用函数: 命令历史、快捷方式创建等实用工具
错误处理: 统一的异常管理
媒体工具: FFmpeg 相关功能
系统工具: 字体、硬件、代理等系统管理功能

📚 详细文档

查看 PSUtils 模块文档了解完整的功能列表、使用示例和 API 参考。

🔗 相关链接

注意: 使用这些脚本前请仔细阅读每个脚本的帮助文档，某些操作可能会修改系统配置或删除文件。建议在测试环境中先行验证。

Name		Name	Last commit message	Last commit date
Latest commit History 1,557 Commits
.claude		.claude
.codex/skills		.codex/skills
.gemini		.gemini
.github		.github
.husky		.husky
.promptx		.promptx
.serena		.serena
.trae		.trae
.vercel		.vercel
.vscode		.vscode
ai		ai
config		config
deprecated		deprecated
docs		docs
ipynb		ipynb
linux		linux
macos		macos
openspec		openspec
profile		profile
projects/clis		projects/clis
psutils		psutils
scripts		scripts
shell		shell
templates		templates
tests		tests
todos		todos
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.mcp.json		.mcp.json
.rumdl.toml		.rumdl.toml
AGENTS.md		AGENTS.md
AI-INDEX.md		AI-INDEX.md
CLAUDE.md		CLAUDE.md
Dockerfile.pester		Dockerfile.pester
LICENSE		LICENSE
Manage-BinScripts.ps1		Manage-BinScripts.ps1
PesterConfiguration.ps1		PesterConfiguration.ps1
README.md		README.md
biome.json		biome.json
blockDanmuku		blockDanmuku
docker-compose.pester.yml		docker-compose.pester.yml
install.ps1		install.ps1
lint-staged.config.js		lint-staged.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
powershellScripts.code-workspace		powershellScripts.code-workspace
ruff.toml		ruff.toml
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

PowerShell Scripts Collection

📋 目录

🚀 项目概述

主要特性

🛠️ 安装和设置

快速开始

脚本管理

系统要求

📦 核心脚本

🔧 系统环境管理

cleanEnvPath

restoreEnvPath

🏃‍♂️ 脚本执行器

runScripts

install.ps1

🎬 媒体处理工具

视频处理

ffmpegPreset

VideoToAudio

concatflv

dvdcompress

音频处理

losslessToAdaptiveAudio

图像处理

pngCompress

webpCompress

播放器配置

mpv-config

🖥️ 系统管理工具

文件管理

smallFileCleaner

folderSize

renameLegal

findLostNum

系统配置

syncConfig

proxyHelper