# Quick Start Guide

快速上手 Windows Remote Toolkit，從安裝到實際使用。

## 🚀 5 分鐘快速開始

### 1. 準備執行環境

#### macOS/Linux 需求
```bash
# 安裝 sshpass（SSH 方法必需）
brew install hudochenkov/sshpass/sshpass

# 安裝 Python WinRM 庫（WinRM 方法，可選）
pip3 install pywinrm
```

#### 目標 Windows 機器需求
- Windows 10/11 with PowerShell 5.1
- 啟用 OpenSSH Server（連接埠 22）
- 網路可達

### 2. 驗證連線

```bash
# 測試基本連線
ssh Admin@192.168.88.112

# 或使用自訂連線參數
HOST=your.windows.ip USER_NAME=your_user PASS='your_pass' ./scripts/ssh/recon.sh
```

### 3. 執行第一個腳本

```bash
# 系統偵察（安全且資訊豐富）
./scripts/ssh/recon.sh

# 查看結果
ls logs/recon-*
```

## 🎯 常見使用情境

### 情境一：新機器初始化
```bash
# 步驟 1：確保永久 SSH 存取
./scripts/ssh/firewall-allow-ssh.sh

# 步驟 2：啟用 WinRM（可選，用於快速執行）
./scripts/ssh/enable-winrm.sh

# 步驟 3：系統偵察
./scripts/ssh/recon.sh

# 步驟 4：Windows 啟用
./scripts/ssh/activate-windows.sh

# 步驟 5：移除 AI 組件 → **重啟** → 驗證
./scripts/ssh/remove-windows-ai.sh
# 手動重啟機器後
./scripts/ssh/verify-ai-removed.sh

# 步驟 6：系統去膨脹 → **重啟** → 驗證
./scripts/ssh/win11debloat.sh
# 手動重啟機器後
./scripts/ssh/verify-debloat.sh

# 步驟 7：安裝常用軟體
./scripts/ssh/install-apps.sh
./scripts/ssh/install-thunderbird.sh
./scripts/ssh/setup-thunderbird.sh
```

### 情境二：應用程式管理
```bash
# 安裝常用軟體
./scripts/ssh/install-apps.sh

# 移除特定軟體（自訂 config/remove-apps-config.json）
./scripts/ssh/remove-apps.sh

# 安裝診斷工具
./scripts/ssh/install-nirsoft.sh
```

### 情境三：系統診斷
```bash
# 完整系統資訊
./scripts/ssh/recon.sh

# 深度診斷並打包結果
./scripts/ssh/nirsoft-dump.sh

# 檢查系統狀態
./scripts/ssh/verify-debloat.sh
./scripts/ssh/verify-ai-removed.sh
```

## ⚙️ 自訂配置

### 修改連線目標
有三種方法：

#### 方法一：環境變數（單次執行）
```bash
HOST=192.168.1.100 USER_NAME=MyUser PASS='MyPass' ./scripts/ssh/recon.sh
```

#### 方法二：Shell 設定檔（長期使用）
在 `~/.zshrc` 或 `~/.bashrc` 中加入：
```bash
export HOST=192.168.1.100
export USER_NAME=MyUser
export PASS='MyPass'
```

#### 方法三：修改腳本檔案（不推薦）
直接編輯各 `.sh` 檔案中的預設值。

### 自訂配置檔案

#### Win11Debloat 設定
編輯 `config/win11debloat-config.json`：
```json
{
  "Tweaks": ["DisableTelemetry", "DisableCortana"],
  "Apps": ["Microsoft.BingWeather", "Microsoft.Xbox*"]
}
```

#### Thunderbird 電子郵件設定
編輯 `config/thunderbird-config.json`：
```json
{
  "accounts": [
    {
      "name": "我的信箱",
      "email": "user@gmail.com",
      "provider": "gmail"
    }
  ]
}
```

#### 應用程式移除清單
編輯 `config/remove-apps-config.json`：
```json
{
  "apps": [
    "Microsoft.BingNews",
    "Microsoft.GetHelp"
  ]
}
```

## 🏃‍♂️ 效能優化

### SSH vs WinRM 方法選擇

| 方法 | 速度 | 穩定性 | 適用場景 |
|------|------|--------|----------|
| SSH | 標準 | 高 | 大型腳本、批次操作 |
| WinRM | 1.9x 快 | 中等 | 小型腳本、快速查詢 |

```bash
# SSH 方法（預設）
./scripts/ssh/recon.sh

# WinRM 方法
python3 scripts/winrm/test_simple_winrm.py

# 智慧選擇（自動判斷最佳方法）
python3 scripts/winrm/smart_executor.py scripts/powershell/recon.ps1
```

### 批次執行技巧
```bash
# 平行執行多個獨立任務
./scripts/ssh/install-apps.sh &
./scripts/ssh/install-nirsoft.sh &
wait

# 循序執行有相依性的任務
./scripts/ssh/remove-windows-ai.sh && \
echo "請重啟機器後按 Enter 繼續..." && read && \
./scripts/ssh/verify-ai-removed.sh
```

## 🛠️ 故障排除

### 常見問題

#### 1. "Permission denied" 或連線失敗
```bash
# 檢查 SSH 服務狀態
ssh Admin@192.168.88.112 'Get-Service sshd'

# 檢查防火牆規則
ssh Admin@192.168.88.112 'netsh advfirewall firewall show rule name=all | findstr SSH'
```

**解決方案**：
- 確認 Windows 已啟用 OpenSSH Server
- 執行 `firewall-allow-ssh.sh` 建立防火牆規則

#### 2. 重啟後無法連線
**原因**：Windows 防火牆設定檔重置

**解決方案**：
```bash
# 重新設定防火牆（從能連線的網路或本機執行）
./scripts/ssh/firewall-allow-ssh.sh
```

#### 3. PowerShell 腳本執行策略錯誤
**錯誤訊息**：`execution of scripts is disabled on this system`

**解決方案**：腳本已自動使用 `-ExecutionPolicy Bypass`，無需額外設定

#### 4. WinRM 無法連線
```bash
# 檢查 WinRM 設定
./scripts/ssh/check-winrm.sh

# 修復 WinRM 配置
./scripts/ssh/fix-winrm.sh
```

#### 5. 中文字元顯示亂碼
**原因**：PowerShell 編碼問題

**解決方案**：腳本自動處理 UTF-8 BOM，無需手動修正

### 偵錯技巧

#### 查看詳細執行記錄
```bash
# 即時監看日誌
tail -f logs/recon-PC-74269-$(date +%Y%m%d)*.log

# 搜尋錯誤訊息
grep -i error logs/*.log
```

#### 測試單一 PowerShell 命令
```bash
# 透過 SSH 執行單一命令
ssh Admin@192.168.88.112 'powershell -Command "Get-ComputerInfo"'
```

#### 開啟偵錯模式
```bash
# 在腳本中加入偵錯資訊（環境變數）
DEBUG=1 ./scripts/ssh/recon.sh
```

## 📝 最佳實務

### 執行順序建議
1. **連線測試** → `recon.sh`
2. **防火牆設定** → `firewall-allow-ssh.sh`
3. **系統配置** → `remove-windows-ai.sh` → 重啟 → `win11debloat.sh` → 重啟
4. **軟體安裝** → `install-apps.sh` 等
5. **帳戶管理**（最後）→ `rename-hide-accounts.sh`

### 安全注意事項
- 不要在腳本中硬編碼密碼
- 重要操作前先測試並備份
- 帳戶重新命名操作建議最後執行
- 敏感檔案已加入 `.gitignore`

### 備份策略
```bash
# 操作前先收集系統資訊
./scripts/ssh/recon.sh
./scripts/ssh/nirsoft-dump.sh

# 保存配置備份
cp config/*.json config/backup/
```

---

🔗 **相關文檔**：
- [README.md](README.md) - 完整腳本功能參考
- [SUMMARY.md](SUMMARY.md) - 架構設計理念
- [CLAUDE.md](CLAUDE.md) - 技術實作細節