kld-sdd 2.6.16 → 2.6.21

package/skywalk-sdd/lib/shared.cjs

@@ -0,0 +1,811 @@
+'use strict';
+
+/**
+ * shared.cjs — skywalk-sdd 脚本共用工具模块
+ *
+ * 统一以下 7 类重复实现（原有 5+ 份不同实现散落在各脚本中）：
+ *   1. parseArgs       — CLI 参数解析（原 5 份不同实现）
+ *   2. readJson/Safe   — JSON 读取 + BOM 剥离（原 8 处，仅 1 处有 BOM 处理）
+ *   3. writeJsonAtomic — 原子写入 JSON（原 3 份实现）
+ *   4. ensureDir       — 目录创建（零散内联）
+ *   5. copyDirRecursive — 递归复制目录（原 2 份相同实现）
+ *   6. resolveSpecRootFast — spec root 解析（原 3 份重复逻辑）
+ *   7. loadKbState     — KB 配置加载（原 2 份，1 份缺 BOM 剥离）
+ *   8. httpRequest     — HTTP 请求（context-client.cjs 提取，替代 kb-upload.cjs 的 curl）
+ *
+ * 使用方式：
+ *   const { parseArgs, readJson, ... } = require('./lib/shared.cjs');
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+// ═══════════════════════════════════════════════════════════════
+// 1. CLI 参数解析
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * 统一 CLI 参数解析器。
+ *
+ * 支持三种格式：
+ *   --key=value     → args.key = 'value'
+ *   --key value     → args.key = 'value'（下一个 token 不以 -- 开头时）
+ *   --flag          → args.flag = true
+ *   --              → 忽略（分隔符）
+ *
+ * @param {string[]} argv — 通常传入 process.argv.slice(2)
+ * @returns {Record<string, string|boolean>}
+ */
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === '--') continue;
+    if (!token.startsWith('--')) continue;
+    const eq = token.indexOf('=');
+    if (eq !== -1) {
+      args[token.slice(2, eq)] = token.slice(eq + 1);
+    } else {
+      const key = token.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = true;
+      }
+    }
+  }
+  return args;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 2. JSON 读取（带 BOM 剥离）
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * 剥离 UTF-8 BOM（PowerShell Out-File -Encoding utf8 会写入 U+FEFF）。
+ * @param {string} raw
+ * @returns {string}
+ */
+function stripBom(raw) {
+  if (raw.charCodeAt(0) === 0xFEFF) return raw.slice(1);
+  return raw;
+}
+
+/**
+ * 读取并解析 JSON 文件，带 BOM 剥离。
+ * @param {string} filePath
+ * @returns {object}
+ * @throws {Error} 文件不存在或 JSON 解析失败时抛出
+ */
+function readJson(filePath) {
+  let raw = fs.readFileSync(filePath, 'utf8');
+  raw = stripBom(raw);
+  return JSON.parse(raw);
+}
+
+/**
+ * 安全读取 JSON 文件，带 BOM 剥离。解析失败返回 null。
+ * @param {string} filePath
+ * @returns {object|null}
+ */
+function readJsonSafe(filePath) {
+  try {
+    let raw = fs.readFileSync(filePath, 'utf8');
+    raw = stripBom(raw);
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 3. 原子写入
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * 原子写入文本文件（临时文件 → rename，含 fsync）。
+ * @param {string} filePath
+ * @param {string|Buffer} content
+ */
+function writeTextAtomic(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  const tempPath = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  let fd;
+  try {
+    fd = fs.openSync(tempPath, 'w');
+    fs.writeFileSync(fd, content, 'utf8');
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    fs.renameSync(tempPath, filePath);
+  } catch (error) {
+    if (fd != null) {
+      try { fs.closeSync(fd); } catch {}
+    }
+    try { fs.rmSync(tempPath, { force: true }); } catch {}
+    throw error;
+  }
+}
+
+/**
+ * 原子写入 JSON 文件（序列化 + 换行 + 原子写入）。
+ * @param {string} filePath
+ * @param {*} value — 可 JSON.stringify 的值
+ * @returns {Buffer} 写入的字节
+ */
+function writeJsonAtomic(filePath, value) {
+  const bytes = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  writeTextAtomic(filePath, bytes);
+  return bytes;
+}
+
+/**
+ * 仅在内容变化时写入（避免不必要的文件系统事件）。
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {boolean} 是否实际写入
+ */
+function writeIfChanged(filePath, content) {
+  if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === content) {
+    return false;
+  }
+  writeTextAtomic(filePath, content);
+  return true;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 4. 目录 / 文件操作
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * 确保目录存在（recursive）。
+ * @param {string} dirPath
+ */
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * 递归复制目录。
+ * @param {string} src
+ * @param {string} dest
+ */
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 5. 日期 / hash / 路径工具
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * 返回今天的 ISO 日期（YYYY-MM-DD）。
+ */
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+/**
+ * 返回当前时间的 ISO 8601 时间戳。
+ */
+function nowISO() {
+  return new Date().toISOString();
+}
+
+/**
+ * 计算字符串的 SHA-256 哈希。
+ */
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * 将路径中的反斜杠转为正斜杠（Windows 路径归一化）。
+ */
+function toPosix(value) {
+  return String(value || '').replace(/\\/g, '/');
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 6. Spec Root 解析
+// ═══════════════════════════════════════════════════════════════
+
+let _resolveSpecProjectRoot = null;
+
+/**
+ * 惰性加载 resolve-spec-root.cjs（避免循环依赖）。
+ */
+function getResolveSpecProjectRoot() {
+  if (!_resolveSpecProjectRoot) {
+    const mod = require(path.join(__dirname, '..', 'ontology', 'resolve-spec-root.cjs'));
+    _resolveSpecProjectRoot = mod.resolveSpecProjectRoot;
+  }
+  return _resolveSpecProjectRoot;
+}
+
+/**
+ * 快速解析 spec root 路径。
+ *
+ * 三级策略：
+ *   1. 如果 anchorDir 自身在 skywalk-sdd/ 内，父目录可能是 spec root → 验证后直接返回
+ *   2. 从 anchorDir 向上遍历查找 .sdd-spec-root → resolveSpecProjectRoot
+ *   3. 退回到 process.cwd() 解析
+ *
+ * @param {string} [anchorDir=__dirname] — 解析起点
+ * @returns {string} spec root 绝对路径
+ * @throws {Error} 找不到 spec root 时抛出
+ */
+function resolveSpecRootFast(anchorDir = __dirname) {
+  // 策略 1：脚本自身在 skywalk-sdd/ 内，父目录即 spec root
+  if (path.basename(anchorDir) === 'skywalk-sdd') {
+    const directParent = path.dirname(anchorDir);
+    if (fs.existsSync(path.join(directParent, 'openspec')) ||
+        fs.existsSync(path.join(directParent, 'modules.yaml')) ||
+        fs.existsSync(path.join(directParent, 'sdd.config.yaml'))) {
+      return directParent;
+    }
+  }
+
+  // 策略 2：从 anchorDir 向上查找
+  const resolveFn = getResolveSpecProjectRoot();
+  let root = resolveFn(anchorDir);
+
+  // 策略 3：退回到 CWD
+  if (root === anchorDir) {
+    root = resolveFn(process.cwd());
+  }
+
+  if (root === anchorDir || root === process.cwd()) {
+    throw new Error(
+      '未找到 spec 包目录。\n' +
+      '配置方式: 在项目根目录创建 .sdd-spec-root 文件，写入 spec 包相对或绝对路径\n' +
+      '或使用: kld-sdd link-spec --path=<spec-clone>'
+    );
+  }
+  return root;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 7. KB 配置加载
+// ═══════════════════════════════════════════════════════════════
+
+/** 已知的 IDE skills 目录名 */
+const IDE_DIRS = [
+  '.codebuddy', '.claude', '.cursor', '.vscode',
+  '.kunlunzhima', '.opencode', '.workbuddy', '.codex',
+];
+
+/**
+ * 加载 KB 配置（kb-state.json）。
+ *
+ * 从 anchorDir 逐层向上搜索（优先新路径，兼容旧路径）：
+ *   - <dir>/kb-state.json                              ← 新路径（spec 仓根目录）
+ *   - <dir>/<ide>/skills/kb-state.json                  ← 新路径（IDE skills 目录）
+ *   - <dir>/.shared/kb-state.json                       ← 旧路径（向后兼容）
+ *   - <dir>/<ide>/skills/.shared/kb-state.json          ← 旧路径（向后兼容）
+ *
+ * @param {string} [anchorDir=__dirname] — 搜索起点
+ * @param {object} [env=process.env] — 环境变量（用于 fallback）
+ * @returns {{ config: object|null, path: string|null, warnings: string[] }}
+ */
+function loadKbState(anchorDir = __dirname, env = process.env) {
+  const warnings = [];
+  const candidatePaths = [];
+
+  const MAX_LEVELS = 6;
+  let current = path.resolve(anchorDir);
+  const fileRoot = path.parse(current).root;
+  for (let level = 0; level < MAX_LEVELS; level++) {
+    // 新路径（优先）：直接放在目录下
+    candidatePaths.push(path.join(current, 'kb-state.json'));
+    // 新路径：IDE skills 目录下
+    for (const ide of IDE_DIRS) {
+      candidatePaths.push(path.join(current, ide, 'skills', 'kb-state.json'));
+    }
+    // 旧路径（向后兼容）：.shared/ 子目录
+    candidatePaths.push(path.join(current, '.shared', 'kb-state.json'));
+    for (const ide of IDE_DIRS) {
+      candidatePaths.push(path.join(current, ide, 'skills', '.shared', 'kb-state.json'));
+    }
+    if (current === fileRoot) break;
+    current = path.dirname(current);
+  }
+
+  for (const p of candidatePaths) {
+    try {
+      if (fs.existsSync(p)) {
+        let raw = fs.readFileSync(p, 'utf8');
+        raw = stripBom(raw);
+        const config = JSON.parse(raw);
+        return { config, path: p, warnings };
+      }
+    } catch (e) {
+      warnings.push(`kb-state.json 解析失败 (${p}): ${e.message}`);
+    }
+  }
+
+  return { config: null, path: null, warnings };
+}
+
+/** 监控项目绑定名长度上限：与 batch schema project_name maxLength 对齐。 */
+const PROJECT_NAME_MAX_LENGTH = 128;
+
+/**
+ * 归一化监控项目绑定名：非字符串或 trim 后为空 → null。
+ *
+ * @param {*} value
+ * @returns {string|null}
+ */
+function normalizeProjectName(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed === '' ? null : trimmed;
+}
+
+/**
+ * 从 KB 配置 + 环境变量解析 KB 连接参数。
+ *
+ * @param {object} stateConfig — loadKbState().config
+ * @param {object} [env=process.env]
+ * @returns {{ apiBase: string, token: string, spaceId: string, kbId: string, targets: array, projectName: string|null }}
+ */
+function resolveKbParams(stateConfig = {}, env = process.env) {
+  const apiBase = stateConfig.api || env.ENGINEERING_KB_API || 'http://localhost:8090/api';
+  const token = stateConfig.apiKey || env.ENGINEERING_KB_TOKEN || '';
+  const spaceId = stateConfig.targets && stateConfig.targets.length > 0
+    ? stateConfig.targets[0].spaceId : '';
+  const kbId = stateConfig.targets && stateConfig.targets.length > 0
+    ? stateConfig.targets[0].kbId : '';
+  const projectName = normalizeProjectName(stateConfig.projectName)
+    || normalizeProjectName(env.ENGINEERING_KB_PROJECT_NAME);
+  return { apiBase, token, spaceId, kbId, targets: stateConfig.targets || [], projectName };
+}
+
+/**
+ * Normalize API client scope list from kb-state or env.
+ * @param {object} stateConfig
+ * @param {object} [env=process.env]
+ * @returns {string[]}
+ */
+function resolveKbScopes(stateConfig = {}, env = process.env) {
+  const fromState = stateConfig.scopes
+    || stateConfig.apiKeyScopes
+    || stateConfig.api_client_scopes;
+  if (Array.isArray(fromState)) {
+    return fromState.map((scope) => String(scope).trim()).filter(Boolean);
+  }
+  if (typeof fromState === 'string' && fromState.trim()) {
+    return fromState.split(/[\s,]+/).map((scope) => scope.trim()).filter(Boolean);
+  }
+  const fromEnv = env.ENGINEERING_KB_SCOPES || env.ENGINEERING_KB_API_SCOPES;
+  if (typeof fromEnv === 'string' && fromEnv.trim()) {
+    return fromEnv.split(/[\s,]+/).map((scope) => scope.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+// kld-T06: progress:write 校验、progress binding 读取已随 Progress Runtime 一并删除。
+// Archive/Knowledge 的 api_client 能力由 resolveKbParams / httpGetJson / uploadFile 等保留。
+
+/**
+ * 通过服务端 dimensions 端点校验当前 API Key 用户是否为指定项目成员。
+ *
+ * 用于 kb-config 配置期的项目绑定预校验；服务端 A3 仍在上传时做权威裁决
+ * （非成员置空、不阻断），因此本函数对端点缺失/网络失败软返回而不抛错。
+ *
+ * @param {string} specRoot — spec 包根目录（含 kb-state.json）
+ * @param {string} projectName — 待校验的项目名称
+ * @param {object} [options]
+ * @param {object} [options.env=process.env]
+ * @param {number} [options.timeoutMs=15000]
+ * @returns {Promise<{ ok: boolean, reason?: string, member: boolean|null, matchedProject?: object }>}
+ * @throws {Error} E_PROGRESS_BINDING_INCOMPLETE — kb-state 缺失或缺 api/apiKey
+ */
+async function verifyProjectMembershipViaServer(specRoot, projectName, options = {}) {
+  const env = options.env || process.env;
+  const normalized = normalizeProjectName(projectName);
+  if (!normalized || normalized.length > PROJECT_NAME_MAX_LENGTH) {
+    return { ok: false, reason: 'invalid_input', member: null };
+  }
+
+  const root = path.resolve(specRoot);
+  const { config: kbState, path: statePath } = loadKbState(root, env);
+  if (!kbState || !statePath) {
+    const error = new Error('kb-state.json not found');
+    error.code = 'E_PROGRESS_BINDING_INCOMPLETE';
+    error.missingFields = ['kb-state.json'];
+    throw error;
+  }
+
+  const kbParams = resolveKbParams(kbState, env);
+  const missing = [];
+  if (!kbParams.apiBase) missing.push('api');
+  if (!kbParams.token) missing.push('apiKey');
+  if (missing.length > 0) {
+    const error = new Error(`Progress binding incomplete: missing ${missing.join(', ')}`);
+    error.code = 'E_PROGRESS_BINDING_INCOMPLETE';
+    error.missingFields = missing;
+    throw error;
+  }
+
+  const apiBase = String(kbParams.apiBase).replace(/\/+$/, '');
+  const url = `${apiBase}/v1/sdd-runs/dimensions`;
+  let response;
+  try {
+    response = await httpGetJson(url, kbParams.token, options.timeoutMs || 15000);
+  } catch (error) {
+    // 鉴权失败（密钥失效/吊销）与端点缺失/网络异常分开归因，避免配置流程误导。
+    const statusMatch = error && /^HTTP (\d{3})\b/.exec(String(error.message || ''));
+    if (statusMatch && (statusMatch[1] === '401' || statusMatch[1] === '403')) {
+      return { ok: false, reason: 'auth_failed', member: null };
+    }
+    return { ok: false, reason: 'endpoint_unavailable', member: null };
+  }
+
+  const data = response && typeof response === 'object' && response.data != null
+    ? response.data
+    : response;
+  const projects = Array.isArray(data?.projects) ? data.projects : [];
+  const matched = projects.find((p) => {
+    const name = normalizeProjectName(p && (p.name || p.projectName));
+    return name === normalized;
+  });
+  return {
+    ok: true,
+    member: Boolean(matched),
+    matchedProject: matched
+      ? { id: matched.projectId || matched.id || null, name: normalized }
+      : undefined,
+  };
+}
+
+/**
+ * 原子写入/清除 kb-state.json 的 projectName（监控项目绑定），保留其余键。
+ *
+ * @param {string} specRoot — spec 包根目录
+ * @param {string|null} projectName — 项目名；null/空白 = 清除绑定
+ * @returns {{ ok: true, path: string, projectName: string|null }}
+ * @throws {Error} E_PROGRESS_BINDING_INCOMPLETE — kb-state.json 不存在
+ */
+function setKbProjectName(specRoot, projectName, options = {}) {
+  const env = options.env || process.env;
+  const root = path.resolve(specRoot);
+  const { config: kbState, path: statePath } = loadKbState(root, env);
+  if (!kbState || !statePath) {
+    const error = new Error('kb-state.json not found');
+    error.code = 'E_PROGRESS_BINDING_INCOMPLETE';
+    error.missingFields = ['kb-state.json'];
+    throw error;
+  }
+  const normalized = normalizeProjectName(projectName);
+  if (normalized && normalized.length > PROJECT_NAME_MAX_LENGTH) {
+    const error = new Error(`projectName 超长（>${PROJECT_NAME_MAX_LENGTH} 字符）`);
+    error.code = 'E_PROJECT_NAME_INVALID';
+    throw error;
+  }
+  const next = { ...kbState, projectName: normalized };
+  writeJsonAtomic(statePath, next);
+  return { ok: true, path: statePath, projectName: next.projectName };
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 7.5. PowerShell CLIXML 剥离
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * 检测并剥离 PowerShell CLIXML 包装。
+ *
+ * PowerShell 在捕获子进程 stdout 时，可能将其包装为 CLIXML 格式：
+ *   <Objs ...><S S="...">line1</S><S S="...">line2</S>...</Objs>
+ * 这会导致 JSON.parse 失败。本函数检测并剥离该包装，还原纯文本。
+ *
+ * @param {string} output - 原始输出字符串
+ * @returns {string} 剥离 CLIXML 后的纯文本（非 CLIXML 则原样返回）
+ */
+function stripCliXml(output) {
+  if (!output || typeof output !== 'string') return output;
+  const trimmed = output.trim();
+  if (!trimmed.startsWith('<Objs ') || !trimmed.endsWith('</Objs>')) {
+    return output;
+  }
+  // CLIXML 格式：提取 <S>...</S> 标签内的文本
+  const lines = [];
+  const regex = /<S[^>]*>([\s\S]*?)<\/S>/g;
+  let match;
+  while ((match = regex.exec(trimmed)) !== null) {
+    lines.push(match[1]
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&amp;/g, '&')
+      .replace(/&quot;/g, '"')
+      .replace(/&apos;/g, "'"));
+  }
+  return lines.length > 0 ? lines.join('\n') : output;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// 8. HTTP 请求
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * 发送 JSON POST 请求并返回解析后的响应。
+ *
+ * @param {string} url — 完整 URL
+ * @param {object} payload — 请求体（会被 JSON.stringify）
+ * @param {string} [token] — Bearer token
+ * @param {number} [timeoutMs=30000] — 超时
+ * @returns {Promise<object>} — 解析后的响应 data 字段
+ */
+function requestJson(url, payload, token, timeoutMs = 30000) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(url);
+    const transport = target.protocol === 'https:' ? https : http;
+
+    let body;
+    try {
+      body = JSON.stringify(payload);
+      JSON.parse(body); // 二次验证
+    } catch (jsonErr) {
+      reject(new Error(`payload serialization error: ${jsonErr.message}`));
+      return;
+    }
+
+    const headers = {
+      Accept: 'application/json',
+      'Content-Type': 'application/json; charset=utf-8',
+    };
+    if (token) headers.Authorization = `Bearer ${token}`;
+
+    const request = transport.request(
+      {
+        hostname: target.hostname,
+        port: target.port || (target.protocol === 'https:' ? 443 : 80),
+        path: target.pathname + target.search,
+        method: 'POST',
+        headers,
+        timeout: timeoutMs,
+      },
+      (response) => {
+        let responseBody = '';
+        response.on('data', (chunk) => { responseBody += chunk; });
+        response.on('end', () => {
+          let parsed;
+          try {
+            parsed = responseBody ? JSON.parse(responseBody) : null;
+          } catch {
+            reject(new Error(`knowledge base returned invalid JSON (HTTP ${response.statusCode})`));
+            return;
+          }
+          if (response.statusCode >= 400) {
+            const statusLabel = response.statusCode === 400 ? 'Bad Request'
+              : response.statusCode === 401 ? 'Unauthorized'
+              : response.statusCode === 403 ? 'Forbidden'
+              : response.statusCode === 404 ? 'Not Found'
+              : `HTTP ${response.statusCode}`;
+            const serverMsg = parsed?.message || parsed?.error || '';
+            reject(new Error(serverMsg
+              ? `knowledge base ${statusLabel}: ${serverMsg}`
+              : `knowledge base ${statusLabel}`));
+            return;
+          }
+          if (parsed?.code != null && parsed.code !== 0) {
+            reject(new Error(parsed?.message || `knowledge base error code ${parsed.code}`));
+            return;
+          }
+          resolve(parsed.data);
+        });
+      },
+    );
+    request.on('timeout', () => request.destroy(new Error(`knowledge base timeout after ${timeoutMs}ms`)));
+    request.on('error', reject);
+    request.end(body);
+  });
+}
+
+/**
+ * 发送 GET 请求并返回解析后的完整响应 JSON（含 code/data 字段）。
+ *
+ * 用于 KB pre-check 等只读接口。返回完整的 API 响应体
+ * （如 `{code: 0, message: "ok", data: {...}}`），调用方通过 `.data` 访问业务数据。
+ * HTTP 4xx/5xx 会 reject。
+ *
+ * @param {string} url — 完整 URL（含 query string）
+ * @param {string} [token] — Bearer token
+ * @param {number} [timeoutMs=15000] — 超时
+ * @returns {Promise<object|null>} — 完整 API 响应 JSON（含 code/data）；非 JSON 或错误时 reject
+ */
+function httpGetJson(url, token, timeoutMs = 15000) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(url);
+    const transport = target.protocol === 'https:' ? https : http;
+
+    const headers = {
+      Accept: 'application/json',
+    };
+    if (token) headers.Authorization = `Bearer ${token}`;
+
+    const request = transport.request(
+      {
+        hostname: target.hostname,
+        port: target.port || (target.protocol === 'https:' ? 443 : 80),
+        path: target.pathname + target.search,
+        method: 'GET',
+        headers,
+        timeout: timeoutMs,
+      },
+      (response) => {
+        let responseBody = '';
+        response.on('data', (chunk) => { responseBody += chunk; });
+        response.on('end', () => {
+          let parsed;
+          try {
+            parsed = responseBody ? JSON.parse(responseBody) : null;
+          } catch {
+            if (response.statusCode >= 400) {
+              reject(new Error(`HTTP ${response.statusCode} - ${responseBody.slice(0, 200)}`));
+              return;
+            }
+            reject(new Error(`invalid JSON response: ${responseBody.slice(0, 200)}`));
+            return;
+          }
+          if (response.statusCode >= 400) {
+            const serverMsg = parsed?.message || parsed?.error || responseBody.slice(0, 200);
+            reject(new Error(`HTTP ${response.statusCode}: ${serverMsg}`));
+            return;
+          }
+          resolve(parsed);
+        });
+      },
+    );
+    request.on('timeout', () => request.destroy(new Error(`timeout after ${timeoutMs}ms`)));
+    request.on('error', reject);
+    request.end();
+  });
+}
+
+/**
+ * 上传文件到 KB（multipart/form-data，替代 curl）。
+ *
+ * @param {string} url — 完整的上传 URL
+ * @param {string} filePath — 本地文件路径
+ * @param {string} token — Bearer token
+ * @param {object} [extraFields={}] — 额外的 form 字段
+ * @param {number} [timeoutMs=60000] — 超时
+ * @returns {Promise<object>} — 解析后的响应
+ */
+function uploadFile(url, filePath, token, extraFields = {}, timeoutMs = 60000) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(url);
+    const transport = target.protocol === 'https:' ? https : http;
+
+    const boundary = '----SDDBoundary' + crypto.randomBytes(8).toString('hex');
+    const fileName = path.basename(filePath);
+    const fileContent = fs.readFileSync(filePath);
+    const fileStat = fs.statSync(filePath);
+
+    // 构建 multipart body
+    const parts = [];
+
+    // 额外字段
+    for (const [key, value] of Object.entries(extraFields)) {
+      parts.push(Buffer.from(
+        `--${boundary}\r\n` +
+        `Content-Disposition: form-data; name="${key}"\r\n\r\n` +
+        `${value}\r\n`
+      ));
+    }
+
+    // 文件字段
+    parts.push(Buffer.from(
+      `--${boundary}\r\n` +
+      `Content-Disposition: form-data; name="package"; filename="${fileName}"\r\n` +
+      `Content-Type: application/zip\r\n\r\n`
+    ));
+    parts.push(fileContent);
+    parts.push(Buffer.from(`\r\n--${boundary}--\r\n`));
+
+    const body = Buffer.concat(parts);
+
+    const headers = {
+      'Content-Type': `multipart/form-data; boundary=${boundary}`,
+      'Content-Length': body.length,
+    };
+    if (token) headers.Authorization = `Bearer ${token}`;
+
+    const request = transport.request(
+      {
+        hostname: target.hostname,
+        port: target.port || (target.protocol === 'https:' ? 443 : 80),
+        path: target.pathname + target.search,
+        method: 'POST',
+        headers,
+        timeout: timeoutMs,
+      },
+      (response) => {
+        let responseBody = '';
+        response.on('data', (chunk) => { responseBody += chunk; });
+        response.on('end', () => {
+          let parsed;
+          try {
+            parsed = responseBody ? JSON.parse(responseBody) : null;
+          } catch {
+            if (response.statusCode >= 400) {
+              reject(new Error(`upload failed: HTTP ${response.statusCode} - ${responseBody.slice(0, 200)}`));
+              return;
+            }
+            reject(new Error(`upload returned invalid JSON: ${responseBody.slice(0, 200)}`));
+            return;
+          }
+          if (response.statusCode >= 400) {
+            const serverMsg = parsed?.message || parsed?.error || responseBody.slice(0, 200);
+            reject(new Error(`upload failed (HTTP ${response.statusCode}): ${serverMsg}`));
+            return;
+          }
+          resolve(parsed);
+        });
+      },
+    );
+    request.on('timeout', () => request.destroy(new Error(`upload timeout after ${timeoutMs}ms`)));
+    request.on('error', reject);
+    request.end(body);
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Module Exports
+// ═══════════════════════════════════════════════════════════════
+
+module.exports = {
+  // CLI
+  parseArgs,
+  // JSON I/O
+  stripBom,
+  stripCliXml,
+  readJson,
+  readJsonSafe,
+  writeTextAtomic,
+  writeJsonAtomic,
+  writeIfChanged,
+  // Filesystem
+  ensureDir,
+  copyDirRecursive,
+  // Utilities
+  today,
+  nowISO,
+  sha256,
+  toPosix,
+  // Spec root
+  resolveSpecRootFast,
+  // KB state
+  IDE_DIRS,
+  loadKbState,
+  resolveKbParams,
+  resolveKbScopes,
+  normalizeProjectName,
+  verifyProjectMembershipViaServer,
+  setKbProjectName,
+  // HTTP
+  requestJson,
+  httpGetJson,
+  uploadFile,
+};