diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b91ee2a..02293d2 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -5,8 +5,8 @@ "email": "daymadev89@gmail.com" }, "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", - "version": "1.31.0", + "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.32.0", "homepage": "https://github.com/daymade/claude-code-skills" }, "plugins": [ @@ -753,6 +753,33 @@ "skills": [ "./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" + ] } ] } diff --git a/CHANGELOG.md b/CHANGELOG.md index e34d2f6..c42edf0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - 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 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index efd03c3..5888483 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 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. @@ -134,7 +134,7 @@ Skills for public distribution must NOT contain: ## Marketplace Configuration 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 - 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`) - Tracks the marketplace catalog as a whole - - Current: v1.31.0 + - Current: v1.32.0 - Bump when: Adding/removing skills, major marketplace restructuring - 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 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 +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. diff --git a/README.md b/README.md index a104cbe..0897db5 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,15 @@ [![简体中文](https://img.shields.io/badge/语言-简体中文-red)](./README.zh-CN.md) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![Skills](https://img.shields.io/badge/skills-36-blue.svg)](https://github.com/daymade/claude-code-skills) -[![Version](https://img.shields.io/badge/version-1.31.0-green.svg)](https://github.com/daymade/claude-code-skills) +[![Skills](https://img.shields.io/badge/skills-37-blue.svg)](https://github.com/daymade/claude-code-skills) +[![Version](https://img.shields.io/badge/version-1.32.0-green.svg)](https://github.com/daymade/claude-code-skills) [![Claude Code](https://img.shields.io/badge/Claude%20Code-2.0.13+-purple.svg)](https://claude.com/code) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md) [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/daymade/claude-code-skills/graphs/commit-activity) -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 @@ -222,6 +222,9 @@ claude plugin install skill-reviewer@daymade-skills # GitHub contribution strategy 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! @@ -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 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 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 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 - **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 +- **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 diff --git a/README.zh-CN.md b/README.zh-CN.md index 27c4ff4..84e8fac 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -6,15 +6,15 @@ [![简体中文](https://img.shields.io/badge/语言-简体中文-red)](./README.zh-CN.md) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![Skills](https://img.shields.io/badge/skills-36-blue.svg)](https://github.com/daymade/claude-code-skills) -[![Version](https://img.shields.io/badge/version-1.31.0-green.svg)](https://github.com/daymade/claude-code-skills) +[![Skills](https://img.shields.io/badge/skills-37-blue.svg)](https://github.com/daymade/claude-code-skills) +[![Version](https://img.shields.io/badge/version-1.32.0-green.svg)](https://github.com/daymade/claude-code-skills) [![Claude Code](https://img.shields.io/badge/Claude%20Code-2.0.13+-purple.svg)](https://claude.com/code) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md) [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/daymade/claude-code-skills/graphs/commit-activity) -专业的 Claude Code 技能市场，提供 36 个生产就绪的技能，用于增强开发工作流。 +专业的 Claude Code 技能市场，提供 37 个生产就绪的技能，用于增强开发工作流。 ## 📑 目录 @@ -225,6 +225,9 @@ claude plugin install skill-reviewer@daymade-skills # GitHub 贡献策略 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/)。 @@ -1665,6 +1707,9 @@ claude plugin install tunnel-doctor@daymade-skills ### 网络与 VPN 故障排查 使用 **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 感到困惑的人。 @@ -1712,6 +1757,7 @@ claude plugin install tunnel-doctor@daymade-skills - **claude-skills-troubleshooting**：参见 `claude-skills-troubleshooting/SKILL.md` 了解插件故障排除工作流程和架构 - **fact-checker**：参见 `fact-checker/SKILL.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` 了解传输协议详情 ## 🛠️ 系统要求 diff --git a/claude-md-progressive-disclosurer/SKILL.md b/claude-md-progressive-disclosurer/SKILL.md index fb530d2..db46b89 100644 --- a/claude-md-progressive-disclosurer/SKILL.md +++ b/claude-md-progressive-disclosurer/SKILL.md @@ -2,8 +2,8 @@ name: claude-md-progressive-disclosurer description: | Optimize CLAUDE.md files using progressive disclosure. - Goal: Maximize LLM working efficiency, NOT minimize line count. - Use when: User wants to optimize CLAUDE.md, complains about context issues, or file exceeds 500 lines. + Goal: Maximize information efficiency, readability, and maintainability. + Use when: User wants to optimize CLAUDE.md, information is duplicated across files, or LLM repeatedly fails to follow rules. --- # CLAUDE.md 渐进式披露优化器 @@ -12,7 +12,14 @@ description: | > "找到最小的高信号 token 集合，最大化期望结果的可能性。" — Anthropic -**目标是最大化 LLM 工作效能，而非最小化行数。** +**目标是最大化信息效率、可读性、可维护性。** + +### 铁律：禁止用行数作为评价指标 + +- 行数少不代表更好，行数多不代表更差 +- 优化的评判标准是：**单一信息源**（同一信息不在多处维护）、**认知相关性**（当前任务不需要的信息不干扰注意力）、**维护一致性**（改一处不需要同步另一处） +- 禁止在优化方案中出现"从 X 行精简到 Y 行"、"减少 Z%"等表述 +- 一个结构清晰、信息不重复的长文件，比一个砍掉关键信息的短文件更好 ### 两层架构 @@ -285,16 +292,16 @@ function getDatabase() { ## 反模式警告 -### ⚠️ 反模式 1：过度精简 +### ⚠️ 反模式 1：以行数为目标的过度精简 -**案例**：把 2937 行压缩到 165 行 +**案例**：为了"减少行数"，移走了代码模式、诊断流程、目录映射 **结果**： -- 丢失代码模式，每次重新推导 +- 丢失代码模式，LLM 每次重新推导 - 丢失诊断流程，遇错不知查哪 - 丢失目录映射，找文件效率低 -**正确**：保留所有高频使用的内容，即使行数较多。 +**正确**：保留所有高频使用的内容。优化的判断标准是信息是否重复维护、是否与当前任务无关，而不是"文件太长"。 ### ⚠️ 反模式 2：无触发条件的引用 @@ -320,6 +327,14 @@ function getDatabase() { **正确**：移到 Level 2，保留触发条件。 +### ⚠️ 反模式 5：用行数当 KPI + +**案例**：优化方案写"从 2000 行精简到 500 行，减少 75%" + +**问题**：把行数当成功指标，会驱动错误决策——为了凑数字而砍掉有用的信息。 + +**正确**：用信息质量评估优化效果——信息是否有重复？维护负担是否降低？LLM 是否能更快找到需要的信息？ + --- ## 信息量检验 @@ -354,7 +369,7 @@ function getDatabase() { |------|--------|--------| | 位置 | `~/.claude/CLAUDE.md` | `项目/CLAUDE.md` | | References | `~/.claude/references/` | `docs/references/` | -| 行数参考 | 100-300 | 300-600 | +| 信息范围 | 个人偏好、全局规则 | 项目架构、团队规范 | --- diff --git a/claude-md-progressive-disclosurer/references/progressive_disclosure_principles.md b/claude-md-progressive-disclosurer/references/progressive_disclosure_principles.md index 7eb312f..af7218b 100644 --- a/claude-md-progressive-disclosurer/references/progressive_disclosure_principles.md +++ b/claude-md-progressive-disclosurer/references/progressive_disclosure_principles.md @@ -4,13 +4,13 @@ --- -## 案例 1：过度精简的失败 +## 案例 1：以行数为目标的过度精简 ### 背景 -某项目 CLAUDE.md 原有 2937 行，尝试优化。 +某项目 CLAUDE.md 内容丰富，包含代码模式、诊断流程、目录映射等。 ### 错误做法 -压缩到 165 行，移走了大部分内容。 +以"减少行数"为目标，移走了大部分内容，只保留简短描述和指针。 ### 结果 - ❌ 丢失代码模式，LLM 每次重新推导 @@ -18,17 +18,17 @@ - ❌ 丢失目录映射，找文件效率低 ### 正确做法 -保留 482 行，关键内容如下： +按**信息质量**而非行数判断去留： -| 内容 | 保留位置 | 原因 | -|------|----------|------| -| 核心命令表 | Level 1 | 高频使用 | -| 懒加载代码模式 | Level 1 | 需要直接复制 | -| ABI 错误诊断 | Level 1 | 完整流程 | -| 详细 SOP | Level 2 | 有触发条件 | +| 内容 | 保留位置 | 判断依据 | +|------|----------|----------| +| 核心命令表 | Level 1 | 高频使用，不应让 LLM 每次去查 | +| 懒加载代码模式 | Level 1 | 需要直接复制，移走会导致重新推导 | +| ABI 错误诊断 | Level 1 | 完整症状→原因→修复流程 | +| 详细 SOP | Level 2 | 低频、有明确触发条件 | ### 教训 -**行数不是目标，效能才是。** +**信息效率、可读性、可维护性是标准，行数不是。** --- @@ -143,10 +143,10 @@ LLM 注意力呈 U 型分布：开头和末尾强，中间弱。只放中间会 ## 案例 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 | +| **维护一致性** | 改一处是否需要同步另一处？如果是，消除重复 | + +### 教训 +**行数少不代表更好，行数多不代表更差。真正的标准是信息效率、可读性、可维护性。** diff --git a/windows-remote-desktop-connection-doctor/.security-scan-passed b/windows-remote-desktop-connection-doctor/.security-scan-passed new file mode 100644 index 0000000..5d43066 --- /dev/null +++ b/windows-remote-desktop-connection-doctor/.security-scan-passed @@ -0,0 +1,4 @@ +Security scan passed +Scanned at: 2026-02-09T11:27:20.232525 +Tool: gitleaks + pattern-based validation +Content hash: ad704c37736e699057f51e289f718b1252d8cff6a1e953f0411ef24400a413da diff --git a/windows-remote-desktop-connection-doctor/SKILL.md b/windows-remote-desktop-connection-doctor/SKILL.md new file mode 100644 index 0000000..c319709 --- /dev/null +++ b/windows-remote-desktop-connection-doctor/SKILL.md @@ -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="" curl -s --connect-timeout 5 "http://: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__