Release v1.32.0: Add windows-remote-desktop-connection-doctor skill
- Add windows-remote-desktop-connection-doctor v1.0.0 for diagnosing AVD/W365 connection quality issues with transport protocol analysis and log parsing - Update claude-md-progressive-disclosurer SKILL.md and references - Update marketplace to v1.32.0 (37 skills) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
daymade
@@ -5,8 +5,8 @@
|
|||||||
"email": "daymadev89@gmail.com"
|
"email": "daymadev89@gmail.com"
|
||||||
},
|
},
|
||||||
"metadata": {
|
"metadata": {
|
||||||
"description": "Professional Claude Code skills for GitHub operations, document conversion, diagram generation, statusline customization, Teams communication, repomix utilities, skill creation, CLI demo generation, LLM icon access, Cloudflare troubleshooting, UI design system extraction, professional presentation creation, YouTube video downloading, secure repomix packaging, ASR transcription correction, video comparison quality analysis, comprehensive QA testing infrastructure, prompt optimization with EARS methodology, session history recovery, documentation cleanup, format-controlled deep research report generation with evidence tracking, PDF generation with Chinese font support, CLAUDE.md progressive disclosure optimization, CCPM skill registry search and management, Promptfoo LLM evaluation framework, iOS app development with XcodeGen and SwiftUI, fact-checking with automated corrections, Twitter/X content fetching, intelligent macOS disk space recovery, skill quality review and improvement, GitHub contribution strategy, complete internationalization/localization setup, plugin/skill troubleshooting with diagnostic tools, and evidence-based competitor analysis with source citations",
|
"description": "Professional Claude Code skills for GitHub operations, document conversion, diagram generation, statusline customization, Teams communication, repomix utilities, skill creation, CLI demo generation, LLM icon access, Cloudflare troubleshooting, UI design system extraction, professional presentation creation, YouTube video downloading, secure repomix packaging, ASR transcription correction, video comparison quality analysis, comprehensive QA testing infrastructure, prompt optimization with EARS methodology, session history recovery, documentation cleanup, format-controlled deep research report generation with evidence tracking, PDF generation with Chinese font support, CLAUDE.md progressive disclosure optimization, CCPM skill registry search and management, Promptfoo LLM evaluation framework, iOS app development with XcodeGen and SwiftUI, fact-checking with automated corrections, Twitter/X content fetching, intelligent macOS disk space recovery, skill quality review and improvement, GitHub contribution strategy, complete internationalization/localization setup, plugin/skill troubleshooting with diagnostic tools, evidence-based competitor analysis with source citations, and Windows Remote Desktop (AVD/W365) connection quality diagnosis with transport protocol analysis and log parsing",
|
||||||
"version": "1.31.0",
|
"version": "1.32.0",
|
||||||
"homepage": "https://github.com/daymade/claude-code-skills"
|
"homepage": "https://github.com/daymade/claude-code-skills"
|
||||||
},
|
},
|
||||||
"plugins": [
|
"plugins": [
|
||||||
@@ -753,6 +753,33 @@
|
|||||||
"skills": [
|
"skills": [
|
||||||
"./tunnel-doctor"
|
"./tunnel-doctor"
|
||||||
]
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "windows-remote-desktop-connection-doctor",
|
||||||
|
"description": "Diagnose Windows App (Microsoft Remote Desktop / Azure Virtual Desktop / W365) connection quality issues on macOS. Analyze transport protocol selection (UDP Shortpath vs WebSocket), detect VPN/proxy interference with STUN/TURN negotiation, and parse Windows App logs for Shortpath failures. This skill should be used when VDI connections are slow, when transport shows WebSocket instead of UDP, when RDP Shortpath fails to establish, or when RTT is unexpectedly high.",
|
||||||
|
"source": "./",
|
||||||
|
"strict": false,
|
||||||
|
"version": "1.0.0",
|
||||||
|
"category": "developer-tools",
|
||||||
|
"keywords": [
|
||||||
|
"rdp",
|
||||||
|
"avd",
|
||||||
|
"wvd",
|
||||||
|
"w365",
|
||||||
|
"windows-app",
|
||||||
|
"remote-desktop",
|
||||||
|
"shortpath",
|
||||||
|
"udp",
|
||||||
|
"websocket",
|
||||||
|
"stun",
|
||||||
|
"turn",
|
||||||
|
"vpn",
|
||||||
|
"macos",
|
||||||
|
"networking"
|
||||||
|
],
|
||||||
|
"skills": [
|
||||||
|
"./windows-remote-desktop-connection-doctor"
|
||||||
|
]
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
|
|||||||
20
CHANGELOG.md
20
CHANGELOG.md
@@ -10,6 +10,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||||||
### Added
|
### Added
|
||||||
- None
|
- None
|
||||||
|
|
||||||
|
## [1.32.0] - 2026-02-09
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- **New Skill**: windows-remote-desktop-connection-doctor - Diagnose AVD/W365 connection quality issues
|
||||||
|
- 5-step diagnostic workflow for transport protocol analysis
|
||||||
|
- UDP Shortpath vs WebSocket detection and root cause identification
|
||||||
|
- VPN/proxy interference detection (ShadowRocket, Clash, Tailscale)
|
||||||
|
- Windows App log parsing for STUN/TURN/ICE negotiation failures
|
||||||
|
- ISP UDP restriction testing and Chinese ISP-specific guidance
|
||||||
|
- Bundled references: windows_app_log_analysis.md, avd_transport_protocols.md
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- Updated marketplace skills count from 36 to 37
|
||||||
|
- Updated marketplace version from 1.31.0 to 1.32.0
|
||||||
|
- Updated README.md badges (skills count, version)
|
||||||
|
- Updated README.md to include windows-remote-desktop-connection-doctor in skills listing
|
||||||
|
- Updated README.zh-CN.md badges (skills count, version)
|
||||||
|
- Updated README.zh-CN.md to include windows-remote-desktop-connection-doctor in skills listing
|
||||||
|
- Updated CLAUDE.md skills count from 36 to 37
|
||||||
|
|
||||||
## [1.31.0] - 2026-02-07
|
## [1.31.0] - 2026-02-07
|
||||||
|
|
||||||
### Added
|
### Added
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|||||||
|
|
||||||
## Repository Overview
|
## Repository Overview
|
||||||
|
|
||||||
This is a Claude Code skills marketplace containing 36 production-ready skills organized in a plugin marketplace structure. Each skill is a self-contained package that extends Claude's capabilities with specialized knowledge, workflows, and bundled resources.
|
This is a Claude Code skills marketplace containing 37 production-ready skills organized in a plugin marketplace structure. Each skill is a self-contained package that extends Claude's capabilities with specialized knowledge, workflows, and bundled resources.
|
||||||
|
|
||||||
**Essential Skill**: `skill-creator` is the most important skill in this marketplace - it's a meta-skill that enables users to create their own skills. Always recommend it first for users interested in extending Claude Code.
|
**Essential Skill**: `skill-creator` is the most important skill in this marketplace - it's a meta-skill that enables users to create their own skills. Always recommend it first for users interested in extending Claude Code.
|
||||||
|
|
||||||
@@ -134,7 +134,7 @@ Skills for public distribution must NOT contain:
|
|||||||
## Marketplace Configuration
|
## Marketplace Configuration
|
||||||
|
|
||||||
The marketplace is configured in `.claude-plugin/marketplace.json`:
|
The marketplace is configured in `.claude-plugin/marketplace.json`:
|
||||||
- Contains 36 plugins, each mapping to one skill
|
- Contains 37 plugins, each mapping to one skill
|
||||||
- Each plugin has: name, description, version, category, keywords, skills array
|
- Each plugin has: name, description, version, category, keywords, skills array
|
||||||
- Marketplace metadata: name, owner, version, homepage
|
- Marketplace metadata: name, owner, version, homepage
|
||||||
|
|
||||||
@@ -144,7 +144,7 @@ The marketplace is configured in `.claude-plugin/marketplace.json`:
|
|||||||
|
|
||||||
1. **Marketplace Version** (`.claude-plugin/marketplace.json` → `metadata.version`)
|
1. **Marketplace Version** (`.claude-plugin/marketplace.json` → `metadata.version`)
|
||||||
- Tracks the marketplace catalog as a whole
|
- Tracks the marketplace catalog as a whole
|
||||||
- Current: v1.31.0
|
- Current: v1.32.0
|
||||||
- Bump when: Adding/removing skills, major marketplace restructuring
|
- Bump when: Adding/removing skills, major marketplace restructuring
|
||||||
- Semantic versioning: MAJOR.MINOR.PATCH
|
- Semantic versioning: MAJOR.MINOR.PATCH
|
||||||
|
|
||||||
@@ -196,6 +196,7 @@ The marketplace is configured in `.claude-plugin/marketplace.json`:
|
|||||||
34. **deep-research** - Generate format-controlled research reports with evidence mapping, citations, and multi-pass synthesis
|
34. **deep-research** - Generate format-controlled research reports with evidence mapping, citations, and multi-pass synthesis
|
||||||
35. **competitors-analysis** - Evidence-based competitor tracking and analysis with source citations (file:line_number format)
|
35. **competitors-analysis** - Evidence-based competitor tracking and analysis with source citations (file:line_number format)
|
||||||
36. **tunnel-doctor** - Diagnose and fix Tailscale + proxy/VPN route conflicts on macOS with WSL SSH support
|
36. **tunnel-doctor** - Diagnose and fix Tailscale + proxy/VPN route conflicts on macOS with WSL SSH support
|
||||||
|
37. **windows-remote-desktop-connection-doctor** - Diagnose AVD/W365 connection quality issues with transport protocol analysis and Windows App log parsing
|
||||||
|
|
||||||
**Recommendation**: Always suggest `skill-creator` first for users interested in creating skills or extending Claude Code.
|
**Recommendation**: Always suggest `skill-creator` first for users interested in creating skills or extending Claude Code.
|
||||||
|
|
||||||
|
|||||||
52
README.md
52
README.md
@@ -6,15 +6,15 @@
|
|||||||
[](./README.zh-CN.md)
|
[](./README.zh-CN.md)
|
||||||
|
|
||||||
[](https://opensource.org/licenses/MIT)
|
[](https://opensource.org/licenses/MIT)
|
||||||
[](https://github.com/daymade/claude-code-skills)
|
[](https://github.com/daymade/claude-code-skills)
|
||||||
[](https://github.com/daymade/claude-code-skills)
|
[](https://github.com/daymade/claude-code-skills)
|
||||||
[](https://claude.com/code)
|
[](https://claude.com/code)
|
||||||
[](./CONTRIBUTING.md)
|
[](./CONTRIBUTING.md)
|
||||||
[](https://github.com/daymade/claude-code-skills/graphs/commit-activity)
|
[](https://github.com/daymade/claude-code-skills/graphs/commit-activity)
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
Professional Claude Code skills marketplace featuring 36 production-ready skills for enhanced development workflows.
|
Professional Claude Code skills marketplace featuring 37 production-ready skills for enhanced development workflows.
|
||||||
|
|
||||||
## 📑 Table of Contents
|
## 📑 Table of Contents
|
||||||
|
|
||||||
@@ -222,6 +222,9 @@ claude plugin install skill-reviewer@daymade-skills
|
|||||||
|
|
||||||
# GitHub contribution strategy
|
# GitHub contribution strategy
|
||||||
claude plugin install github-contributor@daymade-skills
|
claude plugin install github-contributor@daymade-skills
|
||||||
|
|
||||||
|
# Windows Remote Desktop / AVD connection diagnosis
|
||||||
|
claude plugin install windows-remote-desktop-connection-doctor@daymade-skills
|
||||||
```
|
```
|
||||||
|
|
||||||
Each skill can be installed independently - choose only what you need!
|
Each skill can be installed independently - choose only what you need!
|
||||||
@@ -1539,6 +1542,45 @@ claude plugin install tunnel-doctor@daymade-skills
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
### 37. **windows-remote-desktop-connection-doctor** - AVD/W365 Connection Quality Diagnostician
|
||||||
|
|
||||||
|
Diagnose Windows App (Microsoft Remote Desktop / Azure Virtual Desktop / W365) connection quality issues on macOS, with focus on transport protocol optimization (UDP Shortpath vs WebSocket fallback).
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- VDI connection is slow with high RTT (>100ms)
|
||||||
|
- Transport Protocol shows WebSocket instead of UDP
|
||||||
|
- RDP Shortpath fails to establish
|
||||||
|
- Connection quality degraded after changing network location
|
||||||
|
- Need to identify VPN/proxy interference with STUN/TURN
|
||||||
|
|
||||||
|
**Key features:**
|
||||||
|
- 5-step diagnostic workflow from connection info collection to fix verification
|
||||||
|
- Transport protocol analysis (UDP Shortpath > TCP > WebSocket hierarchy)
|
||||||
|
- VPN/proxy interference detection (ShadowRocket TUN mode, Tailscale exit node)
|
||||||
|
- Windows App log parsing for health check failures, certificate errors, FetchClientOptions timeouts
|
||||||
|
- ISP UDP restriction testing with STUN connectivity checks
|
||||||
|
- Chinese ISP-specific guidance for UDP throttling issues
|
||||||
|
- Working vs broken log comparison methodology
|
||||||
|
|
||||||
|
**Example usage:**
|
||||||
|
```bash
|
||||||
|
# Install the skill
|
||||||
|
claude plugin install windows-remote-desktop-connection-doctor@daymade-skills
|
||||||
|
|
||||||
|
# Then ask Claude to diagnose
|
||||||
|
"My VDI connection shows WebSocket instead of UDP, RTT is 165ms"
|
||||||
|
"Diagnose why RDP Shortpath is not working"
|
||||||
|
"Windows App transport protocol stuck on WebSocket"
|
||||||
|
```
|
||||||
|
|
||||||
|
**🎬 Live Demo**
|
||||||
|
|
||||||
|
*Coming soon*
|
||||||
|
|
||||||
|
📚 **Documentation**: See [windows-remote-desktop-connection-doctor/references/](./windows-remote-desktop-connection-doctor/references/) for log analysis patterns and AVD transport protocol details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 🎬 Interactive Demo Gallery
|
## 🎬 Interactive Demo Gallery
|
||||||
|
|
||||||
Want to see all demos in one place with click-to-enlarge functionality? Check out our [interactive demo gallery](./demos/index.html) or browse the [demos directory](./demos/).
|
Want to see all demos in one place with click-to-enlarge functionality? Check out our [interactive demo gallery](./demos/index.html) or browse the [demos directory](./demos/).
|
||||||
@@ -1623,6 +1665,9 @@ Use **i18n-expert** to set up complete i18n infrastructure for React/Next.js/Vue
|
|||||||
### For Network & VPN Troubleshooting
|
### For Network & VPN Troubleshooting
|
||||||
Use **tunnel-doctor** to diagnose and fix route conflicts between Tailscale and proxy/VPN tools on macOS. Essential when Tailscale ping works but TCP connections fail, or when setting up Tailscale SSH to WSL instances alongside Shadowrocket, Clash, or Surge.
|
Use **tunnel-doctor** to diagnose and fix route conflicts between Tailscale and proxy/VPN tools on macOS. Essential when Tailscale ping works but TCP connections fail, or when setting up Tailscale SSH to WSL instances alongside Shadowrocket, Clash, or Surge.
|
||||||
|
|
||||||
|
### For Remote Desktop & VDI Optimization
|
||||||
|
Use **windows-remote-desktop-connection-doctor** to diagnose Azure Virtual Desktop / W365 connection quality issues on macOS. Essential when transport shows WebSocket instead of UDP Shortpath, when RTT is unexpectedly high, or when RDP Shortpath fails after changing network locations. Combines network evidence gathering with Windows App log analysis for systematic root cause identification.
|
||||||
|
|
||||||
### For Plugin & Skill Troubleshooting
|
### For Plugin & Skill Troubleshooting
|
||||||
Use **claude-skills-troubleshooting** to diagnose and resolve Claude Code plugin and skill configuration issues. Debug why plugins appear installed but don't show in available skills, understand the installed_plugins.json vs settings.json enabledPlugins architecture, and batch-enable missing plugins from a marketplace. Essential for marketplace maintainers debugging installation issues, developers troubleshooting skill activation, or anyone confused by the GitHub #17832 auto-enable bug.
|
Use **claude-skills-troubleshooting** to diagnose and resolve Claude Code plugin and skill configuration issues. Debug why plugins appear installed but don't show in available skills, understand the installed_plugins.json vs settings.json enabledPlugins architecture, and batch-enable missing plugins from a marketplace. Essential for marketplace maintainers debugging installation issues, developers troubleshooting skill activation, or anyone confused by the GitHub #17832 auto-enable bug.
|
||||||
|
|
||||||
@@ -1670,6 +1715,7 @@ Each skill includes:
|
|||||||
- **claude-skills-troubleshooting**: See `claude-skills-troubleshooting/SKILL.md` for plugin troubleshooting workflow and architecture
|
- **claude-skills-troubleshooting**: See `claude-skills-troubleshooting/SKILL.md` for plugin troubleshooting workflow and architecture
|
||||||
- **fact-checker**: See `fact-checker/SKILL.md` for fact-checking workflow and claim verification process
|
- **fact-checker**: See `fact-checker/SKILL.md` for fact-checking workflow and claim verification process
|
||||||
- **competitors-analysis**: See `competitors-analysis/SKILL.md` for evidence-based analysis workflow and `competitors-analysis/references/profile_template.md` for competitor profile template
|
- **competitors-analysis**: See `competitors-analysis/SKILL.md` for evidence-based analysis workflow and `competitors-analysis/references/profile_template.md` for competitor profile template
|
||||||
|
- **windows-remote-desktop-connection-doctor**: See `windows-remote-desktop-connection-doctor/references/windows_app_log_analysis.md` for log parsing patterns and `windows-remote-desktop-connection-doctor/references/avd_transport_protocols.md` for transport protocol details
|
||||||
|
|
||||||
## 🛠️ Requirements
|
## 🛠️ Requirements
|
||||||
|
|
||||||
|
|||||||
@@ -6,15 +6,15 @@
|
|||||||
[](./README.zh-CN.md)
|
[](./README.zh-CN.md)
|
||||||
|
|
||||||
[](https://opensource.org/licenses/MIT)
|
[](https://opensource.org/licenses/MIT)
|
||||||
[](https://github.com/daymade/claude-code-skills)
|
[](https://github.com/daymade/claude-code-skills)
|
||||||
[](https://github.com/daymade/claude-code-skills)
|
[](https://github.com/daymade/claude-code-skills)
|
||||||
[](https://claude.com/code)
|
[](https://claude.com/code)
|
||||||
[](./CONTRIBUTING.md)
|
[](./CONTRIBUTING.md)
|
||||||
[](https://github.com/daymade/claude-code-skills/graphs/commit-activity)
|
[](https://github.com/daymade/claude-code-skills/graphs/commit-activity)
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
专业的 Claude Code 技能市场，提供 36 个生产就绪的技能，用于增强开发工作流。
|
专业的 Claude Code 技能市场，提供 37 个生产就绪的技能，用于增强开发工作流。
|
||||||
|
|
||||||
## 📑 目录
|
## 📑 目录
|
||||||
|
|
||||||
@@ -225,6 +225,9 @@ claude plugin install skill-reviewer@daymade-skills
|
|||||||
|
|
||||||
# GitHub 贡献策略
|
# GitHub 贡献策略
|
||||||
claude plugin install github-contributor@daymade-skills
|
claude plugin install github-contributor@daymade-skills
|
||||||
|
|
||||||
|
# Windows 远程桌面 / AVD 连接诊断
|
||||||
|
claude plugin install windows-remote-desktop-connection-doctor@daymade-skills
|
||||||
```
|
```
|
||||||
|
|
||||||
每个技能都可以独立安装 - 只选择你需要的！
|
每个技能都可以独立安装 - 只选择你需要的！
|
||||||
@@ -1581,6 +1584,45 @@ claude plugin install tunnel-doctor@daymade-skills
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
### 37. **windows-remote-desktop-connection-doctor** - AVD/W365 连接质量诊断
|
||||||
|
|
||||||
|
诊断 macOS 上 Windows App（Microsoft Remote Desktop / Azure Virtual Desktop / W365）连接质量问题，专注于传输协议优化（UDP Shortpath vs WebSocket 回退）。
|
||||||
|
|
||||||
|
**使用场景：**
|
||||||
|
- VDI 连接缓慢，RTT 高（>100ms）
|
||||||
|
- 传输协议显示 WebSocket 而非 UDP
|
||||||
|
- RDP Shortpath 无法建立
|
||||||
|
- 更换网络位置后连接质量下降
|
||||||
|
- 需要识别 VPN/代理对 STUN/TURN 的干扰
|
||||||
|
|
||||||
|
**主要功能：**
|
||||||
|
- 5 步诊断流程：从连接信息收集到修复验证
|
||||||
|
- 传输协议分析（UDP Shortpath > TCP > WebSocket 优先级）
|
||||||
|
- VPN/代理干扰检测（ShadowRocket TUN 模式、Tailscale 出口节点）
|
||||||
|
- Windows App 日志解析：健康检查失败、证书错误、FetchClientOptions 超时
|
||||||
|
- ISP UDP 限制测试与 STUN 连通性检查
|
||||||
|
- 中国 ISP UDP 限速的专门指导
|
||||||
|
- 正常 vs 异常日志对比方法论
|
||||||
|
|
||||||
|
**示例用法：**
|
||||||
|
```bash
|
||||||
|
# 安装技能
|
||||||
|
claude plugin install windows-remote-desktop-connection-doctor@daymade-skills
|
||||||
|
|
||||||
|
# 然后让 Claude 诊断
|
||||||
|
"我的 VDI 连接显示 WebSocket 而不是 UDP，RTT 165ms"
|
||||||
|
"诊断为什么 RDP Shortpath 不工作"
|
||||||
|
"Windows App 传输协议一直是 WebSocket"
|
||||||
|
```
|
||||||
|
|
||||||
|
**🎬 实时演示**
|
||||||
|
|
||||||
|
*即将推出*
|
||||||
|
|
||||||
|
📚 **文档**：参见 [windows-remote-desktop-connection-doctor/references/](./windows-remote-desktop-connection-doctor/references/) 了解日志分析模式和 AVD 传输协议详情。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 🎬 交互式演示画廊
|
## 🎬 交互式演示画廊
|
||||||
|
|
||||||
想要在一个地方查看所有演示并具有点击放大功能？访问我们的[交互式演示画廊](./demos/index.html)或浏览[演示目录](./demos/)。
|
想要在一个地方查看所有演示并具有点击放大功能？访问我们的[交互式演示画廊](./demos/index.html)或浏览[演示目录](./demos/)。
|
||||||
@@ -1665,6 +1707,9 @@ claude plugin install tunnel-doctor@daymade-skills
|
|||||||
### 网络与 VPN 故障排查
|
### 网络与 VPN 故障排查
|
||||||
使用 **tunnel-doctor** 诊断和修复 macOS 上 Tailscale 与代理/VPN 工具的路由冲突。当 Tailscale ping 正常但 TCP 连接失败，或在使用 Shadowrocket、Clash、Surge 的同时设置 Tailscale SSH 到 WSL 实例时特别有用。
|
使用 **tunnel-doctor** 诊断和修复 macOS 上 Tailscale 与代理/VPN 工具的路由冲突。当 Tailscale ping 正常但 TCP 连接失败，或在使用 Shadowrocket、Clash、Surge 的同时设置 Tailscale SSH 到 WSL 实例时特别有用。
|
||||||
|
|
||||||
|
### 远程桌面与 VDI 优化
|
||||||
|
使用 **windows-remote-desktop-connection-doctor** 诊断 macOS 上 Azure Virtual Desktop / W365 连接质量问题。当传输协议显示 WebSocket 而非 UDP Shortpath、RTT 异常高，或更换网络位置后 RDP Shortpath 失败时特别有用。结合网络证据收集与 Windows App 日志分析，系统性定位根因。
|
||||||
|
|
||||||
### 插件与技能故障排除
|
### 插件与技能故障排除
|
||||||
使用 **claude-skills-troubleshooting** 诊断和解决 Claude Code 插件和技能配置问题。调试为什么插件显示已安装但未显示在可用技能列表中、了解 installed_plugins.json 与 settings.json enabledPlugins 架构，以及批量启用市场中缺失的插件。非常适合市场维护者调试安装问题、开发者调试技能激活，或任何对 GitHub #17832 自动启用 bug 感到困惑的人。
|
使用 **claude-skills-troubleshooting** 诊断和解决 Claude Code 插件和技能配置问题。调试为什么插件显示已安装但未显示在可用技能列表中、了解 installed_plugins.json 与 settings.json enabledPlugins 架构，以及批量启用市场中缺失的插件。非常适合市场维护者调试安装问题、开发者调试技能激活，或任何对 GitHub #17832 自动启用 bug 感到困惑的人。
|
||||||
|
|
||||||
@@ -1712,6 +1757,7 @@ claude plugin install tunnel-doctor@daymade-skills
|
|||||||
- **claude-skills-troubleshooting**：参见 `claude-skills-troubleshooting/SKILL.md` 了解插件故障排除工作流程和架构
|
- **claude-skills-troubleshooting**：参见 `claude-skills-troubleshooting/SKILL.md` 了解插件故障排除工作流程和架构
|
||||||
- **fact-checker**：参见 `fact-checker/SKILL.md` 了解事实核查工作流程和声明验证过程
|
- **fact-checker**：参见 `fact-checker/SKILL.md` 了解事实核查工作流程和声明验证过程
|
||||||
- **competitors-analysis**：参见 `competitors-analysis/SKILL.md` 了解证据驱动的分析工作流程和 `competitors-analysis/references/profile_template.md` 了解竞品档案模板
|
- **competitors-analysis**：参见 `competitors-analysis/SKILL.md` 了解证据驱动的分析工作流程和 `competitors-analysis/references/profile_template.md` 了解竞品档案模板
|
||||||
|
- **windows-remote-desktop-connection-doctor**：参见 `windows-remote-desktop-connection-doctor/references/windows_app_log_analysis.md` 了解日志解析模式和 `windows-remote-desktop-connection-doctor/references/avd_transport_protocols.md` 了解传输协议详情
|
||||||
|
|
||||||
## 🛠️ 系统要求
|
## 🛠️ 系统要求
|
||||||
|
|
||||||
|
|||||||
@@ -2,8 +2,8 @@
|
|||||||
name: claude-md-progressive-disclosurer
|
name: claude-md-progressive-disclosurer
|
||||||
description: |
|
description: |
|
||||||
Optimize CLAUDE.md files using progressive disclosure.
|
Optimize CLAUDE.md files using progressive disclosure.
|
||||||
Goal: Maximize LLM working efficiency, NOT minimize line count.
|
Goal: Maximize information efficiency, readability, and maintainability.
|
||||||
Use when: User wants to optimize CLAUDE.md, complains about context issues, or file exceeds 500 lines.
|
Use when: User wants to optimize CLAUDE.md, information is duplicated across files, or LLM repeatedly fails to follow rules.
|
||||||
---
|
---
|
||||||
|
|
||||||
# CLAUDE.md 渐进式披露优化器
|
# CLAUDE.md 渐进式披露优化器
|
||||||
@@ -12,7 +12,14 @@ description: |
|
|||||||
|
|
||||||
> "找到最小的高信号 token 集合，最大化期望结果的可能性。" — Anthropic
|
> "找到最小的高信号 token 集合，最大化期望结果的可能性。" — Anthropic
|
||||||
|
|
||||||
**目标是最大化 LLM 工作效能，而非最小化行数。**
|
**目标是最大化信息效率、可读性、可维护性。**
|
||||||
|
|
||||||
|
### 铁律：禁止用行数作为评价指标
|
||||||
|
|
||||||
|
- 行数少不代表更好，行数多不代表更差
|
||||||
|
- 优化的评判标准是：**单一信息源**（同一信息不在多处维护）、**认知相关性**（当前任务不需要的信息不干扰注意力）、**维护一致性**（改一处不需要同步另一处）
|
||||||
|
- 禁止在优化方案中出现"从 X 行精简到 Y 行"、"减少 Z%"等表述
|
||||||
|
- 一个结构清晰、信息不重复的长文件，比一个砍掉关键信息的短文件更好
|
||||||
|
|
||||||
### 两层架构
|
### 两层架构
|
||||||
|
|
||||||
@@ -285,16 +292,16 @@ function getDatabase() {
|
|||||||
|
|
||||||
## 反模式警告
|
## 反模式警告
|
||||||
|
|
||||||
### ⚠️ 反模式 1：过度精简
|
### ⚠️ 反模式 1：以行数为目标的过度精简
|
||||||
|
|
||||||
**案例**：把 2937 行压缩到 165 行
|
**案例**：为了"减少行数"，移走了代码模式、诊断流程、目录映射
|
||||||
|
|
||||||
**结果**：
|
**结果**：
|
||||||
- 丢失代码模式，每次重新推导
|
- 丢失代码模式，LLM 每次重新推导
|
||||||
- 丢失诊断流程，遇错不知查哪
|
- 丢失诊断流程，遇错不知查哪
|
||||||
- 丢失目录映射，找文件效率低
|
- 丢失目录映射，找文件效率低
|
||||||
|
|
||||||
**正确**：保留所有高频使用的内容，即使行数较多。
|
**正确**：保留所有高频使用的内容。优化的判断标准是信息是否重复维护、是否与当前任务无关，而不是"文件太长"。
|
||||||
|
|
||||||
### ⚠️ 反模式 2：无触发条件的引用
|
### ⚠️ 反模式 2：无触发条件的引用
|
||||||
|
|
||||||
@@ -320,6 +327,14 @@ function getDatabase() {
|
|||||||
|
|
||||||
**正确**：移到 Level 2，保留触发条件。
|
**正确**：移到 Level 2，保留触发条件。
|
||||||
|
|
||||||
|
### ⚠️ 反模式 5：用行数当 KPI
|
||||||
|
|
||||||
|
**案例**：优化方案写"从 2000 行精简到 500 行，减少 75%"
|
||||||
|
|
||||||
|
**问题**：把行数当成功指标，会驱动错误决策——为了凑数字而砍掉有用的信息。
|
||||||
|
|
||||||
|
**正确**：用信息质量评估优化效果——信息是否有重复？维护负担是否降低？LLM 是否能更快找到需要的信息？
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 信息量检验
|
## 信息量检验
|
||||||
@@ -354,7 +369,7 @@ function getDatabase() {
|
|||||||
|------|--------|--------|
|
|------|--------|--------|
|
||||||
| 位置 | `~/.claude/CLAUDE.md` | `项目/CLAUDE.md` |
|
| 位置 | `~/.claude/CLAUDE.md` | `项目/CLAUDE.md` |
|
||||||
| References | `~/.claude/references/` | `docs/references/` |
|
| References | `~/.claude/references/` | `docs/references/` |
|
||||||
| 行数参考 | 100-300 | 300-600 |
|
| 信息范围 | 个人偏好、全局规则 | 项目架构、团队规范 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -4,13 +4,13 @@
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 案例 1：过度精简的失败
|
## 案例 1：以行数为目标的过度精简
|
||||||
|
|
||||||
### 背景
|
### 背景
|
||||||
某项目 CLAUDE.md 原有 2937 行，尝试优化。
|
某项目 CLAUDE.md 内容丰富，包含代码模式、诊断流程、目录映射等。
|
||||||
|
|
||||||
### 错误做法
|
### 错误做法
|
||||||
压缩到 165 行，移走了大部分内容。
|
以"减少行数"为目标，移走了大部分内容，只保留简短描述和指针。
|
||||||
|
|
||||||
### 结果
|
### 结果
|
||||||
- ❌ 丢失代码模式，LLM 每次重新推导
|
- ❌ 丢失代码模式，LLM 每次重新推导
|
||||||
@@ -18,17 +18,17 @@
|
|||||||
- ❌ 丢失目录映射，找文件效率低
|
- ❌ 丢失目录映射，找文件效率低
|
||||||
|
|
||||||
### 正确做法
|
### 正确做法
|
||||||
保留 482 行，关键内容如下：
|
按**信息质量**而非行数判断去留：
|
||||||
|
|
||||||
| 内容 | 保留位置 | 原因 |
|
| 内容 | 保留位置 | 判断依据 |
|
||||||
|------|----------|------|
|
|------|----------|----------|
|
||||||
| 核心命令表 | Level 1 | 高频使用 |
|
| 核心命令表 | Level 1 | 高频使用，不应让 LLM 每次去查 |
|
||||||
| 懒加载代码模式 | Level 1 | 需要直接复制 |
|
| 懒加载代码模式 | Level 1 | 需要直接复制，移走会导致重新推导 |
|
||||||
| ABI 错误诊断 | Level 1 | 完整流程 |
|
| ABI 错误诊断 | Level 1 | 完整症状→原因→修复流程 |
|
||||||
| 详细 SOP | Level 2 | 有触发条件 |
|
| 详细 SOP | Level 2 | 低频、有明确触发条件 |
|
||||||
|
|
||||||
### 教训
|
### 教训
|
||||||
**行数不是目标，效能才是。**
|
**信息效率、可读性、可维护性是标准，行数不是。**
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -143,10 +143,10 @@ LLM 注意力呈 U 型分布：开头和末尾强，中间弱。只放中间会
|
|||||||
## 案例 6：缺少信息记录原则
|
## 案例 6：缺少信息记录原则
|
||||||
|
|
||||||
### 背景
|
### 背景
|
||||||
优化完成后，CLAUDE.md 从 2937 行精简到 524 行，结构清晰。
|
优化完成后，CLAUDE.md 结构清晰，信息分层合理。
|
||||||
|
|
||||||
### 问题
|
### 问题
|
||||||
后续用户继续要求 Claude "把这个记录到 CLAUDE.md"，Claude 没有判断标准，只能照做。一个月后 CLAUDE.md 又膨胀回 1500+ 行。
|
后续用户继续要求 Claude "把这个记录到 CLAUDE.md"，Claude 没有判断标准，只能照做。逐渐出现信息重复维护、低频内容和高频内容混杂的问题。
|
||||||
|
|
||||||
### 错误做法
|
### 错误做法
|
||||||
只优化内容，不添加规则。
|
只优化内容，不添加规则。
|
||||||
@@ -219,3 +219,28 @@ LLM 注意力呈 U 型分布：开头和末尾强，中间弱。只放中间会
|
|||||||
| 边缘情况处理 | | ✅ |
|
| 边缘情况处理 | | ✅ |
|
||||||
| 历史决策记录 | | ✅ |
|
| 历史决策记录 | | ✅ |
|
||||||
| 性能数据 | | ✅ |
|
| 性能数据 | | ✅ |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 案例 7：用行数当 KPI
|
||||||
|
|
||||||
|
### 错误做法
|
||||||
|
优化方案写"当前 2,114 行，目标 ~580 行，约 73% 精简"，用行数和百分比作为成功指标。
|
||||||
|
|
||||||
|
### 问题
|
||||||
|
行数驱动的优化会导致错误决策：
|
||||||
|
- 为了凑数字而砍掉有用的代码模式
|
||||||
|
- 为了"减少百分比"而合并不相关的章节
|
||||||
|
- 把"短"等同于"好"，把"长"等同于"差"
|
||||||
|
|
||||||
|
### 正确做法
|
||||||
|
用信息架构质量作为评估维度：
|
||||||
|
|
||||||
|
| 评估维度 | 问题 |
|
||||||
|
|----------|------|
|
||||||
|
| **单一信息源** | 这段信息是否在别处已经有了？如果是，消除重复 |
|
||||||
|
| **认知相关性** | 这段信息在大多数开发场景下是否需要？如果不是，移到 Level 2 |
|
||||||
|
| **维护一致性** | 改一处是否需要同步另一处？如果是，消除重复 |
|
||||||
|
|
||||||
|
### 教训
|
||||||
|
**行数少不代表更好，行数多不代表更差。真正的标准是信息效率、可读性、可维护性。**
|
||||||
|
|||||||
@@ -0,0 +1,4 @@
|
|||||||
|
Security scan passed
|
||||||
|
Scanned at: 2026-02-09T11:27:20.232525
|
||||||
|
Tool: gitleaks + pattern-based validation
|
||||||
|
Content hash: ad704c37736e699057f51e289f718b1252d8cff6a1e953f0411ef24400a413da
|
||||||
221
windows-remote-desktop-connection-doctor/SKILL.md
Normal file
221
windows-remote-desktop-connection-doctor/SKILL.md
Normal file
@@ -0,0 +1,221 @@
|
|||||||
|
---
|
||||||
|
name: windows-remote-desktop-connection-doctor
|
||||||
|
description: Diagnose Windows App (Microsoft Remote Desktop / Azure Virtual Desktop / W365) connection quality issues on macOS. Analyze transport protocol selection (UDP Shortpath vs WebSocket), detect VPN/proxy interference with STUN/TURN negotiation, and parse Windows App logs for Shortpath failures. This skill should be used when VDI connections are slow, when transport shows WebSocket instead of UDP, when RDP Shortpath fails to establish, or when RTT is unexpectedly high.
|
||||||
|
allowed-tools: Read, Grep, Bash
|
||||||
|
---
|
||||||
|
|
||||||
|
# Windows Remote Desktop Connection Doctor
|
||||||
|
|
||||||
|
Diagnose and fix Windows App (AVD/WVD/W365) connection quality issues on macOS, with focus on transport protocol optimization.
|
||||||
|
|
||||||
|
## Background
|
||||||
|
|
||||||
|
Azure Virtual Desktop transport priority: **UDP Shortpath > TCP > WebSocket**. UDP Shortpath provides the best experience (lowest latency, supports UDP Multicast). When it fails, the client falls back to WebSocket over TCP 443 through the gateway, adding significant latency overhead.
|
||||||
|
|
||||||
|
## Diagnostic Workflow
|
||||||
|
|
||||||
|
### Step 1: Collect Connection Info
|
||||||
|
|
||||||
|
Ask the user to provide the Connection Info from Windows App (click the signal icon in the toolbar). Key fields to extract:
|
||||||
|
|
||||||
|
| Field | What It Tells |
|
||||||
|
|-------|--------------|
|
||||||
|
| Transport Protocol | Current transport: `UDP`, `UDP Multicast`, `WebSocket`, or `TCP` |
|
||||||
|
| Round-Trip Time (RTT) | End-to-end latency in ms |
|
||||||
|
| Available Bandwidth | Current bandwidth in Mbps |
|
||||||
|
| Gateway | The AVD gateway hostname and port |
|
||||||
|
| Service Region | Azure region code (e.g., SEAS = South East Asia) |
|
||||||
|
|
||||||
|
If Transport Protocol is `UDP` or `UDP Multicast`, the connection is optimal — no further diagnosis needed.
|
||||||
|
|
||||||
|
If Transport Protocol is `WebSocket` or `TCP`, proceed to Step 2.
|
||||||
|
|
||||||
|
### Step 2: Collect Network Evidence
|
||||||
|
|
||||||
|
Gather evidence in parallel — do NOT make assumptions. Run the following checks simultaneously:
|
||||||
|
|
||||||
|
#### 2A: Network Interfaces and Routing
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ifconfig | grep -E "^[a-z]|inet |utun"
|
||||||
|
netstat -rn | head -40
|
||||||
|
scutil --proxy
|
||||||
|
```
|
||||||
|
|
||||||
|
Look for:
|
||||||
|
- **utun interfaces**: Identify VPN/proxy TUN tunnels (ShadowRocket, Clash, Tailscale)
|
||||||
|
- **Default route priority**: Which interface handles default traffic
|
||||||
|
- **Split routing**: `0/1 + 128.0/1 → utun` pattern means a VPN captures all traffic
|
||||||
|
- **System proxy**: HTTP/HTTPS proxy enabled on localhost ports
|
||||||
|
|
||||||
|
#### 2B: RDP Client Process and Connections
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Find the Windows App process (NOT "msrdc" — the new client uses "Windows" as process name)
|
||||||
|
ps aux | grep -i -E 'msrdc|Windows' | grep -v grep
|
||||||
|
# Check its network connections
|
||||||
|
lsof -i -n -P 2>/dev/null | grep -i "Windows" | head -20
|
||||||
|
# Check for UDP connections
|
||||||
|
lsof -i UDP -n -P 2>/dev/null | head -30
|
||||||
|
```
|
||||||
|
|
||||||
|
Key evidence to look for:
|
||||||
|
- **Source IP `198.18.0.x`**: Traffic is being routed through ShadowRocket/proxy TUN tunnel
|
||||||
|
- **No UDP connections from Windows process**: Shortpath not established
|
||||||
|
- **Only TCP 443**: Fallback to gateway WebSocket transport
|
||||||
|
|
||||||
|
#### 2C: VPN/Proxy State
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Environment proxy variables
|
||||||
|
env | grep -i proxy
|
||||||
|
# System proxy via scutil
|
||||||
|
scutil --proxy
|
||||||
|
# ShadowRocket config API (if accessible on local network)
|
||||||
|
NO_PROXY="<local-ip>" curl -s --connect-timeout 5 "http://<local-ip>:8080/api/read"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2D: Tailscale State (if running)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
tailscale status
|
||||||
|
tailscale netcheck
|
||||||
|
```
|
||||||
|
|
||||||
|
The `netcheck` output reveals NAT type (`MappingVariesByDestIP`), UDP support, and public IP — valuable even when Tailscale is not the problem.
|
||||||
|
|
||||||
|
### Step 3: Analyze Windows App Logs
|
||||||
|
|
||||||
|
This is the most critical step. Windows App logs contain transport negotiation details that no network-level test can reveal.
|
||||||
|
|
||||||
|
**Log location on macOS:**
|
||||||
|
```
|
||||||
|
~/Library/Containers/com.microsoft.rdc.macos/Data/Library/Logs/Windows App/
|
||||||
|
```
|
||||||
|
|
||||||
|
Files are named: `com.microsoft.rdc.macos_v<version>_<date>_<time>.log`
|
||||||
|
|
||||||
|
See [references/windows_app_log_analysis.md](references/windows_app_log_analysis.md) for detailed log parsing guidance.
|
||||||
|
|
||||||
|
#### Quick Log Search
|
||||||
|
|
||||||
|
```bash
|
||||||
|
LOG_DIR=~/Library/Containers/com.microsoft.rdc.macos/Data/Library/Logs/Windows\ App
|
||||||
|
# Find the most recent log
|
||||||
|
LATEST_LOG=$(ls -t "$LOG_DIR"/*.log 2>/dev/null | head -1)
|
||||||
|
|
||||||
|
# Search for transport-critical entries (filter out noise)
|
||||||
|
grep -i -E "STUN|TURN|VPN|Routed|Shortpath|FetchClient|clientoption|GATEWAY.*ERR|Certificate.*valid|InternetConnectivity|Passed URL" "$LATEST_LOG" | grep -v "BasicStateManagement\|DynVC\|dynvcstat\|asynctransport"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Key Log Patterns
|
||||||
|
|
||||||
|
| Log Pattern | Meaning |
|
||||||
|
|-------------|---------|
|
||||||
|
| `Passed: InternetConnectivity` | Health check completed successfully |
|
||||||
|
| `TCP/IP Traffic Routed Through VPN: No/Yes` | Client detected VPN routing for TCP |
|
||||||
|
| `STUN/TURN Traffic Routed Through VPN: Yes` | Client detected VPN routing for STUN/TURN |
|
||||||
|
| `Passed URL: https://...wvd.microsoft.com/ Response Time: Nms` | Gateway reachability confirmed |
|
||||||
|
| `FetchClientOptions exception: Request timed out` | **Critical**: Client cannot get transport options from gateway |
|
||||||
|
| `Certificate validation failed` | TLS interception or DNS poisoning detected |
|
||||||
|
| `OnRDWebRTCRedirectorRpc rtcSession not handled` | WebRTC session setup not handled by client |
|
||||||
|
|
||||||
|
#### Compare Working vs Broken Logs
|
||||||
|
|
||||||
|
When possible, compare a log from when the connection worked (UDP) with the current log:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Compare startup health check blocks
|
||||||
|
for f in "$LOG_DIR"/*.log; do
|
||||||
|
echo "=== $(basename "$f") ==="
|
||||||
|
grep -E "InternetConnectivity|Routed Through VPN|Passed URL|FetchClient" "$f" | head -10
|
||||||
|
echo ""
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
A working log will contain the full health check block (InternetConnectivity, VPN routing detection, gateway URL tests). A broken log may show these entries missing entirely, or show certificate/timeout errors instead.
|
||||||
|
|
||||||
|
### Step 4: Determine Root Cause
|
||||||
|
|
||||||
|
Based on collected evidence, identify the root cause category:
|
||||||
|
|
||||||
|
#### Category A: VPN/Proxy Interference
|
||||||
|
|
||||||
|
**Evidence**: Windows App source IP is `198.18.0.x`, STUN/TURN routed through VPN, no UDP connections.
|
||||||
|
|
||||||
|
**Fix**: Add DIRECT rules for AVD traffic in the proxy tool:
|
||||||
|
```
|
||||||
|
DOMAIN-SUFFIX,wvd.microsoft.com,DIRECT
|
||||||
|
DOMAIN-SUFFIX,microsoft.com,DIRECT
|
||||||
|
IP-CIDR,13.104.0.0/14,DIRECT
|
||||||
|
```
|
||||||
|
|
||||||
|
**Verify**: Temporarily disable VPN/proxy, reconnect VDI, check if transport changes to UDP.
|
||||||
|
|
||||||
|
#### Category B: ISP/Network UDP Restriction
|
||||||
|
|
||||||
|
**Evidence**: Even with all VPNs off, still WebSocket. No UDP connections. `FetchClientOptions` timeout.
|
||||||
|
|
||||||
|
**Verify**:
|
||||||
|
```bash
|
||||||
|
# Test STUN connectivity to a known server
|
||||||
|
python3 -c "
|
||||||
|
import socket, struct, os
|
||||||
|
header = struct.pack('!HHI', 0x0001, 0, 0x2112A442) + os.urandom(12)
|
||||||
|
for srv in [('stun.l.google.com', 19302), ('stun1.l.google.com', 19302)]:
|
||||||
|
try:
|
||||||
|
s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
|
||||||
|
s.settimeout(3)
|
||||||
|
s.sendto(header, srv)
|
||||||
|
data, addr = s.recvfrom(1024)
|
||||||
|
print(f'STUN from {srv[0]}: OK')
|
||||||
|
s.close(); break
|
||||||
|
except: print(f'STUN from {srv[0]}: FAILED'); s.close()
|
||||||
|
"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fix options**:
|
||||||
|
- Try mobile hotspot (isolate home network from ISP)
|
||||||
|
- Check router NAT type (Full Cone NAT preferred)
|
||||||
|
- Enable UPnP on router
|
||||||
|
- Try IPv6 if available
|
||||||
|
- Contact ISP about UDP restrictions
|
||||||
|
|
||||||
|
#### Category C: Client Health Check Failure
|
||||||
|
|
||||||
|
**Evidence**: Log shows certificate validation errors at startup, health check block (InternetConnectivity, STUN/TURN detection) missing from log, `FetchClientOptions` timeout.
|
||||||
|
|
||||||
|
This means the client cannot complete its diagnostic/capability discovery, preventing Shortpath negotiation.
|
||||||
|
|
||||||
|
**Possible causes**:
|
||||||
|
- ISP HTTPS interception/MITM (especially in China)
|
||||||
|
- DNS poisoning returning incorrect IPs for Microsoft diagnostic endpoints
|
||||||
|
- Firewall blocking Microsoft telemetry endpoints
|
||||||
|
|
||||||
|
**Fix options**:
|
||||||
|
- Change DNS to 8.8.8.8 or 1.1.1.1 (bypass ISP DNS)
|
||||||
|
- Route Microsoft traffic through a clean proxy
|
||||||
|
- Check if ISP injects certificates
|
||||||
|
|
||||||
|
#### Category D: Server-Side Shortpath Not Enabled
|
||||||
|
|
||||||
|
**Evidence**: Log shows no STUN/TURN or Shortpath related entries at all (not even detection), but health checks pass and no errors.
|
||||||
|
|
||||||
|
This means the AVD host pool does not have RDP Shortpath enabled. This requires admin action on the Azure portal.
|
||||||
|
|
||||||
|
### Step 5: Verify Fix
|
||||||
|
|
||||||
|
After applying a fix, reconnect the VDI session and verify:
|
||||||
|
|
||||||
|
1. Check Connection Info — Transport Protocol should show `UDP` or `UDP Multicast`
|
||||||
|
2. RTT should drop significantly (e.g., from 165ms to 40-60ms)
|
||||||
|
3. Verify with lsof:
|
||||||
|
```bash
|
||||||
|
lsof -i UDP -n -P 2>/dev/null | grep -i "Windows"
|
||||||
|
# Should show UDP connections if Shortpath is active
|
||||||
|
```
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- [references/windows_app_log_analysis.md](references/windows_app_log_analysis.md) — Detailed log parsing patterns, error signatures, and comparison methodology
|
||||||
|
- [references/avd_transport_protocols.md](references/avd_transport_protocols.md) — How AVD transport selection works, STUN/TURN/ICE overview, Shortpath architecture
|
||||||
@@ -0,0 +1,150 @@
|
|||||||
|
# AVD Transport Protocol Reference
|
||||||
|
|
||||||
|
How Azure Virtual Desktop selects transport protocols and how RDP Shortpath works.
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
|
- Transport protocol hierarchy
|
||||||
|
- RDP Shortpath architecture
|
||||||
|
- STUN/TURN/ICE overview
|
||||||
|
- Why Shortpath fails
|
||||||
|
- Network requirements
|
||||||
|
- Common interference patterns
|
||||||
|
|
||||||
|
## Transport Protocol Hierarchy
|
||||||
|
|
||||||
|
Azure Virtual Desktop clients attempt transports in this order:
|
||||||
|
|
||||||
|
1. **UDP Shortpath** (best) — Direct UDP connection via ICE/STUN/TURN
|
||||||
|
2. **TCP** — Direct TCP connection to session host
|
||||||
|
3. **WebSocket** — WebSocket over TCP 443 through the AVD gateway (worst)
|
||||||
|
|
||||||
|
The client always establishes a WebSocket connection to the gateway first (for control plane). Then it attempts to upgrade to UDP Shortpath. If Shortpath negotiation fails, the session data stays on the WebSocket channel.
|
||||||
|
|
||||||
|
## RDP Shortpath Architecture
|
||||||
|
|
||||||
|
### For Public Networks (most common for remote workers)
|
||||||
|
|
||||||
|
RDP Shortpath for public networks uses ICE, STUN, and TURN protocols to establish a direct UDP connection between client and session host:
|
||||||
|
|
||||||
|
1. Client connects to AVD gateway via WebSocket (TCP 443)
|
||||||
|
2. Through this control channel, ICE negotiation begins
|
||||||
|
3. Client and server gather ICE candidates using STUN
|
||||||
|
4. They exchange candidates and attempt connectivity checks
|
||||||
|
5. If a direct UDP path exists, Shortpath is established
|
||||||
|
6. If direct fails but TURN relay is available, traffic relays through TURN
|
||||||
|
7. If all UDP attempts fail, session stays on WebSocket
|
||||||
|
|
||||||
|
### For Managed Networks (corporate LAN)
|
||||||
|
|
||||||
|
When client and session host are on the same network, Shortpath uses direct UDP without STUN/TURN. This is the simplest mode and rarely fails.
|
||||||
|
|
||||||
|
## STUN/TURN/ICE Overview
|
||||||
|
|
||||||
|
### STUN (Session Traversal Utilities for NAT)
|
||||||
|
|
||||||
|
STUN discovers the client's public IP and port as seen from outside the NAT. The client sends a STUN Binding Request to a STUN server, which replies with the client's observed address.
|
||||||
|
|
||||||
|
**Key port**: UDP 3478
|
||||||
|
|
||||||
|
**NAT types that affect STUN:**
|
||||||
|
- **Endpoint-Independent Mapping (EIM)**: Best — same public port regardless of destination. STUN works reliably.
|
||||||
|
- **Address-Dependent Mapping**: Moderate — different public port per destination IP. STUN may work with help from TURN.
|
||||||
|
- **Address-and-Port-Dependent (Symmetric NAT)**: Worst — different public port per destination IP:port. STUN alone often fails; requires TURN relay.
|
||||||
|
|
||||||
|
### TURN (Traversal Using Relays around NAT)
|
||||||
|
|
||||||
|
When direct UDP fails, TURN provides a relay server. Traffic goes: Client → TURN server → Session Host. Adds latency but still uses UDP.
|
||||||
|
|
||||||
|
**Key ports**: UDP 3478, TCP 443 (fallback)
|
||||||
|
|
||||||
|
### ICE (Interactive Connectivity Establishment)
|
||||||
|
|
||||||
|
ICE orchestrates STUN and TURN to find the best available path. It gathers candidates (direct, server-reflexive via STUN, relayed via TURN), exchanges them with the peer, and tests connectivity.
|
||||||
|
|
||||||
|
## Why Shortpath Fails
|
||||||
|
|
||||||
|
### 1. VPN/Proxy TUN Hijacking
|
||||||
|
|
||||||
|
When a VPN tool (ShadowRocket, Clash, Surge) runs in TUN mode, it captures all outbound traffic including STUN/TURN UDP packets. The proxy typically cannot relay raw UDP correctly, causing ICE negotiation to fail.
|
||||||
|
|
||||||
|
**Detection**: Windows App's source IP in `lsof` shows `198.18.0.x` (ShadowRocket) or another VPN virtual IP instead of the real local IP.
|
||||||
|
|
||||||
|
### 2. ISP UDP Restrictions
|
||||||
|
|
||||||
|
Some ISPs (particularly in China, especially outside tier-1 cities) throttle or block UDP to certain ports or destinations. This prevents STUN binding requests from reaching Azure's STUN servers.
|
||||||
|
|
||||||
|
**Detection**: STUN tests fail even with all VPNs disabled.
|
||||||
|
|
||||||
|
### 3. Symmetric NAT (Address-and-Port-Dependent)
|
||||||
|
|
||||||
|
If the router implements symmetric NAT, each outbound UDP flow gets a different public port. STUN discovers one port, but when the actual Shortpath connection uses a different destination, the NAT assigns a different port, and the peer's packets go to the wrong port.
|
||||||
|
|
||||||
|
**Detection**: Tailscale `netcheck` shows `MappingVariesByDestIP: true`.
|
||||||
|
|
||||||
|
### 4. FetchClientOptions Timeout
|
||||||
|
|
||||||
|
The client needs to fetch transport capabilities from the gateway. If this request times out (network issues, DNS problems, TLS interception), the client never learns about Shortpath availability.
|
||||||
|
|
||||||
|
**Detection**: Log entry `CWVDTransport::FetchClientOptions exception: Request timed out`.
|
||||||
|
|
||||||
|
### 5. Health Check Failure
|
||||||
|
|
||||||
|
Certificate validation errors at app startup prevent the diagnostic subsystem from completing, which can cascade into transport capability discovery failures.
|
||||||
|
|
||||||
|
**Detection**: `Failed to validate X509CertificateChain` at the start of the log, followed by absence of the health check block.
|
||||||
|
|
||||||
|
### 6. Server-Side Not Enabled
|
||||||
|
|
||||||
|
RDP Shortpath must be enabled on the AVD host pool by an administrator. If not enabled, the server never offers Shortpath candidates.
|
||||||
|
|
||||||
|
**Detection**: No STUN/TURN/Shortpath entries at all in logs, even though health checks pass.
|
||||||
|
|
||||||
|
## Network Requirements for Shortpath
|
||||||
|
|
||||||
|
### Ports
|
||||||
|
|
||||||
|
| Protocol | Port | Purpose |
|
||||||
|
|----------|------|---------|
|
||||||
|
| UDP | 3478 | STUN Binding Requests |
|
||||||
|
| UDP | 1024-65535 (dynamic) | Shortpath data channel |
|
||||||
|
| TCP | 443 | Gateway WebSocket (always needed) |
|
||||||
|
|
||||||
|
### DNS
|
||||||
|
|
||||||
|
The client must resolve these domains correctly:
|
||||||
|
- `*.wvd.microsoft.com` — AVD gateway
|
||||||
|
- `rdweb.wvd.microsoft.com` — AVD web client
|
||||||
|
- STUN/TURN server addresses (provided by the gateway during ICE)
|
||||||
|
|
||||||
|
DNS poisoning (returning fake IPs) prevents proper transport negotiation.
|
||||||
|
|
||||||
|
### TLS
|
||||||
|
|
||||||
|
The client validates TLS certificates for Microsoft endpoints. If the certificate chain is modified (ISP proxy, corporate MITM, DNS poisoning), the health check fails and transport negotiation may be impaired.
|
||||||
|
|
||||||
|
## Common Interference Patterns
|
||||||
|
|
||||||
|
### Pattern: ShadowRocket TUN Mode
|
||||||
|
|
||||||
|
**Mechanism**: Creates utun interface with IP 198.18.0.1, captures all public traffic via `0/1 + 128.0/1` split routing, DNS hijacked to 198.18.0.2.
|
||||||
|
|
||||||
|
**Effect on RDP**: All AVD traffic goes through proxy tunnel. STUN/TURN fails because proxy cannot relay raw UDP. DNS returns fake IPs (198.18.0.x).
|
||||||
|
|
||||||
|
**Fix**: Add DIRECT rules for Microsoft/Azure domains and IPs.
|
||||||
|
|
||||||
|
### Pattern: Tailscale with Exit Node
|
||||||
|
|
||||||
|
**Mechanism**: When exit node is enabled, all traffic routes through the Tailscale tunnel.
|
||||||
|
|
||||||
|
**Effect on RDP**: Similar to VPN hijacking — UDP packets go through WireGuard tunnel to exit node, then to Azure. Adds latency and may break STUN.
|
||||||
|
|
||||||
|
**Fix**: Disable exit node, or add route exceptions for Azure IPs.
|
||||||
|
|
||||||
|
### Pattern: Chinese ISP UDP Throttling
|
||||||
|
|
||||||
|
**Mechanism**: Some Chinese ISPs, particularly in non-tier-1 cities, apply QoS policies that throttle or drop UDP packets to foreign destinations.
|
||||||
|
|
||||||
|
**Effect on RDP**: STUN binding requests time out. Even with perfect client-side configuration, Shortpath cannot establish.
|
||||||
|
|
||||||
|
**Fix**: Try mobile hotspot (different ISP/carrier), use a proxy with good UDP support to Azure's region, or accept WebSocket with optimization (change DNS to reduce resolution latency).
|
||||||
@@ -0,0 +1,207 @@
|
|||||||
|
# Windows App Log Analysis Guide
|
||||||
|
|
||||||
|
Detailed patterns for parsing Windows App (Microsoft Remote Desktop) diagnostic logs on macOS.
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
|
- Log file locations
|
||||||
|
- Log file naming and rotation
|
||||||
|
- Startup health check block
|
||||||
|
- Transport negotiation entries
|
||||||
|
- Error signatures and their meaning
|
||||||
|
- Comparing working vs broken sessions
|
||||||
|
- Filtering noise from logs
|
||||||
|
|
||||||
|
## Log File Locations
|
||||||
|
|
||||||
|
### macOS
|
||||||
|
|
||||||
|
```
|
||||||
|
~/Library/Containers/com.microsoft.rdc.macos/Data/Library/Logs/Windows App/
|
||||||
|
```
|
||||||
|
|
||||||
|
Files follow the pattern:
|
||||||
|
```
|
||||||
|
com.microsoft.rdc.macos_v<version>_<YYYY-MM-DD>_<HH-mm-ss>.log
|
||||||
|
```
|
||||||
|
|
||||||
|
A new log file is created each day or when the app restarts. Multiple files may exist — sort by modification time to find the most recent:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ls -lt ~/Library/Containers/com.microsoft.rdc.macos/Data/Library/Logs/Windows\ App/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Startup Health Check Block
|
||||||
|
|
||||||
|
When the Windows App launches, it runs a health check sequence. A healthy startup produces entries in this order:
|
||||||
|
|
||||||
|
```
|
||||||
|
Passed: InternetConnectivity
|
||||||
|
0: 1
|
||||||
|
4: 3
|
||||||
|
AvcDecodingCheck: 0
|
||||||
|
HardwarePresenterCheck: 0
|
||||||
|
AvcHwDecodingCheck: 1
|
||||||
|
4: 4
|
||||||
|
TCP/IP Traffic Routed Through VPN: No
|
||||||
|
STUN/TURN Traffic Routed Through VPN: Yes
|
||||||
|
```
|
||||||
|
|
||||||
|
Followed by gateway reachability tests:
|
||||||
|
|
||||||
|
```
|
||||||
|
Passed URL: https://afdfp-rdgateway-r1.wvd.microsoft.com/ Attempts Made: 1 Used Ipv4: 1 HTTP Status Code: 200 Response Time: 480
|
||||||
|
Passed URL: https://rdweb.wvd.microsoft.com/ Attempts Made: 1 Used Ipv4: 1 HTTP Status Code: 200 Response Time: 613
|
||||||
|
```
|
||||||
|
|
||||||
|
### What Each Entry Means
|
||||||
|
|
||||||
|
| Entry | Description |
|
||||||
|
|-------|-------------|
|
||||||
|
| `Passed: InternetConnectivity` | General internet reachability confirmed |
|
||||||
|
| `AvcDecodingCheck` / `AvcHwDecodingCheck` | Hardware video decoding capability (0=unavailable, 1=available) |
|
||||||
|
| `HardwarePresenterCheck` | Hardware presentation capability |
|
||||||
|
| `TCP/IP Traffic Routed Through VPN` | Whether the client detects a VPN intercepting TCP traffic |
|
||||||
|
| `STUN/TURN Traffic Routed Through VPN` | Whether the client detects a VPN intercepting STUN/TURN (UDP) traffic |
|
||||||
|
| `Passed URL: ...` | Gateway reachability test with response time in ms |
|
||||||
|
|
||||||
|
### When Health Check Fails
|
||||||
|
|
||||||
|
If the startup health check block is **completely absent** from a log, the diagnostic subsystem itself failed. Check for certificate validation errors near the log start:
|
||||||
|
|
||||||
|
```
|
||||||
|
DIAGNOSTICS(ERR): Failed to validate X509CertificateChain, certificate is not trusted.
|
||||||
|
BASIX_DCT(ERR): OSSLClosingException thrown, msg=Certificate validation failed
|
||||||
|
```
|
||||||
|
|
||||||
|
This indicates TLS interception (common with ISP HTTPS proxies in China) or DNS poisoning affecting Microsoft diagnostic endpoints.
|
||||||
|
|
||||||
|
## Transport Negotiation Entries
|
||||||
|
|
||||||
|
### FetchClientOptions
|
||||||
|
|
||||||
|
This is the critical function that retrieves transport capabilities from the gateway:
|
||||||
|
|
||||||
|
```
|
||||||
|
GATEWAY(ERR): CWVDTransport::FetchClientOptions exception when attempting to fetch client options: Request timed out
|
||||||
|
wvd_transport.cpp(521): FetchClientOptions()
|
||||||
|
```
|
||||||
|
|
||||||
|
When this times out, the client cannot discover available transport options (including Shortpath). The connection will fall back to WebSocket.
|
||||||
|
|
||||||
|
### ClientOptions Controller
|
||||||
|
|
||||||
|
A separate mechanism that refreshes client properties:
|
||||||
|
|
||||||
|
```
|
||||||
|
ClientOptions_Controller(ERR): ClientOptionsController RefreshProperties attempt 1 failed: Request timed out. Retrying in 30s...
|
||||||
|
client_options.cpp(214): RefreshProperties()
|
||||||
|
```
|
||||||
|
|
||||||
|
This is less critical than `FetchClientOptions` but indicates general connectivity issues to Microsoft configuration services.
|
||||||
|
|
||||||
|
### WebRTC Session
|
||||||
|
|
||||||
|
```
|
||||||
|
A3CORE(ERR): OnRDWebRTCRedirectorRpc rtcSession not handled
|
||||||
|
```
|
||||||
|
|
||||||
|
This appears when the server sends a WebRTC session setup but the client does not process it. This may indicate incomplete Shortpath support in the client version, or a session setup that arrives after fallback.
|
||||||
|
|
||||||
|
Note: `OnRDWebRTCRedirectorRpc notifyClipRectChanged not handled` is a benign clipboard-related message, not transport-related.
|
||||||
|
|
||||||
|
## Error Signatures
|
||||||
|
|
||||||
|
### Certificate Validation Failure
|
||||||
|
|
||||||
|
```
|
||||||
|
DIAGNOSTICS(ERR): Failed to validate X509CertificateChain, certificate is not trusted.
|
||||||
|
A3CORE(ERR): ITrustDelegateAdaptorPtr is empty.
|
||||||
|
BASIX_DCT(ERR): OSSLClosingException thrown, msg=Certificate validation failed, ossl error string="error:00000000:lib(0)::reason(0)", closing error code=1002
|
||||||
|
```
|
||||||
|
|
||||||
|
**Cause**: TLS certificate for Microsoft diagnostic endpoints is not trusted. Common with ISP HTTPS proxies/MITM, DNS poisoning, or corporate proxy servers.
|
||||||
|
|
||||||
|
**Impact**: Prevents the diagnostic health check from completing, which may block transport capability discovery.
|
||||||
|
|
||||||
|
### Channel Write Failures
|
||||||
|
|
||||||
|
```
|
||||||
|
"-legacy-"(ERR): Channel::StartWrite failed
|
||||||
|
```
|
||||||
|
|
||||||
|
Multiple consecutive `StartWrite failed` errors indicate a connection disruption — the WebSocket or TCP connection to the gateway was interrupted. This is typically followed by a reconnection attempt.
|
||||||
|
|
||||||
|
### Diagnostics Flush Errors
|
||||||
|
|
||||||
|
```
|
||||||
|
DIAGNOSTICS(ERR): FlushTracesInternal() is called before BeginUpload(). we don't have a claims token yet
|
||||||
|
```
|
||||||
|
|
||||||
|
This is a benign telemetry error — the diagnostics system tried to upload traces before authentication completed. Does NOT affect connection quality.
|
||||||
|
|
||||||
|
## Comparing Working vs Broken Sessions
|
||||||
|
|
||||||
|
The most effective diagnostic approach: compare a log from when the connection was healthy (UDP transport) with the current broken log.
|
||||||
|
|
||||||
|
### Quick Comparison Script
|
||||||
|
|
||||||
|
```bash
|
||||||
|
LOG_DIR=~/Library/Containers/com.microsoft.rdc.macos/Data/Library/Logs/Windows\ App
|
||||||
|
|
||||||
|
echo "=== Health check and transport entries per log file ==="
|
||||||
|
for f in "$LOG_DIR"/*.log; do
|
||||||
|
echo ""
|
||||||
|
echo "--- $(basename "$f") ---"
|
||||||
|
grep -c "InternetConnectivity" "$f" 2>/dev/null | xargs -I{} echo " InternetConnectivity checks: {}"
|
||||||
|
grep "Routed Through VPN" "$f" 2>/dev/null | head -2 | sed 's/^/ /'
|
||||||
|
grep "Passed URL:" "$f" 2>/dev/null | head -2 | sed 's/^/ /'
|
||||||
|
grep "FetchClientOptions" "$f" 2>/dev/null | head -1 | sed 's/^/ /'
|
||||||
|
grep "Certificate validation failed" "$f" 2>/dev/null | head -1 | sed 's/^/ /'
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
### What to Compare
|
||||||
|
|
||||||
|
| Aspect | Working (UDP) | Broken (WebSocket) |
|
||||||
|
|--------|--------------|-------------------|
|
||||||
|
| Health check block | Present, complete | Missing or incomplete |
|
||||||
|
| `TCP/IP Routed Through VPN` | Present | Missing |
|
||||||
|
| `STUN/TURN Routed Through VPN` | Present | Missing |
|
||||||
|
| `Passed URL:` | Present with response times | Missing |
|
||||||
|
| `FetchClientOptions` | No error | Timeout error |
|
||||||
|
| Certificate errors | None at startup | Present at startup |
|
||||||
|
|
||||||
|
## Filtering Noise
|
||||||
|
|
||||||
|
Windows App logs contain many repetitive entries that obscure useful information. Filter these out:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grep -v -E "BasicStateManagement|DynVC.*SendChannelClose|dynvcstat.*SerializeToJson|asynctransport\.cpp|FlushTracesInternal"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Common Noise Patterns
|
||||||
|
|
||||||
|
| Pattern | What It Is | Safe to Filter |
|
||||||
|
|---------|-----------|----------------|
|
||||||
|
| `~BasicStateManagement()` | Transport object destructor | Yes |
|
||||||
|
| `SendChannelClose()` | Dynamic virtual channel cleanup | Yes |
|
||||||
|
| `SerializeToJson()` | Channel stats serialization | Yes |
|
||||||
|
| `FlushTracesInternal()` | Telemetry upload attempt | Yes |
|
||||||
|
| `Stateful object ... destructed while in state Opened` | Abrupt connection close | Context-dependent |
|
||||||
|
|
||||||
|
The last pattern (`Stateful object destructed in Opened state`) may be significant during active troubleshooting — it indicates connections being torn down unexpectedly. Keep it when investigating disconnection events.
|
||||||
|
|
||||||
|
## Activity ID Tracking
|
||||||
|
|
||||||
|
Each RDP session gets a unique activity ID (GUID). Track a specific session through the log:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Find activity IDs from connection events
|
||||||
|
grep -E "\{[0-9a-f]{8}-" "$LOG_FILE" | grep -v "00000000-0000-0000-0000-000000000000" | head -5
|
||||||
|
|
||||||
|
# Trace a specific session
|
||||||
|
grep "<activity-id>" "$LOG_FILE" | grep -v "BasicStateManagement\|FlushTraces"
|
||||||
|
```
|
||||||
|
|
||||||
|
The null GUID `{00000000-0000-0000-0000-000000000000}` indicates background/system events, not specific RDP sessions.
|
||||||
Reference in New Issue
Block a user