nx-kv 0.1.1

package/bin/cli.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// nx-kv 唯一入口。
+// 设计约定：Web 面板上每个按钮，都对应这里的一条 CLI 命令——二者由同一份 action
+// 声明派生（见 src/modules/*/index.js），不是靠人维护两份清单。
+import { runCli } from '../src/runtime/cli.js';
+
+runCli(process.argv.slice(2)).catch((err) => {
+  console.error(err && err.stack ? err.stack : String(err));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "nx-kv",
+  "version": "0.1.1",
+  "description": "nx-kv — KV 清单管理中枢：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 领取主题任务",
+  "type": "module",
+  "bin": {
+    "nx-kv": "bin/cli.mjs"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "dev:serve": "node bin/cli.mjs serve --no-open",
+    "start": "pnpm run build && node bin/cli.mjs serve",
+    "lint": "eslint .",
+    "test": "pnpm run lint && pnpm run build && pnpm run test:smoke && pnpm run test:unit",
+    "test:smoke": "node tests/smoke.mjs",
+    "test:unit": "node --test tests/unit/*.test.mjs"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "assets/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "cli",
+    "web-panel",
+    "kv",
+    "todo",
+    "agent-tools",
+    "skills",
+    "npx"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/On-DevPlan/nx-kv.git"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@vitejs/plugin-react": "^6.1.1",
+    "eslint": "^10.10.0",
+    "vite": "^8.3.0"
+  },
+  "dependencies": {
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  }
+}

package/src/core/config.js

@@ -0,0 +1,94 @@
+// 本机配置：后端地址 + 登录态。
+//
+// 与业务数据（KV 清单）分开存放：清单在服务端，这里只存「怎么连过去」。
+// 复用 store.js 的原子写语义，但结构独立——配置是单例，不是集合。
+import fsp from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { badInput } from './errors.js';
+
+export const CONFIG_PATH = join(homedir(), '.nx-kv', 'config.json');
+
+// 测试与多实例覆盖：NX_KV_CONFIG 环境变量优先，其次是 NX_KV_STORE 所在目录
+export function configPathFromEnv() {
+  return process.env.NX_KV_CONFIG || CONFIG_PATH;
+}
+
+export const DEFAULT_BASE_URL = 'http://47.110.80.47:8988';
+
+const EMPTY = () => ({
+  baseUrl: process.env.NX_KV_BASE_URL || DEFAULT_BASE_URL,
+  token: '',
+  email: '',
+  userId: 0,
+  // 当前工作空间：0 = 不传 groupId（后端回落默认组）
+  groupId: 0,
+});
+
+let cache = null;
+let cacheMtime = -1;
+
+function normalize(data) {
+  const base = EMPTY();
+  if (!data || typeof data !== 'object') return base;
+  return {
+    baseUrl: String(data.baseUrl || base.baseUrl),
+    token: String(data.token || ''),
+    email: String(data.email || ''),
+    userId: Number(data.userId) || 0,
+    groupId: Number(data.groupId) || 0,
+  };
+}
+
+export async function loadConfig(explicitPath) {
+  const p = explicitPath || configPathFromEnv();
+  try {
+    const st = await fsp.stat(p);
+    if (cache && cacheMtime === st.mtimeMs) return cache;
+    cache = normalize(JSON.parse(await fsp.readFile(p, 'utf8')));
+    cacheMtime = st.mtimeMs;
+    return cache;
+  } catch {
+    // 不存在或损坏：返回默认结构（首次运行；也允许外部修好后自动恢复）
+    cache = normalize(null);
+    cacheMtime = -1;
+    return cache;
+  }
+}
+
+export async function saveConfig(next, explicitPath) {
+  const p = explicitPath || configPathFromEnv();
+  const data = normalize(next);
+  await fsp.mkdir(dirname(p), { recursive: true });
+  const tmp = p + '.tmp';
+  await fsp.writeFile(tmp, JSON.stringify(data, null, 2), 'utf8');
+  await fsp.rename(tmp, p);
+  cache = data;
+  try {
+    cacheMtime = (await fsp.stat(p)).mtimeMs;
+  } catch {
+    cacheMtime = -1;
+  }
+  return data;
+}
+
+export async function updateConfig(patch) {
+  const cur = await loadConfig();
+  return saveConfig({ ...cur, ...patch });
+}
+
+// 读配置并要求已登录。所有需要 token 的 action 都先过这里，
+// 报错文案里的「未登录」是 agent 的失败分类锚点（与 kvcli 保持一致）。
+export async function requireAuth() {
+  const cfg = await loadConfig();
+  if (!cfg.token) {
+    throw badInput('未登录（先执行 nx-kv auth login <email>）');
+  }
+  return cfg;
+}
+
+// groupId 归一：0 / 负数 / 空 → undefined（不传参，由后端回落默认组）
+export function normalizeGroupId(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}

package/src/core/errors.js

@@ -0,0 +1,81 @@
+// 错误契约：**失败抛 AppError，业务结果返回 {status}**。
+//
+// 这条边界是整个项目最重要的一条约定，判定标准是「调用方要不要处理它」：
+//
+// - 失败（参数非法、目标不存在、外部命令挂掉、数据损坏）
+//   → throw。调用方无从处理，只能中断当前操作并上报。API 映射成 4xx/5xx，
+//     CLI 映射成 exit 1 + 可解析文本。
+// - 业务结果（同步遇到冲突等待选侧、幂等跳过、规则阻止删除）
+//   → return { status: 'ok' | 'skipped' | 'conflict' | 'blocked', ... }。
+//     这不是错误——UI 要拿它弹窗让用户决策，所以绝不能抛。
+//
+// 历史教训：改造前同一层里并存 throw / {ok:false} / {status} / {available} 四种
+// 表达，上层只能靠字符串猜，无法程序化分支。
+//
+// 兼容约束：assets/repo-hub/references/agent-workflow.md 教 agent 用错误文本里的
+// 「用法:」「未设置」「不存在」三个子串分类失败。message 可以追加内容，但不得删除它们。
+
+export const CODES = {
+  INVALID_INPUT: 'INVALID_INPUT', // 参数缺失/非法/越界
+  NOT_FOUND: 'NOT_FOUND', // 目标不存在
+  CONFLICT: 'CONFLICT', // 状态冲突，需调用方决策
+  BLOCKED: 'BLOCKED', // 业务规则主动阻止
+  EXTERNAL: 'EXTERNAL', // 外部命令（git / gh）失败
+  INTERNAL: 'INTERNAL', // 兜底
+};
+
+// code -> HTTP 状态。只在这里映射一次，api.js 不再自行判断。
+const HTTP_STATUS = {
+  [CODES.INVALID_INPUT]: 400,
+  [CODES.NOT_FOUND]: 404,
+  [CODES.CONFLICT]: 409,
+  [CODES.BLOCKED]: 409,
+  [CODES.EXTERNAL]: 502,
+  [CODES.INTERNAL]: 500,
+};
+
+// code -> 进程退出码。CLI 只区分「成功 / 失败」，保持 agent-workflow.md 声明的契约。
+const EXIT_CODE = {
+  [CODES.INVALID_INPUT]: 1,
+  [CODES.NOT_FOUND]: 1,
+  [CODES.CONFLICT]: 1,
+  [CODES.BLOCKED]: 1,
+  [CODES.EXTERNAL]: 1,
+  [CODES.INTERNAL]: 1,
+};
+
+export class AppError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.name = 'AppError';
+    this.code = CODES[code] ? code : CODES.INTERNAL;
+    if (details !== undefined) this.details = details;
+  }
+}
+
+export function httpStatusOf(code) {
+  return HTTP_STATUS[code] || 500;
+}
+
+export function exitCodeOf(code) {
+  return EXIT_CODE[code] || 1;
+}
+
+// 把任意抛出物归一成 { code, message, details }，供 API / CLI 统一序列化。
+// 非 AppError 一律归为 INTERNAL——不把内部堆栈细节泄漏给 agent。
+export function toErrorPayload(err) {
+  if (err instanceof AppError) {
+    const out = { code: err.code, message: err.message };
+    if (err.details !== undefined) out.details = err.details;
+    return out;
+  }
+  return { code: CODES.INTERNAL, message: String((err && err.message) || err) };
+}
+
+// ---- 构造快捷方式：让 service 层读起来是「为什么失败」而不是「怎么构造」 ----
+
+export const badInput = (message, details) => new AppError(CODES.INVALID_INPUT, message, details);
+export const notFound = (message, details) => new AppError(CODES.NOT_FOUND, message, details);
+export const conflict = (message, details) => new AppError(CODES.CONFLICT, message, details);
+export const blocked = (message, details) => new AppError(CODES.BLOCKED, message, details);
+export const external = (message, details) => new AppError(CODES.EXTERNAL, message, details);

package/src/core/frontmatter.js

@@ -0,0 +1,65 @@
+// SKILL.md frontmatter 解析（与 fileops.go / gitimporter.go 同语义，另修 CRLF）。
+//
+// 关键点：Windows 上 SKILL.md 通常是 CRLF，必须先归一化换行再逐行解析，
+// 否则 JS 正则的 `$`（非 multiline）无法匹配行尾残留的 \r，name/description 会全部丢失。
+//
+// 只解析 name / description 两个字段——不引入 YAML 依赖，手写够用的子集：
+// 单行值、成对引号值、| / > 块标量、缩进续行。
+
+// 返回 { name, description }；无 frontmatter 或字段缺失时为空串（调用方自行兜底）
+export function parseFrontmatter(raw) {
+  // 去 BOM：用 charCodeAt 判定而非正则字面量，避免源码里出现不可见的 BOM 字符
+  let content = String(raw ?? '');
+  if (content.charCodeAt(0) === 0xfeff) content = content.slice(1);
+  content = content.replace(/\r\n?/g, '\n');
+  const m = /^---[ \t]*\n([\s\S]*?)\n---[ \t]*(\n|$)/.exec(content);
+  if (!m) return { name: '', description: '' };
+  const lines = m[1].split('\n');
+  return {
+    name: readField(lines, 'name').trim(),
+    description: readField(lines, 'description').trim(),
+  };
+}
+
+// 去掉包裹的成对引号
+function unquote(v) {
+  const s = v.trim();
+  if (s.length >= 2 && ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'")))) {
+    return s.slice(1, -1).trim();
+  }
+  return s;
+}
+
+// 读取 frontmatter 字段：支持单行值、引号值、| / > 块标量、以及缩进续行
+function readField(lines, key) {
+  const re = new RegExp('^' + key + ':[ \\t]*(.*)$');
+  for (let i = 0; i < lines.length; i++) {
+    const m = re.exec(lines[i]);
+    if (!m) continue;
+    const rawVal = m[1].trim();
+    const isBlock = /^[|>][-+]?$/.test(rawVal);
+    if (!isBlock && rawVal !== '') return unquote(rawVal);
+
+    // 块标量或空值：收集后续缩进行（YAML 多行标量）
+    const block = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (l.trim() === '') {
+        block.push('');
+        continue;
+      }
+      if (!/^[ \t]/.test(l)) break;
+      block.push(stripIndent(l));
+    }
+    const text = block.join('\n').trim();
+    if (text) return rawVal.startsWith('>') ? text.replace(/\s*\n\s*/g, ' ').trim() : text;
+    return unquote(rawVal);
+  }
+  return '';
+}
+
+function stripIndent(l) {
+  if (l.startsWith('  ')) return l.slice(2);
+  if (l.startsWith('\t')) return l.slice(1);
+  return l.replace(/^[ \t]+/, '');
+}

package/src/core/fstree.js

@@ -0,0 +1,74 @@
+// 文件系统原语：存在性判定、内容摘要、目录树遍历与逐文件差异。
+// 零业务语义——skill 同步（两侧目录比较）与内置包安装（包内目录比较）共用同一套。
+//
+// 从 services/skills.js 下沉而来：这些函数被 bundled.js 跨模块使用，
+// 原本造成 service 之间的横向依赖，属于通用能力。
+import { join } from 'node:path';
+import fsp from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+
+// access 判存在。**是否穿透链接由操作系统决定**，不是一个可靠的判据：
+// POSIX 上悬空 symlink 返回 false，而 Windows 上悬空 junction 返回 true。
+// 因此凡是「必须认出悬空链接」的场合一律用 pathExists，不要用这个。
+export async function exists(p) {
+  try {
+    await fsp.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// lstat 判存在：不跟随链接，看的是链接本身。
+// 悬空链接（目标已被删）也算「存在」——这正是它被需要的原因：
+// 中心侧删掉 skill 后，项目侧的链接要能被列出来并删除，否则就成了删不掉的幽灵。
+export async function pathExists(p) {
+  try {
+    await fsp.lstat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function md5Of(buf) {
+  return createHash('md5').update(buf).digest('hex');
+}
+
+// 递归收集目录下所有文件：rel 路径 -> { abs, md5, size }
+export async function walkFiles(root) {
+  const files = new Map();
+  async function walk(dir, rel) {
+    const entries = await fsp.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const e of entries) {
+      const abs = join(dir, e.name);
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) await walk(abs, r);
+      else if (e.isFile()) {
+        const buf = await fsp.readFile(abs).catch(() => null);
+        if (buf === null) continue;
+        files.set(r, { abs, md5: md5Of(buf), size: buf.length });
+      }
+    }
+  }
+  await walk(root, '');
+  return files;
+}
+
+// 两棵目录树的差异：逐文件 md5 比较。
+// side 语义固定为 a 侧视角：only-central=仅 a 有 / only-project=仅 b 有 / both-differ=两侧都有但不同。
+// 命名沿用「中心 vs 项目」场景，调用方按 a=基准侧 理解即可。
+// 注意：bRoot 不存在时视为空树（bundled.js 用不存在的路径当哨兵来列出全部文件）。
+export async function diffTrees(aRoot, bRoot) {
+  const [a, b] = await Promise.all([walkFiles(aRoot), walkFiles(bRoot)]);
+  const out = [];
+  for (const [rel, fa] of a) {
+    const fb = b.get(rel);
+    if (!fb) out.push({ file: rel, side: 'only-central' });
+    else if (fa.md5 !== fb.md5) out.push({ file: rel, side: 'both-differ' });
+  }
+  for (const [rel] of b) {
+    if (!a.has(rel)) out.push({ file: rel, side: 'only-project' });
+  }
+  return out;
+}

package/src/core/kvapi.js

@@ -0,0 +1,201 @@
+// 后端 KV 客户端 —— 对接 47 服务器的 goframe 接口。
+//
+// 信封约定：**HTTP 状态恒为 200，成败看 body 里的 `code`**（0 = 成功）。
+// 这一点与常见的 REST 直觉相反，所以统一收在本文件里判断；
+// 上层 service 只看到「成功返回 data / 失败抛异常」，不必各自解析信封。
+//
+// 端点（来自 Flutter 端 api/goframe/kv/kv_endpoint.dart 与 user/user_auth_service.dart）：
+//   POST   /api/v1/user/login   { email, password }        → { token, userId }
+//   GET    /api/v1/kv/{key}[?groupId=N]                    → { key, value, expires_at, tags }
+//   POST   /api/v1/kv           { key, value, ttl, groupId }
+//   DELETE /api/v1/kv/{key}[?groupId=N]
+//   GET    /api/v1/kv?limit=&offset=[&groupId=N]           → { items, total }
+//   GET    /api/v1/groups                                  → { groups: [...] }
+import { badInput, external, notFound } from './errors.js';
+import { loadConfig, normalizeGroupId } from './config.js';
+
+const TIMEOUT_MS = 20000;
+
+async function call({ method, path, body, token, baseUrl, allowMissing = false }) {
+  const cfg = baseUrl ? { baseUrl, token } : await loadConfig();
+  const url = cfg.baseUrl.replace(/\/$/, '') + path;
+
+  const headers = {};
+  if (cfg.token) headers.authorization = `Bearer ${cfg.token}`;
+  if (body !== undefined) headers['content-type'] = 'application/json';
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: ctrl.signal,
+    });
+  } catch (e) {
+    if (e && e.name === 'AbortError') throw external(`请求超时（${TIMEOUT_MS}ms）: ${method} ${path}`);
+    throw external(`无法连接后端 ${cfg.baseUrl}: ${e.message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  let envelope;
+  try {
+    envelope = JSON.parse(await res.text());
+  } catch {
+    throw external(`后端返回了非 JSON（HTTP ${res.status}）: ${method} ${path}`);
+  }
+
+  const code = envelope.code ?? res.status;
+  if (code !== 0) {
+    // 401 单独识别成「未登录」——这是 agent 最需要一眼看懂的失败
+    if (code === 401) throw badInput('未登录或登录已过期（执行 nx-kv auth login <email>）');
+    // 业务上"这个 key 不存在"不是错误，由调用方决定怎么处理
+    if (allowMissing && (code === 404 || /not\s*found|不存在/i.test(envelope.message || ''))) {
+      return null;
+    }
+    throw external(`后端 code=${code}: ${envelope.message || '(无消息)'}`, { code, path });
+  }
+  return envelope.data ?? null;
+}
+
+const gid = (groupId) => {
+  const n = normalizeGroupId(groupId);
+  return n === undefined ? '' : `?groupId=${n}`;
+};
+
+// ---- 认证 ----
+
+export async function login(email, password, { baseUrl } = {}) {
+  if (!email || !password) throw badInput('邮箱与密码不能为空');
+  const data = await call({
+    method: 'POST',
+    path: '/api/v1/user/login',
+    body: { email, password },
+    baseUrl,
+    token: '', // 登录本身不需要 token（显式传空，避免用旧 token）
+  });
+  if (!data || !data.token) throw external('登录成功但未返回 token');
+  return { token: data.token, userId: Number(data.userId ?? data.user?.id ?? 0) };
+}
+
+export async function userInfo() {
+  return call({ method: 'GET', path: '/api/v1/user/info' });
+}
+
+// ---- 工作空间 ----
+
+function normalizeGroup(g) {
+  return {
+    id: Number(g.id) || 0,
+    name: g.name ?? '',
+    description: g.description ?? '',
+    myRole: g.myRole ?? '',
+    memberCount: Number(g.memberCount) || 0,
+    ownerId: Number(g.ownerId) || 0,
+    createdAt: g.createdAt ?? '',
+  };
+}
+
+export async function listGroups() {
+  const data = await call({ method: 'GET', path: '/api/v1/groups' });
+  return (data?.groups ?? []).map(normalizeGroup);
+}
+
+// 建组。返回后端给的完整对象——建完立刻能拿到 id，不必再列一次。
+export async function createGroup({ name, description } = {}) {
+  const n = String(name || '').trim();
+  if (!n) throw badInput('工作空间名称不能为空');
+  const data = await call({
+    method: 'POST',
+    path: '/api/v1/groups',
+    body: { name: n, description: String(description ?? '') },
+  });
+  return normalizeGroup(data?.group ?? {});
+}
+
+// 改名 / 改描述。只发传入的字段（PATCH 语义）。
+export async function updateGroup(id, { name, description } = {}) {
+  const body = {};
+  if (name !== undefined) {
+    const n = String(name).trim();
+    if (!n) throw badInput('工作空间名称不能为空');
+    body.name = n;
+  }
+  if (description !== undefined) body.description = String(description);
+  if (!Object.keys(body).length) throw badInput('至少要给出 --name 或 --description');
+  const data = await call({ method: 'PATCH', path: `/api/v1/groups/${Number(id)}`, body });
+  return normalizeGroup(data?.group ?? {});
+}
+
+// 解散工作空间。后端有前置条件：组内不能还有 KV，
+// 报错文案会把原因带回来（例如「组内存在 KV，请先删除或转移后再解散组」），
+// 这里原样透出——调用方需要知道到底卡在哪一步。
+export async function deleteGroup(id) {
+  await call({ method: 'DELETE', path: `/api/v1/groups/${Number(id)}` });
+  return { id: Number(id), deleted: true };
+}
+
+export async function listGroupMembers(id) {
+  const data = await call({ method: 'GET', path: `/api/v1/groups/${Number(id)}/members` });
+  return (data?.members ?? []).map((m) => ({
+    userId: Number(m.userId) || 0,
+    email: m.email ?? '',
+    nickname: m.nickname ?? '',
+    role: m.role ?? m.myRole ?? '',
+  }));
+}
+
+// ---- KV 读写 ----
+//
+// 注意：后端**没有「单条更新」接口**。任何写都是「读整把 key → 改数组 → 整把覆盖」，
+// 所以上层必须先读后写，且两把 key 要一起写（见 modules/todo/service.js 的契约注释）。
+
+// 读一个 key。key 不存在时返回 null（不是错误）。
+export async function kvGet(key, groupId) {
+  const data = await call({
+    method: 'GET',
+    path: '/api/v1/kv/' + encodeURIComponent(key) + gid(groupId),
+    allowMissing: true,
+  });
+  if (!data) return null;
+  return {
+    key: data.key ?? key,
+    value: data.value ?? '',
+    expiresAt: data.expires_at ?? data.expiresAt ?? null,
+    tags: Array.isArray(data.tags) ? data.tags.map(String) : [],
+  };
+}
+
+export async function kvSet({ key, value, ttl = 0, groupId }) {
+  const n = normalizeGroupId(groupId);
+  const body = { key, value, ttl };
+  if (n !== undefined) body.groupId = n;
+  await call({ method: 'POST', path: '/api/v1/kv', body });
+  return { key, bytes: Buffer.byteLength(String(value), 'utf8') };
+}
+
+export async function kvDelete(key, groupId) {
+  await call({ method: 'DELETE', path: '/api/v1/kv/' + encodeURIComponent(key) + gid(groupId) });
+  return { key, deleted: true };
+}
+
+export async function kvList({ limit = 50, offset = 0, groupId } = {}) {
+  const n = normalizeGroupId(groupId);
+  const q = `?limit=${limit}&offset=${offset}` + (n === undefined ? '' : `&groupId=${n}`);
+  const data = await call({ method: 'GET', path: '/api/v1/kv' + q });
+  return {
+    total: Number(data?.total) || 0,
+    items: (data?.items ?? []).map((it) => ({
+      key: it.key ?? '',
+      value: it.value ?? '',
+      expiresAt: it.expires_at ?? it.expiresAt ?? null,
+      tags: Array.isArray(it.tags) ? it.tags.map(String) : [],
+    })),
+  };
+}
+
+// 供 service 层判断「key 不存在」时抛的错（保持错误码语义）
+export { notFound };

package/src/core/open.js

@@ -0,0 +1,26 @@
+// 交给操作系统的两个动作：打开浏览器、在文件管理器里打开目录。
+// 零业务语义，且刻意不抛错——打不开就算了，调用方已经打印了地址。
+import { spawn } from 'node:child_process';
+
+function open(target) {
+  try {
+    const plat = process.platform;
+    if (plat === 'win32') {
+      spawn('cmd', ['/c', 'start', '', target], { detached: true, stdio: 'ignore' }).unref();
+    } else if (plat === 'darwin') {
+      spawn('open', [target], { detached: true, stdio: 'ignore' }).unref();
+    } else {
+      spawn('xdg-open', [target], { detached: true, stdio: 'ignore' }).unref();
+    }
+  } catch {
+    // 静默降级：调用方已经把 URL / 路径打印到终端
+  }
+}
+
+export function openBrowser(url) {
+  open(url);
+}
+
+export function openPath(dir) {
+  open(dir);
+}

package/src/core/paths.js

@@ -0,0 +1,46 @@
+// 路径与常量的唯一权威来源。
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { badInput } from './errors.js';
+
+export const APP_NAME = 'nx-kv';
+export const APP_DIR = join(homedir(), '.nx-kv');
+export const STORE_PATH = join(APP_DIR, 'store.json');
+export const DEFAULT_PORT = 7820;
+
+// 允许测试与多实例覆盖存储位置：NX_KV_STORE 环境变量优先
+export function storePathFromEnv() {
+  return process.env.NX_KV_STORE || STORE_PATH;
+}
+
+// 名称安全校验：拒绝路径穿越（保留中文等合法命名，与 fileops.go 语义一致）。
+//
+// 用于「这个字符串会被用作**目录名**」的场景：skill 名、内置包名、适配器 id。
+// 因此拒绝前导点——避免意外生成隐藏目录。
+// 注意：文件路径不要用这个，用下面的 assertSafeRelPath——像 .gitignore 这样的
+// 文件名是合法且常见的，用名称规则去卡它会把正常文件挡在门外。
+export function assertSafeName(name, label = 'skill 名称') {
+  if (!name || typeof name !== 'string' || /[\\/]/.test(name) || name.includes('..') || name.startsWith('.')) {
+    throw badInput('非法 ' + label + ': ' + name);
+  }
+  return name;
+}
+
+// 相对路径校验：一切来自外部的「某个目录内的文件路径」都要过这里。
+// 允许子目录（git 的 --file 常带路径）与前导点（.gitignore / .github/workflows/x.yml）。
+// 拒绝绝对路径与 .. 段——历史上 applySkillSide 做了这类校验而 gitResolve/gitDiff 没做，
+// 同一类输入校验强度不一致，本身就是可乘之口。
+//
+// 返回**归一化后**的路径（折叠重复分隔符、去掉 './' 段），调用方应使用返回值。
+export function assertSafeRelPath(input, { label = '文件路径', allowSubdir = true } = {}) {
+  if (!input || typeof input !== 'string') throw badInput(label + '不能为空');
+  if (/^([a-zA-Z]:|[\\/])/.test(input)) throw badInput(label + '必须是相对路径: ' + input);
+
+  const segments = input.split(/[\\/]+/).filter((x) => x !== '' && x !== '.');
+  if (!segments.length) throw badInput('非法 ' + label + ': ' + input);
+  if (segments.includes('..')) throw badInput(label + '不得包含 ..: ' + input);
+  if (!allowSubdir && segments.length > 1) {
+    throw badInput(label + '不能包含路径分隔符: ' + input);
+  }
+  return segments.join('/');
+}