@zhuoyuezs/ml-platform 0.1.1 → 0.1.4

package/runtime/business-client/src/http.js

@@ -45,6 +45,7 @@ class PlatformApiClient {
 
   get(endpoint, params) { return this.request("GET", endpoint, { params }); }
   post(endpoint, payload, params) { return this.request("POST", endpoint, { payload, params }); }
+  put(endpoint, payload, params) { return this.request("PUT", endpoint, { payload, params }); }
   delete(endpoint, params) { return this.request("DELETE", endpoint, { params }); }
   uploadOperatorPackage(project, name, version, packagePath) {
     const resolved = path.resolve(expandHome(packagePath));
@@ -63,33 +64,95 @@ class PlatformApiClient {
     fs.mkdirSync(target, { recursive: true });
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    const temporaryDir = fs.mkdtempSync(path.join(os.tmpdir(), "data-platform-artifact-download-"));
+    const temporary = path.join(temporaryDir, "artifact.zip");
     let response;
     try {
       response = await fetch(this.url(`/dataset-artifacts/${encodeURIComponent(project)}/${encodeURIComponent(datasetId)}/${encodeURIComponent(manifestHash)}/download`), { headers: { Accept: "application/zip" }, signal: controller.signal });
-    } catch (error) {
-      throw new Error(`artifact download failed: ${error.message}`);
-    } finally {
-      clearTimeout(timer);
-    }
-    if (!response.ok) {
-      let detail = response.statusText;
-      try { detail = JSON.parse(await response.text())?.detail ?? detail; } catch (_) { /* use status text */ }
-      throw new Error(`artifact download failed: HTTP ${response.status}: ${detail}`);
-    }
-    const temporary = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "data-platform-artifact-download-")), "artifact.zip");
-    try {
-      fs.writeFileSync(temporary, Buffer.from(await response.arrayBuffer()));
+      if (!response.ok) {
+        let detail = response.statusText;
+        try { detail = JSON.parse(await abortable(response.text(), controller.signal))?.detail ?? detail; } catch (_) { /* use status text */ }
+        throw new Error(`artifact download failed: HTTP ${response.status}: ${detail}`);
+      }
+      const total = contentLength(response);
+      let lastReported = -1;
+      const report = (received, complete = false) => {
+        if ((complete && received !== lastReported) || received === 0 || received - lastReported >= 1024 * 1024) {
+          reportDownloadProgress(received, total);
+          lastReported = received;
+        }
+      };
+      report(0);
+      await writeResponseBody(response, temporary, controller.signal, report);
       const files = await extractArchive(temporary, target);
       return { dataset_id: datasetId, manifest_hash: manifestHash, output_dir: target, file_count: files.length, files };
     } catch (error) {
       fs.rmSync(target, { recursive: true, force: true });
-      throw error;
+      if (error instanceof Error && error.message.startsWith("artifact download failed:")) throw error;
+      throw new Error(`artifact download failed: ${error.message}`);
     } finally {
-      fs.rmSync(path.dirname(temporary), { recursive: true, force: true });
+      clearTimeout(timer);
+      fs.rmSync(temporaryDir, { recursive: true, force: true });
     }
   }
 }
 
+function contentLength(response) {
+  const raw = response.headers?.get?.("content-length") ?? response.headers?.["content-length"];
+  const value = Number(raw);
+  return Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+function reportDownloadProgress(received, total) {
+  const suffix = total == null ? "" : `/${total}`;
+  process.stderr.write(`artifact download: received ${received}${suffix} bytes\n`);
+}
+
+function abortable(value, signal) {
+  if (signal.aborted) return Promise.reject(new Error("This operation was aborted"));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => { cleanup(); reject(new Error("This operation was aborted")); };
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    signal.addEventListener("abort", onAbort, { once: true });
+    Promise.resolve(value).then((result) => { cleanup(); resolve(result); }, (error) => { cleanup(); reject(error); });
+  });
+}
+
+async function writeResponseBody(response, outputPath, signal, onProgress) {
+  const handle = fs.openSync(outputPath, "w");
+  let received = 0;
+  try {
+    const write = (value) => {
+      const chunk = Buffer.from(value);
+      fs.writeSync(handle, chunk);
+      received += chunk.length;
+      onProgress(received);
+    };
+    if (response.body?.getReader) {
+      const reader = response.body.getReader();
+      while (true) {
+        const item = await abortable(reader.read(), signal);
+        if (item.done) break;
+        write(item.value);
+      }
+    } else if (response.body?.[Symbol.asyncIterator]) {
+      const iterator = response.body[Symbol.asyncIterator]();
+      while (true) {
+        const item = await abortable(iterator.next(), signal);
+        if (item.done) break;
+        write(item.value);
+      }
+    } else if (typeof response.arrayBuffer === "function") {
+      write(await abortable(response.arrayBuffer(), signal));
+    } else {
+      throw new Error("artifact download response has no readable body");
+    }
+    onProgress(received, true);
+  } finally {
+    fs.closeSync(handle);
+  }
+}
+
 async function extractArchive(archivePath, outputDir) {
   const archive = fs.readFileSync(archivePath);
   const end = findEndOfCentralDirectory(archive);
@@ -111,8 +174,8 @@ async function extractArchive(archivePath, outputDir) {
     if (next > archive.length || compressedSize === 0xffffffff || size === 0xffffffff || localOffset === 0xffffffff) throw new Error("artifact archive entry metadata is invalid");
     if (flags & 1) throw new Error("artifact archive contains an encrypted entry");
     if (![0, 8].includes(method)) throw new Error(`artifact archive compression method is unsupported: ${method}`);
-    if (!(flags & 0x800)) throw new Error("artifact archive contains a non-UTF-8 filename");
-    const rawName = archive.subarray(cursor + 46, cursor + 46 + nameLength).toString("utf8");
+    const rawNameBytes = archive.subarray(cursor + 46, cursor + 46 + nameLength);
+    const rawName = decodeZipFilename(rawNameBytes, flags);
     const name = rawName.replace(/\\/g, "/"); const parts = name.split("/"); const mode = (attributes >>> 16) & 0xffff;
     if (!name || name.startsWith("/") || /^[A-Za-z]:/.test(name) || parts.includes("..")) throw new Error(`artifact archive contains unsafe path: ${JSON.stringify(rawName)}`);
     if ((mode & 0o170000) === 0o120000) throw new Error(`artifact archive contains a symbolic link: ${JSON.stringify(rawName)}`);
@@ -131,6 +194,14 @@ async function extractArchive(archivePath, outputDir) {
   return files.sort();
 }
 
+function decodeZipFilename(bytes, flags) {
+  if (flags & 0x800) return bytes.toString("utf8");
+  // ZIP producers commonly omit the UTF-8 flag for ASCII entry names. Keep
+  // those names interoperable while refusing ambiguous non-ASCII encodings.
+  if (bytes.some((value) => value > 0x7f)) throw new Error("artifact archive contains an unsupported non-UTF-8 filename");
+  return bytes.toString("ascii");
+}
+
 function findEndOfCentralDirectory(archive) { const minimum = Math.max(0, archive.length - 65557); for (let offset = archive.length - 22; offset >= minimum; offset -= 1) if (archive.readUInt32LE(offset) === 0x06054b50 && offset + 22 + archive.readUInt16LE(offset + 20) === archive.length) return offset; throw new Error("artifact download is not a valid zip archive"); }
 function crc32(buffer) { let crc = 0xffffffff; for (const byte of buffer) { crc ^= byte; for (let bit = 0; bit < 8; bit += 1) crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1)); } return (crc ^ 0xffffffff) >>> 0; }
 

package/scripts/lib.js

@@ -25,6 +25,12 @@ if (RELEASE_POLICY.schema_version !== "data_platform.ml_platform_release_policy/
 const FORBIDDEN_DIRECTORIES = new Set(RELEASE_POLICY.forbidden_directories);
 const FORBIDDEN_FILES = new Set(RELEASE_POLICY.forbidden_files);
 const FORBIDDEN_SUFFIXES = new Set(RELEASE_POLICY.forbidden_suffixes);
+const FORBIDDEN_CONTENT_PATTERNS = (RELEASE_POLICY.forbidden_content_patterns || []).map((item) => {
+  if (!item || typeof item.name !== "string" || typeof item.pattern !== "string") {
+    throw new Error("release policy 包含无效内容规则");
+  }
+  return { name: item.name, pattern: new RegExp(item.pattern, "i") };
+});
 
 function parseOptions(args) {
   const options = {
@@ -34,7 +40,9 @@ function parseOptions(args) {
     allowDowngrade: false,
     prewarm: true,
     backupUnmanaged: false,
+    summary: true,
   };
+  let outputFlag = null;
   const valueFlags = new Map([
     ["--agent", "agent"],
     ["--scope", "scope"],
@@ -59,6 +67,14 @@ function parseOptions(args) {
       options.prewarm = false;
     } else if (arg === "--backup-unmanaged") {
       options.backupUnmanaged = true;
+    } else if (arg === "--summary") {
+      if (outputFlag === "json") throw new Error("--summary 与 --json 不能同时使用");
+      outputFlag = "summary";
+      options.summary = true;
+    } else if (arg === "--json") {
+      if (outputFlag === "summary") throw new Error("--summary 与 --json 不能同时使用");
+      outputFlag = "json";
+      options.summary = false;
     } else {
       throw new Error(`未知参数: ${arg}`);
     }
@@ -130,6 +146,12 @@ function loadRelease(packageRoot = PACKAGE_ROOT) {
     throw new Error("release policy 摘要与 release manifest 不匹配");
   }
   if (!isSemver(release.release_version)) throw new Error("release_version 不是有效 SemVer");
+  const requirements = release.runtime_requirements;
+  if (!requirements || requirements.node !== ">=18"
+      || !Array.isArray(requirements.os)
+      || requirements.os.join(",") !== "darwin,linux") {
+    throw new Error("release manifest 缺少有效 runtime requirements");
+  }
   const skill = release.skills && release.skills[SKILL_NAME];
   if (!skill || skill.path !== `skills/${SKILL_NAME}` || !isSha256(skill.sha256)
       || !isSemver(skill.revision) || typeof skill.requires_cli !== "string") {
@@ -186,6 +208,13 @@ function verifyPackage(packageRoot = PACKAGE_ROOT) {
   assertAllowedClient(clientRoot);
   rejectForbiddenTree(skillRoot, "Skill");
   rejectForbiddenTree(clientRoot, "business client");
+  rejectForbiddenContent([
+    ...listFiles(skillRoot),
+    ...listFiles(clientRoot),
+    ...["README.md", "DEVELOPMENT.md"]
+      .map((name) => path.join(packageRoot, name))
+      .filter((file) => fs.existsSync(file)),
+  ], "release payload");
   if (fs.existsSync(path.join(skillRoot, "runtime")) || fs.existsSync(path.join(skillRoot, "scripts"))) {
     throw new Error("Skill 不得包含 CLI runtime 或 wrapper");
   }
@@ -326,11 +355,31 @@ function doctor(options = {}, packageRoot = PACKAGE_ROOT) {
     actual: matchingShim ?? pathMatches[0] ?? null,
     remediation: pathOk ? null : `将 ${paths.binDir} 加入 PATH，然后重启 Agent 会话`,
   });
-  if (options.apiUrl) {
-    const apiHealth = runApiHealth(paths.dispatcher, options.apiUrl);
-    checks.push({ name: "platform_api", ok: apiHealth.ok, detail: apiHealth.detail });
+  const apiTarget = resolveEffectiveApiTarget(options, paths.dispatcher);
+  if (apiTarget.error) {
+    checks.push({
+      name: "platform_api",
+      ok: false,
+      source: apiTarget.source,
+      detail: apiTarget.error,
+    });
+  } else if (apiTarget.apiUrl) {
+    const apiHealth = runApiHealth(paths.dispatcher, apiTarget.apiUrl);
+    checks.push({
+      name: "platform_api",
+      ok: apiHealth.ok,
+      source: apiTarget.source,
+      api_url: apiTarget.apiUrl,
+      detail: apiHealth.detail,
+    });
   } else {
-    checks.push({ name: "platform_api", ok: null, skipped: true, reason: "未提供 --api-url" });
+    checks.push({
+      name: "platform_api",
+      ok: null,
+      skipped: true,
+      source: null,
+      reason: "未通过 --api-url、ML_PLATFORM_API_URL 或 configure 配置 API 地址",
+    });
   }
   return {
     ok: checks.every((check) => check.ok !== false),
@@ -693,6 +742,38 @@ function runApiHealth(dispatcher, apiUrl) {
   return runCliRuntime(dispatcher, ["--api-url", apiUrl.replace(/\/+$/, ""), "health"], false);
 }
 
+function resolveEffectiveApiTarget(
+  options,
+  dispatcher,
+  env = process.env,
+  runtime = runCliRuntime,
+) {
+  if (options.apiUrl && String(options.apiUrl).trim()) {
+    return { apiUrl: String(options.apiUrl).trim(), source: "argument" };
+  }
+  if (env.ML_PLATFORM_API_URL && String(env.ML_PLATFORM_API_URL).trim()) {
+    return { apiUrl: String(env.ML_PLATFORM_API_URL).trim(), source: "environment" };
+  }
+  const configured = runtime(dispatcher, ["show-config"], false);
+  if (!configured.ok) {
+    return {
+      apiUrl: null,
+      source: "saved_config",
+      error: `无法读取已保存的 API 配置: ${configured.detail || "未知错误"}`,
+    };
+  }
+  let payload;
+  try {
+    payload = JSON.parse(configured.detail);
+  } catch (_) {
+    return { apiUrl: null, source: "saved_config", error: "show-config 未返回有效 JSON" };
+  }
+  const apiUrl = payload && payload.effective && payload.effective.api_url;
+  return apiUrl
+    ? { apiUrl: String(apiUrl).trim(), source: "saved_config" }
+    : { apiUrl: null, source: null };
+}
+
 function checkTree(checks, name, root, expected) {
   if (!expected || !fs.existsSync(root)) {
     checks.push({ name, ok: false, error: `缺少安装目录或预期摘要: ${root}` });
@@ -796,6 +877,18 @@ function rejectForbiddenTree(root, label) {
   visit(root);
 }
 
+function rejectForbiddenContent(files, label) {
+  for (const file of files) {
+    if (!fs.statSync(file).isFile() || path.basename(file) === "release-policy.json") continue;
+    const text = fs.readFileSync(file, "utf8");
+    for (const rule of FORBIDDEN_CONTENT_PATTERNS) {
+      if (rule.pattern.test(text)) {
+        throw new Error(`${label} 包含禁止发布内容 ${rule.name}: ${file}`);
+      }
+    }
+  }
+}
+
 function treeDigest(root) {
   const files = listFiles(root);
   const hash = crypto.createHash("sha256");
@@ -990,6 +1083,7 @@ module.exports = {
   loadRelease,
   migrate,
   parseOptions,
+  resolveEffectiveApiTarget,
   resolveInstallPaths,
   sha256File,
   status,

package/scripts/main.js

@@ -17,13 +17,29 @@ const BUSINESS_ENTRY = path.resolve(__dirname, "..", "runtime", "business-client
 
 function usage() {
   return `用法:
-  ml-platform install [--agent codex|pi|custom] [--scope user|project] [--skills-dir PATH] [--project-dir PATH] [--state-dir PATH] [--bin-dir PATH] [--upgrade] [--allow-downgrade] [--backup-unmanaged]
-  ml-platform upgrade [install options]
-  ml-platform migrate [--agent codex|pi|custom] [--scope user|project] [--skills-dir PATH] [--project-dir PATH]
-  ml-platform status  [--agent codex|pi|custom] [--scope user|project] [--skills-dir PATH] [--project-dir PATH] [--state-dir PATH] [--bin-dir PATH]
-  ml-platform doctor  [status options] [--api-url URL]
+  ml-platform install [--scope user|project] [--json]
+  ml-platform upgrade [--scope user|project] [--json]
+  ml-platform migrate [--scope user|project] [--json]
+  ml-platform status  [--scope user|project] [--json]
+  ml-platform doctor  [--scope user|project] [--api-url URL] [--json]
   ml-platform <business-command> [args]
 
+默认安装:
+  Codex 用户级 Skill，持久 CLI，简洁输出
+
+项目级安装:
+  ml-platform install --scope project
+
+常用选项:
+  --scope user|project   Skill 安装范围，默认 user
+  --project-dir PATH     项目根目录，project scope 默认使用当前目录
+  --json                 输出供 Agent 和 CI 解析的 JSON
+  --backup-unmanaged     备份目标位置已有的非托管 Skill
+
+高级选项:
+  --agent codex|pi|custom, --skills-dir PATH, --state-dir PATH, --bin-dir PATH,
+  --allow-downgrade, --no-prewarm, --upgrade, --summary
+
 安装管理命令:
   install, upgrade, migrate, status, doctor
 
@@ -31,10 +47,70 @@ function usage() {
 `;
 }
 
+function managementUsage(command) {
+  const signatures = {
+    install: "install [--scope user|project] [--project-dir PATH] [--json]",
+    upgrade: "upgrade [--scope user|project] [--project-dir PATH] [--json]",
+    migrate: "migrate [--scope user|project] [--project-dir PATH] [--json]",
+    status: "status [--scope user|project] [--project-dir PATH] [--json]",
+    doctor: "doctor [--scope user|project] [--project-dir PATH] [--api-url URL] [--json]",
+  };
+  return `用法: ml-platform ${signatures[command]}\n`;
+}
+
 function printJson(payload) {
   process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
 }
 
+function formatSummary(command, payload) {
+  if (command === "status") {
+    const lines = [`ML Platform: ${payload.installed ? "已安装" : "未安装"}`];
+    if (payload.installed_release) lines.push(`Release: ${payload.installed_release}`);
+    if (payload.cli?.version) lines.push(`CLI: ${payload.cli.version} (${payload.cli.path})`);
+    if (payload.skill?.revision) lines.push(`Skill: ${payload.skill.name}@${payload.skill.revision} (${payload.skill.path})`);
+    if (payload.record_error) lines.push(`错误: ${payload.record_error}`);
+    return `${lines.join("\n")}\n`;
+  }
+  if (command === "doctor") {
+    if (!Array.isArray(payload.checks)) {
+      return `ML Platform 检查失败: ${payload.error || "未知错误"}\n`;
+    }
+    const failed = payload.checks.filter((check) => check.ok === false);
+    const passed = payload.checks.filter((check) => check.ok === true);
+    const skipped = payload.checks.filter((check) => check.skipped);
+    const lines = [
+      `ML Platform 检查: ${payload.ok ? "通过" : "失败"}`,
+      `Release: ${payload.release_version || "未知"}  CLI: ${payload.cli_version || "未知"}`,
+      `检查项: ${passed.length} 通过, ${failed.length} 失败, ${skipped.length} 跳过`,
+    ];
+    const api = payload.checks.find((check) => check.name === "platform_api");
+    if (api?.api_url) lines.push(`API: ${api.api_url} (${api.source})`);
+    else if (api?.skipped) lines.push(`API: 未配置 (${api.reason})`);
+    for (const check of failed) lines.push(`失败: ${check.name} - ${check.error || check.detail || "检查未通过"}`);
+    return `${lines.join("\n")}\n`;
+  }
+  const actionLabels = {
+    installed: "安装完成",
+    upgraded: "升级完成",
+    unchanged: "已是当前版本",
+    migrated: "迁移完成",
+  };
+  const lines = [
+    `ML Platform: ${actionLabels[payload.action] || payload.action || (payload.ok ? "完成" : "失败")}`,
+  ];
+  if (payload.release_version) lines.push(`Release: ${payload.release_version}  CLI: ${payload.cli_version}`);
+  if (payload.cli_shim) lines.push(`命令: ${payload.cli_shim}`);
+  if (payload.skill_root) lines.push(`Skill: ${payload.skill_root}`);
+  if (payload.path_ready === false && payload.path_setup) lines.push(`PATH: ${payload.path_setup}`);
+  if (payload.restart_agent_session) lines.push("请重启 Agent 会话以加载最新 Skill。");
+  return `${lines.join("\n")}\n`;
+}
+
+function printResult(command, payload, summary) {
+  if (summary) process.stdout.write(formatSummary(command, payload));
+  else printJson(payload);
+}
+
 function loadBusinessCommands() {
   try {
     const { BUSINESS_COMMANDS } = require(BUSINESS_ENTRY);
@@ -66,24 +142,29 @@ function main(argv) {
   }
   if (!MANAGEMENT_COMMANDS.has(command)) return dispatchBusiness(argv);
 
+  if (rest.includes("--help") || rest.includes("-h")) {
+    process.stdout.write(managementUsage(command));
+    return 0;
+  }
+
   const options = parseOptions(rest);
   if (command === "install" || command === "upgrade") {
     if (command === "upgrade") options.upgrade = true;
-    printJson(install(options));
+    printResult(command, install(options), options.summary);
     return 0;
   }
   if (command === "migrate") {
     const result = migrate(options);
-    printJson(result);
+    printResult(command, result, options.summary);
     return result.ok ? 0 : 1;
   }
   if (command === "status") {
     const result = status(options);
-    printJson(result);
+    printResult(command, result, options.summary);
     return result.ok ? 0 : 1;
   }
   const result = doctor(options);
-  printJson(result);
+  printResult(command, result, options.summary);
   return result.ok ? 0 : 1;
 }
 
@@ -91,9 +172,13 @@ if (require.main === module) {
   try {
     process.exitCode = main(process.argv.slice(2));
   } catch (error) {
-    process.stderr.write(`${JSON.stringify({ ok: false, error: error.message }, null, 2)}\n`);
+    if (process.argv.slice(2).includes("--json")) {
+      process.stderr.write(`${JSON.stringify({ ok: false, error: error.message }, null, 2)}\n`);
+    } else {
+      process.stderr.write(`ML Platform: 失败\n错误: ${error.message}\n`);
+    }
     process.exitCode = 2;
   }
 }
 
-module.exports = { BUSINESS_ENTRY, MANAGEMENT_COMMANDS, dispatchBusiness, main, usage };
+module.exports = { BUSINESS_ENTRY, MANAGEMENT_COMMANDS, dispatchBusiness, formatSummary, main, managementUsage, usage };