@vetta-org/plugin-cli 0.1.5 → 0.1.7

package/dist/index.js

@@ -11904,6 +11904,18 @@ var agentExperimentalSettingsUpdateType = Type.Object({
   promptPrediction: Type.Optional(Type.Boolean()),
   agentSkills: Type.Optional(Type.Boolean())
 }, { additionalProperties: false, minProperties: 1 });
+var imageGenerationSettingsType = Type.Object({
+  textToImageProviderId: Type.Optional(Type.String({ minLength: 1, maxLength: 129 })),
+  textToImageModelId: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+  imageToImageProviderId: Type.Optional(Type.String({ minLength: 1, maxLength: 129 })),
+  imageToImageModelId: Type.Optional(Type.String({ minLength: 1, maxLength: 256 }))
+}, { additionalProperties: false });
+var imageGenerationSettingsUpdateType = Type.Object({
+  textToImageProviderId: Type.Optional(Type.Union([Type.String({ minLength: 1, maxLength: 129 }), Type.Null()])),
+  textToImageModelId: Type.Optional(Type.Union([Type.String({ minLength: 1, maxLength: 256 }), Type.Null()])),
+  imageToImageProviderId: Type.Optional(Type.Union([Type.String({ minLength: 1, maxLength: 129 }), Type.Null()])),
+  imageToImageModelId: Type.Optional(Type.Union([Type.String({ minLength: 1, maxLength: 256 }), Type.Null()]))
+}, { additionalProperties: false, minProperties: 1 });
 var agentSettingsEmptyInputSchema = defineCapabilityInputSchema(agentSettingsEmptyInputType);
 var agentExperimentalSettingsSchema = defineCapabilityOutputSchema(agentExperimentalSettingsType, { clean: true });
 var agentExperimentalSettingsUpdateSchema = defineCapabilityInputSchema(agentExperimentalSettingsUpdateType);
@@ -11923,6 +11935,22 @@ var DOMAIN_AGENT_SETTINGS_CAPABILITIES = {
     version: 1,
     input: agentExperimentalSettingsUpdateSchema,
     output: agentExperimentalSettingsSchema
+  }),
+  GET_IMAGE_GENERATION: defineCapability({
+    id: "cap.domain.vetta.agent-settings.image-generation.get",
+    kind: "query",
+    layer: CAPABILITY_LAYERS.DOMAIN,
+    version: 1,
+    input: agentSettingsEmptyInputSchema,
+    output: defineCapabilityOutputSchema(imageGenerationSettingsType, { clean: true })
+  }),
+  SET_IMAGE_GENERATION: defineCapability({
+    id: "cap.domain.vetta.agent-settings.image-generation.set",
+    kind: "command",
+    layer: CAPABILITY_LAYERS.DOMAIN,
+    version: 1,
+    input: defineCapabilityInputSchema(imageGenerationSettingsUpdateType),
+    output: defineCapabilityOutputSchema(imageGenerationSettingsType, { clean: true })
   })
 };
 var DOMAIN_AGENT_SETTINGS_CAPABILITY_CATALOG = createCapabilityCatalog(Object.values(DOMAIN_AGENT_SETTINGS_CAPABILITIES));
@@ -13028,7 +13056,7 @@ var FOUNDATION_JOB_CAPABILITIES = {
 var FOUNDATION_JOB_CAPABILITY_CATALOG = createCapabilityCatalog(Object.values(FOUNDATION_JOB_CAPABILITIES));
 
 // ../../capability-sdk/dist/domain/media.js
-var MEDIA_PROTOCOL_VERSION = 4;
+var MEDIA_PROTOCOL_VERSION = 5;
 var MEDIA_OPERATIONS = {
   GENERATE: "generate",
   COMPOSE: "compose",
@@ -13127,6 +13155,16 @@ var mediaGenerationModeCapabilityType = Type.Object({
   aspectRatioPolicy: Type.Optional(Type.Union([Type.Literal("configurable"), Type.Literal("input-derived")])),
   audioGeneration: Type.Optional(Type.Union([Type.Literal("none"), Type.Literal("always"), Type.Literal("optional")]))
 }, { additionalProperties: false });
+var mediaGenerationModelDescriptorType = Type.Object({
+  id: requiredStringType2,
+  displayName: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
+  sourceId: Type.Optional(requiredStringType2),
+  sourceDisplayName: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
+  modes: Type.Array(mediaGenerationModeType, { minItems: 1 }),
+  aspectRatios: Type.Optional(Type.Array(requiredStringType2)),
+  resolutions: Type.Optional(Type.Array(requiredStringType2)),
+  defaultResolution: Type.Optional(requiredStringType2)
+}, { additionalProperties: false });
 var mediaGenerateCapabilityType = Type.Object({
   operation: Type.Literal(MEDIA_OPERATIONS.GENERATE),
   kind: mediaGenerationKindType,
@@ -13134,6 +13172,8 @@ var mediaGenerateCapabilityType = Type.Object({
   aspectRatios: Type.Optional(Type.Array(requiredStringType2)),
   resolutions: Type.Optional(Type.Array(requiredStringType2)),
   defaultResolution: Type.Optional(requiredStringType2),
+  models: Type.Optional(Type.Array(mediaGenerationModelDescriptorType, { minItems: 1 })),
+  defaultModelId: Type.Optional(requiredStringType2),
   durationsSeconds: Type.Optional(Type.Array(Type.Number({ exclusiveMinimum: 0 }))),
   modeCapabilities: Type.Optional(Type.Array(mediaGenerationModeCapabilityType))
 }, { additionalProperties: false });
@@ -13317,6 +13357,8 @@ var modelProviderUpsertModelType = Type.Object({
   name: Type.Optional(Type.String()),
   api: Type.Optional(Type.String()),
   reasoning: Type.Optional(Type.Boolean()),
+  reasoningLevels: modelDefinitionDetailType.properties.reasoningLevels,
+  defaultReasoningLevel: modelDefinitionDetailType.properties.defaultReasoningLevel,
   contextWindow: Type.Optional(Type.Number()),
   maxTokens: Type.Optional(Type.Number())
 }, { additionalProperties: false });
@@ -15418,7 +15460,9 @@ var PluginAgentTeamMemberManifestSchema = Type.Object({
   agent: Type.Optional(NonWhitespaceStringSchema),
   role: Type.Optional(PluginAgentRoleSchema),
   responsibility: Type.String({ maxLength: 2000 }),
-  optional: Type.Optional(Type.Boolean())
+  optional: Type.Optional(Type.Boolean()),
+  instructions: Type.Optional(Type.String({ maxLength: 64000 })),
+  instructionsPath: Type.Optional(NonWhitespaceStringSchema)
 }, { additionalProperties: false });
 var PluginAgentTeamManifestSchema = Type.Object({
   id: Type.String({ pattern: "^[a-z0-9][a-z0-9-]{0,63}$" }),
@@ -18920,13 +18964,33 @@ async function resolveNpmPluginArchive(packageSpec, pack = runNpmPack) {
 }
 
 // src/agents-template.ts
-var AGENTS_GUIDE_REVISION = 2;
+var AGENTS_GUIDE_REVISION = 3;
 function readAgentsGuideRevision(content) {
   const match2 = /<!--\s*vetta-guide-revision:\s*(\d+)\s*-->/.exec(content);
   if (!match2)
     return;
   return Number(match2[1]);
 }
+function renderCommands(pluginId, scripts) {
+  const known = [
+    ["dev", "npm run dev            # 开发服务器"],
+    ["build", "npm run build          # 产出 dist/"],
+    ["install:vetta", "npm run install:vetta  # 打包并装进正在运行的 Vetta（需要 Vetta 已启动）"]
+  ];
+  const lines = known.filter(([name]) => scripts.includes(name)).map(([, line]) => line);
+  if (!scripts.includes("install:vetta")) {
+    lines.push("npx vetta-plugin-cli add .       # 打包并装进正在运行的 Vetta");
+  }
+  return [
+    ...lines,
+    "",
+    "npx vetta-plugin-cli watch       # 热更新：宿主改从本工程目录加载，改完即生效",
+    `npx vetta-plugin-cli reload ${pluginId}   # 装完提示有 pending 版本时用它`,
+    "npx vetta-plugin-cli uninstall   # 卸载（省略 id 即本工程对应的插件）",
+    "npx vetta-plugin-cli sync        # 在 hub 仓库根上跑：把索引与各能力目录对账"
+  ].join(`
+`);
+}
 function renderAgentsGuide(input) {
   return `<!-- vetta-guide-revision: ${AGENTS_GUIDE_REVISION} -->
 # ${input.displayName}
@@ -18966,14 +19030,7 @@ npx vetta-plugin-cli docs --check-latest
 ## 常用命令
 
 \`\`\`bash
-npm run dev            # Vite + Module Federation 开发服务器
-npm run build          # 产出 dist/
-npm run install:vetta  # 打包并装进正在运行的 Vetta（需要 Vetta 已启动）
-
-npx vetta-plugin-cli watch       # 热更新：宿主改从本工程目录加载，改完即生效
-npx vetta-plugin-cli reload ${input.pluginId}   # 装完提示有 pending 版本时用它
-npx vetta-plugin-cli uninstall   # 卸载（省略 id 即本工程对应的插件）
-npx vetta-plugin-cli sync        # 在 hub 仓库根上跑：把索引与各能力目录对账
+${renderCommands(input.pluginId, input.scripts ?? ["dev", "build", "install:vetta"])}
 \`\`\`
 
 细节都在 \`getting-started.md\`。\`docs\` 打印了 \`Marketplace index:\` 就说明这个目录之上有能力
@@ -19026,16 +19083,25 @@ npx @vetta-org/plugin-cli init --id <slug> --name "<Display Name>" abilities/plu
 
 ## 索引由工具对账，不要手改派生字段
 
-\`.vetta/marketplace.json\` 里能力的 \`version\`、\`config.api_version\`、\`config.permissions\`、
-\`config.commands\` 全都是从能力包推导出来的。改完能力后：
+改完能力后：
 
 \`\`\`bash
-npx @vetta-org/plugin-cli sync          # 回填派生字段，并推进 marketplaceVersion
+npx @vetta-org/plugin-cli sync          # 对账并回填，看输出
 npx @vetta-org/plugin-cli sync --check  # 只报不写，非零退出（CI 用）
 \`\`\`
 
+\`sync\` 到底做什么，分三档看清楚——它不是万能的：
+
+| 字段 | \`sync\` 的行为 |
+| --- | --- |
+| 条目 \`version\` | **回填**成能力包里的版本 |
+| \`marketplaceVersion\` | 内容有变化时**尝试**推进。只认 semver（\`1.2.3\`）和纯整数；\`YYYY.MM.DD-NN\` 之类的格式推不动，会报出来要你手改 |
+| \`config.api_version\` / \`config.permissions\` / \`config.commands\` | **不写**。宿主建目录时用 \`plugin.json\` 整个重算 \`config\`，索引里的副本读都不读。已经存在且与真源不符时 \`sync\` 会提醒你删掉或改对 |
+
+所以 \`sync\` 跑完要看输出：它报出来的问题（尤其是推不动的 \`marketplaceVersion\`）没人会替你处理。
+
 要**手写**的只有身份与展示：\`slug\`、\`name\`、\`description\`、\`source.path\`、\`category\`、\`tags\`、
-\`detail\`。新能力上架时手动加一条这样的条目，其余字段交给 \`sync\`。
+\`detail\`。新能力上架时手动加一条这样的条目。
 
 三条容易踩的约束，\`sync --check\` 会替你守住：
 
@@ -19045,7 +19111,7 @@ npx @vetta-org/plugin-cli sync --check  # 只报不写，非零退出（CI 用
 | \`plugin.json\` 的 \`entry\` / \`styles\` 必须在已发布目录里真实存在 | 本地能装，市场上装不了 |
 | 改了任何内容必须换 \`marketplaceVersion\` | 客户端不报错、也不更新，用户永远收不到 |
 
-第三条最阴险——它不报错。
+第三条最阴险——它不报错。\`sync\` 只在版本号是 semver 或整数时才推得动，其余格式要你自己换。
 
 ## 为什么插件目录里要提交 \`dist/\`
 
@@ -19213,26 +19279,80 @@ node_modules/
   }
   return { root, pluginId: input.pluginId, files: Object.keys(files).sort() };
 }
-function refreshAgentsGuide(targetDir) {
+function refreshAgentsGuide(targetDir, options = {}) {
   const root = resolve2(targetDir);
+  const file = join3(root, "AGENTS.md");
   const manifestPath = join3(root, "plugin.json");
+  const hubManifestPath = join3(root, ".vetta", "marketplace.json");
+  let kind;
+  let content;
   if (existsSync(manifestPath)) {
     const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
     const pluginId = typeof manifest.id === "string" ? manifest.id : undefined;
     if (!pluginId)
       throw new Error(`plugin.json at ${root} has no id`);
-    const displayName = typeof manifest.name === "string" && manifest.name.length > 0 ? manifest.name : pluginId;
-    writeFileSync(join3(root, "AGENTS.md"), renderAgentsGuide({ pluginId, displayName }), "utf8");
-    return { root, kind: "plugin", file: join3(root, "AGENTS.md") };
+    kind = "plugin";
+    content = renderAgentsGuide({
+      pluginId,
+      displayName: resolveManifestText(manifest.name, root, pluginId),
+      scripts: readPackageScripts(root)
+    });
+  } else if (existsSync(hubManifestPath)) {
+    const manifest = JSON.parse(readFileSync(hubManifestPath, "utf8"));
+    kind = "hub";
+    content = renderHubAgentsGuide({
+      name: typeof manifest.name === "string" && manifest.name.length > 0 ? manifest.name : "marketplace"
+    });
+  } else {
+    throw new Error(`Not a plugin project or marketplace repository: ${root}`);
+  }
+  if (!options.dryRun)
+    assertSafeToOverwrite(file, options.force === true);
+  if (options.dryRun)
+    return { root, kind, file, content, written: false };
+  writeFileSync(file, content, "utf8");
+  return { root, kind, file, content, written: true };
+}
+function assertSafeToOverwrite(file, force) {
+  if (force || !existsSync(file))
+    return;
+  if (readAgentsGuideRevision(readFileSync(file, "utf8")) !== undefined)
+    return;
+  throw new Error(`${file} has no vetta-guide-revision marker, so it looks hand-written rather than scaffolded. ` + "Refusing to overwrite it. Review the new template with `--dry-run`, merge what you want by hand, " + "or pass `--force` to replace the file.");
+}
+function resolveManifestText(raw2, root, fallback) {
+  if (typeof raw2 !== "string" || raw2.length === 0)
+    return fallback;
+  const match2 = /^%([^%]+)%$/.exec(raw2);
+  if (!match2)
+    return raw2;
+  const key = match2[1];
+  const pluginManifest = readJsonFile(join3(root, "plugin.json"));
+  const locale = typeof pluginManifest?.defaultLocale === "string" ? pluginManifest.defaultLocale : "zh";
+  for (const candidate of [locale, "zh", "en"]) {
+    const table = readJsonFile(join3(root, "locales", `${candidate}.json`));
+    const value = table?.[key];
+    if (typeof value === "string" && value.length > 0)
+      return value;
   }
-  const hubManifest = join3(root, ".vetta", "marketplace.json");
-  if (existsSync(hubManifest)) {
-    const manifest = JSON.parse(readFileSync(hubManifest, "utf8"));
-    const name = typeof manifest.name === "string" && manifest.name.length > 0 ? manifest.name : "marketplace";
-    writeFileSync(join3(root, "AGENTS.md"), renderHubAgentsGuide({ name }), "utf8");
-    return { root, kind: "hub", file: join3(root, "AGENTS.md") };
+  return fallback;
+}
+function readPackageScripts(root) {
+  const pkg = readJsonFile(join3(root, "package.json"));
+  const scripts = pkg?.scripts;
+  if (typeof scripts !== "object" || scripts === null || Array.isArray(scripts))
+    return [];
+  return Object.keys(scripts);
+}
+function readJsonFile(path) {
+  if (!existsSync(path))
+    return;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : undefined;
+  } catch {
+    return;
   }
-  throw new Error(`Not a plugin project or marketplace repository: ${root}`);
 }
 var HUB_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 var APP_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
@@ -19292,7 +19412,7 @@ function detectJsonIndent(source) {
   const match2 = /\n([ \t]+)\S/.exec(source);
   return match2?.[1] ?? "\t";
 }
-function readJsonFile(path) {
+function readJsonFile2(path) {
   try {
     const parsed = JSON.parse(readFileSync2(path, "utf8"));
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
@@ -19336,7 +19456,7 @@ function nextMarketplaceVersion(current) {
   return;
 }
 function syncMarketplaceIndex(input) {
-  const manifest = readJsonFile(input.manifestPath);
+  const manifest = readJsonFile2(input.manifestPath);
   if (!manifest)
     throw new Error(`Malformed marketplace manifest: ${input.manifestPath}`);
   const abilities = Array.isArray(manifest.abilities) ? manifest.abilities : [];
@@ -19354,13 +19474,31 @@ function syncMarketplaceIndex(input) {
       for (const member of Array.isArray(bundleConfig?.members) ? bundleConfig.members : []) {
         if (typeof member !== "object" || member === null || Array.isArray(member))
           continue;
-        const memberSource = member.source;
+        const memberEntry = member;
+        const memberSource = memberEntry.source;
         const memberPath = typeof memberSource === "object" && memberSource !== null && !Array.isArray(memberSource) ? memberSource.path : undefined;
         if (typeof memberPath !== "string")
           continue;
         const dir = resolveAbilityDir(input.hubRoot, memberPath);
-        if (dir)
+        if (dir) {
           listedDirs.add(dir);
+          if (manifest.schemaVersion === 3 && memberEntry.type === "plugin") {
+            const descriptor2 = readJsonFile2(join4(dir, "ability.json"));
+            const memberChanges = [];
+            reconcilePlugin({
+              entry: { ...memberEntry, version: descriptor2?.version },
+              slug: typeof memberEntry.slug === "string" ? memberEntry.slug : "(unnamed)",
+              abilityDir: dir,
+              schemaVersion: manifest.schemaVersion,
+              minAppVersion: manifest.minAppVersion,
+              changes: memberChanges,
+              problems
+            });
+            for (const change of memberChanges) {
+              problems.push({ slug: change.slug, message: `ability.json version does not match latest release: ${change.to}` });
+            }
+          }
+        }
       }
       continue;
     }
@@ -19377,7 +19515,7 @@ function syncMarketplaceIndex(input) {
     }
     listedDirs.add(abilityDir);
     if (type === "plugin")
-      reconcilePlugin({ entry, slug, abilityDir, changes, problems });
+      reconcilePlugin({ entry, slug, abilityDir, schemaVersion: manifest.schemaVersion, minAppVersion: manifest.minAppVersion, changes, problems });
     else if (type === "mcp")
       reconcileIdentityFile({ entry, slug, abilityDir, fileName: "mcp.json", changes, problems });
   }
@@ -19404,8 +19542,78 @@ function syncMarketplaceIndex(input) {
   return { manifestPath: input.manifestPath, changes, problems, unlisted, written };
 }
 function reconcilePlugin(context) {
-  const { entry, slug, abilityDir, changes, problems } = context;
-  const manifest = readJsonFile(join4(abilityDir, "plugin.json"));
+  const { entry, slug, abilityDir, schemaVersion, minAppVersion, changes, problems } = context;
+  if (schemaVersion === 3 && !("releases" in entry)) {
+    problems.push({ slug, message: "schemaVersion 3 plugin requires versioned releases" });
+    return;
+  }
+  if ("releases" in entry) {
+    if (schemaVersion !== 3) {
+      problems.push({ slug, message: "versioned plugin releases require marketplace schemaVersion 3" });
+      return;
+    }
+    const releases = entry.releases;
+    if (!Array.isArray(releases) || releases.length === 0) {
+      problems.push({ slug, message: "plugin releases must be a nonempty array" });
+      return;
+    }
+    let latest;
+    const seen = new Set;
+    for (const raw2 of releases) {
+      if (typeof raw2 !== "object" || raw2 === null || Array.isArray(raw2)) {
+        problems.push({ slug, message: "plugin release must be an object" });
+        continue;
+      }
+      const release = raw2;
+      const match2 = typeof release.version === "string" ? /^(\d+)\.(\d+)\.(\d+)$/.exec(release.version) : null;
+      if (!match2 || seen.has(release.version)) {
+        problems.push({ slug, message: `invalid or duplicate plugin release version: ${String(release.version)}` });
+        continue;
+      }
+      seen.add(release.version);
+      const minimum = typeof release.minAppVersion === "string" ? /^(\d+)\.(\d+)\.(\d+)$/.exec(release.minAppVersion) : null;
+      if (!minimum || typeof minAppVersion !== "string" || !/^(\d+)\.(\d+)\.(\d+)$/.test(minAppVersion)) {
+        problems.push({ slug, message: `release ${release.version} has an invalid minAppVersion` });
+      } else {
+        const marketMinimum = /^(\d+)\.(\d+)\.(\d+)$/.exec(minAppVersion);
+        if (marketMinimum && compareVersionParts(minimum.slice(1).map(Number), marketMinimum.slice(1).map(Number)) < 0) {
+          problems.push({ slug, message: `release ${release.version} requires an app older than the marketplace` });
+        }
+      }
+      if (typeof release.pluginApiVersion !== "string" || !/^\^\d+\.\d+\.\d+$/.test(release.pluginApiVersion)) {
+        problems.push({ slug, message: `release ${release.version} has an invalid pluginApiVersion` });
+      }
+      for (const field of ["permissions", "commands"]) {
+        if (release[field] !== undefined && !stringArray(release[field])) {
+          problems.push({ slug, message: `release ${release.version} has invalid ${field}` });
+        }
+      }
+      const parts = [Number(match2[1]), Number(match2[2]), Number(match2[3])];
+      if (!latest || compareVersionParts(parts, latest.parts) > 0) {
+        latest = { version: release.version, parts };
+      }
+      const artifact = release.artifact;
+      if (typeof artifact !== "object" || artifact === null || Array.isArray(artifact)) {
+        problems.push({ slug, message: `release ${release.version} has no artifact` });
+        continue;
+      }
+      const { url, sha256 } = artifact;
+      let validUrl = false;
+      try {
+        const parsed = new URL(String(url));
+        validUrl = parsed.protocol === "https:" && !parsed.username && !parsed.password && !parsed.hash;
+      } catch {}
+      if (!validUrl || typeof sha256 !== "string" || !/^[a-f0-9]{64}$/.test(sha256)) {
+        problems.push({ slug, message: `release ${release.version} has an invalid HTTPS artifact or SHA-256` });
+      }
+    }
+    if (latest && entry.version !== latest.version) {
+      changes.push({ slug, field: "version", from: entry.version, to: latest.version });
+      entry.version = latest.version;
+    }
+    return;
+  }
+  const manifest = readJsonFile2(join4(abilityDir, "plugin.json"));
   if (!manifest) {
     problems.push({ slug, message: "plugin.json is missing or malformed" });
     return;
@@ -19444,9 +19652,16 @@ function reconcilePlugin(context) {
     }
   }
 }
+function compareVersionParts(left, right) {
+  for (let index = 0;index < 3; index += 1) {
+    if (left[index] !== right[index])
+      return (left[index] ?? 0) - (right[index] ?? 0);
+  }
+  return 0;
+}
 function reconcileIdentityFile(context) {
   const { entry, slug, abilityDir, fileName, changes, problems } = context;
-  const identity = readJsonFile(join4(abilityDir, fileName));
+  const identity = readJsonFile2(join4(abilityDir, fileName));
   if (!identity) {
     problems.push({ slug, message: `${fileName} is missing or malformed` });
     return;
@@ -19489,7 +19704,7 @@ function findAbilityDirectories(hubRoot) {
   return found.sort();
 }
 function describeIndexDrift(input) {
-  const manifest = readJsonFile(input.manifestPath);
+  const manifest = readJsonFile2(input.manifestPath);
   if (!manifest || !Array.isArray(manifest.abilities))
     return;
   const entry = manifest.abilities.find((item) => typeof item === "object" && item !== null && !Array.isArray(item) && item.slug === input.slug);
@@ -19575,11 +19790,11 @@ function readManualSdkVersion(manualDir) {
 var HELP_TEXT = `Vetta plugin manager
 
 Usage:
-  vetta-plugin-cli add <npm-package|zip-path|http-url> [--json]
+  vetta-plugin-cli add <npm-package|package-path|http-url> [--json]
   vetta-plugin-cli reload <plugin-id> [--json]
   vetta-plugin-cli docs [--check-latest] [--json]
   vetta-plugin-cli init --id <plugin-id> [--name <display>] [dir] [--json]
-  vetta-plugin-cli init --refresh-guide [dir] [--json]
+  vetta-plugin-cli init --refresh-guide [dir] [--dry-run] [--force] [--json]
   vetta-plugin-cli init hub --name <slug> --repository <url> --min-app-version <x.y.z> [dir]
   vetta-plugin-cli watch [dir] [--stop] [--json]
   vetta-plugin-cli uninstall [plugin-id] [--json]
@@ -19589,7 +19804,7 @@ Examples:
   npx @vetta-org/plugin-cli add @example/vetta-plugin-demo
   npx @vetta-org/plugin-cli add @example/vetta-plugin-demo@1.2.0
   npx @vetta-org/plugin-cli add .                      # 当前插件工程（先 pack）
-  npx @vetta-org/plugin-cli add ./release/demo-1.2.0.zip
+  npx @vetta-org/plugin-cli add ./release/demo-1.2.0.vettapkg
   npx @vetta-org/plugin-cli reload demo
   npx @vetta-org/plugin-cli docs
   npx @vetta-org/plugin-cli init --id my-plugin --name "My Plugin"
@@ -19615,7 +19830,7 @@ function parsePluginAddCommand(argv) {
   }
   const [source, unexpected] = parsed.positionals;
   if (!source)
-    return { type: "error", message: "Missing <npm-package|zip-path|http-url>" };
+    return { type: "error", message: "Missing <npm-package|package-path|http-url>" };
   if (unexpected)
     return { type: "error", message: `Unexpected argument: ${unexpected}` };
   return { type: "add", source, json: parsed.values.json === true };
@@ -19680,7 +19895,9 @@ function parsePluginInitCommand(argv) {
         id: { type: "string" },
         name: { type: "string" },
         json: { type: "boolean" },
-        "refresh-guide": { type: "boolean" }
+        "refresh-guide": { type: "boolean" },
+        force: { type: "boolean" },
+        "dry-run": { type: "boolean" }
       }
     });
   } catch (error) {
@@ -19690,7 +19907,13 @@ function parsePluginInitCommand(argv) {
     const [dir, extra] = parsed.positionals;
     if (extra)
       return { type: "error", message: `Unexpected argument: ${extra}` };
-    return { type: "refresh-guide", ...dir ? { targetDir: dir } : {}, json: parsed.values.json === true };
+    return {
+      type: "refresh-guide",
+      ...dir ? { targetDir: dir } : {},
+      json: parsed.values.json === true,
+      force: parsed.values.force === true,
+      dryRun: parsed.values["dry-run"] === true
+    };
   }
   const pluginId = parsed.values.id;
   if (typeof pluginId !== "string" || pluginId.length === 0) {
@@ -19838,8 +20061,9 @@ function isHttpUrl(source) {
     return false;
   }
 }
-function isLocalZip(source) {
-  if (source.toLowerCase().endsWith(".zip"))
+function isLocalPackage(source) {
+  const lower = source.toLowerCase();
+  if (lower.endsWith(".vettapkg") || lower.endsWith(".zip"))
     return true;
   const path = resolve5(source);
   return existsSync4(path) && !statSync2(path).isDirectory();
@@ -19858,7 +20082,7 @@ function resolveProjectArchive(source) {
     }
     throw new Error(`No plugin.json found in ${from} or any parent directory.`);
   }
-  const archivePath = join6(project.root, "release", `${project.pluginId}-${project.version}.zip`);
+  const archivePath = join6(project.root, "release", `${project.pluginId}-${project.version}.vettapkg`);
   if (!existsSync4(archivePath)) {
     throw new Error(`Packaged archive not found: ${archivePath}
 Build it first: npm run build && npx vetta-plugin pack`);
@@ -19879,6 +20103,7 @@ function indexDriftHint(project) {
 function npmInstallInput(resolved) {
   return {
     operation: "install-from-path",
+    initiator: "plugin-cli",
     path: resolved.archivePath,
     enable: true,
     source: "npm",
@@ -19972,19 +20197,22 @@ async function runPluginCommand(command, dependencies = defaultDependencies) {
     } else if (isHttpUrl(command.source)) {
       result = await dependencies.runAction("plugins.manage", {
         operation: "install-from-url",
+        initiator: "plugin-cli",
         url: command.source
       });
     } else if (isDirectorySource(command.source)) {
       const { archivePath, project } = resolveProjectArchive(command.source);
       result = await dependencies.runAction("plugins.manage", {
         operation: "install-from-path",
+        initiator: "plugin-cli",
         path: archivePath,
         enable: true
       });
       driftHint = indexDriftHint(project);
-    } else if (isLocalZip(command.source)) {
+    } else if (isLocalPackage(command.source)) {
       result = await dependencies.runAction("plugins.manage", {
         operation: "install-from-path",
+        initiator: "plugin-cli",
         path: resolve5(command.source),
         enable: true
       });
@@ -20068,7 +20296,9 @@ async function runDocsCommand(command, dependencies) {
     lines.push(`Manual follows the installed SDK. To refresh it: ${SDK_REFRESH_COMMAND}`);
   }
   if (guide.stale) {
-    lines.push(`This brief is stale (AGENTS.md revision ${guide.revision ?? "unstamped"} < ${AGENTS_GUIDE_REVISION}). Refresh it with: ${GUIDE_REFRESH_COMMAND}`);
+    lines.push(`This brief is stale (AGENTS.md revision ${guide.revision} < ${AGENTS_GUIDE_REVISION}). Refresh it with: ${GUIDE_REFRESH_COMMAND}`);
+  } else if (guide.unstamped) {
+    lines.push(`AGENTS.md has no revision marker, so it looks hand-written. Review the current template with \`${GUIDE_REFRESH_COMMAND} --dry-run\` and merge by hand; do not overwrite it blindly.`);
   }
   if (hub) {
     lines.push(`Marketplace index: ${hub.manifestPath}`);
@@ -20084,17 +20314,18 @@ var GUIDE_REFRESH_COMMAND = "npx @vetta-org/plugin-cli init --refresh-guide";
 function inspectAgentsGuide(root) {
   const path = join6(root, "AGENTS.md");
   if (!existsSync4(path))
-    return { present: false, stale: false };
+    return { present: false, stale: false, unstamped: false };
   let revision;
   try {
     revision = readAgentsGuideRevision(readFileSync4(path, "utf8"));
   } catch {
-    return { present: true, stale: false };
+    return { present: true, stale: false, unstamped: false };
   }
   return {
     present: true,
     ...revision === undefined ? {} : { revision },
-    stale: revision === undefined || revision < AGENTS_GUIDE_REVISION
+    stale: revision !== undefined && revision < AGENTS_GUIDE_REVISION,
+    unstamped: revision === undefined
   };
 }
 function compareSemver(left, right) {
@@ -20117,11 +20348,18 @@ function compareSemver(left, right) {
 function runRefreshGuideCommand(command, dependencies) {
   const cwd = dependencies.cwd?.() ?? process.cwd();
   try {
-    const result = refreshAgentsGuide(resolve5(cwd, command.targetDir ?? "."));
-    dependencies.writeStdout(command.json ? `${JSON.stringify({ ok: true, ...result })}
-` : `Rewrote ${result.file}
-Next: npx vetta-plugin-cli docs --check-latest
+    const result = refreshAgentsGuide(resolve5(cwd, command.targetDir ?? "."), {
+      force: command.force,
+      dryRun: command.dryRun
+    });
+    if (command.json) {
+      dependencies.writeStdout(`${JSON.stringify({ ok: true, ...result })}
 `);
+      return 0;
+    }
+    dependencies.writeStdout(result.written ? `Rewrote ${result.file}
+Next: npx vetta-plugin-cli docs --check-latest
+` : `${result.content}`);
     return 0;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/dist/init.d.ts

@@ -14,10 +14,19 @@ export interface InitPluginResult {
     readonly files: readonly string[];
 }
 export declare function initPluginProject(input: InitPluginInput): InitPluginResult;
+export interface RefreshGuideOptions {
+    /** 覆盖一份没有版本戳的 `AGENTS.md`。缺省拒绝——没有戳的多半是手写的。 */
+    readonly force?: boolean;
+    /** 只算出内容，不落盘。 */
+    readonly dryRun?: boolean;
+}
 export interface RefreshGuideResult {
     readonly root: string;
     readonly kind: "plugin" | "hub";
     readonly file: string;
+    /** 这次生成的说明书正文。`dryRun` 时用它做人工合并。 */
+    readonly content: string;
+    readonly written: boolean;
 }
 /**
  * 在已有的工程或能力市场仓库里重写 `AGENTS.md`。
@@ -25,8 +34,12 @@ export interface RefreshGuideResult {
  * `init` 拒绝覆盖已有工程，所以老目录里那份说明书从落地起就再也没变过——它写于某个版本的
  * SDK，之后新增的约定一条都没有。这里只重写这一个文件：它是脚手架里唯一「纯派生、没有用户
  * 内容」的产物，其余文件都可能被改过，不该被一次刷新抹掉。
+ *
+ * **只有确实由脚手架生成的那份才算纯派生。** 没有版本戳的文件无法与手写内容区分——能力市场
+ * 仓库的根 `AGENTS.md` 往往是一整本手写的市场规范——所以一律拒绝覆盖，让调用方拿 `dryRun`
+ * 的内容去人工合并，或显式 `force`。宁可少刷新一份，也不能悄悄删掉别人写的东西。
  */
-export declare function refreshAgentsGuide(targetDir: string): RefreshGuideResult;
+export declare function refreshAgentsGuide(targetDir: string, options?: RefreshGuideOptions): RefreshGuideResult;
 export interface InitHubInput {
     readonly targetDir: string;
     /** 市场名（slug）。 */