@kg-ai/kugou-skill 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kg-ai/kugou-skill",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Kugou Skill CLI",
   "main": "index.js",
   "bin": {

package/references/control.md

@@ -42,6 +42,7 @@
 | 命令 | 说明 |
 |------|------|
 | `kugou-cli control open` | 打开客户端内页面（主界面/歌手/专辑/歌单/搜索） |
+| `kugou-cli control doctor` | 诊断 `control start` 失败的根因（HVCI / VBS / launcher / home-dir） |
 
 ---
 
@@ -63,6 +64,11 @@ kugou-cli control start
 kugou-cli control: not logged in, run `kugou-cli auth login` first: auth file not found
 ```
 
+**`start` 失败时优先跑 `control doctor` 诊断根因**（见下文 §N）。常见场景：
+- Win11 Memory Integrity (HVCI) 开着 + 客户端 v20.1.40：HVCI 拦截客户端启动时访问的内存，触发 NTSTATUS 0xC0000005 → 关 HVCI 后重试
+- PowerShell 被裁掉（Windows Sandbox / AppContainer）：URL scheme 触发失败 → 自动 fallback 到 `cmd /c start`
+- $HOME / $USERPROFILE 未设置或不可写：握手文件无法落地 → 设置有效环境变量
+
 ---
 
 ## 2. status — 获取客户端状态
@@ -714,6 +720,108 @@ kugou-cli control detect --json=false  # 人类可读一行
 
 ---
 
+## 14. Doctor (`control doctor`)
+
+> 诊断 `control start` 失败的根因——`detect` 只看"客户端有没有装"，`doctor` 看"为什么拉不起"。
+
+`control start` 的"6 秒握手超时"对**完全没装客户端**、**Win11 HVCI 不兼容导致客户端启动后立即崩**、**PowerShell 被裁掉**、**$HOME 不可写**这些情况长得一模一样——都是同一个错误。`doctor` 把这些信号分开成结构化字段，AI agent 能直接据此判断该走哪个分支。
+
+### 用法
+
+```bash
+kugou-cli control doctor               # 默认 JSON 输出
+kugou-cli control doctor --json=false   # 一行人类可读
+```
+
+**零副作用**：不启动客户端、不抢焦点、不写盘。安全在任何时候跑。
+
+### 退出码
+
+| 退出码 | 含义 | 何时 |
+|---|---|---|
+| `0` | OK，无 fatal 无 hint | 环境正常，可直接 `control start` |
+| `1` | FATAL，必须修 | `client.installed=false` 或 `home_dir_accessible=false` |
+| `2` | 非 fatal，有 hint | `hints` 数组非空——start 仍可能成功，但建议看 hint |
+
+### JSON 输出字段
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `platform` / `goos` | string | `runtime.GOOS`（`windows` / `darwin` / `linux`） |
+| `checked_at` | RFC3339 | 检查时间 |
+| `client.installed` | bool | `Detect()` 的总判定 |
+| `client.exe_path` | string | 客户端可执行文件绝对路径（HKCR scheme handler 或 install 路径扫描） |
+| `client.version` | string | HKLM Uninstall `DisplayVersion`（Win）；空表示无法读到 |
+| `client.scheme_registered` | bool | `HKCR\kugou` 注册项 |
+| `client.handshake_path` | string | 握手文件期望位置 |
+| `client.handshake_exists` | bool | 握手文件是否已存在 |
+| `environment.hvci_enabled` | bool \| null | Win11 Memory Integrity（`HKLM\...\HypervisorEnforcedCodeIntegrity\Enabled`），非 Win 平台为 `null` |
+| `environment.vbs_enabled` | bool \| null | VBS（`HKLM\...\DeviceGuard\EnableVirtualizationBasedSecurity`） |
+| `environment.powershell_available` | bool \| null | `powershell.exe` 是否在 PATH |
+| `environment.explorer_available` | bool \| null | `explorer.exe` 是否在 PATH |
+| `environment.home_dir` | string | 解析后的 `$HOME`/`$USERPROFILE` |
+| `environment.home_dir_accessible` | bool | `.config/kugou-cli/` 是否可创建+写 |
+| `hints` | string[] | 给用户的修复建议（HVCI 关、$HOME 设置、PowerShell 缺失等） |
+| `fatal` | bool | 是否 fatal |
+| `fatal_reason` | string | fatal 时的简短原因 |
+
+**三态指针规则**：`null` = 该平台不探测或探测失败；`true`/`false` = 已探测且确定。
+
+### JSON 输出示例（Win11 + HVCI 开 + 客户端 v20.1.40）
+
+```json
+{
+  "platform": "windows",
+  "goos": "windows",
+  "checked_at": "2026-09-11T16:14:30+08:00",
+  "client": {
+    "installed": true,
+    "exe_path": "C:\\Program Files\\KuGou\\KGMusic\\KuGou.exe",
+    "version": "20.1.40.27854",
+    "scheme_registered": true,
+    "handshake_path": "C:\\Users\\alice\\.config\\kugou-cli\\handshake.json",
+    "handshake_exists": false
+  },
+  "environment": {
+    "hvci_enabled": true,
+    "vbs_enabled": true,
+    "powershell_available": true,
+    "explorer_available": true,
+    "home_dir": "C:\\Users\\alice",
+    "home_dir_accessible": true
+  },
+  "hints": [
+    "Win11 Memory Integrity (HVCI) is enabled — Kugou client v20.x is known to crash with NTSTATUS 0xC0000005 under HVCI",
+    "workaround: Settings → Privacy & Security → Windows Security → Device Security → Core Isolation → Memory Integrity → Off, then reboot",
+    "client version 20.1.40.27854 is on the known-HVCI-crash list even with Memory Integrity on; upgrading to v20.2+ is recommended",
+    "no handshake file yet — `control start` will fire the URL scheme; if it times out, the most likely cause is the client crashing on launch (see HVCI hint above)"
+  ],
+  "fatal": false
+}
+```
+
+### 在 AI 工作流里的位置
+
+```text
+agent wants to call control play
+  └─ first: run control doctor
+       ├─ fatal=1 → tell user to install client / fix $HOME, abort
+       └─ fatal=0 → proceed
+            ├─ hints contain "HVCI" → warn user before start, ask before disabling HVCI
+            └─ no hints → just run control start, then control play
+```
+
+### 与 `control detect` 的区别
+
+| 维度 | `control detect` | `control doctor` |
+|---|---|---|
+| 副作用 | 零（只读 OS 信号） | 零（多读了 HVCI/VBS/launcher/$HOME） |
+| 输出焦点 | "客户端有没有装？" | "为什么 `control start` 会失败？" |
+| 退出码 | 0/1/2（installed 维度） | 0/1/2（fatal+hint 维度） |
+| 应在何时跑 | AI agent 每次冷启动前 | `control start` 失败后 |
+
+---
+
 ## 相关文档
 
 - [references/output-format.md](./output-format.md) — 输出格式与展示规范