# 🖥️ B17 | Your First PowerShell Command, with AI — Companion Assets

> **Series**: AI-Powered Office: From Beginner to Expert
> **Article**: B17 (Track 3 Automation / Level 1 Basics)
> **Title (EN)**: Your First PowerShell Command, with AI
> **Title (中文)**: 用 AI 写出你的第一条 PowerShell 命令

---

## 1. Who Is This For? What Problem Does It Solve?

This asset is for **anyone whose palms sweat the moment a black console window appears**: no idea how to write a command, scared to press Enter, drowning in red error messages. The five `*.ps1` scripts here are your **safe practice partner** — every one of them is **read-only and zero-risk** (`Get-Process` / `Get-Service` / `Get-ChildItem` / `Get-Help` / `Get-Command`), plus one **safety red-lines demo** that shows you what you must NOT run blindly. After working through this folder, the black box stops being mysterious and pressing Enter stops making your hands shake.

The main tutorial `B17_第一条命令_双语.md` (English section) teaches you how to use AI as your translator; this folder is the **hands-on version** — every command from the tutorial is turned into a one-click `.ps1`, and after running them all, you've earned the right to say "I can open the black box."

---

## 2. How to Use (5 Steps to Your First Command)

### Step 1: Open PowerShell

> 💡 Built into Windows 10 / 11. **No installation required.**

Press `Win + R`, type `powershell`, press Enter. When you see a prompt like `PS C:\Users\YourName>`, you're set. **Do NOT** open it as Administrator (the tutorial's Section 3 explains why).

### Step 2: Run the 5 "Three-Check Method" warm-up scripts (in order 01→05)

Each `.ps1` is independent — run them one at a time:

```powershell
# Open PowerShell and cd into this folder
cd "C:\Users\cynix\WorkBuddy\VBA.net\配套资产\B17_第一条命令"

# First one: look at processes
.\01-LookAtProcesses_en.ps1
```

After running scripts 01–05 in order, you've built the muscle memory: any PowerShell command you see, the verb (`Get-` / `Set-` / `Remove-`) tells you **80% of its safety**.

> 🛡 Scripts 01–05 are all 🟢 GREEN (read-only). They never touch your files.

### Step 3: Run the Safety Red Lines demo (mandatory!)

```powershell
.\SafetyRedLines_demo_en.ps1
```

This script **demonstrates** but does NOT execute any dangerous command (dangerous commands are printed via `Write-Host` as text only). It teaches you the safe equivalents of all 4 red lines — so when you ever see `Set-ExecutionPolicy Unrestricted` / `Remove-Item -Recurse -Force` / `Format-Volume` / `iex (irm ...)` you'll know **what to do instead**.

### Step 4: Tweak the parameters yourself

Every `.ps1` has clear comments (Chinese + English). For example, in `01-LookAtProcesses_en.ps1`:

```powershell
Get-Process -Name powershell, chrome, excel, winword, wps `
             -ErrorAction SilentlyContinue `
             | Sort-Object -Property WorkingSet64 -Descending `
             | Select-Object -First 5 ...
```

Replace `powershell, chrome, excel, winword, wps` with whatever's actually running on your machine (e.g., `qq, wechat, code`), then run again. Once you understand what each segment does, you've started "modifying commands."

### Step 5: Let AI write commands for you (full flow in tutorial Section 4)

The "Prompt" section in the tutorial is copy-paste ready for Copilot / ChatGPT. AI's command always goes through the **Three-Check Method**:

1. **Check the verb** — `Get-` is green; `Remove-` is red.
2. **Check the parameters** — `Get-Help <cmd> -Online` to confirm against official docs.
3. **Check the path** — never operate on `C:\Windows` or similar system folders.

---

## 3. File Listing

| File | Type | Purpose | Safety |
|------|------|---------|--------|
| `B17_FirstCommand_EnglishREADME.md` | Markdown | This file (English instructions) | — |
| `B17_第一条命令_中文README.md` | Markdown | Chinese version | — |
| `01-LookAtProcesses_en.ps1` | PowerShell | Get-Process demo | 🟢 Green |
| `01-看进程_zh.ps1` | PowerShell | Chinese version | 🟢 Green |
| `02-LookAtServices_en.ps1` | PowerShell | Get-Service demo | 🟢 Green |
| `02-看服务_zh.ps1` | PowerShell | Chinese version | 🟢 Green |
| `03-ListFiles_en.ps1` | PowerShell | Get-ChildItem demo (list + sort) | 🟢 Green |
| `03-列文件_zh.ps1` | PowerShell | Chinese version | 🟢 Green |
| `04-GetHelp_en.ps1` | PowerShell | Get-Help / man / -? / -Online (4 styles) | 🟢 Green |
| `04-查帮助_zh.ps1` | PowerShell | Chinese version | 🟢 Green |
| `05-FindCommand_en.ps1` | PowerShell | Get-Command / Get-Verb demo | 🟢 Green |
| `05-找命令_zh.ps1` | PowerShell | Chinese version | 🟢 Green |
| `SafetyRedLines_demo_en.ps1` | PowerShell | 4 red lines + safe equivalents | 🟡 Yellow (demo only) |
| `安全红线_demo_zh.ps1` | PowerShell | Chinese version | 🟡 Yellow |

---

## 4. Prerequisite for Running `.ps1` Files (one-time config)

PowerShell **blocks `.ps1` files by default** (for safety). You need to do this once:

```powershell
# Method A: bypass for this single run (recommended for first-time users)
powershell -ExecutionPolicy Bypass -File ".\01-LookAtProcesses_en.ps1"

# Method B: allow scripts for your user (more durable)
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
# After this, you can run .\01-LookAtProcesses_en.ps1 directly
```

> ⚠️ The tutorial's Section 3 explicitly says **don't use `Set-ExecutionPolicy Unrestricted`** — that turns off every safety lock. `RemoteSigned` is Windows' default: local scripts run freely; downloaded ones need a digital signature.

---

## 5. Quick Reference — 5 "Three-Check Method" Commands

| # | Cmdlet | Verb | What it does | One-liner example |
|---|--------|------|--------------|-------------------|
| 01 | `Get-Process` | Get | Inspect processes | `Get-Process -Name chrome` |
| 02 | `Get-Service` | Get | Inspect services | `Get-Service \| Group-Object Status` |
| 03 | `Get-ChildItem` | Get | List files | `Get-ChildItem -File \| Sort-Object Length -Descending` |
| 04 | `Get-Help` / `man` / `-?` | Get | Look up help | `Get-Help Get-Process -Online` |
| 05 | `Get-Command` / `Get-Verb` | Get | Find cmdlets | `Get-Command -Verb Get -Noun Process` |

> 💡 **The essence of the Three-Check Method**: the verb tells you how dangerous, the parameters tell you whether it's accurate, the path tells you whether it's pointing at the right target.

---

## 6. 4 Safety Red Lines Cheat Sheet

| Category | Dangerous command | Risk | Safe alternative |
|----------|-------------------|------|------------------|
| Delete | `Remove-Item -Path "X" -Recurse -Force` | 🔴 Red | `Get-ChildItem` first, then `-WhatIf` dry run |
| Change policy | `Set-ExecutionPolicy Unrestricted` | 🔴 Red | `Unblock-File -Path .\some.ps1` |
| Format drive | `Format-Volume -DriveLetter C` | 🔴 Red | Use Disk Management GUI |
| Run a string | `iex (irm https://...)` | 🔴 Red | `Invoke-RestMethod ... -OutFile`, review with eyes, then `. .\local.ps1` |

> ⚠️ **The blacklist isn't "don't ever use" — it's "don't use until you understand it."** Once you can recite all 4 red lines, `Remove-Item` is fine — by then you'll know `-WhatIf` and `-Confirm` cold.

---

## 7. PowerShell Version Differences (`pwsh` vs built-in 5.1)

| Item | Windows PowerShell 5.1 | PowerShell 7 (`pwsh`) |
|------|------------------------|------------------------|
| Built-in | ✅ Yes (Win 10 / 11) | ❌ Manual install (recommended) |
| Program name | `powershell` | `pwsh` |
| Compatibility | Best for legacy scripts | Cross-platform + modern syntax |
| CSV encoding | `Export-Csv -Encoding UTF8` adds BOM | `Export-Csv -Encoding utf8` no BOM |
| Scripts in this folder | ✅ All work | ✅ All work |

Check your version:

```powershell
$PSVersionTable
# PSVersion: 5.1.xxxx  = 5.1
# PSVersion: 7.x.xxxx  = 7
```

---

## 8. FAQ / Pitfall Guide

1. **".ps1 cannot be loaded because running scripts is disabled on this system"**
   PowerShell blocks `.ps1` by default. Two fixes:
   - One-off: `powershell -ExecutionPolicy Bypass -File ".\01-LookAtProcesses_en.ps1"`
   - Durable: `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned`
   **Never** use `Set-ExecutionPolicy Unrestricted` — that's a red line.

2. **`Get-Help -Examples` says "no help found"**
   Windows PowerShell 5.1 doesn't ship full help docs by default. Use `Get-Help <cmd> -Online` (web version, needs internet).

3. **My Desktop path is `C:\Users\me\OneDrive\Desktop` instead of `C:\Users\me\Desktop`**
   OneDrive took over your Desktop. Use `[Environment]::GetFolderPath("Desktop")` to ask Windows the real path. **Don't hardcode Desktop paths** — that's how `03-ListFiles_en.ps1` handles it.

4. **AI gave me a `Remove-Item` command without explanation**
   If AI's command contains `Remove-` / `Set-` / `Format-` / `Invoke-Expression` / `iex` / `irm`, treat it as a red line — reply to AI: "Can you rewrite using only `Get-` style read-only commands?" or ask it to add `-WhatIf` so it shows what would happen first.

5. **Red text everywhere, I'm freaking out**
   Don't close the window! Mouse-drag to select the red text, `Ctrl+C`, then paste to AI: "I ran this command in PowerShell 5.1 … here's the error verbatim … in plain English, what went wrong, give me the fixed command, and is the fixed command still read-only?" Tutorial Section 4.7 has the full prompt.

6. **Chinese characters in my path break the script**
   PowerShell's default Chinese encoding is GBK. Save scripts as **UTF-8 with BOM** (click the encoding chip in VS Code's status bar) or test with English paths first, then switch back.

7. **The script runs and prints nothing**
   The processes named in the script (`chrome`, etc.) probably aren't running on your machine. The script uses `-ErrorAction SilentlyContinue` so it won't print red errors. Replace with names you know are running (e.g., `notepad, explorer, qq`) and re-run.

---

## 9. Where to Go Next

- **B18 Intro to Batch Scripts**: Turn a single command into a script that runs hundreds or thousands of times — e.g., bulk-rename files, bulk-read Excel files.
- **B19 Modular Scripts**: Split scripts into functions and bundle them into `.psm1` modules for team reuse.
- **A5 Safety Red Lines**: This tutorial's 4 red lines are entry-level; A5 is the full "AI-generated-command safety audit checklist."

---

*This folder is the companion asset for article B17 in the series "AI-Powered Office: From Beginner to Expert." Scripts 01–05 are verified on both PowerShell 5.1 and 7; the red-lines script demonstrates only — it never executes. **A command you don't understand is a command you don't press Enter on.** That's the most important rule for the beginner stage.*