@coze-arch/cli 0.0.36-alpha.b293fc → 0.0.36-alpha.fd6b86

package/README.md

@@ -19,6 +19,17 @@ rush update
 
 ## 使用
 
+### 部署应用
+
+```bash
+coze-dev deploy auth login
+coze-dev deploy code deploy --source-root . --yes --wait
+```
+
+完整命令、参数和示例见 [部署命令文档](./docs/deploy.md)。部署命令与其它
+`coze-dev` 能力共享 `~/.coze/cli/config.json` 登录态，也支持通过
+`COZE_API_TOKEN` 提供固定运行时凭证。
+
 ### 初始化项目
 
 ```bash

package/docs/deploy.md

@@ -0,0 +1,171 @@
+# coze-dev deploy
+
+`coze-dev` 内置的部署命令，复用主 Coze CLI 保存在
+`~/.coze/cli/config.json` 中的登录状态。
+
+## 安装与运行
+
+```bash
+npm install -g @coze-arch/cli
+coze-dev deploy auth login
+coze-dev deploy auth status
+coze-dev deploy doctor
+```
+
+默认输出 JSON，可通过 `--format text` 切换为文本输出。
+
+首次部署不需要手动查找 `space_id` 或 `project_id`。当 `.coze [project]` 没有
+`project_id` 时，CLI 会复用已配置的 Space；如果尚未配置，会查询当前账号
+可用的 Space、自动选择第一个并保存，然后根据 `.coze` 的
+`[project].project_type` 创建当前源码目录专属的普通编程 Project。
+映射与部署服务端对 `.coze` 的解析保持一致：`agent`→Agent、`workflow`/`automation`→Automation、
+`app`→App、`skill`→Skill、`web`/`backend`→GeneralWeb、`miniapp`/`miniprogram`→WechatMiniProgram；
+其他值或未声明 `project_type` 时创建通用 General Project。不会复用共享的 CLIBilling Project。
+
+> Project 类型不只是元信息：它决定注入运行时的 `COZE_PROJECT_TYPE`、是否为该 Project 开通
+> Postgres、以及流量网关是否强制入站鉴权。类型建错时部署照样成功，但服务可能起不来 —— 例如
+> agent 模板靠 `COZE_PROJECT_TYPE` 选择要加载的图，并在启动时读取 `PGDATABASE_URL`。
+> 类型在创建 Project 时一次性确定，之后再改 `.coze project_type` 不会改变已有 Project 的类型。
+
+指定 PPE 泳道时，增加全局参数 `--lane`。CLI 会为所有部署 API 请求发送
+`x-tt-env` 和 `x-use-ppe: 1`，该参数只对当前命令生效：
+
+```bash
+coze-dev deploy --lane ppe_deploy code app list
+coze-dev deploy --lane ppe_deploy code deploy --source-root .
+```
+
+## 命令
+
+```text
+coze-dev deploy context show
+coze-dev deploy auth login|status|logout
+coze-dev deploy context use --space-id <space_id>
+coze-dev deploy doctor
+coze-dev deploy code app list [--page-size <n>] [--page-token <token>] [--all]
+coze-dev deploy code app show --app-id <app_id>
+coze-dev deploy code app rename <name> --app-id <app_id> --yes
+coze-dev deploy code app delete --app-id <app_id> --yes
+coze-dev deploy code app analytics|metrics --app-id <app_id> [--time-range <range>]
+coze-dev deploy code app usage --app-id <app_id> --bill-month <YYYY-MM>
+coze-dev deploy [--lane <ppe_lane>] code deploy [--source-root <directory>] [--app-id <app_id>] [--application-type <type>] [--name <name>] [--connector-id <id>]
+coze-dev deploy code deploy status|list|online|rollback-check|cancel|rollback|stop|resume|pause
+coze-dev deploy code deploy logs|log-count|count|build-log|config
+coze-dev deploy code domain list [--unit-type dev|prod]
+coze-dev deploy code domain add <domain>
+coze-dev deploy code domain set-prefix <prefix> --app-id <app_id> --yes
+coze-dev deploy code mini-program status|bind|submit-code|unbind|auth|preview
+```
+
+`code app list` 是真分页：一次只返回一页（`--page-size` 默认 20、上限 100），`has_more` 为真时用返回的 `next_page_token` 取下一页；要一次拿到名下全部应用用 `--all`，它会自己翻到底。
+
+部署确认阶段不传 `--yes`；确认后使用相同参数增加 `--yes`，需要等待终态时再增加
+`--wait`。CLI 会为每次请求自动生成一个 40 位十六进制源码快照 ID，用于兼容 V2 接口的
+`commit_hash` 字段，用户无需指定。该 ID 不代表 Git commit；源码目录无需由 Git 管理，
+打包时始终读取目录的最新内容。CLI 会把当前源码目录专属的 `project_id` 和唯一 `app_id`
+写入 `.coze [project]`，ID 使用引号包裹的十进制字符串。后续类型一致时自动复用该
+Application；类型不一致时创建新 Application、覆盖 `app_id` 并提示。也可用 `--project-id`
+或 `--app-id` 显式指定已有资源，显式指定时不会额外创建 Project。
+
+首次部署的应用名称可通过 `--name` 指定；显式参数优先于 `.coze` 的
+`[project].name`。Pages 部署没有 `.coze` 时，CLI 会先生成最小配置再写入绑定。
+
+```toml
+[project]
+name = "Phaser 游戏"
+project_type = "web"
+project_id = "987654321"
+app_id = "123456789"
+```
+
+Pages 首次部署没有 `app_id`，必须显式指定交付类型。Pages 将
+`--source-root` 视为项目根目录：根目录已有 `index.html` 时直接打包；否则读取 `.coze`，
+要求 `project.template = "nextjs"` 且 `deploy.build` 为非空命令数组。CLI 不在本地安装
+依赖或执行 Pages 构建，只上传源码；Deploy 服务在 Sandbox 中注入 Next.js 静态导出配置，
+执行 `deploy.build`，并要求最终产出 `out/index.html`：
+
+```bash
+coze-dev deploy code deploy --source-root . --application-type pages
+coze-dev deploy code deploy --source-root . --application-type pages --yes --wait
+```
+
+创建成功后 CLI 会把 Pages Application 写入 `.coze`；后续可继续传
+`--application-type pages` 自动复用，或显式传 `--app-id`。
+
+V2 接口的所有参数均通过 POST JSON body 发送，不会放入 URL。确认非 Pages 部署后，CLI
+会执行 `.coze` 中可选的 `dev.pack` 命令，将
+本地部署内容打成无根目录的 `tar.gz`，再通过 `source_package_base64` 上传。Pages 部署
+统一上传源码根目录：已有 `index.html` 时服务端跳过构建，没有时由服务端按 Snapshot 中的
+`.coze deploy.build` 构建。打包由 CLI 自带的 Node.js 脚本执行，并排除 `.coze`、`.env`、
+`.git`、`.venv`、`.codegraph`、`node_modules`、`.next`、`site-packages` 和 `__pycache__`。
+`scripts/package-project.py` 仍随源码和 npm 包保留，仅作为 Python 参考备份与行为对照，
+生产打包链路不会调用 Python。
+
+环境变量以当前线上成功版本的 Secret 快照为准，CLI 不再读取源码根目录的 `.env`。
+更新服务或小程序时，CLI 会读取线上快照中的用户变量并重新加密上传；首次部署没有线上
+快照，因此使用空的用户变量集合。平台系统变量由 Secret 服务管理，不作为用户变量上传。
+
+通过 `app_id` 查看当前线上版本的环境变量及快照状态：
+
+```bash
+coze-dev deploy code env list
+coze-dev deploy code env list --app-id 7672644451805691910
+```
+
+小程序部署可重复指定渠道：微信为 `10000127`，抖音为 `10000126`：
+
+```bash
+coze-dev deploy code deploy --source-root . --application-type mini_program \
+  --connector-id 10000127 --yes --wait
+```
+
+小程序预览先完成授权，再执行 preview。preview 会打包微信的 dist/ 或抖音的 dist-tt/ 并上传。Project ID 可通过参数传入或从 .coze 自动读取。
+
+```bash
+coze-dev deploy code mini-program auth --platform wechat --mini-app-id wx123 --source-root .
+coze-dev deploy code mini-program preview --platform wechat --mini-app-id wx123 --source-root .
+```
+
+绑定小程序 AppID 时，默认从源码目录 `.coze [project]` 读取该目录的 `project_id`：
+
+```bash
+coze-dev deploy code mini-program bind \
+  --platform wechat \
+  --mini-app-id wx123 \
+  --redirect-url https://code.coze.cn/coding/auth/callback/miniprogram
+```
+
+返回 `bind_status=1` 时，打开 `need_authorize_data.auth_url` 完成授权。回调页会自动
+提交授权码；无回调页的调用方也可使用 `mini-program submit-code` 手动提交。
+
+`code deploy status` 和 `list` 会返回 `deploy_detail[].deploy_log_key`。只有一个日志
+key 时，`code deploy build-log --deploy-id <id>` 会自动解析；存在多个 key 时按错误
+详情中的 `available_keys` 选择一个并传 `--key`。
+
+应用维度的管理和观测命令均支持 `--app-id`；省略时从当前目录的 `.coze [project]` 读取：
+
+```bash
+coze-dev deploy code app rename "新应用名称" --app-id <app_id> --yes
+coze-dev deploy code deploy online --app-id <app_id>
+coze-dev deploy code deploy rollback-check --app-id <app_id> --deploy-id <history_id>
+coze-dev deploy code deploy log-count --app-id <app_id>
+coze-dev deploy code deploy count --app-id <app_id>
+coze-dev deploy code app metrics --app-id <app_id> --time-range week
+coze-dev deploy code app usage --app-id <app_id> --bill-month 2026-08
+coze-dev deploy code domain list --app-id <app_id> --unit-type dev
+```
+
+`domain list` 默认查询 Prod 域名；传 `--unit-type dev` 查询开发态预览域名。
+审核 Unit 是内部流水线槽位，不支持从 CLI 查询。
+
+`code domain set-prefix` 改的是**系统分配的默认域名**（`<prefix>.coze.site`）里的 prefix，
+后缀不变；`code domain add` 加进来的自定义域名不受影响 —— 那类域名服务端只有 create/delete，
+域名串本身改不了。改完旧默认域名立刻不再指向本应用，已经发出去的链接会失效，所以必须传 `--yes`。
+前缀的长度、保留词、是否被占用由服务端判定，CLI 只拦形态明显不合法的值（大写、首尾连字符等）。
+这是**权益能力**：账号没有对应权益时服务端会直接拒绝。
+
+`code app delete` 删除应用，终态不可撤销，必须传 `--yes`。服务端**只接受已停服的应用**：
+仍在服务时会返回一条带当前状态的错误，先跑 `code deploy stop --yes` 再删。CLI 不会替你先停 ——
+停服会真的把线上服务摘掉，那一步要由你自己确认。删除会一并停掉该应用名下的部署单元、
+软删它的域名并清理残留的函数；已删除的应用再删一次是幂等成功。删完记得把 `.coze [project]`
+里的 `app_id` 去掉，否则同目录下一次 `code deploy` 会打到这个已删除的应用上被服务端拒。

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

@@ -1,17 +1,20 @@
+#!/usr/bin/env bash
+
 ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
 PREVIEW_DIR="/source/preview"
 LOG_DIR="${COZE_LOG_DIR:-$ROOT_DIR/logs}"
 LOG_CLIENT_FILE="$LOG_DIR/client.log"
+LOG_SERVER_FILE="$LOG_DIR/server.log"
 mkdir -p "$LOG_DIR"
 
 # ==================== 配置项 ====================
 # Server 服务配置
 SERVER_HOST="0.0.0.0"
-SERVER_PORT="9091"
+SERVER_PORT="${SERVER_PORT:-9091}"
 # Expo 项目配置
 EXPO_HOST="0.0.0.0"
 EXPO_DIR="expo"
-EXPO_PORT="5000"
+EXPO_PORT="${EXPO_PORT:-5000}"
 WEB_URL="${COZE_PROJECT_DOMAIN_DEFAULT:-http://127.0.0.1:${SERVER_PORT}}"
 ASSUME_YES="1"
 EXPO_PUBLIC_BACKEND_BASE_URL="${EXPO_PUBLIC_BACKEND_BASE_URL:-$WEB_URL}"
@@ -22,6 +25,7 @@ export EXPO_PUBLIC_BACKEND_BASE_URL EXPO_PACKAGER_PROXY_URL EXPO_PUBLIC_COZE_PRO
 # 运行时变量（为避免 set -u 的未绑定错误，预置为空）
 SERVER_PID=""
 EXPO_PID=""
+PNPM_BIN=""
 
 # ==================== 工具函数 ====================
 check_command() {
@@ -112,22 +116,67 @@ wait_port_connectable() {
   return 1
 }
 
-start_expo() {
-  local offline="${1:-0}"
+# 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');
 
-  pushd "$ROOT_DIR/client"
+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
+}
+
+start_expo() {
+  local offline="${1:-0}"
+  local -a expo_env
+  expo_env=(
+    "EXPO_NO_DEPENDENCY_VALIDATION=1"
+    "EXPO_PUBLIC_BACKEND_BASE_URL=$EXPO_PUBLIC_BACKEND_BASE_URL"
+    "EXPO_PACKAGER_PROXY_URL=$EXPO_PACKAGER_PROXY_URL"
+    "EXPO_PUBLIC_COZE_PROJECT_ID=$EXPO_PUBLIC_COZE_PROJECT_ID"
+  )
   if [ "$offline" = "1" ]; then
-    ( EXPO_OFFLINE=1 EXPO_NO_DEPENDENCY_VALIDATION=1 EXPO_PUBLIC_BACKEND_BASE_URL="$EXPO_PUBLIC_BACKEND_BASE_URL" EXPO_PACKAGER_PROXY_URL="$EXPO_PACKAGER_PROXY_URL" EXPO_PUBLIC_COZE_PROJECT_ID="$EXPO_PUBLIC_COZE_PROJECT_ID" \
-      nohup npx expo start --clear --port "$EXPO_PORT" 2>&1 | pipe_to_log "CLIENT" "$LOG_CLIENT_FILE" ) &
-  else
-    ( EXPO_NO_DEPENDENCY_VALIDATION=1 EXPO_PUBLIC_BACKEND_BASE_URL="$EXPO_PUBLIC_BACKEND_BASE_URL" EXPO_PACKAGER_PROXY_URL="$EXPO_PACKAGER_PROXY_URL" EXPO_PUBLIC_COZE_PROJECT_ID="$EXPO_PUBLIC_COZE_PROJECT_ID" \
-      nohup npx expo start --clear --port "$EXPO_PORT" 2>&1 | pipe_to_log "CLIENT" "$LOG_CLIENT_FILE" ) &
+    expo_env+=("EXPO_OFFLINE=1")
   fi
-  EXPO_PID=$!
-  disown $EXPO_PID 2>/dev/null || true
 
-  popd
+  EXPO_PID="$(spawn_detached \
+    "$ROOT_DIR/client" \
+    "$LOG_CLIENT_FILE" \
+    /usr/bin/env "${expo_env[@]}" \
+    "$PNPM_BIN" exec expo start --clear --port "$EXPO_PORT")"
 }
 
 detect_expo_fetch_failed() {
@@ -168,6 +217,8 @@ check_command "npm"
 check_command "pnpm"
 check_command "lsof"
 check_command "bash"
+check_command "node"
+PNPM_BIN="$(command -v pnpm)"
 
 # 端口占用预检查与处理
 ensure_port SERVER_PORT "$SERVER_PORT"
@@ -175,9 +226,12 @@ ensure_port EXPO_PORT "$EXPO_PORT"
 
 echo "==================== 启动 server 服务 ===================="
 echo "正在执行：pnpm run dev (server)"
-( pushd "$ROOT_DIR/server" > /dev/null && SERVER_PORT="$SERVER_PORT" nohup pnpm run dev; popd > /dev/null ) &
-SERVER_PID=$!
-disown $SERVER_PID 2>/dev/null || true
+: > "$LOG_SERVER_FILE"
+export SERVER_PORT
+SERVER_PID="$(spawn_detached \
+  "$ROOT_DIR/server" \
+  /dev/null \
+  "$PNPM_BIN" run dev)"
 if [ -z "${SERVER_PID}" ]; then
   echo "无法获取 server 后台进程 PID"
 fi
@@ -185,11 +239,12 @@ echo "server 服务已启动，进程 ID：${SERVER_PID:-unknown}"
 
 echo "==================== 启动 Expo 项目 ===================="
 echo "开始启动 Expo 服务，端口 ${EXPO_PORT}"
+: > "$LOG_CLIENT_FILE"
 start_expo 0
 if detect_expo_fetch_failed 8; then
   echo "Expo 启动检测到网络错误：TypeError: fetch failed，启用离线模式重试"
-  if [ -n "${EXPO_PID}" ]; then kill -9 "$EXPO_PID" 2>/dev/null || true; fi
-  : > "$ROOT_DIR/logs/client.log"
+  stop_detached "$EXPO_PID"
+  : > "$LOG_CLIENT_FILE"
   start_expo 1
 fi
 # 输出以下环境变量，确保 Expo 项目能正确连接到 Server 服务

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

@@ -269,8 +269,8 @@ importers:
         specifier: ^2.8.5
         version: 2.8.6
       coze-coding-dev-sdk:
-        specifier: ^0.7.24
-        version: 0.7.24(openai@6.16.0(ws@8.19.0)(zod@4.3.6))(ws@8.19.0)
+        specifier: ^0.7.25-beta.4
+        version: 0.7.25-beta.4(openai@6.16.0(ws@8.19.0)(zod@4.3.6))(ws@8.19.0)
       dayjs:
         specifier: ^1.11.20
         version: 1.11.20
@@ -2643,8 +2643,8 @@ packages:
     resolution: {integrity: sha512-AdmX6xUzdNASswsFtmwSt7Vj8po9IuqXm0UXz7QKPuEUmPB4XyjGfaAr2PSuELMwkRMVH1EpIkX5bTZGRB3eCA==}
     engines: {node: '>=10'}
 
-  coze-coding-dev-sdk@0.7.24:
-    resolution: {integrity: sha512-oL9Tg5PwxP6iMixonzzMO4aBjOKWcFUMVM+iz5dPyaqQkG84HP1y9DqK5DJVmtdfJuYdAW7pzOatDqLvgvZiXg==}
+  coze-coding-dev-sdk@0.7.25-beta.4:
+    resolution: {integrity: sha512-+PCoJ8yhsAIlx3YT898bCkB2gx5EMBunJMP7/kI/Jq/8dj7SDU9EUBZ2Z8ZJocSaPBT9T6dVvFHBsDLZh4FN/Q==}
     engines: {node: '>=18.0.0'}
     hasBin: true
 
@@ -9088,7 +9088,7 @@ snapshots:
       path-type: 4.0.0
       yaml: 1.10.2
 
-  coze-coding-dev-sdk@0.7.24(openai@6.16.0(ws@8.19.0)(zod@4.3.6))(ws@8.19.0):
+  coze-coding-dev-sdk@0.7.25-beta.4(openai@6.16.0(ws@8.19.0)(zod@4.3.6))(ws@8.19.0):
     dependencies:
       '@langchain/core': 1.1.17(openai@6.16.0(ws@8.19.0)(zod@4.3.6))
       '@langchain/openai': 1.2.3(@langchain/core@1.1.17(openai@6.16.0(ws@8.19.0)(zod@4.3.6)))(ws@8.19.0)

package/lib/__templates__/expo/server/package.json

@@ -12,7 +12,7 @@
   "dependencies": {
     "@supabase/supabase-js": "2.95.3",
     "cors": "^2.8.5",
-    "coze-coding-dev-sdk": "^0.7.24",
+    "coze-coding-dev-sdk": "^0.7.25-beta.4",
     "dayjs": "^1.11.20",
     "dotenv": "^17.2.3",
     "drizzle-orm": "^0.45.1",

package/lib/__templates__/nextjs/scripts/dev.sh

@@ -32,8 +32,89 @@ kill_port_if_listening() {
     fi
 }
 
+<% if (process.env.NODE_ENV === 'test') { %>
+echo "Clearing port ${DEPLOY_RUN_PORT} before start."
+kill_port_if_listening
+echo "Starting HTTP service on port ${DEPLOY_RUN_PORT} for dev..."
+
+# 测试环境保持服务为前台进程，便于 e2e 收集输出并停止进程。
+exec env PORT="${DEPLOY_RUN_PORT}" pnpm tsx watch src/server.ts
+<% } else { %>
+LOG_DIR="${COZE_LOG_DIR:-${COZE_WORKSPACE_PATH}/logs}"
+LOG_FILE="${LOG_DIR}/server.log"
+PID_FILE="${LOG_DIR}/server.pid"
+
+# 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
+}
+
+# 监听端口的是孙进程（pnpm -> tsx -> node），只清端口会漏掉上层 pnpm/tsx，
+# 所以先按上次记录的 PID 把整个进程组回收掉。
+if [[ -f "${PID_FILE}" ]]; then
+  stop_detached "$(cat "${PID_FILE}" 2>/dev/null || true)"
+  rm -f "${PID_FILE}"
+fi
+
 echo "Clearing port ${DEPLOY_RUN_PORT} before start."
 kill_port_if_listening
 echo "Starting HTTP service on port ${DEPLOY_RUN_PORT} for dev..."
 
-PORT=${DEPLOY_RUN_PORT} pnpm tsx watch src/server.ts
+mkdir -p "${LOG_DIR}"
+: > "${LOG_FILE}"
+
+export PORT="${DEPLOY_RUN_PORT}"
+server_pid="$(spawn_detached "${COZE_WORKSPACE_PATH}" "${LOG_FILE}" \
+  "$(command -v pnpm)" tsx watch src/server.ts)"
+echo "${server_pid}" > "${PID_FILE}"
+
+sleep 1
+if [[ -z "${server_pid}" ]] || ! kill -0 "${server_pid}" 2>/dev/null; then
+  echo "Dev server failed to start. See ${LOG_FILE}." >&2
+  tail -n 20 "${LOG_FILE}" >&2 || true
+  rm -f "${PID_FILE}"
+  exit 1
+fi
+
+echo "Dev server started (PID: ${server_pid})."
+echo "Log file: ${LOG_FILE}"
+echo "PID file: ${PID_FILE}"
+<% } %>

package/lib/__templates__/nextjs/template.config.js

@@ -3,6 +3,7 @@
 import { spawn } from 'child_process';
 import { resolve, join, basename } from 'path';
 import { appendFileSync, openSync, closeSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
 
 
 
@@ -74,7 +75,8 @@ const config = {
       const projectRoot = resolve(outputPath);
 
       // Determine log directory
-      const logDir = process.env.COZE_LOG_DIR || resolve(__dirname, '../.log');
+      const cozeHome = process.env.COZE_HOME || join(homedir(), '.coze');
+      const logDir = process.env.COZE_LOG_DIR || join(cozeHome, 'logs');
       mkdirSync(logDir, { recursive: true });
 
       // Use project name in log file to avoid conflicts

package/lib/__templates__/nuxt-vue/scripts/dev.sh

@@ -32,8 +32,89 @@ kill_port_if_listening() {
     fi
 }
 
+<% if (process.env.NODE_ENV === 'test') { %>
+echo "Clearing port ${DEPLOY_RUN_PORT} before start."
+kill_port_if_listening
+echo "Starting Nuxt dev server on port ${DEPLOY_RUN_PORT}..."
+
+# 测试环境保持服务为前台进程，便于 e2e 收集输出并停止进程。
+exec env PORT="${DEPLOY_RUN_PORT}" pnpm nuxt dev
+<% } else { %>
+LOG_DIR="${COZE_LOG_DIR:-${COZE_WORKSPACE_PATH}/logs}"
+LOG_FILE="${LOG_DIR}/server.log"
+PID_FILE="${LOG_DIR}/server.pid"
+
+# 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
+}
+
+# 监听端口的是孙进程（pnpm -> nuxt -> node），只清端口会漏掉上层 pnpm/nuxt，
+# 所以先按上次记录的 PID 把整个进程组回收掉。
+if [[ -f "${PID_FILE}" ]]; then
+  stop_detached "$(cat "${PID_FILE}" 2>/dev/null || true)"
+  rm -f "${PID_FILE}"
+fi
+
 echo "Clearing port ${DEPLOY_RUN_PORT} before start."
 kill_port_if_listening
 echo "Starting Nuxt dev server on port ${DEPLOY_RUN_PORT}..."
 
-PORT=${DEPLOY_RUN_PORT} pnpm nuxt dev
+mkdir -p "${LOG_DIR}"
+: > "${LOG_FILE}"
+
+export PORT="${DEPLOY_RUN_PORT}"
+server_pid="$(spawn_detached "${COZE_WORKSPACE_PATH}" "${LOG_FILE}" \
+  "$(command -v pnpm)" nuxt dev)"
+echo "${server_pid}" > "${PID_FILE}"
+
+sleep 1
+if [[ -z "${server_pid}" ]] || ! kill -0 "${server_pid}" 2>/dev/null; then
+  echo "Dev server failed to start. See ${LOG_FILE}." >&2
+  tail -n 20 "${LOG_FILE}" >&2 || true
+  rm -f "${PID_FILE}"
+  exit 1
+fi
+
+echo "Dev server started (PID: ${server_pid})."
+echo "Log file: ${LOG_FILE}"
+echo "PID file: ${PID_FILE}"
+<% } %>

package/lib/__templates__/phaser/_gitignore

@@ -8,6 +8,7 @@ coverage/
 
 *.log
 *.tsbuildinfo
+logs/
 .vite/
 .cache/
 node-compile-cache/

package/lib/__templates__/phaser/package.json

@@ -24,7 +24,7 @@
     "typescript": "^5.9.3",
     "vite": "^8.2.0"
   },
-  "packageManager": "pnpm@9.15.9",
+  "packageManager": "pnpm@9.0.0",
   "engines": {
     "pnpm": ">=9.0.0"
   }