基础工具与工作流 · daymade/claude-code-skills
windows-remote-desktop-connection-doctor
Diagnose Windows App (Microsoft Remote Desktop / Azure Virtual Desktop / W365 / direct PC) connection issues on macOS. Analyze transport protocol selection (UDP Shortpath vs WebSocket), detect VPN/proxy interference, parse Windows App logs for Shortpath failures, and resolve stuck "Configuring remote PC..." dialogs caused by expired Microsoft accounts, server reboots, or client-side auth poisoning. Use when VDI connections are slow or stuck, when direct PC connections fail to connect, when transport shows WebSocket instead of UDP, when RDP Shortpath fails, or when Windows App is frozen at a progress dialog.
L4 高权限 · 分级授权与审计V1 已固定执行命令联网Dual-pass Audit
管控等级描述 skill 的能力与建议配套的管控措施，不代表质量或安全认证，也不表示可用或不可用。是否使用由用户和管理者决定。不同 agent 宿主对权限的约束各不相同，请勿假定宿主一定会提供安全兜底。第三方 skill 版权归原作者，使用风险由使用者自行承担。
1实现原理 · 为什么它能做到
它按「连接类型」先分流再取证：AVD/WVD/W365 走 Connection Info 面板 + 网关健康检查 + Shortpath 日志；直连 PC 没有该面板，必须先跑 RDP 协议探针证明服务端活着，再查客户端身份/日志。分流决定后续用什么证据。
windows-remote-desktop-connection-doctor/SKILL.md
| Scenario | Key Characteristic | Primary Evidence Source | |---|---|---| | **AVD/WVD/W365** | User connects to a cloud desktop through a workspace/gateway | Connection Info panel, gateway health checks, UDP Shortpath logs | | **Direct PC** | User connects to a named PC by hostname or IP (e.g., a home workstation) | RDP protocol probe, Windows App log auth chain, Windows-side reboot events |
分流的可执行判据：'If Transport Protocol is `UDP` or `UDP Multicast`, the connection is optimal — no further diagnosis needed.' 否则进 Step 2。
核心取证手段是解析 Windows App 客户端日志——因为传输协商细节「没有任何网络层测试能揭示」，这是该 skill 不可替代的信息源。
windows-remote-desktop-connection-doctor/SKILL.md
This is the most critical step. Windows App logs contain transport negotiation details that no network-level test can reveal.
日志路径被写死给出：`~/Library/Containers/com.microsoft.rdc.macos/Data/Library/Logs/Windows App/`，文件名形如 `com.microsoft.rdc.macos_v<version>_<date>_<time>.log`。
自带探针脚本用「无凭据」方式证明服务端 RDP 栈健康：发 X.224 Connection Request + RDP_NEG_REQ，解析 RDP_NEG_RSP 得到协商的加密协议，再把同一 socket 升级到 TLS。
windows-remote-desktop-connection-doctor/scripts/probe_rdp_server.py
RDP_NEG_REQ_PACKET = bytes.fromhex("030000130ee000000000000100080003000000")
docstring 说明其目的：'Use this to falsify "the server is down" when Windows App is stuck at a progress dialog. A successful probe means the server-side RDP stack is healthy and the problem is almost certainly client-side (auth, identity, local proxy, app state).' 退出码被细分为 0/1/2/3/4（成功/用法错/TCP 失败/RDP 响应异常/TLS 失败）。
探针刻意关闭 TLS 证书校验，且文档明确交代理由与局限——目的是验证「服务端接受 TLS」而非认证服务端。
windows-remote-desktop-connection-doctor/references/direct_pc_and_auth_diagnostics.md
> **Note on TLS verification:** The probe intentionally disables certificate verification so it can confirm the RDP stack accepts TLS even with self-signed or domain-issued certificates. It does not authenticate the server. For a full certificate audit, use a separate TLS inspection tool.
代码侧对应：ctx.check_hostname = False; ctx.verify_mode = ssl.CERT_NONE，并带注释 'We intentionally disable verification because the diagnostic goal is to confirm the RDP stack accepts TLS, not to validate the certificate chain.'。
诊断纪律要求「先证明客户端还是服务端」——探针成功则问题在客户端（认证/应用状态/代理/身份），失败则问题在服务端或网络。这是把二元归因做成一条可执行的成败判据。
windows-remote-desktop-connection-doctor/SKILL.md
A successful probe reports `RDP server <host>:<port> is reachable and healthy (RDP + TLS).` and means the problem is **client-side** (auth, app state, proxy, or identity). A failed probe means the problem is **server-side or network** (PC off, firewall, port unreachable, TLS interception).
reference 侧给了完整判读表：TCP connect failed / RDP_NEG_FAILURE / TLS handshake failed / RDP + TLS OK 四种结果各自的含义。
它把六类根因写成可对照的证据签名表（VPN/代理干扰、ISP 限 UDP、客户端健康检查失败、服务端未开 Shortpath、客户端身份/账号毒化、服务端重启），每类都给「证据 → 修复 → 验证」三段。
windows-remote-desktop-connection-doctor/SKILL.md
#### Category E: Client Identity / Expired Microsoft Account Poisoning (Direct PC and AVD)
Category E 的关键洞见：'This can affect **direct PC connections** even when the expired account is unrelated to that PC, because the Windows App client shares the same auth orchestration across all connection types.'
验证阶段要求看客户端行为证据而非只看「能不能连上」：日志里要出现输入事件、且不得再有 UserCancelled(8)。
windows-remote-desktop-connection-doctor/SKILL.md
2. The Windows App log for the new session should show mouse/keyboard input events (`IHAddMouseEventToPDU`, `IHAddKeyboardEventToPDU`) and no `UserCancelled(8)` errors.
AVD 侧的验证则是回到 Connection Info 看 Transport Protocol 是否变成 UDP / UDP Multicast，并用 lsof 看 UDP 连接。
2核心能力
01AVD/W365 传输协议判定（UDP Shortpath vs WebSocket）与 RTT 对比
02Windows App 日志关键模式速查（健康检查、VPN 路由检测、FetchClientOptions 超时、证书失败、OneAuth 错误、连接丢弃、输入事件）
03带 GUID 的逐会话生命周期聚合（把一次连接尝试的事件串起来）
04无凭据的独立 RDP 协议 + TLS 健康探针（自带脚本）
05VPN/代理干扰识别与 DIRECT 规则修复（源 IP 198.18.0.x、STUN/TURN 走 VPN 的判据）
06UDP 受限排查（STUN 连通性实测脚本 + 移动热点/UPnP/IPv6 等处置选项）
07客户端身份毒化（过期微软账号）识别与修复（Settings→Accounts 移除旧账号并完全重启应用）
08服务端重启关联（Windows LastBootUpTime + Event ID 1074，含经 WSL/SSH 用 -EncodedCommand 传 PowerShell）
09工作正常 vs 故障日志的对照分析法（逐文件 grep 健康检查块）
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | python3（运行自带 RDP 探针与文档内联的 STUN 检测脚本） |
| cli | macOS 网络工具（ifconfig / netstat / scutil / lsof / ps / env / tailscale） |
| cli | grep（日志模式提取，文档给成套 grep -E 模板） |
| cli | ssh + PowerShell -EncodedCommand（经 WSL/Tailscale 到 Windows 主机取证） |
| cli | curl（读 ShadowRocket 配置 API 以核对代理状态） |
| api | Azure Virtual Desktop 网关/工作区端点（日志中出现，用于 DIRECT 规则配置示例） |
| network | STUN 公共服务器（测试 UDP 是否被 ISP 封锁） |
| network | 目标 RDP 主机（用户指定的 host:3389 或自定义端口，探针与日志分析的对象） |
| network | Windows 侧 RDP 主机（经 SSH/Tailscale 执行 PowerShell 取证） |
| network | Tailscale（netcheck/status，用于 NAT 类型与 UDP 能力评估） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: python3 scripts/probe_rdp_server.py <host> [port]（仓库自带；对目标主机发 TCP 连接 + RDP
- 网络端点: 声明外部网络访问: TCP 连接到用户指定 RDP 主机:3389（或自定义端口），发送 RDP 协商包并升级 TLS
审计说明： 。依据：本 skill 不读取任何凭据（无密码/token/keychain/env 密钥），不写任何文件（frontmatter 只声明 Read, Grep, Bash），也没有反爬或批量采集行为；它做的网络动作是「对用户指定主机做 RDP 协议+TLS 握手」与「向公共 STUN 服务器测 UDP」，都是诊断必需且不发用户数据。触发黄档（而非蓝档）的是两点常规网络行为：①主动对目标主机发起 TCP/TLS 探针与 UDP STUN 探测——外发对象可预期但确实是网络行为；②会读取本机 Windows App 日志，其中含微软账号邮箱与租户/主机名等身份信息。关于「探针关闭 TLS 证书校验」：确属安全降级手法，但它是无凭据、无数据的连通性探针，且文档与代码都明确交代了目的与局限（'It does not authenticate the server.'），不构成对数据通道的降级，故不据此升档；若把该做法照搬到有数据流的场景才是问题。使用建议：只对自己有权探测的主机运行；日志片段不要整段外发（含账号邮箱）。
5第二遍独立确认
- [ok] 探针「无凭据」声明是否有反例（是否真的不读认证材料） — 反例检索失败：probe_rdp_server.py 的 import 为 socket/ssl/struct/sys/typing，无 os.environ/getenv、无 open()、无 keychain 调用；全流程是 create_connection → sendall(19 字节固定握手包) → recv → wrap_socket。凭据类 token 在全目录 grep（password/token/secret/api_key/credential）除文档描述「认证失败」的语义词外零命中。声明成立。
- [ok] TLS 校验关闭是否为「未交代的松绑」 — 已充分交代：代码内注释 'We intentionally disable verification because the diagnostic goal is to confirm the RDP stack accepts TLS, not to validate the certificate chain.'；reference 内有专门引用块说明 'The probe intentionally disables certificate verification... It does not authenticate the server. For a full certificate audit, use a separate TLS inspection tool.'。属有意识、有边界说明的设计，不是隐藏降级。已记入 security.injection_surface 与 grade.reason。
- [ok] 是否漏记外发目标（域名/IP 全量回查） — 提取结果：stun.l.google.com:19302、stun1.l.google.com:19302、rdweb.wvd.microsoft.com、<prefix>-rdgateway-r1.wvd.microsoft.com、*.wvd.microsoft.com（DIRECT 规则示例）、13.104.0.0/14（IP-CIDR 示例）、<local-ip>:8080（ShadowRocket 配置 API）、<host>:3389（用户指定目标）。均已归入 external_deps 的 12 个条目；无未记载的隐蔽外发。
- [ok] frontmatter 的 allowed-tools 声明与文档行为是否一致 — 声明为 `allowed-tools: Read, Grep, Bash`。文档要求的动作是：读日志（Read/grep）、跑 ifconfig/netstat/scutil/lsof/tailscale/ps（Bash）、跑探针与内联 python（Bash）——全部落在声明范围内；且文档不要求写文件（无 chmod/编辑配置/生成文件的步骤，AVD 的 DIRECT 规则是以「给用户的修法」形式给出，由用户在代理工具里配置，而非本 skill 直接改配置）。声明与行为一致，且比同仓库的 tunnel-doctor（含 Edit）更保守。
- [ok] 是否有未实现的宣称（能力 vs 文档） — 逐项抽查成立：承诺「分析传输协议选择」→ 有 Connection Info 字段表与日志 FetchClientOptions/WebRTC 条目；承诺「解析日志找 Shortpath 失败」→ 有日志模式→含义对照表与 GUID 聚合方法；承诺「解决卡在 Configuring remote PC」→ 有 Category E 完整签名集与修复步骤；承诺「检测 VPN/代理干扰」→ 有 198.18.0.x、STUN/TURN routed through VPN 的判据与 DIRECT 规则修法。均有对应实现/流程支撑，未见夸大。
- [ok] 文档内部是否存在自相矛盾（如是否同时建议放宽校验又不建议） — 抽查与 tunnel-doctor 类似的张力点：本 skill 未出现 ssh -o StrictHostKeyChecking=no；唯一放宽是探针的 CERT_NONE，且被解释为「验证服务端接受 TLS」的必需手法并有明确局限说明。未发现未消解的内部矛盾。
- [ok] pin commit 与 skill.path 是否与任务书表格一致 — git rev-parse HEAD = d5c4678cb5d4fd6acc9c922690df035dbd33d247，与任务书表格『库内 HEAD』逐字一致；目录位于仓库根，相对路径 windows-remote-desktop-connection-doctor；本目录最后一次提交 878f947（2026-09-07）。GitHub API 复核 MIT / stars 1392 / pushed 2026-09-15T09:30:04Z。
- [ok] evidence 逐字性是否经磁盘级复核 — 【evidence 逐字性校正】首稿该条 quote 把源码第 152 行的 grep 模板截断且过度转义（把 `\|` 写成 `\\|`），导致未与源文逐字匹配；已改为源码中的真实前缀（截到 `"$LATEST_LOG"` 为止，避开后续含反斜杠的 `grep -v` 段）。该 grep 模板确实存在，结论未变，属引用精度问题。
6结论
适合： 适合：用 macOS 上的 Windows App 连 AVD/W365/家里 PC，遇到「连不上、卡在 Configuring remote PC、延迟异常高、传输显示 WebSocket 而不是 UDP」的人；也适合想把「到底是客户端还是服务端的问题」一次性定型、而不是反复重启应用碰运气的人。对需要给同事/自己排查 VDI 体验的中文网络环境用户尤其适用（文档对证书替换、DNS 污染、UDP 限速有专门分类）。
不适合： 不适合：非 macOS 客户端（文档与日志路径都针对 com.microsoft.rdc.macos）；不使用 Windows App 的 RDP 客户端（mstsc/FreeRDP 的日志与传输语义不同）；纯应用层或服务端内部故障（应在服务端排查）；以及不愿对目标主机做主动探测的场景。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload windows-remote-desktop-connection-doctor.tar.gz
sha256:
Option B · Copy Guide for Agentc5c2e8a79a426da5…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.