nx-sk 0.15.2 → 0.15.3

package/CHANGELOG.md

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

package/README.md

@@ -130,10 +130,14 @@ CLI 与 API 同源，skill 驱动 agent**。落到具体功能上：
 
 | 命令 | 作用 |
 | --- | --- |
-| `nx-sk serve [--port N] [--no-open]` | 起 Web 面板（唯一常驻命令；默认只绑 `127.0.0.1`） |
+| `nx-sk serve [--port N] [--no-open]` | 起 Web 面板（唯一常驻命令；默认只绑 `127.0.0.1`；端口上已有本面板就直接打开它，被别的服务占了就顺延到下一个空闲端口） |
 | `nx-sk help [主题]` | 命令表（由 action 声明生成，不是手写） |
 | `nx-sk version` | 裸输出版本号 |
 
+端口被占不会报错退出：占用者就是**本项目自己的面板** → 不重复启动，直接把浏览器指向它；
+占用者是别的服务 → 顺延到下一个空闲端口起自己的面板，并把浏览器指向新面板。
+不想开浏览器：`--no-open`（只影响这一次）或 `NX_SERVE_NO_OPEN=1`（所有 nx-xx 项目通用的开关，对整个 shell 生效）。
+
 模块命令（`src/modules/*/index.js` 声明，`nx-sk routes` 可双向查）：
 
 | 命令 | 作用 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-sk",
-  "version": "0.15.2",
+  "version": "0.15.3",
   "description": "nx-sk · 本机个人资源管理器（server-cli-web 骨架）：栏目化存储个人信息与大模型密钥，CLI 与 Web 同源，敏感字段密文落盘。",
   "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/runtime/cli.js

@@ -17,23 +17,47 @@ async function cmdServe(ctx) {
   const { openBrowser } = await import('../core/open.js');
   const { loadStore, storePathInUse } = await import('../core/store.js');
   const { appHome, displayPath } = await import('../core/paths.js');
+  const { autoOpenEnabled, resolvePortConflict, describeOccupant } = await import('../core/serve-port.js');
 
   await loadStore(); // 触发首次播种：面板一打开就该有「求职」栏目
+  const host = '127.0.0.1';
+  // --port 0 = 让 OS 挑一个空闲端口（测试用），所以这里不能用 DEFAULT_PORT 兜底
+  const desiredPort = ctx.port;
+  // --no-open 与 NX_SERVE_NO_OPEN 走同一个开关：任一为真就不开浏览器
+  const canOpen = autoOpenEnabled(ctx['no-open']);
+  // --json 分支的字段形状：正常启动与复用旧实例共用一份，避免两条路径漂移
+  const jsonLine = (u, p) => JSON.stringify({
+    url: u, port: p, host, pid: process.pid,
+    storePath: displayPath(storePathInUse()), storePathRaw: storePathInUse(), home: displayPath(appHome()),
+  }) + '\n';
+  // --json 模式下 stdout 只能有 JSON，人类可读的行改走 stderr
+  const say = (s) => (OUTPUT_JSON ? process.stderr : process.stdout).write(s + '\n');
+
   let server;
   try {
-    server = await startServer({ port: ctx.port });
+    server = await startServer({ port: desiredPort });
   } catch (e) {
-    if (e && e.code === 'EADDRINUSE') throw external(`端口 ${ctx.port} 已被占用；换一个：nx-sk serve --port ${ctx.port + 1}（或在 nxSk.port 里改默认端口）`);
-    throw external(`启动服务失败: ${e && e.message ? e.message : String(e)}`);
+    if (!e || e.code !== 'EADDRINUSE') throw external(`启动服务失败: ${e && e.message ? e.message : String(e)}`);
+    // 端口被占：先问一句「上面跑的是不是我」。
+    const decision = await resolvePortConflict(desiredPort, APP_NAME, host);
+    if (decision.action === 'reuse') {
+      // 自己的面板已经在跑：不重复启动，直接把浏览器指过去。
+      const runningUrl = `http://${host}:${desiredPort}`;
+      say(APP_NAME + ' 已在运行：' + runningUrl);
+      say('直接打开浏览器（不重复启动）；如需重启请先停掉旧实例');
+      if (OUTPUT_JSON) process.stdout.write(jsonLine(runningUrl, desiredPort));
+      if (canOpen) await openBrowser(runningUrl);
+      return { status: 'reused', url: runningUrl, port: desiredPort, host, pid: process.pid };
+    }
+    // 别人占的：顺延到下一个空闲端口，再起自己的面板。
+    say(`端口 ${desiredPort} 已被占用（占用者: ${describeOccupant(decision.occupant)}），改用 ${decision.port}`);
+    server = await startServer({ port: decision.port });
   }
   // --port 0 = 让 OS 挑一个空闲端口（测试用），所以真实端口要回读，不能信入参
-  const realPort = server.address() && typeof server.address() === 'object' ? server.address().port : ctx.port;
+  const realPort = server.address() && typeof server.address() === 'object' ? server.address().port : desiredPort;
   const url = `http://127.0.0.1:${realPort}`;
   if (OUTPUT_JSON) {
-    process.stdout.write(JSON.stringify({
-      url, port: realPort, host: '127.0.0.1', pid: process.pid,
-      storePath: displayPath(storePathInUse()), storePathRaw: storePathInUse(), home: displayPath(appHome()),
-    }) + '\n');
+    process.stdout.write(jsonLine(url, realPort));
   } else {
     process.stdout.write([
       `面板:   ${url}`,
@@ -42,7 +66,7 @@ async function cmdServe(ctx) {
       '机器可读: nx-sk serve --json（先打一行 JSON，再继续常驻）',
     ].join('\n') + '\n');
   }
-  if (!ctx['no-open']) await openBrowser(url);
+  if (canOpen) await openBrowser(url);
 
   await new Promise((done) => {
     let closed = false;
@@ -64,7 +88,7 @@ const BUILTINS = [
     module: 'system',
     cli: ['serve'],
     http: null,
-    summary: '启动 Web 面板（唯一常驻命令；--no-open 给开发与 CI 用）',
+    summary: '启动 Web 面板（默认 :7866；--port N 改端口；--no-open 不开浏览器；端口上已有本面板则直接打开它；NX_SERVE_NO_OPEN=1 全局不开浏览器）',
     flags: { port: { type: 'number', default: DEFAULT_PORT }, 'no-open': { type: 'boolean' } },
     run: (ctx) => cmdServe(ctx),
     render: () => '',