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

package/AGENTS.md

@@ -7,10 +7,12 @@
 
 ## 核心约定（v-cli 本体）
 
-- 环境要求 Node.js >= 20；v-cli 版本 @kevlns/v-cli@0.2.0-beta.1
+- 环境要求 Node.js >= 20；v-cli 版本 @kevlns/v-cli@0.2.0-beta.2
 - 命令分三类：builtin（内置）、local（~/.v-cli/commands/ 下的本地插件）、official（官方插件白名单）；
   **最新、live 的命令集合以实际发现为准**：先运行 `v-cli agent index --json` 获取全部命令与 agent 元数据
 - 单个命令的完整元数据用 `v-cli agent describe <命令名> --json` 查看
+- AI Agent 引导文档：`v-cli agent docs` 输出本文件原文（`--json` 含 sha256/content）；
+  `v-cli agent init .` 把它写入工作区（已存在默认拒绝，`--force` 覆盖，`--dry-run` 预览；符号链接目标 fail-closed）
 - 官方插件命令（`v-cli xlmerge …`、`v-cli unity …`）在子进程中运行（stdio 继承）：v-cli 只做路由，
   不解析、不改写插件的 stdout/stderr；插件 `--help`/`--json` 等参数由插件自己消费
 - 插件对 worktree 的写入/提交行为以插件清单 v-cli.plugin.json 的 `agent.safety` 为准：

package/README.md

@@ -26,7 +26,7 @@ v-cli 让你**用一个命令沉淀所有个人小工具**，而不用为每个
 - **官方插件白名单** - `@kevlns/xlmerge`（`xlmerge`）与 `@kevlns/u-cli-mod`（`unity`）是唯一被路由的官方插件，安装后在子进程中运行
 - **容错加载** - 单个插件语法错误、契约不符或注册异常只会被跳过并报告，绝不阻断其他命令
 - **双通道输出** - 结果走 stdout（可管道、可脚本化），诊断走 stderr
-- **agent 友好** - `agent index/describe` 输出统一索引与完整元数据；仓库内 AGENTS.md 自动生成并有漂移检查
+- **agent 友好** - `agent docs`/`agent init` 让 AI Agent 自举读取引导文档；`agent index/describe` 输出统一索引与完整元数据；仓库内 AGENTS.md 自动生成并有漂移检查
 - **TypeScript-first** - 严格类型编写，tsup 将核心逻辑打包为单文件 ESM，仅保留 `commander` 运行依赖
 
 ## Getting started
@@ -51,10 +51,33 @@ npm install -g git+https://github.com/kevlns/v-cli.git
 v-cli doctor          # 环境体检：node/版本、主目录、配置、官方/本地插件状态
 v-cli plugin list     # 列出内置命令、本地插件与官方插件状态
 v-cli ts 1710000000   # 时间戳互转
+v-cli agent docs      # 输出当前安装包内置 AGENTS.md 原文（AI Agent 引导文档）
 v-cli agent index     # 命令 + agent 元数据索引（--json 输出机器可读）
 v-cli agent describe xlmerge --json
+v-cli agent init .    # （可选）把 AGENTS.md 初始化到当前目录
 ```
 
+### AI Agent 快速开始
+
+v-cli 内置 AGENTS.md 随包发布，AI Agent 可自行发现并读取引导文档，无需人工粘贴：
+
+```bash
+v-cli agent docs                    # 读当前包内置 AGENTS.md 原文（--json 拿 package/version/sha256/content）
+v-cli agent index --json            # 枚举全部命令 + 元数据（builtin/local/official，live 发现）
+v-cli agent describe <name> --json  # 单命令：用法/参数/选项/输出/退出码/安全标签
+v-cli agent init .                  # （可选）把 AGENTS.md 写入工作区，AI Agent 自动读取
+```
+
+`agent docs` 文本模式逐字节输出内置 AGENTS.md，`--json` 输出稳定对象
+`{ package, version, sha256, content }`。
+
+`agent init [directory]`（默认当前目录；目录必须已存在且为目录）：
+
+- 已存在 AGENTS.md 时**默认拒绝并退出 1，绝不改动现有文件**（`--force` 才原子覆盖）；
+- `--dry-run` 只报告目标与将执行的动作，不写入任何文件；
+- 符号链接目标一律 fail-closed 拒绝（不跟随、不覆盖链接目标）；
+- `--json` 输出稳定结果（`ok/dryRun/action/directory/target/sha256/bytes/…`）。
+
 ### 控制器命令（官方插件）
 
 ```bash
@@ -106,7 +129,7 @@ v-cli --json ts 1710000000 | jq .seconds   # 前置全局 --json 同样生效
 ## `--json` 语义（v-cli 0.2）
 
 - **前置全局**：`v-cli --json <cmd> …` —— `--json` 出现在首个命令词之前时被 v-cli 消费，`ctx.json` 为真
-- **命令自有**：`<cmd> --json …` —— 属于该命令：内置命令（`ts`、`doctor`、`plugin list`、`agent index`、`agent describe`）各自声明 `--json` 并消费；官方插件命令则**原样转发**给插件
+- **命令自有**：`<cmd> --json …` —— 属于该命令：内置命令（`ts`、`doctor`、`plugin list`、`agent index`、`agent describe`、`agent docs`、`agent init`）各自声明 `--json` 并消费；官方插件命令则**原样转发**给插件
 - 其他中间位置（如 `v-cli plugin --json list`）不承诺 JSON 输出
 - 插件转发示例：`v-cli xlmerge detect --json` 会把 `--json` 转给 xlmerge；`v-cli --json xlmerge detect` 则消费掉全局 `--json`、只转发 `detect`
 
@@ -122,6 +145,8 @@ v-cli --json ts 1710000000 | jq .seconds   # 前置全局 --json 同样生效
 | `v-cli ts [value]` | 无参=当前时间；数字（秒/毫秒自动识别）=转可读时间；日期串=转时间戳 |
 | `v-cli agent index [--json]` | 全部命令的 agent 索引（builtin/local/official，含元数据状态） |
 | `v-cli agent describe <name> [--json]` | 单个命令的完整记录；未找到时 stderr 报错并退出 1 |
+| `v-cli agent docs [--json]` | 输出当前包内置 AGENTS.md 原文；`--json` 输出 `{ package, version, sha256, content }`；缺失时退出 1 |
+| `v-cli agent init [directory] [--force] [--dry-run] [--json]` | 把内置 AGENTS.md 写入目录（默认 cwd）；已存在默认拒绝退出 1，`--force` 原子覆盖，`--dry-run` 只报告 |
 
 ### 插件契约 `CliCommand`（apiVersion 1）
 
@@ -191,7 +216,7 @@ kevlns 工具家族共享同一套发布约定（tag 驱动、CI 护栏、MIT）
 
 | Package | Purpose | Status |
 | --- | --- | --- |
-| [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI（本仓库） | v0.2.0-beta.1 |
+| [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI（本仓库） | v0.2.0-beta.2 |
 | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具 | v1.2.1-beta.2 |
 | [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包（Windows-first） | v0.1.0-beta.2 |
 

package/dist/cli.mjs

@@ -75,8 +75,8 @@ function defaultHomeDir() {
 }
 
 // src/core/loader.ts
-import fs4 from "fs";
-import path5 from "path";
+import fs5 from "fs";
+import path7 from "path";
 import { pathToFileURL } from "url";
 
 // src/core/official.ts
@@ -554,6 +554,27 @@ function validateAgentMeta(agent2, errors) {
         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`);
+        }
       });
     }
   }
@@ -596,6 +617,193 @@ function validateLocalCommand(candidate, options = {}) {
   return { ok: true, command: candidate, errors: [] };
 }
 
+// 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.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 = [];
@@ -659,10 +867,153 @@ function rowToText(row) {
   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 \u7D22\u5F15\uFF1Aindex \u5217\u51FA\u5168\u90E8\u547D\u4EE4\u53CA\u5143\u6570\u636E\uFF0Cdescribe \u67E5\u770B\u5355\u4E2A\u547D\u4EE4\u8BE6\u60C5",
+  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;
@@ -704,27 +1055,82 @@ var agent = {
       }
       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}`
-          );
-        }
+        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 fs3 from "fs";
-
-// src/version.ts
-var VERSION = "0.2.0-beta.1";
-
-// 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",
@@ -733,7 +1139,7 @@ var doctor = {
     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 = fs3.existsSync(homeDir);
+      const exists = fs4.existsSync(homeDir);
       let configWritable = false;
       try {
         ctx.config.set((cfg) => cfg);
@@ -787,7 +1193,7 @@ var doctor = {
 };
 
 // src/commands/plugin.ts
-import path4 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",
@@ -826,7 +1232,7 @@ var plugin = {
       }
     });
     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");
+      const dir = path6.join(ctx.homeDir, "commands");
       if (ctx.json || opts.json) {
         ctx.log.result({ dir });
       } else {
@@ -894,12 +1300,12 @@ async function loadBuiltinCommands() {
   return builtinCommands.map((command) => ({ command, source: "builtin" }));
 }
 async function loadLocalPlugins(ctx) {
-  const dir = path5.join(ctx.homeDir, "commands");
+  const dir = path7.join(ctx.homeDir, "commands");
   const loaded = [];
-  if (!fs4.existsSync(dir)) return loaded;
-  const files = fs4.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 = path5.join(dir, file);
+    const abs = path7.join(dir, file);
     try {
       const mod = await import(
         /* @vite-ignore */
@@ -1041,6 +1447,18 @@ async function main() {
   if (intercepted !== void 0) return intercepted;
   const program = new Command();
   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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kevlns/v-cli",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.2",
   "description": "kevlns 的个人工具箱 CLI（插件化架构，内置 + 本地插件）+ doctor/plugin/ts 命令",
   "type": "module",
   "bin": {