Initial commit

CLAUDE.md

@@ -0,0 +1,142 @@
+# 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 腳本
+
+### 執行流程
+1. Shell 腳本使用 `sshpass` + `scp` 將 PowerShell 腳本上傳到目標機器
+2. 透過 SSH 遠端執行：`powershell -NoProfile -ExecutionPolicy Bypass`
+3. 輸出同時顯示在終端並記錄到 `logs/` 目錄（帶時間戳）
+
+### 雙連線方法支援
+**SSH 方法（穩定，適合大型腳本）：**
+- 穩定可靠，處理大型腳本（>3KB）無問題
+- 所有現有 `.sh` 腳本使用此方法
+- 執行時間：~22 秒（recon 腳本）
+
+**WinRM 方法（快速，適合快速任務）：**
+- 1.9 倍執行速度（12 秒 vs 22 秒）
+- 原生 Windows 遠端管理，更好的 PowerShell 整合
+- 受命令列長度限制，適合小型腳本
+
+## 常用命令
+
+### 環境需求設置
+```bash
+# 安裝 sshpass（SSH 方法必需）
+brew install hudochenkov/sshpass/sshpass
+
+# 安裝 Python WinRM 庫（WinRM 方法）
+pip3 install pywinrm
+```
+
+### 系統偵察和驗證
+```bash
+./recon.sh                    # 完整系統清單（15 個區塊）
+./verify-ai-removed.sh        # 驗證 Windows AI 組件已移除
+./verify-debloat.sh          # 驗證 Win11Debloat 變更已套用
+```
+
+### 核心系統配置
+```bash
+./firewall-allow-ssh.sh       # 啟用永久 SSH 存取
+./activate-windows.sh         # 透過 KMS 啟用 Windows
+./remove-windows-ai.sh        # 移除 Windows AI/Copilot 組件
+./win11debloat.sh            # 移除膨脹軟體並停用遙測
+```
+
+### 連線方法選擇
+```bash
+# 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`
+
+## 環境變數覆寫
+
+所有腳本支援連線參數覆寫：
+```bash
+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 設定目標使用者
+```
+
+## 建議執行順序（新機器）
+
+1. `firewall-allow-ssh.sh` - 確保永久 SSH 存取
+2. `enable-winrm.sh` - 配置 WinRM（如使用 WinRM 方法）
+3. `recon.sh` - 系統清單
+4. `activate-windows.sh` - Windows 啟用
+5. AI 移除 + 重啟 + 驗證
+6. Win11Debloat + 重啟 + 驗證
+7. 應用程式安裝
+8. 帳戶管理（重新命名/隱藏應最後進行）
+
+## 日誌記錄和輸出
+
+- 所有操作在 `logs/` 目錄建立帶時間戳的日誌
+- 格式：`{operation}-{host}-{timestamp}.log`
+- 診斷傾印儲存到 `dumps/` 目錄為 ZIP 檔案
+- 腳本提供即時輸出並同時記錄
+
+## 遠端目標需求
+
+- 啟用 OpenSSH Server 的 Windows 機器（連接埠 22）
+- 預設憑證：`Admin@192.168.88.112` / `P@ssw0rd!`
+- 需要 PowerShell 5.1（非 PowerShell 7/Core）
+- 目標必須可從執行環境存取
+
+## 故障排除要點
+
+1. **重啟後 SSH 無法連線**：Private/Public 設定檔會恢復為系統預設的阻擋入站設定
+2. **Thunderbird 設置後看不到帳戶**：確認 `[Install<HASH>]` 區塊配置正確
+3. **Telegram Desktop 安裝限制**：不支援機器範圍安裝，使用 per-user 變通方法
+4. **Win11Debloat 配置架構**：使用 `Tweaks`/`Deployment`/`Apps`，不是 `Settings`
+5. **NirSoft 工具 URL 變更**：部分下載連結可能失效，腳本會跳過並繼續