kld-sdd 2.6.17 → 2.6.21

package/skywalk-sdd/index.cjs

@@ -1375,30 +1375,35 @@ function appendEventUnlocked(dataDir, changeName, event) {
   appendMarkdownLog(dataDir, changeName, event);
 }
 
-/** 追加一行 JSONL 到事件文件；同一 change 的事实写入和日志投影共享跨进程锁。 */
-function appendEvent(dataDir, changeName, event, options = {}) {
-  if (options.lockHeld) {
-    return appendEventUnlocked(dataDir, changeName, event);
-  }
-  return withEventWriteLock(dataDir, changeName, () => {
-    if (event?.type === 'stage_end') {
-      const existing = readAllEventEndsById(dataDir, event.event_id, changeName);
-      if (existing.length > 0) {
-        const latest = existing.sort((a, b) => timestampMs(b) - timestampMs(a))[0];
-        if (latest.result !== event.result) {
-          const error = new Error(
-            `E_STAGE_END_CONFLICT: event_id "${event.event_id}" 已记录 result=${latest.result}，不能改为 ${event.result}`,
-          );
-          error.code = 'E_STAGE_END_CONFLICT';
-          throw error;
-        }
-        return { idempotent: true, event: latest };
-      }
-    }
-    appendEventUnlocked(dataDir, changeName, event);
-    return { idempotent: false, event };
-  });
-}
+	/** 追加一行 JSONL 到事件文件；同一 change 的事实写入和日志投影共享跨进程锁。
+	 *  kld-T06：Progress Runtime 已删除，appendEvent 仅负责本地持久化，不再做事件富化、
+	 *  agent 拉起、metadata refresh 或 artifact snapshot。
+	 */
+	function appendEvent(dataDir, changeName, event, options = {}) {
+	  if (options.lockHeld) {
+	    appendEventUnlocked(dataDir, changeName, event);
+	    return { idempotent: false, event };
+	  }
+	  const result = withEventWriteLock(dataDir, changeName, () => {
+	    if (event?.type === 'stage_end') {
+	      const existing = readAllEventEndsById(dataDir, event.event_id, changeName);
+	      if (existing.length > 0) {
+	        const latest = existing.sort((a, b) => timestampMs(b) - timestampMs(a))[0];
+	        if (latest.result !== event.result) {
+	          const error = new Error(
+	            `E_STAGE_END_CONFLICT: event_id "${event.event_id}" 已记录 result=${latest.result}，不能改为 ${event.result}`,
+	          );
+	          error.code = 'E_STAGE_END_CONFLICT';
+	          throw error;
+	        }
+	        return { idempotent: true, event: latest };
+	      }
+	    }
+	    appendEventUnlocked(dataDir, changeName, event);
+	    return { idempotent: false, event };
+	  });
+	  return result;
+	}
 
 /** 把 ISO 时间戳格式化为本地时区 `YYYY-MM-DD HH:mm:ss (UTC±HH:MM)`。
  *  execution-log 面向人读，统一用本地时区 + 显式偏移标注，避免 UTC 裸值与用户体感差 8 小时（N9）。 */
@@ -5385,6 +5390,20 @@ function cmdStart(args) {
   appendEvent(dataDir, event.change, event);
   writeActiveStage(projectRoot, event);
 
+  // kld-T05: 七值命令成功写入 stage_start 后，异步上报使用事件。
+  // test/explore 与失败路径不上报；上报失败不影响本地事件与退出码。
+  const usagePromise = (() => {
+    try {
+      const { mapCommandToUsageSkill } = require('./lib/usage-contract.cjs');
+      const skill = mapCommandToUsageSkill(command);
+      if (!skill) return null;
+      const { reportUsageOnce } = require('./lib/usage-reporter.cjs');
+      return reportUsageOnce({ skill, startedAt: timestamp }).catch(() => null);
+    } catch {
+      return null;
+    }
+  })();
+
   // 输出 JSON，方便 AI Agent 解析 event_id
   const output = {
     event_id: eventId,
@@ -5392,6 +5411,9 @@ function cmdStart(args) {
     message: `SDD ${command} 阶段开始记录（change: ${event.change}）`,
   };
   console.log(JSON.stringify(output, null, 2));
+  // 返回 usage 上报 promise（可能为 null），便于测试或调用方 await；
+  // 现有 main() 不读返回值，行为兼容。
+  return usagePromise;
 }
 
 const ONTOLOGY_AUTHORING_STAGES = new Set(['propose', 'spec', 'design', 'task', 'check']);
@@ -5738,6 +5760,9 @@ function cmdEnd(args, options = {}) {
       ...event.details.archive_result,
       ...actualPaths,
     };
+    if (event.details.archive_result.archive_id && !event.archive_id) {
+      event.archive_id = event.details.archive_result.archive_id;
+    }
   }
 
   appendEvent(dataDir, event.change, event);
@@ -5745,6 +5770,37 @@ function cmdEnd(args, options = {}) {
     clearActiveStage(projectRoot, startEvent);
   }
 
+  // Archive stage_end is remapped to archive_linked on the wire. Also emit an explicit
+  // run_ended so monitors that only listen for terminal kinds still close the run.
+  if (command === 'archive' && (result === 'success' || result === 'partial' || result === 'failed' || result === 'failure')) {
+    try {
+      const terminalResult = result === 'failure' ? 'failed' : result;
+      appendEvent(dataDir, event.change, cleanOptionalFields({
+        schema_version: SCHEMA_VERSION,
+        event_id: generateEventId(),
+        type: 'stage_end',
+        event_kind: 'run_ended',
+        source: event.source,
+        command: 'archive',
+        stage: 'archive',
+        change: event.change,
+        agent_type: event.agent_type,
+        project_root: projectRoot,
+        session_id: event.session_id,
+        git_sha: event.git_sha,
+        timestamp: nowISO(),
+        result: terminalResult,
+        summary: event.summary || '变更归档完成，运行已结束',
+        details: {
+          terminal_of: event.event_id,
+          archive_id: event.details?.archive_result?.archive_id,
+        },
+      }));
+    } catch (err) {
+      try { console.error(`[telemetry] run_ended 补发失败（不阻塞）: ${err.message}`); } catch {}
+    }
+  }
+
   // 终态摘要必须基于已经落库的 archive stage_end。
   if (command === 'archive') {
     try { appendChangeSummary(projectRoot, change, readEvents(dataDir, change)); } catch (err) {
@@ -6246,6 +6302,64 @@ function normalizeStrictFinalOutputSnapshot(details) {
   };
 }
 
+/**
+ * Best-effort per-file byte sizes for apply delivery snapshots.
+ * Looks under projectRoot first, then its parent (split specs/code workspace).
+ * Never fails the record path — missing files simply omit size entries.
+ */
+function attachFinalOutputFileSizes(details, projectRoot) {
+  const snapshot = details?.final_output_snapshot;
+  if (!snapshot || !Array.isArray(snapshot.files) || snapshot.files.length === 0) {
+    return details;
+  }
+  const existing = (snapshot.file_sizes && typeof snapshot.file_sizes === 'object'
+    && !Array.isArray(snapshot.file_sizes))
+    ? { ...snapshot.file_sizes }
+    : {};
+  const roots = [];
+  const pushRoot = (candidate) => {
+    if (!candidate || typeof candidate !== 'string') return;
+    const resolved = path.resolve(candidate);
+    if (!roots.some((item) => item.toLowerCase?.() === resolved.toLowerCase() || item === resolved)) {
+      roots.push(resolved);
+    }
+  };
+  pushRoot(projectRoot);
+  if (projectRoot) pushRoot(path.dirname(projectRoot));
+
+  let changed = false;
+  for (const relative of snapshot.files) {
+    const rel = String(relative || '').trim().replace(/\\/g, '/');
+    if (!rel || Number.isInteger(existing[rel])) continue;
+    for (const root of roots) {
+      try {
+        const absolute = path.resolve(root, ...rel.split('/'));
+        const rootKey = process.platform === 'win32' ? root.toLowerCase() : root;
+        const absKey = process.platform === 'win32' ? absolute.toLowerCase() : absolute;
+        const prefix = rootKey.endsWith(path.sep) ? rootKey : `${rootKey}${path.sep}`;
+        if (absKey !== rootKey && !absKey.startsWith(prefix)) continue;
+        if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) continue;
+        const bytes = fs.statSync(absolute).size;
+        if (Number.isInteger(bytes) && bytes >= 0) {
+          existing[rel] = bytes;
+          changed = true;
+          break;
+        }
+      } catch {
+        // try next root
+      }
+    }
+  }
+  if (!changed && Object.keys(existing).length === 0) return details;
+  return {
+    ...details,
+    final_output_snapshot: {
+      ...snapshot,
+      file_sizes: existing,
+    },
+  };
+}
+
 function normalizeStrictTestResult(args, details) {
   const input = details?.test_results;
   if (!input || typeof input !== 'object' || Array.isArray(input)) {
@@ -7362,7 +7476,10 @@ function cmdRecord(args) {
     details = normalizeStrictCheckResult(details, args.result);
   } else if (strict && type === 'final_output_snapshot') {
     strictRunId = requireStrictString(strictRunId, 'EVENT_RUN_ID_REQUIRED', 'run_id');
-    details = normalizeStrictFinalOutputSnapshot(details);
+    details = attachFinalOutputFileSizes(
+      normalizeStrictFinalOutputSnapshot(details),
+      projectRoot,
+    );
   } else if (strict) {
     strictRunId = requireStrictString(strictRunId, 'EVENT_RUN_ID_REQUIRED', 'run_id');
   }

package/skywalk-sdd/lib/shared.cjs

@@ -347,12 +347,27 @@ function loadKbState(anchorDir = __dirname, env = process.env) {
   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 }}
+ * @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';
@@ -361,7 +376,136 @@ function resolveKbParams(stateConfig = {}, env = process.env) {
     ? stateConfig.targets[0].spaceId : '';
   const kbId = stateConfig.targets && stateConfig.targets.length > 0
     ? stateConfig.targets[0].kbId : '';
-  return { apiBase, token, spaceId, kbId, targets: stateConfig.targets || [] };
+  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 };
 }
 
 // ═══════════════════════════════════════════════════════════════
@@ -656,6 +800,10 @@ module.exports = {
   IDE_DIRS,
   loadKbState,
   resolveKbParams,
+  resolveKbScopes,
+  normalizeProjectName,
+  verifyProjectMembershipViaServer,
+  setKbProjectName,
   // HTTP
   requestJson,
   httpGetJson,

package/skywalk-sdd/lib/usage-contract.cjs

@@ -0,0 +1,276 @@
+// kld-T01 — CLI 使用统计上报契约
+// 集中定义：七值 skill 枚举、Device Flow 信封、ApiResponse 解包、
+// Node 14 兼容的 URL/HTTP 基础函数。与 kb-sdd 跨仓契约保持一致。
+'use strict';
+
+const http = require('node:http');
+const https = require('node:https');
+
+/**
+ * 七值使用统计 skill 枚举。
+ * test / explore 不属于统计范围，永不映射。
+ */
+const USAGE_SKILLS = Object.freeze([
+  'propose',
+  'spec',
+  'design',
+  'task',
+  'check',
+  'apply',
+  'archive',
+]);
+
+const USAGE_SKILL_SET = new Set(USAGE_SKILLS);
+
+/**
+ * 将 opsx 命令映射到使用统计 skill。
+ * @param {string} command
+ * @returns {string|null} 七值之一；非七值返回 null
+ */
+function mapCommandToUsageSkill(command) {
+  if (typeof command !== 'string' || !command) return null;
+  return USAGE_SKILL_SET.has(command) ? command : null;
+}
+
+/**
+ * 规范化 server URL：只接受 http/https，去尾斜杠，去首尾空白。
+ * @param {string} raw
+ * @returns {string|null} 规范化后的 base URL；非法返回 null
+ */
+function normalizeServerUrl(raw) {
+  if (typeof raw !== 'string') return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;
+  // 重组：protocol + // + host + pathname（去尾斜杠），忽略 search/hash
+  const path = parsed.pathname.replace(/\/+$/, '');
+  return `${parsed.protocol}//${parsed.host}${path}`;
+}
+
+/**
+ * 解开 ApiResponse 信封：{ code, message, data } → data；code 非 0 抛错。
+ * @param {object} body — 已 JSON.parse 的响应体
+ * @returns {*} data 字段内容
+ * @throws {Error} code 非 0、非对象、缺 code 字段
+ */
+function unwrapApiResponse(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    throw new Error('ApiResponse must be an object');
+  }
+  if (typeof body.code !== 'number') {
+    throw new Error('ApiResponse missing numeric code');
+  }
+  if (body.code !== 0) {
+    const msg = typeof body.message === 'string' && body.message
+      ? body.message
+      : `server error code ${body.code}`;
+    throw new Error(msg);
+  }
+  return body.data === undefined ? null : body.data;
+}
+
+/**
+ * 解析 Device Flow code 响应。
+ * kb-sdd 契约：{ deviceCode, userCode, verificationUri, verificationUriComplete?, expiresIn?, interval? }
+ * @param {object} body
+ * @returns {{deviceCode:string,userCode:string,verificationUri:string,verificationUriComplete:string|null,expiresIn:number,interval:number}|null}
+ */
+function parseDeviceCodeResponse(body) {
+  if (!body || typeof body !== 'object') return null;
+  if (typeof body.deviceCode !== 'string' || !body.deviceCode) return null;
+  if (typeof body.userCode !== 'string' || !body.userCode) return null;
+  if (typeof body.verificationUri !== 'string' || !body.verificationUri) return null;
+  const expiresIn = Number.isFinite(body.expiresIn) && body.expiresIn > 0
+    ? Math.floor(body.expiresIn)
+    : 600;
+  const interval = Number.isFinite(body.interval) && body.interval > 0
+    ? Math.floor(body.interval)
+    : 2;
+  return {
+    deviceCode: body.deviceCode,
+    userCode: body.userCode,
+    verificationUri: body.verificationUri,
+    verificationUriComplete: typeof body.verificationUriComplete === 'string' && body.verificationUriComplete
+      ? body.verificationUriComplete
+      : null,
+    expiresIn,
+    interval,
+  };
+}
+
+/**
+ * 分类 Device Flow poll 响应。
+ * kb-sdd 主契约：{ status: 'pending'|'authorized'|'expired'|'denied', token?, user? }
+ * 兼容 RFC 8628：{ error: 'authorization_pending'|'slow_down'|'expired_token'|'access_denied' }
+ *
+ * @param {number|null} statusCode — HTTP 状态码；网络错误为 null
+ * @param {object|null} body — 已解析 JSON；解析失败为 null
+ * @returns {{kind:'authorized',token:string,user:*}|{kind:'pending'}|{kind:'slow_down'}|{kind:'expired'}|{kind:'denied'}|{kind:'error',message?:string}}
+ */
+function classifyDevicePollResponse(statusCode, body) {
+  const payload = body && typeof body === 'object' ? body : {};
+  // kb-sdd 主契约：status 字段
+  if (typeof payload.status === 'string') {
+    const s = payload.status;
+    if (s === 'authorized') {
+      if (typeof payload.token === 'string' && payload.token) {
+        return { kind: 'authorized', token: payload.token, user: payload.user === undefined ? null : payload.user };
+      }
+      return { kind: 'error', message: 'authorized but missing token' };
+    }
+    if (s === 'pending') return { kind: 'pending' };
+    if (s === 'expired') return { kind: 'expired' };
+    if (s === 'denied') return { kind: 'denied' };
+    return { kind: 'error', message: `unknown status: ${s}` };
+  }
+  // RFC 8628 兼容：error 字段
+  if (typeof payload.error === 'string') {
+    const e = payload.error;
+    if (e === 'authorization_pending') return { kind: 'pending' };
+    if (e === 'slow_down') return { kind: 'slow_down' };
+    if (e === 'expired_token') return { kind: 'expired' };
+    if (e === 'access_denied') return { kind: 'denied' };
+    return { kind: 'error', message: e };
+  }
+  // 无识别字段：网络错误或 HTTP 异常
+  if (statusCode == null) return { kind: 'error', message: 'network error' };
+  if (statusCode >= 400) return { kind: 'error', message: `HTTP ${statusCode}` };
+  return { kind: 'error', message: 'unrecognized response' };
+}
+
+/**
+ * 分类 usage 上报响应。
+ * - confirmed: 2xx/204，服务端已确认，可从 pending 队列移除
+ * - unauthorized: 401，token 失效；调用方应原子删除本地 token 并提示一次
+ * - retry: 网络错误 / 429 / 5xx / timeout；保留在 pending 队列
+ * - drop: 其他 4xx；不再重试但不上抛
+ *
+ * @param {number|null} statusCode
+ * @returns {'confirmed'|'unauthorized'|'retry'|'drop'}
+ */
+function classifyUsageSubmitResponse(statusCode) {
+  if (statusCode == null || statusCode === 0) return 'retry';
+  if (statusCode >= 200 && statusCode < 300) return 'confirmed';
+  if (statusCode === 401) return 'unauthorized';
+  if (statusCode === 429) return 'retry';
+  if (statusCode >= 500) return 'retry';
+  return 'drop';
+}
+
+/**
+ * Node 14 兼容的 POST JSON 实现。
+ * - 仅用核心 http/https，不依赖全局 fetch
+ * - 任何网络/解析错误均不抛，返回 statusCode=null 让调用方分类
+ * - 4xx/5xx 不抛错，返回 statusCode + body 供分类
+ *
+ * @param {string} url — 完整 URL（必须 http/https）
+ * @param {object} payload — 请求体（JSON 序列化）
+ * @param {{token?:string,timeoutMs?:number,headers?:object}} [options]
+ * @returns {Promise<{statusCode:number|null,body:*,data:*,error:*}>}
+ *   statusCode: HTTP 状态码，网络错误为 null
+ *   body: 原始解析后的 JSON 对象（如可解析）
+ *   data: 若为 ApiResponse 信封且 code=0，则为解包后的 data；否则为 undefined
+ *   error: 仅在 statusCode=null 时携带 Error；否则为 null
+ */
+function postJson(url, payload, options = {}) {
+  return new Promise((resolve, reject) => {
+    let target;
+    try {
+      target = new URL(url);
+    } catch (err) {
+      reject(new Error(`invalid url: ${err.message}`));
+      return;
+    }
+    if (target.protocol !== 'http:' && target.protocol !== 'https:') {
+      reject(new Error(`only http/https supported, got ${target.protocol}`));
+      return;
+    }
+    const transport = target.protocol === 'https:' ? https : http;
+    const token = options && typeof options.token === 'string' && options.token ? options.token : null;
+    const timeoutMs = Number.isFinite(options && options.timeoutMs) && options.timeoutMs > 0
+      ? Math.floor(options.timeoutMs)
+      : 30000;
+
+    let body;
+    try {
+      body = JSON.stringify(payload === undefined ? {} : payload);
+    } catch (err) {
+      reject(new Error(`payload serialization error: ${err.message}`));
+      return;
+    }
+
+    const headers = Object.assign(
+      {
+        Accept: 'application/json',
+        'Content-Type': 'application/json; charset=utf-8',
+        'Content-Length': Buffer.byteLength(body),
+      },
+      options && options.headers && typeof options.headers === 'object' ? options.headers : {},
+    );
+    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) => {
+        const chunks = [];
+        response.on('data', (chunk) => chunks.push(chunk));
+        response.on('end', () => {
+          const raw = Buffer.concat(chunks).toString('utf8');
+          let parsedBody = null;
+          if (raw) {
+            try {
+              parsedBody = JSON.parse(raw);
+            } catch {
+              parsedBody = null;
+            }
+          }
+          let data;
+          if (parsedBody && typeof parsedBody === 'object' && parsedBody.code === 0) {
+            try {
+              data = unwrapApiResponse(parsedBody);
+            } catch {
+              data = undefined;
+            }
+          }
+          resolve({
+            statusCode: response.statusCode == null ? null : response.statusCode,
+            body: parsedBody,
+            data,
+            error: null,
+          });
+        });
+      },
+    );
+    request.on('timeout', () => {
+      request.destroy(new Error(`request timeout after ${timeoutMs}ms`));
+    });
+    request.on('error', (err) => {
+      resolve({ statusCode: null, body: null, data: undefined, error: err });
+    });
+    request.end(body);
+  });
+}
+
+module.exports = {
+  USAGE_SKILLS,
+  mapCommandToUsageSkill,
+  normalizeServerUrl,
+  unwrapApiResponse,
+  parseDeviceCodeResponse,
+  classifyDevicePollResponse,
+  classifyUsageSubmitResponse,
+  postJson,
+};