Windowsスクリプト規約 完全ガイド 【AIエージェント向け】 2025年版

2025.08.09

Windows Script Standards for AI Agents

Version: 5.0-AI | Updated: 2025-08-10 | Target: AI Agents & Automation Tools

METADATA

document_type: technical_specification
target_audience: ai_agents
encoding: UTF-8 with BOM
language: ja-JP
compatibility:
  - Windows 11 (Build 26100+)
  - Windows 10 (Build 19041+)
  - PowerShell 5.1
  - PowerShell 7.5+
  - CMD/Batch
priority_level: CRITICAL
auto_execution: ENABLED

AGENT_INSTRUCTIONS

PRIMARY_DIRECTIVE: |
  When processing Windows scripts, ALWAYS apply these rules in order:
  1. Detect environment → 2. Apply encoding rules → 3. Execute with safety checks

EXECUTION_CONTEXT:
  default_encoding: UTF-8 with BOM
  fallback_encoding: UTF-8
  error_handling: STRICT
  validation: MANDATORY

CRITICAL_RULES

RULE_001: ENCODING_DETECTION

id: RULE_001
priority: HIGHEST
condition: ALWAYS
actions:
  - detect_os_build:
      command: "[Environment]::OSVersion.Version.Build"
      store_as: $OS_BUILD

  - detect_powershell_version:
      command: "$PSVersionTable.PSVersion.Major"
      store_as: $PS_VERSION

  - apply_encoding_matrix:
      matrix:
        - condition: "$PS_VERSION -eq 5"
          encoding: "UTF-8 with BOM"
          required: true

        - condition: "$PS_VERSION -ge 7"
          encoding: "UTF-8 without BOM"
          required: false

        - condition: "$OS_BUILD -ge 26100"
          console_encoding: "UTF-8"
          special_handling: "netsh_wrapper"

RULE_002: WINDOWS11_24H2_HANDLER

id: RULE_002
priority: CRITICAL
condition: "$OS_BUILD -ge 26100"
trigger: "netsh|ipconfig|nslookup"
implementation:
  wrapper_function: |
    function Invoke-SystemCommand {
        param([string]$Command)
        $orig = [Console]::OutputEncoding
        [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
        try { 
            Invoke-Expression $Command 
        } finally { 
            [Console]::OutputEncoding = $orig 
        }
    }

  auto_apply: true
  scope: GLOBAL

RULE_003: BATCH_FILE_SAFETY

id: RULE_003
priority: HIGH
condition: "file_extension -eq '.bat' -or '.cmd'"
requirements:
  - encoding: "UTF-8 with BOM"
  - line_ending: "CRLF"
  - codepage_handling:
      set: "chcp 65001"
      restore: MANDATORY

  safety_rules:
    - rule: "APPEND_ASCII_TO_JAPANESE_LINES"
      description: "Add semicolon after Japanese text at line end"
      example:
        bad: 'set VAR=日本語'
        good: 'set VAR=日本語;'

    - rule: "PRESERVE_ORIGINAL_CODEPAGE"
      template: |
        for /f "tokens=2 delims=:" %%a in ('chcp') do set ORIGINAL_CP=%%a
        chcp 65001 > nul 2>&1
        REM [YOUR CODE HERE]
        if defined ORIGINAL_CP chcp %ORIGINAL_CP% > nul 2>&1

AUTOMATIC_DIAGNOSTICS

DIAG_001: FILE_ENCODING_CHECK

# AUTO-EXECUTE: Check file encoding
function Test-FileEncodingAI {
    param([string]$Path)
    $bytes = [System.IO.File]::ReadAllBytes($Path) | Select-Object -First 4
    $result = @{
        Path = $Path
        HasBOM = $false
        Encoding = "UNKNOWN"
        Action = "NONE"
    }

    if ($bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {
        $result.Encoding = "UTF8BOM"
        $result.HasBOM = $true
        $result.Action = "OK"
    } elseif ($bytes[0] -eq 0xFF -and $bytes[1] -eq 0xFE) {
        $result.Encoding = "UTF16LE"
        $result.HasBOM = $true
        $result.Action = "CONVERT_TO_UTF8BOM"
    } else {
        $result.Encoding = "UTF8_OR_ANSI"
        $result.Action = "CONVERT_TO_UTF8BOM"
    }
    return $result
}

DIAG_002: ENVIRONMENT_CHECK

# AUTO-EXECUTE: Environment validation
function Get-EnvironmentStatusAI {
    return @{
        OS_BUILD = [Environment]::OSVersion.Version.Build
        PS_VERSION = $PSVersionTable.PSVersion.Major
        CONSOLE_INPUT = [Console]::InputEncoding.CodePage
        CONSOLE_OUTPUT = [Console]::OutputEncoding.CodePage
        CURRENT_CP = (Get-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\Nls\CodePage').OEMCP
        REQUIRES_24H2_FIX = ([Environment]::OSVersion.Version.Build -ge 26100)
    }
}

COMMAND_TEMPLATES

TEMPLATE_001: SAFE_NETSH_EXECUTION

# ID: CMD_NETSH_SAFE
# Usage: Replace all netsh calls with this template
$NETSH_TEMPLATE = {
    $e = [Console]::OutputEncoding
    [Console]::OutputEncoding = [Text.Encoding]::UTF8
    $r = netsh $args
    [Console]::OutputEncoding = $e
    return $r
}

TEMPLATE_002: FILE_WRITE_UTF8BOM

# ID: CMD_WRITE_BOM
# Usage: Always use for PowerShell 5.1 scripts
$WRITE_BOM_TEMPLATE = {
    param($Path, $Content)
    $utf8bom = New-Object System.Text.UTF8Encoding $true
    [System.IO.File]::WriteAllText($Path, $Content, $utf8bom)
}

TEMPLATE_003: BATCH_SAFE_WRAPPER

@REM ID: CMD_BATCH_SAFE
@REM Usage: Wrap all batch files with this template
@echo off
for /f "tokens=2 delims=:" %%a in ('chcp') do set OCP=%%a
chcp 65001 >nul 2>&1
REM === USER CODE START ===
%USER_CODE%
REM === USER CODE END ===
if defined OCP chcp %OCP% >nul 2>&1
exit /b %ERRORLEVEL%

ERROR_HANDLERS

ERROR_001: ENCODING_MISMATCH

error_code: ENC_MISMATCH
detection: "Output contains � or ���"
immediate_action:
  - apply: RULE_002
  - retry_with: "UTF-8"
  - fallback: "Get-Content -Raw -Encoding Default"

ERROR_002: BATCH_CORRUPTION

error_code: BATCH_CORRUPT
detection: "Command truncation (e.g., 'echo' → 'cho')"
immediate_action:
  - check: "Line ends with full-width character"
  - fix: "Append semicolon to affected lines"
  - revalidate: true

QUICK_REFERENCE_MATRIX

DECISION_MATRIX:
  - query: "Which encoding for .ps1 file?"
    conditions:
      - "PS 5.1": "UTF-8 BOM"
      - "PS 7.x": "UTF-8"
      - "Mixed": "UTF-8 BOM"

  - query: "netsh command fails?"
    conditions:
      - "Build >= 26100": "Apply RULE_002"
      - "Build < 26100": "Check codepage"

  - query: "Batch file Japanese corruption?"
    conditions:
      - "Always": "Apply RULE_003"
      - "Add semicolon": true

  - query: "VS Code settings?"
    apply:
      "[powershell]":
        "files.encoding": "utf8bom"
      "[bat]":
        "files.encoding": "utf8bom"

AUTOMATED_FIXES

FIX_001: CONVERT_TO_UTF8BOM

# AUTO-FIX: Convert file to UTF-8 with BOM
function Convert-ToUTF8BOMAI {
    param([string]$Path)
    if (Test-Path $Path) {
        $content = Get-Content $Path -Raw -Encoding Default
        $utf8bom = [System.Text.UTF8Encoding]::new($true)
        [System.IO.File]::WriteAllText($Path, $content, $utf8bom)
        return @{Status="SUCCESS"; Path=$Path}
    }
    return @{Status="FILE_NOT_FOUND"; Path=$Path}
}

FIX_002: PROFILE_INJECTION

# AUTO-FIX: Add encoding settings to PowerShell profile
$PROFILE_FIX = @'
# Windows Script Standards - Auto Configuration
if ($PSVersionTable.PSVersion.Major -eq 5) {
    $PSDefaultParameterValues['*:Encoding'] = 'utf8'
}
if ([Environment]::OSVersion.Version.Build -ge 26100) {
    function netsh { 
        $e=[Console]::OutputEncoding
        [Console]::OutputEncoding=[Text.Encoding]::UTF8
        & netsh.exe $args
        [Console]::OutputEncoding=$e
    }
}
'@

VALIDATION_CHECKS

CHECK_001: PRE_EXECUTION_VALIDATION

# MANDATORY: Run before script execution
function Validate-ScriptEnvironmentAI {
    $checks = @{
        EncodingValid = $false
        EnvironmentSafe = $false
        Win11_24H2_Ready = $false
    }

    # Check 1: File encoding
    $encoding = Test-FileEncodingAI $args[0]
    $checks.EncodingValid = ($encoding.Action -eq "OK")

    # Check 2: Environment
    $env = Get-EnvironmentStatusAI
    $checks.EnvironmentSafe = ($env.CONSOLE_OUTPUT -eq 65001 -or $env.PS_VERSION -ge 7)

    # Check 3: Windows 11 24H2
    $checks.Win11_24H2_Ready = (-not $env.REQUIRES_24H2_FIX -or (Get-Command Invoke-SystemCommand -ErrorAction SilentlyContinue))

    return $checks
}

INTEGRATION_ENDPOINTS

ENDPOINT_001: WORDPRESS_API

api_endpoint: "/wp-json/scripts/v1/validate"
method: POST
payload:
  script_content: base64_encoded
  environment: auto_detect
  apply_fixes: true
response:
  validation_result: object
  fixed_content: base64_encoded
  recommendations: array

ENDPOINT_002: CI_CD_HOOK

pipeline_integration:
  pre_commit:
    - validate: "Validate-ScriptEnvironmentAI"
    - fix: "Convert-ToUTF8BOMAI"

  pre_deploy:
    - check: "Get-EnvironmentStatusAI"
    - inject: "$PROFILE_FIX"

EXECUTION_PRIORITY

PRIORITY_ORDER:
  1: CRITICAL_RULES
  2: AUTOMATIC_DIAGNOSTICS
  3: ERROR_HANDLERS
  4: AUTOMATED_FIXES
  5: VALIDATION_CHECKS

PARALLEL_EXECUTION:
  allowed:
    - DIAG_001
    - DIAG_002
  sequential:
    - RULE_001
    - RULE_002
    - RULE_003

API_RESPONSES

RESPONSE_FORMAT

{
  "status": "SUCCESS|WARNING|ERROR",
  "applied_rules": ["RULE_001", "RULE_002"],
  "diagnostics": {
    "encoding": "UTF8BOM",
    "environment": "SAFE",
    "fixes_applied": ["FIX_001"]
  },
  "recommendations": [],
  "execution_log": []
}

USAGE_INSTRUCTIONS_FOR_AI

WHEN_PROCESSING_WINDOWS_SCRIPTS:
  1_ALWAYS:
    - Load this specification first
    - Run DIAG_001 and DIAG_002
    - Apply CRITICAL_RULES based on conditions

  2_CHECK:
    - If errors occur, consult ERROR_HANDLERS
    - Apply AUTOMATED_FIXES as needed
    - Validate with CHECK_001

  3_EXECUTE:
    - Use COMMAND_TEMPLATES for safe execution
    - Monitor for encoding issues
    - Report using API_RESPONSES format

NEVER:
  - Skip encoding detection
  - Ignore Windows 11 24H2 special cases
  - Execute batch files without codepage handling
  - Write PowerShell 5.1 scripts without BOM

VERSION_CONTROL

version: "5.0-AI"
last_updated: "2025-08-10T10:00:00Z"
compatibility_matrix:
  "5.0-AI": ["Windows 11 24H2", "PowerShell 7.5"]
  "4.0": ["Windows 11 23H2", "PowerShell 7.4"]
backwards_compatible: false
migration_required: true

END_OF_SPECIFICATION

document_hash: "SHA256:7f3a9b2c..."
validation: "COMPLETE"
ready_for_execution: true
ai_optimized: true

コメント

タイトルとURLをコピーしました