Generare automată de documentație tehnică din scripturi PowerShell folosind Local AI

Situatie

Echipele de administrare acumulează în timp zeci de scripturi PowerShell (.ps1) fără documentație. Când un coleg pleacă sau un script trebuie modificat, nimeni nu mai știe exact ce face și cum se rulează. Această soluție parcurge un folder cu scripturi, le trimite pe rând unui model AI local și generează automat fișiere de documentație în limba română (descriere, parametri, exemple de utilizare, riscuri potențiale) — fără upload în cloud.

Solutie

Pasi de urmat

Pasul 1 — Pregătire

powershell

ollama pull llama3

$ScriptsPath = "C:\Scripts"          # folderul cu scripturile .ps1
$DocsPath    = "C:\Scripts\Docs"     # unde se salveaza documentatia
New-Item -ItemType Directory -Force -Path $DocsPath | Out-Null

Pasul 2 — Funcție de generare documentație

powershell

function New-ScriptDoc {
    param(
        [string]$ScriptContent,
        [string]$ScriptName,
        [string]$Model = "llama3"
    )

    $Prompt = @"
Esti un expert PowerShell. Analizeaza scriptul de mai jos si genereaza
documentatie tehnica in limba romana, structurata astfel (Markdown):

# <Numele scriptului>
## Descriere
(ce face scriptul, pe scurt)
## Parametri
(lista parametrilor si rolul lor, daca exista)
## Cum se ruleaza
(exemplu concret de comanda)
## Riscuri / Atentionari
(operatii periculoase, modificari ireversibile, drepturi necesare)

Fii tehnic si concis. Raspunde DOAR cu documentatia in Markdown.

SCRIPT: $ScriptName
$ScriptContent
"@

    $Body = @{
        model  = $Model
        prompt = $Prompt
        stream = $false
    } | ConvertTo-Json -Depth 3

    try {
        $Response = Invoke-RestMethod `
            -Uri "http://localhost:11434/api/generate" `
            -Method POST -ContentType "application/json" `
            -Body $Body -TimeoutSec 180
        return $Response.response
    }
    catch {
        return "EROARE la generare documentatie: $_"
    }
}

Pasul 3 — Script principal


$ScriptsPath = "C:\Scripts"
$DocsPath    = "C:\Scripts\Docs"
$Model       = "llama3"

# Verifica Ollama
try {
    Invoke-RestMethod -Uri "http://localhost:11434/api/tags" -TimeoutSec 5 | Out-Null
    Write-Host "[OK] Ollama activ." -ForegroundColor Green
}
catch {
    Write-Host "[EROARE] Ollama nu raspunde." -ForegroundColor Red
    exit 1
}

# Gaseste toate scripturile .ps1 (exclude folderul Docs)
$Scripts = Get-ChildItem -Path $ScriptsPath -Filter "*.ps1" -Recurse |
           Where-Object { $_.DirectoryName -notlike "*\Docs*" }

$Counter = 0
foreach ($Script in $Scripts) {
    $Counter++
    Write-Host "[$Counter/$($Scripts.Count)] Documentez: $($Script.Name)" -ForegroundColor Cyan

    $Content = Get-Content $Script.FullName -Raw -Encoding UTF8

    if ($Content.Trim().Length -lt 10) {
        Write-Host "   (gol - skip)" -ForegroundColor Yellow
        continue
    }

    $Documentation = New-ScriptDoc `
        -ScriptContent $Content `
        -ScriptName $Script.Name `
        -Model $Model

    $DocFile = Join-Path $DocsPath "$($Script.BaseName).md"
    $Documentation | Out-File -FilePath $DocFile -Encoding UTF8

    Write-Host "   -> $DocFile" -ForegroundColor Green
    Start-Sleep -Seconds 1
}

Write-Host "`n[DONE] Documentatie generata in: $DocsPath" -ForegroundColor Green

Pasul 4 — Rulare și verificare

powershell

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\AI_Script_Documenter.ps1

# Verifica un fisier generat
Get-Content "C:\Scripts\Docs\*.md" | Select-Object -First 30

Tip solutie

Permanent

Follow Us