# 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 變更**：部分下載連結可能失效，腳本會跳過並繼續