@kg-ai/kugou-skill 0.1.19 → 0.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kg-ai/kugou-skill",
-  "version": "0.1.19",
+  "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 握手本来也要用这个目录）。安全在任何时候跑。
 
 ### 退出码
 
@@ -760,7 +760,8 @@ kugou-cli control doctor --json=false   # 一行人类可读
 | `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`）。`false` = 派生链逃不出 sandbox；`null` 字段省略 = 不在 Job 或读不到 Job handle |
+| `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"） |
@@ -822,14 +823,19 @@ agent wants to call control play
 
 `control start` 失败的"6 秒超时"对多种原因长得一模一样，**`doctor` 的 `environment` 字段把它们分开**：
 
-| `in_job_object` | `job_breakaway_allowed` | `process_integrity_level` | 隔离类型 | `control start` 是否能拉起客户端 |
-|---|---|---|---|---|
-| `false` | (字段省略) | `Medium` | 无 Job 隔离 | ✅ 应能正常 |
-| `true` | `true` | 任意 | Job 隔离，允许 breakaway | ✅ 派生链能逃出 Job |
-| `true` | `false` | `Medium` | Job 隔离，**不允许** breakaway | ❌ 客户端会被 reap |
-| `true` | (字段省略) | 任意 | Job 隔离，读不到 breakaway flag | ❌ 推测为不允许 |
-| (字段省略) | (字段省略) | `Low` | **AppContainer / LPAC**（不走 Job） | ❌ Job breakaway 救不了 |
-| (字段省略) | (字段省略) | (字段省略) | 非 Windows 平台 | N/A |
+| `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 字段都省略。
 
@@ -839,7 +845,7 @@ agent wants to call control play
 
 | 维度 | `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` 失败后 |