timmy/win-remote-toolkit

Fork 0

Files

Timmy 7105e8b165 Initial commit

2026-04-24 17:44:02 +08:00

5.3 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

專案概述

這是一個 Windows 遠端管理工具包，專門設計用於從 macOS/Linux 系統遠端配置和管理 Windows 機器（預設目標：PC-74269 at 192.168.88.112）。工具包提供自動化腳本進行系統 debloating、應用程式安裝、安全性配置和診斷。

核心架構模式

雙腳本架構

每個功能都包含兩個檔案：

.ps1 - 在目標 Windows 機器上執行的 PowerShell 腳本
.sh - macOS/Linux shell wrapper，透過 SSH 上傳並執行 PowerShell 腳本

執行流程

Shell 腳本使用 sshpass + scp 將 PowerShell 腳本上傳到目標機器
透過 SSH 遠端執行：powershell -NoProfile -ExecutionPolicy Bypass
輸出同時顯示在終端並記錄到 logs/ 目錄（帶時間戳）

雙連線方法支援

SSH 方法（穩定，適合大型腳本）：

穩定可靠，處理大型腳本（>3KB）無問題
所有現有 .sh 腳本使用此方法
執行時間：~22 秒（recon 腳本）

WinRM 方法（快速，適合快速任務）：

1.9 倍執行速度（12 秒 vs 22 秒）
原生 Windows 遠端管理，更好的 PowerShell 整合
受命令列長度限制，適合小型腳本

常用命令

環境需求設置

# 安裝 sshpass（SSH 方法必需）
brew install hudochenkov/sshpass/sshpass

# 安裝 Python WinRM 庫（WinRM 方法）
pip3 install pywinrm

系統偵察和驗證

./recon.sh                    # 完整系統清單（15 個區塊）
./verify-ai-removed.sh        # 驗證 Windows AI 組件已移除
./verify-debloat.sh          # 驗證 Win11Debloat 變更已套用

核心系統配置

./firewall-allow-ssh.sh       # 啟用永久 SSH 存取
./activate-windows.sh         # 透過 KMS 啟用 Windows
./remove-windows-ai.sh        # 移除 Windows AI/Copilot 組件
./win11debloat.sh            # 移除膨脹軟體並停用遙測

連線方法選擇

# SSH 方法（預設，適合所有腳本）
./recon.sh

# WinRM 方法（更快的替代方案）
python3 test_simple_winrm.py
python3 benchmark_ssh_vs_winrm.py

# 智慧方法選擇
python3 smart_executor.py script.ps1

重要配置檔案

`win11debloat-config.json`

Win11Debloat 操作配置。使用包含 Tweaks、Deployment 和 Apps 區塊的架構。所有調整名稱必須存在於 Win11Debloat 的 Config/Features.json 中，否則會被拒絕為「no importable data」。

`thunderbird-config.json`

Thunderbird 設置的電子郵件帳戶配置。支援各種提供商（Gmail、Outlook、iCloud、自定義伺服器）的 IMAP/SMTP。

`nirsoft-config.json`

定義要安裝的 16 個 NirSoft 診斷工具，包括下載 URL 和安裝路徑。

關鍵架構陷阱

PowerShell 編碼問題

中文 Windows 系統將無 BOM 的 UTF-8 腳本讀取為 CP950。腳本會自動為下載的 PowerShell 檔案添加 UTF-8 BOM 以避免解析失敗。

防火牆持久性

Windows 防火牆設定檔在重啟後會重置。防火牆腳本建立永久規則並啟用所有設定檔，確保 SSH 存取持續有效。

Thunderbird 設定檔處理

Thunderbird 72+ 使用 profiles.ini 中的 [Install<HASH>] 區塊而非 Default=1。設置腳本正確處理這種變更。

Win11Debloat 範圍限制

靜默模式僅將 UI 設定套用到執行使用者。使用 apply-ui-to-user.sh 將設定同步到其他使用者。

WinRM 目標需求

目標上運行的 WinRM 服務（連接埠 5985 HTTP 或 5986 HTTPS）
執行過 Enable-PSRemoting -Force
為 Windows 遠端管理啟用防火牆規則
對於 HTTP：WinRM 配置中的 AllowUnencrypted=true

環境變數覆寫

所有腳本支援連線參數覆寫：

HOST=192.168.x.x USER_NAME=foo PASS='xxx' ./script.sh
MODE=Apply|Revert ./remove-windows-ai.sh    # AI 移除模式
TARGET_USER=someone ./apply-ui-to-user.sh   # UI 設定目標使用者

建議執行順序（新機器）

firewall-allow-ssh.sh - 確保永久 SSH 存取
enable-winrm.sh - 配置 WinRM（如使用 WinRM 方法）
recon.sh - 系統清單
activate-windows.sh - Windows 啟用
AI 移除 + 重啟 + 驗證
Win11Debloat + 重啟 + 驗證
應用程式安裝
帳戶管理（重新命名/隱藏應最後進行）

日誌記錄和輸出

所有操作在 logs/ 目錄建立帶時間戳的日誌
格式：{operation}-{host}-{timestamp}.log
診斷傾印儲存到 dumps/ 目錄為 ZIP 檔案
腳本提供即時輸出並同時記錄

遠端目標需求

啟用 OpenSSH Server 的 Windows 機器（連接埠 22）
預設憑證：Admin@192.168.88.112 / P@ssw0rd!
需要 PowerShell 5.1（非 PowerShell 7/Core）
目標必須可從執行環境存取

故障排除要點

重啟後 SSH 無法連線：Private/Public 設定檔會恢復為系統預設的阻擋入站設定
Thunderbird 設置後看不到帳戶：確認 [Install<HASH>] 區塊配置正確
Telegram Desktop 安裝限制：不支援機器範圍安裝，使用 per-user 變通方法
Win11Debloat 配置架構：使用 Tweaks/Deployment/Apps，不是 Settings
NirSoft 工具 URL 變更：部分下載連結可能失效，腳本會跳過並繼續

5.3 KiB Raw Permalink Blame History Unescape Escape