huaweicloud-devkit 1.1.12 → 1.1.13-next.2

package/plugins/huaweicloud-core/src/sandbox/hdkitservice-api.mjs

@@ -1,7 +1,9 @@
 import { getCredentials } from './hwlink-api.mjs';
 import { getProxyDispatcher } from '../proxy/proxy-agent.mjs';
 import { cacheUserHash } from '../telemetry/telemetry.mjs';
+import { detectAgent } from '../telemetry/agent-detect.mjs';
 import { readInstalledVersion } from '../update-check.mjs';
+import { pinnedTemplateFor } from './sandbox-pool.mjs';
 
 function getHdkitBaseUrl() {
   return process.env.HDKITSERVICE_ENDPOINT || 'https://devkit.huaweicloud.com/rest/developer/server/hdkitservice/';
@@ -21,6 +23,8 @@ async function hdkitRequest(method, path, body, timeoutMs = 300000) {
     'X-HW-AK': ak,
     'X-HW-SK': sk,
     'X-HW-Client-Version': readInstalledVersion() || '0.0.0',
+    // #1040: 对外请求统一携带 X-HW-Agent（值=detectAgent 结果 harness）
+    'X-HW-Agent': detectAgent().harness,
   };
   if (securitytoken) {
     headers['X-HW-Security-Token'] = securitytoken;
@@ -75,6 +79,43 @@ async function hdkitRequest(method, path, body, timeoutMs = 300000) {
         ],
       };
     }
+    // 429 双错误码结构化处理（两池配额契约）：配额满（用户侧，重试无效）与
+    // 池容量不足（平台侧，错峰重试）给出差异化引导；携带服务端 Retry-After
+    if (code === 'HDKIT_QUOTA_EXCEEDED') {
+      err.retryAfter = resp.headers.get('Retry-After') || undefined;
+      err.remediation = {
+        hint: '沙箱并发配额已满（每账号最多 5 台、每类型 1 台），重试无效：',
+        steps: [
+          '确认已有实例是否够用：connect 对同池实例自动复用，无需重复创建',
+          '释放不再使用的沙箱（控制台或平台回收）后重试',
+          '如需两种生命周期语义并存：ephemeral 与 persistent 各可持有 1 台',
+        ],
+      };
+    }
+    if (code === 'HDKIT_CAPACITY_INSUFFICIENT') {
+      err.retryAfter = resp.headers.get('Retry-After') || undefined;
+      err.remediation = {
+        hint: '平台池容量暂时不足（非账号问题）：',
+        steps: [
+          '稍后错峰重试（devkit提供的免费资源紧张，建议错峰使用）',
+          '急需使用时可尝试另一 pool_type（另一池可能有余量）',
+        ],
+      };
+    }
+    // 烧核播报（缺口#5 代码层）：账号核心时长耗尽——上游码 HD.97520422 经
+    // hdkitservice 以 HDKIT_UPSTREAM_ERROR 包装透传，客户端按消息内错误码识别。
+    // 仅在前面的分支未设置 remediation 时生效（else-if 语义：烧核不覆盖 429 双码/凭证指引）
+    if (!err.remediation && String(data.message || '').includes('HD.97520422')) {
+      err.coreHoursExhausted = true;
+      err.remediation = {
+        hint: '账号核心时长（核时）已耗尽，沙箱无法继续运行：',
+        steps: [
+          '核时按沙箱运行时长消耗，当前账号余额为 0',
+          '更换有核时余额的账号，或等待/申请核时补充',
+          '详见华为云开发者空间核心时长说明',
+        ],
+      };
+    }
     throw err;
   }
 
@@ -104,6 +145,13 @@ export async function hdkitConnect(options = {}) {
   if (options.git) body.git = options.git;
   if (options.template_id) body.template_id = options.template_id;
   if (options.flavor_id) body.flavor_id = options.flavor_id;
+  if (options.pool_type) {
+    // 两池：pool_type 由服务端权威映射（不传默认 ephemeral）。
+    // 可选运维钉扎：配置 HW_POOL_TEMPLATE_* 时附带映射模板（服务端与老服务端均按显式模板处理）
+    body.pool_type = options.pool_type;
+    const pinned = pinnedTemplateFor(options.pool_type);
+    if (pinned && !body.template_id) body.template_id = pinned;
+  }
 
   return await hdkitRequest('POST', 'connect', body);
 }

package/plugins/huaweicloud-core/src/sandbox/sandbox-pool.mjs

@@ -0,0 +1,104 @@
+// 两池沙箱（pool_type）客户端支持。
+// 机制（定稿）：池 = 平台预置模板，客户端传 pool_type（ephemeral/persistent），
+// 服务端权威映射 template_id；显式 template_id 优先（运维钉扎场景）。
+// - 非持久池（默认）：闲置 30min 自动关机 + 1h 删除（平台定时任务，已实测生效）
+// - 持久池：EVS 数据盘跨关机保留，闲置回收保留期上限 7 天
+// - 配额：每用户每类型 1 台（同类复用），账号并发上限 5
+
+const POOL_TYPES = new Set(['ephemeral', 'persistent']);
+
+/** workspaceId → poolType 缓存：exec/upload/deploy 等工具返回值据此附带池上下文 */
+const workspacePool = new Map();
+
+/**
+ * 校验并归一化 pool_type；未传时返回 null（交由服务端默认 ephemeral，不在客户端伪造语义）。
+ * @throws Error 非法值（ephemeral/persistent 之外）
+ */
+export function validatePoolType(raw) {
+  if (raw === undefined || raw === null || raw === '') return null;
+  const normalized = String(raw).trim().toLowerCase();
+  if (!POOL_TYPES.has(normalized)) {
+    throw new Error(
+      `invalid pool_type "${raw}" (expected ephemeral or persistent). ` +
+        'ephemeral = 非持久沙箱（闲置 30min 自动关机、1h 删除）；persistent = 持久沙箱（数据盘保留，闲置回收上限 7 天）',
+    );
+  }
+  return normalized;
+}
+
+/**
+ * 运维钉扎（可选）：设置 HW_POOL_TEMPLATE_EPHEMERAL/PERSISTENT 后，客户端把映射出的
+ * template_id 与 pool_type 一并上送——服务端（及未升级的老服务端）按显式模板处理。
+ * 日常部署无需配置：模板 ID 由服务端 POOL_TEMPLATE_* 环境变量权威维护。
+ */
+export function pinnedTemplateFor(poolType) {
+  if (poolType === 'ephemeral') return process.env.HW_POOL_TEMPLATE_EPHEMERAL || '';
+  if (poolType === 'persistent') return process.env.HW_POOL_TEMPLATE_PERSISTENT || '';
+  return '';
+}
+
+/** 记录 workspace 的池归属（来自服务端 connect 响应的 pool_type 回显） */
+export function rememberWorkspacePool(workspaceId, poolType) {
+  if (workspaceId && poolType) workspacePool.set(workspaceId, poolType);
+}
+
+/** 清理 workspace 池缓存（测试用） */
+export function forgetWorkspacePool(workspaceId) {
+  if (workspaceId === undefined) workspacePool.clear();
+  else workspacePool.delete(workspaceId);
+}
+
+/**
+ * exec/upload/deploy 等工具返回值的池上下文（缺口#2 模式提示）。
+ * 未记录池归属（老服务端/自定义模板）时返回 undefined，不附加任何字段。
+ */
+export function poolContextFor(workspaceId) {
+  const poolType = workspacePool.get(workspaceId);
+  if (poolType === 'ephemeral') {
+    return {
+      poolMode: 'ephemeral',
+      persistenceHint: '非持久沙箱：闲置 30 分钟自动关机、1 小时自动删除，重要数据请及时保存或迁出',
+    };
+  }
+  if (poolType === 'persistent') {
+    return {
+      poolMode: 'persistent',
+      persistenceHint: '持久沙箱：数据盘跨关机保留，闲置回收保留期最长 7 天',
+    };
+  }
+  return undefined;
+}
+
+/**
+ * connect 结果池富化（缺口#1 TTL 播报）。
+ * 仅当服务端回显 pool_type 才播报（两种状态制：服务端未确认池语义不编造）。
+ * 钉扎/自定义模板（服务端回显 null）不播报。
+ * 读取做 pool_type/poolType 双读兜底（与 devStageId 双读同型，防 wire 命名漂移）。
+ */
+export function enrichConnectResult(result) {
+  if (!result || typeof result !== 'object') return result;
+  const poolType = result.pool_type || result.poolType;
+  if (poolType === 'ephemeral') {
+    result.pool = {
+      pool_type: 'ephemeral',
+      lifecycle: 'idle 30min auto-shutdown + 1h auto-delete (platform scheduled task, verified)',
+      ttl_hint:
+        '非持久沙箱：闲置 30 分钟将自动关机、闲置 1 小时将自动删除（平台定时任务已生效）。' +
+        '重要数据请及时保存或迁出；需要跨会话保留数据请改用 pool_type=persistent。',
+    };
+  } else if (poolType === 'persistent') {
+    result.pool = {
+      pool_type: 'persistent',
+      lifecycle: 'EVS data disk retained; idle reclaim within 7 days max',
+      ttl_hint: '持久沙箱：数据盘跨关机保留，闲置回收保留期最长 7 天；长期不用请自行导出数据。',
+    };
+  }
+  return result;
+}
+
+/** 池信息字段并入既有对象结果（非对象结果原样返回） */
+export function withPoolContext(workspaceId, result) {
+  const ctx = poolContextFor(workspaceId);
+  if (!ctx || !result || typeof result !== 'object') return result;
+  return { ...result, ...ctx };
+}

package/plugins/huaweicloud-core/src/setup-cli.mjs

@@ -75,6 +75,13 @@ function configRoot(target = 'opencode') {
   return join(home, '.config', target);
 }
 
+// Must match telemetry.mjs GLOBAL_TELEMETRY_DIR root: HUAWEICLOUD_DEVKIT_HOME
+// overrides homedir() so sandbox/multi-HOME environments stay consistent (#1014).
+function devkitTelemetryDir() {
+  const home = (process.env.HUAWEICLOUD_DEVKIT_HOME || '').trim() || homedir();
+  return join(home, '.huaweicloud-devkit', 'telemetry');
+}
+
 function opencodeSkillsDir() {
   return join(configRoot('opencode'), 'skills');
 }
@@ -1814,7 +1821,7 @@ function deployWorkBuddyHooks() {
 
   // 4. Ensure telemetry output directories exist
   mkdirSync(join(workbuddyPluginsDir(), 'telemetry'), { recursive: true });
-  mkdirSync(join(homedir(), '.huaweicloud-devkit', 'telemetry'), { recursive: true });
+  mkdirSync(devkitTelemetryDir(), { recursive: true });
 }
 
 // ── AtomCode hooks deployment ────────────────────────────────
@@ -1982,10 +1989,10 @@ function uninstallWorkBuddy() {
     console.log(`  Removed hook tracker: ${trackerPath}`);
   }
 
-  const devkitTelemetryDir = join(homedir(), '.huaweicloud-devkit', 'telemetry');
-  if (existsSync(devkitTelemetryDir)) {
-    rmSync(devkitTelemetryDir, { recursive: true, force: true });
-    console.log(`  Removed telemetry cache: ${devkitTelemetryDir}`);
+  const devkitTelemetryPath = devkitTelemetryDir();
+  if (existsSync(devkitTelemetryPath)) {
+    rmSync(devkitTelemetryPath, { recursive: true, force: true });
+    console.log(`  Removed telemetry cache: ${devkitTelemetryPath}`);
   }
 }
 

package/plugins/huaweicloud-core/src/telemetry/agent-detect.mjs

@@ -1,24 +1,31 @@
-import { AGENTS, matchAgent, detectVersion, installSegment } from './agent-registry.mjs';
+import { AGENTS, matchAgent, detectVersion } from './agent-registry.mjs';
 
 /**
- * 仅返回 harness 字符串（或 null），不返回 version。
- * 用于简单场景（如 keepalive 判断、测试断言）。
+ * 仅返回 harness 字符串，不返回 version。
+ * #1040: 白名单 / AGENT_HARNESS 未命中时一律返回 'unknown'——
+ * 不再透传 clientInfo.name（startup、voucher-claim*、test* 等探针类 clientName 同样归 unknown），
+ * 也不拼接 installSegment，避免 agent 名出现 '|' 污染。
  */
 export function detectAgentHarness(clientInfo = {}) {
-  if (process.env.AGENT_HARNESS) return process.env.AGENT_HARNESS;
+  const envHarness = process.env.AGENT_HARNESS;
+  if (envHarness && AGENTS.some((a) => a.id === envHarness)) return envHarness;
   for (const agent of AGENTS) {
     if (matchAgent(agent, clientInfo)) return agent.id;
   }
-  return clientInfo.name || null;
+  return 'unknown';
 }
 
 export function detectAgent(clientInfo = {}) {
-  if (process.env.AGENT_HARNESS) {
-    const cfg = AGENTS.find((a) => a.id === process.env.AGENT_HARNESS) || null;
-    return {
-      harness: process.env.AGENT_HARNESS,
-      version: detectVersion(cfg ? cfg.version : null) || clientInfo.version || '0.0.0',
-    };
+  // AGENT_HARNESS 仅在命中白名单时生效；未命中视为不可信输入，不透传任意环境值。
+  const envHarness = process.env.AGENT_HARNESS;
+  if (envHarness) {
+    const cfg = AGENTS.find((a) => a.id === envHarness) || null;
+    if (cfg) {
+      return {
+        harness: envHarness,
+        version: detectVersion(cfg.version) || clientInfo.version || '0.0.0',
+      };
+    }
   }
 
   for (const agent of AGENTS) {
@@ -30,11 +37,9 @@ export function detectAgent(clientInfo = {}) {
     }
   }
 
-  const seg = installSegment();
-  const base = clientInfo.name || 'unknown';
-  const harness = seg ? `${base}|${seg}` : base;
+  // #1040: 兜底收敛 'unknown'——安装位置信息走遥测独立字段 installSegment，不进入 agent 名。
   return {
-    harness: harness.length > 32 ? harness.slice(0, 32) : harness,
+    harness: 'unknown',
     version: clientInfo.version || '0.0.0',
   };
 }

package/plugins/huaweicloud-core/src/telemetry/agent-registry.mjs

@@ -10,6 +10,10 @@ const selfPath = (() => {
   }
 })();
 
+/**
+ * #1040: 安装位置段——仅用于遥测的独立安装位置字段（telemetry 事件 installSegment），
+ * 不进入 agent 名/harness；AGENTS 白名单与 matchAgent 规则不受安装位置影响。
+ */
 export function installSegment() {
   const parts = selfPath.split('/').filter(Boolean);
   const srcIdx = parts.lastIndexOf('src');

package/plugins/huaweicloud-core/src/telemetry/telemetry.mjs

@@ -14,6 +14,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
 import { fetchWithProxy } from '../proxy/proxy-agent.mjs';
+import { installSegment } from './agent-registry.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -68,7 +69,7 @@ const MAX_RETRIES = 3;
 const DEFAULT_ENDPOINT = 'https://devkit.huaweicloud.com/rest/developer/server/hdkitservice/telemetry/events';
 
 let eventQueue = [];
-let isFlushing = false;
+let currentFlush = null;
 let flushTimer = null;
 let lastCheckedDate = '';
 let installId = null;
@@ -207,6 +208,9 @@ function buildEvent(raw) {
     os: osTypeStr,
     osVersion: osVersionStr,
   };
+  // #1040: 安装位置独立字段——原拼接进 harness 的 installSegment 改为单列上报。
+  const seg = installSegment();
+  if (seg) event.installSegment = sanitizeValue(seg);
   const cap = raw.capability || capabilityFromKey(raw.key);
   if (cap) event.capability = cap;
   return event;
@@ -214,7 +218,9 @@ function buildEvent(raw) {
 
 export function enqueueEvent(raw) {
   if (!isTelemetryEnabled()) return;
-  if (!installId) return;
+  // #1014: installId 未初始化时（如未走 initialize 直接 tools/call）不再丢弃事件，
+  // 惰性恢复，避免 telemetry_event 缺记录。
+  if (!installId) installId = generateOrRecoverInstallId();
 
   ingestHookEvents();
 
@@ -324,10 +330,37 @@ export function clearUserHash() {
   } catch {}
 }
 
-function flushEvents() {
-  if (isFlushing) return;
-  if (eventQueue.length === 0) return;
-  isFlushing = true;
+// #1014: flush 前兜底补齐队列事件的缺失身份字段——
+// userHash 在 enqueue 之后才解析到（领券响应 / user-hash 文件）时，
+// 已入队事件的 userHash 仍为 null，这里统一回填，降低 user_hash null 占比。
+function backfillIdentityFields() {
+  try {
+    if (!installId) installId = generateOrRecoverInstallId();
+    if (!userHash) loadUserHash();
+    for (const event of eventQueue) {
+      if (!event.installId && installId) event.installId = installId;
+      if (event.userHash == null && userHash) event.userHash = userHash;
+    }
+  } catch (_) {
+    debugLog('BACKFILL identity fields failed');
+  }
+}
+
+// #1014: flush 可被 await（P0 领券类工具同步上报）；
+// 并发调用复用同一次 in-flight flush（currentFlush 声明于模块顶部）。
+export function flushEvents() {
+  if (currentFlush) return currentFlush;
+  if (eventQueue.length === 0) return Promise.resolve();
+  currentFlush = performFlush().finally(() => {
+    currentFlush = null;
+  });
+  return currentFlush;
+}
+
+async function performFlush() {
+  // flush 前统一回填身份字段（含 userHash 重解析，#1014）：
+  // 入队时身份未解析的事件此前会永久携带 null userHash。
+  backfillIdentityFields();
 
   const batch = eventQueue.splice(0, BATCH_SIZE);
   const keys = batch.map((e) => e.key).join(',');
@@ -339,34 +372,72 @@ function flushEvents() {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
 
-  fetchWithProxy(endpoint, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(batch.map(({ _retries, ...rest }) => rest)),
-    signal: controller.signal,
-  })
-    .then((resp) => {
-      clearTimeout(timer);
-      debugLog(`POST status=${resp.status} events=${batch.length}`);
-      if (resp.ok) {
-        for (const event of batch) {
-          if (event.key === 'dau:active_today') touchFile(dauStampPath());
-          if (event.key === 'plugin:install') touchFile(installStampPath());
-          if (event.key === 'plugin:first_use') touchFile(firstUseStampPath());
-        }
-      } else if (resp.status >= 400 && resp.status < 500) {
-        debugLog(`POST status=${resp.status} dropping ${batch.length} events (client error)`);
-      } else {
-        requeueEvents(batch);
+  try {
+    const resp = await fetchWithProxy(endpoint, {
+      method: 'POST',
+      // #1040: 对外上报统一携带 X-HW-Agent（值=detectAgent 结果 harness，initTelemetry 缓存）
+      headers: { 'Content-Type': 'application/json', 'X-HW-Agent': agentHarness || 'unknown' },
+      body: JSON.stringify(batch.map(({ _retries, ...rest }) => rest)),
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+    debugLog(`POST status=${resp.status} events=${batch.length}`);
+    if (resp.ok) {
+      for (const event of batch) {
+        if (event.key === 'dau:active_today') touchFile(dauStampPath());
+        if (event.key === 'plugin:install') touchFile(installStampPath());
+        if (event.key === 'plugin:first_use') touchFile(firstUseStampPath());
       }
-      isFlushing = false;
-    })
-    .catch((error) => {
-      clearTimeout(timer);
-      debugLog(`POST FAIL err=${error.message} events=${batch.length}`);
+    } else if (resp.status >= 400 && resp.status < 500) {
+      debugLog(`POST status=${resp.status} dropping ${batch.length} events (client error)`);
+    } else {
       requeueEvents(batch);
-      isFlushing = false;
+    }
+  } catch (error) {
+    clearTimeout(timer);
+    debugLog(`POST FAIL err=${error.message} events=${batch.length}`);
+    requeueEvents(batch);
+  }
+}
+
+// #1014 P1: 排空整个队列（退出兜底用，单次 flush 只发一个 batch）。
+export async function flushAllEvents() {
+  const maxBatches = Math.ceil(MAX_QUEUE_SIZE / BATCH_SIZE) + 1;
+  for (let i = 0; i < maxBatches && eventQueue.length > 0; i++) {
+    await flushEvents();
+  }
+}
+
+const EXIT_FLUSH_TIMEOUT_MS = 3000;
+let exitFlushRegistered = false;
+
+// #1014 P1: SIGTERM/SIGINT 退出兜底 flush（有界超时，避免阻塞退出）。
+// 返回反注册函数（仅测试使用）。
+export function registerExitFlush() {
+  if (exitFlushRegistered) return () => {};
+  exitFlushRegistered = true;
+  const flushAndExit = () => {
+    if (eventQueue.length === 0) {
+      // eslint-disable-next-line n/no-process-exit -- signal shutdown with nothing to flush
+      process.exit(0);
+    }
+    const cap = new Promise((resolve) => {
+      const t = setTimeout(resolve, EXIT_FLUSH_TIMEOUT_MS);
+      t.unref?.();
+    });
+    const done = flushAllEvents().catch(() => {});
+    Promise.race([done, cap]).finally(() => {
+      // eslint-disable-next-line n/no-process-exit -- signal shutdown after bounded exit flush
+      process.exit(0);
     });
+  };
+  process.once('SIGTERM', flushAndExit);
+  process.once('SIGINT', flushAndExit);
+  return () => {
+    process.removeListener('SIGTERM', flushAndExit);
+    process.removeListener('SIGINT', flushAndExit);
+    exitFlushRegistered = false;
+  };
 }
 
 function requeueEvents(batch) {
@@ -390,6 +461,9 @@ export function initTelemetry({ harness, version }) {
 
   loadUserHash();
 
+  // #1014 P1: SIGTERM/SIGINT 退出兜底 flush（队列空时立即退出，零开销）。
+  registerExitFlush();
+
   if (!isTelemetryEnabled()) return;
 
   if (!stampExists(installStampPath()) && !existsSync(installCounterPath())) {