kld-sdd 2.6.21 → 2.7.8

package/skywalk-sdd/kb-upload.cjs

@@ -33,19 +33,48 @@ const {
   httpGetJson,
 } = require('./lib/shared.cjs');
 
+function resolveUploadTarget(state, options = {}) {
+  if (Boolean(options.spaceId) !== Boolean(options.kbId)) throw new Error('必须同时指定 --space-id 和 --kb-id');
+  const targets = state.targets || [];
+  if (options.spaceId && options.kbId) {
+    return targets.find(t => t.spaceId === options.spaceId && t.kbId === options.kbId) || options;
+  }
+  if (targets.length !== 1) throw new Error('请明确上传目标：配置一个知识库，或同时指定 --space-id 和 --kb-id；不会自动分发到多个 KB');
+  if (!targets[0].spaceId || !targets[0].kbId) throw new Error('知识库目标缺少 spaceId/kbId');
+  return targets[0];
+}
+
+function cacheKey(changeName, context) {
+  if (!context?.api || !context?.spaceId || !context?.kbId) return null;
+  return JSON.stringify([context.api.replace(/\/+$/, ''), context.spaceId, context.kbId, changeName]);
+}
+
+function assertIngestionResult(result) {
+  if (result?.code != null && result.code !== 0) throw new Error(result.message || 'KB API 拒绝入库');
+  const job = result?.data || result;
+  if (!job || !['projecting', 'succeeded'].includes(job.status) || job.relationStatus !== 'committed') {
+    throw new Error(`INGEST_NOT_COMMITTED: ${job?.errorCode || job?.status || 'unknown'} ${job?.errorMessage || ''} job=${job?.jobId || 'unknown'}`);
+  }
+  if (Number(job.report?.version_conflicts || 0) > 0 || job.report?.publication_status === 'needs_review') {
+    throw new Error(`VERSION_CONFLICT: 事实包已保存为候选，当前事实未更新；请合并基线后重新发布。job=${job.jobId}`);
+  }
+  return job;
+}
+
 /**
  * 读取 kb-state.json 中指定 change 的 archive 缓存。
  * @param {string} specRoot
  * @param {string} changeName
  * @returns {object|null} { archive_id, content_hash, uploaded_at }
  */
-function readArchiveCache(specRoot, changeName) {
+function readArchiveCache(specRoot, changeName, context) {
   const directPath = path.join(specRoot, 'kb-state.json');
   const legacyPath = path.join(specRoot, '..', '.shared', 'kb-state.json');
   const statePath = fs.existsSync(directPath) ? directPath : legacyPath;
   const state = readJsonSafe(statePath);
   if (!state || !state.archiveCache) return null;
-  return state.archiveCache[changeName] || null;
+  const key = cacheKey(changeName, context);
+  return key ? state.archiveCache[key] || null : null;
 }
 
 /**
@@ -55,16 +84,19 @@ function readArchiveCache(specRoot, changeName) {
  * @param {string} archiveId
  * @param {string} contentHash
  */
-function updateKbStateCache(specRoot, changeName, archiveId, contentHash) {
+function updateKbStateCache(specRoot, changeName, archiveId, contentHash, context) {
   const directPath = path.join(specRoot, 'kb-state.json');
   const legacyPath = path.join(specRoot, '..', '.shared', 'kb-state.json');
   const statePath = fs.existsSync(directPath) ? directPath : legacyPath;
   const state = readJsonSafe(statePath) || {};
   if (!state.archiveCache) state.archiveCache = {};
-  state.archiveCache[changeName] = {
+  const key = cacheKey(changeName, context);
+  if (!key) throw new Error('缓存必须包含 API、Space 和 KB');
+  state.archiveCache[key] = {
     archive_id: archiveId,
     content_hash: contentHash,
     uploaded_at: new Date().toISOString(),
+    target: context,
   };
   writeJsonAtomic(statePath, state);
   console.log(`✓ 已更新本地缓存: ${changeName} → ${archiveId.slice(0, 24)}...`);
@@ -144,7 +176,11 @@ function readKbState(specRoot) {
  */
 function validateRequiredFiles(folderPath, minimumLevel) {
   const required = MINIMUM_LEVELS[minimumLevel] || MINIMUM_LEVELS[DEFAULT_LEVEL];
-  const missing = required.filter(f => !fs.existsSync(path.join(folderPath, f)));
+  const specsDir = path.join(folderPath, 'specs');
+  const capabilityDirs = fs.existsSync(specsDir) ? fs.readdirSync(specsDir, { withFileTypes: true })
+    .filter(e => e.isDirectory()).map(e => path.join(specsDir, e.name)) : [];
+  const missing = required.filter(f => !fs.existsSync(path.join(folderPath, f))
+    && !(f !== 'proposal.md' && capabilityDirs.length > 0 && capabilityDirs.every(d => fs.existsSync(path.join(d, f)))));
   if (missing.length > 0) {
     throw new Error(
       `[${minimumLevel}] 缺少必需文件: ${missing.join(', ')}\n` +
@@ -162,11 +198,11 @@ function validateRequiredFiles(folderPath, minimumLevel) {
 /**
  * 本地预检 project_id === spaceKey
  */
-function preCheckProjectId(projectId, state) {
+function preCheckProjectId(projectId, state, selectedTarget) {
   if (!state.targets || !state.targets[0]) {
     throw new Error('KB 配置中无 targets，请运行 /opsx-kb-config 配置知识库。');
   }
-  const spaceKey = state.targets[0].spaceKey;
+  const spaceKey = (selectedTarget || resolveUploadTarget(state)).spaceKey;
   if (!spaceKey) {
     console.warn('⚠️  kb-state.json targets[0].spaceKey 为空，跳过本地预检');
     return;
@@ -255,15 +291,9 @@ function buildPackageFromFolder(specRoot, changeName, options) {
  * 上传 zip 到 KB（使用 Node.js HTTP，替代 curl）
  */
 async function uploadZip(zipPath, state, options) {
-  const target = options.spaceId && options.kbId
-    ? { spaceId: options.spaceId, kbId: options.kbId }
-    : state.targets[0];
+  const target = resolveUploadTarget(state, options);
 
-  if (!target || !target.spaceId || !target.kbId) {
-    throw new Error('未指定目标 Space/KB，请运行 /opsx-kb-config 配置知识库。');
-  }
-
-  const apiUrl = state.api || 'http://localhost:8090/api';
+  const apiUrl = (state.api || 'http://localhost:8090/api').replace(/\/+$/, '');
   const uploadUrl = `${apiUrl}/v1/spaces/${target.spaceId}/knowledge-bases/${target.kbId}/ingestions`;
 
   console.log(`→ 上传到 KB: ${target.spaceName || target.spaceId}/${target.kbName || target.kbId}`);
@@ -272,6 +302,7 @@ async function uploadZip(zipPath, state, options) {
 
   try {
     const result = await uploadFile(uploadUrl, zipPath, state.apiKey);
+    assertIngestionResult(result);
     return result;
   } catch (err) {
     throw new Error(`上传失败: ${err.message}`);
@@ -339,6 +370,11 @@ async function main() {
       changeName = path.basename(folderPath);
     }
 
+    const expectedFolder = path.resolve(specRoot, 'openspec', 'changes', changeName);
+    if (path.resolve(folderPath) !== expectedFolder || !expectedFolder.startsWith(path.resolve(specRoot, 'openspec', 'changes') + path.sep)) {
+      throw new Error('文件夹上传仅接受当前 Spec 仓 openspec/changes/<change>；已归档内容请用 --zip 指定归档包');
+    }
+
     if (!fs.existsSync(folderPath)) {
       throw new Error(`变更目录不存在: ${folderPath}`);
     }
@@ -362,7 +398,9 @@ async function main() {
     if (!state.apiKey) {
       throw new Error('KB 配置中无 apiKey，请运行 /opsx-kb-config 配置知识库。');
     }
-    preCheckProjectId(projectId, state);
+    const target = resolveUploadTarget(state, { spaceId: args['space-id'], kbId: args['kb-id'] });
+    preCheckProjectId(projectId, state, target);
+    const cacheContext = { api: state.api || 'http://localhost:8090/api', spaceId: target.spaceId, kbId: target.kbId };
 
     // 4. 仅校验模式（含语义校验）
     if (args['validate-only']) {
@@ -390,26 +428,8 @@ async function main() {
     });
 
     try {
-      // === Step 5.1: 本地缓存快速检查 ===
-      const cache = readArchiveCache(specRoot, changeName);
-      if (cache && cache.archive_id === manifest.archive_id) {
-        console.log('\n✓ 内容无变更（archive_id 与上次成功上传一致），跳过上传');
-        console.log(`  cached archive_id: ${cache.archive_id}`);
-        console.log(`  uploaded_at: ${cache.uploaded_at}`);
-        console.log('\n✓ 完成（本地缓存命中）');
-        return;
-      }
-
-      // 解析上传目标
-      const target = (args['space-id'] && args['kb-id'])
-        ? { spaceId: args['space-id'], kbId: args['kb-id'] }
-        : state.targets[0];
-
-      if (!target || !target.spaceId || !target.kbId) {
-        throw new Error('未指定目标 Space/KB，请运行 /opsx-kb-config 配置知识库。');
-      }
-
-      const apiUrl = state.api || 'http://localhost:8090/api';
+      // Local receipts are informational only. Always verify the selected destination remotely.
+      const apiUrl = (state.api || 'http://localhost:8090/api').replace(/\/+$/, '');
 
       // === Step 5.5: KB 预检（网络级幂等确认）===
       const archiveId = manifest.archive_id;
@@ -424,11 +444,13 @@ async function main() {
       try {
         const checkResult = await httpGetJson(checkUrl, state.apiKey);
 
-        if (checkResult && checkResult.data && checkResult.data.idempotent) {
+        if (checkResult?.data?.idempotent && checkResult.data.publicationStatus === 'published') {
           console.log('\n✓ KB 中已存在相同 archive（幂等命中），跳过上传');
           console.log(`  snapshot_id: ${checkResult.data.snapshotId}`);
-          updateKbStateCache(specRoot, changeName, archiveId, contentHash);
-          console.log('\n✓ 完成（KB 预检命中）');
+          updateKbStateCache(specRoot, changeName, archiveId, contentHash, cacheContext);
+          console.log(`  publication: ${checkResult.data.publicationStatus}; projection: ${checkResult.data.projectionStatus}`);
+          if (['failed', 'degraded'].includes(checkResult.data.projectionStatus)) console.log('⚠️ 检索准备尚未完成，请在知识库概览重试该任务的投影');
+          console.log('\n✓ 归档已存在（检索状态以上述回执为准）');
           return;
         }
 
@@ -467,8 +489,8 @@ async function main() {
       console.log(`  change_id:  ${manifest.change_id}`);
       console.log(`  files:      ${manifest.files.length}`);
 
-      // === 上传成功后更新本地缓存 ===
-      updateKbStateCache(specRoot, changeName, archiveId, contentHash);
+      // Canonical commit has been verified; a receipt does not imply projection completion.
+      updateKbStateCache(specRoot, changeName, archiveId, contentHash, cacheContext);
 
       // === 投影状态提示 ===
       // 上传成功后，KB 后端异步执行 vector embedding + AGE graph 投影。
@@ -479,9 +501,9 @@ async function main() {
       if (projStatus === 'complete') {
         console.log('\n✓ 投影已完成，向量/图检索可用');
       } else if (projStatus === 'degraded') {
-        console.log('\n⚠️  投影完成但有降级（部分通道不可用，FTS 仍可用）');
+        console.log('\n⚠️  投影完成但有降级（部分通道不可用，召回结果会标记降级）');
       } else if (projStatus === 'disabled') {
-        console.log('\nℹ️  投影已禁用（FTS-only 模式）');
+        console.log('\nℹ️  投影已禁用（仅可使用当前已就绪的检索通道）');
       } else if (projStatus && projStatus !== 'complete') {
         console.log(`\nℹ️  投影进行中 (${projStatus})，向量/图检索暂不可用`);
         console.log('  → 正常 SDD 流程中阶段间间隔通常足够投影完成');
@@ -502,4 +524,5 @@ async function main() {
   }
 }
 
-main();
+if (require.main === module) main();
+module.exports = { resolveUploadTarget, readArchiveCache, updateKbStateCache, assertIngestionResult, uploadZip, buildPackageFromFolder, validateRequiredFiles };

package/skywalk-sdd/lib/git-identity.cjs

@@ -0,0 +1,270 @@
+// kld-T07 — git 身份持久缓存与后台刷新（慢 git 环境韧性）
+// 职责：~/.kld-sdd/git-identity.json 持久缓存读写（tmp+rename 原子）；
+//   TTL 判定（身份 7 天 / tombstone 1 天）；
+//   detached+unref 后台刷新（git config --get-regexp 单次调用，宽限 60s）；
+//   in-progress 锁（mtime TTL 120s）防并发多 spawn；
+//   仅 git 成功但字段缺失才写 tombstone；失败/超时不写，允许下次重试。
+// 设计背景：企业终端 git 进程启动 7~34s，前台 execFileSync 必然超时；
+//   稳态（缓存命中）零 git 调用、零额外延迟。
+// 依赖注入（spawn/execFileSync/now/env/homeDir）便于单测；Node 14 兼容。
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const childProcess = require('node:child_process');
+
+const IDENTITY_FILE_NAME = 'git-identity.json';
+const REFRESH_LOCK_NAME = 'git-identity.refresh.lock';
+const IDENTITY_TTL_MS = 7 * 24 * 3600 * 1000; // 身份缓存 7 天
+const TOMBSTONE_TTL_MS = 24 * 3600 * 1000; // tombstone 1 天
+const REFRESH_LOCK_TTL_MS = 120 * 1000; // in-progress 锁 120s
+const REFRESH_GIT_TIMEOUT_MS = 60 * 1000; // 后台 git 宽限 60s（适配 7-34s 慢机器）
+
+/** 解析 home：显式 homeDir > env KLD_SDD_HOME > os.homedir（与 pendingPathFor 同注入模式） */
+function resolveHome(homeDir, env) {
+  const e = env || process.env;
+  return homeDir || (e && e.KLD_SDD_HOME) || os.homedir();
+}
+
+function identityPathFor(homeDir, env) {
+  return path.join(resolveHome(homeDir, env), '.kld-sdd', IDENTITY_FILE_NAME);
+}
+
+function refreshLockPathFor(homeDir, env) {
+  return path.join(resolveHome(homeDir, env), '.kld-sdd', REFRESH_LOCK_NAME);
+}
+
+function nowMs(options) {
+  return options && typeof options.now === 'function' ? options.now() : Date.now();
+}
+
+/** 原子写 JSON（tmp+rename），与 writePendingAtomic 同款 */
+function writeJsonAtomic(filePath, obj) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`,
+  );
+  fs.writeFileSync(tmp, `${JSON.stringify(obj)}\n`, 'utf8');
+  try {
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+/**
+ * 写入身份缓存（readAt 可经 options.now 注入，测试 TTL 用）。
+ * @param {{userName:string,email:string}} identity
+ */
+function writeIdentityCache(identity, options = {}) {
+  writeJsonAtomic(identityPathFor(options.homeDir, options.env), {
+    userName: identity.userName,
+    email: identity.email,
+    readAt: new Date(nowMs(options)).toISOString(),
+  });
+}
+
+/** 写入 tombstone（确认无身份；TTL 1 天，防止每命令反复 spawn git） */
+function writeTombstone(options = {}) {
+  writeJsonAtomic(identityPathFor(options.homeDir, options.env), {
+    unavailable: true,
+    readAt: new Date(nowMs(options)).toISOString(),
+  });
+}
+
+/**
+ * 读身份缓存。
+ * @returns {{kind:'identity',userName:string,email:string,stale:boolean}
+ *          |{kind:'tombstone',stale:boolean}
+ *          |{kind:'miss'}}
+ *   损坏 JSON / 缺字段 / 文件不存在一律 miss
+ */
+function readIdentityCache(options = {}) {
+  let raw;
+  try {
+    raw = fs.readFileSync(identityPathFor(options.homeDir, options.env), 'utf8');
+  } catch {
+    return { kind: 'miss' };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { kind: 'miss' };
+  }
+  if (!parsed || typeof parsed !== 'object') return { kind: 'miss' };
+  const readAt = Date.parse(typeof parsed.readAt === 'string' ? parsed.readAt : '');
+  const age = Number.isFinite(readAt) ? nowMs(options) - readAt : Infinity;
+  if (parsed.unavailable === true) {
+    return { kind: 'tombstone', stale: !(age >= 0 && age < TOMBSTONE_TTL_MS) };
+  }
+  if (
+    typeof parsed.userName === 'string' && parsed.userName
+    && typeof parsed.email === 'string' && parsed.email
+  ) {
+    return {
+      kind: 'identity',
+      userName: parsed.userName,
+      email: parsed.email,
+      stale: !(age >= 0 && age < IDENTITY_TTL_MS),
+    };
+  }
+  return { kind: 'miss' };
+}
+
+/**
+ * 获取 in-progress 锁：新鲜锁（<120s）存在或并发创建失败返回 false。
+ * 锁内容无语义，mtime 即心跳。
+ */
+function tryAcquireRefreshLock(options = {}) {
+  const lockPath = refreshLockPathFor(options.homeDir, options.env);
+  let stale = false;
+  try {
+    const st = fs.statSync(lockPath);
+    if (nowMs(options) - st.mtimeMs < REFRESH_LOCK_TTL_MS) return false;
+    stale = true; // 过期锁：可接管
+  } catch { /* 无锁 */ }
+  try {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    // 新建用 'wx' 排他竞争；过期锁允许覆盖接管（并发接管最多多刷一次，幂等无害）
+    fs.writeFileSync(lockPath, String(nowMs(options)), { encoding: 'utf8', flag: stale ? 'w' : 'wx' });
+    return true;
+  } catch {
+    return false; // 并发创建失败视为他人持锁
+  }
+}
+
+function releaseRefreshLock(options = {}) {
+  try {
+    fs.unlinkSync(refreshLockPathFor(options.homeDir, options.env));
+  } catch { /* ignore */ }
+}
+
+/**
+ * 触发后台刷新：detached+unref 子进程运行本文件 refresh 模式。
+ * spawn 抛错时释放锁。返回是否真正触发（false=锁被持有或 spawn 失败）。
+ */
+function triggerBackgroundRefresh(options = {}) {
+  if (!tryAcquireRefreshLock(options)) return false;
+  const spawnFn = (options && options.spawn) || childProcess.spawn;
+  try {
+    const child = spawnFn(
+      process.execPath,
+      [__filename, 'refresh', '--home', resolveHome(options.homeDir, options.env)],
+      { detached: true, stdio: 'ignore' },
+    );
+    if (child && typeof child.unref === 'function') child.unref();
+    return true;
+  } catch {
+    releaseRefreshLock(options);
+    return false;
+  }
+}
+
+/**
+ * 主入口（同步，零 git）：读持久缓存，必要时触发后台刷新。
+ * - 身份新鲜：直接返回，零 spawn
+ * - 身份过期：沿用旧值 + 触发刷新
+ * - tombstone 新鲜：返回 null，零 spawn
+ * - tombstone 过期 / miss：返回 null + 触发刷新
+ *
+ * @returns {{userName:string,email:string}|null}
+ */
+function ensureIdentity(options = {}) {
+  const cache = readIdentityCache(options);
+  if (cache.kind === 'identity') {
+    if (cache.stale) triggerBackgroundRefresh(options);
+    return { userName: cache.userName, email: cache.email };
+  }
+  if (cache.kind === 'tombstone' && !cache.stale) return null;
+  triggerBackgroundRefresh(options);
+  return null;
+}
+
+/**
+ * 后台刷新执行体（也可注入 execFileSync 在测试内 in-process 运行）。
+ * git 成功但字段缺失才写 tombstone；失败/超时什么都不写（允许下次重试）。
+ * 总是释放 in-progress 锁。
+ * @returns {boolean} git 调用是否成功（不代表一定写入了身份）
+ */
+function runRefresh(options = {}) {
+  const execFileSyncFn = (options && options.execFileSync) || childProcess.execFileSync;
+  try {
+    let out;
+    try {
+      out = String(execFileSyncFn('git', ['config', '--get-regexp', '^user\\.'], {
+        timeout: REFRESH_GIT_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }));
+    } catch {
+      return false; // 失败/超时：不写 tombstone，允许下次重试
+    }
+    let userName = '';
+    let email = '';
+    for (const line of out.split('\n')) {
+      const m = line.match(/^(\S+)\s+(.*)$/);
+      if (!m) continue;
+      if (m[1] === 'user.name') userName = m[2].trim();
+      else if (m[1] === 'user.email') email = m[2].trim();
+    }
+    if (userName && email) {
+      writeIdentityCache({ userName, email }, options);
+    } else {
+      writeTombstone(options);
+    }
+    return true;
+  } finally {
+    releaseRefreshLock(options);
+  }
+}
+
+/**
+ * refresh 子进程 CLI 入口：node git-identity.cjs refresh --home <dir>
+ * runRefresh 成功且回读缓存为 identity 时，lazy require usage-reporter 自触发一次
+ * pending 冲刷（身份就绪后数秒内补报，不再等下一次七值 start）。
+ * lazy require 规避循环依赖（usage-reporter 顶层已 require 本模块）。
+ * 返回 flush promise（无触发时为 resolved promise），便于测试 await。
+ */
+function runRefreshCli(argv, options = {}) {
+  const homeIdx = argv.indexOf('--home');
+  const homeDir = homeIdx >= 0 ? argv[homeIdx + 1] : undefined;
+  try {
+    const ok = runRefresh(Object.assign({}, options, { homeDir }));
+    if (!ok) return Promise.resolve(false);
+    // 回读缓存：仅真实写入 identity 才触发 flush（tombstone 不触发）
+    const cache = readIdentityCache({ homeDir });
+    if (cache.kind !== 'identity') return Promise.resolve(false);
+    try {
+      const { flushPendingUsage } = require('./usage-reporter.cjs');
+      return flushPendingUsage({ homeDir })
+        .catch(() => false)
+        .then(() => true);
+    } catch {
+      return Promise.resolve(true);
+    }
+  } catch { /* 永不抛到进程外 */ }
+  return Promise.resolve(false);
+}
+
+if (require.main === module) {
+  if (process.argv[2] === 'refresh') runRefreshCli(process.argv.slice(2));
+}
+
+module.exports = {
+  ensureIdentity,
+  readIdentityCache,
+  writeIdentityCache,
+  writeTombstone,
+  triggerBackgroundRefresh,
+  runRefresh,
+  runRefreshCli,
+  identityPathFor,
+  refreshLockPathFor,
+  IDENTITY_TTL_MS,
+  TOMBSTONE_TTL_MS,
+  REFRESH_LOCK_TTL_MS,
+  REFRESH_GIT_TIMEOUT_MS,
+};

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

@@ -1,11 +1,16 @@
 // kld-T01 — CLI 使用统计上报契约
-// 集中定义：七值 skill 枚举、Device Flow 信封、ApiResponse 解包、
+// 集中定义：七值 skill 枚举、ApiResponse 解包、内置默认上报地址、
 // Node 14 兼容的 URL/HTTP 基础函数。与 kb-sdd 跨仓契约保持一致。
 'use strict';
 
 const http = require('node:http');
 const https = require('node:https');
 
+/**
+ * 内置默认上报地址：四级 server 解析的最后一级兜底。
+ */
+const DEFAULT_SERVER_URL = 'http://10.29.213.80:8080';
+
 /**
  * 七值使用统计 skill 枚举。
  * test / explore 不属于统计范围，永不映射。
@@ -75,89 +80,18 @@ function unwrapApiResponse(body) {
   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；不再重试但不上抛
+ * - drop: 其他 4xx（含 401）；不再重试但不上抛，也不清除任何本地状态
  *
  * @param {number|null} statusCode
- * @returns {'confirmed'|'unauthorized'|'retry'|'drop'}
+ * @returns {'confirmed'|'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';
@@ -171,14 +105,14 @@ function classifyUsageSubmitResponse(statusCode) {
  *
  * @param {string} url — 完整 URL（必须 http/https）
  * @param {object} payload — 请求体（JSON 序列化）
- * @param {{token?:string,timeoutMs?:number,headers?:object}} [options]
+ * @param {{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 = {}) {
+function postJson(url, payload = {}, options = {}) {
   return new Promise((resolve, reject) => {
     let target;
     try {
@@ -192,14 +126,14 @@ function postJson(url, payload, options = {}) {
       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);
+      // payload 缺省为 {}（默认参数），null 仍按 "null" 序列化，与原三元行为一致
+      body = JSON.stringify(payload);
     } catch (err) {
       reject(new Error(`payload serialization error: ${err.message}`));
       return;
@@ -213,7 +147,6 @@ function postJson(url, payload, options = {}) {
       },
       options && options.headers && typeof options.headers === 'object' ? options.headers : {},
     );
-    if (token) headers.Authorization = `Bearer ${token}`;
 
     const request = transport.request(
       {
@@ -269,8 +202,7 @@ module.exports = {
   mapCommandToUsageSkill,
   normalizeServerUrl,
   unwrapApiResponse,
-  parseDeviceCodeResponse,
-  classifyDevicePollResponse,
   classifyUsageSubmitResponse,
   postJson,
+  DEFAULT_SERVER_URL,
 };