alibabacloud-ecs-windows-online-troubleshooting

Windows ECS Online Diagnostics Skill

When to Use This Skill

Load this skill when a user reports a fault symptom on a Windows instance, or requests troubleshooting or status checks on a Windows instance. Coverage includes:

Network issues: ping, DNS, DHCP, firewall, SMB
RDP/Remote Desktop: connection failures, authentication, black screen, lag
Storage/disk, system activation, Windows Update, performance issues
User accounts/permissions, drivers, application crashes, security/certificates/TLS, scheduled tasks
Vague descriptions such as "check the system" or "something is wrong with the system"

The diagnostic capability list and issue routing table are stored in references/REFERENCE.md , loaded during the path planning phase.

Diagnostic Execution Flow

General Rules for Presenting to Users

During execution, when presenting information such as progress, troubleshooting paths, and current steps to the user,exposing internal Skill markers is prohibited, and the diagnostic function corresponding to the step must be described in natural language. Internal markers that must be hidden include but are not limited to:

Internal file names / paths: such as references/REFERENCE.md、references/rdp-service.md、references/networking-tcpip.md , etc.
Internal terminology: Skill design concepts such as "routing table", "reference", "speculative troubleshooting", "dynamic planning", "step set", "event log pre-diagnosis", etc.
Internal numbers / labels: mechanical numbers such as Step 1、Step 2 , etc., as well as Direct/Contributing/Unrelated、Critical/Warning/Info、MUST the original wording of terms such as
Tool call details: implementation descriptions such as "call ReadReference / load xxx file"

Examples：

Do not say: "Now execute the steps in rdp-service.md" or "This issue is Direct + Critical"
Instead say: "Now check the TermService service status and RDP listening port configuration" or "This issue is a direct root cause and severely affects the connection"

Internal markers are only used for tool calls, logs, and the model's internal reasoning,and do not enterthe user-facing dialogue text.

Issue Understanding

Extract the core symptoms from the user's issue (error codes, prompt messages, user operations)
Confirm key context: Can the system start? Current execution environment (console/RDP/Cloud Assistant)?
When information is insufficient, MUST first ask the user follow-up questions(specific symptoms, error prompts, timing of operations, etc.), and only enter the path planning phase after collecting sufficient information
Record the original issue description; all subsequent analysis MUST revolve around this issue

Path Planning

Load diagnostic capabilities and routing table: read references/REFERENCE.md, to obtain the diagnostic capability list and issue routing table
Event log pre-diagnosis(optional):
- Collect key event logs (System, Application, Security) within the time period reported by the user
- Filter Error/Critical level events, and extract Event ID and source
- Based on event log characteristics, preliminarily define the problem direction (such as network-related, driver-related, service-related, security-related)
- Note: only collect and pre-analyze, do not execute specific diagnostic steps
Routing table matching(proprietary knowledge base and world knowledge may be used to assist judgment):
- Exact match → use the established sequence
- Fuzzy matching → use the closest sequence, but mark it as "speculative investigation"
Dynamic programming(when no route table entry is hit):
- Combine the user's problem description + event log pre-diagnosis results, and select relevant references from the diagnostic capability list
- Combine the investigation sequence and explain to the user: "This is a dynamically programmed investigation path, not a preset scenario"
Output: an ordered list of references (usually 2-5, avoid too many) + planning rationale
- When presenting the investigation path to the user, it is forbidden to use meaningless numbering such as "Step 1, Step 2"; you must describe the specific content to be checked at each step (e.g., "Check the TermService service status and listening port configuration")

Step-by-step execution

Load and execute diagnostics one by one according to the investigation sequence.

Single reference execution rules：

Read the reference file (references/{file}.md）
Select the relevant subset from the step set based on the user's problem
Strictly execute step by step: each step must complete the full process of "data collection → analysis and determination → normal/abnormal conclusion" before proceeding to the next step. It is forbidden to collect data for multiple steps in a batch and then analyze them all at once
- Each abnormal determination MUST have corresponding collected data as evidence
- Each step MUST give a clear binary normal/abnormal conclusion
- Discovered abnormalities MUST be associated with a specific root cause
- Collection scripts may be adjusted according to the actual situation, but the scripts provided in the reference file should be used as a starting point
When encountering a cross-reference → handle the jump target first, then return to the main sequence
Duplicate reference optimization: when the same reference is referenced multiple times, it only needs to be executed once, and subsequent uses directly reuse the existing results

Sequence control logic：

Early termination: the discovered root cause can already fully explain all of the user's symptoms → terminate subsequent references
Continue execution: only explains part of the symptoms → continue executing subsequent references
Direction correction: during execution, if the problem direction is found to be inconsistent with the initial plan → fall back to the path planning stage and replan based on new clues

Causal chain analysis

Summarize the findings of all references
Build a causal relationship chain (distinguish direct causes from indirect causes)
Prioritize according to relevance to the user's problem:Two-dimensional sorting by relation (Direct > Contributing > Unrelated) × severity (Critical > Warning > Info); Unrelated issues are listed separately as "Other findings" and are not mixed into the main repair plan
When there are no findings: try expanding the investigation scope; if there are still no findings → truthfully inform the user and provide suggested investigation directions

Repair plan

Provide an executable repair script for each root cause, and MUST include verification methods and expected results
Present in priority order
Show the complete repair content to the user and wait for explicit confirmation — it is forbidden to automatically execute any repair command
Same-issue aggregation: multiple modifications for the same root cause are merged into one script
Different-issue separation: repairs for different root causes are strictly separated and confirmed one by one
Operations involving system modifications MUST be marked with risk

Causal chain output specification

Causal chain example

[用户问题] 远程桌面连不上
    │
    ├── [Direct] TermService 服务已停止
    │       └── [Contributing] 依赖服务 RpcSs 异常
    │
    └── [Direct] 防火墙阻止 3389 端口
            └── [Contributing] 公共网络配置文件生效

Repair script template

#requires -RunAsAdministrator
# 修复：{根因名称}
# 风险：{风险说明}
# 验证：执行后运行 {验证命令} 确认修复结果

# --- 修复操作 ---
{修复命令}

# --- 验证 ---
{验证命令}

Diagnostic conclusion output template

Diagnostic Conclusion

User Problem: {original problem description}

A total of {N} problems were found, arranged by repair priority:

🔴 Problem 1 (Direct | Critical): {root_cause}

Evidence: {collected abnormal data}

Analysis: {why this problem directly caused the phenomenon the user observed}

Causal Chain: {user problem} ← {direct cause} ← {indirect cause (if any)}

Repair Plan：
{修复脚本}
Verification：
{验证命令}
Expected Result: {normal state}

🟡 Problem 2 (Contributing | Warning): {root_cause} ...

Gotchas (error-prone points)

Diagnostic Phase

Get-WmiObject is deprecated on some systems; prefer Get-CimInstance
Network connectivity checks need to distinguish between ICMP being blocked and true network unreachability
Principle for simplifying command output formats: when using commands to collect information, the output format MUST be as simple as possible to reduce the LLM's comprehension cost. Prefer Select-Object to output only key fields, avoiding lengthy full object output. Example:
- Recommended:Get-Service TermService | Select-Object Name, Status, StartType
- Not recommended:Get-Service TermService(output contains many irrelevant fields)
- Recommended:Get-Process | Sort-Object CPU -Descending | Select-Object -First 5 Id, Name, CPU
- Not recommended:Get-Process | Sort-Object CPU -Descending | Select-Object -First 5(outputs 20+ fields)
PowerShell formatted output delay：Select-Object objects returned enter the deferred formatting queue, and subsequent Write-Host output may reach the console before the table, causing output order to be scrambled. When writing collection scripts, after Select-Object you must append | Format-Table or | Format-List to force synchronous rendering, ensuring correct output order from the source

Avoid parsing the text output of cmd command lines: the field names in cmd command output vary with the system language, and parsing will produce different results on Chinese/English systems. Prefer PowerShell cmdlets instead; when no replacement is possible, pass the raw output directly to the LLM for analysis. Common replacements:

cmd command	PowerShell replacement
`net user`	`Get-LocalUser` / `Get-CimInstance Win32_UserAccount`
`net localgroup`	`Get-LocalGroupMember` / `Get-CimInstance Win32_GroupUser`
`netstat`	`Get-NetTCPConnection` / `Get-NetUDPEndpoint`
`ipconfig`	`Get-NetIPConfiguration` / `Get-NetIPAddress`
`tasklist`	`Get-Process` / `Get-CimInstance Win32_Process`
`sc query`	`Get-Service` / `Get-CimInstance Win32_Service`
`net accounts`	No direct replacement; pass raw output directly
`netsh`	No direct replacement; pass raw output directly
`fsutil`	No direct replacement; pass raw output directly
`bcdedit`	No direct replacement; pass raw output directly

Do not directly call GUI pop-up commands：slmgr、winver and other commands pop up graphical dialogs by default, which can cause hangs in unattended or non-interactive execution environments (such as cloud assistants, remote scripts). You must use the cscript //Nologo prefix to call the corresponding .vbs script and redirect the output to the console: for example cscript //Nologo C:\windows\system32\slmgr.vbs /dli instead of slmgr /dli
Encoding Standards: encoding issues are divided into two aspects: the input side (reading external command output) and the output side (PowerShell's own output):

Input Side — CMD/EXE Command Output Capture: the following commands use the system default code page (GBK/936 on Simplified Chinese systems), which is inconsistent with PowerShell's UTF8 encoding, and direct execution will cause garbled Chinese. When executing these commands, you MUST explicitly specify ProcessStartInfo via StandardOutputEncoding = [System.Text.Encoding]::GetEncoding(936) to correctly capture the output:
- w32tm — Windows Time Service command
- cscript — script host (e.g., slmgr.vbs)
- netsh — network configuration commands
- ipconfig — IP configuration commands
- net accounts — account policy commands
- pnputil — device driver tools
- bcdedit — boot configuration commands
- fsutil — file system tools
- icacls — permission management commands
- wusa — Windows Update Standalone Installer
- Other CMD/EXE commands not native to PowerShell
ProcessStartInfo wrapper template:
```
$psi = New-Object System.Diagnostics.ProcessStartInfo "<executable>", "<arguments>"
$psi.RedirectStandardOutput = $true; $psi.UseShellExecute = $false
$psi.StandardOutputEncoding = [System.Text.Encoding]::GetEncoding(936)
$p = [System.Diagnostics.Process]::Start($psi)
$p.StandardOutput.ReadToEnd(); $p.WaitForExit()
```
In the reference file, you can directly write the raw command (e.g., w32tm /query /source), and the agent automatically applies the ProcessStartInfo wrapper according to this rule during actual execution

Input side: The above rules are used to correctly capture the Chinese output of cmd commands and avoid garbled text
Variable naming avoids built-in identifiers: Custom variable names in PowerShell collection scripts MUST avoid built-in keywords (e.g., switch、foreach、function , etc.) and automatic variables (e.g., $_、$input、$args、$error、$host、$pwd、$foreach、$switch、$null、$true、$false , etc.). Misusing built-in identifiers can cause abnormal script behavior or variable values being overwritten, making troubleshooting difficult
Get-ItemProperty output filtering rules：Get-ItemProperty By default returns PowerShell metadata fields including PSPath、PSParentPath、PSChildName、PSDrive、PSProvider , etc., which interfere with diagnostic output. MUST filter these fields in one of the following ways:
1. Pipe to | Select-Object <目标属性> to explicitly select the needed properties (recommended, suitable for scenarios where the property names are known):Get-ItemProperty ... -Name ProxyEnable, ProxyServer | Select-Object ProxyEnable, ProxyServer
2. Pipe to | Select-Object -Property * -ExcludeProperty PSPath,PSParentPath,PSChildName,PSDrive,PSProvider(suitable for scenarios where all registry values are needed but metadata is excluded)
3. After variable assignment, extract the target property via [PSCustomObject] (suitable for scenarios requiring further processing) It is forbidden to directly output the complete result of Get-ItemProperty complete result

Repair phase

When repairing firewall rules, MUST retain existing rules, and only append or modify the target rule
Restarting the service may affect an RDP session in use; the user needs to be reminded
Before modifying the registry, MUST advise the user to back up the relevant key values first
RDP certificate repair involves MachineKeys permissions, and operations must be performed with caution

Output phase

The "indirect cause" in the causal chain does not necessarily need to be repaired (it may be a chain reaction from an upstream problem)
Issues marked as Unrelated should not be mixed into the main repair plan; list them separately as "Other Findings"
The troubleshooting path of the dynamic plan MUST be marked as speculative, and the user should be informed that this is not a preset troubleshooting sequence

Handling of non-existent commands

When a cmd tool or PowerShell cmdlet reports an error "command/module does not exist" during execution (e.g., CommandNotFoundException、'xxx' is not recognized as an internal or external command）→ directly skip that check item and do not retry
Reason: The system environment does not support the tool (e.g., a stripped-down system, component not installed, version too low, feature not enabled), and retrying will not produce a result
Handling method: Record "this check item was skipped because the tool is unavailable" and continue executing subsequent steps

Mixing PowerShell and cmd redirection syntax

It is forbidden to use cmd redirection syntax in PowerShell scripts(e.g., >nul、2>nul、1>nul), as this triggers the RedirectionFailed error
The correct way to discard output in PowerShell: use $null instead of nul, e.g., 2>$null、>$null
Example comparison:
- Incorrect:schtasks /query /fo LIST /v 2>nul | Select-String "TermService"
- Correct:schtasks /query /fo LIST /v 2>$null | Select-String "TermService"
- Recommended: Prefer PowerShell cmdlets (such as Get-ScheduledTask) instead of cmd commands

Command arguments containing curly braces MUST be wrapped in quotes

PowerShell treats bare {...} as a script block (ScriptBlock), and when passed to native commands (such as bcdedit、reg、schtasks , etc.) it will be incorrectly expanded into the -encodedCommand parameter, causing the command to fail
Typical symptom：bcdedit /enum {default} reports error Invalid command line switch: /encodedCommand / 参数错误
Rule: all literal arguments containing curly braces (BCD identifier {default} / {bootmgr} / {current} / {globalsettings} / GUID form {xxxxxxxx-xxxx-...} , etc.) MUST be wrapped in double quotes or single quotes before being passed to native commands
Example comparison:
- Incorrect:bcdedit /enum {default} 2>&1
- Correct:bcdedit /enum "{default}" 2>&1
- Incorrect:bcdedit /set {default} bootstatuspolicy IgnoreAllFailures
- Correct:bcdedit /set "{default}" bootstatuspolicy IgnoreAllFailures
The same applies to reg、wmic、schtasks、takeown and all other native cmd/exe tool invocations