nx-sk 0.3.0

package/src/runtime/cli.js

@@ -0,0 +1,266 @@
+// 通用 CLI 运行器：解析 → 匹配 → 校验 → 渲染 → help。
+// 命令表由 action 声明派生，所以「Web 上能做的 CLI 都能做」是结构保证，不靠人记。
+import { resolve as resolvePath } from 'node:path';
+import { APP_NAME, DEFAULT_PORT, ENV_STORE, VERSION } from '../core/paths.js';
+import { badInput, external, toErrorShape } from '../core/errors.js';
+import { ACTIONS, MODULES, MODULE_TITLES, commandEntry } from './registry.js';
+import { applySpec, argSpecsOf, cliPathsOf, flagSpecsOf, usageOf } from './spec.js';
+
+// `--json` 需要被 serve 这类长驻命令看到，所以用一个模块级开关而不是往 meta 里塞字段
+// （meta 的契约只有 { transport }，别把两端形态差异以外的东西塞进去）。
+let OUTPUT_JSON = false;
+
+async function cmdServe(ctx) {
+  const { startServer } = await import('./server.js');
+  const { openBrowser } = await import('../core/open.js');
+  const { loadStore, storePathInUse } = await import('../core/store.js');
+  const { appHome, displayPath } = await import('../core/paths.js');
+
+  await loadStore(); // 触发首次播种：面板一打开就该有「求职」栏目
+  let server;
+  try {
+    server = await startServer({ port: ctx.port });
+  } 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)}`);
+  }
+  // --port 0 = 让 OS 挑一个空闲端口（测试用），所以真实端口要回读，不能信入参
+  const realPort = server.address() && typeof server.address() === 'object' ? server.address().port : ctx.port;
+  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');
+  } else {
+    process.stdout.write([
+      `面板:   ${url}`,
+      `存储:   ${displayPath(storePathInUse())}`,
+      '退出:   Ctrl-C',
+      '机器可读: nx-sk serve --json（先打一行 JSON，再继续常驻）',
+    ].join('\n') + '\n');
+  }
+  if (!ctx['no-open']) await openBrowser(url);
+
+  await new Promise((done) => {
+    let closed = false;
+    const stop = () => {
+      if (closed) return;
+      closed = true;
+      server.close(() => done());
+      setTimeout(done, 800).unref?.();
+    };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+  });
+  return { status: 'ok', stopped: true, url };
+}
+
+const BUILTINS = [
+  {
+    id: 'serve',
+    module: 'system',
+    cli: ['serve'],
+    http: null,
+    summary: '启动 Web 面板（唯一常驻命令；--no-open 给开发与 CI 用）',
+    flags: { port: { type: 'number', default: DEFAULT_PORT }, 'no-open': { type: 'boolean' } },
+    run: (ctx) => cmdServe(ctx),
+    render: () => '',
+  },
+  {
+    id: 'help',
+    module: 'system',
+    cli: ['help'],
+    http: null,
+    summary: '命令表；可带主题（模块 id / 命令组 / action id）',
+    args: [{ name: 'topic', required: false }],
+    run: (ctx) => helpEntries(ctx.topic),
+    render: (d, ctx) => renderHelp(d, ctx.topic),
+  },
+  {
+    id: 'version',
+    module: 'system',
+    cli: ['version'],
+    http: null,
+    summary: '输出版本号（裸输出，便于 V=$(nx-sk version)）',
+    run: () => VERSION,
+    render: (v) => v,
+  },
+];
+
+export const ALL_COMMANDS = [...BUILTINS, ...ACTIONS];
+
+// 转出去给 system 模块用：它必须在**函数体内**动态 import 这里（静态 import registry 会成环）。
+// 不转这一行，system 就得去静态 import registry —— 那正是分层规则要禁止的环。
+export { commandEntry };
+
+export function helpEntries(topic) {
+  const all = ALL_COMMANDS.map(commandEntry);
+  if (!topic) return all;
+  const t = String(topic);
+  if (MODULES.some((m) => m.id === t)) return all.filter((e) => e.module === t);
+  const byRoot = all.filter((e) => e.command.split(' ')[1] === t);
+  if (byRoot.length) return byRoot;
+  const byId = all.filter((e) => e.id === t);
+  if (byId.length) return byId;
+  throw badInput(`未知帮助主题: ${t}（可用模块: ${MODULES.map((m) => m.id).join(' / ')}；或命令组如 section / entry）`);
+}
+
+export function renderHelp(entries, topic) {
+  const lines = [`${APP_NAME} v${VERSION} · 本机个人资源管理器`, ''];
+  if (topic) lines.push(`主题: ${topic}`, '');
+  lines.push('用法: nx-sk <命令组> <子命令> [参数] [--flags]　　任何命令都支持 --json', '');
+  const groups = new Map();
+  for (const e of entries) {
+    if (!groups.has(e.module)) groups.set(e.module, []);
+    groups.get(e.module).push(e);
+  }
+  for (const [mod, list] of groups) {
+    lines.push(`【${MODULE_TITLES[mod] || mod}】`);
+    for (const e of list) {
+      lines.push(`  ${e.command}`);
+      lines.push(`      ${e.summary}`);
+      if (e.usage !== e.command) lines.push(`      用法: ${e.usage}`);
+      if (e.http) lines.push(`      接口: ${e.http}`);
+    }
+    lines.push('');
+  }
+  lines.push('常用姿势：');
+  lines.push('  nx-sk bootstrap --json                          一次拿齐上下文（agent 首选入口）');
+  lines.push('  nx-sk section dump job --json                   一个栏目的全部信息（字段 + 全部条目 + 未填清单）');
+  lines.push('  nx-sk entry fields --section job                字段字典：填之前先看，别猜字段名');
+  lines.push('  nx-sk entry update 赵刘学 --set 微信=zhaoliuxue 改一个字段（PATCH 语义）');
+  lines.push('  nx-sk export run --format both                  整体导出到 ~/nx-sk/export');
+  lines.push('  nx-sk serve                                     打开 Web 面板');
+  return lines.join('\n');
+}
+
+/**
+ * 最长前缀匹配：命令路径里可以含 flag（那是一条命令路径，不是「带 flag 的命令」）。
+ * 导出是为了让一致性测试能「只走匹配、零副作用」地验证每条 action 都能被解析回自己。
+ */
+export function resolveCommand(tokens, commands = ALL_COMMANDS) {
+  let best = null;
+  let bestLen = -1;
+  for (const action of commands) {
+    for (const path of cliPathsOf(action)) {
+      if (path.length <= bestLen || path.length > tokens.length) continue;
+      if (path.every((seg, i) => tokens[i] === seg)) { best = action; bestLen = path.length; }
+    }
+  }
+  if (!best) return { action: null, rest: [], tried: tokens.slice(0, 2) };
+  return { action: best, rest: tokens.slice(bestLen), tried: tokens.slice(0, bestLen) };
+}
+
+function pushFlag(raw, name, value, spec) {
+  if (spec.type === 'array' || spec.type === 'kv') {
+    raw[name] = raw[name] === undefined ? [value] : [].concat(raw[name], value);
+  } else {
+    raw[name] = value;
+  }
+}
+
+function parseArgs(action, tokens) {
+  const flagSpecs = new Map(flagSpecsOf(action).map((s) => [s.name, s]));
+  const argSpecs = argSpecsOf(action);
+  const flags = {};
+  const positional = [];
+
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t === '--') { positional.push(...tokens.slice(i + 1)); break; }
+    if (t.startsWith('--')) {
+      const eq = t.indexOf('=');
+      const name = eq >= 0 ? t.slice(2, eq) : t.slice(2);
+      const spec = flagSpecs.get(name);
+      if (!spec) throw badInput(`用法: ${usageOf(action)} —— 未知参数 --${name}`);
+      if (eq >= 0) { pushFlag(flags, name, t.slice(eq + 1), spec); continue; }
+      if (spec.type === 'boolean') { pushFlag(flags, name, true, spec); continue; }
+      const next = tokens[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        // 注意：`--depth` 无值时报错，不要静默转换——Number(true) 会变成「深度 1」这种另一个合法值
+        throw badInput(`用法: ${usageOf(action)} —— 参数 --${name} 缺少取值`);
+      }
+      i++;
+      pushFlag(flags, name, next, spec);
+      continue;
+    }
+    if (t.startsWith('-') && t.length > 1) {
+      throw badInput(`用法: ${usageOf(action)} —— 未知参数 ${t}（本 CLI 只使用 --长参数）`);
+    }
+    positional.push(t);
+  }
+
+  if (positional.length > argSpecs.length) {
+    throw badInput(`用法: ${usageOf(action)} —— 多余的位置参数: ${positional.slice(argSpecs.length).join(' ')}`);
+  }
+  const raw = {};
+  for (let i = 0; i < positional.length; i++) raw[argSpecs[i].name] = positional[i];
+  // 显式 flag 覆盖位置参数：`key set K --value=<值>` 与 `key set K <值>` 必须等价，
+  // 而后者在值以 `-` 开头时会被当成 flag（那时只能走前者）。
+  return { ...raw, ...flags };
+}
+
+const STATUS_NOTE = {
+  skipped: '（未做改动——目标已是期望状态，或用 --dry-run 试运行）',
+  conflict: '（需要你决策后才能继续，不要自动重试）',
+  blocked: '（被业务规则挡住：先去满足前置条件）',
+};
+
+async function emit(action, data, ctx) {
+  if (OUTPUT_JSON) {
+    process.stdout.write(JSON.stringify(data === undefined ? null : data) + '\n');
+    return;
+  }
+  let text;
+  if (typeof action.render === 'function') text = await action.render(data, ctx);
+  else text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+  if (text === undefined || text === null || text === '') return;
+  const status = data && typeof data === 'object' ? data.status : undefined;
+  if (status && status !== 'ok') text = `${text}\n状态: ${status} ${STATUS_NOTE[status] || ''}`.trimEnd();
+  process.stdout.write(`${text}\n`);
+}
+
+export async function runCli(argv) {
+  const opts = { json: false, store: null };
+  const tokens = [];
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === '--json') { opts.json = true; continue; }
+    if (t === '--store') {
+      const v = argv[++i];
+      if (v === undefined) { process.stderr.write('nx-sk: --store 缺少取值\n'); process.exitCode = 1; return; }
+      opts.store = v;
+      continue;
+    }
+    if (t.startsWith('--store=')) { opts.store = t.slice('--store='.length); continue; }
+    tokens.push(t);
+  }
+  // 全局 flag 先摘掉再匹配命令；--store 通过环境变量下传，服务层就不必到处接一个路径参数
+  if (opts.store) process.env[ENV_STORE] = resolvePath(opts.store);
+  OUTPUT_JSON = opts.json;
+
+  let lastAction = null;
+  try {
+    if (!tokens.length) {
+      await emit({ render: (d, c) => renderHelp(d, c) }, helpEntries(), {});
+      return;
+    }
+    const { action, rest, tried } = resolveCommand(tokens);
+    if (!action) throw badInput(`未知命令: ${tried.join(' ')} —— 用 nx-sk help 看全部命令`);
+    lastAction = action;
+    const ctx = applySpec(action, parseArgs(action, rest));
+    const data = await action.run(ctx, { transport: 'cli' });
+    await emit(action, data, ctx);
+  } catch (err) {
+    const e = toErrorShape(err);
+    // 参数/用法类错误必须带完整用法串——agent 靠「用法:」这个锚点判断「该改参数而不是重试」。
+    // 放在运行器里统一补，比要求每个 service 自己记得写更可靠。
+    if (e.code === 'INVALID_INPUT' && !e.message.includes('用法:') && lastAction) {
+      e.message += `\n用法: ${usageOf(lastAction)}`;
+    }
+    if (opts.json) process.stdout.write(JSON.stringify({ ok: false, error: e.message, code: e.code }) + '\n');
+    else process.stderr.write(`${APP_NAME}: ${e.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/src/runtime/registry.js

@@ -0,0 +1,65 @@
+// 模块注册表 + **装载期自检**：重复的 action id / CLI 路径 / HTTP 路由在启动瞬间就炸，
+// 而不是等某个用户敲到那条命令才发现。
+import { APP_NAME } from '../core/paths.js';
+import { cliPathsOf, usageOf } from './spec.js';
+
+import sections from '../modules/sections/index.js';
+import entries from '../modules/entries/index.js';
+import exportModule from '../modules/export/index.js';
+import skill from '../modules/skill/index.js';
+import settings from '../modules/settings/index.js';
+import system from '../modules/system/index.js';
+
+// 顺序 = 面板 tab 顺序与 help 分组顺序（system 放最后，它是聚合模块）
+export const MODULES = [sections, entries, exportModule, skill, settings, system]
+  .slice()
+  .sort((a, b) => (a.order || 50) - (b.order || 50));
+
+export const MODULE_TITLES = Object.fromEntries(MODULES.map((m) => [m.id, m.title]));
+
+export const ACTIONS = MODULES.flatMap((m) => (m.actions || []).map((a) => ({ ...a, module: m.id })));
+
+/** 命令表的一行——`help` / `routes` / bootstrap 共用同一份，不存在「第二张命令表」。 */
+export function commandEntry(a) {
+  const paths = cliPathsOf(a);
+  return {
+    id: a.id,
+    module: a.module,
+    command: `${APP_NAME} ${paths[0].join(' ')}`,
+    usage: usageOf(a),
+    summary: a.summary || '',
+    http: Array.isArray(a.http) ? a.http.join(' ') : null,
+    aliases: paths.slice(1).map((p) => `${APP_NAME} ${p.join(' ')}`),
+  };
+}
+
+/** 装载期自检。导出成纯函数，好让测试能用一份**故意写坏的清单**验证它真的会红。 */
+export function selfCheckActions(actions) {
+  const ids = new Map();
+  const cliKeys = new Map();
+  const httpKeys = new Map();
+  for (const a of actions) {
+    if (!a.id) throw new Error(`action 缺少 id（模块 ${a.module}）`);
+    if (ids.has(a.id)) throw new Error(`action id 重复: ${a.id}`);
+    ids.set(a.id, a);
+
+    const paths = cliPathsOf(a);
+    if (!paths.length) throw new Error(`action 没有 CLI 命令: ${a.id}`);
+    for (const p of paths) {
+      const k = p.join(' ');
+      if (cliKeys.has(k)) throw new Error(`CLI 路径重复: ${k}（${a.id} 与 ${cliKeys.get(k)}）`);
+      cliKeys.set(k, a.id);
+    }
+
+    if (a.http !== null && a.http !== undefined) {
+      if (!Array.isArray(a.http) || a.http.length !== 2) throw new Error(`http 既不是数组也不是 null: ${a.id}`);
+      const k = `${a.http[0]} ${a.http[1]}`;
+      if (httpKeys.has(k)) throw new Error(`HTTP 路由重复: ${k}（${a.id} 与 ${httpKeys.get(k)}）`);
+      httpKeys.set(k, a.id);
+    }
+    if (typeof a.run !== 'function') throw new Error(`action 缺少 run: ${a.id}`);
+  }
+  return { ids, cliKeys, httpKeys };
+}
+
+export const SELF_CHECK = selfCheckActions(ACTIONS);

package/src/runtime/server.js

@@ -0,0 +1,80 @@
+// 零依赖静态 + /api 委派。对构建工具**零感知**——它只服务 src/web/public/，
+// 不管是 dev 还是 prod，所以「dev 能跑、打包后白屏」这类问题不会出现。
+import http from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { extname, join, resolve, sep } from 'node:path';
+import { DEFAULT_PORT, DEV_VITE_PORT, PUBLIC_DIR } from '../core/paths.js';
+import { handleApi } from './api.js';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.woff2': 'font/woff2',
+  '.map': 'application/json; charset=utf-8',
+};
+
+function sendText(res, status, text) {
+  res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
+  res.end(text);
+}
+
+async function sendFile(res, file) {
+  try {
+    const buf = await readFile(file);
+    res.writeHead(200, { 'content-type': MIME[extname(file).toLowerCase()] || 'application/octet-stream' });
+    res.end(buf);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const NOT_BUILT = [
+  '面板还没有构建产物。',
+  '',
+  `开发模式:  pnpm run dev        （vite :${DEV_VITE_PORT} + serve :${DEFAULT_PORT}）`,
+  '生产模式:  pnpm start          （先 vite build，再 serve）',
+].join('\n');
+
+async function serveStatic(pathname, res) {
+  const rel = decodeURIComponent(pathname).replace(/^\/+/, '');
+  // 静态服务做 resolve 后前缀校验，别用正则剥 '..'
+  let file = resolve(PUBLIC_DIR, rel);
+  if (file !== resolve(PUBLIC_DIR) && !file.startsWith(resolve(PUBLIC_DIR) + sep)) {
+    return sendText(res, 403, '禁止访问');
+  }
+  if (!rel) file = join(PUBLIC_DIR, 'index.html');
+  if (await sendFile(res, file)) return;
+  // SPA 回退：非 /api 的未命中路径交给前端 hash 路由
+  if (await sendFile(res, join(PUBLIC_DIR, 'index.html'))) return;
+  return sendText(res, 503, NOT_BUILT);
+}
+
+export function startServer({ port = DEFAULT_PORT, host = '127.0.0.1' } = {}) {
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+    if (url.pathname === '/api' || url.pathname.startsWith('/api/')) {
+      handleApi(req, res, url).catch((err) => {
+        sendText(res, 500, `内部错误: ${err && err.message ? err.message : String(err)}`);
+      });
+      return;
+    }
+    serveStatic(url.pathname, res).catch((err) => {
+      sendText(res, 500, `内部错误: ${err && err.message ? err.message : String(err)}`);
+    });
+  });
+  return new Promise((ok, no) => {
+    server.once('error', no);
+    // 默认只绑 127.0.0.1：这是本机工具，不要暴露到局域网。
+    server.listen(port, host, () => ok(server));
+  });
+}

package/src/runtime/spec.js

@@ -0,0 +1,158 @@
+// action 规格：校验 / 强转 / 路由编译 / 用法串。
+//
+// 为什么 flag 要随 action 声明、而不是用全局白名单：
+// `entry update --mask x` 里 `--mask` 是布尔型（不取值），全局白名单猜不出来；
+// 只有 action 自己知道。同理 `type:'number'` 让两端都得到数字，不必各写一遍 parseInt。
+import { readFileSync } from 'node:fs';
+import { APP_NAME } from '../core/paths.js';
+import { badInput } from '../core/errors.js';
+import { BOOL_FALSE, BOOL_TRUE } from '../core/fields.js';
+
+export function cliPathsOf(action) {
+  const c = action.cli;
+  // `cli: []` 也要算「没有 CLI 命令」——否则会得到一个空路径，装载期自检形同虚设
+  if (!c || !c.length) return [];
+  return Array.isArray(c[0]) ? c : [c];
+}
+
+export function argSpecsOf(action) {
+  return (action.args || []).map((a) => (typeof a === 'string'
+    ? { name: a, required: true }
+    : { name: a.name, required: a.required !== false }));
+}
+
+export function flagSpecsOf(action) {
+  return Object.entries(action.flags || {}).map(([name, spec]) => ({ name, type: 'string', required: false, ...spec }));
+}
+
+/** 用法串：`nx-sk entry update <id> [--section <section>] [--mask]` */
+export function usageOf(action) {
+  const paths = cliPathsOf(action);
+  const parts = [APP_NAME, ...(paths[0] || [action.id])];
+  for (const a of argSpecsOf(action)) parts.push(a.required ? `<${a.name}>` : `[${a.name}]`);
+  for (const f of flagSpecsOf(action)) {
+    if (f.type === 'boolean') { parts.push(f.required ? `--${f.name}` : `[--${f.name}]`); continue; }
+    // 值的占位符优先用 enum 展开，其次显式 hint，最后才退回 flag 名——
+    // `--side <side>` 这种读起来没有信息量
+    const hint = f.enum ? f.enum.join('|') : f.hint || f.name;
+    const token = `--${f.name} <${hint}>`;
+    parts.push(f.required ? token : `[${token}]`);
+  }
+  return parts.join(' ');
+}
+
+function coerce(spec, value) {
+  const type = spec.type || 'string';
+  if (type === 'string') return String(value);
+  if (type === 'number') {
+    const n = typeof value === 'number' ? value : Number(String(value).trim());
+    if (!Number.isFinite(n)) throw badInput(`--${spec.name} 需要数字，收到 ${JSON.stringify(value)}`);
+    return n;
+  }
+  if (type === 'boolean') {
+    if (typeof value === 'boolean') return value;
+    if (typeof value === 'number') return value !== 0;
+    const s = String(value).trim().toLowerCase();
+    if (BOOL_TRUE.includes(s)) return true;
+    if (BOOL_FALSE.includes(s) || s === '') return false;
+    throw badInput(`--${spec.name} 需要是/否，收到 ${JSON.stringify(value)}`);
+  }
+  if (type === 'array') {
+    const list = Array.isArray(value) ? value : String(value).split(',');
+    return list.map((x) => String(x).trim()).filter((x) => x !== '');
+  }
+  if (type === 'json') {
+    if (typeof value === 'object' && value !== null) return value;
+    const s = String(value).trim();
+    if (s.startsWith('@')) {
+      // 命令行塞不下大 JSON 时用 `--data @file.json`——agent 的常用姿势
+      return readFileTextSync(s.slice(1), spec.name);
+    }
+    try { return JSON.parse(s); } catch (e) { throw badInput(`--${spec.name} 不是合法 JSON: ${e.message}`); }
+  }
+  if (type === 'kv') {
+    // CLI: `--set name=值`（可重复）；HTTP: `{set: {name: '值'}}` 或 `{set: ['name=值']}`
+    if (value && typeof value === 'object' && !Array.isArray(value)) return { ...value };
+    const list = Array.isArray(value) ? value : [value];
+    const out = {};
+    for (const item of list) {
+      const s = String(item);
+      const eq = s.indexOf('=');
+      if (eq <= 0) throw badInput(`--${spec.name} 需要 key=value 形式，收到 ${JSON.stringify(item)}`);
+      out[s.slice(0, eq).trim()] = s.slice(eq + 1);
+    }
+    return out;
+  }
+  return value;
+}
+
+// 同步读文件（`@file` 展开）。用 readFileSync 是因为 applySpec 在两端都是同步契约的一部分。
+function readFileTextSync(p, flagName) {
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch (e) {
+    throw badInput(`--${flagName} 读取文件失败: ${p}（${e.message}）`);
+  }
+}
+
+/**
+ * 把「两端拼出来的扁平对象」变成 ctx：只保留声明的键，做 required 校验与强转。
+ * 严格过滤是有意的——HTTP body 里的多余字段不该悄悄流进 service。
+ */
+export function applySpec(action, raw = {}) {
+  const usage = usageOf(action);
+  const ctx = {};
+  for (const a of argSpecsOf(action)) {
+    const v = raw[a.name];
+    if (v === undefined || v === null || v === '') {
+      if (a.required) throw badInput(`用法: ${usage} —— 缺少参数 <${a.name}>`);
+      continue;
+    }
+    ctx[a.name] = String(v);
+  }
+  for (const s of flagSpecsOf(action)) {
+    const v = raw[s.name];
+    if (v === undefined || v === null || v === '') {
+      // ⚠️ 读命令的过滤 flag **不要声明 default**——参数层无条件注入默认值会让
+      // 「不传 = 全部」的分支永远走不到（不报错、不崩，只是永远返回半个结果）
+      if (s.default !== undefined) { ctx[s.name] = s.default; continue; }
+      if (s.required) throw badInput(`用法: ${usage} —— 缺少参数 --${s.name}`);
+      continue;
+    }
+    const coerced = coerce(s, v);
+    if (s.enum && !s.enum.includes(coerced)) {
+      throw badInput(`--${s.name} 只能是 ${s.enum.join(' / ')}，收到 ${JSON.stringify(coerced)}`);
+    }
+    ctx[s.name] = coerced;
+  }
+  return ctx;
+}
+
+export function compileRoute(http) {  const [method, path] = http;
+  const segs = String(path).split('/').filter(Boolean);
+  const keys = [];
+  const parts = segs.map((s) => {
+    if (s.startsWith(':')) { keys.push(s.slice(1)); return '([^/]+)'; }
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  });
+  return { method: String(method).toUpperCase(), path, segs, keys, regex: new RegExp(`^/${parts.join('/')}/?$`) };
+}
+
+/**
+ * 路由按「字面量段优先」排序，让**声明顺序不影响匹配**。
+ * 否则 `GET /api/sections/templates` 会被 `GET /api/sections/:id` 遮蔽，
+ * 而命中哪条取决于 actions 数组的顺序——有人调整顺序就静默错乱。
+ */
+export function compareRoutes(a, b) {
+  const n = Math.max(a.segs.length, b.segs.length);
+  for (let i = 0; i < n; i++) {
+    const x = a.segs[i];
+    const y = b.segs[i];
+    if (x === undefined) return 1; // 段数少的排后面（更笼统）
+    if (y === undefined) return -1;
+    const xp = x.startsWith(':') ? 1 : 0;
+    const yp = y.startsWith(':') ? 1 : 0;
+    if (xp !== yp) return xp - yp; // 字面量优先
+  }
+  return 0;
+}

package/src/web/frontend/App.jsx

@@ -0,0 +1,108 @@
+import { Suspense, useEffect, useMemo } from 'react';
+import { SECTION_VIEW, VIEWS } from './registry.js';
+import { Copyable, DialogHost, ErrorBoundary, Toasts } from './components/ui.jsx';
+import { useStore } from './store.jsx';
+
+function viewFromHash() {
+  const m = /^#\/?([^?/]*)/.exec(window.location.hash || '');
+  return m ? decodeURIComponent(m[1]) : '';
+}
+
+export default function App() {
+  const { boot, bootError, ui, patchUi, reload } = useStore();
+
+  // 栏目 tab 是**数据驱动**的（来自 bootstrap.sections），静态 tab 来自前端注册表。
+  // 两者的 id 可能撞车时静态 tab 不参与第一优先级的排序——栏目 order 是 10/20，静态是 500+。
+  const tabs = useMemo(() => {
+    const dyn = (boot?.sections || []).map((s) => ({
+      id: s.id, title: s.title, order: s.order, kind: 'section', count: s.entries,
+    }));
+    const stat = VIEWS.filter((v) => v.tab !== false).map((v) => ({
+      id: v.id, title: v.title, order: v.order, kind: 'view', component: v.component,
+    }));
+    const seen = new Set();
+    return [...dyn, ...stat]
+      .sort((a, b) => (a.order ?? 50) - (b.order ?? 50))
+      .filter((t) => (seen.has(t.id) ? false : (seen.add(t.id), true)));
+  }, [boot]);
+
+  const current = tabs.find((t) => t.id === ui.view) || tabs[0] || null;
+
+  // hash 与 localStorage 双写对齐：只在挂载时对齐一次，之后交给 hashchange
+  useEffect(() => {
+    const fromHash = viewFromHash();
+    if (fromHash && fromHash !== ui.view) patchUi({ view: fromHash });
+    else if (!window.location.hash) window.location.hash = `#/${ui.view}`;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    const on = () => { const v = viewFromHash(); if (v) patchUi({ view: v }); };
+    window.addEventListener('hashchange', on);
+    return () => window.removeEventListener('hashchange', on);
+  }, [patchUi]);
+
+  useEffect(() => {
+    if (current && current.id !== ui.view) patchUi({ view: current.id });
+  }, [current, ui.view, patchUi]);
+
+  const go = (id) => {
+    patchUi({ view: id });
+    window.location.hash = `#/${id}`;
+  };
+
+  return (
+    <div className="app">
+      <header className="top">
+        <span className="brand">nx-sk</span>
+        <span className="meta">本机个人资源管理器{boot ? ` · v${boot.app.version}` : ''}</span>
+        {boot ? (
+          <span className="meta">
+            存储 <Copyable className="mono" text={boot.storePathRaw}>{boot.storePath}</Copyable>
+          </span>
+        ) : null}
+        <span className="right rowgap">
+          <button className="btn small ghost" onClick={() => reload()}>刷新数据</button>
+        </span>
+      </header>
+
+      <nav className="tabs">
+        {tabs.map((t) => (
+          <button key={t.id} className={`tab ${t.id === current?.id ? 'active' : ''}`} onClick={() => go(t.id)}>
+            {t.title}
+            {typeof t.count === 'number' ? <span className="count">{t.count}</span> : null}
+          </button>
+        ))}
+        {!tabs.length ? <span className="meta">正在装载…</span> : null}
+      </nav>
+
+      <main className="body">
+        {bootError ? (
+          <div className="pad stack">
+            <div className="bad"><strong>读不到后端上下文</strong></div>
+            <pre className="block">{bootError}</pre>
+            <div className="hint">确认 nx-sk serve 正在运行；或点右上角「刷新数据」重试。</div>
+          </div>
+        ) : null}
+        {!bootError && current ? (
+          <ErrorBoundary key={current.id}>
+            <Suspense fallback={<div className="pad muted">加载中…</div>}>
+              {current.kind === 'section'
+                ? <SectionPane sectionId={current.id} />
+                : <current.component />}
+            </Suspense>
+          </ErrorBoundary>
+        ) : null}
+      </main>
+
+      <Toasts />
+      <DialogHost />
+    </div>
+  );
+}
+
+/** 栏目 tab 的动态挂载点：共用 entries 模块的视图，把 sectionId 传进去。 */
+function SectionPane({ sectionId }) {
+  const View = SECTION_VIEW;
+  return <View sectionId={sectionId} />;
+}