@coze-arch/cli 0.0.36-alpha.3ab612 → 0.0.36-alpha.4e6503

package/lib/__templates__/taro/.cozeproj/scripts/dev_run.sh

@@ -2,17 +2,12 @@
 echo "⚙️ dev_run.sh 开始运行"
 set -Eeuo pipefail
 
-ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
-COZE_WORKSPACE_PATH="${COZE_WORKSPACE_PATH:-${ROOT_DIR}}"
 cd "${COZE_WORKSPACE_PATH}"
 
 # ---------------------------------------------------------
-# 项目级日志目录
+# PID 文件，用于追踪上一次启动的进程树
 # ---------------------------------------------------------
-LOG_DIR="${COZE_WORKSPACE_PATH}/logs"
-LOG_FILE="${LOG_DIR}/dev.log"
-PID_FILE="${LOG_DIR}/dev.pid"
-DEV_PID=""
+PID_FILE="/tmp/coze-dev-run.pid"
 
 # ---------------------------------------------------------
 # 工具函数
@@ -30,165 +25,99 @@ kill_process_tree() {
     fi
 }
 
-# coze-daemon 会在 runtime shell 退出时清理原进程组。
-# 通过 Node detached spawn 创建独立 session/进程组，并将 stdio 直接写入日志。
-spawn_detached() {
-    local cwd="$1"
-    local log_file="$2"
-    shift 2
-
-    node - "$cwd" "$log_file" "$@" <<'NODE'
-const fs = require('node:fs');
-const { spawn } = require('node:child_process');
-
-const [cwd, logFile, command, ...args] = process.argv.slice(2);
-if (!cwd || !logFile || !command) {
-  throw new Error('spawn_detached 缺少 cwd、log_file 或 command');
-}
-
-const logFd = fs.openSync(logFile, 'a');
-try {
-  const child = spawn(command, args, {
-    cwd,
-    detached: true,
-    env: process.env,
-    stdio: ['ignore', logFd, logFd],
-  });
-  child.unref();
-  process.stdout.write(String(child.pid));
-} finally {
-  fs.closeSync(logFd);
-}
-NODE
-}
-
-stop_detached() {
-    local pid="${1:-}"
-    if [[ -z "${pid}" ]]; then
-        return
-    fi
-
-    kill -TERM -- "-${pid}" 2>/dev/null || kill -TERM "${pid}" 2>/dev/null || true
-    sleep 1
-    kill -KILL -- "-${pid}" 2>/dev/null || true
-}
-
-process_belongs_to_workspace() {
-    local pid=$1
-    local cwd=""
-
-    if [[ -L "/proc/${pid}/cwd" ]]; then
-        cwd=$(readlink "/proc/${pid}/cwd" 2>/dev/null || true)
-    elif command -v lsof >/dev/null 2>&1; then
-        cwd=$(lsof -a -p "${pid}" -d cwd -Fn 2>/dev/null | sed -n 's/^n//p' | head -1)
-    fi
-
-    case "${cwd}" in
-        "${COZE_WORKSPACE_PATH}"|"${COZE_WORKSPACE_PATH}"/*) return 0 ;;
-        *) return 1 ;;
-    esac
-}
-
-process_group_belongs_to_workspace() {
-    local pgid=$1
-    local pids
-    local found=0
-
-    pids=$(ps -axo pid=,pgid= 2>/dev/null | awk -v pgid="${pgid}" '$2 == pgid {print $1}')
-    for pid in ${pids}; do
-        found=1
-        if ! process_belongs_to_workspace "${pid}"; then
-            return 1
-        fi
-    done
-
-    [[ "${found}" -eq 1 ]]
-}
-
-# 优先用 ss，无结果或缺少 ss 时回落到 lsof；两者都不可用则显式告警，避免静默误判为端口空闲
-list_port_pids() {
-    local port=$1
-    local pids=""
-    local has_tool=0
-
-    if command -v ss >/dev/null 2>&1; then
-        has_tool=1
-        pids=$(ss -H -lntp 2>/dev/null | awk -v port="${port}" '$4 ~ ":"port"$"' | grep -o 'pid=[0-9]*' | cut -d= -f2 | sort -u | paste -sd' ' - || true)
-    fi
-    if [[ -z "${pids}" ]] && command -v lsof >/dev/null 2>&1; then
-        has_tool=1
-        pids=$(lsof -t -iTCP:"${port}" -sTCP:LISTEN 2>/dev/null | sort -u | paste -sd' ' - || true)
-    fi
-    if [[ "${has_tool}" -eq 0 ]]; then
-        echo "Warning: neither ss nor lsof available, cannot inspect port ${port}." >&2
-    fi
-
-    echo "${pids}"
-}
-
 kill_port_if_listening() {
     local port=$1
     local pids
-    pids=$(list_port_pids "${port}")
+    pids=$(ss -H -lntp 2>/dev/null | awk -v port="${port}" '$4 ~ ":"port"$"' | grep -o 'pid=[0-9]*' | cut -d= -f2 | sort -u | paste -sd' ' - || true)
     if [[ -z "${pids}" ]]; then
         echo "Port ${port} is free."
         return
     fi
-    echo "Port ${port} in use by PIDs: ${pids} (SIGKILL)"
+    echo "Port ${port} in use by PIDs: ${pids}"
     for pid in ${pids}; do
         kill_process_tree "${pid}"
     done
     sleep 1
-    pids=$(list_port_pids "${port}")
+    pids=$(ss -H -lntp 2>/dev/null | awk -v port="${port}" '$4 ~ ":"port"$"' | grep -o 'pid=[0-9]*' | cut -d= -f2 | sort -u | paste -sd' ' - || true)
     if [[ -n "${pids}" ]]; then
-        echo "Warning: port ${port} still busy after SIGKILL, PIDs: ${pids}"
+        echo "Warning: port ${port} still busy after cleanup, PIDs: ${pids}"
     else
         echo "Port ${port} cleared."
     fi
 }
 
-# 只清理当前项目上次记录的 detached 进程。
+# ---------------------------------------------------------
+# 1. 清理上一次运行残留的整棵进程树
+# ---------------------------------------------------------
 cleanup_previous_run() {
-    if [[ ! -f "${PID_FILE}" ]]; then
-        return
+    # 1a. 通过 PID 文件清理上次的进程树
+    if [[ -f "${PID_FILE}" ]]; then
+        local old_pid
+        old_pid=$(cat "${PID_FILE}" 2>/dev/null || true)
+        if [[ -n "${old_pid}" ]] && kill -0 "${old_pid}" 2>/dev/null; then
+            echo "🧹 Killing previous dev process tree (root PID: ${old_pid})..."
+            kill_process_tree "${old_pid}"
+        fi
+        rm -f "${PID_FILE}"
     fi
 
-    local old_pid
-    old_pid=$(cat "${PID_FILE}" 2>/dev/null || true)
-    if [[ "${old_pid}" =~ ^[1-9][0-9]*$ ]] && process_group_belongs_to_workspace "${old_pid}"; then
-        echo "🧹 Killing previous dev process group (PGID: ${old_pid})..."
-        stop_detached "${old_pid}"
-    fi
-    rm -f "${PID_FILE}"
+    # 1b. 兜底：按特征匹配清理所有残留的相关进程（排除自身）
+    echo "🧹 Cleaning up any orphaned dev processes..."
+    local patterns=(
+        "pnpm dev"
+        "concurrently.*dev:web.*dev:server"
+        "nest start --watch"
+        "taro build --type h5 --watch"
+        "node --enable-source-maps.*/workspace/projects/server/dist/main"
+        "esbuild --service.*--ping"
+    )
+    for pattern in "${patterns[@]}"; do
+        local pids
+        pids=$(pgrep -f "${pattern}" 2>/dev/null || true)
+        for pid in ${pids}; do
+            # 不杀自己和自己的父进程链
+            if [[ "${pid}" != "$$" ]] && [[ "${pid}" != "${PPID}" ]]; then
+                echo "  Killing orphan PID ${pid} matching '${pattern}'"
+                kill -9 "${pid}" 2>/dev/null || true
+            fi
+        done
+    done
+    sleep 1
 }
 
 # ---------------------------------------------------------
 # 2. 安装依赖
 # ---------------------------------------------------------
 echo "📦 Installing dependencies..."
-PNPM_BIN="$(command -v pnpm)"
-"${PNPM_BIN}" install
+pnpm install
 echo "✅ Dependencies installed successfully!"
 
 # ---------------------------------------------------------
 # 3. 清理旧进程 + 端口
 # ---------------------------------------------------------
-# DEPLOY_RUN_PORT 是平台注入的对外端口，项目内统一使用 PORT。
-PORT="${DEPLOY_RUN_PORT:-${PORT:-<%= port %>}}"
-SERVER_PORT="${SERVER_PORT:-<%= serverPort %>}"
-export PORT
-export SERVER_PORT
+SERVER_PORT=3000
 
-mkdir -p "${LOG_DIR}"
 cleanup_previous_run
 
-echo "Clearing port ${PORT} (web) before start."
-kill_port_if_listening "${PORT}"
+echo "Clearing port ${DEPLOY_RUN_PORT} (web) before start."
+kill_port_if_listening "${DEPLOY_RUN_PORT}"
 echo "Clearing port ${SERVER_PORT} (server) before start."
 kill_port_if_listening "${SERVER_PORT}"
 
 # ---------------------------------------------------------
-# 4. 启动服务
+# 4. 退出时自动清理子进程（信号 trap）
+# ---------------------------------------------------------
+cleanup_on_exit() {
+    echo "🛑 dev_run.sh exiting, cleaning up child processes..."
+    # 杀掉当前脚本的所有子进程
+    kill -- -$$ 2>/dev/null || true
+    rm -f "${PID_FILE}"
+    exit 0
+}
+trap cleanup_on_exit EXIT INT TERM HUP
+
+# ---------------------------------------------------------
+# 5. 启动服务
 # ---------------------------------------------------------
 start_service() {
     cd "${COZE_WORKSPACE_PATH}"
@@ -204,30 +133,19 @@ start_service() {
     # 启动 Taro H5 和 NestJS Server
     echo "Starting Taro H5 Dev Server and NestJS Server..."
 
-    : > "${LOG_FILE}"
-
-    DEV_PID="$(spawn_detached \
-        "${COZE_WORKSPACE_PATH}" \
-        "${LOG_FILE}" \
-        "${PNPM_BIN}" dev)"
-    if [[ -z "${DEV_PID}" ]]; then
-        echo "❌ 无法获取 dev 后台进程 PID"
-        return 1
-    fi
-    echo "${DEV_PID}" > "${PID_FILE}"
+    export PORT=${DEPLOY_RUN_PORT}
+    rm -f /tmp/coze-logs/dev.log
+    mkdir -p /tmp/coze-logs
 
-    sleep 1
-    if ! kill -0 "${DEV_PID}" 2>/dev/null; then
-        echo "❌ Dev service failed to start. See ${LOG_FILE}." >&2
-        tail -n 20 "${LOG_FILE}" >&2 || true
-        rm -f "${PID_FILE}"
-        return 1
-    fi
+    # 后台启动并记录 PID
+    pnpm dev 2>&1 | tee /tmp/coze-logs/dev.log &
+    local dev_pid=$!
+    echo "${dev_pid}" > "${PID_FILE}"
+    echo "📝 Dev process started with PID: ${dev_pid} (saved to ${PID_FILE})"
 
-    echo "📝 Dev process started with PID: ${DEV_PID}"
-    echo "Log file: ${LOG_FILE}"
-    echo "PID file: ${PID_FILE}"
+    # 前台等待，保证 trap 能正常捕获信号
+    wait "${dev_pid}" || true
 }
 
-echo "Starting HTTP services on port ${PORT} (web) and ${SERVER_PORT} (server)..."
+echo "Starting HTTP services on port ${DEPLOY_RUN_PORT} (web) and ${SERVER_PORT} (server)..."
 start_service

package/lib/__templates__/taro/AGENTS.md

@@ -361,24 +361,20 @@ if (isExternalUrl) {
 
 **工作原理**：
 
-1. **开发环境（H5）**：使用 `/api/xxx` 相对路径，Vite 的 proxy 会自动将其代理到后端；后端端口读取 `SERVER_PORT`，未设置时使用模板默认端口 `<%= serverPort %>`
+1. **开发环境（H5）**：使用 `/api/xxx` 相对路径，Vite 的 proxy 会自动将其代理到 `http://localhost:3000/api/xxx`
 2. **生产环境**：如果配置了 `PROJECT_DOMAIN` 环境变量，Network 会自动拼接为 `${PROJECT_DOMAIN}/api/xxx`
 3. **小程序端**：同样会根据 `PROJECT_DOMAIN` 配置使用正确的域名
 
 **Vite 代理配置**（已在项目中配置，无需修改）：
 
 ```typescript
-// config/index.ts
-const serverPort = Number(process.env.SERVER_PORT) || <%= serverPort %>
-
+// vite.config.ts
 export default {
-  h5: {
-    devServer: {
-      proxy: {
-        '/api': {
-          target: `http://localhost:${serverPort}`,
-          changeOrigin: true
-        }
+  server: {
+    proxy: {
+      '/api': {
+        target: 'http://localhost:3000',
+        changeOrigin: true
       }
     }
   }

package/lib/__templates__/taro/README.md

@@ -63,8 +63,8 @@ pnpm install
 pnpm dev
 ```
 
-- 前端地址：http://localhost:<%= port %>
-- 后端地址：http://localhost:<%= serverPort %>
+- 前端地址：http://localhost:5000
+- 后端地址：http://localhost:3000
 
 单独启动：
 
@@ -560,7 +560,7 @@ async function getLocation(): Promise<Taro.getLocation.SuccessCallbackResult> {
 ### 开发命令
 
 ```sh
-pnpm dev:server // 启动开发服务 (热重载, 默认端口 <%= serverPort %>，可用 SERVER_PORT 环境变量覆盖)
+pnpm dev:server // 启动开发服务 (热重载, 默认端口 3000)
 pnpm build:server // 构建生产版本
 ```
 
@@ -586,7 +586,7 @@ npx nest g service modules/order
 
 ```sh
 ## 服务端口
-SERVER_PORT=<%= serverPort %>
+PORT=3000
 
 ## 微信小程序配置
 WX_APP_ID=你的AppID

package/lib/__templates__/taro/config/index.ts

@@ -12,14 +12,6 @@ import pkg from '../package.json';
 
 dotenv.config({ path: path.resolve(__dirname, '../.env.local') });
 
-const resolvePort = (value: string | undefined, fallback: number): number => {
-  const port = Number(value);
-  return Number.isInteger(port) && port > 0 && port < 65536 ? port : fallback;
-};
-
-const h5Port = resolvePort(process.env.PORT, <%= port %>);
-const serverPort = resolvePort(process.env.SERVER_PORT, <%= serverPort %>);
-
 const generateTTProjectConfig = (outputRoot: string) => {
   const config = {
     miniprogramRoot: './',
@@ -190,12 +182,12 @@ export default defineConfig<'vite'>(async (merge, _env) => {
         mode: 'hash',
       },
       devServer: {
-        port: h5Port,
+        port: <%= port %>,
         host: '0.0.0.0',
         open: false,
         proxy: {
           '/api': {
-            target: `http://localhost:${serverPort}`,
+            target: 'http://localhost:<%= serverPort %>',
             changeOrigin: true,
           },
         },

package/lib/__templates__/taro/pnpm-lock.yaml

@@ -204,8 +204,8 @@ importers:
         specifier: 2.95.3
         version: 2.95.3
       coze-coding-dev-sdk:
-        specifier: ^0.7.25-beta.8
-        version: 0.7.25-beta.8(openai@6.16.0(ws@8.19.0)(zod@4.3.5))(ws@8.19.0)
+        specifier: ^0.7.24
+        version: 0.7.24(openai@6.16.0(ws@8.19.0)(zod@4.3.5))(ws@8.19.0)
       dotenv:
         specifier: ^17.2.3
         version: 17.2.3
@@ -5416,8 +5416,8 @@ packages:
       typescript:
         optional: true
 
-  coze-coding-dev-sdk@0.7.25-beta.8:
-    resolution: {integrity: sha512-RSKlXCO0W/OPDjx9D9JICn2cGeOJw3iG+y0Pr1AhAf7YdAjjNbBZoG7qfg0Zg2SqgaVN2qSLQFmKPbhNq9ZWSg==}
+  coze-coding-dev-sdk@0.7.24:
+    resolution: {integrity: sha512-oL9Tg5PwxP6iMixonzzMO4aBjOKWcFUMVM+iz5dPyaqQkG84HP1y9DqK5DJVmtdfJuYdAW7pzOatDqLvgvZiXg==}
     engines: {node: '>=18.0.0'}
     hasBin: true
 
@@ -17159,7 +17159,7 @@ snapshots:
     optionalDependencies:
       typescript: 5.9.3
 
-  coze-coding-dev-sdk@0.7.25-beta.8(openai@6.16.0(ws@8.19.0)(zod@4.3.5))(ws@8.19.0):
+  coze-coding-dev-sdk@0.7.24(openai@6.16.0(ws@8.19.0)(zod@4.3.5))(ws@8.19.0):
     dependencies:
       '@langchain/core': 1.1.16(openai@6.16.0(ws@8.19.0)(zod@4.3.5))
       '@langchain/openai': 1.2.3(@langchain/core@1.1.16(openai@6.16.0(ws@8.19.0)(zod@4.3.5)))(ws@8.19.0)

package/lib/__templates__/taro/server/package.json

@@ -17,7 +17,7 @@
     "@nestjs/core": "^10.4.15",
     "@nestjs/platform-express": "^10.4.15",
     "@supabase/supabase-js": "2.95.3",
-    "coze-coding-dev-sdk": "^0.7.25-beta.8",
+    "coze-coding-dev-sdk": "^0.7.24",
     "dotenv": "^17.2.3",
     "drizzle-kit": "^0.31.8",
     "drizzle-orm": "^0.45.1",

package/lib/__templates__/taro/server/src/main.ts

@@ -12,12 +12,6 @@ function parsePort(): number {
       return port;
     }
   }
-
-  const envPort = parseInt(process.env.SERVER_PORT || '', 10);
-  if (!isNaN(envPort) && envPort > 0 && envPort < 65536) {
-    return envPort;
-  }
-
   return <%= serverPort %>;
 }
 
@@ -44,12 +38,12 @@ async function bootstrap() {
     console.log(`Server running on http://localhost:${port}`);
   } catch (err) {
     if (err.code === 'EADDRINUSE') {
-      console.error(`❌ 端口 ${port} 被占用，请设置其他 SERVER_PORT 后重试。`);
+      console.error(`❌ 端口 \({port} 被占用! 请运行 'npx kill-port \){port}' 然后重试。`);
       process.exit(1);
     } else {
       throw err;
     }
   }
-  console.log(`Application is running on: http://localhost:${port}`);
+  console.log(`Application is running on: http://localhost:<%= serverPort %>`);
 }
 bootstrap();

package/lib/__templates__/templates.json

@@ -16,17 +16,10 @@
           },
           "port": {
             "type": "number",
-            "default": 5000,
+            "default": 8081,
             "minimum": 1024,
             "maximum": 65535,
             "description": "Metro bundler port"
-          },
-          "serverPort": {
-            "type": "number",
-            "default": 9091,
-            "minimum": 1024,
-            "maximum": 65535,
-            "description": "Express backend server port"
           }
         },
         "required": [],
@@ -101,49 +94,6 @@
         "additionalProperties": false
       }
     },
-    {
-      "name": "phaser",
-      "description": "Phaser（2D 游戏）：`coze-dev init ${COZE_WORKSPACE_PATH} --template phaser`\n- 适用：基于 Phaser 3、Vite 和 TypeScript 的 2D Web 游戏。",
-      "location": "./phaser",
-      "paramsSchema": {
-        "type": "object",
-        "properties": {
-          "appName": {
-            "type": "string",
-            "minLength": 1,
-            "pattern": "^[a-z0-9-]+$",
-            "description": "Application name (lowercase, alphanumeric and hyphens only)"
-          },
-          "port": {
-            "type": "number",
-            "default": 5000,
-            "minimum": 1024,
-            "maximum": 65535,
-            "description": "Development and preview server port"
-          }
-        },
-        "required": [],
-        "additionalProperties": false
-      }
-    },
-    {
-      "name": "phaser-static",
-      "description": "Phaser Static（纯静态 2D 游戏）：coze-dev init ${COZE_WORKSPACE_PATH} --template phaser-static\n- 适用：浏览器原生 JavaScript ESM 的 Phaser 3 游戏。\n- Phaser 与 Phaser Bridge 从 CDN 加载；无需 npm、Vite 或 TypeScript。",
-      "location": "./phaser-static",
-      "paramsSchema": {
-        "type": "object",
-        "properties": {
-          "appName": {
-            "type": "string",
-            "minLength": 1,
-            "pattern": "^[a-z0-9-]+$",
-            "description": "Application name (lowercase, alphanumeric and hyphens only)"
-          }
-        },
-        "required": [],
-        "additionalProperties": false
-      }
-    },
     {
       "name": "pi-agent",
       "description": "Pi Agent：`coze-dev init ${COZE_WORKSPACE_PATH} --template pi-agent`\n- 适用：基于 pi-agent-core 的 AI Agent 应用\n- 支持飞书、微信等多渠道接入\n- 内置 Dashboard 管理面板\n- 使用 TypeScript + Express + Vite",

package/lib/__templates__/vite/package.json

@@ -22,7 +22,7 @@
     "@types/express": "^5.0.0",
     "@types/node": "^22.10.5",
     "autoprefixer": "^10.4.20",
-    "coze-coding-dev-sdk": "^0.7.25-beta.8",
+    "coze-coding-dev-sdk": "^0.7.16",
     "esbuild": "^0.24.2",
     "eslint": "^9",
     "eslint-plugin-import": "^2.32.0",

package/lib/__templates__/vite/pnpm-lock.yaml

@@ -32,8 +32,8 @@ importers:
         specifier: ^10.4.20
         version: 10.4.23(postcss@8.5.6)
       coze-coding-dev-sdk:
-        specifier: ^0.7.25-beta.8
-        version: 0.7.25-beta.8(openai@6.16.0(ws@8.19.0)(zod@4.3.5))(ws@8.19.0)
+        specifier: ^0.7.16
+        version: 0.7.16(openai@6.16.0(ws@8.19.0)(zod@4.3.5))(ws@8.19.0)
       esbuild:
         specifier: ^0.27.2
         version: 0.27.2
@@ -910,8 +910,8 @@ packages:
       typescript:
         optional: true
 
-  coze-coding-dev-sdk@0.7.25-beta.8:
-    resolution: {integrity: sha512-RSKlXCO0W/OPDjx9D9JICn2cGeOJw3iG+y0Pr1AhAf7YdAjjNbBZoG7qfg0Zg2SqgaVN2qSLQFmKPbhNq9ZWSg==}
+  coze-coding-dev-sdk@0.7.16:
+    resolution: {integrity: sha512-B7gRPBa+sfrZL8ur0+F/92SOgZgFaWD/fOnCN2DjthnHSdmCYhAJWCfqzG2oO2vwTiYCXkKUuTBZ3MJLMj886g==}
     engines: {node: '>=18.0.0'}
     hasBin: true
 
@@ -3281,7 +3281,7 @@ snapshots:
     optionalDependencies:
       typescript: 5.9.3
 
-  coze-coding-dev-sdk@0.7.25-beta.8(openai@6.16.0(ws@8.19.0)(zod@4.3.5))(ws@8.19.0):
+  coze-coding-dev-sdk@0.7.16(openai@6.16.0(ws@8.19.0)(zod@4.3.5))(ws@8.19.0):
     dependencies:
       '@langchain/core': 1.1.16(openai@6.16.0(ws@8.19.0)(zod@4.3.5))
       '@langchain/openai': 1.2.3(@langchain/core@1.1.16(openai@6.16.0(ws@8.19.0)(zod@4.3.5)))(ws@8.19.0)

package/lib/__templates__/vite/scripts/build.ps1

@@ -4,7 +4,7 @@ $workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (
 Set-Location $workspace
 
 Write-Host "Installing dependencies..."
-& pnpm install --prefer-frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
+& pnpm install --frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
 if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 
 Write-Host "Building frontend with Vite..."

package/lib/__templates__/vite/scripts/dev.ps1

@@ -7,9 +7,9 @@ function Get-WorkspacePath {
   return (Get-Location).Path
 }
 
-function Stop-ProcessTree([int] $processId) {
-  if ($processId -gt 0 -and (Get-Process -Id $processId -ErrorAction SilentlyContinue)) {
-    & taskkill.exe /PID $processId /T /F *> $null
+function Stop-ProcessTree([int] $targetProcessId) {
+  if ($targetProcessId -gt 0 -and (Get-Process -Id $targetProcessId -ErrorAction SilentlyContinue)) {
+    & taskkill.exe /PID $targetProcessId /T /F *> $null
   }
 }
 
@@ -20,11 +20,40 @@ function Stop-ListeningProcess([int] $port) {
   }
 }
 
+function Test-PortListening([int] $port) {
+  return $null -ne (Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue | Select-Object -First 1)
+}
+
+function Wait-PortState([int] $port, [bool] $listening, [int] $timeoutSeconds) {
+  $deadline = (Get-Date).AddSeconds($timeoutSeconds)
+  do {
+    if ((Test-PortListening $port) -eq $listening) {
+      return $true
+    }
+    Start-Sleep -Milliseconds 250
+  } while ((Get-Date) -lt $deadline)
+  return $false
+}
+
+function Get-Port {
+  $rawPort = if ($env:DEPLOY_RUN_PORT) { $env:DEPLOY_RUN_PORT } elseif ($env:PORT) { $env:PORT } else { "<%= port %>" }
+  $parsedPort = 0
+  if (-not [int]::TryParse($rawPort, [ref] $parsedPort) -or $parsedPort -lt 1 -or $parsedPort -gt 65535) {
+    throw "Invalid port '$rawPort'. Expected an integer between 1 and 65535."
+  }
+  return $parsedPort
+}
+
 $workspace = Get-WorkspacePath
-$defaultPort = <%= port %>
-$port = if ($env:DEPLOY_RUN_PORT) { [int] $env:DEPLOY_RUN_PORT } elseif ($env:PORT) { [int] $env:PORT } else { $defaultPort }
+if (-not (Test-Path -LiteralPath $workspace -PathType Container)) {
+  throw "Workspace directory does not exist: $workspace"
+}
+$port = Get-Port
 Set-Location $workspace
 Stop-ListeningProcess $port
+if (-not (Wait-PortState $port $false 10)) {
+  throw "Port $port is still in use after stopping the previous process."
+}
 
 <% if (process.env.NODE_ENV === 'test') { %>
 $env:PORT = "$port"
@@ -38,7 +67,10 @@ $pidFile = Join-Path $logDirectory "server.pid"
 New-Item -ItemType Directory -Force -Path $logDirectory | Out-Null
 
 if (Test-Path $pidFile) {
-  Stop-ProcessTree ([int] (Get-Content $pidFile -Raw))
+  $previousPid = 0
+  if ([int]::TryParse((Get-Content $pidFile -Raw).Trim(), [ref] $previousPid)) {
+    Stop-ProcessTree $previousPid
+  }
   Remove-Item $pidFile -Force
 }
 
@@ -51,13 +83,37 @@ try {
 }
 
 $process.Id | Set-Content $pidFile
-Start-Sleep -Seconds 1
-if ($process.HasExited) {
+$processStartTime = $process.StartTime.ToUniversalTime().Ticks
+if (-not (Wait-PortState $port $true 30)) {
   Get-Content $errorLogFile -Tail 20 -ErrorAction SilentlyContinue
+  Stop-ProcessTree $process.Id
   Remove-Item $pidFile -Force -ErrorAction SilentlyContinue
-  exit 1
+  throw "Dev server did not listen on port $port within 30 seconds."
+}
+
+# 后台服务最长运行 20 分钟。回收前校验启动时间，避免 PID 复用后误杀无关进程。
+$pidFileBase64 = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($pidFile))
+$watchdogScript = @'
+$targetProcessId = __PROCESS_ID__
+$expectedStartTime = __START_TIME__
+$pidFile = [Text.Encoding]::Unicode.GetString([Convert]::FromBase64String('__PID_FILE__'))
+Start-Sleep -Seconds 1200
+$target = Get-Process -Id $targetProcessId -ErrorAction SilentlyContinue
+if ($target -and $target.StartTime.ToUniversalTime().Ticks -eq $expectedStartTime) {
+  & taskkill.exe /PID $targetProcessId /T /F *> $null
+}
+$recordedPid = 0
+if ((Test-Path -LiteralPath $pidFile) -and [int]::TryParse((Get-Content -LiteralPath $pidFile -Raw).Trim(), [ref] $recordedPid) -and $recordedPid -eq $targetProcessId) {
+  Remove-Item -LiteralPath $pidFile -Force -ErrorAction SilentlyContinue
 }
+'@
+$watchdogScript = $watchdogScript.Replace('__PROCESS_ID__', "$($process.Id)").Replace('__START_TIME__', "$processStartTime").Replace('__PID_FILE__', $pidFileBase64)
+$encodedWatchdog = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($watchdogScript))
+Start-Process -FilePath "powershell.exe" -WindowStyle Hidden -ArgumentList @(
+  "-NoProfile", "-ExecutionPolicy", "Bypass", "-EncodedCommand", $encodedWatchdog
+) | Out-Null
 
 Write-Host "Dev server started (PID: $($process.Id))."
+Write-Host "Auto stop after 1200 seconds."
 Write-Host "Log file: $logFile"
 <% } %>