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

package/dist/cli.mjs

@@ -75,31 +75,1071 @@ function defaultHomeDir() {
 }
 
 // src/core/loader.ts
-import fs3 from "fs";
-import path4 from "path";
+import fs5 from "fs";
+import path7 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`);
+        }
+        if (c.arguments !== void 0) {
+          const bad = !Array.isArray(c.arguments) || c.arguments.some(
+            (a) => !isPlainObject3(a) || typeof a.name !== "string" || typeof a.required !== "boolean" || typeof a.description !== "string"
+          );
+          if (bad) errors.push(`${at}.arguments \u5FC5\u987B\u662F { name: string; required: boolean; description: string }[]`);
+        }
+        if (c.options !== void 0) {
+          const bad = !Array.isArray(c.options) || c.options.some((o) => !isPlainObject3(o) || typeof o.flags !== "string" || typeof o.description !== "string");
+          if (bad) errors.push(`${at}.options \u5FC5\u987B\u662F { flags: string; description: string }[]`);
+        }
+        if (c.output !== void 0) {
+          const bad = !isPlainObject3(c.output) || typeof c.output.format !== "string" || typeof c.output.description !== "string";
+          if (bad) errors.push(`${at}.output \u5FC5\u987B\u662F { format: string; description: string }`);
+        }
+        if (c.exitCodes !== void 0) {
+          const bad = !isPlainObject3(c.exitCodes) || Object.entries(c.exitCodes).some(([code, desc]) => typeof code !== "string" || typeof desc !== "string");
+          if (bad) errors.push(`${at}.exitCodes \u5FC5\u987B\u662F { [\u9000\u51FA\u7801: string]: string }`);
+        }
+        if (c.safety !== void 0 && !isStringArray2(c.safety)) {
+          errors.push(`${at}.safety \u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4`);
+        }
+      });
+    }
+  }
+}
+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/doctor.ts
-import fs2 from "fs";
+// src/commands/agent.ts
+import path5 from "path";
+
+// src/core/agent-docs.ts
+import fs3 from "fs";
+import path4 from "path";
+import { createHash, randomBytes } from "crypto";
+import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/version.ts
-var VERSION = "0.1.1-beta.1";
+var VERSION = "0.2.0-beta.2";
+
+// src/core/agent-docs.ts
+var BUNDLED_DOCS_FILE = "AGENTS.md";
+var BUNDLED_DOCS_PACKAGE = "@kevlns/v-cli";
+function bundledCandidatePaths(moduleFile) {
+  const candidates = [];
+  const push = (p) => {
+    if (!candidates.includes(p)) candidates.push(p);
+  };
+  if (path4.basename(path4.dirname(moduleFile)) === "dist") {
+    push(path4.join(path4.dirname(path4.dirname(moduleFile)), BUNDLED_DOCS_FILE));
+  }
+  let dir = path4.dirname(moduleFile);
+  for (; ; ) {
+    if (pkgName(path4.join(dir, "package.json")) === BUNDLED_DOCS_PACKAGE) {
+      push(path4.join(dir, BUNDLED_DOCS_FILE));
+      break;
+    }
+    const nestedPkg = path4.join(dir, "node_modules", "@kevlns", "v-cli", "package.json");
+    if (pkgName(nestedPkg) === BUNDLED_DOCS_PACKAGE) {
+      push(path4.join(dir, "node_modules", "@kevlns", "v-cli", BUNDLED_DOCS_FILE));
+      break;
+    }
+    const parent = path4.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return candidates;
+}
+function pkgName(pkgJsonPath) {
+  try {
+    const pkg = JSON.parse(fs3.readFileSync(pkgJsonPath, "utf-8"));
+    return typeof pkg.name === "string" ? pkg.name : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function resolveBundledAgentsMd(opts = {}) {
+  const moduleFile = opts.base ?? fileURLToPath2(import.meta.url);
+  for (const candidate of bundledCandidatePaths(moduleFile)) {
+    try {
+      if (fs3.lstatSync(candidate).isFile()) return candidate;
+    } catch {
+    }
+  }
+  return void 0;
+}
+function readBundledAgentsMd(opts = {}) {
+  const file = resolveBundledAgentsMd(opts);
+  if (!file) {
+    const tried = bundledCandidatePaths(opts.base ?? fileURLToPath2(import.meta.url));
+    const lastTried = tried.length > 0 ? tried[tried.length - 1] : "\uFF08\u65E0\u5019\u9009\u4F4D\u7F6E\uFF09";
+    throw new Error(
+      `\u65E0\u6CD5\u5B9A\u4F4D ${BUNDLED_DOCS_PACKAGE} \u5185\u7F6E ${BUNDLED_DOCS_FILE}\uFF1A\u5DF2\u68C0\u67E5 ${tried.length} \u4E2A\u5019\u9009\u4F4D\u7F6E\u5747\u4E0D\u5B58\u5728\u6216\u4E0D\u53EF\u8BFB\uFF08\u6700\u540E\u68C0\u67E5: ${lastTried}\uFF09\u3002\u8BF7\u786E\u8BA4\u5B89\u88C5\u7684\u5305\u5185\u5305\u542B AGENTS.md\uFF08\u91CD\u65B0\u5B89\u88C5 @kevlns/v-cli \u540E\u91CD\u8BD5\uFF09\u3002`
+    );
+  }
+  let content;
+  try {
+    content = fs3.readFileSync(file, "utf-8");
+  } catch (err) {
+    throw new Error(
+      `\u65E0\u6CD5\u8BFB\u53D6 ${BUNDLED_DOCS_PACKAGE} \u5185\u7F6E ${BUNDLED_DOCS_FILE}\uFF08${file}\uFF09: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  return {
+    file,
+    content,
+    sha256: sha256Hex(content),
+    bytes: Buffer.byteLength(content, "utf-8")
+  };
+}
+function sha256Hex(content) {
+  return createHash("sha256").update(content, "utf-8").digest("hex");
+}
+function performAgentInit(opts) {
+  const { directory, docs, force = false, dryRun = false, explicitDirectory = false } = opts;
+  const target = path4.join(directory, BUNDLED_DOCS_FILE);
+  const base = {
+    ok: false,
+    dryRun,
+    action: "refused",
+    directory,
+    target,
+    package: BUNDLED_DOCS_PACKAGE,
+    version: VERSION,
+    sha256: docs.sha256,
+    bytes: docs.bytes
+  };
+  const refuse = (reason) => ({ ...base, ok: false, action: "refused", reason });
+  let dirStat;
+  try {
+    dirStat = fs3.statSync(directory);
+  } catch {
+    return refuse(`\u76EE\u6807\u76EE\u5F55\u4E0D\u5B58\u5728\u6216\u4E0D\u53EF\u8BBF\u95EE: ${directory}`);
+  }
+  if (!dirStat.isDirectory()) {
+    return refuse(`\u76EE\u6807\u4E0D\u662F\u76EE\u5F55: ${directory}`);
+  }
+  if (explicitDirectory) {
+    let dirLstat;
+    try {
+      dirLstat = fs3.lstatSync(directory);
+    } catch {
+    }
+    if (dirLstat && dirLstat.isSymbolicLink()) {
+      return refuse(
+        `\u62D2\u7EDD\u5199\u5165\uFF1A\u76EE\u6807\u76EE\u5F55 ${directory} \u662F\u7B26\u53F7\u94FE\u63A5/\u8054\u63A5\u76EE\u5F55\uFF08fail-closed\uFF0C\u4E0D\u8DDF\u968F\uFF09\u3002\u8BF7\u4F20\u5165\u771F\u5B9E\u76EE\u5F55\u8DEF\u5F84\uFF0C\u6216\u7701\u7565\u53C2\u6570\u8BA9 v-cli \u4F7F\u7528\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55`
+      );
+    }
+  }
+  let targetStat;
+  try {
+    targetStat = fs3.lstatSync(target);
+  } catch {
+    targetStat = void 0;
+  }
+  if (targetStat) {
+    if (targetStat.isSymbolicLink()) {
+      return refuse(
+        `\u62D2\u7EDD\u5199\u5165 ${target}\uFF1A\u76EE\u6807\u662F\u7B26\u53F7\u94FE\u63A5\uFF08fail-closed\uFF0C\u4E0D\u8DDF\u968F\u3001\u4E0D\u8986\u76D6\u94FE\u63A5\u76EE\u6807\uFF09\u3002\u8BF7\u5148\u79FB\u9664\u94FE\u63A5\u6216\u9009\u62E9\u5176\u4ED6\u76EE\u5F55`
+      );
+    }
+    if (targetStat.isDirectory()) {
+      return refuse(`\u62D2\u7EDD\u5199\u5165 ${target}\uFF1A\u76EE\u6807\u662F\u4E00\u4E2A\u76EE\u5F55\uFF08\u65E0\u6CD5\u4EE5\u6587\u4EF6\u8986\u76D6\uFF09`);
+    }
+    if (!force) {
+      return refuse(
+        `${target} \u5DF2\u5B58\u5728\uFF0C\u9ED8\u8BA4\u62D2\u7EDD\u8986\u76D6\uFF08\u4E0D\u505A\u4EFB\u4F55\u6539\u52A8\uFF09\u3002\u5982\u9700\u8986\u76D6\u8BF7\u4F7F\u7528 --force\uFF1B\u5982\u9700\u9884\u89C8\u8BF7\u4F7F\u7528 --dry-run\uFF1B\u5982\u9700\u5148\u67E5\u770B\u5185\u5BB9\u8BF7\u8FD0\u884C v-cli agent docs`
+      );
+    }
+  }
+  const existed = targetStat !== void 0;
+  const action = existed ? dryRun ? "overwrite" : "overwritten" : dryRun ? "write" : "written";
+  if (dryRun) {
+    return { ...base, ok: true, action };
+  }
+  try {
+    atomicWrite(target, docs.content);
+  } catch (err) {
+    return refuse(`\u5199\u5165\u5931\u8D25 ${target}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return { ...base, ok: true, action };
+}
+function isEexist(err) {
+  return typeof err === "object" && err !== null && err.code === "EEXIST";
+}
+var MAX_TMP_RETRIES = 5;
+function atomicWrite(target, content) {
+  let lastError;
+  for (let attempt = 0; attempt < MAX_TMP_RETRIES; attempt++) {
+    const tmp = path4.join(
+      path4.dirname(target),
+      `.${BUNDLED_DOCS_FILE}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`
+    );
+    let created = false;
+    try {
+      fs3.writeFileSync(tmp, content, { encoding: "utf-8", flag: "wx", mode: 420 });
+      created = true;
+      fs3.renameSync(tmp, target);
+      return;
+    } catch (err) {
+      lastError = err;
+      if (created) {
+        try {
+          fs3.rmSync(tmp, { force: true });
+        } catch {
+        }
+      }
+      if (isEexist(err)) continue;
+      throw err;
+    }
+  }
+  const detail = lastError instanceof Error ? lastError.message : String(lastError ?? "\u672A\u77E5\u9519\u8BEF");
+  throw new Error(`\u539F\u5B50\u5199\u5165\u5931\u8D25\uFF08\u4E34\u65F6\u6587\u4EF6\u547D\u540D\u78B0\u649E\u91CD\u8BD5 ${MAX_TMP_RETRIES} \u6B21\u672A\u679C\uFF09: ${detail}`);
+}
+
+// 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})`;
+}
+function describeCommandLine(c) {
+  const pathText = Array.isArray(c.path) ? c.path.join(" ") : "";
+  const argText = Array.isArray(c.arguments) && c.arguments.length > 0 ? ` \u53C2\u6570: ${c.arguments.map((a) => `${a.required ? `<${a.name}>` : `[${a.name}]`}`).join(", ")}` : "";
+  const optText = Array.isArray(c.options) && c.options.length > 0 ? ` \u9009\u9879: ${c.options.map((o) => o.flags).join(", ")}` : "";
+  const outputText = c.output && typeof c.output === "object" && typeof c.output.format === "string" ? ` \u8F93\u51FA: ${c.output.format}${c.output.description ? `\uFF08${c.output.description}\uFF09` : ""}` : "";
+  const exitText = c.exitCodes && typeof c.exitCodes === "object" && Object.keys(c.exitCodes).length > 0 ? ` \u9000\u51FA\u7801: ${Object.entries(c.exitCodes).map(([code, desc]) => `${code}=${desc}`).join(", ")}` : "";
+  const safeText = Array.isArray(c.safety) && c.safety.length > 0 ? ` \u5B89\u5168: ${c.safety.join("\uFF1B")}` : "";
+  return `  ${pathText} \u2014 ${c.description}${c.usage ? ` (\u7528\u6CD5: ${c.usage})` : ""}${argText}${optText}${outputText}${exitText}${safeText}`;
+}
+var AGENT_HELP_TEXT = [
+  "agent \u5B50\u547D\u4EE4\u4E00\u89C8\uFF1A",
+  "  index    \u5217\u51FA\u5168\u90E8\u547D\u4EE4\uFF08builtin/local/official\uFF09\u4E0E agent \u5143\u6570\u636E\uFF1B--json \u8F93\u51FA\u7A33\u5B9A JSON \u6570\u7EC4",
+  "  describe \u67E5\u770B\u5355\u4E2A\u547D\u4EE4\u7684\u5B8C\u6574\u8BB0\u5F55\uFF08\u7528\u6CD5/\u53C2\u6570/\u9009\u9879/\u8F93\u51FA/\u9000\u51FA\u7801/\u5B89\u5168\u6807\u7B7E\uFF09\uFF1B--json \u8F93\u51FA\u5355\u6761\u8BB0\u5F55",
+  "  docs     \u8F93\u51FA\u5F53\u524D @kevlns/v-cli \u5305\u5185\u7F6E AGENTS.md \u539F\u6587\uFF1B--json \u8F93\u51FA { package, version, sha256, content }",
+  "  init     \u628A\u5185\u7F6E AGENTS.md \u5199\u5165\u5DE5\u4F5C\u533A\uFF08\u9ED8\u8BA4\u5F53\u524D\u76EE\u5F55\uFF09\uFF1B\u5DF2\u5B58\u5728\u9ED8\u8BA4\u62D2\u7EDD\uFF0C--force \u8986\u76D6\uFF0C--dry-run \u9884\u89C8",
+  "",
+  "JSON\uFF1A\u6240\u6709\u5B50\u547D\u4EE4\u652F\u6301 --json\uFF08\u6216\u524D\u7F6E\u5168\u5C40 --json\uFF0C\u5982 v-cli --json agent index\uFF09",
+  "",
+  "AI Agent \u5FEB\u901F\u5F00\u59CB\uFF08\u63A8\u8350\u987A\u5E8F\uFF09\uFF1A",
+  "  1. v-cli agent docs",
+  "  2. v-cli agent index --json",
+  "  3. v-cli agent describe <name> --json",
+  "  4. v-cli agent init .          \uFF08\u53EF\u9009\uFF1A\u5199\u5165\u5DE5\u4F5C\u533A AGENTS.md\uFF0CAI Agent \u81EA\u52A8\u8BFB\u53D6\uFF09",
+  "",
+  "\u793A\u4F8B\uFF1A",
+  "  v-cli agent index --json            # \u5168\u91CF\u547D\u4EE4\u7D22\u5F15",
+  "  v-cli agent describe ts --json      # \u5355\u547D\u4EE4\u8BE6\u60C5",
+  "  v-cli agent docs                    # \u5185\u7F6E\u5F15\u5BFC\u6587\u6863\u539F\u6587",
+  "  v-cli agent init . --dry-run        # \u9884\u89C8\u521D\u59CB\u5316\u76EE\u6807"
+].join("\n");
+var DOCS_HELP_TEXT = [
+  "\u8F93\u51FA\u5F53\u524D\u5B89\u88C5\u7684 @kevlns/v-cli \u5305\u5185\u7F6E AGENTS.md \u539F\u6587\uFF08AI Agent \u5F15\u5BFC\u6587\u6863\uFF09\uFF0C\u9010\u5B57\u8282\u539F\u6837\u8F93\u51FA\u3001\u4E0D\u8FFD\u52A0\u6362\u884C\u3002",
+  "",
+  "JSON \u884C\u4E3A\uFF08--json \u6216\u524D\u7F6E\u5168\u5C40 --json\uFF09\uFF1A",
+  "  \u6210\u529F\uFF1Astdout \u8F93\u51FA\u7A33\u5B9A\u5BF9\u8C61 { package, version, sha256, content }",
+  "    package  \u5305\u540D @kevlns/v-cli",
+  "    version  \u5F53\u524D\u5305\u7248\u672C",
+  "    sha256   content \u7684 SHA-256\uFF08hex\uFF09\uFF0C\u53EF\u6821\u9A8C\u5F15\u5BFC\u6587\u6863\u672A\u88AB\u7BE1\u6539",
+  "    content  AGENTS.md \u539F\u6587",
+  "  \u5931\u8D25\uFF1Astdout \u8F93\u51FA\u7A00\u758F\u5BF9\u8C61 { ok: false, error }\uFF0Cstderr \u518D\u8F93\u51FA\u540C\u4E00 error\uFF0C\u9000\u51FA\u7801 1",
+  "",
+  "\u9000\u51FA\u7801\uFF1A0 \u6210\u529F\uFF1B1 \u5185\u7F6E AGENTS.md \u7F3A\u5931/\u4E0D\u53EF\u8BFB",
+  "",
+  "\u793A\u4F8B\uFF1A",
+  "  v-cli agent docs",
+  "  v-cli agent docs --json"
+].join("\n");
+var INIT_HELP_TEXT = [
+  "\u628A\u5F53\u524D @kevlns/v-cli \u5305\u5185\u7F6E AGENTS.md \u539F\u6837\u5199\u5165 <\u76EE\u5F55>/AGENTS.md\uFF0CAI Agent \u4F1A\u81EA\u52A8\u8BFB\u53D6\u5DE5\u4F5C\u533A\u6587\u6863\u3002",
+  "",
+  "\u53C2\u6570\uFF1A",
+  "  [directory]  \u76EE\u6807\u76EE\u5F55\uFF0C\u9ED8\u8BA4\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55\uFF1B\u5FC5\u987B\u5DF2\u5B58\u5728\u4E14\u4E3A\u76EE\u5F55",
+  "",
+  "\u9ED8\u8BA4\u884C\u4E3A\uFF08\u65E0 --force\uFF09\uFF1A\u76EE\u6807\u5DF2\u5B58\u5728 AGENTS.md \u65F6\u62D2\u7EDD\u5E76\u9000\u51FA 1\uFF0C\u7EDD\u4E0D\u6539\u52A8\u73B0\u6709\u6587\u4EF6\u3002",
+  "  --force    \u8986\u76D6\u5DF2\u5B58\u5728\u7684 AGENTS.md\uFF08\u539F\u5B50\u5199\u5165\uFF1A\u540C\u76EE\u5F55\u4E34\u65F6\u6587\u4EF6 + rename\uFF09",
+  "  --dry-run  \u53EA\u62A5\u544A\u76EE\u6807\u4E0E\u5C06\u6267\u884C\u7684\u52A8\u4F5C\uFF0C\u4E0D\u5199\u5165\u4EFB\u4F55\u6587\u4EF6",
+  "  --json     \u6210\u529F/\u5E72\u8DD1\u8F93\u51FA\u7A33\u5B9A JSON { ok, dryRun, action, directory, target, package, version, sha256, bytes }\uFF1B",
+  '             \u62D2\u7EDD\uFF08\u5982\u5DF2\u5B58\u5728\u672A\u52A0 --force\uFF09\u8F93\u51FA { ok: false, action: "refused", reason, \u2026 } \u4E14\u9000\u51FA 1\uFF1B',
+  "             \u5185\u7F6E\u6587\u6863\u7F3A\u5931\u65F6\u8F93\u51FA\u7A00\u758F { ok: false, error } \u4E14\u9000\u51FA 1",
+  "  \u7B26\u53F7\u94FE\u63A5\u89C4\u5219\uFF1A\u76EE\u6807 AGENTS.md \u662F\u7B26\u53F7\u94FE\u63A5\u4E00\u5F8B\u62D2\u7EDD\uFF08fail-closed\uFF1A\u4E0D\u8DDF\u968F\u3001\u4E0D\u8986\u76D6\u94FE\u63A5\u76EE\u6807\uFF09\uFF1B",
+  "             \u663E\u5F0F\u4F20\u5165\u7684\u76EE\u5F55\u672C\u8EAB\u662F\u7B26\u53F7\u94FE\u63A5/\u8054\u63A5\u76EE\u5F55\uFF08junction\uFF09\u4E5F\u62D2\u7EDD\uFF1B\u7701\u7565\u76EE\u5F55\u53C2\u6570\uFF08\u9ED8\u8BA4\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55\uFF09\u4E0D\u53D7\u6B64\u9650\u5236",
+  "",
+  "\u9000\u51FA\u7801\uFF1A0 \u6210\u529F\u6216\u5E72\u8DD1\uFF1B1 \u76EE\u5F55\u65E0\u6548 / \u5DF2\u5B58\u5728\u672A\u52A0 --force / \u7B26\u53F7\u94FE\u63A5\u6216\u8054\u63A5\u76EE\u6807 / \u5185\u7F6E\u6587\u6863\u7F3A\u5931 / \u5199\u5165\u5931\u8D25",
+  "",
+  "\u793A\u4F8B\uFF1A",
+  "  v-cli agent init",
+  "  v-cli agent init ./myproj",
+  "  v-cli agent init --dry-run",
+  "  v-cli agent init --force",
+  "  v-cli agent init --json"
+].join("\n");
+var agent = {
+  name: "agent",
+  description: "agent\uFF1Aindex \u547D\u4EE4\u7D22\u5F15\uFF0Cdescribe \u8BE6\u60C5\uFF0Cdocs \u5185\u7F6E AGENTS.md\uFF0Cinit \u5DE5\u4F5C\u533A\u5F15\u5BFC",
+  apiVersion: 1,
+  agent: {
+    whenToUse: "\u5F53\u7528\u6237\u9700\u8981 AGENTS \u5F15\u5BFC\u6587\u6863\u3001\u547D\u4EE4\u53D1\u73B0\u6216\u4E3A AI Agent \u521D\u59CB\u5316\u5DE5\u4F5C\u533A\u65F6\uFF1A\u5148 `docs` \u8BFB\u5185\u7F6E AGENTS.md\uFF0C\u518D `index --json` \u679A\u4E3E\u5168\u90E8\u547D\u4EE4\u4E0E\u5143\u6570\u636E\uFF0C\u7528 `describe <name> --json` \u770B\u5355\u547D\u4EE4\u8BE6\u60C5\uFF0C\u6700\u540E\u53EF `init` \u628A AGENTS.md \u5199\u5165\u5DE5\u4F5C\u533A",
+    globalOptions: [
+      { flags: "-h, --help", description: "\u663E\u793A\u547D\u4EE4\u5E2E\u52A9" }
+    ],
+    commands: [
+      {
+        path: ["index"],
+        usage: "v-cli agent index [--json]",
+        description: "\u5217\u51FA\u5168\u90E8\u547D\u4EE4\uFF08builtin/local/official\uFF09\u4E0E agent \u5143\u6570\u636E",
+        arguments: [],
+        options: [{ flags: "--json", description: "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON" }],
+        output: {
+          format: "stdout",
+          description: "\u6B63\u6587\u8F93\u51FA\u5230 stdout\uFF1B--json \u65F6\u8F93\u51FA\u7A33\u5B9A JSON \u6570\u7EC4\uFF08name/type/description/metadataStatus/commands/\u2026\uFF09"
+        },
+        exitCodes: { "0": "\u6210\u529F" },
+        safety: ["read-only", "no-network"]
+      },
+      {
+        path: ["describe"],
+        usage: "v-cli agent describe <name> [--json]",
+        description: "\u67E5\u770B\u5355\u4E2A\u547D\u4EE4\u7684\u5B8C\u6574\u8BB0\u5F55",
+        arguments: [{ name: "name", required: true, description: "\u547D\u4EE4\u540D\uFF08builtin/local/official\uFF09" }],
+        options: [{ flags: "--json", description: "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON" }],
+        output: { format: "stdout", description: "\u6B63\u6587\u8F93\u51FA\u5230 stdout\uFF1B--json \u65F6\u8F93\u51FA\u5355\u6761\u7A33\u5B9A JSON \u5BF9\u8C61" },
+        exitCodes: { "0": "\u6210\u529F", "1": "\u672A\u627E\u5230\u547D\u4EE4\uFF08stderr \u8BF4\u660E\uFF09" },
+        safety: ["read-only"]
+      },
+      {
+        path: ["docs"],
+        usage: "v-cli agent docs [--json]",
+        description: "\u8F93\u51FA\u5F53\u524D @kevlns/v-cli \u5305\u5185\u7F6E AGENTS.md \u539F\u6587",
+        arguments: [],
+        options: [{ flags: "--json", description: "\u8F93\u51FA { package, version, sha256, content }" }],
+        output: {
+          format: "stdout",
+          description: "AGENTS.md \u539F\u6587\u9010\u5B57\u8282\u8F93\u51FA\u5230 stdout\uFF1B--json \u65F6\u8F93\u51FA\u542B sha256/content \u7684\u7A33\u5B9A JSON"
+        },
+        exitCodes: { "0": "\u6210\u529F", "1": "\u5185\u7F6E AGENTS.md \u7F3A\u5931/\u4E0D\u53EF\u8BFB" },
+        safety: ["read-only", "no-network"]
+      },
+      {
+        path: ["init"],
+        usage: "v-cli agent init [directory] [--force] [--dry-run] [--json]",
+        description: "\u628A\u5185\u7F6E AGENTS.md \u5199\u5165 <\u76EE\u5F55>/AGENTS.md\uFF1B\u9ED8\u8BA4\u5F53\u524D\u76EE\u5F55\uFF1B\u5DF2\u5B58\u5728\u9ED8\u8BA4\u62D2\u7EDD",
+        arguments: [
+          { name: "directory", required: false, description: "\u76EE\u6807\u76EE\u5F55\uFF08\u9ED8\u8BA4\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55\uFF1B\u987B\u5DF2\u5B58\u5728\u4E14\u4E3A\u76EE\u5F55\uFF09" }
+        ],
+        options: [
+          { flags: "--force", description: "\u8986\u76D6\u5DF2\u5B58\u5728 AGENTS.md\uFF08\u539F\u5B50\u5199\u5165\uFF09" },
+          { flags: "--dry-run", description: "\u53EA\u62A5\u544A\u76EE\u6807\u4E0E\u52A8\u4F5C\uFF0C\u4E0D\u5199\u5165" },
+          { flags: "--json", description: "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB\u7ED3\u679C" }
+        ],
+        output: {
+          format: "stdout",
+          description: "\u7ED3\u679C\u6587\u672C\u8F93\u51FA\u5230 stdout\uFF1B--json \u65F6\u8F93\u51FA\u7A33\u5B9A JSON\uFF08ok/dryRun/action/directory/target/package/version/sha256/bytes\uFF09"
+        },
+        exitCodes: {
+          "0": "\u6210\u529F\u6216\u5E72\u8DD1",
+          "1": "\u76EE\u5F55\u65E0\u6548 / \u5DF2\u5B58\u5728\u672A\u8986\u76D6 / \u7B26\u53F7\u94FE\u63A5\u6216\u8054\u63A5\u76EE\u6807 / \u6587\u6863\u7F3A\u5931 / \u5199\u5165\u5931\u8D25"
+        },
+        safety: [
+          "writes-target-atomic",
+          "refuses-existing",
+          "fail-closed-symlink",
+          "dry-run-supported",
+          "no-commit"
+        ]
+      }
+    ]
+  },
+  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) lines.push(describeCommandLine(c));
+      }
+      ctx.log.result(lines.join("\n"));
+    });
+    program.command("docs").description("\u8F93\u51FA\u5F53\u524D @kevlns/v-cli \u5305\u5185\u7F6E AGENTS.md \u539F\u6587\uFF08AI Agent \u5F15\u5BFC\u6587\u6863\uFF09").option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON\uFF08\u542B sha256/content\uFF09").addHelpText("after", DOCS_HELP_TEXT).action((opts) => {
+      const json = ctx.json || opts.json;
+      let docs;
+      try {
+        docs = readBundledAgentsMd();
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (json) ctx.log.result({ ok: false, error: message });
+        ctx.log.error(message);
+        process.exitCode = 1;
+        return;
+      }
+      if (json) {
+        ctx.log.result({
+          package: BUNDLED_DOCS_PACKAGE,
+          version: VERSION,
+          sha256: docs.sha256,
+          content: docs.content
+        });
+        return;
+      }
+      process.stdout.write(docs.content);
+    });
+    program.command("init").description("\u521D\u59CB\u5316 <\u76EE\u5F55>/AGENTS.md\uFF08\u9ED8\u8BA4\u5F53\u524D\u76EE\u5F55\uFF09\uFF1B\u5DF2\u5B58\u5728\u9ED8\u8BA4\u62D2\u7EDD\uFF0C--force \u8986\u76D6\uFF0C--dry-run \u9884\u89C8").argument("[directory]", "\u76EE\u6807\u76EE\u5F55\uFF08\u9ED8\u8BA4\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55\uFF1B\u5FC5\u987B\u5DF2\u5B58\u5728\u4E14\u4E3A\u76EE\u5F55\uFF09").option("--force", "\u8986\u76D6\u5DF2\u5B58\u5728\u7684 AGENTS.md\uFF08\u539F\u5B50\u5199\u5165\uFF09").option("--dry-run", "\u53EA\u62A5\u544A\u76EE\u6807\u4E0E\u52A8\u4F5C\uFF0C\u4E0D\u5199\u5165\u4EFB\u4F55\u6587\u4EF6").option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB\u7ED3\u679C").addHelpText("after", INIT_HELP_TEXT).action(
+      (directory, opts) => {
+        const json = ctx.json || opts.json;
+        let docs;
+        try {
+          docs = readBundledAgentsMd();
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          if (json) ctx.log.result({ ok: false, error: message });
+          ctx.log.error(message);
+          process.exitCode = 1;
+          return;
+        }
+        const result = performAgentInit({
+          directory: path5.resolve(directory ?? process.cwd()),
+          docs,
+          force: opts.force,
+          dryRun: opts.dryRun,
+          // 显式传入目录才做目录符号链接/联接 fail-closed；默认 cwd 不受限
+          explicitDirectory: directory !== void 0
+        });
+        if (json) {
+          ctx.log.result(result);
+          if (!result.ok && result.reason) ctx.log.error(result.reason);
+          if (!result.ok) process.exitCode = 1;
+          return;
+        }
+        if (!result.ok) {
+          if (result.reason) ctx.log.error(result.reason);
+          process.exitCode = 1;
+          return;
+        }
+        if (result.dryRun) {
+          ctx.log.result(
+            `[dry-run] \u5C06${result.action === "overwrite" ? "\u8986\u76D6" : "\u5199\u5165"} ${result.target}\uFF08${result.bytes} \u5B57\u8282\uFF09`
+          );
+        } else {
+          ctx.log.result(
+            `\u5DF2${result.action === "overwritten" ? "\u8986\u76D6" : "\u5199\u5165"} ${result.target}\uFF08${result.bytes} \u5B57\u8282\uFF0CSHA-256 ${result.sha256.slice(0, 12)}\u2026\uFF09`
+          );
+        }
+      }
+    );
+    program.addHelpText("after", AGENT_HELP_TEXT);
+  }
+};
 
 // src/commands/doctor.ts
+import fs4 from "fs";
 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 = fs4.existsSync(homeDir);
       let configWritable = false;
       try {
         ctx.config.set((cfg) => cfg);
@@ -113,6 +1153,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 +1168,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 +1181,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 path6 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 +1208,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 = path6.join(ctx.homeDir, "commands");
+      if (ctx.json || opts.json) {
         ctx.log.result({ dir });
       } else {
         ctx.log.result(dir);
@@ -192,8 +1264,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 +1276,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 +1287,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 = path7.join(ctx.homeDir, "commands");
   const loaded = [];
-  if (!fs3.existsSync(dir)) return loaded;
-  const files = fs3.readdirSync(dir).filter((f) => f.endsWith(".mjs")).sort();
+  if (!fs5.existsSync(dir)) return loaded;
+  const files = fs5.readdirSync(dir).filter((f) => f.endsWith(".mjs")).sort();
   for (const file of files) {
-    const abs = path4.join(dir, file);
+    const abs = path7.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 +1333,132 @@ 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();
+  program.addHelpText(
+    "after",
+    [
+      "AI Agent \u5FEB\u901F\u5F00\u59CB\uFF08\u63A8\u8350\u987A\u5E8F\uFF09\uFF1A",
+      "  1. v-cli agent docs",
+      "  2. v-cli agent index --json",
+      "  3. v-cli agent describe <name> --json",
+      "  4. v-cli agent init .            \uFF08\u53EF\u9009\uFF1A\u5199\u5165\u5DE5\u4F5C\u533A AGENTS.md\uFF0CAI Agent \u81EA\u52A8\u8BFB\u53D6\uFF09",
+      "",
+      "\u8BE6\u60C5\u89C1 `v-cli agent --help`\uFF1B\u5355\u547D\u4EE4\u8BF4\u660E\u4E66\uFF1A`v-cli agent docs --help` / `v-cli agent init --help`\u3002"
+    ].join("\n")
+  );
   const loaded = await loadAllCommands(ctx);
   for (const item of loaded) {
     if (!item.command) {
@@ -273,12 +1467,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;