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