用途：诊断 winapp CLI 命令报错、为任务选择合适命令、理解各命令的前置条件与产出物，并给出常见错误的解决方案。若用户无法运行 winapp（无 shell 或命令被拒），应直接提供其项目所需的 winapp 命令，而非仅描述步骤。
主要能力：以错误对照表形式覆盖 winapp.yaml/Package.appxmanifest 缺失、发布者不匹配、权限不足、证书不受信任、构建工具未下载、包身份添加失败、证书或清单文件已存在、0x800704EC（开发者模式未启用）、0x80073CFB（身份冲突）、开始菜单项静默失效，以及缓存目录不可写等情形，并给出对应命令或设置。
使用方式：提供命令选择流程，如单 .cs 文件用 winapp run；无清单时可 winapp init 或 winapp manifest generate；已有清单则按需 restore、update、cert generate、create-debug-identity、package、sign、manifest update-assets、tool、store、get-winapp-path。调试方面可用 --no-launch、--debug-output、--unregister-on-exit、--detach、--json、unregister --prune 等。通用调试技巧包括 --verbose、--quiet、--cli-schema、--help。
限制与注意事项：winapp init 只向已有项目添加文件，不创建新项目；多数命令关键前置是 Package.appxmanifest，而非 winapp.yaml；winapp.yaml 仅用于 SDK 版本管理。含 NuGet 引用的项目可无需 winapp.yaml。Electron 需用 npm 包并在 npx winapp node 下使用。Visual Studio 有打包项目时通常无需 winapp 调试。缓存不可写时可设置 WINAPP_CLI_CACHE_DIRECTORY。更多信息见 https://github.com/microsoft/WinAppCli/blob/main/docs/usage.md 与 https://github.com/microsoft/WinAppCli/issues。