@kg-ai/kugou-skill 0.1.18 → 0.1.20

package/package.json

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

package/references/control.md

@@ -733,7 +733,7 @@ kugou-cli control doctor               # 默认 JSON 输出
 kugou-cli control doctor --json=false   # 一行人类可读
 ```
 
-**零副作用**：不启动客户端、不抢焦点、不写盘。安全在任何时候跑。
+**副作用极小**：不启动客户端、不抢焦点、不触发 URL scheme。唯一的磁盘动作是 `$HOME` 可写性探测——可能创建 `~/.config/kugou-cli` 目录并写入后立即删除一个临时文件（CLI 握手本来也要用这个目录）。安全在任何时候跑。
 
 ### 退出码
 
@@ -759,6 +759,12 @@ kugou-cli control doctor --json=false   # 一行人类可读
 | `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.in_job_object` | bool \| null | 当前进程是否在 Job Object 里（Win 才有意义）。`true` 意味着 kugou-cli 派生的进程可能被 sandbox reap |
+| `environment.job_breakaway_allowed` | bool \| null | Job 是否允许 `CREATE_BREAKAWAY_FROM_JOB`（设置 `JOB_OBJECT_LIMIT_BREAKAWAY_OK` / `SILENT_BREAKAWAY_OK`）。`false` = 派生链逃不出 Job，CLI 因此**不再**设置该标志；`null` 字段省略 = 不在 Job 或读不到 Job flag |
+| `environment.job_kill_on_close` | bool \| null | Job 是否设置 `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`。`true` = Job 关闭时其内进程被内核终止——这是"客户端启动后又消失"的真正原因；`null` = 不在 Job 或读不到 |
+| `environment.process_integrity_level` | string | Token 完整性级别：`Low`（AppContainer / LPAC）/`Medium`（普通）/`High`（elevated）/`System`/`Unknown`。`Low` 意味着 Job breakaway 也救不了 |
+| `environment.parent_process` | string | `pid=N path=...` —— 当前进程的父进程，用于识别是否跑在 sandbox runner 下 |
+| `environment.grandparent_process` | string | `pid=N path=...` —— 祖父进程，二级排查（"spawned by shell" vs "spawned directly by sandbox"） |
 | `environment.home_dir` | string | 解析后的 `$HOME`/`$USERPROFILE` |
 | `environment.home_dir_accessible` | bool | `.config/kugou-cli/` 是否可创建+写 |
 | `hints` | string[] | 给用户的修复建议（HVCI 关、$HOME 设置、PowerShell 缺失等） |
@@ -808,14 +814,38 @@ agent wants to call control play
        ├─ fatal=1 → tell user to install client / fix $HOME, abort
        └─ fatal=0 → proceed
             ├─ hints contain "HVCI" → warn user before start, ask before disabling HVCI
+            ├─ hints contain "Job Object" or "AppContainer" → sandbox reap 问题,
+            │   kugou-cli 改不了,需要 sandbox 平台方配合或绕开 sandbox 启动
             └─ no hints → just run control start, then control play
 ```
 
+### Sandbox reap 诊断速查
+
+`control start` 失败的"6 秒超时"对多种原因长得一模一样，**`doctor` 的 `environment` 字段把它们分开**：
+
+| `in_job_object` | `job_breakaway_allowed` | `job_kill_on_close` | `process_integrity_level` | 隔离类型 | 结果 |
+|---|---|---|---|---|---|
+| `false` | (省略) | (省略) | `Medium` | 无 Job 隔离 | ✅ 客户端正常存活 |
+| `true` | `true` | 任意 | 任意 | Job 隔离，允许 breakaway | ✅ CLI 请求脱离 Job，客户端存活 |
+| `true` | `false` | `true` | 任意 | Job 隔离，不允许脱离且关闭即终止 | ⚠️ 客户端能启动，但 Job 关闭（宿主结束命令）时被终止 |
+| `true` | `false` | `false` | 任意 | Job 隔离，不允许脱离但不强杀 | ⚠️ 客户端可能存活，但不保证 |
+| `true` | (省略) | (省略) | 任意 | Job 隔离，读不到 flag | ⚠️ 未知，按最坏情况处理 |
+| (省略) | (省略) | (省略) | `Low` | **AppContainer / LPAC**（不走 Job） | ❌ Job breakaway 救不了 |
+| (省略) | (省略) | (省略) | (省略) | 非 Windows 平台 | N/A |
+
+> **重要（2026-09-11 修正）**：当 `job_breakaway_allowed=false` 时，CLI **不会**再设置 `CREATE_BREAKAWAY_FROM_JOB`——因为在禁止脱离的 Job 里请求脱离会让 `CreateProcess` 直接返回 `ERROR_ACCESS_DENIED`，客户端根本起不来。旧版无条件设置该标志，反而在最需要它的 Job 隔离环境里把启动搞挂了。现在客户端会正常启动并在**当前命令**存续期间存活；能否跨命令存活由宿主的 Job 生命周期决定（`job_kill_on_close`）。
+>
+> **实用结论**：在 `breakaway=false` 的宿主里，把 `control start` 和真正的控制命令**串在同一条命令里执行**（例如 `control start && control play ...`）即可播放——它们共享同一个 Job，客户端在这条命令期间一直活着。分成两条独立命令时，前一条启动的客户端在后一条里可能已被回收。
+
+> 字段省略 (`omitempty`) = 该平台不探测，或探测失败导致值是 nil。要区分这两种情况，看 `platform` 字段：非 Windows 上所有 Win-only 字段都省略。
+
+父进程链 (`parent_process` / `grandparent_process`) 用于识别"我是被什么 spawn 出来的"，对识别具体 sandbox runner（workbuddy / opencode / cloud-agent 等）有用，但 doctor 不内置 sandbox 名到 hint 的映射——这部分逻辑放在调用方，doctor 只负责给出**真实数据**。
+
 ### 与 `control detect` 的区别
 
 | 维度 | `control detect` | `control doctor` |
 |---|---|---|
-| 副作用 | 零（只读 OS 信号） | 零（多读了 HVCI/VBS/launcher/$HOME） |
+| 副作用 | 零（只读 OS 信号） | 极小（读 HVCI/VBS/launcher/Job，外加一次 `~/.config/kugou-cli` 可写性探测：建目录+写删临时文件） |
 | 输出焦点 | "客户端有没有装？" | "为什么 `control start` 会失败？" |
 | 退出码 | 0/1/2（installed 维度） | 0/1/2（fatal+hint 维度） |
 | 应在何时跑 | AI agent 每次冷启动前 | `control start` 失败后 |