@zhuoyuezs/ml-platform 0.1.1 → 0.1.3

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 };

package/skills/feature-management/SKILL.md

@@ -24,7 +24,10 @@ Treat `Recipe` and public `Feature.compute` as removed. Treat `computation_hash`
 
 ## Initialize The Client
 
-Use the `ml-platform` executable on `PATH` for every platform command. The formal distribution contract requires the npm release to install the CLI and this Skill together; that packaging stage is not implemented yet. The Skill does not contain a second CLI runtime, launcher, or installer. During repository development, provide the current JavaScript CLI through an isolated test `PATH`.
+Use the `ml-platform` executable on `PATH` for every platform command. The formal npm release installs
+the CLI and this pure Skill together. The Skill does not contain a second CLI runtime, launcher, or
+installer. During repository development, provide the current JavaScript CLI through an isolated test
+`PATH`.
 
 Before any platform operation, verify the executable and its version:
 
@@ -36,17 +39,19 @@ ml-platform version
 If the executable is missing or cannot start, stop and report that the ML Platform release installation is incomplete. Do not download a client, search for a repository checkout, or fall back to another executable.
 
 Before any server-profile discovery, dry-run, publication, build, or artifact
-operation, configure the deployed API URL exactly as follows:
+operation, inspect the effective API configuration:
 
 ```bash
-ml-platform configure --api-url http://10.36.9.212:30620
+ml-platform show-config
 ml-platform --profile server health
 ```
 
-Use `http://10.36.9.212:30620` when operating against the current deployed
-environment. Placeholder host and port values elsewhere in the references are
-generic templates, not this environment's configured target. The API is
-unauthenticated, so access it only from the approved internal network.
+The effective API target is resolved in this order: explicit `--api-url`,
+`ML_PLATFORM_API_URL`, then the saved value written by `ml-platform configure`.
+If no target is configured, ask the user for an approved API URL before making
+server requests. Do not hardcode an environment-specific address in a Skill,
+catalog, or prompt. Keep database, MinIO, and source credentials out of commands;
+use the server's managed Secrets.
 
 Install and upgrade the CLI and Skill only through the explicit commands provided by `@zhuoyuezs/ml-platform`. Restart the Agent session after a successful Skill upgrade so the definition is reloaded. Never copy files over an installed Skill directory manually.
 
@@ -76,6 +81,30 @@ Check the selected profile and list existing Parameter, Operator, Feature, Featu
 
 Create a new version when source semantics, formula code, config meaning, inputs, output dtype, time behavior, quality rules, or column order change. Never overwrite an immutable version or use suffixes such as `new`, `final`, or `test2`.
 
+### Operate An Existing Registered Dataset
+
+For diagnosis, resolve, build, Job lookup, and artifact lookup of an already
+registered DatasetManifest, use the API through `ml-platform`. Do not search the
+platform source checkout or a local Catalog directory for a matching JSON file.
+
+1. Run `show-config` and `health` to record the effective API source.
+2. Run `list-projects`, then `list-datasets --project <project>` to discover
+   candidates from the Registry.
+3. Ask the user to confirm the exact `project`, `dataset_id`, and
+   `dataset_version` when more than one valid candidate exists. Never infer a
+   target from a similar local filename.
+4. Run `get-dataset <dataset_id> <dataset_version> --project <project>` and
+   inspect the returned registered contract.
+5. Run `resolve-dataset` for a read-only dependency and manifest-hash check.
+6. Submit exactly one `build-registered-dataset ... --wait` only after the user
+   authorizes that exact registered version.
+7. Use the returned Job ID with `get-job`, then use the returned manifest hash
+   with `get-dataset-artifact` after success.
+
+Local `resolve-manifest` and `build-dataset <file>` remain authoring tools for a
+new or changed Catalog contract before it is registered. They are not required
+for operating an existing Registry version.
+
 ## Upgrade Dependency Chains
 
 Treat a version change as a release of its affected reverse-dependency closure, not as an isolated asset bump.
@@ -235,7 +264,7 @@ Require all of the following before reporting success:
   windows tiling the fetch range, and any retries are accounted for;
 - missing values and warnings are reported, not silently repaired.
 
-The manifest hash returned by `resolve-manifest` is the artifact key: it stays
+The manifest hash returned by `resolve-manifest` or `resolve-dataset` is the artifact key: it stays
 the same after the build, so it is usable for cache reuse and polling before
 submission. Distinguish the two lookup failures rather than treating both as "not
 ready" — `422` with `invalid_artifact_key` means the key can never name an

package/skills/feature-management/references/commands.md

@@ -31,10 +31,11 @@ ml-platform --profile server show-config
 ml-platform --profile server health
 ```
 
-The API URL for this environment is fixed at `http://10.36.9.212:30620`.
-Configure it before all discovery, dry-run, publication, build, and artifact
-commands. The address in the command block is a reusable placeholder; replace
-it with the fixed URL above for this deployment.
+The URL is environment-specific and must be supplied by the user, an approved
+`ML_PLATFORM_API_URL`, or the saved value from `ml-platform configure`. Do not
+hardcode an internal address in this Skill or in a catalog. `show-config` displays
+the effective target before discovery, dry-run, publication, build, or artifact
+commands.
 
 Do not place database, MinIO, or source credentials in commands when the server profile can use managed Secrets.
 
@@ -154,6 +155,38 @@ The cross-store publication is not transactional. If an error occurs, report the
 
 ## Resolve And Build A Dataset
 
+For an existing registered DatasetManifest, use the Registry identity only; no
+local Catalog or Manifest path is needed:
+
+```bash
+ml-platform --profile server list-projects
+ml-platform --profile server list-datasets --project <project>
+ml-platform --profile server \
+  get-dataset <dataset_id> <dataset_version> --project <project>
+ml-platform --profile server \
+  resolve-dataset <dataset_id> <dataset_version> --project <project>
+```
+
+After the user confirms the exact triple and authorizes one build:
+
+```bash
+ml-platform --profile server \
+  build-registered-dataset <dataset_id> <dataset_version> \
+  --project <project> \
+  --partition-duration 1d \
+  --max-parallelism 1 \
+  --wait
+```
+
+The command first fetches that immutable DatasetManifest from the API and sends
+the validated response to the resolve/build endpoint. It never searches the
+current repository for a similarly named file. Record the API source,
+`project/dataset_id:dataset_version`, manifest hash, Job ID, terminal status,
+and artifact reference.
+
+When authoring a new or changed contract that has not been registered yet, use
+the local-file commands below.
+
 Resolve without fetching source data:
 
 ```bash