cardbuddy 0.9.1 → 0.11.0

package/README.md

@@ -66,6 +66,7 @@ cardbuddy --preview          # 等价短参 -p
 | --- | --- | --- |
 | `DSL_CARD_ROOT` | 当前目录 (`cwd`) | 卡片代码仓库根（含 `src/cards`）。可用环境变量二次覆盖。 |
 | `DSL_DEV_PORT` | `8787` | 本地服务监听端口。 |
+| `DSL_DEV_PORT_TAKEOVER` | `auto` | 端口被占用时的接管策略：`auto` 自动结束占用该端口的旧 cardbuddy 实例后启动；`force` 连无关进程一并结束；`off` 关闭前置检查（退回原生 `EADDRINUSE` 报错）。 |
 | `EDITOR_URL` | `http://127.0.0.1:5180` | 截图自访问的编辑器实例地址（默认指向本地编辑器）。写入 `.env` 即可持久化。 |
 | `DSL_DEV_TOKEN` | _(空)_ | 可选鉴权令牌；开启后请求须带 `x-dev-token` 头。默认仅靠 `127.0.0.1` 绑定（不暴露局域网）。 |
 | `DSL_DEV_HTTPS` | `0` | 设为 `1` 启用自签 HTTPS（兜底旧 Safari / 企业策略的混合内容拦截）。 |
@@ -76,6 +77,20 @@ cardbuddy --preview          # 等价短参 -p
 
 ---
 
+## 端口被占用时自动接管
+
+启动前先探测 `DSL_DEV_PORT`：若被**上一个 cardbuddy 实例**占用（终端直接关掉、`Ctrl+C` 漏杀、后台残留等），
+自动 `SIGTERM`（宽限 2.5s 后升级 `SIGKILL`）结束旧进程、等端口真正释放，再继续启动，免去手动
+`lsof -ti tcp:8787 | xargs kill`。
+
+判定「占用者是本服务」有两条依据：HTTP 探测 `/__cards` 返回 cardbuddy 响应体（`{ cards: [...] }` 或 token 鉴权 403），
+或占用进程命令行含 `cardbuddy` / `dsl-card` 字样。**无关进程占着端口时不会动手**，而是直接报错并给出手动处理命令；
+确需强制接管设 `DSL_DEV_PORT_TAKEOVER=force`。
+
+跨平台：macOS / Linux 用 `lsof` 定位 PID（缺失时回退 `ss`），Windows 用 `netstat -ano` + `taskkill /T /F`。
+
+---
+
 ## HTTPS 模式（混合内容兜底）
 
 默认本服务跑在 `http://127.0.0.1:8787`。当公网编辑器是 **HTTPS** 时，浏览器可能因「混合内容（Mixed Content）」或「私有网络访问（PNA）」策略拦截对 `http://127.0.0.1` 的跨源请求。现代 **Chrome / Firefox** 对回环地址（127.0.0.1 / localhost）豁免混合内容，默认即可用；但 **Safari** 等更严格的环境会拦截，此时启用 HTTPS 模式：
@@ -116,7 +131,7 @@ DSL_DEV_HTTPS=1 cardbuddy
 | `POST /__code-bridge/:id/heartbeat` | 自包含 | 代码桥：会话心跳（前端 5s 一次） |
 | `DELETE /__code-bridge/:id` | 自包含 | 代码桥：结束会话并删除临时文件 |
 
-> **FinMall 凭据只在本机**：`/__sync` `/__save` `/__preview` 由本地服务代理 FinMall，凭据存于本机 `skills/finmall-card-sync` 与 `.env.finmall`，公网前端永不接触。
+> **FinMall 凭据只在本机**：`/__sync` `/__save` `/__preview` 由本地服务代理 FinMall，凭据存于本机 `skills/finmall-card-sync` 与 `.env.cb`，公网前端永不接触。
 
 ### VSCode 代码桥（事件面板代码编辑区）
 
@@ -143,7 +158,7 @@ DSL_DEV_HTTPS=1 cardbuddy
 - `finmall-card-sync`（sync / save / preview）
 - `dsl-card-generator`（validate）
 
-请确保项目根下存在 `skills/finmall-card-sync/scripts/api_batch_sync.mjs` 等，且 `.env.finmall` 已配置 `FINMALL_BASE_URL` 等。
+请确保项目根下存在 `skills/finmall-card-sync/scripts/api_batch_sync.mjs` 等，且 `.env.cb` 已配置 `FINMALL_BASE_URL` 等。
 
 ---
 
@@ -168,7 +183,7 @@ DSL_DEV_HTTPS=1 cardbuddy
 
 | 命令 | 编辑器来源 | 后端来源 | 用途 |
 | --- | --- | --- | --- |
-| `npm run dev` | `preview/` 源码（Vite dev + HMR） | Vite 插件同源挂载（5180） | 日常改编辑器 / 卡片（同域，**不**走生产跨域链路） |
+| `npm run dev` | `preview/` 源码（Vite dev + HMR，5180） | `cardbuddy` 服务（8787，由 `tools/dev.mjs` 同起） | 日常改编辑器 / 卡片 |
 | `npm run dev:prod` | `dist/` **构建产物**（`vite preview`） | `cardbuddy` 服务（8787） | 部署前权威跨域 smoke test（最贴近生产） |
 | 部署公网 | `dist/` 静态托管（CDN） | 用户本机起 8787 | 生产环境 |
 
@@ -178,11 +193,11 @@ DSL_DEV_HTTPS=1 cardbuddy
 
 ```bash
 npm run dev
-# → Vite dev server 端口 5180（由 .env.finmall 的 FINMALL_DEV_PORT 控制）
+# → Vite dev server 端口 5180（由 .env.cb 的 FINMALL_DEV_PORT 控制）
 # 浏览器打开 http://localhost:5180
 ```
 
-`/__cards` `/__card/:id` `/__render-status` `/__node-models` 等后端端点由 Vite 插件 `server/cardServer.js` **同源挂载**，编辑器前端直接同源调用，无需单独起服务。
+`/__cards` `/__card/:id` `/__render-status` `/__node-models` 等后端端点全部由 `cardbuddy`（8787）提供：`server/core` 的中间件经 `mountCoreMiddlewares` 挂到它的 connect 实例，Vite 不承载任何后端插件。编辑器前端在 DEV 下经 `resolveApiBase()` 默认直连 `http://127.0.0.1:8787`（用非回环地址打开时走 `vite.config.mjs` 的 `cardDevProxy` 同源兜底，规避浏览器私有网络访问限制）。
 
 ### 模式二：开发期顺手看跨域（可选）
 
@@ -219,7 +234,7 @@ npm run dev:prod
 
 ### 前置条件
 
-- `.env.finmall` 已存在（含 `FINMALL_BASE_URL` 远端基址、`FINMALL_DEV_PORT`）。缺它编辑器仍能起，只是远端资源代理会告警。
+- `.env.cb` 已存在（含 `FINMALL_BASE_URL` 远端基址、`FINMALL_DEV_PORT`）。缺它编辑器仍能起，只是远端资源代理会告警。
 - 首次跑前先 `npm install`（仓库根）。
 
 ### 服务侧单独起（调试 8787 本身）

package/dist/cli.js

@@ -2,13 +2,13 @@
 /**
  * cardbuddy CLI 入口（npm 包名与可执行命令同为 cardbuddy；0.6.0 前叫 cardbuddy-dev）。
  *
- * 读取 cwd 下 .env / .env.finmall / .env.finmall.local（dotenv），启动本地开发服务（127.0.0.1）。
+ * 读取 cwd 下 .env / .env.cb / .env.cb.local（dotenv），启动本地开发服务（127.0.0.1）。
  * 配置项见 src/config.js（DSL_CARD_ROOT / FINMALL_CARD_PORT / DSL_DEV_PORT /
  * DSL_DEV_TOKEN / DSL_DEV_HTTPS / EDITOR_URL / DSL_EDITOR_SRC）。
  *
- * 端口约定：.env.finmall 的 FINMALL_CARD_PORT 为「卡片开发服务端口」单一真值，
+ * 端口约定：.env.cb 的 FINMALL_CARD_PORT 为「卡片开发服务端口」单一真值，
  * 主仓库由 tools/dev.mjs 把它注入为 DSL_DEV_PORT；此处直接用 FINMALL_CARD_PORT，
- * 使 demo（直接 npx cardbuddy 或 npm run dev，无启动器注入）也能经 .env.finmall 生效。
+ * 使 demo（直接 npx cardbuddy 或 npm run dev，无启动器注入）也能经 .env.cb 生效。
  */
 import dotenv from 'dotenv'
 import chalk from 'chalk'
@@ -25,10 +25,17 @@ const srcTag =
     ? ''
     : chalk.magenta('▌ ') + chalk.magenta.bold('cardbuddy') + ' '
 
-// 加载环境（与 skills 同套约定：.env.finmall 为共享配置，.env.finmall.local 为个人覆盖层）。
+// 加载环境（与 skills 同套约定：.env.cb 为共享配置，.env.cb.local 为个人覆盖层）。
 // dotenv 默认不覆盖已存在变量，故主仓库由启动器注入的 DSL_DEV_PORT / FINMALL_BASE_URL 仍优先。
-for (const p of ['.env', '.env.finmall', '.env.finmall.local']) {
-  dotenv.config({ path: p })
+// 同时登记「dotenv 注入值」：server/core/ai-chat.js 据此区分「启动时灌进 process.env 的文件值」
+// 与「真实环境变量覆盖」，否则磁盘上改了 .env.cb.local 也会被启动快照遮挡。
+for (const p of ['.env', '.env.cb', '.env.cb.local']) {
+  const loaded = dotenv.config({ path: p })
+  for (const [k, v] of Object.entries(loaded.parsed || {})) {
+    if (process.env[k] === v) {
+      globalThis.__cardbuddyDotenvInjected = Object.assign(globalThis.__cardbuddyDotenvInjected || {}, { [k]: v })
+    }
+  }
 }
 
 const args = process.argv.slice(2)
@@ -42,6 +49,7 @@ if (args.includes('--help') || args.includes('-h')) {
   --preview, -p  同时托管打包后的编辑器前端（本地预览），替代线上地址，并自动打开浏览器
                  旧名 --offline / -o 仍可用，已废弃
   --help, -h     显示帮助
+  init            初始化项目骨架：创建 src/cards/ 目录，释放内置技能脚本到 skills/，生成模板 .env.cb
 
 环境变量:
   DSL_CARD_ROOT   卡片仓库根目录（默认 cwd）
@@ -50,6 +58,9 @@ if (args.includes('--help') || args.includes('-h')) {
   DSL_DEV_TOKEN   可选鉴权 token
   DSL_DEV_PREVIEW=1 等价于 --preview
   DSL_PREVIEW_ROOT  自定义 preview 前端构建产物目录（默认包内 dist/preview-editor，回退 cwd/dist）
+  DSL_DEV_PORT_TAKEOVER=auto|force|off
+                  端口被占用时的接管策略。auto（默认）自动结束占用端口的旧 cardbuddy 实例后启动；
+                  force 连无关进程一并结束；off 关闭前置检查（退回原生 EADDRINUSE 报错）
 
 已废弃别名（仍生效）：--offline / -o、DSL_DEV_OFFLINE、DSL_OFFLINE_ROOT
 `)

package/dist/config.js

@@ -3,13 +3,14 @@
  *
  * 约定：
  *   - 项目根默认 process.cwd()，可用 DSL_CARD_ROOT 覆盖。
- *   - 监听端口默认 8787，由 FINMALL_CARD_PORT 控制（.env.finmall 单一真值）；
+ *   - 监听端口默认 8787，由 FINMALL_CARD_PORT 控制（.env.cb 单一真值）；
  *     兼容旧 DSL_DEV_PORT（主仓库 tools/dev.mjs / prod-preview.mjs 注入）。
  *     前端 resolveApiBase 的 DEV 默认端口同样读 FINMALL_CARD_PORT，保持三者一致。
  *   - 编辑器 URL 默认 http://127.0.0.1:5180（EDITOR_URL），供截图使用。
  *   - 仅绑定 127.0.0.1；token / https 为可选增强。
  */
 import path from 'node:path'
+import fs from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -29,11 +30,21 @@ export function loadConfig(env = process.env) {
   const truthy = (value) => value === '1' || value === 'true'
   const preview = truthy(env.DSL_DEV_PREVIEW) || truthy(env.DSL_DEV_OFFLINE)
   const previewRoot = env.DSL_PREVIEW_ROOT || env.DSL_OFFLINE_ROOT || ''
+  // 端口接管策略：启动时若目标端口已被「上一个 cardbuddy 实例」占用，主动结束旧进程再接管，
+  // 免去手动 lsof + kill（详见 src/portGuard.js）。
+  //   auto（默认）只结束能确认是本服务的进程；force 连无关进程一并结束；off 关闭前置检查，
+  //   退回原生 EADDRINUSE 行为。
+  const takeover = String(env.DSL_DEV_PORT_TAKEOVER || 'auto').toLowerCase()
+  const portTakeover = ['auto', 'force', 'off'].includes(takeover) ? takeover : 'auto'
   // FinMall 远端站点基址：资源代理（createAssetProxyMiddleware）回源用。
-  // 由 .env.finmall 的 FINMALL_BASE_URL 经启动器（tools/dev.mjs / prod-preview.mjs）
+  // 由 .env.cb 的 FINMALL_BASE_URL 经启动器（tools/dev.mjs / prod-preview.mjs）
   // 注入到本进程 env；缺省空串表示不回源（/minio 等只走占位图兜底）。
   const upstream = env.FINMALL_BASE_URL || ''
 
+
+  const repoSkillsDir = path.resolve(process.cwd(), 'skills')
+  const vendoredSkillsDir = path.resolve(__dirname, 'vendored', 'skills')
+
   return {
     root,
     port,
@@ -44,6 +55,7 @@ export function loadConfig(env = process.env) {
     preview,
     previewRoot,
     upstream,
+    portTakeover,
     // 包内 vendored 运行时快照（build 阶段从 preview/ 复制到 dist/vendored）：SSR 端点
     // 所需的编辑器运行时（components/* + runtime/*）全量快照，使发布后无需消费者持有编辑器源码。
     //   - 源码运行（src/cli.js，__dirname=.../src）：此处指向 .../src/vendored（不存在）→
@@ -53,11 +65,17 @@ export function loadConfig(env = process.env) {
     vendoredRuntimeDir: path.resolve(__dirname, 'vendored'),
     // 仓库内开发回退：从仓库根运行时（cwd=仓库根）能直接命中 preview/，无需先 build。
     repoPreviewDir: path.resolve(process.cwd(), 'preview'),
+    // 包内 vendored 技能脚本（build 阶段从 skills/ 复制到 dist/vendored/skills）：运行时回退
+    vendoredSkillsDir,
+    // 仓库内 skills/ 目录（开发期直接命中）
+    repoSkillsDir,
     // 发布态包内自带的预览编辑器构建产物（build.mjs 从 ../../dist 复制到 dist/preview-editor）。
     previewEditorDir: path.resolve(__dirname, 'preview-editor'),
     // 兼容旧包布局（<= 0.5.x 的 dist/offline-editor）：存在时作为回退，避免升级后 --preview 找不到前端。
     legacyOfflineEditorDir: path.resolve(__dirname, 'offline-editor'),
     // 仓库内开发回退：根目录 npm run build 的产物 dist/。
     repoDistDir: path.resolve(process.cwd(), 'dist'),
+    // 技能脚本根目录：优先用户项目 skills/，否则回退包内 vendored
+    skillsRoot: fs.existsSync(repoSkillsDir) ? repoSkillsDir : (fs.existsSync(vendoredSkillsDir) ? vendoredSkillsDir : null),
   }
 }

package/dist/portGuard.js

@@ -0,0 +1,293 @@
+/**
+ * 端口占用守卫 —— cardbuddy 启动前置检查。
+ *
+ * 背景：编辑器 / dev 启动器重启时，上一个 cardbuddy 进程偶尔不会被回收干净（终端直接关掉、
+ * Ctrl+C 漏杀、后台残留等），新实例便以 EADDRINUSE 直接启动失败，开发者只能手动
+ * `lsof -ti tcp:8787 | xargs kill`。这里把这套动作内置进启动流程：
+ *   探测端口 → 定位占用进程 → 确认是本服务 → SIGTERM（宽限期后 SIGKILL）→ 等端口真正释放。
+ *
+ * 安全边界：默认（mode='auto'）只结束「能确认是 cardbuddy」的进程 —— HTTP 探测 /__cards 命中
+ * 本服务响应，或命令行含 cardbuddy / dsl-card 字样；占用者是无关进程时不动手，直接报错并给出
+ * 手动处理命令。确需强制接管用 DSL_DEV_PORT_TAKEOVER=force，完全关闭前置检查用 off。
+ *
+ * 跨平台：macOS / Linux 走 lsof（缺失时回退 ss），Windows 走 netstat -ano + taskkill。
+ */
+import net from 'node:net'
+import http from 'node:http'
+import https from 'node:https'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import chalk from 'chalk'
+
+const execFileAsync = promisify(execFile)
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/** 命令行特征：命中即认为是本服务（覆盖 npx cardbuddy、node .../packages/cardbuddy/src/cli.js 等启动形态）。 */
+const OWN_COMMAND_RE = /cardbuddy|dsl-card/i
+
+const POLL_INTERVAL_MS = 120
+const TERM_GRACE_MS = 2500
+const KILL_GRACE_MS = 2000
+const PROBE_TIMEOUT_MS = 900
+
+/** 执行外部命令；失败（含 lsof 无匹配时的退出码 1）一律退化为空输出，由调用方按「没找到」处理。 */
+async function tryExec(cmd, args) {
+  try {
+    const { stdout } = await execFileAsync(cmd, args, { windowsHide: true, timeout: 5000 })
+    return String(stdout || '')
+  } catch (err) {
+    return String(err?.stdout || '')
+  }
+}
+
+/** 试绑端口判断是否空闲：比 TCP connect 更贴近「我到底能不能 listen」这个真实问题。 */
+export function probePort(port, host = '127.0.0.1') {
+  return new Promise((resolve) => {
+    const tester = net.createServer()
+    tester.once('error', (err) => resolve({ free: false, code: err?.code || 'ERROR' }))
+    tester.once('listening', () => tester.close(() => resolve({ free: true, code: null })))
+    tester.listen(port, host)
+  })
+}
+
+function manualHint(port) {
+  return process.platform === 'win32'
+    ? `netstat -ano | findstr :${port} → taskkill /PID <pid> /F`
+    : `lsof -ti tcp:${port} | xargs kill -9`
+}
+
+/** Windows：解析 `netstat -ano -p TCP` 的 LISTENING 行。 */
+export function parseWindowsNetstat(stdout, port) {
+  const pids = new Set()
+  for (const line of String(stdout).split(/\r?\n/)) {
+    const cols = line.trim().split(/\s+/)
+    if (cols.length < 5 || cols[0].toUpperCase() !== 'TCP') continue
+    if (!cols[1].endsWith(`:${port}`) || !/LISTENING/i.test(cols[3])) continue
+    const pid = Number(cols[4])
+    if (Number.isInteger(pid) && pid > 0) pids.add(pid)
+  }
+  return [...pids]
+}
+
+/** Linux 回退（无 lsof 时）：解析 `ss -ltnp` 的 users:(("node",pid=1234,fd=23))。 */
+export function parseSs(stdout, port) {
+  const pids = new Set()
+  for (const line of String(stdout).split(/\r?\n/)) {
+    const cols = line.trim().split(/\s+/)
+    if (cols.length < 4 || !/LISTEN/i.test(cols[0])) continue
+    if (!cols[3].endsWith(`:${port}`)) continue
+    for (const m of line.matchAll(/pid=(\d+)/g)) pids.add(Number(m[1]))
+  }
+  return [...pids]
+}
+
+/** 定位监听该端口的进程 pid（已排除本进程）。 */
+export async function findListenerPids(port) {
+  let pids = []
+  if (process.platform === 'win32') {
+    pids = parseWindowsNetstat(await tryExec('netstat', ['-ano', '-p', 'TCP']), port)
+  } else {
+    pids = String(await tryExec('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t']))
+      .split(/\s+/)
+      .map(Number)
+      .filter((n) => Number.isInteger(n) && n > 0)
+    if (!pids.length) pids = parseSs(await tryExec('ss', ['-ltnp']), port)
+  }
+  return [...new Set(pids)].filter((pid) => pid !== process.pid)
+}
+
+/** 取进程命令行：既用于日志，也是「是不是本服务」的兜底判据。 */
+export async function readProcessCommand(pid) {
+  if (process.platform === 'win32') {
+    const out = await tryExec('powershell', [
+      '-NoProfile',
+      '-Command',
+      `(Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}').CommandLine`,
+    ])
+    const line = out.trim().split(/\r?\n/).filter(Boolean).pop()
+    if (line) return line
+    const csv = await tryExec('tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH'])
+    return csv.split('","')[0].replace(/"/g, '').trim()
+  }
+  const out = await tryExec('ps', ['-p', String(pid), '-o', 'command='])
+  return out.trim().split(/\r?\n/)[0] || ''
+}
+
+export async function findPortOwners(port) {
+  const owners = []
+  for (const pid of await findListenerPids(port)) {
+    owners.push({ pid, command: await readProcessCommand(pid) })
+  }
+  return owners
+}
+
+/** 判定响应是否来自 cardbuddy：/__cards 的 { cards: [...] }，或 token 鉴权失败的 403。 */
+export function classifyProbe(status, body) {
+  const text = String(body || '')
+  if (status === 403 && /x-dev-token/i.test(text)) return { ours: true, detail: 'token 鉴权 403' }
+  if (status !== 200) return { ours: false, detail: `HTTP ${status}` }
+  try {
+    const json = JSON.parse(text)
+    if (json && Array.isArray(json.cards)) return { ours: true, detail: `${json.cards.length} 张卡片` }
+  } catch {
+    /* 非 JSON：不是本服务 */
+  }
+  return { ours: false, detail: 'HTTP 200（非 cardbuddy 响应）' }
+}
+
+function probeOnce(client, port, token, timeout) {
+  return new Promise((resolve) => {
+    const req = client.get(
+      {
+        host: '127.0.0.1',
+        port,
+        path: '/__cards',
+        timeout,
+        rejectUnauthorized: false,
+        headers: token ? { 'x-dev-token': token } : {},
+      },
+      (res) => {
+        let body = ''
+        res.setEncoding('utf8')
+        res.on('data', (chunk) => {
+          body += chunk
+          if (body.length > 256 * 1024) req.destroy()
+        })
+        res.on('end', () => resolve(classifyProbe(res.statusCode, body)))
+        res.on('error', () => resolve(null))
+      }
+    )
+    req.on('timeout', () => {
+      req.destroy()
+      resolve(null)
+    })
+    req.on('error', () => resolve(null))
+  })
+}
+
+/** 探测端口上的服务是不是 cardbuddy：先按本次启动的协议试，再试另一种（旧实例可能协议不同）。 */
+export async function probeService(port, { token = '', tls = false, timeout = PROBE_TIMEOUT_MS } = {}) {
+  let foreign = null
+  for (const client of tls ? [https, http] : [http, https]) {
+    const hit = await probeOnce(client, port, token, timeout)
+    if (hit?.ours) return hit
+    if (hit && !foreign) foreign = hit
+  }
+  return foreign || { ours: false, detail: '无有效响应' }
+}
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return err?.code === 'EPERM'
+  }
+}
+
+/** 结束进程：POSIX 走信号（SIGTERM 给旧实例一次优雅关闭的机会），Windows 走 taskkill /T /F。 */
+async function terminate(pid, sig) {
+  if (process.platform === 'win32') {
+    await tryExec('taskkill', ['/PID', String(pid), '/T', '/F'])
+    return
+  }
+  try {
+    process.kill(pid, sig)
+  } catch {
+    /* ESRCH：已经退出 */
+  }
+}
+
+async function waitForPortFree(port, host, budgetMs) {
+  const deadline = Date.now() + budgetMs
+  for (;;) {
+    const { free } = await probePort(port, host)
+    if (free) return true
+    if (Date.now() >= deadline) return false
+    await sleep(POLL_INTERVAL_MS)
+  }
+}
+
+async function terminateOwner(owner, { port, host, log }) {
+  await terminate(owner.pid, 'SIGTERM')
+  let freed = await waitForPortFree(port, host, TERM_GRACE_MS)
+  if (!freed && isAlive(owner.pid)) {
+    log(chalk.dim(`PID ${owner.pid} 在 ${TERM_GRACE_MS}ms 内未退出，升级为 SIGKILL …`))
+    await terminate(owner.pid, 'SIGKILL')
+    freed = await waitForPortFree(port, host, KILL_GRACE_MS)
+  }
+  if (!freed) {
+    throw new Error(`无法释放端口 ${port}（PID ${owner.pid} 仍占用）。手动排查：${manualHint(port)}`)
+  }
+  log(chalk.green(`旧进程 PID ${owner.pid} 已结束，端口 ${port} 已释放。`))
+}
+
+/**
+ * 确保端口可用；被旧的 cardbuddy 实例占用时主动结束它。
+ *
+ * @param {object} opts
+ * @param {number} opts.port                    目标端口
+ * @param {string} [opts.host]                  绑定地址（默认 127.0.0.1）
+ * @param {boolean} [opts.tls]                  本次是否以 HTTPS 启动（决定探测顺序）
+ * @param {string} [opts.token]                DSL_DEV_TOKEN，探测时带上
+ * @param {'auto'|'force'|'off'} [opts.mode]    接管策略（DSL_DEV_PORT_TAKEOVER）
+ * @param {(msg: string) => void} [opts.log]    日志输出
+ * @returns {Promise<{ freed: Array<{pid:number,command:string}>, skipped: Array<{pid:number,command:string}> }>}
+ */
+export async function ensurePortFree({
+  port,
+  host = '127.0.0.1',
+  tls = false,
+  token = '',
+  mode = 'auto',
+  log = (msg) => console.log(msg),
+}) {
+  const result = { freed: [], skipped: [] }
+  if (mode === 'off') return result
+
+  const before = await probePort(port, host)
+  if (before.free) return result
+  if (before.code !== 'EADDRINUSE') {
+    throw new Error(`端口 ${port} 无法绑定（${before.code}）。请检查权限，或用 FINMALL_CARD_PORT 换一个端口。`)
+  }
+
+  const owners = await findPortOwners(port)
+  if (!owners.length) {
+    throw new Error(`端口 ${port} 已被占用，但未能定位占用进程。手动排查：${manualHint(port)}`)
+  }
+
+  const identity = await probeService(port, { token, tls })
+  for (const owner of owners) {
+    const ours = identity.ours || OWN_COMMAND_RE.test(owner.command || '')
+    if (!ours && mode !== 'force') {
+      result.skipped.push(owner)
+      continue
+    }
+    log(
+      chalk.yellow(`端口 ${port} 已被占用`) +
+        chalk.dim(` → PID ${owner.pid}${owner.command ? ` ${owner.command}` : ''}`) +
+        chalk.dim(
+          ours
+            ? `（cardbuddy 旧实例${identity.ours ? `，${identity.detail}` : ''}），正在结束并接管…`
+            : '（非 cardbuddy 进程，force 接管）'
+        )
+    )
+    await terminateOwner(owner, { port, host, log })
+    result.freed.push(owner)
+  }
+
+  if (result.skipped.length) {
+    const list = result.skipped.map((o) => `PID ${o.pid}${o.command ? ` — ${o.command}` : ''}`).join('\n  ')
+    throw new Error(
+      `端口 ${port} 被非 cardbuddy 进程占用，未自动结束：\n  ${list}\n` +
+        `请手动处理（${manualHint(port)}），或用 FINMALL_CARD_PORT 换端口；确需强制接管设 DSL_DEV_PORT_TAKEOVER=force。`
+    )
+  }
+
+  const after = await probePort(port, host)
+  if (!after.free) {
+    throw new Error(`结束旧进程后端口 ${port} 仍被占用（${after.code}）。手动排查：${manualHint(port)}`)
+  }
+  return result
+}