nx-kv 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 ## [Unreleased]
 
+## [0.10.1] - 2026-10-20
+
+### Changed
+
+- **端口被占用时不再报错退出：自动复用或顺延，并把浏览器指过去**。`serve` 绑定端口
+  遇到 `EADDRINUSE` 时，先探测该端口上的 `/api/bootstrap`：占用者**就是本项目的面板**
+  （`app.name` 相同）就直接复用它——不再起第二个进程——并打开浏览器指向它；占用者是
+  别的服务（或探测不出来）则顺延到**下一个空闲端口**起自己的面板，并打开浏览器指向新
+  面板，不会把浏览器指向别人的服务。
+- **跨项目统一的关闭开关 `NX_SERVE_NO_OPEN`**：设成 `1` / `true` / `yes` / `on` 时
+  `serve` 完全不开浏览器（所有 nx-xx 项目共用这一个变量名）；`--no-open` 仍然只关
+  当前这一次。
+
 ## [0.10.0] - 2026-10-20
 
 ### Added

package/README.md

@@ -28,6 +28,13 @@ pnpm test
 
 冒烟测试**对着假后端跑**（`tests/fake-backend.mjs`），不会碰生产服务器上的真实数据。
 
+`nx-kv serve` 默认会打开浏览器；**端口被占时不会报错退出**：
+
+- 占用者**就是本项目的面板** → 直接复用它（不重复起进程），并打开它；
+- 占用者是别的服务 → 顺延到**下一个空闲端口**起自己的面板，并打开它。
+
+`--no-open` 只关这一次；`NX_SERVE_NO_OPEN=1`（`true` / `yes` / `on` 同义）则是**所有 nx-xx 项目共用**的全局开关，设为真值后 `serve` 完全不开浏览器。
+
 ## 登录
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-kv",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "nx-kv — KV 清单管理中枢（远程）+ 本机本地任务队列（localtask）：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 提交 / 领取 / 阻塞接收任务",
   "type": "module",
   "bin": {

package/src/core/serve-port.js

@@ -0,0 +1,139 @@
+// serve 的端口协商 + 浏览器打开策略。
+//
+// 零业务语义：所有 nx-xx 面板共用这一份，靠环境变量 NX_SERVE_NO_OPEN 统一关闭自动开浏览器。
+// 放 core/ 是因为它只依赖 Node 内置模块与「本项目的 app 名」，不涉及任何功能域。
+//
+// 这份文件在所有 nx-xx 项目之间**逐字节相同**——改一处就要全量同步，
+// 否则「口径统一」这件事本身会悄悄分叉。
+import net from 'node:net';
+
+/**
+ * 所有 nx-xx 项目共享的关闭开关。
+ * 设成 1 / true / yes / on 即禁止 `serve` 自动打开浏览器（正常启动与端口复用都算）。
+ * 命令行 `--no-open` 只影响这一次；这个环境变量对整个 shell 生效。
+ */
+export const NO_OPEN_ENV = 'NX_SERVE_NO_OPEN';
+
+/**
+ * 探测面板时给的应答窗口。
+ *
+ * 1500ms 而不是更短：面板的 bootstrap 不一定是纯本机计算——nx-kv 登录后要去后端
+ * 拉分组，链路一慢就超过 800ms。窗口太窄的后果不是「探测失败」这么轻，
+ * 而是**把自己的面板误判成别人的服务**，于是白起一个实例、占掉第二个端口——
+ * 恰好是这套机制要消灭的那种体验。
+ */
+export const PROBE_TIMEOUT_MS = 1500;
+
+/** 真值判定：1 / true / yes / on（大小写不敏感）算开，其他一律算关。 */
+export function isEnvTruthy(value) {
+  if (value === undefined || value === null) return false;
+  const s = String(value).trim().toLowerCase();
+  return s === '1' || s === 'true' || s === 'yes' || s === 'on';
+}
+
+/**
+ * 是否允许自动打开浏览器。
+ * 优先级：`--no-open` 命令行开关 > NX_SERVE_NO_OPEN 环境变量 > 默认允许。
+ */
+export function autoOpenEnabled(flagNoOpen) {
+  if (flagNoOpen) return false;
+  return !isEnvTruthy(process.env[NO_OPEN_ENV]);
+}
+
+/**
+ * 探一次端口，返回 { data, timedOut }。
+ *
+ * 把「超时」和「不是面板」分开，是因为两者的后续动作不同：
+ * 超时说明端口上可能正是一个应答慢的面板，值得再等一次；
+ * 明确不是面板就没有再等的必要。
+ */
+async function probePanelOnce(port, host, timeoutMs, headers) {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+      res = await fetch(`http://${host}:${port}/api/bootstrap`, {
+        signal: controller.signal,
+        headers: headers || undefined,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!res.ok) return { data: null, timedOut: false };
+    const body = await res.json();
+    return { data: (body && body.data) || null, timedOut: false };
+  } catch (err) {
+    return { data: null, timedOut: !!(err && err.name === 'AbortError') };
+  }
+}
+
+/**
+ * 探测端口上有没有面板在跑：GET /api/bootstrap，短超时。
+ *
+ * 所有 nx-xx 面板都暴露 /api/bootstrap，响应里带 app.name / app.version ——
+ * 这就是跨项目唯一的认领签名（别的服务不会恰好返回它）。
+ * 不是面板、无响应、超时一律返回 null。
+ *
+ * headers 形参给需要鉴权的项目用（nx-as 的管理面要 Bearer 密钥）；
+ * 默认不传，匿名探测。
+ */
+export async function probePanel(port, host = '127.0.0.1', timeoutMs = PROBE_TIMEOUT_MS, headers = null) {
+  const { data } = await probePanelOnce(port, host, timeoutMs, headers);
+  return data;
+}
+
+/**
+ * 从 start 起逐个试，返回第一个能监听的端口（最多试 50 个）。
+ * 用临时 net.Server 探测、立刻关闭；与 startServer 走同一套 EADDRINUSE 判定。
+ */
+export function findFreePort(start, host = '127.0.0.1') {
+  return new Promise((resolve_, reject) => {
+    const tryPort = (p) => {
+      if (p > start + 50) {
+        reject(new Error(`找不到空闲端口（从 ${start} 起连续 50 个被占）`));
+        return;
+      }
+      const probe = net.createServer();
+      probe.once('error', (err) => {
+        if (err && err.code === 'EADDRINUSE') tryPort(p + 1);
+        else reject(err);
+      });
+      probe.listen(p, host, () => probe.close(() => resolve_(p)));
+    };
+    tryPort(start);
+  });
+}
+
+/**
+ * 端口冲突的统一决策。
+ *
+ * reuse —— 端口上跑的就是本项目的面板：复用它，不再起第二个进程。
+ *          起第二个会让「切项目」变成「切端口」，而用户想看的其实是已经开着的那一个。
+ * shift —— 端口被别的东西占着：顺延到下一个空闲端口，再起自己的面板。
+ *
+ * 返回 { action, port, occupant, existing }：
+ *   action   'reuse' | 'shift'
+ *   port     reuse 时是原端口；shift 时是下一个空闲端口
+ *   occupant 占用者的 app 名（探测不到就是 null）
+ */
+export async function resolvePortConflict(port, appName, host = '127.0.0.1', headers = null) {
+  let probe = await probePanelOnce(port, host, PROBE_TIMEOUT_MS, headers);
+  if (probe.timedOut) {
+    // 慢应答的面板也认：再等一次。别把「自己的面板」误判成「别人的服务」，
+    // 白白再起一个实例——那正是这套机制要消灭的行为。
+    probe = await probePanelOnce(port, host, PROBE_TIMEOUT_MS, headers);
+  }
+  const existing = probe.data;
+  const occupant = existing && existing.app ? existing.app.name || null : null;
+  if (existing && occupant === appName) {
+    return { action: 'reuse', port, occupant, existing };
+  }
+  const next = await findFreePort(port + 1, host);
+  return { action: 'shift', port: next, occupant, existing };
+}
+
+/** 占用者的一句话描述，用于终端提示。探测不到就是「未知服务」。 */
+export function describeOccupant(occupant) {
+  return occupant || '未知服务';
+}

package/src/modules/system/index.js

@@ -5,7 +5,7 @@ import { readFileSync } from 'node:fs';
 import { configPathFromEnv, loadConfig } from '../../core/config.js';
 import { badInput, notFound } from '../../core/errors.js';
 import { listGroups } from '../../core/kvapi.js';
-import { DEFAULT_PORT } from '../../core/paths.js';
+import { APP_NAME, DEFAULT_PORT } from '../../core/paths.js';
 
 const VERSION = JSON.parse(
   readFileSync(new URL('../../../package.json', import.meta.url), 'utf8')
@@ -33,6 +33,9 @@ async function bootstrap() {
     }
   }
   return {
+    // app 段是跨项目的认领签名：serve 端口被占时靠 app.name 判断
+    // 「上面跑的是不是本项目的面板」——相等则复用，不等则顺延端口。
+    app: { name: APP_NAME, version: VERSION },
     version: VERSION,
     configPath: configPathFromEnv(),
     baseUrl: cfg.baseUrl,

package/src/runtime/cli.js

@@ -4,7 +4,7 @@
 // renderXxx 四处重复登记。现在命令表、help 文本、参数校验全部由 action 声明派生，
 // 新增命令只需在所属模块的 actions 里加一条。
 import { readFileSync } from 'node:fs';
-import { DEFAULT_PORT } from '../core/paths.js';
+import { APP_NAME, DEFAULT_PORT } from '../core/paths.js';
 import { configPathFromEnv } from '../core/config.js';
 import { toErrorPayload, exitCodeOf, badInput } from '../core/errors.js';
 import { ACTIONS, MODULES } from './registry.js';
@@ -20,7 +20,7 @@ const BUILTINS = [
   {
     id: 'serve',
     cli: ['serve'],
-    summary: '启动 Web 面板',
+    summary: '启动 Web 面板（默认 :7877；--port N 改端口；--no-open 不开浏览器；端口上已有本面板则直接打开它；NX_SERVE_NO_OPEN=1 全局不开浏览器）',
     flags: {
       port: { type: 'number', default: DEFAULT_PORT },
       'no-open': { type: 'boolean' },
@@ -256,13 +256,42 @@ async function cmdServe(ctx) {
   const { startServer } = await import('./server.js');
   const { startPanelIdleGuard } = await import('../modules/localtask/panel-guard.js');
   const { openBrowser } = await import('../core/open.js');
+  const { autoOpenEnabled, resolvePortConflict, describeOccupant } = await import('../core/serve-port.js');
+  const host = '127.0.0.1';
   const port = ctx.port || DEFAULT_PORT;
   const autoExit = !!ctx['auto-exit'];
+  // --no-open 与 NX_SERVE_NO_OPEN 都看这里：任一为真即完全不开浏览器。
+  const canOpen = autoOpenEnabled(ctx['no-open']);
 
   // 活动观测钩子：每个进来的请求（静态或 /api）都回调一次，供空闲自释放判活。
   // 不参与响应，异常必须吞掉。
   const onRequest = () => {};
-  const server = await startServer({ port, host: '127.0.0.1', onRequest });
+
+  let server;
+  try {
+    server = await startServer({ port, host, onRequest });
+  } catch (err) {
+    if (!err || err.code !== 'EADDRINUSE') throw err;
+
+    // 端口被占：先问一句「上面跑的是不是我」。
+    const decision = await resolvePortConflict(port, APP_NAME, host);
+
+    if (decision.action === 'reuse') {
+      // 自己的面板已经在跑：不重复启动，直接把浏览器指过去。
+      const addr = `http://${host}:${port}`;
+      console.log(APP_NAME + ' 已在运行：' + addr);
+      console.log('直接打开浏览器（不重复启动）；如需重启请先停掉旧实例');
+      if (canOpen) openBrowser(addr);
+      return;
+    }
+
+    // 别人占的：顺延到下一个空闲端口，再起自己的面板。
+    console.log(
+      `端口 ${port} 已被占用（占用者: ${describeOccupant(decision.occupant)}），改用 ${decision.port}`
+    );
+    server = await startServer({ port: decision.port, host, onRequest });
+  }
+
   const addr = `http://127.0.0.1:${server.address().port}`;
 
   console.log('nx-kv · nx-kv v' + VERSION);
@@ -272,7 +301,7 @@ async function cmdServe(ctx) {
   if (autoExit) console.log('模式:   空闲自释放（面板关闭且无等待中的主题后自动退出）');
   console.log('按 Ctrl+C 停止');
 
-  if (!ctx['no-open']) openBrowser(addr);
+  if (canOpen) openBrowser(addr);
 
   const shutdown = () => {
     console.log('\n正在停止...');