@shundoo-ai/dsh-cosmic 1.0.2 → 1.0.4-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shundoo-ai/dsh-cosmic",
-  "version": "1.0.2",
+  "version": "1.0.4-alpha.0",
   "type": "module",
   "files": [
     ".config",

package/skills/cosmic-build/skills/cosmic-vibe-coding/SKILL.md

@@ -10,7 +10,7 @@ description: >
 | 职责 | 内容 | 载体 |
 |------|------|------|
 | ① 开启热部署 | 开 `jar_deploy_enable` 开关、连 IDEA MCP、生成 `dev.json` | `scripts/dev.py` + `assets/dev.json` |
-| ② 热加载 | 不重启、不碰 mc，把 jar 注入运行中 cosmic | `assets/kd-reloadjar-agent.jar` |
+| ② 热加载 | 不重启、不碰 mc，把 jar 注入运行中 cosmic | `assets/kd-reloadjar-agent.jar`（**需先复制到机器级缓存再用**，见职责②§3） |
 | ③ build + 热部署 | 构建 jar（MCP 定位编译错误）→ 热加载 | IDEA MCP / gradle + agent |
 
 ## 触发场景
@@ -42,6 +42,32 @@ description: >
 
 ---
 
+## Windows：一条命令走完全程（推荐）
+
+> 下面各职责给的是 **macOS/Linux** 命令。Windows 上**手拼这套流程代价极高** —— 实测一个 Windows 会话为跑通「构建 + 热部署」发了 **63 条 pwsh**、**6 次提权**（探测 PID → 找 JDK → 找 tools.jar → attach，每步都要单独授权）。
+
+本 skill 随包提供封装脚本，**把全程收敛成一次调用 ⇒ 只需一次提权**：
+
+```powershell
+# 体检（不部署）
+pwsh -File {SKILL_DIR}\scripts\cosmic-hotdeploy.ps1
+# 构建 + 热部署
+pwsh -File {SKILL_DIR}\scripts\cosmic-hotdeploy.ps1 -Module <模块名>
+# 干净重建 + 热部署
+pwsh -File {SKILL_DIR}\scripts\cosmic-hotdeploy.ps1 -Module <模块名> -Clean
+# 只热部署已有 jar
+pwsh -File {SKILL_DIR}\scripts\cosmic-hotdeploy.ps1 -Jar <jar路径>
+# 只构建、不部署
+pwsh -File {SKILL_DIR}\scripts\cosmic-hotdeploy.ps1 -Module <模块名> -WhatIf
+```
+
+内部依次完成：定位工作区 → 解析 preset bundle → 读 `dev.json` → **按端口反查 cosmic PID**（不是 `jps`，见职责②）→ 挑含 `tools.jar` 的 JDK → 构建 → Attacher 热加载。
+
+参数：`-Module`｜`-Jar`｜`-Clean`｜`-WhatIf`｜`-LogFile`｜`-Workspace`｜`-PresetDir`｜`-Port`。
+工作区默认从「脚本位置的上两级」或当前目录推断；布局不同就传 `-Workspace <项目根>`。
+
+---
+
 ## 职责①：开启热部署（每个环境一次性）
 
 1. **IDEA 启动 MCP（可选）**：JetBrains MCP，固定 URL `http://127.0.0.1:64342/stream`，用于**代码智能**（符号查找、调用分析、重构、即时查错）。⚠️ **非构建必需**——产 jar 走 gradle 命令行（见职责③），MCP 未配/未连不影响「build + 热部署」主线。
@@ -89,12 +115,36 @@ description: >
 
 - 通用：`jps -l | grep kd.bos.service.webserver.JettyServer`（取 `appName=cosmic` 的那个）
 - macOS 备选：`lsof -tiTCP:<port> -sTCP:LISTEN`
+- **Windows 推荐（实测最可靠）**：按端口反查 + 命令行校验
+
+  ```powershell
+  $conn = Get-NetTCPConnection -LocalPort <port> -State Listen | Select-Object -First 1
+  (Get-CimInstance Win32_Process -Filter "ProcessId=$($conn.OwningProcess)").CommandLine   # 应含 kd.bos.service.webserver.JettyServer
+  ```
+
+  > ⚠️ **Windows 上 `jps` 看不到 cosmic**（实测）：cosmic 常由 **SYSTEM** 账户启动，而 `jps` 只列举**当前用户**的 JVM → 输出里完全没有它，**极易误判「cosmic 没启动」**。用上面的方式零替代。
+  > 另：发现 PID 后先扫命令行里有没有 `-XX:+DisableAttachMechanism` —— 带此参数的 JVM **无法 attach**（硬阻断）。
+  > 跨用户 attach 本身**可用、无需提权**（Windows JVM attach 命名管道对 Administrators 组放行）。
 
 ### 3. 热部署
 
+> ⚠️ **别直接用 preset 里的 `{SKILL_DIR}/assets/kd-reloadjar-agent.jar`** —— 先把 agent jar 复制到**机器级缓存**再用（`{AGENT}`，见下）。原因：Attacher 会把这个 jar **载入运行中的 cosmic JVM**，而 JVM 的 classloader 会**长期持有**该文件句柄；preset 一旦升级，包管理器要**整目录替换**（每个文件都得能删/改名）→ 必然在这个 jar 上失败（Windows 报 `os error 32`／拒绝访问）。
+>
+> `{AGENT}` = `$DSH_HOME/cache/cosmic/agent/kd-reloadjar-agent-<sha1前8位>.jar`（**带内容哈希命名**，所以新版永远不会覆盖可能已被 JVM 载入的旧副本）。`init-python.{sh,ps1}` 会预先复制；`cosmic-hotdeploy.ps1` 也会自动解析并复制。手工操作时：
+
 ```bash
-<java_home>/bin/java -cp <java_home>/lib/tools.jar:{SKILL_DIR}/assets/kd-reloadjar-agent.jar kd.reloadjar.Attacher \
-     <cosmicPID> {SKILL_DIR}/assets/kd-reloadjar-agent.jar \
+# 先把 preset 里的原件复制到机器级缓存（哈希命名），再用缓存路径
+AGENT_DIR="${DSH_HOME:-$HOME/.dsh}/cache/cosmic/agent"
+SRC="{SKILL_DIR}/assets/kd-reloadjar-agent.jar"
+HASH=$( (shasum -a 1 "$SRC" 2>/dev/null || sha1sum "$SRC") | cut -c1-8 )
+AGENT="$AGENT_DIR/kd-reloadjar-agent-$HASH.jar"
+mkdir -p "$AGENT_DIR" && [ -f "$AGENT" ] || cp "$SRC" "$AGENT"
+```
+
+```bash
+# 用缓存副本调 Attacher（Windows 上把 : 换成 ;）
+<java_home>/bin/java -cp <java_home>/lib/tools.jar:"$AGENT" kd.reloadjar.Attacher \
+     <cosmicPID> "$AGENT" \
      "<jar绝对路径1>,<jar绝对路径2>" \
      <account_id> <tenant_id> \
      <可选logFile绝对路径>
@@ -104,6 +154,7 @@ description: >
 - jar 路径可直接用构建产物 `build/libs/xxx.jar`，**无需拷到 lib/cus**。
 - 最后一个参数 `logFile` **可选**：填了则在开发机侧写成功/失败标记日志（`status=SUCCESS/FAILED`）。
 - classpath 分隔符：macOS/Linux 用 `:`，Windows 用 `;`。
+- **Windows 直接用**「Windows：一条命令走完全程」里的 `cosmic-hotdeploy.ps1`（它已内置上述缓存逻辑）。
 
 ### 4. 验证
 
@@ -131,6 +182,13 @@ GRADLE_USER_HOME=<cwd>/.gradle/user-home "$GRADLE" :<模块>:build -x test
 - 产物在 `<模块>/build/libs/*.jar`（本环境 `code/yun/sd-khxty-yun/build/libs/sd-khxty-yun-1.0.0.jar`）。
 - ⚠️ 产 jar **只认 gradle 命令行**：IDEA MCP `build_project` 默认增量、源码未变会跳过（`isSuccess:true` 但 jar 不更新）；勿用 `buildJar`/`deployJar`（那是冷启动拷贝到 lib/cus，热部署不需要）。
 
+> **Windows 必读（实测踩坑，失败一次排查很久）**
+> - **必须显式设 `JAVA_HOME` 指向 JDK（不是 JRE）**：Windows 注册表 `HKLM\SOFTWARE\JavaSoft\Java Development Kit` 的 `JavaHome` 会被 JRE 安装包改写成 `...\jre1.8.0_481`，Gradle 采信它 → `java.home` 指向 JRE → 报 `Could not find tools.jar`。显式 `$env:JAVA_HOME="C:\Program Files\Java\jdk1.8.0_XXX"`
+> - **Gradle 版本必须按 `gradle/wrapper/gradle-wrapper.properties` 锁定**，不要「取 `~/.gradle/wrapper/dists` 下最新」—— 机器上可能同时装了要求 Java 22 的新版 Gradle，会直接把构建带偏。
+> - ⚠️ **「伪成功构建」陷阱**：`compileJava` 处于 `UP-TO-DATE` 时 Gradle **根本不加载编译器**，缺 tools.jar 也不报错 → 看到 `BUILD SUCCESSFUL` + jar 正常产出，**但里面是旧字节码**。首次接入务必 `clean build` 验证一次真编译。
+>
+> 完整分析见 `cosmic-dev-best-practices/references/cosmic-hotdeploy-build-slow-windows.md` §4.3 / §4.7。Windows 上直接用上面「Windows：一条命令走完全程」的封装脚本即可，它已内置这些约束。
+
 ### 2. 定位错误 / 理解代码（IDEA MCP 代码智能，可选加分项）
 
 > 此节可选：MCP 未配/未连不影响「build + 热部署」主线（gradle stderr 本身也会报编译错误，含文件名+行号）。
@@ -181,4 +239,5 @@ agent（`kd.reloadjar.ReloadAgent`）在 cosmic 进程内自动执行这两步
 |------|------|------|
 | `assets/dev.json` | ① 开启热部署 | 空配置模板（`dev.py` 读它作字段基础，生成工作区 `.dsh/cosmic/config/dev.json`） |
 | `scripts/dev.py` | ① 开启热部署 | 环境配置脚本（`init`=读 `.kd/config.json` 覆盖 dev.json；`read`=只读；`__file__` 反推 skill 根） |
-| `assets/kd-reloadjar-agent.jar` | ② 热加载 | 热重载 agent（含 `kd.reloadjar.ReloadAgent` + `Attacher`） |
+| `scripts/cosmic-hotdeploy.ps1` | ②③ 热加载 / 构建+热部署 | **Windows 一键封装**（可移植：工作区自动推断、无硬编码路径）：体检 / `-Module` 构建+热部署 / `-Clean` / `-Jar` 直传 / `-WhatIf`。见「Windows：一条命令走完全程」 |
+| `assets/kd-reloadjar-agent.jar` | ② 热加载 | 热重载 agent（含 `kd.reloadjar.ReloadAgent` + `Attacher`）。⚠️ **原件不要直接加载** —— 先复制到 `$DSH_HOME/cache/cosmic/agent/kd-reloadjar-agent-<sha1前8位>.jar` 再用（避免 preset 升级时被 JVM 锁住，见职责②§3） |

package/skills/cosmic-build/skills/cosmic-vibe-coding/scripts/cosmic-hotdeploy.ps1

@@ -0,0 +1,257 @@
+# cosmic-hotdeploy.ps1 -- Kingdee Cosmic build + hot-deploy (Windows, portable)
+#
+# PURPOSE
+#   Windows port of the cosmic-vibe-coding skill workflow (the skill docs give
+#   macOS/Linux commands). Discovers the running cosmic JVM, builds the module
+#   with the wrapper-pinned Gradle + a real JDK8, then hot-loads the jar via the
+#   Attacher agent -- no cosmic restart, no touching mc.
+#
+# USAGE
+#   pwsh -File cosmic-hotdeploy.ps1                              # health check only
+#   pwsh -File cosmic-hotdeploy.ps1 -Module <name>                # build + hot-deploy
+#   pwsh -File cosmic-hotdeploy.ps1 -Module <name> -Clean         # clean build + hot-deploy
+#   pwsh -File cosmic-hotdeploy.ps1 -Jar a.jar,b.jar              # hot-deploy existing jars
+#   pwsh -File cosmic-hotdeploy.ps1 -Module <name> -WhatIf        # dry run (build only)
+#
+# PORTABILITY
+#   The workspace is inferred from this script's location (expects to live in
+#   <workspace>/runtime/); override with -Workspace. The skill bundle is located
+#   via $DSH_PROFILE_DIR or $DSH_HOME; override with -PresetDir. No other
+#   machine-specific paths are hard-coded -- the JDK is discovered from the
+#   running cosmic process, then from JAVA_HOME, then from common install roots.
+#
+# NOTE
+#   Windows classpath separator is ';' (not ':'). The Attacher must run on a JDK
+#   whose major version matches the target JVM (JDK8 + lib\tools.jar for cosmic).
+
+[CmdletBinding()]
+param(
+    [string[]]$Jar,
+    [string]$Module,
+    [switch]$Clean,
+    [switch]$WhatIf,
+    [string]$LogFile,
+    [string]$Workspace,
+    [string]$PresetDir,
+    [int]$Port
+)
+
+$ErrorActionPreference = 'Stop'
+
+# ---- 0. Resolve workspace (no hard-coded user paths) ----
+if (-not $Workspace) {
+    # Expect this script at <workspace>\runtime\cosmic-hotdeploy.ps1
+    if ($PSScriptRoot) {
+        $Workspace = Split-Path $PSScriptRoot -Parent
+    } else {
+        $Workspace = (Get-Location).Path
+    }
+    # If it was moved elsewhere, fall back to the cwd when that looks like a workspace.
+    if (-not (Test-Path (Join-Path $Workspace 'settings.gradle'))) {
+        if (Test-Path (Join-Path (Get-Location).Path 'settings.gradle')) {
+            $Workspace = (Get-Location).Path
+        }
+    }
+}
+if (-not (Test-Path (Join-Path $Workspace 'settings.gradle'))) {
+    throw "Workspace '$Workspace' has no settings.gradle. Pass -Workspace <project root>."
+}
+$cwd = (Resolve-Path $Workspace).Path
+
+# ---- 0.1 Resolve the cosmic skill bundle ----
+if (-not $PresetDir) {
+    $roots = @()
+    if ($env:DSH_PROFILE_DIR) { $roots += (Join-Path $env:DSH_PROFILE_DIR 'node_modules\@shundoo-ai\dsh-cosmic') }
+    if ($env:DSH_HOME) { $roots += (Join-Path $env:DSH_HOME '.agent-presets\cosmic') }
+    $PresetDir = $roots | Where-Object { $_ -and (Test-Path $_) } | Select-Object -First 1
+}
+if (-not $PresetDir) {
+    throw "Cannot locate the cosmic skill bundle. Set DSH_PROFILE_DIR/DSH_HOME, or pass -PresetDir <path containing skills\cosmic-build>."
+}
+$srcAgent = Join-Path $PresetDir 'skills\cosmic-build\skills\cosmic-vibe-coding\assets\kd-reloadjar-agent.jar'
+if (-not (Test-Path $srcAgent)) { throw "Missing reload agent: $srcAgent" }
+
+# ---- 0.2 Agent jar: use a machine-level, content-hashed COPY -- never load it from the preset ----
+#   Why: the Attacher loads this jar into the running cosmic JVM, and the JVM's classloader keeps
+#   the JarFile handle open for the JVM's lifetime. npm/pnpm upgrades replace the *whole package
+#   directory* (move the old dir away, put the new one in), which requires every file inside to be
+#   deletable/renamable -> the upgrade always fails on this jar (Windows: os error 32 / access
+#   denied). The old git-based layout never hit this because git only rewrites files whose content
+#   actually changed, and this jar rarely changes.
+#   Naming the copy with the content hash means a *new* preset version never overwrites an old copy
+#   that may already be loaded by a JVM.
+$dshHome = if ($env:DSH_HOME) { $env:DSH_HOME }
+           elseif ($env:USERPROFILE) { Join-Path $env:USERPROFILE '.dsh' }
+           elseif ($env:HOME) { Join-Path $env:HOME '.dsh' }
+           else { $null }
+$agent = $srcAgent
+if ($dshHome) {
+    $agentHash = (Get-FileHash $srcAgent -Algorithm SHA1).Hash.Substring(0, 8).ToLower()
+    $agentDir = Join-Path (Join-Path $dshHome 'cache\cosmic') 'agent'
+    $cachedAgent = Join-Path $agentDir "kd-reloadjar-agent-$agentHash.jar"
+    try {
+        if (-not (Test-Path $cachedAgent)) {
+            New-Item -ItemType Directory -Force -Path $agentDir | Out-Null
+            Copy-Item $srcAgent $cachedAgent -Force
+        }
+        $agent = $cachedAgent
+        # best-effort housekeeping: keep only the newest few hashed copies
+        Get-ChildItem $agentDir -Filter 'kd-reloadjar-agent-*.jar' -ErrorAction SilentlyContinue |
+            Sort-Object LastWriteTime -Descending | Select-Object -Skip 5 |
+            Remove-Item -Force -ErrorAction SilentlyContinue
+    } catch {
+        Write-Host "[agent] WARN cannot use the cached copy ($($_.Exception.Message)); falling back to the preset copy (preset upgrades may then hit a file lock)."
+    }
+}
+$devScript = Join-Path $PresetDir 'skills\cosmic-build\skills\cosmic-vibe-coding\scripts\dev.py'
+
+# ---- 1. Read dev.json (env config produced by dev.py init) ----
+$devJson = Join-Path $cwd '.dsh\cosmic\config\dev.json'
+if (-not (Test-Path $devJson)) {
+    throw "Missing $devJson -- run 'dev.py init' first (enable hot-deploy / set ERP login)."
+}
+$dev = Get-Content $devJson -Raw | ConvertFrom-Json
+
+# Port: explicit -Port wins, then dev.json, then the port embedded in erp_url.
+$effPort = if ($Port) { $Port }
+elseif ($dev.port) { [int]$dev.port }
+elseif ($dev.erp_url -match '^https?://[^:/]+:(\d+)') { [int]$Matches[1] }
+else { 80 }
+$accountId = $dev.account_id
+$tenantId = $dev.tenant_id
+if (-not $accountId) { throw "dev.json has no account_id -- re-run 'dev.py init'." }
+
+# ---- 2. Discover the cosmic PID by port ownership, then validate the JVM ----
+$conn = Get-NetTCPConnection -LocalPort $effPort -State Listen -ErrorAction SilentlyContinue |
+    Select-Object -First 1
+if (-not $conn) { throw "Nothing is listening on port $effPort -- is cosmic running?" }
+$targetPid = $conn.OwningProcess
+$proc = Get-CimInstance Win32_Process -Filter "ProcessId=$targetPid"
+if ($proc.CommandLine -notmatch 'kd\.bos\.service\.webserver\.JettyServer') {
+    throw "Process $targetPid on port $effPort is not the cosmic JettyServer: $($proc.CommandLine)"
+}
+if ($proc.CommandLine -match 'DisableAttachMechanism') {
+    throw "Process $targetPid has -XX:+DisableAttachMechanism -- hot-deploy cannot attach to it."
+}
+$owner = ($proc | Invoke-CimMethod -MethodName GetOwner).User
+
+# ---- 3. Pick the JDK: prefer the one the cosmic process itself runs on ----
+# Derive JAVA_HOME from the process executable (reliable, unlike parsing the
+# command line, which may quote "C:\path with spaces"\bin\java differently).
+$candidates = @()
+if ($proc.ExecutablePath) {
+    $javaBin = Split-Path $proc.ExecutablePath -Parent          # ...\jdk\bin
+    if ((Split-Path $javaBin -Leaf) -ieq 'bin') { $candidates += (Split-Path $javaBin -Parent) }
+}
+if ($env:JAVA_HOME) { $candidates += $env:JAVA_HOME }
+# Common JDK install roots across drives (best effort, machine independent).
+foreach ($root in @("$env:ProgramFiles\Java", "${env:ProgramFiles(x86)}\Java", 'C:\Java',
+                    'D:\Java', 'D:\Program Files\Java', "$env:USERPROFILE\.jdks")) {
+    if ($root -and (Test-Path $root)) {
+        $candidates += (Get-ChildItem $root -Directory -ErrorAction SilentlyContinue |
+            Where-Object { $_.Name -match '^jdk' } | ForEach-Object { $_.FullName })
+    }
+}
+$candidates = $candidates | Where-Object { $_ } | Select-Object -Unique
+
+# A usable JDK for the Attacher has lib\tools.jar (JDK8) and bin\java.exe.
+$attacherJdk = $candidates |
+    Where-Object { (Test-Path (Join-Path $_ 'lib\tools.jar')) -and (Test-Path (Join-Path $_ 'bin\java.exe')) } |
+    Select-Object -First 1
+if (-not $attacherJdk) {
+    throw @"
+No usable JDK for the Attacher (needs lib\tools.jar + bin\java.exe).
+Candidates tried: $($candidates -join ' | ')
+The target cosmic JVM needs a matching JDK whose major version matches it.
+If cosmic runs on JDK8, install a JDK8 (not a JRE!) and pass -Workspace/-PresetDir as needed,
+or set `$env:JAVA_HOME to a real JDK.
+"@
+}
+$java = Join-Path $attacherJdk 'bin\java.exe'
+$toolsJar = Join-Path $attacherJdk 'lib\tools.jar'
+
+Write-Host "[env] workspace  = $cwd"
+Write-Host "[env] erp_url    = $($dev.erp_url)  (port $effPort)"
+Write-Host "[env] cosmic PID = $targetPid (owner=$owner)"
+Write-Host "[env] attacher JDK = $attacherJdk"
+Write-Host "[env] accountId  = $accountId / tenantId = $tenantId"
+if ($agent -ne $srcAgent) {
+    Write-Host "[agent] $agent  (cached copy; the preset original is never loaded)"
+} else {
+    Write-Host "[agent] $agent  (PRESET ORIGINAL -- preset upgrades may hit a file lock while cosmic runs)"
+}
+
+# ---- 4. Optional: build first ----
+if ($Module) {
+    $gradleHome = Join-Path $cwd '.gradle\user-home'
+
+    # 4.1 Gradle version must follow the wrapper, never "newest dist" -- a newer
+    #     dist (e.g. 8.x) may demand a newer Java runtime and derail this JDK8 chain.
+    $wrapperProps = Join-Path $cwd 'gradle\wrapper\gradle-wrapper.properties'
+    if (-not (Test-Path $wrapperProps)) { throw "Missing $wrapperProps." }
+    $m = [regex]::Match((Get-Content $wrapperProps -Raw), 'gradle-([0-9.]+)-bin')
+    if (-not $m.Success) { throw "Cannot parse the Gradle version from $wrapperProps." }
+    $distVer = $m.Groups[1].Value
+    $distRoot = Join-Path $env:USERPROFILE ".gradle\wrapper\dists\gradle-$distVer-bin"
+    $gradleBat = Get-ChildItem $distRoot -Recurse -Filter 'gradle.bat' -ErrorAction SilentlyContinue |
+        Select-Object -First 1
+    if (-not $gradleBat) {
+        throw "Gradle $distVer not found under $distRoot. Let the wrapper download it first (run .\gradlew.bat)."
+    }
+
+    # 4.2 Build JDK: same preference order as above, but must carry tools.jar.
+    $buildJdk = $attacherJdk
+    if ($WhatIf) { Write-Host '[whatif] dry run: skipping the actual build.' }
+
+    $gradleArgs = @()
+    if ($Clean) { $gradleArgs += (':' + $Module + ':clean') }
+    $gradleArgs += (':' + $Module + ':build')
+    $gradleArgs += @('-x', 'test', '--console=plain')
+    Write-Host "[build] gradle $distVer | $($gradleArgs -join ' ')"
+    Write-Host "[build] JAVA_HOME=$buildJdk  (GRADLE_USER_HOME=$gradleHome)"
+    $env:GRADLE_USER_HOME = $gradleHome
+    $env:JAVA_HOME = $buildJdk
+    & $gradleBat.FullName @gradleArgs
+    if ($LASTEXITCODE -ne 0) { throw "Gradle build failed (exit $LASTEXITCODE) -- see the compile errors above." }
+}
+
+# ---- 5. Resolve jars (auto-locate the build output when -Module was given) ----
+if ((-not $Jar -or $Jar.Count -eq 0) -and $Module) {
+    $settings = Get-Content (Join-Path $cwd 'settings.gradle') -Raw
+    $mm = [regex]::Match($settings,
+        "project\(':$([regex]::Escape($Module))'\)\.projectDir\s*=\s*new File\('([^']+)'\)")
+    $moduleDir = if ($mm.Success) { Join-Path $cwd ($mm.Groups[1].Value -replace '/', '\') }
+                 else { Join-Path $cwd "code\$Module" }
+    $libsDir = Join-Path $moduleDir 'build\libs'
+    $Jar = @(Get-ChildItem $libsDir -Filter '*.jar' -ErrorAction SilentlyContinue |
+        Where-Object { $_.Name -notlike '*sources*' -and $_.Name -notlike '*javadoc*' } |
+        Sort-Object LastWriteTime -Descending | Select-Object -First 1 |
+        ForEach-Object { $_.FullName })
+    if (-not $Jar) { throw "No build output jar in $libsDir." }
+}
+if (-not $Jar -or $Jar.Count -eq 0) {
+    Write-Host '[done] Health check only -- no hot-deploy (pass -Jar or -Module).'
+    exit 0
+}
+$jars = $Jar | ForEach-Object { (Resolve-Path $_).Path }
+foreach ($j in $jars) {
+    Write-Host "[jar] $j  ($([math]::Round((Get-Item $j).Length / 1KB)) KB)"
+}
+
+# ---- 6. Attach: save the jar bytes, then reload the ExtClassLoader ----
+$attArgs = @(
+    '-cp', "$toolsJar;$agent",
+    'kd.reloadjar.Attacher',
+    $targetPid, $agent,
+    ($jars -join ','),
+    $accountId, $tenantId
+)
+if ($LogFile) {
+    $dir = Split-Path $LogFile -Parent
+    if ($dir -and -not (Test-Path $dir)) { New-Item -ItemType Directory -Force -Path $dir | Out-Null }
+    $attArgs += (Join-Path (Resolve-Path $dir).Path (Split-Path $LogFile -Leaf))
+}
+
+& $java @attArgs
+if ($LASTEXITCODE -ne 0) { throw "Hot-deploy failed (exit $LASTEXITCODE)." }
+Write-Host '[done] Hot-deploy complete (SUCCESS = save + reset both applied).'

package/skills/cosmic-dev-best-practices/references/cosmic-hotdeploy-build-slow-windows.md

@@ -139,13 +139,25 @@ api fileTree(trd) {
 `<cwd>/.dsh/cosmic/config/dev.json`：
 
 ```json
-{ "java_home": "C:\\Program Files\\java\\jdk" }
+{ "java_home": "C:\\Program Files\\Java\\jdk1.8.0_281" }
 ```
 
-- 以 IDEA 项目 SDK 为准（本项目 = `C:\Program Files\java\jdk`，JDK 8，含 tools.jar）
-- Attacher 需与 cosmic 进程同 JDK **大版本**（JDK 8，具体小版本无关）
+- 以 IDEA 项目 SDK 为准（实测本机 = `C:\Program Files\Java\jdk1.8.0_281`，JDK 8，含 tools.jar）
+- Attacher 需与 cosmic 进程同 JDK **大版本**（JDK 8，具体小版本无关；cosmic 自带
+  `F:\cosmic\xinghan8\jdk` = 1.8.0_212，与本机 1.8.0_281 混用无碍）
 - `dev.py init` 自动发现不到时手动补；改后 `dev.py read` 验证
 
+> ⚠️ **必设 `JAVA_HOME`，否则 `compileJava` 必失败**（实测踩坑）：本机 Windows 注册表
+> `HKLM\SOFTWARE\JavaSoft\Java Development Kit` 的 `JavaHome` 被 8u481 安装包改写成
+> **JRE** 路径 `C:\Program Files\Java\jre1.8.0_481`。Gradle 在该值存在时优先采信它，
+> 于是 `java.home` 指向 JRE → 没有 `tools.jar` → 报
+> `Could not find tools.jar. Please check that ...\jre1.8.0_481 contains a valid JDK installation`。
+> 显式 `$env:JAVA_HOME="C:\Program Files\Java\jdk1.8.0_281"` 即解（实测全量编译 10s 通过）。
+>
+> 🔎 **同源陷阱：「伪成功构建」**。若 `compileJava` 处于 `UP-TO-DATE`，Gradle 根本不加载
+> 编译器，缺 tools.jar 也不报错 —— 你会看到 `BUILD SUCCESSFUL` + `jar` 正常产出，
+> **但 jar 里是旧字节码**。首次接入务必用 `clean build` 验证一次真编译（本次就是这么暴露的）。
+
 ### 4.4 验证 classpath 是否真的干净（临时 init script）
 
 `showcp.gradle`（用完可删）：
@@ -205,11 +217,19 @@ Get-ChildItem "<lib>" -Recurse -Filter *.jar | ForEach-Object {
 > 见 §0），须先单命令级放开 `danger-full-access`；`--no-daemon` 也救不了。
 
 ```powershell
-$env:JAVA_HOME = "C:\Program Files\java\jdk"
+$env:JAVA_HOME = "C:\Program Files\Java\jdk1.8.0_281"   # 必须：注册表 java.home 指向 JRE（见 §4.3）
 $gradle = "C:\Users\<user>\.gradle\wrapper\dists\gradle-7.6.3-bin\<hash>\gradle-7.6.3\bin\gradle.bat"
 & $gradle ":<模块>:build" -x test --console=plain
 ```
 
+> ⚠️ **Gradle 版本必须按 `gradle/wrapper/gradle-wrapper.properties` 锁定**，不要「取
+> `~/.gradle/wrapper/dists` 下最新」。本机同时存在 `gradle-8.8-bin`，它要求 Java 22
+> 运行时，与本项目 JDK 8 + tools.jar 链路不兼容，会直接把构建带偏。
+>
+> 🧩 本工作区已把整套流程封装为脚本：`runtime/cosmic-hotdeploy.ps1`
+> （体检 / `-Jar` 热加载 / `-Module` 构建+热加载 / `-Clean`），内置上述 JDK、Gradle
+> 版本、PID 发现、account/tenant 读取逻辑，可直接用。
+
 > ❌ 不要加 `--no-daemon`：每次 fork 单次 Daemon（JVM 冷启动 + 重新加载配置 ≈ +30s）
 > ✅ 复用常驻 Daemon（`org.gradle.daemon=true` 默认开启），改几行代码约 5-10 秒
 
@@ -314,6 +334,11 @@ for incremental compilation. See the debug log for more details.
 ### 6.1 发现 cosmic PID
 
 ```powershell
+# ⭐ 方式零（推荐）：按端口归属进程反查 + 命令行校验（实测最可靠）
+$conn = Get-NetTCPConnection -LocalPort <cosmic_port> -State Listen | Select-Object -First 1
+$cosmicPID = $conn.OwningProcess
+(Get-CimInstance Win32_Process -Filter "ProcessId=$cosmicPID").CommandLine   # 应含 kd.bos.service.webserver.JettyServer
+
 # 方式一：HTTP 探测端口（最可靠，权限问题兜底）
 Invoke-WebRequest http://127.0.0.1:<cosmic_port>/ierp   # HTTP 200 = cosmic 活着
 
@@ -355,6 +380,15 @@ $jar = "<模块>\build\libs\<模块>-1.0.0.jar"
    多次构建间隔短时用「最新时间戳 ±30s」窗口精确切分，避免混入前一次全量产物
 8. **`dependencies --configuration compileClasspath` 对 fileTree 是惰性展开**，不一定显示 jar 明细，
    要确认真实 classpath 必须用自定义任务打印 `sourceSets.main.compileClasspath.files`
+9. **`jps` 看不到 cosmic 进程**（实测）：本机 cosmic 由 **SYSTEM** 账户启动
+   （`F:\cosmic\xinghan8\jdk\bin\java ... -DappName=cosmic ... kd.bos.service.webserver.JettyServer`），
+   而 `jps` 只列举当前用户的 JVM → 输出里完全没有它，容易误判「cosmic 没启动」。
+   用 §6.1 方式零（按端口反查 OwningProcess）替代。
+10. **跨用户 attach 是可用的，无需提权**：cosmic 跑在 SYSTEM 下、Attacher 由
+   `lihaisheng\administrator` 启动，实测 attach 成功（Windows JVM attach 命名管道对
+   Administrators 组放行），不必 `Start-Process -Verb RunAs`。
+11. **`-XX:+DisableAttachMechanism` 是硬阻断**：本机 IDEA 侧另一个 JVM（`CosmicStudio-runnable.jar`）
+   带此参数，对它 attach 必然失败；发现 PID 后先扫命令行里有没有这个 flag。
 9. **`java_home` 以 IDEA 项目 SDK 为准**（Windows 常见 `C:\Program Files\java\jdk`），
    不要误填 cosmic 自带 JDK 目录；Attacher 只需与 cosmic 同 JDK 大版本（同为 JDK8 即兼容）
 10. **gradle 构建命令不要加 `--no-daemon`**；多 IDLE Daemon 并存无害，`--stop` 可一次性清理

package/skills/erp-analysis/scripts/init-python.ps1

@@ -47,3 +47,25 @@ Write-Host "==> 验证导入"
 uv run --python $VENV python -c "import pandas, numpy, plotly, jinja2, requests; print('OK', pandas.__version__, numpy.__version__, plotly.__version__, jinja2.__version__, 'requests', requests.__version__)"
 
 Write-Host "==> init-python 完成"
+
+# 顺带把热部署用的 agent jar 预复制到机器级缓存（与 venv 同理：**不要把会被外部进程独占
+# 加载的文件留在 preset 里**）。Attacher 会把这个 jar 载入运行中的 cosmic JVM，JVM 长期持有
+# 其句柄；preset 升级要整目录替换 → 会在这个 jar 上失败（Windows os error 32 / 拒绝访问）。
+# 文件名带内容哈希：新版不会覆盖可能已被 JVM 载入的旧副本。幂等。
+$AgentSrc = Join-Path $ROOT "skills\cosmic-build\skills\cosmic-vibe-coding\assets\kd-reloadjar-agent.jar"
+if (Test-Path $AgentSrc) {
+    $AgentDir = Join-Path $DshHome "cache\cosmic\agent"
+    $AgentHash = (Get-FileHash $AgentSrc -Algorithm SHA1).Hash.Substring(0, 8).ToLower()
+    $AgentDst = Join-Path $AgentDir "kd-reloadjar-agent-$AgentHash.jar"
+    if (-not (Test-Path $AgentDir)) { New-Item -ItemType Directory -Force -Path $AgentDir | Out-Null }
+    if (Test-Path $AgentDst) {
+        Write-Host "==> agent 缓存已存在: $AgentDst"
+    } else {
+        Copy-Item $AgentSrc $AgentDst -Force
+        Write-Host "==> agent 已缓存: $AgentDst"
+    }
+    # 只保留最近 5 份哈希副本（best-effort）
+    Get-ChildItem $AgentDir -Filter "kd-reloadjar-agent-*.jar" -ErrorAction SilentlyContinue |
+        Sort-Object LastWriteTime -Descending | Select-Object -Skip 5 |
+        Remove-Item -Force -ErrorAction SilentlyContinue
+}

package/skills/erp-analysis/scripts/init-python.sh

@@ -48,3 +48,22 @@ echo "==> 验证导入"
 uv run --python "$VENV" python -c 'import pandas, numpy, plotly, jinja2, requests; print("OK", pandas.__version__, numpy.__version__, plotly.__version__, jinja2.__version__, "requests", requests.__version__)'
 
 echo "==> init-python 完成"
+
+# 4) 顺带把热部署用的 agent jar 预复制到机器级缓存（与 venv 同理：**不要把会被外部进程
+#    独占加载的文件留在 preset 里**）。Attacher 会把这个 jar 载入运行中的 cosmic JVM，
+#    JVM 长期持有其句柄；preset 升级要整目录替换 → 会在这个 jar 上失败（Windows os error 32）。
+#    文件名带内容哈希：新版不会覆盖可能已被 JVM 载入的旧副本。幂等。
+AGENT_SRC="$ROOT/skills/cosmic-build/skills/cosmic-vibe-coding/assets/kd-reloadjar-agent.jar"
+if [ -f "$AGENT_SRC" ]; then
+  AGENT_DIR="$DSH_HOME/cache/cosmic/agent"
+  AGENT_HASH="$( (shasum -a 1 "$AGENT_SRC" 2>/dev/null || sha1sum "$AGENT_SRC") | cut -c1-8 )"
+  AGENT_DST="$AGENT_DIR/kd-reloadjar-agent-$AGENT_HASH.jar"
+  mkdir -p "$AGENT_DIR"
+  if [ -f "$AGENT_DST" ]; then
+    echo "==> agent 缓存已存在: $AGENT_DST"
+  else
+    cp "$AGENT_SRC" "$AGENT_DST" && echo "==> agent 已缓存: $AGENT_DST"
+  fi
+  # 只保留最近 5 份哈希副本（best-effort）
+  ls -1t "$AGENT_DIR"/kd-reloadjar-agent-*.jar 2>/dev/null | tail -n +6 | while read -r old; do rm -f "$old" 2>/dev/null || true; done
+fi