nx-sk 0.3.0

package/src/modules/skill/index.js

@@ -0,0 +1,51 @@
+import * as service from './service.js';
+
+export default {
+  id: 'skill',
+  title: 'Skill',
+  order: 800,
+  // 用户明确要求：skill 不呈现在 Web 面板里（CLI 的 skill install / skill get 保持不变）。
+  // 视图文件已删除 —— 声明了 view 却没有文件会让 vite build 直接报错，两边必须同时改。
+  view: null,
+  actions: [
+    {
+      id: 'skill.list',
+      cli: ['skill', 'list'],
+      http: ['GET', '/api/skills'],
+      summary: '列出随包分发的内置 skill 与其 ref 文档',
+      flags: {},
+      run: () => service.listSkills(),
+      render: (d) => service.renderSkillList(d),
+    },
+    {
+      id: 'skill.install',
+      cli: ['skill', 'install'],
+      http: ['POST', '/api/skills/install'],
+      summary: '把内置 skill 装到 ~/.claude/skills（三态：安装 / 已最新 / 冲突需 --force）；--mode symlink 用软链挂过去，改完立刻生效',
+      args: [{ name: 'name', required: false }],
+      flags: {
+        to: { type: 'string', hint: '安装目录，缺省 ~/.claude/skills' },
+        mode: { type: 'string', enum: ['copy', 'symlink'], hint: 'copy=装副本（默认，可分发）；symlink=软链回项目源码（本机开发，改完立刻生效）' },
+        force: { type: 'boolean', hint: '目标存在且内容不同时覆盖' },
+        'dry-run': { type: 'boolean' },
+      },
+      run: (ctx) => service.installSkill(ctx),
+      render: (d) => service.renderInstall(d),
+    },
+    {
+      id: 'skill.get',
+      cli: ['skill', 'get'],
+      http: ['POST', '/api/skills/get'],
+      summary: '输出 SKILL.md 或 references/<ref> 全文（prefix + 文档 + install 状态三段），同时按 install 逻辑装好',
+      args: [{ name: 'name', required: false }, { name: 'ref', required: false }],
+      flags: {
+        to: { type: 'string' },
+        mode: { type: 'string', enum: ['copy', 'symlink'] },
+        force: { type: 'boolean' },
+        'dry-run': { type: 'boolean', hint: '只输出文档，不装到本机' },
+      },
+      run: (ctx) => service.getSkill(ctx),
+      render: (d) => service.renderSkillContext(d),
+    },
+  ],
+};

package/src/modules/skill/service.js

@@ -0,0 +1,200 @@
+// skill 分发：`skill install` 让识别 ~/.claude/skills 的 agent 学会用 nx-sk；
+// `skill get` 让**不读那个目录**的外部 agent 一次性拿到全上下文（prefix + 文档 + install 状态）。
+// 两条解决的是不同场景，缺一即单边能力归零——所以它们平级，不是补充关系。
+import fsp from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { ASSETS_DIR, SKILL_NAME, assertSafeName, displayPath } from '../../core/paths.js';
+import { copyTree, diffTrees, ensureDir, listFiles, pathExists, readFileText, removeTree } from '../../core/fsx.js';
+import { badInput, notFound } from '../../core/errors.js';
+
+export const DEFAULT_SKILLS_DIR = join(homedir(), '.claude', 'skills');
+
+export async function listSkills() {
+  let names = [];
+  try {
+    const items = await fsp.readdir(ASSETS_DIR, { withFileTypes: true });
+    names = items.filter((i) => i.isDirectory()).map((i) => i.name).sort();
+  } catch { /* assets 缺失 */ }
+  const out = [];
+  for (const n of names) {
+    const src = join(ASSETS_DIR, n);
+    const files = await listFiles(src);
+    const refs = files.filter((f) => f.startsWith('references/'));
+    out.push({
+      name: n,
+      assetsPath: displayPath(src),
+      files: files.length,
+      refs: refs.map((r) => r.replace(/^references\//, '').replace(/\.md$/, '')),
+      hasSkillMd: files.includes('SKILL.md'),
+    });
+  }
+  return { count: out.length, defaultTarget: displayPath(DEFAULT_SKILLS_DIR), skills: out };
+}
+
+async function resolveSkillSource(name) {
+  const n = assertSafeName(name || SKILL_NAME, 'skill 名');
+  const src = join(ASSETS_DIR, n);
+  if (!(await pathExists(join(src, 'SKILL.md')))) {
+    const { skills } = await listSkills();
+    throw notFound(`未找到内置 skill: ${n}（可用: ${skills.map((s) => s.name).join(', ') || '（无）'}）`);
+  }
+  return { name: n, src };
+}
+
+/**
+ * 三态安装，**不静默覆盖**用户目录里的东西。
+ *
+ * 两种模式（骨架 ref 的 `--mode <symlink|copy>`）：
+ * - `copy`（默认，**规范默认**）：把 `assets/<name>` 复制过去。装出来的是副本，
+ *   不受项目目录移动影响，适合 `npx` 分发到别人机器上；代价是改了 `assets/` 不会跟着走。
+ * - `symlink`：把目标**软链**到项目里的源 —— 这就是「shim 到全局」。改代码立刻生效、
+ *   永不漂移，适合本机开发（用户目录里那些 skill 本来就是这么挂的）。
+ */
+export async function installSkill({ name, to, force, mode, 'dry-run': dryRun } = {}) {
+  const { name: n, src } = await resolveSkillSource(name);
+  const dst = join(resolve(to || DEFAULT_SKILLS_DIR), n);
+  const wantsLink = mode === 'symlink';
+
+  if (wantsLink) return installAsLink({ src, dst, force, dryRun });
+
+  const files = await diffTrees(src, dst);
+  if (!files.length) return { status: 'ok', skipped: true, path: displayPath(dst), pathRaw: dst, files: 0 };
+
+  const exists = await pathExists(dst);
+  if (exists && !force) {
+    return {
+      status: 'conflict', path: displayPath(dst), pathRaw: dst, files, count: files.length,
+      hint: '目标已存在且内容不同。确认要覆盖就加 --force（内容一致时不会走到这里）。',
+    };
+  }
+  if (dryRun) {
+    return { status: 'skipped', dryRun: true, wouldInstall: { path: displayPath(dst), replaced: exists, files: files.length, diff: files } };
+  }
+
+  if (exists) await removeTree(dst);
+  await copyTree(src, dst);
+  return { status: 'ok', installed: !exists, replaced: exists, path: displayPath(dst), pathRaw: dst, files: files.length };
+}
+
+/** 软链模式：目标是项目里的源，改完立刻生效。三态照旧（不静默覆盖）。 */
+async function installAsLink({ src, dst, force, dryRun }) {
+  const st = await fsp.lstat(dst).catch(() => null);
+  const pointsAtSrc = st && st.isSymbolicLink() && resolve(await fsp.realpath(dst).catch(() => '')) === resolve(src);
+
+  if (pointsAtSrc) {
+    return {
+      status: 'ok', skipped: true, mode: 'symlink', files: 0,
+      path: displayPath(dst), pathRaw: dst, target: displayPath(src),
+    };
+  }
+
+  const kind = st ? (st.isSymbolicLink() ? '软链（指向别处）' : '真实目录') : null;
+  if (st && !force) {
+    return {
+      status: 'conflict', mode: 'symlink', path: displayPath(dst), pathRaw: dst,
+      existing: kind, target: displayPath(src),
+      hint: `目标已存在（${kind}）。改成软链会动它，确认就加 --force。`,
+    };
+  }
+  if (dryRun) {
+    return {
+      status: 'skipped', dryRun: true, wouldInstall: { mode: 'symlink', path: displayPath(dst), target: displayPath(src), replaced: !!st },
+    };
+  }
+
+  if (st) await removeTree(dst);
+  await ensureDir(join(dst, '..'));   // symlink 不会自建父目录（copyTree 会），不补这步就 ENOENT
+  // Windows 上用 junction：目录软链需要特权（或开发者模式），junction 不需要。
+  await fsp.symlink(src, dst, process.platform === 'win32' ? 'junction' : 'dir');
+  return {
+    status: 'ok', mode: 'symlink', installed: !st, replaced: !!st, files: 0,
+    path: displayPath(dst), pathRaw: dst, target: displayPath(src),
+  };
+}
+
+/**
+ * ref 解析规则（agent 一键输入，输入门槛最低优先）：
+ *   缺省                     → SKILL.md
+ *   含分隔符或 ./\ 开头       → 相对 assets/<name>/ 解析
+ *   裸名                     → 先 references/<名>.md，再 <名>.md，再 <名>
+ *   `..` 或绝对路径           → 拒绝
+ */
+export async function resolveRef(name, ref) {
+  const raw = String(ref ?? '').trim();
+  if (raw.includes('..')) throw badInput("ref 路径不允许包含 '..'");
+  if (isAbsolute(raw) || /^[A-Za-z]:[\\/]/.test(raw)) throw badInput(`ref 越界: ${raw}`);
+
+  const base = join(ASSETS_DIR, name);
+  if (!raw) return { rel: 'SKILL.md', abs: join(base, 'SKILL.md') };
+  if (raw.includes('/') || raw.includes('\\') || raw.startsWith('.')) {
+    const rel = raw.replace(/^\.\//, '').replace(/\\/g, '/');
+    if (rel.includes('..')) throw badInput("ref 路径不允许包含 '..'");
+    return { rel, abs: join(base, rel) };
+  }
+  const candidates = [`references/${raw}.md`, `${raw}.md`, raw];
+  for (const c of candidates) {
+    const abs = join(base, c);
+    if (await pathExists(abs)) return { rel: c, abs };
+  }
+  const refs = (await listFiles(join(base, 'references'))).map((f) => f.replace(/\.md$/, ''));
+  throw badInput(`未知 ref: ${raw}（可用: ${refs.join(', ') || '（无）'}；也可直接写 references/xxx.md）`);
+}
+
+export async function getSkill({ name, ref, to, force, mode, 'dry-run': dryRun } = {}) {
+  const { name: n } = await resolveSkillSource(name);
+  const { rel, abs } = await resolveRef(n, ref);
+  const content = await readFileText(abs);
+  // `skill get` 永远给文档——哪怕目标是 conflict 状态，文档也照常输出。
+  // 「目标端有 diff」是用户的决策范畴，不是 agent 的中止信号。
+  const install = await installSkill({ name: n, to, force, mode, 'dry-run': dryRun });
+  return {
+    skillName: n,
+    ref: rel,
+    content,
+    contentBytes: Buffer.byteLength(content, 'utf8'),
+    install,
+  };
+}
+
+// —— 人读渲染：prefix → 文档 → install 状态，**三段顺序固定** ──
+// 顺序为什么重要：部分 agent 输出过长会自动截断——prefix 必须在最前告诉它
+// 「这是哪个 skill、建议把内容复制到自己可访问的路径」，否则它拿到一坨文档不知道要干什么。
+export function renderSkillContext(d) {
+  const sentinel = '# --- begin skill content (do not modify this line) ---';
+  const prefix = [
+    `# === nx-sk skill context ===`,
+    `# 以下内容来自 nx-sk skill \`${d.skillName}\` 的 ${d.ref}。`,
+    '# nx-sk 是本机个人资源管理器（栏目化存个人信息与大模型密钥，CLI 与 Web 同源）。',
+    '# 如果你（agent）不能直接读取 ~/.claude/skills 目录，请把下面 sentinel 之间、',
+    '# 到下一处 "-- install 状态 --" 之前的内容**完整复制**到你自己的上下文或可访问的文件里，',
+    '# 然后按文档里的命令操作用户的本机数据。',
+    sentinel,
+  ].join('\n');
+  const install = renderInstall(d.install);
+  return `${prefix}\n\n${d.content}\n\n-- install 状态 --\n${install}`;
+}
+
+export function renderInstall(r) {
+  if (!r) return '（未知）';
+  if (r.status === 'skipped' && r.dryRun) return `试运行：将装到 ${r.wouldInstall.path}（${r.wouldInstall.files} 个文件，替换已有: ${r.wouldInstall.replaced ? '是' : '否'}）`;
+  if (r.skipped) return `已是最新: ${r.path}${r.mode === 'symlink' ? `（已软链到 ${r.target}）` : '（与内置内容一致，无差异）'}`;
+  if (r.status === 'conflict' && r.mode === 'symlink') {
+    return `冲突: ${r.path} 已存在（${r.existing}）。改软链会动它，确认：nx-sk skill install ${SKILL_NAME} --mode symlink --force`;
+  }
+  if (r.status === 'conflict') return `冲突: ${r.path} 已存在且内容不同（${r.count} 个文件有差异）。确认覆盖：nx-sk skill install ${SKILL_NAME} --force`;
+  if (r.mode === 'symlink') return `已软链: ${r.path} → ${r.target}（改项目里的源码立刻生效）`;
+  if (r.installed) return `已安装: ${r.path}（${r.files} 个文件）`;
+  if (r.replaced) return `已替换: ${r.path}（${r.files} 个文件）`;
+  return `完成: ${r.path}`;
+}
+
+export function renderSkillList(d) {
+  const lines = [`内置 skill ${d.count} 个　默认安装位置: ${d.defaultTarget}`];
+  for (const s of d.skills) {
+    lines.push(`  ${s.name.padEnd(12)} ${s.files} 个文件　refs: ${s.refs.join(', ') || '（无）'}`);
+  }
+  lines.push('', `装到本机: nx-sk skill install ${SKILL_NAME}`);
+  lines.push(`给外部 agent 取上下文: nx-sk skill get ${SKILL_NAME} --json`);
+  return lines.join('\n');
+}

package/src/modules/system/index.js

@@ -0,0 +1,42 @@
+import * as service from './service.js';
+
+export default {
+  id: 'system',
+  title: '系统',
+  order: 100,
+  // 聚合模块：只读聚合，没有面板（面板里没有「系统」这个 tab）
+  view: null,
+  actions: [
+    {
+      id: 'system.bootstrap',
+      cli: ['bootstrap'],
+      http: ['GET', '/api/bootstrap'],
+      summary: '一次性拿齐上下文：版本 / 存储路径 / 栏目 / 设置 / 命令表',
+      flags: {},
+      run: () => service.bootstrapInfo(),
+      render: (d) => service.renderBootstrap(d),
+    },
+    {
+      id: 'system.health',
+      cli: ['health'],
+      http: ['GET', '/api/health'],
+      summary: '存活与存储可达性检查',
+      flags: {},
+      run: () => service.healthInfo(),
+      render: (d) => service.renderHealth(d),
+    },
+    {
+      id: 'system.routes',
+      cli: ['routes'],
+      http: ['GET', '/api/routes'],
+      summary: '命令与 HTTP 路由的双向对照表',
+      flags: {
+        // 读命令的过滤 flag 一律不带 default：「不传」本身代表「全部」
+        module: { type: 'string', hint: '模块 id 或命令组' },
+        http: { type: 'string', hint: '"POST /api/entries" 形式的路由' },
+      },
+      run: (ctx) => service.routesInfo(ctx),
+      render: (d) => service.renderRoutes(d),
+    },
+  ],
+};

package/src/modules/system/service.js

@@ -0,0 +1,155 @@
+// system 是聚合模块：它读各处的状态拼上下文，不产生业务实体，所以没有视图。
+import fsp from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { APP_LABEL, APP_NAME, ENV_HOME, ENV_PASSPHRASE, ENV_STORE, VERSION, appHome, displayPath, storeFile } from '../../core/paths.js';
+import { loadStore, corruptNote, listSnapshots, migrationNote, storePathInUse } from '../../core/store.js';
+import { vaultStatus } from '../../core/vault.js';
+import { templateSummaries } from '../../core/fields.js';
+import { blocked } from '../../core/errors.js';
+import { compileRoute, usageOf } from '../../runtime/spec.js';
+
+/**
+ * 命令表在 runtime/registry.js，而分层规则说模块不能向上依赖 runtime。
+ * 用**函数体内的动态 import** 破环：静态 import 会成环，动态 import 不会
+ * （调用发生在启动完成之后，registry 早已求值完毕）。
+ */
+async function commandTable() {
+  const { ALL_COMMANDS, commandEntry } = await import('../../runtime/cli.js');
+  return ALL_COMMANDS.map(commandEntry);
+}
+
+export async function bootstrapInfo() {
+  const store = await loadStore();
+  const p = storePathInUse();
+  const commands = await commandTable();
+  const bySection = {};
+  for (const e of store.entries) bySection[e.section] = (bySection[e.section] || 0) + 1;
+  return {
+    app: { name: APP_NAME, label: APP_LABEL, version: VERSION, node: process.version, platform: process.platform },
+    home: displayPath(appHome()),
+    storePath: displayPath(p),
+    storePathRaw: p,
+    envOverrides: {
+      [ENV_HOME]: process.env[ENV_HOME] || null,
+      [ENV_STORE]: process.env[ENV_STORE] || null,
+      [ENV_PASSPHRASE]: process.env[ENV_PASSPHRASE] ? '已设置（口令模式）' : null,
+    },
+    settings: store.settings,
+    // kv 必须带上：bootstrap 是 agent 的首选入口，它得能一眼看出「哪个栏目是 KV 表」
+    // （缺这字段时 agent 只能猜 `/api/sections` 再去查，等于多一次往返）。
+    sections: store.sections.map((s) => ({
+      id: s.id, title: s.title, description: s.description, order: s.order, template: s.template,
+      kv: s.kv === true, titleLabel: s.titleLabel, fields: s.fields.length, entries: bySection[s.id] || 0,
+    })),
+    counts: { sections: store.sections.length, entries: store.entries.length, commands: commands.length },
+    vault: await vaultStatus(),
+    templates: templateSummaries(),
+    snapshots: (await listSnapshots()).slice(0, 5),
+    corrupt: corruptNote(),
+    migration: migrationNote(),
+    commands,
+  };
+}
+
+export async function healthInfo() {
+  const home = appHome();
+  const checks = [];
+
+  let dirOk = true;
+  let dirError = '';
+  try {
+    await fsp.mkdir(home, { recursive: true });
+    await fsp.access(home, constants.W_OK);
+  } catch (e) {
+    dirOk = false;
+    dirError = String(e && e.message);
+  }
+  checks.push({ name: 'store-dir', path: displayPath(home), ok: dirOk, detail: dirError });
+
+  let storeOk = true;
+  let storeDetail = '';
+  let sections = 0;
+  let entries = 0;
+  try {
+    const s = await loadStore();
+    sections = s.sections.length;
+    entries = s.entries.length;
+    storeDetail = `${sections} 栏目 / ${entries} 条目`;
+  } catch (e) {
+    storeOk = false;
+    storeDetail = String(e && e.message);
+  }
+  checks.push({ name: 'store', path: displayPath(storeFile()), ok: storeOk, detail: storeDetail });
+
+  let vault = null;
+  try {
+    vault = await vaultStatus();
+    checks.push({ name: 'vault', path: vault.keyFile || vault.saltFile || '', ok: vault.ready, detail: vault.source });
+  } catch (e) {
+    checks.push({ name: 'vault', path: '', ok: false, detail: String(e && e.message) });
+  }
+
+  const failing = checks.filter((c) => !c.ok);
+  if (failing.length) {
+    throw blocked(
+      `健康检查未通过：${failing.map((c) => `${c.name}（${c.detail}）`).join('；')}`,
+      { checks },
+    );
+  }
+  return { status: 'ok', app: APP_NAME, version: VERSION, cwd: process.cwd(), sections, entries, vault, checks };
+}
+
+export async function routesInfo({ module, http } = {}) {
+  const { ALL_COMMANDS, commandEntry } = await import('../../runtime/cli.js');
+  let entries = ALL_COMMANDS.map(commandEntry);
+  if (module) entries = entries.filter((e) => e.module === module || e.id === module);
+  if (http) {
+    // 反向查找：有端点，查该敲哪条命令。复用路由编译时的正则，所以带参路由也能匹配实例。
+    const raw = String(http).trim().replace(/\s+/g, ' ');
+    const sp = raw.indexOf(' ');
+    const method = (sp > 0 ? raw.slice(0, sp) : 'GET').toUpperCase();
+    const path = (sp > 0 ? raw.slice(sp + 1) : raw).split('?')[0];
+    entries = entries.filter((e) => {
+      if (!e.http) return false;
+      const route = compileRoute(e.http.split(' '));
+      return route.method === method && route.regex.test(path);
+    });
+  }
+  return {
+    count: entries.length,
+    total: (await commandTable()).length,
+    entries: entries.map((e) => ({ ...e, usage: e.usage })),
+  };
+}
+
+export function renderBootstrap(info) {
+  const lines = [
+    `${info.app.label} v${info.app.version}（node ${info.app.node} · ${info.app.platform}）`,
+    `存储:   ${info.storePath}`,
+    `栏目:   ${info.counts.sections} 个 · 条目 ${info.counts.entries} 条 · 命令 ${info.counts.commands} 条`,
+    `密钥:   ${info.vault.source === 'env' ? '口令模式（NX_SK_PASSPHRASE）' : `本机密钥文件 ${info.vault.keyFile}`}`,
+  ];
+  if (info.corrupt) lines.push(`注意: 上次读取时发现损坏文件，已挪到 ${info.corrupt.to}`);
+  lines.push('', '栏目一览：');
+  for (const s of info.sections) lines.push(`  ${s.id.padEnd(12)} ${s.title}　${s.entries} 条 / ${s.fields} 字段`);
+  lines.push('', `提示: ${APP_NAME} help 看全部命令；加 --json 得机器可读输出。`);
+  return lines.join('\n');
+}
+
+export function renderHealth(h) {
+  const lines = [`${h.status === 'ok' ? '正常' : '异常'} · ${h.app} v${h.version}`, `cwd: ${h.cwd}`];
+  for (const c of h.checks) lines.push(`  [${c.ok ? 'ok' : '!!'}] ${c.name.padEnd(12)} ${c.detail}`);
+  return lines.join('\n');
+}
+
+export function renderRoutes(r) {
+  const lines = [`共 ${r.count} / ${r.total} 条命令`];
+  for (const e of r.entries) {
+    lines.push(`  ${e.command}${e.http ? `  <=>  ${e.http}` : ''}`);
+    lines.push(`      ${e.summary}`);
+  }
+  lines.push('', '用法串见: nx-sk help <主题>');
+  return lines.join('\n');
+}
+
+export { usageOf };

package/src/runtime/api.js

@@ -0,0 +1,101 @@
+// HTTP 路由：由 action.http 编译而来，与 CLI **同源**。
+// ctx 拼装顺序固定为「路径占位符 → query（GET/HEAD）或 body（其余）」，
+// 之后交给**同一个** applySpec 做校验与强转——两端不会各写一套。
+import { AppError, CODES, httpStatusOf, toErrorShape } from '../core/errors.js';
+import { ACTIONS } from './registry.js';
+import { applySpec, compareRoutes, compileRoute, usageOf } from './spec.js';
+
+const MAX_BODY = 4 * 1024 * 1024;
+
+export const ROUTES = ACTIONS
+  .filter((a) => Array.isArray(a.http))
+  .map((a) => ({ action: a, ...compileRoute(a.http) }))
+  // 字面量段优先：否则 GET /api/sections/templates 会被 GET /api/sections/:ref 遮蔽，
+  // 命中哪条取决于 actions 的声明顺序——有人调整顺序就静默错乱。
+  .sort(compareRoutes);
+
+export function routeTable() {
+  return ROUTES.map((r) => ({ method: r.method, path: r.path, action: r.action.id, summary: r.action.summary }));
+}
+
+export function matchRoute(method, pathname) {
+  for (const r of ROUTES) {
+    if (r.method !== method) continue;
+    const m = r.regex.exec(pathname);
+    if (m) return { route: r, params: m.slice(1).map((x) => decodeURIComponent(x)) };
+  }
+  return null;
+}
+
+async function readBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const c of req) {
+    size += c.length;
+    if (size > MAX_BODY) throw new AppError(CODES.INVALID_INPUT, '请求体过大');
+    chunks.push(c);
+  }
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    throw new AppError(CODES.INVALID_INPUT, '请求体不是合法 JSON');
+  }
+}
+
+/** 服务在 127.0.0.1，但用户浏览器里的任意页面都能向它发请求——写操作必须校验 Origin。 */
+function originAllowed(req) {
+  const origin = req.headers.origin;
+  if (!origin) return true; // 非浏览器客户端（curl / agent / 测试）不带 Origin，放行
+  try {
+    return ['127.0.0.1', 'localhost', '::1'].includes(new URL(origin).hostname);
+  } catch {
+    return false;
+  }
+}
+
+function send(res, status, payload) {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+export async function handleApi(req, res, url) {
+  const method = String(req.method || 'GET').toUpperCase();
+  const write = method !== 'GET' && method !== 'HEAD';
+
+  if (write && !originAllowed(req)) {
+    return send(res, 403, { ok: false, error: '跨站写操作被拒绝（Origin 不在本机）', code: CODES.BLOCKED });
+  }
+
+  const hit = matchRoute(method, url.pathname);
+  if (!hit) {
+    return send(res, 404, { ok: false, error: `未知接口: ${method} ${url.pathname}`, code: CODES.NOT_FOUND });
+  }
+
+  const { route, params } = hit;
+  const raw = {};
+  route.keys.forEach((k, i) => { raw[k] = params[i]; }); // 路径占位符
+  if (!write) {
+    for (const [k, v] of url.searchParams) raw[k] = v; // query
+  } else {
+    // ⚠️ 无条件合并 body，而不是「只有 body 里有才覆盖」——否则无 body 的 DELETE
+    // 永远绑不上参数（args 与路由占位符靠「同名」绑定，名字对不上就静默传 undefined）
+    Object.assign(raw, await readBody(req).catch((err) => { throw err; }));
+  }
+
+  try {
+    const ctx = applySpec(route.action, raw);
+    const data = await route.action.run(ctx, { transport: 'http' });
+    return send(res, 200, { ok: true, data: data === undefined ? null : data });
+  } catch (err) {
+    const e = toErrorShape(err);
+    // 与 CLI 同一个约定：参数类错误必须带用法串（两端错误码与文本锚点一致）
+    if (e.code === CODES.INVALID_INPUT && !e.message.includes('用法:')) {
+      e.message += `\n用法: ${usageOf(route.action)}`;
+    }
+    return send(res, httpStatusOf(e.code), { ok: false, error: e.message, code: e.code });
+  }
+}