nx-kv 0.1.1

package/src/modules/todo/view.jsx

@@ -0,0 +1,280 @@
+// 清单页：三个桶（待办 / 已完成 / 冻结）+ 主题筛选 + 增删改查与状态流转。
+// 每个按钮 = 一条 /api 路由 = 一条 CLI 命令（三者同源于模块的 action 声明）。
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { api } from '../../web/frontend/api/client.js';
+import { useStore } from '../../web/frontend/store.jsx';
+import { useToast, useGuard, useDialog, Modal, Copyable } from '../../web/frontend/components/ui.jsx';
+import { CliHints } from '../../web/frontend/components/CliHints.jsx';
+
+const BUCKETS = [
+  ['open', '待办'],
+  ['done', '已完成'],
+  ['freeze', '冻结'],
+];
+
+const shortTime = (s) => (s ? String(s).slice(0, 16).replace('T', ' ') : '');
+
+// 单个桶超过这个条数就折叠。已完成常年上百条，全铺出来会把待办挤到看不见。
+const COLLAPSE_AT = 15;
+
+// 一个任务在哪些桶里可能重名 —— id 不是唯一键，UI 必须能显示出来
+const taskKey = (bucket, t) => `${bucket}:${t.id}`;
+
+function TaskRow({ bucket, task, dupCount, onAct }) {
+  const isDone = bucket === 'done';
+  const isFrozen = bucket === 'freeze';
+  const dt = isDone ? task.doneAt : isFrozen ? task.frozenAt : task.createdAt;
+
+  return (
+    <div className="row">
+      <span className="tid">#{task.id}</span>
+      <Copyable className="topic" text={task.topic} title="点击复制主题">{task.topic}</Copyable>
+      <span className="text" title={task.text}>{task.text}</span>
+      {dupCount > 1 ? (
+        <span className="tag" title={`同 id 有 ${dupCount} 条，操作时需要消歧`}>id×{dupCount}</span>
+      ) : null}
+      <span className="muted time">{shortTime(dt)}</span>
+      <span className="acts">
+        {bucket === 'open' ? (
+          <>
+            <button className="btn small" onClick={() => onAct('done', task)}>完成</button>
+            <button className="btn small ghost" onClick={() => onAct('freeze', task)}>冻结</button>
+          </>
+        ) : null}
+        {isFrozen ? (
+          <button className="btn small" onClick={() => onAct('unfreeze', task)}>解冻</button>
+        ) : null}
+        <button className="btn small ghost" onClick={() => onAct('edit', task, bucket)}>编辑</button>
+        <button className="btn small ghost danger" onClick={() => onAct('remove', task, bucket)}>删除</button>
+      </span>
+      {task.note ? <div className="note">{task.note}</div> : null}
+    </div>
+  );
+}
+
+export default function TodoView() {
+  const { boot, ui, patchUi, refreshBoot } = useStore();
+  const toast = useToast();
+  const guard = useGuard();
+  const { dialog, node: dialogNode } = useDialog();
+
+  const [data, setData] = useState(null);
+  const [busy, setBusy] = useState(false);
+  const [form, setForm] = useState({ topic: '', text: '' });
+  const [modal, setModal] = useState(null);
+  // 已完成常常上百条，默认只展示前 N 条，避免整页全是历史噪音
+  const [expanded, setExpanded] = useState({});
+
+  const group = boot?.groupId ?? 0;
+  const groupName = (boot?.groups || []).find((g) => g.id === group)?.name || (group ? `#${group}` : '默认组');
+
+  const load = useCallback(async () => {
+    if (!boot?.loggedIn) return;
+    try {
+      setData(await api('/api/todo'));
+    } catch (e) {
+      toast(e.message);
+    }
+  }, [boot?.loggedIn, toast]);
+
+  useEffect(() => {
+    load();
+    // groupId 变化后必须重取 —— 否则界面还显示上一个工作空间的数据
+  }, [load, group]);
+
+  const reload = useCallback(async () => {
+    setBusy(true);
+    try {
+      await load();
+    } finally {
+      setBusy(false);
+    }
+  }, [load]);
+
+  // 同 id 出现几次 —— 让用户在点「删除」前就看见歧义风险
+  const dupCounts = useMemo(() => {
+    const m = new Map();
+    if (!data) return m;
+    for (const [key] of BUCKETS) {
+      for (const t of data[key] || []) m.set(t.id, (m.get(t.id) || 0) + 1);
+    }
+    return m;
+  }, [data]);
+
+  const filtered = useMemo(() => {
+    if (!data) return null;
+    const topic = ui.topic;
+    const pick = (arr) => (arr ? (topic ? arr.filter((t) => t.topic === topic) : arr) : null);
+    return { open: pick(data.open), done: pick(data.done), freeze: pick(data.freeze) };
+  }, [data, ui.topic]);
+
+  if (!boot?.loggedIn) {
+    return (
+      <div className="card" style={{ padding: 16 }}>
+        <div className="colhead"><h3>请先登录</h3></div>
+        <div className="muted">在「登录」页填写邮箱与密码，或执行 <code>nx-kv auth login &lt;email&gt;</code>。</div>
+      </div>
+    );
+  }
+
+  // 消歧：同 id 多条时让用户选一条（与 CLI 的 --pick 对应）。
+  //
+  // 返回的 `pick` 是**在候选列表里的下标**，必须原样回传给后端 ——
+  // 否则后端会再次面对「同 id 多条」而拒绝执行（这是刻意的：
+  // 不替调用方猜）。候选顺序与服务端 locateAll 一致：
+  // 按 open → done → freeze、桶内按数组顺序。
+  const pickOne = async (task, bucket) => {
+    const candidates = [];
+    for (const [key] of BUCKETS) {
+      for (const t of data[key] || []) if (t.id === task.id) candidates.push({ bucket: key, task: t });
+    }
+    if (candidates.length <= 1) return { bucket, task, pick: undefined };
+
+    const self = candidates.findIndex((c) => c.bucket === bucket && c.task.text === task.text);
+    const answer = await dialog({
+      title: `id #${task.id} 有 ${candidates.length} 条，选哪一条？`,
+      message: candidates
+        .map((c, i) => `[${i}] ${c.bucket}  ${shortTime(c.task.createdAt)}  ${c.task.text.slice(0, 40)}`)
+        .join('\n'),
+      input: true,
+      placeholder: `输入 0..${candidates.length - 1}`,
+      value: String(self >= 0 ? self : 0),
+    });
+    if (answer === null) return null;
+    const i = Number(answer);
+    if (!Number.isInteger(i) || !candidates[i]) {
+      toast(`请输入 0..${candidates.length - 1}`);
+      return null;
+    }
+    return { ...candidates[i], pick: i };
+  };
+
+  const onAct = (act, task, bucket) => guard(async () => {
+    // 会改动「某一条」的动作都要先消歧；状态流转只作用于待办/冻结，那里 id 唯一
+    const needsPick = act === 'remove' || act === 'edit';
+    const target = needsPick ? await pickOne(task, bucket) : { bucket, task, pick: undefined };
+    if (!target) return;
+    const body = { group, pick: target.pick };
+
+    if (act === 'done') {
+      const result = await dialog({ title: '完成结果', message: `完成「${task.text.slice(0, 40)}」`, input: true, placeholder: '可选：写一句完成结果' });
+      if (result === null) return;
+      await api(`/api/todo/${task.id}/done`, { method: 'POST', body: { ...body, result: result || undefined } });
+      toast('已完成');
+    } else if (act === 'freeze') {
+      await api(`/api/todo/${task.id}/freeze`, { method: 'POST', body });
+      toast('已冻结');
+    } else if (act === 'unfreeze') {
+      await api(`/api/todo/${task.id}/unfreeze`, { method: 'POST', body });
+      toast('已解冻');
+    } else if (act === 'remove') {
+      const ok = await dialog({ message: `删除 #${task.id}「${task.text.slice(0, 40)}」？`, danger: true });
+      if (!ok) return;
+      await api(`/api/todo/${target.task.id}`, { method: 'DELETE', body });
+      toast('已删除');
+    } else if (act === 'edit') {
+      const text = await dialog({ title: '编辑内容', input: true, value: target.task.text });
+      if (text === null || !text) return;
+      await api(`/api/todo/${target.task.id}`, {
+        method: 'PATCH',
+        body: { ...body, text, matchTopic: target.task.topic },
+      });
+      toast('已更新');
+    }
+    await reload();
+    await refreshBoot();
+  });
+
+  // 归档：把已完成里较旧的条目移到冷 key（todo:done:cold:<日期>）。
+  // 后端没有「批量删」接口，所以这是清理已完成列表的唯一手段。
+  const archive = () => guard(async () => {
+    const before = await dialog({
+      title: '归档已完成的旧记录',
+      message: '把「完成时间早于该日期」的记录移到冷 key（默认 30 天前）。留空用默认值。',
+      input: true,
+      placeholder: 'YYYY-MM-DD，留空 = 30 天前',
+    });
+    if (before === null) return;
+    const r = await api('/api/todo/archive', { method: 'POST', body: { before: before.trim() || undefined, group } });
+    toast(r.moved ? `已归档 ${r.moved} 条 → ${r.coldKey}` : '没有需要归档的记录');
+    await reload();
+  });
+
+  const add = () => guard(async () => {
+    const topic = form.topic.trim();
+    const text = form.text.trim();
+    if (!topic) { toast('请填主题'); return; }
+    if (!text) { toast('请填内容'); return; }
+    const r = await api('/api/todo', { method: 'POST', body: { topic, text, group } });
+    setForm({ topic, text: '' });
+    toast(`已加入待办 #${r.id}${r.topicAdded ? `（新主题 ${topic}）` : ''}`);
+    await reload();
+  });
+
+  const visible = (key, items) => (expanded[key] ? items : items.slice(0, COLLAPSE_AT));
+
+  const topics = data?.topics || [];
+  const counts = filtered
+    ? BUCKETS.map(([k, label]) => `${label} ${(filtered[k] || []).length}`).join(' · ')
+    : '';
+
+  return (
+    <>
+      <div className="toolbar">
+        <label>工作空间</label>
+        <span className="pill on">{groupName}</span>
+        <span className="sep"></span>
+        <label>主题</label>
+        <select value={ui.topic} onChange={(e) => patchUi({ topic: e.target.value })}>
+          <option value="">全部</option>
+          {topics.map((t) => (
+            <option key={t} value={t}>{t}</option>
+          ))}
+        </select>
+        <span className="sep"></span>
+        <input placeholder="主题" size="8" value={form.topic}
+          onChange={(e) => setForm({ ...form, topic: e.target.value })} />
+        <input placeholder="要做什么…" size="30" value={form.text}
+          onChange={(e) => setForm({ ...form, text: e.target.value })}
+          onKeyDown={(e) => { if (e.key === 'Enter') add(); }} />
+        <button className="btn" onClick={add}>加入待办</button>
+        <button className="btn ghost" onClick={reload} disabled={busy}>{busy ? '刷新中…' : '刷新'}</button>
+      </div>
+
+      <div className="muted" style={{ margin: '0 0 8px 2px', fontSize: 12 }}>{counts}</div>
+
+      <div className="cols">
+        {BUCKETS.map(([key, label]) => (
+          <div className="col" key={key}>
+            <div className="colhead">
+              <h3>{label}</h3>
+              <span className="muted">{(filtered?.[key] || []).length}</span>
+              {key === 'done' && (filtered?.done || []).length ? (
+                <button className="btn small ghost" style={{ marginLeft: 'auto' }} onClick={archive}
+                  title="把较旧的完成记录移到冷 key">归档旧记录</button>
+              ) : null}
+            </div>
+            <div className="card list">
+              {(filtered?.[key] || []).length
+                ? visible(key, filtered[key]).map((t) => (
+                    <TaskRow key={taskKey(key, t)} bucket={key} task={t}
+                      dupCount={dupCounts.get(t.id) || 1} onAct={onAct} />
+                  ))
+                : <div className="row muted">（空）</div>}
+              {(filtered?.[key] || []).length > COLLAPSE_AT ? (
+                <div className="row muted" style={{ cursor: 'pointer', justifyContent: 'center' }}
+                  onClick={() => setExpanded((e) => ({ ...e, [key]: !e[key] }))}>
+                  {expanded[key] ? '收起' : `还有 ${filtered[key].length - COLLAPSE_AT} 条，点击展开`}
+                </div>
+              ) : null}
+            </div>
+          </div>
+        ))}
+      </div>
+
+      <CliHints module="todo" />
+      {modal ? <Modal title={modal.title} onClose={() => setModal(null)}>{modal.node}</Modal> : null}
+      {dialogNode}
+    </>
+  );
+}

package/src/runtime/api.js

@@ -0,0 +1,108 @@
+// HTTP 路由表：由 action.http 编译而来，与 CLI 同源。
+//
+// 这里没有手写路由 —— 每条路由都来自某个模块的 action 声明，
+// 所以「面板上有按钮、CLI 里没命令」在结构上不可能发生。
+import { ACTIONS } from './registry.js';
+import { compileRoute, applySpec } from './spec.js';
+import { toErrorPayload, httpStatusOf, CODES } from '../core/errors.js';
+
+// 逐段比较两条模式，决定谁该先匹配：**字面量段优先于参数段**，段数多的优先。
+//
+// 为什么要排序而不是按声明顺序：`GET /api/repos/status` 与 `GET /api/repos/:id`
+// 都能匹配 `/api/repos/status`，谁先声明谁赢。一旦有人调整 actions 顺序，
+// 前者就会被后者抢走——这种 bug 只在运行时、且只在特定路径上出现，极难排查。
+// 排序后，声明顺序不再影响匹配结果。
+function routeSpecificity([, pattern]) {
+  return pattern.split('/').filter(Boolean);
+}
+
+function compareRoutes(a, b) {
+  const pa = routeSpecificity(a.action.http);
+  const pb = routeSpecificity(b.action.http);
+  for (let i = 0; i < Math.min(pa.length, pb.length); i++) {
+    const litA = !pa[i].startsWith(':');
+    const litB = !pb[i].startsWith(':');
+    if (litA !== litB) return litA ? -1 : 1; // 字面量在前
+  }
+  return pb.length - pa.length; // 更长的（更具体）在前
+}
+
+const ROUTES = ACTIONS.filter((a) => a.http)
+  .map((action) => ({ action, route: compileRoute(action) }))
+  .sort(compareRoutes);
+
+export function sendJson(res, status, obj) {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  });
+  res.end(JSON.stringify(obj));
+}
+
+async function readBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const c of req) {
+    size += c.length;
+    if (size > 4 * 1024 * 1024) throw new Error('请求体过大');
+    chunks.push(c);
+  }
+  if (!chunks.length) return {};
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+
+// 跨站防护。服务虽然只绑 127.0.0.1，但用户浏览器里的任意页面都能向它发起请求——
+// 少了这道校验，一个恶意网页就能 POST /api/repos/scan 或 DELETE /api/repos/:id。
+// 浏览器发跨域请求必带 Origin，非浏览器客户端（curl / agent / 测试）不带，故放行。
+function originAllowed(req) {
+  const origin = req.headers.origin;
+  if (!origin) return true;
+  try {
+    const h = new URL(origin).hostname;
+    return h === '127.0.0.1' || h === 'localhost' || h === '::1';
+  } catch {
+    return false;
+  }
+}
+
+export async function handleApi(req, res, url) {
+  const method = (req.method || 'GET').toUpperCase();
+
+  for (const { action, route } of ROUTES) {
+    if (route.method !== method) continue;
+    const m = route.regex.exec(url.pathname);
+    if (!m) continue;
+
+    if (method !== 'GET' && method !== 'HEAD' && !originAllowed(req)) {
+      sendJson(res, 403, {
+        ok: false,
+        error: '跨站请求被拒绝（面板仅接受本机来源）',
+        code: CODES.BLOCKED,
+      });
+      return;
+    }
+
+    try {
+      const raw = {};
+      route.keys.forEach((k, i) => {
+        raw[k] = decodeURIComponent(m[i + 1]);
+      });
+      if (method === 'GET' || method === 'HEAD') {
+        for (const [k, v] of url.searchParams) raw[k] = v;
+      } else {
+        Object.assign(raw, await readBody(req).catch(() => ({})));
+      }
+      const data = await action.run(applySpec(action, raw), { transport: 'http' });
+      sendJson(res, 200, { ok: true, data });
+    } catch (err) {
+      // 错误码 → HTTP 状态只在这一处映射（core/errors.js 提供表）
+      const p = toErrorPayload(err);
+      const payload = { ok: false, error: p.message, code: p.code };
+      if (p.details !== undefined) payload.details = p.details;
+      sendJson(res, httpStatusOf(p.code), payload);
+    }
+    return;
+  }
+
+  sendJson(res, 404, { ok: false, error: '接口不存在: ' + method + ' ' + url.pathname });
+}

package/src/runtime/cli.js

@@ -0,0 +1,299 @@
+// 通用 CLI 运行器：解析 argv → 匹配 action → 校验 → 执行 → 渲染。
+//
+// 改造前这里是一个 400 行的 switch，每条命令要在 BOOL_FLAGS / helpText / case /
+// renderXxx 四处重复登记。现在命令表、help 文本、参数校验全部由 action 声明派生，
+// 新增命令只需在所属模块的 actions 里加一条。
+import { readFileSync } from 'node:fs';
+import { 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';
+import { cliPathsOf, argSpecsOf, flagSpecsOf, booleanFlagNames, applySpec, usageOf } from './spec.js';
+
+const VERSION = JSON.parse(
+  readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
+).version;
+
+// ---- 平台命令：不属于任何功能域，不参与 action 表 ----
+// 用与 action 相同的形状声明，好让参数解析与 help 生成保持同一套逻辑。
+const BUILTINS = [
+  {
+    id: 'serve',
+    cli: ['serve'],
+    summary: '启动 Web 面板',
+    flags: { port: { type: 'number', default: DEFAULT_PORT }, 'no-open': { type: 'boolean' } },
+    run: (ctx) => cmdServe(ctx),
+  },
+  {
+    id: 'help',
+    cli: ['help'],
+    summary: '显示帮助（可跟模块名或命令组，如 nx-kv help todo）',
+    args: [{ name: 'topic', required: false }],
+    // 走标准 action 形态：--json 时 emit 会序列化返回的条目，
+    // 于是 `help --json` 输出的是可解析的命令表而非帮助文本
+    run: (ctx) => helpEntries(ctx.topic),
+    render: (entries, ctx) => renderHelp(entries, ctx.topic),
+  },
+  // render 让 `nx-kv version` 输出裸版本号（脚本里可 `V=$(nx-kv version)`），
+  // 而 `--json` 仍走序列化，保持机器可读
+  { id: 'version', cli: ['version'], summary: '显示版本', run: () => VERSION, render: (v) => v },
+];
+
+export const ALL_COMMANDS = [...BUILTINS, ...ACTIONS];
+
+// ---- 参数解析 ----
+
+// 全局 flag 先摘掉：它们可以出现在 argv 任意位置，不属于任何 action 的声明。
+function splitGlobals(argv) {
+  const rest = [];
+  let json = false;
+  let cfgPath;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') { json = true; continue; }
+    if (a === '--config') { cfgPath = argv[++i]; continue; }
+    if (a.startsWith('--config=')) { cfgPath = a.slice('--config='.length); continue; }
+    rest.push(a);
+  }
+  return { rest, json, cfgPath };
+}
+
+// 匹配命令：把声明路径与 argv 前缀逐 token 比较，选最长匹配。
+//
+// 逐 token 比较（而非只取「开头连续的非 flag token」）是必需的——有些命令路径
+// 本身就含 flag，例如 `skill install --list` 是「列出内置包」而非「安装」。
+// 最长优先则让 ['skill','central','add'] 压过 ['skill','central']，子命令与别名因此共存。
+export function resolveCommand(argv) {
+  let best = null;
+  let bestLen = -1;
+  for (const cmd of ALL_COMMANDS) {
+    for (const path of cliPathsOf(cmd)) {
+      if (path.length > argv.length || path.length <= bestLen) continue;
+      if (path.every((seg, i) => seg === argv[i])) {
+        best = { cmd, path };
+        bestLen = path.length;
+      }
+    }
+  }
+  return best ? { ...best, rest: argv.slice(bestLen) } : null;
+}
+
+// 解析剩余 token。布尔 flag 不吞下一个 token —— 否则 `skill install --force demo`
+// 会把 force 解析成字符串 'demo'，而 demo 本该是位置参数。
+function parseRest(rest, cmd) {
+  const bools = booleanFlagNames(cmd);
+  const positionals = [];
+  const flags = {};
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (!a.startsWith('--')) { positionals.push(a); continue; }
+    const eq = a.indexOf('=');
+    if (eq > 2) { flags[a.slice(2, eq)] = a.slice(eq + 1); continue; }
+    const key = a.slice(2);
+    const next = rest[i + 1];
+    if (!bools.has(key) && next !== undefined && !next.startsWith('--')) {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  }
+  return { positionals, flags };
+}
+
+// 位置参数按声明顺序映射成具名输入；末尾声明 { rest: true } 的收集剩余全部
+function mapPositionals(positionals, argSpecs) {
+  const out = {};
+  let i = 0;
+  for (const spec of argSpecs) {
+    if (spec.rest) { out[spec.name] = positionals.slice(i); i = positionals.length; break; }
+    if (positionals[i] !== undefined) out[spec.name] = positionals[i];
+    i++;
+  }
+  if (i < positionals.length) {
+    throw badInput(`多余的参数: ${positionals.slice(i).join(' ')}（用法见 nx-kv help）`);
+  }
+  return out;
+}
+
+// 未知 flag 直接报错——`--fiile` 这类拼写错误应该立刻被指出来，而不是被静默忽略
+function assertKnownFlags(flags, cmd) {
+  const known = new Set(flagSpecsOf(cmd).map((f) => f.name));
+  for (const k of Object.keys(flags)) {
+    if (!known.has(k)) throw badInput(`未知参数 --${k}（用法见 nx-kv help）`);
+  }
+}
+
+// ---- 输出 ----
+
+// render 拿到 (data, ctx)，可以是 async——有些渲染需要补一点上下文才能标注
+// （例如候选清单要标出哪一项是「当前」），而 `--json` 必须保持纯数据的旧形状。
+async function emit(cmd, data, json, ctx) {
+  // 无返回值的命令（help / serve 这类）不该打印任何东西：落进 JSON.stringify(undefined)
+  // 会打出字面量 "undefined"，让 `help --json` 的 stdout 不再是合法 JSON。
+  if (data === undefined && !cmd.render) return;
+
+  if (json) {
+    if (data === undefined) return;
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  if (cmd.render) {
+    const text = await cmd.render(data, ctx);
+    if (text !== undefined && text !== null && text !== '') console.log(text);
+    return;
+  }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+// 失败一律 exit 1；--json 下输出可解析的错误对象。
+// 注意 error 保持字符串（历史契约），code 是新增字段——agent 可据此分支，
+// 老消费方按字符串匹配「用法:」「未设置」「不存在」仍然可用。
+function fail(err, json) {
+  const p = toErrorPayload(err);
+  if (json) {
+    const payload = { ok: false, error: p.message, code: p.code };
+    if (p.details !== undefined) payload.details = p.details;
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.error('错误: ' + p.message);
+  }
+  process.exitCode = exitCodeOf(p.code);
+}
+
+// ---- help：完全由命令表生成 ----
+
+// 命令表的一行。`routes` 与 `help` 共用它，因此两张表必然同源同长——
+// 面板底部的「CLI 等价」提示用的也是这个形状（经 bootstrap 下发）。
+export function commandEntry(c) {
+  return {
+    id: c.id,
+    module: c.module || 'platform',
+    command: 'nx-kv ' + cliPathsOf(c)[0].join(' '),
+    usage: usageOf(c),
+    http: c.http ? { method: c.http[0], path: c.http[1] } : null,
+    summary: c.summary,
+  };
+}
+
+// 解析帮助主题。既接受模块 id（repos），也接受命令组（repo）——
+// 用户脑子里想的是「repo 相关的东西」，不会去记内部模块名。
+// 这条路径不能报错退出：`nx-kv help <随便什么>` 失败会让最需要帮助的人卡住。
+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;
+
+  // 命令本身的 id 也认（如 `nx-kv help repo.add`）
+  const byId = all.filter((e) => e.id === t);
+  if (byId.length) return byId;
+
+  const topics = [...new Set(all.map((e) => e.module))].join(', ');
+  throw badInput(`未知帮助主题: ${t}（可用模块: ${topics}；或命令组如 repo / skill / gh）`);
+}
+
+function renderHelp(entries, topic) {
+  const lines = [];
+  if (!topic) {
+    lines.push(`nx-kv · nx-kv v${VERSION}`);
+    lines.push('KV 清单管理中枢：serve 驱动 CLI 与 Web，同源同构。');
+    lines.push(`配置: ${configPathFromEnv()}    （环境变量 NX_KV_CONFIG 或 --config 覆盖）`);
+    lines.push('');
+  }
+
+  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) {
+    const title =
+      MODULES.find((m) => m.id === mod)?.title || (mod === 'platform' ? '平台命令' : mod);
+    lines.push(title + ':');
+    const width = Math.max(...list.map((e) => e.usage.length));
+    for (const e of list) lines.push('  ' + e.usage.padEnd(width + 2) + e.summary);
+    lines.push('');
+  }
+
+  lines.push('通用:');
+  lines.push('  --json    机器可读输出（agent 模式）');
+  lines.push('  --config  本次运行覆盖配置文件路径');
+  return lines.join('\n');
+}
+
+// `nx-kv <命令> --help`：只打印这一条，而不是整个模块——
+// 之前这里传的是 cmd.cli[0]，对别名 action（cli 是数组的数组）会拼出 "bundled,list"。
+function printCommandHelp(cmd) {
+  const lines = [usageOf(cmd)];
+  if (cmd.summary) lines.push('    ' + cmd.summary);
+  lines.push('');
+
+  const aliases = cliPathsOf(cmd).slice(1).map((p) => 'nx-kv ' + p.join(' '));
+  if (aliases.length) lines.push('别名: ' + aliases.join('  ·  '));
+  if (cmd.http) lines.push('对应路由: ' + cmd.http[0] + ' ' + cmd.http[1]);
+  lines.push('所属模块: ' + (cmd.module || 'platform'));
+  console.log(lines.join('\n'));
+}
+
+async function cmdServe(ctx) {
+  const { startServer } = await import('./server.js');
+  const { openBrowser } = await import('../core/open.js');
+  const port = ctx.port || DEFAULT_PORT;
+  const server = await startServer({ port, host: '127.0.0.1' });
+  const addr = `http://127.0.0.1:${server.address().port}`;
+
+  console.log('nx-kv · nx-kv v' + VERSION);
+  console.log(`面板:   ${addr}`);
+  console.log(`配置:   ${configPathFromEnv()}`);
+  console.log('CLI:    nx-kv help（每个按钮都有对应命令，agent 可加 --json）');
+  console.log('按 Ctrl+C 停止');
+
+  if (!ctx['no-open']) openBrowser(addr);
+
+  const shutdown = () => {
+    console.log('\n正在停止...');
+    server.close(() => process.exit(0));
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+// ---- 主入口 ----
+
+export async function runCli(argv) {
+  const { rest, json, cfgPath } = splitGlobals(argv);
+  if (cfgPath) process.env.NX_KV_CONFIG = cfgPath;
+
+  const hit = resolveCommand(rest);
+
+  // 无参数、或只有全局 flag：显示帮助（与历史行为一致，退出码 0）
+  if (!hit) {
+    if (!rest.length) { console.log(renderHelp(helpEntries(), '')); return; }
+    console.error(`未知命令: ${rest.join(' ')}`);
+    console.error('运行 nx-kv help 查看用法');
+    process.exitCode = 1;
+    return;
+  }
+
+  const { cmd, rest: tail } = hit;
+
+  try {
+    if (tail.includes('--help')) { printCommandHelp(cmd); return; }
+
+    const { positionals, flags } = parseRest(tail, cmd);
+    assertKnownFlags(flags, cmd);
+    const input = { ...mapPositionals(positionals, argSpecsOf(cmd)), ...flags };
+    const ctx = applySpec(cmd, input);
+    const data = await cmd.run(ctx, { transport: 'cli' });
+    await emit(cmd, data, json, ctx);
+  } catch (err) {
+    fail(err, json);
+  }
+}