@kevlns/v-cli 0.1.1-beta.1 → 0.2.0-beta.1

package/dist/cli.mjs

@@ -75,31 +75,665 @@ function defaultHomeDir() {
 }
 
 // src/core/loader.ts
-import fs3 from "fs";
-import path4 from "path";
+import fs4 from "fs";
+import path5 from "path";
 import { pathToFileURL } from "url";
 
+// src/core/official.ts
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+import path3 from "path";
+import fs2 from "fs";
+
+// src/core/manifest.ts
+var RESERVED_MANIFEST_COMMAND_NAMES = ["doctor", "plugin", "ts", "agent", "help"];
+var KNOWN_PLATFORMS = ["darwin", "linux", "win32"];
+var OUTPUT_FORMATS = ["json", "stdout", "text"];
+var COMMAND_NAME_RE = /^[a-z][a-z0-9-]*$/;
+var PACKAGE_NAME_RE = /^@[a-zA-Z0-9][a-zA-Z0-9._~-]*\/[a-zA-Z0-9][a-zA-Z0-9._~-]*$/;
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function validateManifest(input) {
+  if (!isPlainObject(input)) {
+    return { ok: false, errors: ["\u6E05\u5355\u5FC5\u987B\u662F JSON \u5BF9\u8C61"] };
+  }
+  const errors = [];
+  const m = input;
+  if (typeof m.schemaVersion !== "number" || !Number.isInteger(m.schemaVersion)) {
+    errors.push("schemaVersion \u5FC5\u987B\u662F\u6574\u6570");
+  } else if (m.schemaVersion === 1) {
+  } else if (m.schemaVersion >= 2) {
+    errors.push(
+      `schemaVersion ${m.schemaVersion} \u4E0D\u53D7\u652F\u6301\uFF1Av-cli 0.2 \u4EC5\u652F\u6301\u5951\u7EA6\u7248\u672C 1 \u7684\u6E05\u5355\uFF0C\u8BF7\u5347\u7EA7\u63D2\u4EF6\u6216 v-cli`
+    );
+  } else {
+    errors.push("schemaVersion \u5FC5\u987B\u4E3A 1");
+  }
+  const requireString = (key) => {
+    const v = m[key];
+    if (typeof v !== "string" || v.length === 0) {
+      errors.push(`${key} \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+      return void 0;
+    }
+    return v;
+  };
+  const packageName = requireString("package");
+  if (typeof packageName === "string" && !PACKAGE_NAME_RE.test(packageName)) {
+    errors.push("package \u5FC5\u987B\u662F @scope/name \u5F62\u5F0F\u7684 npm \u5305\u540D");
+  }
+  const command = requireString("command");
+  if (typeof command === "string") {
+    if (!COMMAND_NAME_RE.test(command)) {
+      errors.push(`command "${command}" \u4E0D\u5408\u6CD5\uFF1A\u53EA\u80FD\u662F\u5C0F\u5199\u5B57\u6BCD\u5F00\u5934\u7684 [a-z0-9-] \u5B57\u7B26\u4E32`);
+    }
+    if (RESERVED_MANIFEST_COMMAND_NAMES.includes(command)) {
+      errors.push(
+        `command "${command}" \u662F v-cli \u4FDD\u7559\u547D\u4EE4\u540D\uFF08${RESERVED_MANIFEST_COMMAND_NAMES.join("/")}\uFF09\uFF0C\u63D2\u4EF6\u4E0D\u80FD\u5360\u7528`
+      );
+    }
+  }
+  requireString("bin");
+  requireString("description");
+  if (!Array.isArray(m.platforms)) {
+    errors.push("platforms \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4");
+  } else if (m.platforms.length === 0) {
+    errors.push("platforms \u81F3\u5C11\u8981\u58F0\u660E\u4E00\u4E2A\u5E73\u53F0");
+  } else if (!isStringArray(m.platforms)) {
+    errors.push("platforms \u7684\u5143\u7D20\u5FC5\u987B\u662F\u5B57\u7B26\u4E32");
+  } else {
+    const unknown = m.platforms.filter((p) => !KNOWN_PLATFORMS.includes(p));
+    if (unknown.length > 0) {
+      errors.push(`platforms \u542B\u672A\u77E5\u5E73\u53F0: ${unknown.join(", ")}\uFF08\u4EC5\u652F\u6301 ${KNOWN_PLATFORMS.join("/")}\uFF09`);
+    }
+  }
+  if (!isPlainObject(m.runtime)) {
+    errors.push("runtime \u5FC5\u987B\u662F\u5BF9\u8C61");
+  }
+  if (!Array.isArray(m.environment)) {
+    errors.push("environment \u5FC5\u987B\u662F\u6570\u7EC4");
+  } else {
+    m.environment.forEach((entry, i) => {
+      if (!isPlainObject(entry)) {
+        errors.push(`environment[${i}] \u5FC5\u987B\u662F\u5BF9\u8C61`);
+      } else {
+        if (typeof entry.name !== "string" || entry.name.length === 0) {
+          errors.push(`environment[${i}].name \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+        }
+        if (typeof entry.description !== "string" || entry.description.length === 0) {
+          errors.push(`environment[${i}].description \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+        }
+      }
+    });
+  }
+  const agent2 = m.agent;
+  if (!isPlainObject(agent2)) {
+    errors.push("agent \u5FC5\u987B\u662F\u5BF9\u8C61");
+  } else {
+    if (typeof agent2.whenToUse !== "string") {
+      errors.push("agent.whenToUse \u5FC5\u987B\u662F\u5B57\u7B26\u4E32");
+    }
+    if (!Array.isArray(agent2.globalOptions)) {
+      errors.push("agent.globalOptions \u5FC5\u987B\u662F\u6570\u7EC4");
+    } else {
+      agent2.globalOptions.forEach((o, i) => {
+        if (!isPlainObject(o)) {
+          errors.push(`agent.globalOptions[${i}] \u5FC5\u987B\u662F\u5BF9\u8C61`);
+        } else {
+          if (typeof o.flags !== "string" || o.flags.length === 0) {
+            errors.push(`agent.globalOptions[${i}].flags \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+          }
+          if (typeof o.description !== "string" || o.description.length === 0) {
+            errors.push(`agent.globalOptions[${i}].description \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+          }
+        }
+      });
+    }
+    if (!Array.isArray(agent2.commands)) {
+      errors.push("agent.commands \u5FC5\u987B\u662F\u6570\u7EC4");
+    } else {
+      const seenPaths = /* @__PURE__ */ new Set();
+      agent2.commands.forEach((c, i) => {
+        const at = `agent.commands[${i}]`;
+        if (!isPlainObject(c)) {
+          errors.push(`${at} \u5FC5\u987B\u662F\u5BF9\u8C61`);
+          return;
+        }
+        if (!Array.isArray(c.path) || !isStringArray(c.path) || c.path.length === 0) {
+          errors.push(`${at}.path \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32\u6570\u7EC4`);
+        } else {
+          const badSegment = c.path.find((seg) => !COMMAND_NAME_RE.test(seg));
+          if (badSegment !== void 0) {
+            errors.push(`${at}.path \u542B\u975E\u6CD5\u6BB5 "${badSegment}"\uFF08\u6BCF\u6BB5\u987B\u5339\u914D ^[a-z][a-z0-9-]*$\uFF09`);
+          }
+          const key = c.path.join(" ");
+          if (seenPaths.has(key)) {
+            errors.push(`${at}.path ${key} \u4E0E\u524D\u9762\u7684\u547D\u4EE4\u91CD\u590D`);
+          }
+          seenPaths.add(key);
+        }
+        if (typeof c.usage !== "string" || c.usage.length === 0) {
+          errors.push(`${at}.usage \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+        }
+        if (typeof c.description !== "string" || c.description.length === 0) {
+          errors.push(`${at}.description \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+        }
+        if (!Array.isArray(c.arguments)) {
+          errors.push(`${at}.arguments \u5FC5\u987B\u662F\u6570\u7EC4`);
+        } else {
+          c.arguments.forEach((a, j) => {
+            if (!isPlainObject(a)) {
+              errors.push(`${at}.arguments[${j}] \u5FC5\u987B\u662F\u5BF9\u8C61`);
+            } else {
+              if (typeof a.name !== "string" || a.name.length === 0) {
+                errors.push(`${at}.arguments[${j}].name \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+              }
+              if (typeof a.required !== "boolean") {
+                errors.push(`${at}.arguments[${j}].required \u5FC5\u987B\u662F\u5E03\u5C14\u503C`);
+              }
+              if (typeof a.description !== "string" || a.description.length === 0) {
+                errors.push(`${at}.arguments[${j}].description \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+              }
+            }
+          });
+        }
+        if (!Array.isArray(c.options)) {
+          errors.push(`${at}.options \u5FC5\u987B\u662F\u6570\u7EC4`);
+        } else {
+          c.options.forEach((o, j) => {
+            if (!isPlainObject(o)) {
+              errors.push(`${at}.options[${j}] \u5FC5\u987B\u662F\u5BF9\u8C61`);
+            } else {
+              if (typeof o.flags !== "string" || o.flags.length === 0) {
+                errors.push(`${at}.options[${j}].flags \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+              }
+              if (typeof o.description !== "string" || o.description.length === 0) {
+                errors.push(`${at}.options[${j}].description \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+              }
+            }
+          });
+        }
+        if (!isPlainObject(c.output)) {
+          errors.push(`${at}.output \u5FC5\u987B\u662F\u5BF9\u8C61`);
+        } else {
+          if (typeof c.output.format !== "string" || c.output.format.length === 0 || !OUTPUT_FORMATS.includes(c.output.format)) {
+            errors.push(
+              `${at}.output.format \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32\u4E14\u5C5E\u4E8E [${OUTPUT_FORMATS.join(", ")}]`
+            );
+          }
+          if (typeof c.output.description !== "string" || c.output.description.length === 0) {
+            errors.push(`${at}.output.description \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32`);
+          }
+        }
+        if (!isPlainObject(c.exitCodes)) {
+          errors.push(`${at}.exitCodes \u5FC5\u987B\u662F\u5BF9\u8C61`);
+        } else {
+          const badExit = Object.values(c.exitCodes).find((v) => typeof v !== "string");
+          if (badExit !== void 0) {
+            errors.push(`${at}.exitCodes \u7684\u503C\u5FC5\u987B\u662F\u5B57\u7B26\u4E32`);
+          }
+        }
+        if (!Array.isArray(c.safety) || !isStringArray(c.safety)) {
+          errors.push(`${at}.safety \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4`);
+        }
+      });
+    }
+  }
+  if (errors.length > 0) {
+    return { ok: false, errors };
+  }
+  return { ok: true, manifest: input };
+}
+function validatePluginIdentity(manifest, pkgJson) {
+  const errors = [];
+  if (manifest.package !== pkgJson.name) {
+    errors.push(
+      `\u6E05\u5355 package "${manifest.package}" \u4E0E package.json name "${String(pkgJson.name)}" \u4E0D\u4E00\u81F4`
+    );
+  }
+  const binKeys = isPlainObject(pkgJson.bin) ? Object.keys(pkgJson.bin) : [];
+  if (!binKeys.includes(manifest.bin)) {
+    errors.push(`\u6E05\u5355 bin "${manifest.bin}" \u4E0D\u5728 package.json bin (${binKeys.join(", ") || "\u7A7A"}) \u4E2D`);
+  }
+  return errors;
+}
+
+// src/core/official.ts
+var OFFICIAL_PLUGINS = [
+  {
+    package: "@kevlns/xlmerge",
+    command: "xlmerge",
+    description: "Git \u4E2D .xlsx/.xlsm \u51B2\u7A81\u53EF\u89C6\u5316\u89E3\u51B3\u65B9\u6848\uFF08\u4E09\u5411 diff\u3001\u672C\u5730 UI\u3001\u5199\u56DE\u4E0E\u63D0\u4EA4\uFF09"
+  },
+  {
+    package: "@kevlns/u-cli-mod",
+    command: "unity",
+    description: "Unity \u5DE5\u7A0B\u7CBE\u786E\u7248\u672C\u8DEF\u7531 + \u5B98\u65B9 CLI \u4E0B\u8F7D + com.unity.pipeline \u9002\u914D\u5305\uFF08Windows-first\uFF09"
+  }
+];
+var OFFICIAL_COMMAND_NAMES = new Set(
+  OFFICIAL_PLUGINS.map((p) => p.command)
+);
+function defaultResolvePackage(pkg, opts = {}) {
+  const baseFile = opts.base ?? fileURLToPath(import.meta.url);
+  const cwd = opts.cwd ?? process.cwd();
+  const resolveFrom = opts.resolveFrom ?? process.env.V_CLI_PLUGIN_RESOLVE_FROM;
+  const candidates = [];
+  if (resolveFrom) {
+    candidates.push(path3.join(path3.resolve(cwd, resolveFrom), "node_modules", pkg, "package.json"));
+  }
+  try {
+    candidates.push(createRequire(baseFile).resolve(`${pkg}/package.json`));
+  } catch {
+  }
+  try {
+    const reqCwd = createRequire(path3.join(cwd, "__v_cli_resolve__.cjs"));
+    candidates.push(reqCwd.resolve(`${pkg}/package.json`, { paths: [cwd] }));
+  } catch {
+  }
+  for (const candidate of candidates) {
+    try {
+      if (fs2.existsSync(candidate)) return candidate;
+    } catch {
+    }
+  }
+  return void 0;
+}
+function defaultExists(file) {
+  try {
+    return fs2.existsSync(file);
+  } catch {
+    return false;
+  }
+}
+function defaultRead(file) {
+  return fs2.readFileSync(file, "utf-8");
+}
+function formatErrors(errors) {
+  return errors.join("\uFF1B");
+}
+function isPlainObject2(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function discoverOfficialPlugin(spec, io = {}) {
+  const platform = io.platform ?? process.platform;
+  const exists = io.existsFile ?? defaultExists;
+  const read = io.readFile ?? defaultRead;
+  const resolvePackage = io.resolvePackage ?? defaultResolvePackage;
+  const base = {
+    source: "official",
+    package: spec.package,
+    name: spec.command,
+    description: spec.description,
+    status: "missing",
+    platform
+  };
+  let pkgJsonPath;
+  try {
+    pkgJsonPath = resolvePackage(spec.package);
+  } catch {
+    pkgJsonPath = void 0;
+  }
+  if (!pkgJsonPath || !exists(pkgJsonPath)) {
+    return {
+      ...base,
+      error: `\u672A\u627E\u5230\u5B98\u65B9\u63D2\u4EF6\u5305 ${spec.package}\uFF08\u672A\u5B89\u88C5\u6216\u4E0D\u5728\u53EF\u89E3\u6790\u8DEF\u5F84\uFF1B\u8BF7\u5B89\u88C5\u540E\u91CD\u8BD5\uFF09`
+    };
+  }
+  let pkgJson;
+  try {
+    pkgJson = JSON.parse(read(pkgJsonPath));
+  } catch (err) {
+    return {
+      ...base,
+      status: "invalid",
+      error: `package.json \u4E0D\u662F\u5408\u6CD5 JSON: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const vCliMeta = pkgJson.vCli && isPlainObject2(pkgJson.vCli) ? pkgJson.vCli : {};
+  const manifestRel = typeof vCliMeta.manifest === "string" ? vCliMeta.manifest : "v-cli.plugin.json";
+  const pkgRoot = path3.dirname(pkgJsonPath);
+  const manifestPath = path3.join(pkgRoot, manifestRel);
+  if (!exists(manifestPath)) {
+    return {
+      ...base,
+      error: `\u5305\u5185\u7F3A\u5C11\u63D2\u4EF6\u6E05\u5355 ${manifestRel}\uFF08package.json \u7684 vCli.manifest \u6307\u5411\u5B83\uFF09`
+    };
+  }
+  let manifestRaw;
+  try {
+    manifestRaw = read(manifestPath);
+  } catch (err) {
+    return {
+      ...base,
+      error: `\u8BFB\u53D6\u6E05\u5355\u5931\u8D25: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(manifestRaw);
+  } catch (err) {
+    return {
+      ...base,
+      status: "invalid",
+      error: `\u6E05\u5355 ${manifestRel} \u4E0D\u662F\u5408\u6CD5 JSON: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const validated = validateManifest(parsed);
+  if (!validated.ok) {
+    return { ...base, status: "invalid", error: `\u6E05\u5355\u6821\u9A8C\u5931\u8D25: ${formatErrors(validated.errors)}` };
+  }
+  const manifest = validated.manifest;
+  const identityErrors = validatePluginIdentity(manifest, pkgJson);
+  if (identityErrors.length > 0) {
+    return {
+      ...base,
+      status: "invalid",
+      error: `\u8EAB\u4EFD\u6821\u9A8C\u5931\u8D25: ${formatErrors(identityErrors)}`
+    };
+  }
+  if (manifest.command !== spec.command) {
+    return {
+      ...base,
+      status: "invalid",
+      error: `\u6E05\u5355 command "${manifest.command}" \u4E0E\u5B98\u65B9\u767D\u540D\u5355\u547D\u4EE4 "${spec.command}" \u4E0D\u4E00\u81F4`
+    };
+  }
+  const binMap = pkgJson.bin;
+  const binRel = isPlainObject2(binMap) ? binMap[manifest.bin] : void 0;
+  if (typeof binRel !== "string" || binRel.length === 0) {
+    return {
+      ...base,
+      status: "invalid",
+      error: `bin "${manifest.bin}" \u7684\u542F\u52A8\u76EE\u6807\u4E0D\u662F\u5B57\u7B26\u4E32\u8DEF\u5F84`
+    };
+  }
+  const binPath = path3.resolve(pkgRoot, binRel);
+  const rootPrefix = pkgRoot.endsWith(path3.sep) ? pkgRoot : pkgRoot + path3.sep;
+  if (!binPath.startsWith(rootPrefix)) {
+    return {
+      ...base,
+      status: "invalid",
+      error: `bin "${manifest.bin}" \u7684\u76EE\u6807 ${binRel} \u9003\u9038\u4E86\u5305\u76EE\u5F55`
+    };
+  }
+  const requiredPlatforms = manifest.platforms;
+  if (!requiredPlatforms.includes(platform)) {
+    return {
+      ...base,
+      status: "platform-mismatch",
+      version: typeof pkgJson.version === "string" ? pkgJson.version : void 0,
+      requiredPlatforms,
+      error: `\u8BE5\u63D2\u4EF6\u4EC5\u652F\u6301\u5E73\u53F0 [${requiredPlatforms.join(", ")}]\uFF0C\u5F53\u524D\u5E73\u53F0\u4E3A ${platform}`
+    };
+  }
+  if (!exists(binPath)) {
+    return {
+      ...base,
+      version: typeof pkgJson.version === "string" ? pkgJson.version : void 0,
+      requiredPlatforms,
+      error: `bin \u6587\u4EF6\u4E0D\u5B58\u5728: ${binRel}\uFF08manifest.bin=${manifest.bin}\uFF09`
+    };
+  }
+  return {
+    ...base,
+    status: "available",
+    version: typeof pkgJson.version === "string" ? pkgJson.version : void 0,
+    requiredPlatforms,
+    bin: binPath,
+    whenToUse: manifest.agent.whenToUse,
+    globalOptions: manifest.agent.globalOptions,
+    commands: manifest.agent.commands.map((c) => ({
+      path: c.path,
+      usage: c.usage,
+      description: c.description,
+      arguments: c.arguments,
+      options: c.options,
+      output: c.output,
+      exitCodes: c.exitCodes,
+      safety: c.safety
+    })),
+    runtime: manifest.runtime,
+    environment: manifest.environment
+  };
+}
+function discoverAllOfficialPlugins(io = {}) {
+  return OFFICIAL_PLUGINS.map((spec) => discoverOfficialPlugin(spec, io));
+}
+function isOfficialCommand(token) {
+  return OFFICIAL_COMMAND_NAMES.has(token);
+}
+
 // src/core/command.ts
-function isCliCommand(candidate) {
-  if (typeof candidate !== "object" || candidate === null) return false;
+var RESERVED_COMMAND_NAMES = ["doctor", "plugin", "ts", "agent", "help"];
+var NAME_RE = /^[a-z][a-z0-9-]*$/;
+function isStringArray2(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function isPlainObject3(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function validateAgentMeta(agent2, errors) {
+  if (agent2 === void 0 || agent2 === null) return;
+  if (!isPlainObject3(agent2)) {
+    errors.push("agent \u5FC5\u987B\u662F\u5BF9\u8C61");
+    return;
+  }
+  if (agent2.whenToUse !== void 0 && typeof agent2.whenToUse !== "string") {
+    errors.push("agent.whenToUse \u5FC5\u987B\u662F\u5B57\u7B26\u4E32");
+  }
+  if (agent2.globalOptions !== void 0) {
+    if (!Array.isArray(agent2.globalOptions)) {
+      errors.push("agent.globalOptions \u5FC5\u987B\u662F\u6570\u7EC4");
+    } else {
+      agent2.globalOptions.forEach((o, i) => {
+        if (!isPlainObject3(o) || typeof o.flags !== "string" || typeof o.description !== "string") {
+          errors.push(`agent.globalOptions[${i}] \u5FC5\u987B\u662F {flags: string, description: string}`);
+        }
+      });
+    }
+  }
+  if (agent2.commands !== void 0) {
+    if (!Array.isArray(agent2.commands)) {
+      errors.push("agent.commands \u5FC5\u987B\u662F\u6570\u7EC4");
+    } else {
+      agent2.commands.forEach((c, i) => {
+        const at = `agent.commands[${i}]`;
+        if (!isPlainObject3(c) || typeof c.description !== "string") {
+          errors.push(`${at} \u5FC5\u987B\u662F\u542B\u5B57\u7B26\u4E32 description \u7684\u5BF9\u8C61`);
+          return;
+        }
+        if (!Array.isArray(c.path) || !isStringArray2(c.path) || c.path.length === 0) {
+          errors.push(`${at}.path \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32\u6570\u7EC4\uFF08\u6BCF\u6BB5\u5339\u914D ^[a-z][a-z0-9-]*$\uFF09`);
+        } else if (c.path.some((seg) => !NAME_RE.test(seg))) {
+          errors.push(`${at}.path \u542B\u975E\u6CD5\u6BB5\uFF08\u6BCF\u6BB5\u987B\u5339\u914D ^[a-z][a-z0-9-]*$\uFF09`);
+        }
+        if (c.usage !== void 0 && typeof c.usage !== "string") {
+          errors.push(`${at}.usage \u5FC5\u987B\u662F\u5B57\u7B26\u4E32`);
+        }
+      });
+    }
+  }
+}
+function validateLocalCommand(candidate, options = {}) {
+  const errors = [];
+  if (!isPlainObject3(candidate)) {
+    return { ok: false, errors: ["\u63D2\u4EF6\u5BFC\u51FA\u5FC5\u987B\u662F\u5BF9\u8C61"] };
+  }
   const cmd = candidate;
-  return typeof cmd.name === "string" && typeof cmd.description === "string" && typeof cmd.register === "function";
+  if (cmd.apiVersion !== 1) {
+    const got = cmd.apiVersion === void 0 ? "\u7F3A\u5931" : JSON.stringify(cmd.apiVersion);
+    errors.push(
+      `apiVersion \u5FC5\u987B\u4E3A 1\uFF08\u5F53\u524D: ${got}\uFF09\u3002v-cli 0.2 \u8D77\u91C7\u7528 apiVersion 1 \u63D2\u4EF6\u5951\u7EA6\uFF0C\u65E7\u7248\u63D2\u4EF6\u8BF7\u8865\u4E0A apiVersion: 1 \u540E\u91CD\u65B0\u52A0\u8F7D`
+    );
+  }
+  if (typeof cmd.name !== "string" || cmd.name.length === 0) {
+    errors.push("name \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32");
+  } else {
+    if (!NAME_RE.test(cmd.name)) {
+      errors.push(`\u547D\u4EE4\u540D "${cmd.name}" \u4E0D\u5408\u6CD5\uFF1A\u53EA\u80FD\u662F\u5C0F\u5199\u5B57\u6BCD\u5F00\u5934\u7684 [a-z0-9-] \u5B57\u7B26\u4E32`);
+    }
+    const reserved = [...RESERVED_COMMAND_NAMES, ...OFFICIAL_COMMAND_NAMES];
+    if (reserved.includes(cmd.name)) {
+      const kind = RESERVED_COMMAND_NAMES.includes(cmd.name) ? "v-cli \u5185\u7F6E\u4FDD\u7559\u547D\u4EE4" : "\u5B98\u65B9\u63D2\u4EF6\u547D\u4EE4";
+      errors.push(`\u547D\u4EE4\u540D "${cmd.name}" \u662F${kind}\uFF0C\u672C\u5730\u63D2\u4EF6\u4E0D\u80FD\u5360\u7528`);
+    }
+    if ((options.existingNames ?? []).includes(cmd.name)) {
+      errors.push(`\u91CD\u590D\u7684\u547D\u4EE4\u540D "${cmd.name}"\uFF08\u5DF2\u7531\u5176\u4ED6\u672C\u5730\u63D2\u4EF6\u5B9A\u4E49\uFF09`);
+    }
+  }
+  if (typeof cmd.description !== "string" || cmd.description.length === 0) {
+    errors.push("description \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32");
+  }
+  if (typeof cmd.register !== "function") {
+    errors.push("register \u5FC5\u987B\u662F\u51FD\u6570");
+  }
+  validateAgentMeta(cmd.agent, errors);
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, command: candidate, errors: [] };
+}
+
+// src/commands/agent.ts
+function buildAgentIndex(builtin, local, official) {
+  const rows = [];
+  for (const cmd of builtin) {
+    rows.push({
+      name: cmd.name,
+      type: "builtin",
+      description: cmd.description,
+      metadataStatus: cmd.agent ? "full" : "minimal",
+      whenToUse: cmd.agent?.whenToUse,
+      globalOptions: cmd.agent?.globalOptions,
+      commands: cmd.agent?.commands
+    });
+  }
+  for (const item of local) {
+    const cmd = item.command;
+    if (!cmd) {
+      rows.push({
+        name: item.file ? item.file.split(/[\\/]/).pop()?.replace(/\.mjs$/, "") ?? "(\u52A0\u8F7D\u5931\u8D25)" : "(\u52A0\u8F7D\u5931\u8D25)",
+        type: "local",
+        description: item.error ?? "\u52A0\u8F7D\u5931\u8D25",
+        metadataStatus: "minimal",
+        error: item.error
+      });
+      continue;
+    }
+    rows.push({
+      name: cmd.name,
+      type: "local",
+      description: cmd.description,
+      metadataStatus: cmd.agent ? "full" : "minimal",
+      whenToUse: cmd.agent?.whenToUse,
+      globalOptions: cmd.agent?.globalOptions,
+      commands: cmd.agent?.commands
+    });
+  }
+  for (const info of official) {
+    rows.push({
+      name: info.name,
+      type: "official",
+      description: info.description,
+      metadataStatus: info.status === "available" ? "full" : "minimal",
+      package: info.package,
+      version: info.version,
+      status: info.status,
+      platform: info.platform,
+      requiredPlatforms: info.requiredPlatforms,
+      error: info.error,
+      whenToUse: info.whenToUse,
+      globalOptions: info.globalOptions,
+      // 完整清单元数据全量透传（arguments/options/output/exitCodes/safety）
+      commands: info.commands,
+      runtime: info.runtime,
+      environment: info.environment
+    });
+  }
+  return rows;
+}
+function rowToText(row) {
+  const status = row.status ? ` [${row.status}]` : "";
+  const meta = row.metadataStatus === "full" ? "\u5B8C\u6574\u5143\u6570\u636E" : "\u6700\u5C0F\u5143\u6570\u636E";
+  return `[${row.type}] ${row.name}${status}: ${row.description} (${meta})`;
 }
+var agent = {
+  name: "agent",
+  description: "agent \u7D22\u5F15\uFF1Aindex \u5217\u51FA\u5168\u90E8\u547D\u4EE4\u53CA\u5143\u6570\u636E\uFF0Cdescribe \u67E5\u770B\u5355\u4E2A\u547D\u4EE4\u8BE6\u60C5",
+  apiVersion: 1,
+  register(program, ctx) {
+    program.command("index").description("\u5217\u51FA\u5168\u90E8\u547D\u4EE4\uFF08builtin/local/official\uFF09\u4E0E agent \u5143\u6570\u636E").option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON").action(async (opts) => {
+      const json = ctx.json || opts.json;
+      const rows = buildAgentIndex(
+        builtinCommands,
+        await loadLocalPlugins(ctx),
+        discoverAllOfficialPlugins()
+      );
+      ctx.log.result(json ? rows : rows.map(rowToText).join("\n"));
+    });
+    program.command("describe").description("\u67E5\u770B\u5355\u4E2A\u547D\u4EE4\u7684\u5B8C\u6574\u8BB0\u5F55\uFF08builtin/local/official\uFF09").argument("<name>", "\u547D\u4EE4\u540D").option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON").action(async (name, opts) => {
+      const json = ctx.json || opts.json;
+      const row = buildAgentIndex(
+        builtinCommands,
+        await loadLocalPlugins(ctx),
+        discoverAllOfficialPlugins()
+      ).find((r) => r.name === name);
+      if (!row) {
+        ctx.log.error(`\u672A\u627E\u5230\u547D\u4EE4: ${name}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (json) {
+        ctx.log.result(row);
+        return;
+      }
+      const lines = [
+        `\u547D\u4EE4: ${row.name} (${row.type})`,
+        `\u63CF\u8FF0: ${row.description}`,
+        `\u5143\u6570\u636E: ${row.metadataStatus}`
+      ];
+      if (row.status) lines.push(`\u72B6\u6001: ${row.status}${row.error ? `\uFF08${row.error}\uFF09` : ""}`);
+      if (row.package) lines.push(`\u5305: ${row.package}${row.version ? `@${row.version}` : ""}`);
+      if (row.requiredPlatforms) lines.push(`\u652F\u6301\u5E73\u53F0: ${row.requiredPlatforms.join(", ")}`);
+      if (row.whenToUse) lines.push(`\u4F55\u65F6\u4F7F\u7528: ${row.whenToUse}`);
+      if (row.globalOptions && row.globalOptions.length > 0) {
+        lines.push("\u5168\u5C40\u9009\u9879:");
+        for (const o of row.globalOptions) lines.push(`  ${o.flags} \u2014 ${o.description}`);
+      }
+      if (row.commands && row.commands.length > 0) {
+        lines.push("\u5B50\u547D\u4EE4:");
+        for (const c of row.commands) {
+          const pathText = Array.isArray(c.path) ? c.path.join(" ") : "";
+          const optText = Array.isArray(c.options) && c.options.length > 0 ? ` \u9009\u9879: ${c.options.map((o) => o.flags).join(", ")}` : "";
+          const safeText = Array.isArray(c.safety) && c.safety.length > 0 ? ` \u5B89\u5168: ${c.safety.join("\uFF1B")}` : "";
+          lines.push(
+            `  ${pathText} \u2014 ${c.description}${c.usage ? ` (\u7528\u6CD5: ${c.usage})` : ""}${optText}${safeText}`
+          );
+        }
+      }
+      ctx.log.result(lines.join("\n"));
+    });
+  }
+};
 
 // src/commands/doctor.ts
-import fs2 from "fs";
+import fs3 from "fs";
 
 // src/version.ts
-var VERSION = "0.1.1-beta.1";
+var VERSION = "0.2.0-beta.1";
 
 // src/commands/doctor.ts
 var doctor = {
   name: "doctor",
   description: "\u4F53\u68C0\uFF1Anode/v-cli \u7248\u672C\u3001homeDir\u3001config\u3001\u63D2\u4EF6\u72B6\u6001",
+  apiVersion: 1,
   register(program, ctx) {
-    program.action(async () => {
+    program.option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON").action(async (opts) => {
+      const json = ctx.json || opts.json;
       const homeDir = ctx.homeDir;
-      const exists = fs2.existsSync(homeDir);
+      const exists = fs3.existsSync(homeDir);
       let configWritable = false;
       try {
         ctx.config.set((cfg) => cfg);
@@ -113,6 +747,14 @@ var doctor = {
         file: p.file,
         error: p.error ?? null
       }));
+      const officialPlugins = discoverAllOfficialPlugins().map((o) => ({
+        package: o.package,
+        name: o.name,
+        version: o.version,
+        status: o.status,
+        platform: o.platform,
+        error: o.error
+      }));
       const report = {
         version: VERSION,
         node: process.version,
@@ -120,9 +762,10 @@ var doctor = {
         homeDirExists: exists,
         configWritable,
         localPluginCount: plugins.length,
-        localPlugins: list
+        localPlugins: list,
+        officialPlugins
       };
-      if (ctx.json) {
+      if (json) {
         ctx.log.result(report);
       } else {
         ctx.log.result(`vcli ${VERSION} (node ${process.version})`);
@@ -132,18 +775,26 @@ var doctor = {
         for (const p of plugins) {
           ctx.log.result(`  - ${p.file}${p.error ? `  [\u5931\u8D25: ${p.error}]` : ""}`);
         }
+        ctx.log.result(`\u5B98\u65B9\u63D2\u4EF6: ${officialPlugins.length} \u4E2A`);
+        for (const o of officialPlugins) {
+          ctx.log.result(
+            `  - ${o.name} (${o.package}${o.version ? `@${o.version}` : ""}) [${o.status}]${o.error ? ` ${o.error}` : ""}`
+          );
+        }
       }
     });
   }
 };
 
 // src/commands/plugin.ts
-import path3 from "path";
+import path4 from "path";
 var plugin = {
   name: "plugin",
   description: "\u63D2\u4EF6\u7BA1\u7406\uFF1Alist \u5217\u51FA\u547D\u4EE4\uFF0Cpath \u663E\u793A\u672C\u5730\u63D2\u4EF6\u76EE\u5F55",
+  apiVersion: 1,
   register(program, ctx) {
-    program.command("list").description("\u5217\u51FA\u5185\u7F6E\u547D\u4EE4\u4E0E\u672C\u5730\u63D2\u4EF6").action(async () => {
+    program.command("list").description("\u5217\u51FA\u5185\u7F6E\u547D\u4EE4\u3001\u672C\u5730\u63D2\u4EF6\u4E0E\u5B98\u65B9\u63D2\u4EF6\u72B6\u6001").option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON").action(async (opts) => {
+      const json = ctx.json || opts.json;
       const all = await loadAllCommands(ctx);
       const rows = all.map((item) => ({
         source: item.source,
@@ -151,17 +802,32 @@ var plugin = {
         description: item.command?.description ?? item.error ?? "",
         file: item.file ?? ""
       }));
-      if (ctx.json) {
-        ctx.log.result(rows);
+      const official = discoverAllOfficialPlugins().map((o) => ({
+        source: "official",
+        name: o.name,
+        description: o.description,
+        package: o.package,
+        version: o.version,
+        status: o.status,
+        platform: o.platform,
+        error: o.error
+      }));
+      if (json) {
+        ctx.log.result([...rows, ...official]);
       } else {
         for (const row of rows) {
           ctx.log.result(`[${row.source}] ${row.name}: ${row.description}`);
         }
+        for (const row of official) {
+          ctx.log.result(
+            `[${row.source}] ${row.name}: ${row.description} [${row.status}]${row.error ? ` ${row.error}` : ""}`
+          );
+        }
       }
     });
-    program.command("path").description("\u6253\u5370\u672C\u5730\u63D2\u4EF6\u76EE\u5F55\uFF08\u653E\u5165 .mjs \u6587\u4EF6\u5373\u751F\u6548\uFF09").action(() => {
-      const dir = path3.join(ctx.homeDir, "commands");
-      if (ctx.json) {
+    program.command("path").description("\u6253\u5370\u672C\u5730\u63D2\u4EF6\u76EE\u5F55\uFF08\u653E\u5165 .mjs \u6587\u4EF6\u5373\u751F\u6548\uFF09").option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON").action((opts) => {
+      const dir = path4.join(ctx.homeDir, "commands");
+      if (ctx.json || opts.json) {
         ctx.log.result({ dir });
       } else {
         ctx.log.result(dir);
@@ -192,8 +858,10 @@ function parseInput(input) {
 var ts = {
   name: "ts",
   description: "\u65F6\u95F4\u6233\u5DE5\u5177\uFF1A\u65F6\u95F4\u6233 <-> \u53EF\u8BFB\u65F6\u95F4\u4E92\u8F6C",
+  apiVersion: 1,
   register(program, ctx) {
-    program.argument("[value]", "\u6570\u5B57\u65F6\u95F4\u6233\uFF08\u79D2\u6216\u6BEB\u79D2\uFF0C\u81EA\u52A8\u8BC6\u522B\uFF09\u6216\u65E5\u671F\u5B57\u7B26\u4E32").action((value) => {
+    program.argument("[value]", "\u6570\u5B57\u65F6\u95F4\u6233\uFF08\u79D2\u6216\u6BEB\u79D2\uFF0C\u81EA\u52A8\u8BC6\u522B\uFF09\u6216\u65E5\u671F\u5B57\u7B26\u4E32").option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON").action((value, opts) => {
+      const json = ctx.json || opts.json;
       if (!value || value === "now") {
         const now = Date.now();
         const report2 = {
@@ -202,7 +870,7 @@ var ts = {
           iso: new Date(now).toISOString(),
           local: new Date(now).toString()
         };
-        ctx.log.result(ctx.json ? report2 : report2.iso);
+        ctx.log.result(json ? report2 : report2.iso);
         return;
       }
       const result = parseInput(value);
@@ -213,36 +881,38 @@ var ts = {
         iso: new Date(result.milliseconds).toISOString(),
         local: formatTime(result.milliseconds)
       };
-      ctx.log.result(ctx.json ? report : report.local);
+      ctx.log.result(json ? report : report.local);
     });
   }
 };
 
 // src/commands/index.ts
-var builtinCommands = [doctor, plugin, ts];
+var builtinCommands = [doctor, plugin, ts, agent];
 
 // src/core/loader.ts
 async function loadBuiltinCommands() {
   return builtinCommands.map((command) => ({ command, source: "builtin" }));
 }
 async function loadLocalPlugins(ctx) {
-  const dir = path4.join(ctx.homeDir, "commands");
+  const dir = path5.join(ctx.homeDir, "commands");
   const loaded = [];
-  if (!fs3.existsSync(dir)) return loaded;
-  const files = fs3.readdirSync(dir).filter((f) => f.endsWith(".mjs")).sort();
+  if (!fs4.existsSync(dir)) return loaded;
+  const files = fs4.readdirSync(dir).filter((f) => f.endsWith(".mjs")).sort();
   for (const file of files) {
-    const abs = path4.join(dir, file);
+    const abs = path5.join(dir, file);
     try {
       const mod = await import(
         /* @vite-ignore */
         pathToFileURL(abs).href
       );
-      const cmd = mod.default ?? mod;
-      if (!isCliCommand(cmd)) {
-        loaded.push({ source: "local", file: abs, error: "\u9ED8\u8BA4\u5BFC\u51FA\u4E0D\u7B26\u5408 CliCommand \u5951\u7EA6" });
+      const candidate = mod.default ?? mod;
+      const acceptedNames = loaded.map((l) => l.command?.name).filter((n) => typeof n === "string");
+      const validation = validateLocalCommand(candidate, { existingNames: acceptedNames });
+      if (!validation.ok || !validation.command) {
+        loaded.push({ source: "local", file: abs, error: validation.errors.join("\uFF1B") });
         continue;
       }
-      loaded.push({ command: cmd, source: "local", file: abs });
+      loaded.push({ command: validation.command, source: "local", file: abs });
     } catch (err) {
       loaded.push({
         source: "local",
@@ -257,14 +927,120 @@ async function loadAllCommands(ctx) {
   return [...await loadBuiltinCommands(), ...await loadLocalPlugins(ctx)];
 }
 
+// src/core/runner.ts
+import { spawn } from "child_process";
+var PLUGIN_ENV_KEYS = {
+  V_CLI_HOST_VERSION: VERSION,
+  V_CLI_PLUGIN_API: "1",
+  V_CLI_INVOKED_BY: "v-cli"
+};
+var SIGNAL_NUMBERS = {
+  SIGHUP: 1,
+  SIGINT: 2,
+  SIGQUIT: 3,
+  SIGILL: 4,
+  SIGTRAP: 5,
+  SIGABRT: 6,
+  SIGBUS: 7,
+  SIGFPE: 8,
+  SIGKILL: 9,
+  SIGUSR1: 10,
+  SIGSEGV: 11,
+  SIGUSR2: 12,
+  SIGPIPE: 13,
+  SIGALRM: 14,
+  SIGTERM: 15,
+  SIGSTKFLT: 16,
+  SIGCHLD: 17,
+  SIGCONT: 18,
+  SIGSTOP: 19,
+  SIGTSTP: 20,
+  SIGTTIN: 21,
+  SIGTTOU: 22,
+  SIGURG: 23,
+  SIGXCPU: 24,
+  SIGXFSZ: 25,
+  SIGVTALRM: 26,
+  SIGPROF: 27,
+  SIGWINCH: 28,
+  SIGIO: 29,
+  SIGPWR: 30,
+  SIGSYS: 31
+};
+function runPluginBin({ bin, argv, env = {}, cwd }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [bin, ...argv], {
+      cwd,
+      env: { ...process.env, ...PLUGIN_ENV_KEYS, ...env },
+      stdio: "inherit",
+      shell: false
+    });
+    const forward = (signal) => {
+      try {
+        child.kill(signal);
+      } catch {
+      }
+    };
+    const onSigint = () => forward("SIGINT");
+    const onSigterm = () => forward("SIGTERM");
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    const cleanup = () => {
+      process.removeListener("SIGINT", onSigint);
+      process.removeListener("SIGTERM", onSigterm);
+    };
+    child.on("error", (err) => {
+      cleanup();
+      reject(err);
+    });
+    child.on("close", (code, signal) => {
+      cleanup();
+      resolve({ code, signal });
+    });
+  });
+}
+function mapExitCode(result) {
+  if (result.code !== null) return result.code;
+  if (result.signal !== null) {
+    if (process.platform !== "win32") {
+      const signum = SIGNAL_NUMBERS[result.signal];
+      if (signum !== void 0) return 128 + signum;
+    }
+    return 1;
+  }
+  return 1;
+}
+
 // src/cli.ts
+function scanLeadingJson(rawArgs) {
+  let i = 0;
+  while (i < rawArgs.length && rawArgs[i] === "--json") i++;
+  return { json: i > 0, args: rawArgs.slice(i), commandIndex: i };
+}
+async function interceptOfficialCommand(rawArgs, commandIndex) {
+  const token = rawArgs[commandIndex];
+  if (!isOfficialCommand(token)) return void 0;
+  const spec = OFFICIAL_PLUGINS.find((p) => p.command === token);
+  if (!spec) return void 0;
+  const info = discoverOfficialPlugin(spec);
+  if (info.status !== "available" || !info.bin) {
+    process.stderr.write(
+      `[v-cli] \u9519\u8BEF: \u5B98\u65B9\u63D2\u4EF6 ${spec.package}\uFF08\u547D\u4EE4 ${spec.command}\uFF09\u4E0D\u53EF\u7528\uFF1A${info.error ?? info.status}
+`
+    );
+    return 1;
+  }
+  const result = await runPluginBin({ bin: info.bin, argv: rawArgs.slice(commandIndex + 1) });
+  return mapExitCode(result);
+}
 async function main() {
   const rawArgs = process.argv.slice(2);
-  const json = rawArgs.includes("--json");
-  const args = rawArgs.filter((a) => a !== "--json");
-  const ctx = createContext(defaultHomeDir(), json);
+  const span = scanLeadingJson(rawArgs);
+  const ctx = createContext(defaultHomeDir(), span.json);
+  const intercepted = await interceptOfficialCommand(rawArgs, span.commandIndex);
+  if (intercepted !== void 0) return intercepted;
   const program = new Command();
-  program.name("v-cli").description("kevlns \u7684\u4E2A\u4EBA\u5DE5\u5177\u7BB1").version(VERSION).option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON").showHelpAfterError();
+  program.name("v-cli").description("kevlns \u7684\u4E2A\u4EBA\u5DE5\u5177\u7BB1").version(VERSION).showHelpAfterError();
   const loaded = await loadAllCommands(ctx);
   for (const item of loaded) {
     if (!item.command) {
@@ -273,12 +1049,22 @@ async function main() {
     }
     const cmd = item.command;
     if (cmd.hidden) continue;
-    const sub = program.command(cmd.name).description(cmd.description);
-    cmd.register(sub, ctx);
+    const sub = new Command(cmd.name).description(cmd.description);
+    try {
+      cmd.register(sub, ctx);
+      program.addCommand(sub);
+    } catch (err) {
+      ctx.log.warn(
+        `${item.file ?? cmd.name} register \u5931\u8D25: ${err instanceof Error ? err.message : String(err)}\uFF1B\u5DF2\u8DF3\u8FC7`
+      );
+    }
+  }
+  for (const spec of OFFICIAL_PLUGINS) {
+    program.command(spec.command).description(`${spec.description}\uFF08\u5B98\u65B9\u63D2\u4EF6\uFF1A\u5B89\u88C5\u540E\u53EF\u7528\uFF09`);
   }
   try {
-    await program.parseAsync(args, { from: "user" });
-    return 0;
+    await program.parseAsync(span.args, { from: "user" });
+    return typeof process.exitCode === "number" ? process.exitCode : 0;
   } catch (err) {
     if (err instanceof CommanderError) {
       return err.exitCode ?? 1;