@coze-arch/cli 0.0.37 → 0.1.2

package/lib/__templates__/phaser-static/src/utils/asset-loader.js

@@ -0,0 +1,267 @@
+import { AUDIOS, IMAGES, IMAGE_SEQUENCES, VIDEOS } from '../assets.js';
+
+const FRAME_KEY_MARKER = ':frame:';
+const MANIFEST_KEY_SUFFIX = ':manifest';
+
+const getFrameKey = (assetKey, frameIndex) =>
+  assetKey +
+  FRAME_KEY_MARKER +
+  String(frameIndex + 1).padStart(4, '0');
+
+const getManifestKey = assetKey => assetKey + MANIFEST_KEY_SUFFIX;
+
+const getFrameSource = (directory, frameIndex) =>
+  directory + '/frame_' + String(frameIndex + 1).padStart(4, '0') + '.png';
+
+export const resolveAssetUrl = source => new URL(source, document.baseURI).href;
+
+const isImageSequenceManifest = value => {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  return (
+    value.type === 'image_sequence' &&
+    typeof value.name === 'string' &&
+    typeof value.properties?.fps === 'number' &&
+    typeof value.properties.frame_count === 'number' &&
+    value.properties.frame_count > 0
+  );
+};
+
+const getImageSequenceManifest = (scene, assetKey) => {
+  const manifest = scene.cache.json.get(getManifestKey(assetKey));
+  if (!isImageSequenceManifest(manifest)) {
+    throw new Error('Invalid image sequence manifest: ' + assetKey);
+  }
+
+  return manifest;
+};
+
+const queueImageSequenceFrames = (scene, assetKey, directory, manifest) => {
+  Array.from(
+    { length: manifest.properties.frame_count },
+    (_value, frameIndex) => {
+      scene.load.image(
+        getFrameKey(assetKey, frameIndex),
+        resolveAssetUrl(getFrameSource(directory, frameIndex)),
+      );
+    },
+  );
+};
+
+const queueImages = (scene, images) => {
+  Object.entries(images).forEach(([assetKey, source]) => {
+    scene.load.image(assetKey, resolveAssetUrl(source));
+  });
+  return Object.keys(images).length;
+};
+
+const queueVideos = (scene, videos) => {
+  Object.entries(videos).forEach(([assetKey, source]) => {
+    scene.load.video(assetKey, resolveAssetUrl(source));
+  });
+  return Object.keys(videos).length;
+};
+
+const queueAudios = (scene, audios) => {
+  Object.entries(audios).forEach(([assetKey, source]) => {
+    scene.load.audio(assetKey, resolveAssetUrl(source));
+  });
+  return Object.keys(audios).length;
+};
+
+const queueImageSequences = (scene, imageSequences) =>
+  Object.entries(imageSequences).reduce(
+    (fileCount, [assetKey, directory]) => {
+      const manifestKey = getManifestKey(assetKey);
+      const cachedManifest = scene.cache.json.get(manifestKey);
+
+      if (isImageSequenceManifest(cachedManifest)) {
+        queueImageSequenceFrames(scene, assetKey, directory, cachedManifest);
+        return fileCount + cachedManifest.properties.frame_count;
+      }
+
+      scene.load.once(
+        'filecomplete-json-' + manifestKey,
+        (_key, _type, data) => {
+          if (!isImageSequenceManifest(data)) {
+            throw new Error('Invalid image sequence manifest: ' + assetKey);
+          }
+
+          queueImageSequenceFrames(scene, assetKey, directory, data);
+        },
+      );
+
+      scene.load.json(
+        manifestKey,
+        resolveAssetUrl(directory + '/manifest.json'),
+      );
+      return fileCount + 1;
+    },
+    0,
+  );
+
+export const loadAssets = (scene, collections) =>
+  queueImages(scene, collections.images ?? {}) +
+  queueImageSequences(scene, collections.imageSequences ?? {}) +
+  queueVideos(scene, collections.videos ?? {}) +
+  queueAudios(scene, collections.audios ?? {});
+
+export const getImageSequenceRuntimeKeys = assetKey => ({
+  texture: getFrameKey(assetKey, 0),
+  animation: assetKey + ':animation',
+});
+
+export const getAssetKeyFromFileKey = fileKey =>
+  fileKey.split(FRAME_KEY_MARKER)[0]?.replace(MANIFEST_KEY_SUFFIX, '') ??
+  fileKey;
+
+export const getAssetLabelFromFileKey = (fileKey, collections) => {
+  const assetKey = getAssetKeyFromFileKey(fileKey);
+
+  if (assetKey in (collections.images ?? {})) {
+    return '图片 ' + assetKey;
+  }
+  if (assetKey in (collections.imageSequences ?? {})) {
+    return '帧动画 ' + assetKey;
+  }
+  if (assetKey in (collections.videos ?? {})) {
+    return '视频 ' + assetKey;
+  }
+  if (assetKey in (collections.audios ?? {})) {
+    return '音频 ' + assetKey;
+  }
+
+  return assetKey;
+};
+
+export const registerImageSequenceAnimations = (scene, imageSequences) => {
+  Object.keys(imageSequences).forEach(assetKey => {
+    const manifest = getImageSequenceManifest(scene, assetKey);
+    const animationKey = getImageSequenceRuntimeKeys(assetKey).animation;
+    if (scene.anims.exists(animationKey)) {
+      return;
+    }
+
+    scene.anims.create({
+      key: animationKey,
+      frames: Array.from(
+        { length: manifest.properties.frame_count },
+        (_value, frameIndex) => ({ key: getFrameKey(assetKey, frameIndex) }),
+      ),
+      frameRate: manifest.properties.fps,
+      repeat: -1,
+    });
+  });
+};
+
+const findAsset = assetKey => {
+  const matches = [];
+
+  if (Object.hasOwn(IMAGES, assetKey)) {
+    matches.push({
+      collections: { images: { [assetKey]: IMAGES[assetKey] } },
+      loadedAsset: { kind: 'image', key: assetKey },
+    });
+  }
+  if (Object.hasOwn(IMAGE_SEQUENCES, assetKey)) {
+    matches.push({
+      collections: {
+        imageSequences: { [assetKey]: IMAGE_SEQUENCES[assetKey] },
+      },
+      loadedAsset: {
+        kind: 'image-sequence',
+        key: assetKey,
+        ...getImageSequenceRuntimeKeys(assetKey),
+      },
+    });
+  }
+  if (Object.hasOwn(VIDEOS, assetKey)) {
+    matches.push({
+      collections: { videos: { [assetKey]: VIDEOS[assetKey] } },
+      loadedAsset: { kind: 'video', key: assetKey },
+    });
+  }
+  if (Object.hasOwn(AUDIOS, assetKey)) {
+    matches.push({
+      collections: { audios: { [assetKey]: AUDIOS[assetKey] } },
+      loadedAsset: { kind: 'audio', key: assetKey },
+    });
+  }
+
+  if (matches.length === 0) {
+    throw new Error('Asset not found: ' + assetKey);
+  }
+  if (matches.length > 1) {
+    throw new Error('Duplicate asset key: ' + assetKey);
+  }
+
+  return matches[0];
+};
+
+const isAssetLoaded = (scene, loadedAsset) => {
+  switch (loadedAsset.kind) {
+    case 'image':
+      return scene.textures.exists(loadedAsset.key);
+    case 'image-sequence':
+      return scene.anims.exists(loadedAsset.animation);
+    case 'video':
+      return scene.cache.video.exists(loadedAsset.key);
+    case 'audio':
+      return scene.cache.audio.exists(loadedAsset.key);
+    default:
+      return false;
+  }
+};
+
+export const loadAsset = async (scene, assetKey) => {
+  const { collections, loadedAsset } = findAsset(assetKey);
+  if (isAssetLoaded(scene, loadedAsset)) {
+    return loadedAsset;
+  }
+
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      scene.load.off('complete', onComplete);
+      scene.load.off('loaderror', onLoadError);
+    };
+
+    const onComplete = () => {
+      cleanup();
+      try {
+        if (loadedAsset.kind === 'image-sequence') {
+          registerImageSequenceAnimations(
+            scene,
+            collections.imageSequences ?? {},
+          );
+        }
+        resolve(loadedAsset);
+      } catch (error) {
+        reject(error);
+      }
+    };
+
+    const onLoadError = file => {
+      if (getAssetKeyFromFileKey(file.key) !== assetKey) {
+        return;
+      }
+
+      cleanup();
+      reject(new Error('Failed to load asset: ' + assetKey));
+    };
+
+    scene.load.once('complete', onComplete);
+    scene.load.on('loaderror', onLoadError);
+
+    try {
+      loadAssets(scene, collections);
+      if (!scene.load.isLoading()) {
+        scene.load.start();
+      }
+    } catch (error) {
+      cleanup();
+      reject(error);
+    }
+  });
+};

package/lib/__templates__/phaser-static/src/utils/index.js

@@ -0,0 +1,2 @@
+export * from './asset-loader.js';
+export * from './mark-editable.js';

package/lib/__templates__/phaser-static/src/utils/mark-editable.js

@@ -0,0 +1,3 @@
+export const markEditable = (locator, gameObject, options) =>
+  window.PhaserBridge?.markEditable?.(locator, gameObject, options) ??
+  gameObject;

package/lib/__templates__/phaser-static/template.config.js

@@ -0,0 +1,35 @@
+
+
+
+
+
+
+
+
+export const paramsSchema = {
+  type: 'object',
+  properties: {
+    appName: {
+      type: 'string',
+      minLength: 1,
+      pattern: '^[a-z0-9-]+$',
+      description:
+        'Application name (lowercase, alphanumeric and hyphens only)',
+    },
+  },
+  required: [],
+  additionalProperties: false,
+};
+
+const config = {
+  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。',
+  paramsSchema,
+  defaultParams: {
+    appName: 'phaser-static-game',
+  },
+};
+
+export default config;

package/lib/__templates__/pi-agent/package.json

@@ -22,7 +22,7 @@
     "@mariozechner/pi-ai": "^0.63.2",
     "@mariozechner/pi-coding-agent": "^0.63.2",
     "@sinclair/typebox": "^0.34.48",
-    "coze-coding-dev-sdk": "^0.7.17",
+    "coze-coding-dev-sdk": "^0.7.25",
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-slot": "^1.2.4",
     "@streamdown/code": "^1.1.1",

package/lib/__templates__/pi-agent/pnpm-lock.yaml

@@ -36,8 +36,8 @@ importers:
         specifier: ^2.1.1
         version: 2.1.1
       coze-coding-dev-sdk:
-        specifier: ^0.7.17
-        version: 0.7.20(openai@6.34.0(ws@8.20.0)(zod@4.3.6))(ws@8.20.0)
+        specifier: ^0.7.25
+        version: 0.7.25(openai@6.34.0(ws@8.20.0)(zod@4.3.6))(ws@8.20.0)
       express:
         specifier: ^4.21.2
         version: 4.22.1
@@ -2085,8 +2085,8 @@ packages:
   cose-base@2.2.0:
     resolution: {integrity: sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g==}
 
-  coze-coding-dev-sdk@0.7.20:
-    resolution: {integrity: sha512-f3UeZcYB/udyWrlFrsOViM47PCW+Nk0I4FcXEGzcjEfaQsa1CPBpf/y5UbBM6GIZ1v+lnuh/MiBlAaALFeMTqw==}
+  coze-coding-dev-sdk@0.7.25:
+    resolution: {integrity: sha512-5683ngikMdsRW0slGTE2OAZ1Fyj0lhkC4fGNOwsqKc35e68/gtg9KmmtK9CK9SZ+5/oIn/4wLoHXFB0gHJtO2A==}
     engines: {node: '>=18.0.0'}
     hasBin: true
 
@@ -6120,7 +6120,7 @@ snapshots:
     dependencies:
       layout-base: 2.0.1
 
-  coze-coding-dev-sdk@0.7.20(openai@6.34.0(ws@8.20.0)(zod@4.3.6))(ws@8.20.0):
+  coze-coding-dev-sdk@0.7.25(openai@6.34.0(ws@8.20.0)(zod@4.3.6))(ws@8.20.0):
     dependencies:
       '@langchain/core': 1.1.40(openai@6.34.0(ws@8.20.0)(zod@4.3.6))(ws@8.20.0)
       '@langchain/openai': 1.4.3(@langchain/core@1.1.40(openai@6.34.0(ws@8.20.0)(zod@4.3.6))(ws@8.20.0))(ws@8.20.0)

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

@@ -4,7 +4,7 @@ set -Eeuo pipefail
 start_service() {
     cd "${COZE_WORKSPACE_PATH}/server/dist"
 
-    local port="${DEPLOY_RUN_PORT:-3000}"
+    local port="${DEPLOY_RUN_PORT:-<%= serverPort %>}"
     echo "Starting Static File Server on port ${port} for deploy..."
 
     node ./main.js -p "${port}"

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

@@ -2,12 +2,17 @@
 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 文件，用于追踪上一次启动的进程树
+# 项目级日志目录
 # ---------------------------------------------------------
-PID_FILE="/tmp/coze-dev-run.pid"
+LOG_DIR="${COZE_WORKSPACE_PATH}/logs"
+LOG_FILE="${LOG_DIR}/dev.log"
+PID_FILE="${LOG_DIR}/dev.pid"
+DEV_PID=""
 
 # ---------------------------------------------------------
 # 工具函数
@@ -25,99 +30,192 @@ kill_process_tree() {
     fi
 }
 
+# detached 出去的进程没人负责回收，超过这个时长就自己退出，避免端口与内存长期泄露。
+MAX_RUNTIME_SECONDS=1200
+
+# 真正被 detach 的是这层 bash wrapper：它是进程组 leader，组内 watchdog 到点回收整组
+# （wrapper -> pnpm -> taro/nest）；被包的进程自己先退出时也顺手清空进程组，不留残余。
+RUN_WITH_TIMEOUT='
+timeout_seconds=$1
+shift
+
+"$@" &
+child_pid=$!
+
+# 先忽略 TERM，才能在向整组发 TERM（自己也在组里）之后存活下来补一发 KILL。
+( trap "" TERM
+  sleep "${timeout_seconds}"
+  echo "[dev] 后台进程运行超过 ${timeout_seconds}s，回收进程组 $$。"
+  kill -TERM -- "-$$" 2>/dev/null || true
+  sleep 5
+  kill -KILL -- "-$$" 2>/dev/null || true
+) &
+
+wait "${child_pid}"
+kill -KILL -- "-$$" 2>/dev/null || true
+'
+
+# coze-daemon 会在 runtime shell 退出时清理原进程组。
+# 通过 Node detached spawn 创建独立 session/进程组，并将 stdio 直接写入日志。
+# 返回的 PID 是 wrapper 的，同时也是整个进程组的 PGID，后续按组回收。
+spawn_detached() {
+    local cwd="$1"
+    local log_file="$2"
+    shift 2
+
+    node - "$cwd" "$log_file" \
+        /bin/bash -c "${RUN_WITH_TIMEOUT}" detached-runner "${MAX_RUNTIME_SECONDS}" "$@" <<'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=$(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)
+    pids=$(list_port_pids "${port}")
     if [[ -z "${pids}" ]]; then
         echo "Port ${port} is free."
         return
     fi
-    echo "Port ${port} in use by PIDs: ${pids}"
+    echo "Port ${port} in use by PIDs: ${pids} (SIGKILL)"
     for pid in ${pids}; do
         kill_process_tree "${pid}"
     done
     sleep 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)
+    pids=$(list_port_pids "${port}")
     if [[ -n "${pids}" ]]; then
-        echo "Warning: port ${port} still busy after cleanup, PIDs: ${pids}"
+        echo "Warning: port ${port} still busy after SIGKILL, PIDs: ${pids}"
     else
         echo "Port ${port} cleared."
     fi
 }
 
-# ---------------------------------------------------------
-# 1. 清理上一次运行残留的整棵进程树
-# ---------------------------------------------------------
+# 只清理当前项目上次记录的 detached 进程。
 cleanup_previous_run() {
-    # 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}"
+    if [[ ! -f "${PID_FILE}" ]]; then
+        return
     fi
 
-    # 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
+    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}"
 }
 
 # ---------------------------------------------------------
 # 2. 安装依赖
 # ---------------------------------------------------------
 echo "📦 Installing dependencies..."
-pnpm install
+PNPM_BIN="$(command -v pnpm)"
+"${PNPM_BIN}" install
 echo "✅ Dependencies installed successfully!"
 
 # ---------------------------------------------------------
 # 3. 清理旧进程 + 端口
 # ---------------------------------------------------------
-SERVER_PORT=3000
+# DEPLOY_RUN_PORT 是平台注入的对外端口，项目内统一使用 PORT。
+PORT="${DEPLOY_RUN_PORT:-${PORT:-<%= port %>}}"
+SERVER_PORT="${SERVER_PORT:-<%= serverPort %>}"
+export PORT
+export SERVER_PORT
 
+mkdir -p "${LOG_DIR}"
 cleanup_previous_run
 
-echo "Clearing port ${DEPLOY_RUN_PORT} (web) before start."
-kill_port_if_listening "${DEPLOY_RUN_PORT}"
+echo "Clearing port ${PORT} (web) before start."
+kill_port_if_listening "${PORT}"
 echo "Clearing port ${SERVER_PORT} (server) before start."
 kill_port_if_listening "${SERVER_PORT}"
 
 # ---------------------------------------------------------
-# 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. 启动服务
+# 4. 启动服务
 # ---------------------------------------------------------
 start_service() {
     cd "${COZE_WORKSPACE_PATH}"
@@ -133,19 +231,31 @@ start_service() {
     # 启动 Taro H5 和 NestJS Server
     echo "Starting Taro H5 Dev Server and NestJS Server..."
 
-    export PORT=${DEPLOY_RUN_PORT}
-    rm -f /tmp/coze-logs/dev.log
-    mkdir -p /tmp/coze-logs
+    : > "${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}"
 
-    # 后台启动并记录 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})"
+    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
 
-    # 前台等待，保证 trap 能正常捕获信号
-    wait "${dev_pid}" || true
+    echo "📝 Dev process started with PID: ${DEV_PID}"
+    echo "Auto stop after ${MAX_RUNTIME_SECONDS}s."
+    echo "Log file: ${LOG_FILE}"
+    echo "PID file: ${PID_FILE}"
 }
 
-echo "Starting HTTP services on port ${DEPLOY_RUN_PORT} (web) and ${SERVER_PORT} (server)..."
+echo "Starting HTTP services on port ${PORT} (web) and ${SERVER_PORT} (server)..."
 start_service