@hcmai/sdk 0.3.11 → 0.3.13

package/dist/index.js

@@ -592,6 +592,11 @@ var CliError = class extends Error {
     const detailText = formatDetails(details);
     if (detailText) out += `
   \u8BE6\u60C5: ${detailText}`;
+    if (!detailText) {
+      const causeText = formatCause(this.cause);
+      if (causeText) out += `
+  \u539F\u56E0: ${causeText}`;
+    }
     const nextStep = this.context?.nextStep;
     if (typeof nextStep === "string" && nextStep) out += `
   \u4E0B\u4E00\u6B65: ${nextStep}`;
@@ -657,6 +662,15 @@ function formatDetails(details) {
   if (!text || text === "{}" || text === "[]") return void 0;
   return text.length > 800 ? `${text.slice(0, 800)}\u2026\uFF08\u5DF2\u622A\u65AD\uFF09` : text;
 }
+function formatCause(cause) {
+  if (!cause) return void 0;
+  if (typeof cause === "string") return cause.trim().slice(0, 300) || void 0;
+  if (cause instanceof Error) {
+    const text = cause.message?.trim();
+    return text ? text.slice(0, 300) : void 0;
+  }
+  return void 0;
+}
 
 // src/config/env.ts
 async function saveEnv(name, cfg) {
@@ -1129,6 +1143,167 @@ async function describe(http, model, _opts = {}) {
   };
 }
 
+// src/fde/fingerprint.ts
+import { createHash } from "crypto";
+var GATE_COMPONENTS = [
+  "tenantMetaManifestDigest",
+  "extensionSource",
+  "modelListHash"
+];
+var BLIND_SPOTS = "\u4EA7\u54C1\u5347\u7EA7\uFF1Amanifest \u53EA\u8BFB\u79DF\u6237 workspace \u7684 metas/ \u76EE\u5F55\uFF0C\u4EA7\u54C1\u5347\u7EA7\u6539\u7684\u662F\u5B89\u88C5\u5305\u5185 _metas/\uFF0C\u56DB\u5143\u7EC4\u4E0D\u4F1A\u53D8\u2014\u2014\u8BE5\u573A\u666F\u7684\u9632\u7EBF\u53EA\u6709\u884C\u4E3A\u63A2\u9488\u4E00\u6761\u3002 | \u540C\u5B57\u8282\u6570\u5185\u5BB9\u66FF\u6362\uFF1A\u6E05\u5355\u53EA\u7ED9 name/size/lastModified\uFF0C\u628A\u6807\u7B7E\u300C\u90E8\u95E8\u300D\u6539\u6210\u300C\u673A\u6784\u300D\u5728 UTF-8 \u4E0B\u6070\u597D\u90FD\u662F 6 \u5B57\u8282\uFF0C\u6458\u8981\u4E0D\u53D8\u3002\u21D2 \u5B57\u6BB5\u540D\u53EB ManifestDigest \u800C\u975E Fingerprint\uFF0C\u540D\u5B57\u5FC5\u987B\u8BF4\u5B9E\u8BDD\u3002";
+var MODELS_PATH = "/api/system/models";
+var MANIFEST_PATH = "/api/tenant-meta/list";
+var VERSION_PATH = "/api/version/backend";
+var META_PATH = "/api/models/{model}/meta";
+var EXTENSION_SOURCE_HEADER = "x-hcm-extension-source";
+var MAX_SOURCE_PROBES = 50;
+var MAX_MANIFEST_PAGES = 200;
+var GATE_SOURCES = [MODELS_PATH, MANIFEST_PATH, META_PATH];
+function modelEntries(body) {
+  if (!isPlainObject2(body)) return [];
+  const raw = body.models;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(isPlainObject2);
+}
+function modelKeys(body) {
+  return modelEntries(body).map((m) => typeof m.modelKey === "string" ? m.modelKey : "").filter((k) => k !== "").sort();
+}
+async function probeExtensionSource(probe, keys) {
+  let attempted = 0;
+  let answered = 0;
+  for (const key of [...keys].sort().slice(0, MAX_SOURCE_PROBES)) {
+    attempted += 1;
+    const out = await probe.get(META_PATH.replace("{model}", key));
+    if (out.error !== "ok") continue;
+    answered += 1;
+    const value = out.headers[EXTENSION_SOURCE_HEADER];
+    if (value) return { sourceKey: value, probeModelKey: key, attempted, answered };
+  }
+  return { sourceKey: "", probeModelKey: "", attempted, answered };
+}
+async function fetchManifestRows(probe, failures) {
+  const rows = [];
+  let page = 0;
+  const pageSize = 200;
+  for (; ; ) {
+    const out = await probe.get(MANIFEST_PATH, { page, pageSize });
+    if (out.error !== "ok" || !isPlainObject2(out.body)) {
+      failures.push(MANIFEST_PATH);
+      break;
+    }
+    const body = out.body;
+    const chunk = body.data ?? [];
+    if (!Array.isArray(chunk)) {
+      failures.push(MANIFEST_PATH);
+      break;
+    }
+    rows.push(...chunk.filter(isPlainObject2));
+    const totalPages = typeof body.totalPages === "number" ? body.totalPages : 0;
+    page += 1;
+    if (page >= totalPages || chunk.length === 0) break;
+    if (page >= MAX_MANIFEST_PAGES) {
+      failures.push(`${MANIFEST_PATH}#page-cap`);
+      break;
+    }
+  }
+  return rows;
+}
+function manifestDigest(rows) {
+  const lines = rows.map((r) => `${r.name}|${r.size}|${r.lastModified}`).sort();
+  return sha256(lines.join("\n"));
+}
+async function computeReconSourceKey(probe) {
+  const out = await probe.get(MODELS_PATH);
+  const p = await probeExtensionSource(probe, modelKeys(out.body));
+  return p.sourceKey || "unknown";
+}
+async function computeFingerprint(probe, opts = {}) {
+  const ttlDays = opts.ttlDays ?? 30;
+  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  const failures = [];
+  const modelsOut = await probe.get(MODELS_PATH);
+  const modelsOk = modelsOut.error === "ok" && isPlainObject2(modelsOut.body);
+  if (!modelsOk) failures.push(MODELS_PATH);
+  const models = modelsOk ? modelEntries(modelsOut.body) : [];
+  const keys = modelsOk ? modelKeys(modelsOut.body) : [];
+  if (modelsOut.error === "ok" && keys.length === 0) {
+    failures.push(`${MODELS_PATH}#empty-model-list`);
+  }
+  const p = await probeExtensionSource(probe, keys);
+  let sourceKey = p.sourceKey;
+  if (!sourceKey) {
+    failures.push(
+      p.answered > 0 ? `${META_PATH}#X-HCM-Extension-Source` : `${META_PATH}#no-meta-answered`
+    );
+    sourceKey = "unknown";
+  }
+  const hashLines = models.map((m) => `${m.modelKey ?? ""}|${m.type ?? ""}`).sort();
+  const modelHash = sha256(hashLines.join("\n"));
+  const rows = await fetchManifestRows(probe, failures);
+  const versionOut = await probe.get(VERSION_PATH);
+  let backendVersion;
+  if (versionOut.error === "ok" && versionOut.body !== null && versionOut.body !== void 0) {
+    backendVersion = versionOut.body;
+  } else {
+    failures.push(VERSION_PATH);
+    backendVersion = { version: "unavailable" };
+  }
+  return {
+    tenantMetaManifestDigest: manifestDigest(rows),
+    manifestEntryCount: rows.length,
+    extensionSource: sourceKey,
+    // 🔴 记下**是从哪个模型探到的**：让「这个值是谁给的」在产物里留痕。
+    extensionSourceProbe: p.probeModelKey,
+    // 🔴 没有这两个数，`extensionSource: "unknown"` 就是一个**不可追问的结论**。
+    extensionSourceProbeAttempted: p.attempted,
+    extensionSourceProbeAnswered: p.answered,
+    modelListHash: modelHash,
+    modelCount: models.length,
+    backendVersion,
+    capabilities: probe.capabilities,
+    createdAt: `${now().toISOString().slice(0, 19)}Z`,
+    ttlDays,
+    coverageNotes: {
+      gateComponents: [...GATE_COMPONENTS],
+      blindSpots: BLIND_SPOTS,
+      // 空数组 = 三个端点都真取到了；非空 = 这份四元组是**残的**，
+      // 上面那些 0 和空摘要不代表环境真的空。
+      fetchFailures: failures
+    }
+  };
+}
+function compareFingerprint(recorded, current) {
+  const diffs = GATE_COMPONENTS.filter((c) => recorded[c] !== current[c]);
+  if (recorded.capabilities !== current.capabilities) diffs.push("capabilities");
+  for (const [fp, tag] of [
+    [recorded, "recorded"],
+    [current, "current"]
+  ]) {
+    const notes = fp.coverageNotes;
+    if (!isPlainObject2(notes) || !("fetchFailures" in notes)) {
+      diffs.push(`incomplete:${tag}:coverageNotes-missing`);
+      continue;
+    }
+    const raw = notes.fetchFailures;
+    const list = Array.isArray(raw) ? raw : [];
+    const gateFailures = [...new Set(list.map(String))].filter((x) => GATE_SOURCES.some((s) => x.startsWith(s))).sort();
+    for (const f of gateFailures) diffs.push(`incomplete:${tag}:${f}`);
+  }
+  return diffs;
+}
+function sha256(s) {
+  return createHash("sha256").update(s, "utf8").digest("hex");
+}
+function isPlainObject2(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// src/meta/models.ts
+async function listModels(http) {
+  const resp = await http.get(MODELS_PATH);
+  return modelEntries(resp.data?.data ?? resp.data);
+}
+
 // src/models/create.ts
 async function create(http, model, data) {
   const resp = await http.post(`/api/models/${model}`, data);
@@ -1378,6 +1553,10 @@ var HcmClient = class _HcmClient {
   action(model, name, input) {
     return action(this.http, model, name, input);
   }
+  /** 列出目标环境有哪些 Model —— `describe` 的上一步。 */
+  listModels() {
+    return listModels(this.http);
+  }
   describe(model, opts) {
     return describe(this.http, model, opts);
   }
@@ -4707,7 +4886,7 @@ function buildPushPlan(context, manifest2, localFiles, remoteFiles) {
   for (const entry of status) {
     const remote = remoteByLocal.get(entry.localPath);
     const base = baseByLocal.get(entry.localPath);
-    const remoteSha = remote ? sha256(remote.content.content) : void 0;
+    const remoteSha = remote ? sha2562(remote.content.content) : void 0;
     if (entry.status === "added") {
       if (remote) {
         conflicts.push(conflict(entry, "remote file already exists but was not in local snapshot"));
@@ -4840,7 +5019,7 @@ async function walk(root, relativeDir, files) {
         localPath,
         absolutePath,
         content,
-        sha256: sha256(content),
+        sha256: sha2562(content),
         size: Buffer.byteLength(content, "utf-8")
       });
     }
@@ -4953,7 +5132,7 @@ function localPathFromRemote(remotePrefix, remotePath) {
 function isDirectoryMarkerPath(relativePath) {
   return relativePath.endsWith("/.keep") || relativePath === ".keep";
 }
-function sha256(content) {
+function sha2562(content) {
   return crypto.createHash("sha256").update(content, "utf-8").digest("hex");
 }
 async function writeText(file, content) {
@@ -5267,7 +5446,7 @@ function parseSettingAssignment(raw) {
 }
 
 // src/fde/layout.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import { mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
 import * as path6 from "path";
 var UNSAFE = /[^A-Za-z0-9._-]/g;
@@ -5276,7 +5455,7 @@ function slug(value) {
 }
 function safeSegment(value) {
   const raw = value || "unknown";
-  const digest = createHash2("sha256").update(raw, "utf8").digest("hex").slice(0, 10);
+  const digest = createHash3("sha256").update(raw, "utf8").digest("hex").slice(0, 10);
   return `${slug(raw)}-${digest}`;
 }
 function tenantSegment(value) {
@@ -5391,161 +5570,6 @@ var LayoutContainmentError = class extends Error {
   }
 };
 
-// src/fde/fingerprint.ts
-import { createHash as createHash3 } from "crypto";
-var GATE_COMPONENTS = [
-  "tenantMetaManifestDigest",
-  "extensionSource",
-  "modelListHash"
-];
-var BLIND_SPOTS = "\u4EA7\u54C1\u5347\u7EA7\uFF1Amanifest \u53EA\u8BFB\u79DF\u6237 workspace \u7684 metas/ \u76EE\u5F55\uFF0C\u4EA7\u54C1\u5347\u7EA7\u6539\u7684\u662F\u5B89\u88C5\u5305\u5185 _metas/\uFF0C\u56DB\u5143\u7EC4\u4E0D\u4F1A\u53D8\u2014\u2014\u8BE5\u573A\u666F\u7684\u9632\u7EBF\u53EA\u6709\u884C\u4E3A\u63A2\u9488\u4E00\u6761\u3002 | \u540C\u5B57\u8282\u6570\u5185\u5BB9\u66FF\u6362\uFF1A\u6E05\u5355\u53EA\u7ED9 name/size/lastModified\uFF0C\u628A\u6807\u7B7E\u300C\u90E8\u95E8\u300D\u6539\u6210\u300C\u673A\u6784\u300D\u5728 UTF-8 \u4E0B\u6070\u597D\u90FD\u662F 6 \u5B57\u8282\uFF0C\u6458\u8981\u4E0D\u53D8\u3002\u21D2 \u5B57\u6BB5\u540D\u53EB ManifestDigest \u800C\u975E Fingerprint\uFF0C\u540D\u5B57\u5FC5\u987B\u8BF4\u5B9E\u8BDD\u3002";
-var MODELS_PATH = "/api/system/models";
-var MANIFEST_PATH = "/api/tenant-meta/list";
-var VERSION_PATH = "/api/version/backend";
-var META_PATH = "/api/models/{model}/meta";
-var EXTENSION_SOURCE_HEADER = "x-hcm-extension-source";
-var MAX_SOURCE_PROBES = 50;
-var MAX_MANIFEST_PAGES = 200;
-var GATE_SOURCES = [MODELS_PATH, MANIFEST_PATH, META_PATH];
-function modelEntries(body) {
-  if (!isPlainObject2(body)) return [];
-  const raw = body.models;
-  if (!Array.isArray(raw)) return [];
-  return raw.filter(isPlainObject2);
-}
-function modelKeys(body) {
-  return modelEntries(body).map((m) => typeof m.modelKey === "string" ? m.modelKey : "").filter((k) => k !== "").sort();
-}
-async function probeExtensionSource(probe, keys) {
-  let attempted = 0;
-  let answered = 0;
-  for (const key of [...keys].sort().slice(0, MAX_SOURCE_PROBES)) {
-    attempted += 1;
-    const out = await probe.get(META_PATH.replace("{model}", key));
-    if (out.error !== "ok") continue;
-    answered += 1;
-    const value = out.headers[EXTENSION_SOURCE_HEADER];
-    if (value) return { sourceKey: value, probeModelKey: key, attempted, answered };
-  }
-  return { sourceKey: "", probeModelKey: "", attempted, answered };
-}
-async function fetchManifestRows(probe, failures) {
-  const rows = [];
-  let page = 0;
-  const pageSize = 200;
-  for (; ; ) {
-    const out = await probe.get(MANIFEST_PATH, { page, pageSize });
-    if (out.error !== "ok" || !isPlainObject2(out.body)) {
-      failures.push(MANIFEST_PATH);
-      break;
-    }
-    const body = out.body;
-    const chunk = body.data ?? [];
-    if (!Array.isArray(chunk)) {
-      failures.push(MANIFEST_PATH);
-      break;
-    }
-    rows.push(...chunk.filter(isPlainObject2));
-    const totalPages = typeof body.totalPages === "number" ? body.totalPages : 0;
-    page += 1;
-    if (page >= totalPages || chunk.length === 0) break;
-    if (page >= MAX_MANIFEST_PAGES) {
-      failures.push(`${MANIFEST_PATH}#page-cap`);
-      break;
-    }
-  }
-  return rows;
-}
-function manifestDigest(rows) {
-  const lines = rows.map((r) => `${r.name}|${r.size}|${r.lastModified}`).sort();
-  return sha2562(lines.join("\n"));
-}
-async function computeReconSourceKey(probe) {
-  const out = await probe.get(MODELS_PATH);
-  const p = await probeExtensionSource(probe, modelKeys(out.body));
-  return p.sourceKey || "unknown";
-}
-async function computeFingerprint(probe, opts = {}) {
-  const ttlDays = opts.ttlDays ?? 30;
-  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
-  const failures = [];
-  const modelsOut = await probe.get(MODELS_PATH);
-  const modelsOk = modelsOut.error === "ok" && isPlainObject2(modelsOut.body);
-  if (!modelsOk) failures.push(MODELS_PATH);
-  const models = modelsOk ? modelEntries(modelsOut.body) : [];
-  const keys = modelsOk ? modelKeys(modelsOut.body) : [];
-  if (modelsOut.error === "ok" && keys.length === 0) {
-    failures.push(`${MODELS_PATH}#empty-model-list`);
-  }
-  const p = await probeExtensionSource(probe, keys);
-  let sourceKey = p.sourceKey;
-  if (!sourceKey) {
-    failures.push(
-      p.answered > 0 ? `${META_PATH}#X-HCM-Extension-Source` : `${META_PATH}#no-meta-answered`
-    );
-    sourceKey = "unknown";
-  }
-  const hashLines = models.map((m) => `${m.modelKey ?? ""}|${m.type ?? ""}`).sort();
-  const modelHash = sha2562(hashLines.join("\n"));
-  const rows = await fetchManifestRows(probe, failures);
-  const versionOut = await probe.get(VERSION_PATH);
-  let backendVersion;
-  if (versionOut.error === "ok" && versionOut.body !== null && versionOut.body !== void 0) {
-    backendVersion = versionOut.body;
-  } else {
-    failures.push(VERSION_PATH);
-    backendVersion = { version: "unavailable" };
-  }
-  return {
-    tenantMetaManifestDigest: manifestDigest(rows),
-    manifestEntryCount: rows.length,
-    extensionSource: sourceKey,
-    // 🔴 记下**是从哪个模型探到的**：让「这个值是谁给的」在产物里留痕。
-    extensionSourceProbe: p.probeModelKey,
-    // 🔴 没有这两个数，`extensionSource: "unknown"` 就是一个**不可追问的结论**。
-    extensionSourceProbeAttempted: p.attempted,
-    extensionSourceProbeAnswered: p.answered,
-    modelListHash: modelHash,
-    modelCount: models.length,
-    backendVersion,
-    capabilities: probe.capabilities,
-    createdAt: `${now().toISOString().slice(0, 19)}Z`,
-    ttlDays,
-    coverageNotes: {
-      gateComponents: [...GATE_COMPONENTS],
-      blindSpots: BLIND_SPOTS,
-      // 空数组 = 三个端点都真取到了；非空 = 这份四元组是**残的**，
-      // 上面那些 0 和空摘要不代表环境真的空。
-      fetchFailures: failures
-    }
-  };
-}
-function compareFingerprint(recorded, current) {
-  const diffs = GATE_COMPONENTS.filter((c) => recorded[c] !== current[c]);
-  if (recorded.capabilities !== current.capabilities) diffs.push("capabilities");
-  for (const [fp, tag] of [
-    [recorded, "recorded"],
-    [current, "current"]
-  ]) {
-    const notes = fp.coverageNotes;
-    if (!isPlainObject2(notes) || !("fetchFailures" in notes)) {
-      diffs.push(`incomplete:${tag}:coverageNotes-missing`);
-      continue;
-    }
-    const raw = notes.fetchFailures;
-    const list = Array.isArray(raw) ? raw : [];
-    const gateFailures = [...new Set(list.map(String))].filter((x) => GATE_SOURCES.some((s) => x.startsWith(s))).sort();
-    for (const f of gateFailures) diffs.push(`incomplete:${tag}:${f}`);
-  }
-  return diffs;
-}
-function sha2562(s) {
-  return createHash3("sha256").update(s, "utf8").digest("hex");
-}
-function isPlainObject2(v) {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
 // src/fde/doctor.ts
 var DOCTOR_ANCHORS = [
   "connectivity",
@@ -9275,6 +9299,7 @@ export {
   isServerSlidingSession,
   listEnvs,
   listIdentities,
+  listModels,
   listProfiles,
   listTenantMeta,
   listWorkspaceFiles,