@jacksontian/kite-server 0.3.0 → 0.4.1

package/lib/broadcast.js

@@ -0,0 +1,31 @@
+/**
+ * WebSocket 实时推送：控制台通过 /ws 建立长连接，任务变更即时下发；
+ * Worker 通过 /worker/ws 建立长连接，仅接收任务到达通知。
+ * 本模块只维护已鉴权连接集合与广播函数，连接建立见 lib/websocket.js。
+ */
+
+export function createChannels() {
+  // 已鉴权连接集合（未通过鉴权的 socket 不会进入此集合）
+  const wsClients = new Set();
+
+  function broadcast(msg) {
+    if (!wsClients.size) return;
+    const data = JSON.stringify(msg);
+    for (const ws of wsClients) ws.send(data);
+  }
+
+  // 已鉴权的 Worker 通知连接（见 lib/websocket.js 的 /worker/ws）。通知只是加速：
+  // Worker 收到后仍走 HTTP claim 原子领取，断线期间由轮询兜底
+  const wsWorkers = new Set();
+
+  // 显式指派模型：只唤醒指名 Worker 的连接，其他 Worker 完全不被打扰
+  function notifyWorkers(targetWorker) {
+    if (!wsWorkers.size || !targetWorker) return;
+    const data = JSON.stringify({ type: 'task.available', targetWorker });
+    for (const ws of wsWorkers) {
+      if (ws.workerId === targetWorker) ws.send(data);
+    }
+  }
+
+  return { wsClients, broadcast, wsWorkers, notifyWorkers };
+}

package/lib/cli/args.js

@@ -0,0 +1,83 @@
+/**
+ * kites 子命令分发与 start/check 参数解析。
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+import { printHelp } from './meta.js';
+
+export const SUBCOMMANDS = ['start', 'check', 'keygen', 'init', 'deploy'];
+
+/** 缺省配置文件路径（start/check 不传 --config、init 不传路径时都用它）：
+ * ~/.kites 标准树的 conf/ 下，与 deploy 托管路径一致；运行时取 homedir，
+ * systemd 以 www-data 跑时即 /var/www/.kites/conf/server.yaml */
+export function defaultConfigFile() {
+  return path.join(os.homedir(), '.kites', 'conf', 'server.yaml');
+}
+
+/** 子命令分发：返回 argv[2] 的子命令名。CLI 化的核心约定——启动服务必须显式
+ * 走 start 子命令；裸 kites（不带任何参数）只打印用法退出，绝不启动服务 */
+export function dispatch() {
+  const cmd = process.argv[2];
+  if (cmd === undefined) {
+    printHelp();
+    process.exit(0);
+  }
+  if (SUBCOMMANDS.includes(cmd)) return cmd;
+  if (cmd === '--config' || cmd === '-c' || cmd.startsWith('--config=')) {
+    // 旧版写法（kites --config x）：明确告知启动已改为 start 子命令，不静默兼容
+    console.error('[server] 启动服务请显式使用 start 子命令：kites start --config <配置文件路径>');
+    console.error('[server] 运行 kites --help 查看用法');
+    process.exit(1);
+  }
+  console.error(`[server] 未知子命令 "${cmd}"；运行 kites --help 查看用法`);
+  process.exit(1);
+}
+
+/** check 子命令位参数（argv[2] === 'check'）：其余照常解析，校验通过后在
+ * loadServerConfig 末尾打印摘要退出，不真正启动服务 */
+export function isCheckMode() {
+  return process.argv[2] === 'check';
+}
+
+/** 解析 start/check 子命令后的参数；--config 可选（缺省回落 ~/.kites/conf/server.yaml），
+ * 重复/取不到值/出现未知参数立即退出 */
+export function parseArgs() {
+  const args = process.argv.slice(3);
+  const values = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--config' || args[i] === '-c') {
+      values.push(args[i + 1]);
+      i++;
+    } else if (args[i].startsWith('--config=')) {
+      values.push(args[i].slice('--config='.length));
+    } else {
+      // 输错参数不再静默忽略：报出具体参数并指路 --help，避免误以为已生效
+      console.error(`[server] 未知参数 "${args[i]}"；运行 kites --help 查看用法`);
+      process.exit(1);
+    }
+  }
+  if (values.length === 0) {
+    // 未指定 --config：回落默认配置路径（与 init 默认生成位置一致），先报一行让去向可追溯
+    const file = defaultConfigFile();
+    console.log(`[server] 未指定 --config，使用默认配置文件：${file}`);
+    return file;
+  }
+  if (values.length > 1) {
+    console.error('[server] --config 只能指定一次');
+    process.exit(1);
+  }
+  const file = String(values[0] ?? '').trim();
+  if (!file || file.startsWith('-')) {
+    console.error('[server] --config 后需要给出配置文件路径');
+    process.exit(1);
+  }
+  return path.resolve(file);
+}
+
+export function fail(errors, tag) {
+  console.error(`[${tag}] 配置错误，无法启动：`);
+  for (const e of errors) console.error('  - ' + e);
+  console.error(`[${tag}] 请检查 YAML 配置文件（--config 指定或默认路径），模板见包内 config.example.yaml`);
+  process.exit(1);
+}

package/lib/cli/deploy.js

@@ -0,0 +1,94 @@
+/**
+ * kites deploy 子命令：基于包内 systemd 模板生成托管 unit 文件。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import cp from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { expandHome } from './util.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** init/deploy 就跑在目标环境里，顺手解析 kites 可执行路径（等效 `which kites`），
+ * 好把 unit 安装命令里的 __KITES_BIN__ 占位符换成现成值；
+ * 取不到（如仓库源码里直接跑）则返回 null 由调用方决定回退方式 */
+async function resolveKitesBin() {
+  try {
+    // 调用时经 cp 命名空间取 execFile，单测可 mock cp.execFile
+    const stdout = await new Promise((resolve, reject) => {
+      cp.execFile('which', ['kites'], { encoding: 'utf8' }, (err, out) => (err ? reject(err) : resolve(out)));
+    });
+    const p = stdout.trim();
+    if (p) return p;
+  } catch { /* PATH 里没有 kites */ }
+  return null;
+}
+
+/** deploy 子命令（kites deploy [输出路径] [--config <配置文件路径>]）：
+ * 读取包内 systemd 模板，把 __KITES_BIN__ / __CONFIG_FILE__ 按本机环境替换后
+ * 写出可直接安装的 unit 文件，免去手工 sed；默认输出到当前目录 kiteserver.service。
+ * 产物可随升级重复生成（覆盖写），安装命令打印在输出里 */
+export async function maybeDeploy() {
+  if (process.argv[2] !== 'deploy') return;
+  const args = process.argv.slice(3);
+  let rawOut = '';
+  // 缺省指向 www-data 家目录的 ~/.kites 标准树（字面量给出：deploy 通常以 root
+  // 运行，~ 会展开成 /root 而非服务运行用户的家目录）
+  let rawConfig = '/var/www/.kites/conf/server.yaml';
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--config' || args[i] === '-c') {
+      rawConfig = String(args[++i] ?? '');
+    } else if (args[i].startsWith('--config=')) {
+      rawConfig = args[i].slice('--config='.length);
+    } else if (!args[i].startsWith('-') && !rawOut) {
+      rawOut = args[i];
+    } else {
+      console.error('[server] deploy 用法：kites deploy [unit 输出路径] [--config <配置文件路径>]');
+      console.error(`[server] 无法识别的参数："${args[i]}"`);
+      process.exit(1);
+    }
+  }
+  if (!rawConfig.trim() || rawConfig.startsWith('-')) {
+    console.error('[server] deploy 的 --config 后需要给出配置文件路径');
+    process.exit(1);
+  }
+  const configFile = path.resolve(expandHome(rawConfig));
+  const outPath = path.resolve(expandHome(rawOut || 'kiteserver.service'));
+
+  const kitesBin = await resolveKitesBin();
+  if (!kitesBin) {
+    console.error('[server] PATH 里找不到 kites 可执行文件（which kites 失败），无法填写 unit 的 ExecStart');
+    console.error('[server] 请在 npm 全局安装本包的机器上运行：npm i -g @jacksontian/kite-server');
+    process.exit(1);
+  }
+  let tpl;
+  try {
+    tpl = await fs.promises.readFile(path.join(__dirname, '..', '..', 'deploy', 'kiteserver.service'), 'utf8');
+  } catch (err) {
+    console.error(`[server] 无法读取包内 unit 模板 deploy/kiteserver.service：${err.message}`);
+    process.exit(1);
+  }
+  const content = tpl.replaceAll('__KITES_BIN__', kitesBin).replaceAll('__CONFIG_FILE__', configFile);
+  if (/__[A-Z_]+__/.test(content)) {
+    console.error('[server] 包内 unit 模板结构与预期不符（仍有未替换的占位符），请改用手工方式安装');
+    process.exit(1);
+  }
+  try {
+    await fs.promises.mkdir(path.dirname(outPath), { recursive: true });
+    await fs.promises.writeFile(outPath, content, { mode: 0o644 });
+  } catch (err) {
+    console.error(`[server] 无法写入 ${outPath}：${err.message}`);
+    process.exit(1);
+  }
+  console.log(`[server] 已生成 systemd unit：${outPath}`);
+  console.log(`  ExecStart: ${kitesBin} start --config ${configFile}`);
+  const configExists = await fs.promises.access(configFile).then(() => true, () => false);
+  if (!configExists) {
+    console.warn(`[server] 注意：${configFile} 尚不存在，安装 unit 前请先生成：kites init ${configFile}`);
+  }
+  console.log('[server] 安装（unit 以 www-data 运行，注意先完成 README「云端部署」的目录授权）：');
+  console.log(`  sudo install -m 644 ${outPath} /etc/systemd/system/kiteserver.service`);
+  console.log('  sudo systemctl daemon-reload && sudo systemctl enable --now kiteserver');
+  process.exit(0);
+}

package/lib/cli/init.js

@@ -0,0 +1,208 @@
+/**
+ * kites init 子命令：交互式问答与配置文件生成。
+ */
+
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import readline from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+import { expandHome, PLACEHOLDER_SECRET } from './util.js';
+import { defaultConfigFile } from './args.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** 建 readline 并包装成问答队列：突发到达的行（单测管道注入）不丢失；
+ * Ctrl+C / 输入流结束（Ctrl+D）统一取消退出 130 */
+function createPrompter(tag, { input, output }) {
+  const rl = readline.createInterface({ input, output, terminal: input.isTTY === true });
+  const buffered = [];
+  let waiter = null;
+  const cancel = () => {
+    console.log('');
+    console.log(`[${tag}] 输入已结束，取消 init，未生成配置文件`);
+    process.exit(130);
+  };
+  rl.on('line', (line) => {
+    if (waiter) {
+      const w = waiter;
+      waiter = null;
+      w(line);
+    } else {
+      buffered.push(line);
+    }
+  });
+  rl.on('SIGINT', () => {
+    rl.close();
+    cancel();
+  });
+  rl.on('close', () => {
+    if (waiter) {
+      waiter = null;
+      cancel();
+    }
+  });
+  const ask = (prompt) => {
+    output.write(prompt);
+    if (buffered.length) return Promise.resolve(buffered.shift());
+    return new Promise((resolve) => {
+      waiter = resolve;
+    });
+  };
+  return { ask, close: () => rl.close() };
+}
+
+/** init 交互问答（终端下启用）：逐项确认可调配置，直接回车接受 [...] 里的默认值，
+ * Ctrl+C 取消退出。input/output 可注入（默认真实终端），便于单测以管道模拟 */
+export async function collectServerInitAnswers(defaults, { input = process.stdin, output = process.stdout } = {}) {
+  const { ask, close } = createPrompter('server', { input, output });
+  const answers = { port: defaults.port, dataDir: defaults.dataDir };
+  try {
+    for (;;) {
+      const ans = (await ask(`监听端口 port [${defaults.port}]：`)).trim();
+      if (!ans) break;
+      const n = Number(ans);
+      if (Number.isInteger(n) && n >= 1 && n <= 65535) {
+        answers.port = n;
+        break;
+      }
+      console.log('[server] 端口需为 1-65535 的整数，请重新输入');
+    }
+    const dirAns = (await ask(`持久化目录 dataDir [${defaults.dataDir}]：`)).trim();
+    if (dirAns) answers.dataDir = path.resolve(expandHome(dirAns));
+  } finally {
+    close();
+  }
+  return answers;
+}
+
+/** init 子命令（kites init [配置文件路径] [--yes]）：基于包内模板一步生成配置文件，
+ * 自动填好随机 apiSecret/workerSecret，免去「复制模板 + keygen + 粘贴」三步；
+ * 终端（TTY）下进入交互问答确认 port/dataDir，--yes（或非终端）按默认值直接生成；
+ * 不带路径时默认生成到 ~/.kites/conf/server.yaml（与 start/check 缺省读取的
+ * --config 路径一致，init 完即可直接 kites start）；
+ * 目标已存在时模仿 npm init：现有值作默认答案重新确认，确认后重写该文件
+ * （额外字段保留，密钥不轮换）；无任何变化则只确认不落盘 */
+export async function maybeInit() {
+  if (process.argv[2] !== 'init') return;
+  const args = process.argv.slice(3);
+  let rawPath = '';
+  let skipPrompts = false;
+  for (const a of args) {
+    if (a === '--yes' || a === '-y') {
+      skipPrompts = true;
+    } else if (a.startsWith('-')) {
+      console.error(`[server] 无法识别的参数 "${a}"；init 用法：kites init [配置文件路径] [--yes]`);
+      process.exit(1);
+    } else if (rawPath) {
+      console.error(`[server] init 只接受一个配置文件路径（多余："${a}"）`);
+      process.exit(1);
+    } else {
+      rawPath = a;
+    }
+  }
+  if (rawPath && !rawPath.trim()) {
+    console.error('[server] init 用法：kites init [配置文件路径] [--yes]（默认 ~/.kites/conf/server.yaml）');
+    process.exit(1);
+  }
+  const target = path.resolve(expandHome(rawPath.trim() || defaultConfigFile()));
+  // 目标已存在：读出并解析作为默认值来源（模仿 npm init 重复确认语义）；
+  // 无法解析成 YAML 映射时才报错退出，其余读失败（如 ENOENT）按新文件处理
+  let existing = null;
+  try {
+    existing = YAML.parse(await fs.promises.readFile(target, 'utf8'));
+    if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
+      throw new Error('内容不是一个键值映射');
+    }
+    console.log(`[server] 发现已有配置 ${target}`);
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      console.error(`[server] ${target} 已存在但无法按 YAML 配置解析：${err.message}`);
+      console.error('[server] 请先手工修复，或备份删除后重新 init');
+      process.exit(1);
+    }
+  }
+  let tpl = null;
+  if (!existing) {
+    try {
+      tpl = await fs.promises.readFile(path.join(__dirname, '..', '..', 'config.example.yaml'), 'utf8');
+    } catch (err) {
+      console.error(`[server] 无法读取包内配置模板 config.example.yaml：${err.message}`);
+      process.exit(1);
+    }
+  }
+  // 密钥策略：已有配置保留现值不轮换（占位符视为未设置，生成新的）；全新文件生成随机密钥。
+  // 自动生成的密钥带 kites_ 前缀，便于与 kitew keygen 产物（kitew_ 前缀）目视区分，防粘贴错端
+  let apiSecret = String(existing?.apiSecret ?? '');
+  if (!apiSecret || apiSecret === PLACEHOLDER_SECRET) apiSecret = 'kites_' + crypto.randomBytes(32).toString('hex');
+  const workerSecret = existing ? String(existing.workerSecret ?? '') : 'kites_' + crypto.randomBytes(32).toString('hex');
+  // dataDir 默认落 ~/.kites 标准树（与配置文件位置、启动工作目录都解耦）；
+  // 已有配置则沿用现值作默认
+  const defaults = {
+    port: Number.isInteger(existing?.port) ? existing.port : 8787,
+    dataDir: existing?.dataDir ? String(existing.dataDir) : path.join(os.homedir(), '.kites', 'data'),
+  };
+  let answers = defaults;
+  if (!skipPrompts && process.stdin.isTTY === true && process.stdout.isTTY === true) {
+    // 头部说明与问答区各留一行空隙，避免提示行挤在一起
+    if (existing) console.log('');
+    console.log('[server] 逐项确认，回车接受 [...] 里的默认值（Ctrl+C 取消）：');
+    console.log('');
+    answers = await collectServerInitAnswers(defaults);
+    console.log('');
+  }
+  let content;
+  if (existing) {
+    // 已有配置：合并确认结果后整体重写；额外字段（如 imWebhook）原样保留
+    const unchanged = existing.port === answers.port
+      && String(existing.dataDir ?? '') === answers.dataDir
+      && String(existing.apiSecret ?? '') === apiSecret
+      && String(existing.workerSecret ?? '') === workerSecret;
+    if (unchanged) {
+      console.log(`[server] 配置确认完毕，与现有内容一致，不改动文件：${target}`);
+      process.exit(0);
+    }
+    content = YAML.stringify({ ...existing, apiSecret, workerSecret, port: answers.port, dataDir: answers.dataDir });
+  } else {
+    content = tpl
+      .replace(`apiSecret: ${PLACEHOLDER_SECRET}`, `apiSecret: ${apiSecret}`)
+      .replace('workerSecret: ""', `workerSecret: ${workerSecret}`)
+      .replace('port: 8787', `port: ${answers.port}`)
+      .replace('dataDir: ~/.kites/data', `dataDir: ${answers.dataDir}`);
+    if (!content.includes(apiSecret)) {
+      console.error('[server] 包内配置模板结构与预期不符（找不到占位符），请改用手工方式：复制 config.example.yaml 后填写');
+      process.exit(1);
+    }
+  }
+  try {
+    await fs.promises.mkdir(path.dirname(target), { recursive: true });
+    await fs.promises.writeFile(target, content, { mode: 0o600 });
+  } catch (err) {
+    console.error(`[server] 无法写入 ${target}：${err.message}`);
+    console.error('[server] 目标目录需要 root 权限时请改用 sudo，或 init 到自定义路径');
+    process.exit(1);
+  }
+  const dataDir = answers.dataDir;
+  console.log(`[server] ${existing ? '已确认并更新配置' : '已生成配置'}：${target}（权限 0600；port ${answers.port}，dataDir ${dataDir}）`);
+  console.log('');
+  console.log('密钥（已写入配置文件，请妥善保存；永不在网络上传输）：');
+  console.log(`  ${'apiSecret'.padEnd(12)}（控制台/手机浏览器用）：${apiSecret}`);
+  console.log(`  ${'workerSecret'.padEnd(12)}（填入 worker.yaml 的 apiSecret）：${workerSecret || '（未设置，Worker 与控制台共用 apiSecret）'}`);
+  console.log('');
+  console.log('后续步骤：');
+  console.log(`  kites check --config ${target}  # 干跑验证`);
+  console.log(`  kites start --config ${target}  # 启动`);
+  console.log('');
+  if (target.startsWith('/var/www/.kites')) {
+    console.log('生产部署（systemd 以 www-data 运行）：');
+    console.log(`  sudo chown -R www-data:www-data ${path.dirname(path.dirname(target))}`);
+    console.log(`  kites deploy --config ${target}`);
+    console.log('  sudo install -m 644 kiteserver.service /etc/systemd/system/kiteserver.service');
+    console.log('  sudo systemctl daemon-reload && sudo systemctl enable --now kiteserver');
+  } else {
+    console.log('生产部署：见 README「云端部署」（systemd unit 用 kites deploy 生成）');
+  }
+  process.exit(0);
+}

package/lib/cli/keygen.js

@@ -0,0 +1,23 @@
+/**
+ * kites keygen 子命令：生成强随机密钥并打印配置片段。
+ */
+
+import crypto from 'node:crypto';
+
+/** keygen 子命令（kites keygen）：生成强随机密钥并打印配置片段，免去手工生成/搬运 hex；
+ * 带 kites_ 前缀，便于与 kitew keygen 产物（kitew_ 前缀）目视区分，防粘贴错端 */
+export function maybeKeygen() {
+  if (process.argv[2] !== 'keygen') return;
+  const secret = 'kites_' + crypto.randomBytes(32).toString('hex');
+  console.log('[server] 已生成签名密钥（永不在网络上传输，请妥善保管）：');
+  console.log('');
+  console.log('  ' + secret);
+  console.log('');
+  console.log('[server] 粘贴到 server.yaml（手机浏览器控制台使用同一密钥）：');
+  console.log('');
+  console.log('  apiSecret: ' + secret);
+  console.log('');
+  console.log('[server] 建议再执行一次 kites keygen 生成不同的 workerSecret（分权见 README「安全说明」），');
+  console.log('[server] Worker 端 worker.yaml 的 apiSecret 与 workerSecret 保持一致');
+  process.exit(0);
+}

package/lib/cli/meta.js

@@ -0,0 +1,56 @@
+/**
+ * kites --help / --version 与 meta 选项处理。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** 用法说明：--help/-h 输出到 stdout 并 exit 0（符合 CLI 惯例）；
+ * 裸 kites（不带任何子命令）同样只打印用法，不启动服务 */
+export function printHelp() {
+  console.log('用法：kites <子命令> [选项]');
+  console.log('');
+  console.log('子命令：');
+  console.log('  kites start          启动云端服务（前台运行；常驻托管交给 systemd，见 deploy）');
+  console.log('    -c, --config <路径>  指定 YAML 配置文件（缺省用 ~/.kites/conf/server.yaml，模板见包内 config.example.yaml）');
+  console.log('  kites check          只校验配置文件（--config 指定或默认路径，改配置后干跑验证），通过即退出，不启动服务');
+  console.log('  kites keygen         生成强随机密钥并打印配置片段');
+  console.log('  kites init [路径]    基于包内模板生成配置文件（默认 ~/.kites/conf/server.yaml），自动填好随机密钥；');
+  console.log('                       终端下交互确认 port/dataDir（回车用默认值），--yes 跳过提问按默认生成；');
+  console.log('                       目标已存在时重复运行只是重新确认（仿 npm init），密钥不轮换');
+  console.log('  kites deploy [输出]  基于包内 systemd 模板生成占位符已替换好的 unit 文件（默认当前目录 kiteserver.service），');
+  console.log('                       可选 --config <路径> 指定 unit 里的配置文件路径（默认 /var/www/.kites/conf/server.yaml）');
+  console.log('');
+  console.log('选项：');
+  console.log('  -h, --help           打印本帮助');
+  console.log('  -V, --version        打印版本号');
+  console.log('');
+  console.log('不带任何子命令时只打印本用法，不会启动服务。');
+}
+
+/** --version/-V：读取包内 package.json 输出版本号（与 npm 发布版本一致） */
+export async function printVersion() {
+  try {
+    const pkg = JSON.parse(await fs.promises.readFile(path.join(__dirname, '..', '..', 'package.json'), 'utf8'));
+    console.log(`kites (${pkg.name}) ${pkg.version}`);
+  } catch (err) {
+    console.error(`[server] 无法读取包内 package.json：${err.message}`);
+    process.exit(1);
+  }
+}
+
+/** 常规 CLI 选项：--help/-h 与 --version/-V 优先于子命令/配置加载，识别到即退出 */
+export async function maybeMeta() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+  if (args.includes('--version') || args.includes('-V')) {
+    await printVersion();
+    process.exit(0);
+  }
+}

package/lib/cli/util.js

@@ -0,0 +1,44 @@
+/**
+ * kites CLI 通用小工具：对象判断、占位符常量、~ 展开、schema 辅助。
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+
+export function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/** config.example.yaml 里的占位文本：原样未改就启动等于用公开"密钥"裸奔，必须拦下 */
+export const PLACEHOLDER_SECRET = '换成你生成的密钥';
+
+/** 可选字符串：缺省/给 null 都按空串处理，统一 trim
+ * （zod v4 中 union(z.undefined()) 不能让对象键变可选，须用 .optional()） */
+export const optStr = (errMsg) =>
+  z.string({ error: errMsg }).trim().optional().nullable().transform((v) => v ?? '');
+
+/** 把 zod issues 转成错误行：未知配置项逐条展开并附该层级可用项清单；
+ * custom/各叶子的报错文案均已自带字段名，直接透传 */
+export function formatIssues(issues, knownByPath) {
+  const out = [];
+  for (const iss of issues) {
+    if (iss.code === 'unrecognized_keys') {
+      const known = knownByPath[iss.path.join('.')] || [];
+      for (const key of iss.keys) out.push(`未知配置项 "${key}"（可用：${known.join(', ')}）`);
+      continue;
+    }
+    out.push(iss.message);
+  }
+  return out;
+}
+
+/** 展开开头的 ~ 为用户主目录（YAML 不会替我们做这件事） */
+export function expandHome(p) {
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+export const SECRET_HINT =
+  '（两端共享的签名密钥；生成：node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'hex\'))"）';