@vetta-org/plugin-cli 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to `@vetta-org/plugin-cli` are documented in this file.
 
+## [0.1.6] — 2026-09-14
+
+### Fixed
+
+- **`init --refresh-guide` 不再覆盖手写的 `AGENTS.md`**。此前它无条件重写，而 `docs` 又把「没有
+  版本戳」判成过期并给出这条命令——两者合起来是在引导用户删掉自己的文件。已知造成一个能力市场
+  仓库根部 443 行手写市场规范被整份替换。
+
+  没有 `vetta-guide-revision` 标记的文件现在一律拒绝覆盖（退出码 7），要覆盖得显式 `--force`；
+  新增 `--dry-run` 把新模板打到 stdout 供人工合并。`docs` 对无标记文件改口为「看起来是手写的，
+  请手动合并」，只有**带标记且落后**的才会被称作 stale 并给出刷新命令。
+
+- 说明书标题不再印出未解析的本地化占位符。`plugin.json` 的 `name` 写成 `%plugin.name%` 时，按
+  `defaultLocale` 从 `locales/` 解析；解析不到退回插件 id。
+
+- 说明书的命令清单改为读 `package.json` 的 `scripts`，只列真实存在的。老工程和自定义工程未必有
+  `dev` / `install:vetta`，照着跑只会得到一句 "Missing script"；没有 `install:vetta` 时改列
+  `vetta-plugin-cli add .`。
+
+- 更正 hub `AGENTS.md` 对 `sync` 的两处描述：`marketplaceVersion` 只在 semver 或纯整数时才推得动
+  （`YYYY.MM.DD-NN` 这类会报出来要手改），`config.api_version` / `permissions` / `commands`
+  **不回填**——宿主用 `plugin.json` 整个重算 `config`，`sync` 只在副本与真源不符时提醒删掉。
+
+## [0.1.5] — 2026-09-14
+
+### Changed
+
+- **脚手架的 `AGENTS.md` 削薄成纯指引**：原先写在里面的「不可违反的几条」（Tailwind-only、
+  错误必须 notify、最小权限、MF 顶层 JSX、`agent_mode` 已废弃、依赖用发布版本、`dist/` 进
+  版本库）全部移进手册的 `README.md#不可违反的红线`。写进说明书的规则会在所有存量工程里就地
+  凝固——它是 `init` 当天的快照，之后既不自更新、用户也没有理由回头看它。规则放进手册才能
+  随 SDK 升级一起到位；说明书越薄，需要回头迁移老仓库的理由就越少。
+
+### Added
+
+- `AGENTS.md` 带版本戳（`<!-- vetta-guide-revision: N -->`），`docs` 每次比对并在落后时打印
+  `This brief is stale ... npx @vetta-org/plugin-cli init --refresh-guide`。此前「说明书旧了」
+  只能靠人记得，而这正是它凝固的原因。没有 `AGENTS.md` 的工程不提示——「没有」不是「旧」。
+
 ## [0.1.4] — 2026-09-14
 
 ### Added

package/README.md

@@ -28,6 +28,16 @@ is purely derived and holds no user content — leaving source, manifest and con
 the id and display name from the `plugin.json` already on disk. At a marketplace root it rewrites the
 hub brief instead.
 
+It refuses to overwrite a brief that carries no `vetta-guide-revision` marker — that file is
+indistinguishable from a hand-written one, and a marketplace root often holds a hand-written spec.
+Use `--dry-run` to print the current template for manual merging, or `--force` to replace the file
+outright.
+
+You will rarely have to remember this: the brief carries a revision stamp, and `docs` compares it on
+every run and says outright when it is behind. The brief itself holds no rules — those live in the
+manual, which travels with the SDK — so it changes seldom, and a project that refreshes once keeps
+itself current from then on.
+
 ## Remove a plugin
 
 ```bash

package/dist/agents-template.d.ts

@@ -7,10 +7,25 @@
  * 因此任何 Agent（Claude Code、Cursor、Vetta 自己）在任何陌生目录都能自举，而且读到的
  * 永远是这个工程实际编译所针对的那份合同。
  *
+ * **这里刻意只留指引，不留知识。** 写进这个文件的每一条规则都会在所有存量工程里就地凝固：
+ * 它是 `init` 当天的快照，之后既不会自更新，用户也没有理由回来看它。规则属于手册——手册
+ * 随 SDK 升级一起到位。这个文件越薄，需要回头迁移老仓库的理由就越少。
+ *
  * 单位是插件目录本身：外面是能力市场仓库、是单插件仓库、还是一堆别的东西，都不影响这里。
  */
+/**
+ * 说明书的版本戳。
+ *
+ * `docs` 读它来判断一份说明书是不是旧的——没有这个戳，「该不该刷新」就只能靠人记得，而这
+ * 恰恰是它凝固的原因。**改动模板内容时必须一并推进它**，否则存量工程不会收到提示。
+ */
+export declare const AGENTS_GUIDE_REVISION = 3;
+/** 从一份 AGENTS.md 正文里读出版本戳；不是本模板生成的（或早于版本戳）时返回 undefined。 */
+export declare function readAgentsGuideRevision(content: string): number | undefined;
 export declare function renderAgentsGuide(input: {
     pluginId: string;
     displayName: string;
+    /** 工程 package.json 里实际存在的 script 名；缺省按脚手架的那套算。 */
+    scripts?: readonly string[];
 }): string;
 //# sourceMappingURL=agents-template.d.ts.map

package/dist/agents-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents-template.d.ts","sourceRoot":"","sources":["../src/agents-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CA2F1F","sourcesContent":["/**\n * 随脚手架落地的 Agent 说明书。\n *\n * 它替代的是「把开发知识写死在工作台插件的 skill 里」那套做法：那份 skill 只有 Vetta\n * 自己的 Agent 读得到，而且每加一个能力就要改一次、还要等 App 发版才到用户手里。这里\n * 反过来——工程自带说明书，说明书只说「去哪读手册」，手册随 SDK 版本进 node_modules。\n * 因此任何 Agent（Claude Code、Cursor、Vetta 自己）在任何陌生目录都能自举，而且读到的\n * 永远是这个工程实际编译所针对的那份合同。\n *\n * 单位是插件目录本身：外面是能力市场仓库、是单插件仓库、还是一堆别的东西，都不影响这里。\n */\nexport function renderAgentsGuide(input: { pluginId: string; displayName: string }): string {\n\treturn `# ${input.displayName}\n\nVetta 桌面插件工程。**先读手册再写代码**——不要凭记忆写 SDK API，这套合同变化很快。\n\n## 第一步：装依赖，然后找到手册\n\n\\`\\`\\`bash\nnpm install\nnpx vetta-plugin-cli docs\n\\`\\`\\`\n\n\\`npm install\\` 必须先跑：\\`vetta-plugin-cli\\` 是 \\`@vetta-org/plugin-cli\\` 的命令名，装完才在\n\\`node_modules/.bin\\` 里。还没装就想跑，用全名 \\`npx @vetta-org/plugin-cli docs\\`。\n\n**手册会过期。** 它是随 SDK 装进 \\`node_modules\\` 的快照，工程不升级就永远停在初始化那天的\n版本——本文件同样是那天的快照。开工前先确认一次：\n\n\\`\\`\\`bash\nnpx vetta-plugin-cli docs --check-latest\n\\`\\`\\`\n\n落后就按它打印的命令升级 SDK 再重读手册。\\`docs\\` 的输出永远比本文件新（\\`npx\\` 默认取最新的\nCLI），**两者冲突时以它为准**。\n\n它打印出随 \\`@vetta-org/plugin-sdk\\` 一起装进 \\`node_modules\\` 的手册目录**绝对路径**，以及\n这份手册对应的 SDK 版本。**不要硬编码这个路径**：工作区可能把依赖提升到仓库根，一仓多插件\n时各插件还可能钉不同的 SDK 版本。\n\n拿到路径后，用 read 工具按这个顺序打开：\n\n| 顺序 | 文件 | 何时读 |\n| --- | --- | --- |\n| 1 | \\`README.md\\` | 总是先读：能力矩阵、信任模型、导航 |\n| 2 | \\`getting-started.md\\` | 首次写代码、构建、安装调试 |\n| 3 | \\`manifest.md\\` | 写/改 \\`plugin.json\\`、贡献智能体与团队 |\n| 4 | \\`permissions.md\\` | 选定权限列表之前 |\n| 5 | 按扩展点选读 | \\`ui-slots.md\\` / \\`conversation-and-agent.md\\` / \\`message-cards.md\\` / \\`mcp.md\\` / \\`ai.md\\` / \\`browser.md\\` / \\`app-actions.md\\` |\n\n实现任一扩展点**之前**再读对应那章。手册是唯一真源，本文件与它冲突时以手册为准。\n\n## 开发闭环\n\n\\`\\`\\`bash\nnpm run dev            # Vite + Module Federation 开发服务器\nnpm run build          # 产出 dist/\nnpm run install:vetta  # 打包并装进正在运行的 Vetta（需要 Vetta 已启动）\nnpx vetta-plugin-cli watch   # 开热更新：宿主改从本工程目录加载，改完即生效\nnpx vetta-plugin-cli uninstall  # 卸载（省略 id 即本工程对应的插件）\n\\`\\`\\`\n\n\\`install:vetta\\` 走 \\`vetta-plugin-cli add .\\`：它找到本工程打出来的归档，交给正在运行的\nDesktop 校验、授权、安装。它**不会**直接写 \\`~/.vetta/plugins\\`。\n\n装完若提示有 pending 版本，用 \\`npx vetta-plugin-cli reload ${input.pluginId}\\` 让宿主应用它。\n\n开发期建议开热更新（\\`watch\\`）：之后改源码即时生效，不用每次重新打包安装。改 \\`plugin.json\\`\n的权限或命令声明时仍需重新安装一次，让宿主把授权落盘。\\`watch --stop\\` 关闭。\n\n## 如果这个目录之上有能力市场索引\n\n\\`vetta-plugin-cli docs\\` 会告诉你有没有（它会打印 \\`Marketplace index:\\`）。有的话，**改完\n\\`version\\` / \\`permissions\\` / \\`pluginApiVersion\\` 之后要回仓库根跑一次**：\n\n\\`\\`\\`bash\nnpx @vetta-org/plugin-cli sync          # 从各能力目录回填索引，并推进 marketplaceVersion\nnpx @vetta-org/plugin-cli sync --check  # 只报不写，CI 用\n\\`\\`\\`\n\n索引里的 \\`version\\` 与 \\`plugin.json\\` 的 \\`version\\` 必须**完全相等**，否则宿主同步直接失败；\n而内容变了却不换 \\`marketplaceVersion\\` 时，客户端既不报错也不更新——用户只是永远收不到。\n\\`add .\\` 装完若检测到索引还停在旧版本，会当场提醒你。\n\n## 不可违反的几条\n\n- **样式只用 Tailwind \\`className\\`**。禁止新建业务 CSS、禁止在 \\`style.css\\` 里写 \\`button\\`/\\`div\\`/\\`*\\`\n  这类选择器——插件与宿主共享同一个页面，全局选择器会污染整个 UI。\n- **可能失败的路径必须上报**：读文件、解析、网络、外部库的 catch 里调用\n  \\`ctx.ui.notify({ message, error })\\`（无需权限）。禁止只写死「失败」文案并丢掉原始 error。\n- **权限按需最小声明**。构建期会校验产物用到的能力与 \\`plugin.json\\` 的声明是否匹配，缺了直接\n  构建失败。但 UI 槽位不在这条校验里——那类缺权限在运行时只是静默跳过，所以对着手册核对。\n- **不要写 \\`agent_mode\\`**（已废弃，无运行时语义）。想收窄某个工具的使用场景，把「何时不该用它 +\n  替代做法」写进该工具 description 的反向触发段。\n- **顶层不要出现依赖共享 React 的 JSX**，放进组件或 \\`activate\\` 内（Module Federation 的加载时序）。\n- 依赖用 registry 上已发布的 semver，不要 \\`workspace:*\\`。\n- **\\`dist/\\` 要进版本库**。插件通过仓库目录分发时，宿主直接读 \\`plugin.json\\` 指向的 \\`entry\\`\n  与 \\`styles\\`，它不会替你构建——目录里没有构建产物就装不上。\n## 信息不足时\n\n插件 id、展示名、要用哪些权限、功能边界、是否立刻安装——**问用户**，不要自己假定。\n`;\n}\n"]}
+{"version":3,"file":"agents-template.d.ts","sourceRoot":"","sources":["../src/agents-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,4HAA4D;AAC5D,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI3E;AA4BD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,4FAAkD;IAClD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GAAG,MAAM,CAiDT","sourcesContent":["/**\n * 随脚手架落地的 Agent 说明书。\n *\n * 它替代的是「把开发知识写死在工作台插件的 skill 里」那套做法：那份 skill 只有 Vetta\n * 自己的 Agent 读得到，而且每加一个能力就要改一次、还要等 App 发版才到用户手里。这里\n * 反过来——工程自带说明书，说明书只说「去哪读手册」，手册随 SDK 版本进 node_modules。\n * 因此任何 Agent（Claude Code、Cursor、Vetta 自己）在任何陌生目录都能自举，而且读到的\n * 永远是这个工程实际编译所针对的那份合同。\n *\n * **这里刻意只留指引，不留知识。** 写进这个文件的每一条规则都会在所有存量工程里就地凝固：\n * 它是 `init` 当天的快照，之后既不会自更新，用户也没有理由回来看它。规则属于手册——手册\n * 随 SDK 升级一起到位。这个文件越薄，需要回头迁移老仓库的理由就越少。\n *\n * 单位是插件目录本身：外面是能力市场仓库、是单插件仓库、还是一堆别的东西，都不影响这里。\n */\n\n/**\n * 说明书的版本戳。\n *\n * `docs` 读它来判断一份说明书是不是旧的——没有这个戳，「该不该刷新」就只能靠人记得，而这\n * 恰恰是它凝固的原因。**改动模板内容时必须一并推进它**，否则存量工程不会收到提示。\n */\nexport const AGENTS_GUIDE_REVISION = 3;\n\n/** 从一份 AGENTS.md 正文里读出版本戳；不是本模板生成的（或早于版本戳）时返回 undefined。 */\nexport function readAgentsGuideRevision(content: string): number | undefined {\n\tconst match = /<!--\\s*vetta-guide-revision:\\s*(\\d+)\\s*-->/.exec(content);\n\tif (!match) return undefined;\n\treturn Number(match[1]);\n}\n\n/**\n * 渲染常用命令块。\n *\n * 只列工程真有的 script：模板写死 `npm run dev` / `install:vetta`，老工程和自定义工程未必有，\n * 照着跑就是一句 \"Missing script\"。读不到 package.json 时退回 CLI 直连命令——它们不依赖工程脚本。\n */\nfunction renderCommands(pluginId: string, scripts: readonly string[]): string {\n\tconst known: readonly (readonly [string, string])[] = [\n\t\t[\"dev\", \"npm run dev            # 开发服务器\"],\n\t\t[\"build\", \"npm run build          # 产出 dist/\"],\n\t\t[\"install:vetta\", \"npm run install:vetta  # 打包并装进正在运行的 Vetta（需要 Vetta 已启动）\"],\n\t];\n\tconst lines = known.filter(([name]) => scripts.includes(name)).map(([, line]) => line);\n\tif (!scripts.includes(\"install:vetta\")) {\n\t\tlines.push(\"npx vetta-plugin-cli add .       # 打包并装进正在运行的 Vetta\");\n\t}\n\treturn [\n\t\t...lines,\n\t\t\"\",\n\t\t\"npx vetta-plugin-cli watch       # 热更新：宿主改从本工程目录加载，改完即生效\",\n\t\t`npx vetta-plugin-cli reload ${pluginId}   # 装完提示有 pending 版本时用它`,\n\t\t\"npx vetta-plugin-cli uninstall   # 卸载（省略 id 即本工程对应的插件）\",\n\t\t\"npx vetta-plugin-cli sync        # 在 hub 仓库根上跑：把索引与各能力目录对账\",\n\t].join(\"\\n\");\n}\n\nexport function renderAgentsGuide(input: {\n\tpluginId: string;\n\tdisplayName: string;\n\t/** 工程 package.json 里实际存在的 script 名；缺省按脚手架的那套算。 */\n\tscripts?: readonly string[];\n}): string {\n\treturn `<!-- vetta-guide-revision: ${AGENTS_GUIDE_REVISION} -->\n# ${input.displayName}\n\nVetta 桌面插件工程（插件 id：\\`${input.pluginId}\\`）。\n\n**本文件不讲规则，只告诉你去哪读。** 规则在手册里，手册随 SDK 升级；写在这里的任何一条都会\n停在这个工程创建那天。两者冲突时一律以手册为准。\n\n## 第一步：装依赖，找到手册\n\n\\`\\`\\`bash\nnpm install\nnpx vetta-plugin-cli docs --check-latest\n\\`\\`\\`\n\n\\`npm install\\` 必须先跑：\\`vetta-plugin-cli\\` 是 \\`@vetta-org/plugin-cli\\` 的命令名，装完才在\n\\`node_modules/.bin\\` 里。还没装就想跑，用全名 \\`npx @vetta-org/plugin-cli docs\\`。\n\n它打印手册目录的**绝对路径**、手册对应的 SDK 版本，以及本工程与所属 hub 的位置。\n**不要硬编码这个路径**：工作区可能把依赖提升到仓库根，一仓多插件时各插件还可能钉不同版本。\n\n输出里出现 \\`Manual is behind\\` 或 \\`This brief is stale\\` 就按它给的命令升级，再重跑一次。\n\n## 第二步：按顺序读手册\n\n| 顺序 | 文件 | 何时读 |\n| --- | --- | --- |\n| 1 | \\`README.md\\` | **总是先读**：能力矩阵、信任模型、**不可违反的红线**、导航 |\n| 2 | \\`getting-started.md\\` | 首次写代码、构建、安装调试 |\n| 3 | \\`manifest.md\\` | 写/改 \\`plugin.json\\`、贡献智能体与团队 |\n| 4 | \\`permissions.md\\` | 选定权限列表之前 |\n| 5 | 按扩展点选读 | \\`ui-slots.md\\` / \\`conversation-and-agent.md\\` / \\`message-cards.md\\` / \\`mcp.md\\` / \\`ai.md\\` / \\`browser.md\\` / \\`app-actions.md\\` / \\`styling-and-pitfalls.md\\` |\n\n实现任一扩展点**之前**再读对应那章，不要凭记忆写 SDK API——这套合同变化很快。\n\n## 常用命令\n\n\\`\\`\\`bash\n${renderCommands(input.pluginId, input.scripts ?? [\"dev\", \"build\", \"install:vetta\"])}\n\\`\\`\\`\n\n细节都在 \\`getting-started.md\\`。\\`docs\\` 打印了 \\`Marketplace index:\\` 就说明这个目录之上有能力\n市场索引，改完 \\`version\\` / \\`permissions\\` / \\`pluginApiVersion\\` 后要回仓库根跑 \\`sync\\`。\n\n## 信息不足时\n\n插件 id、展示名、要用哪些权限、功能边界、是否立刻安装——**问用户**，不要自己假定。\n`;\n}\n"]}

package/dist/cli.js

@@ -3647,7 +3647,7 @@ var require_npa = __commonJS((exports, module) => {
 });
 
 // src/command.ts
-import { existsSync as existsSync4, statSync as statSync2 } from "node:fs";
+import { existsSync as existsSync4, readFileSync as readFileSync4, statSync as statSync2 } from "node:fs";
 import { join as join6, resolve as resolve5 } from "node:path";
 import { parseArgs } from "node:util";
 
@@ -15419,7 +15419,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,107 +18922,93 @@ async function resolveNpmPluginArchive(packageSpec, pack = runNpmPack) {
   }
 }
 
-// src/init.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join as join3, resolve as resolve2 } from "node:path";
-
 // src/agents-template.ts
+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 `# ${input.displayName}
+  return `<!-- vetta-guide-revision: ${AGENTS_GUIDE_REVISION} -->
+# ${input.displayName}
 
-Vetta 桌面插件工程。**先读手册再写代码**——不要凭记忆写 SDK API，这套合同变化很快。
+Vetta 桌面插件工程（插件 id：\`${input.pluginId}\`）。
 
-## 第一步：装依赖，然后找到手册
+**本文件不讲规则，只告诉你去哪读。** 规则在手册里，手册随 SDK 升级；写在这里的任何一条都会
+停在这个工程创建那天。两者冲突时一律以手册为准。
+
+## 第一步：装依赖，找到手册
 
 \`\`\`bash
 npm install
-npx vetta-plugin-cli docs
+npx vetta-plugin-cli docs --check-latest
 \`\`\`
 
 \`npm install\` 必须先跑：\`vetta-plugin-cli\` 是 \`@vetta-org/plugin-cli\` 的命令名，装完才在
 \`node_modules/.bin\` 里。还没装就想跑，用全名 \`npx @vetta-org/plugin-cli docs\`。
 
-**手册会过期。** 它是随 SDK 装进 \`node_modules\` 的快照，工程不升级就永远停在初始化那天的
-版本——本文件同样是那天的快照。开工前先确认一次：
-
-\`\`\`bash
-npx vetta-plugin-cli docs --check-latest
-\`\`\`
-
-落后就按它打印的命令升级 SDK 再重读手册。\`docs\` 的输出永远比本文件新（\`npx\` 默认取最新的
-CLI），**两者冲突时以它为准**。
+它打印手册目录的**绝对路径**、手册对应的 SDK 版本，以及本工程与所属 hub 的位置。
+**不要硬编码这个路径**：工作区可能把依赖提升到仓库根，一仓多插件时各插件还可能钉不同版本。
 
-它打印出随 \`@vetta-org/plugin-sdk\` 一起装进 \`node_modules\` 的手册目录**绝对路径**，以及
-这份手册对应的 SDK 版本。**不要硬编码这个路径**：工作区可能把依赖提升到仓库根，一仓多插件
-时各插件还可能钉不同的 SDK 版本。
+输出里出现 \`Manual is behind\` 或 \`This brief is stale\` 就按它给的命令升级，再重跑一次。
 
-拿到路径后，用 read 工具按这个顺序打开：
+## 第二步：按顺序读手册
 
 | 顺序 | 文件 | 何时读 |
 | --- | --- | --- |
-| 1 | \`README.md\` | 总是先读：能力矩阵、信任模型、导航 |
+| 1 | \`README.md\` | **总是先读**：能力矩阵、信任模型、**不可违反的红线**、导航 |
 | 2 | \`getting-started.md\` | 首次写代码、构建、安装调试 |
 | 3 | \`manifest.md\` | 写/改 \`plugin.json\`、贡献智能体与团队 |
 | 4 | \`permissions.md\` | 选定权限列表之前 |
-| 5 | 按扩展点选读 | \`ui-slots.md\` / \`conversation-and-agent.md\` / \`message-cards.md\` / \`mcp.md\` / \`ai.md\` / \`browser.md\` / \`app-actions.md\` |
+| 5 | 按扩展点选读 | \`ui-slots.md\` / \`conversation-and-agent.md\` / \`message-cards.md\` / \`mcp.md\` / \`ai.md\` / \`browser.md\` / \`app-actions.md\` / \`styling-and-pitfalls.md\` |
 
-实现任一扩展点**之前**再读对应那章。手册是唯一真源，本文件与它冲突时以手册为准。
+实现任一扩展点**之前**再读对应那章，不要凭记忆写 SDK API——这套合同变化很快。
 
-## 开发闭环
+## 常用命令
 
 \`\`\`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 uninstall  # 卸载（省略 id 即本工程对应的插件）
+${renderCommands(input.pluginId, input.scripts ?? ["dev", "build", "install:vetta"])}
 \`\`\`
 
-\`install:vetta\` 走 \`vetta-plugin-cli add .\`：它找到本工程打出来的归档，交给正在运行的
-Desktop 校验、授权、安装。它**不会**直接写 \`~/.vetta/plugins\`。
-
-装完若提示有 pending 版本，用 \`npx vetta-plugin-cli reload ${input.pluginId}\` 让宿主应用它。
+细节都在 \`getting-started.md\`。\`docs\` 打印了 \`Marketplace index:\` 就说明这个目录之上有能力
+市场索引，改完 \`version\` / \`permissions\` / \`pluginApiVersion\` 后要回仓库根跑 \`sync\`。
 
-开发期建议开热更新（\`watch\`）：之后改源码即时生效，不用每次重新打包安装。改 \`plugin.json\`
-的权限或命令声明时仍需重新安装一次，让宿主把授权落盘。\`watch --stop\` 关闭。
-
-## 如果这个目录之上有能力市场索引
-
-\`vetta-plugin-cli docs\` 会告诉你有没有（它会打印 \`Marketplace index:\`）。有的话，**改完
-\`version\` / \`permissions\` / \`pluginApiVersion\` 之后要回仓库根跑一次**：
-
-\`\`\`bash
-npx @vetta-org/plugin-cli sync          # 从各能力目录回填索引，并推进 marketplaceVersion
-npx @vetta-org/plugin-cli sync --check  # 只报不写，CI 用
-\`\`\`
-
-索引里的 \`version\` 与 \`plugin.json\` 的 \`version\` 必须**完全相等**，否则宿主同步直接失败；
-而内容变了却不换 \`marketplaceVersion\` 时，客户端既不报错也不更新——用户只是永远收不到。
-\`add .\` 装完若检测到索引还停在旧版本，会当场提醒你。
-
-## 不可违反的几条
-
-- **样式只用 Tailwind \`className\`**。禁止新建业务 CSS、禁止在 \`style.css\` 里写 \`button\`/\`div\`/\`*\`
-  这类选择器——插件与宿主共享同一个页面，全局选择器会污染整个 UI。
-- **可能失败的路径必须上报**：读文件、解析、网络、外部库的 catch 里调用
-  \`ctx.ui.notify({ message, error })\`（无需权限）。禁止只写死「失败」文案并丢掉原始 error。
-- **权限按需最小声明**。构建期会校验产物用到的能力与 \`plugin.json\` 的声明是否匹配，缺了直接
-  构建失败。但 UI 槽位不在这条校验里——那类缺权限在运行时只是静默跳过，所以对着手册核对。
-- **不要写 \`agent_mode\`**（已废弃，无运行时语义）。想收窄某个工具的使用场景，把「何时不该用它 +
-  替代做法」写进该工具 description 的反向触发段。
-- **顶层不要出现依赖共享 React 的 JSX**，放进组件或 \`activate\` 内（Module Federation 的加载时序）。
-- 依赖用 registry 上已发布的 semver，不要 \`workspace:*\`。
-- **\`dist/\` 要进版本库**。插件通过仓库目录分发时，宿主直接读 \`plugin.json\` 指向的 \`entry\`
-  与 \`styles\`，它不会替你构建——目录里没有构建产物就装不上。
 ## 信息不足时
 
 插件 id、展示名、要用哪些权限、功能边界、是否立刻安装——**问用户**，不要自己假定。
 `;
 }
 
+// src/init.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join as join3, resolve as resolve2 } from "node:path";
+
 // src/hub-template.ts
 function renderHubAgentsGuide(input) {
-  return `# ${input.name}
+  return `<!-- vetta-guide-revision: ${AGENTS_GUIDE_REVISION} -->
+# ${input.name}
 
 Vetta 能力市场仓库。本仓库索引若干**能力**（plugin / mcp / skill / scene / bundle），
 每个能力是 \`abilities/\` 下的一个自包含目录。
@@ -19054,16 +19042,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\` 会替你守住：
 
@@ -19073,7 +19070,7 @@ npx @vetta-org/plugin-cli sync --check  # 只报不写，非零退出（CI 用
 | \`plugin.json\` 的 \`entry\` / \`styles\` 必须在已发布目录里真实存在 | 本地能装，市场上装不了 |
 | 改了任何内容必须换 \`marketplaceVersion\` | 客户端不报错、也不更新，用户永远收不到 |
 
-第三条最阴险——它不报错。
+第三条最阴险——它不报错。\`sync\` 只在版本号是 semver 或整数时才推得动，其余格式要你自己换。
 
 ## 为什么插件目录里要提交 \`dist/\`
 
@@ -19241,26 +19238,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}`);
   }
-  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") };
+  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;
+  }
+  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-]+)*)?$/;
@@ -19320,7 +19371,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))
@@ -19364,7 +19415,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 : [];
@@ -19433,7 +19484,7 @@ function syncMarketplaceIndex(input) {
 }
 function reconcilePlugin(context) {
   const { entry, slug, abilityDir, changes, problems } = context;
-  const manifest = readJsonFile(join4(abilityDir, "plugin.json"));
+  const manifest = readJsonFile2(join4(abilityDir, "plugin.json"));
   if (!manifest) {
     problems.push({ slug, message: "plugin.json is missing or malformed" });
     return;
@@ -19474,7 +19525,7 @@ function reconcilePlugin(context) {
 }
 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;
@@ -19517,7 +19568,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);
@@ -19607,7 +19658,7 @@ Usage:
   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]
@@ -19708,7 +19759,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) {
@@ -19718,7 +19771,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) {
@@ -20061,6 +20120,7 @@ async function runDocsCommand(command, dependencies) {
   const sdkVersion = readManualSdkVersion(manualDir);
   const latestVersion = command.checkLatest ? await dependencies.readLatestSdkVersion?.() : undefined;
   const outdated = sdkVersion !== undefined && latestVersion !== undefined && compareSemver(sdkVersion, latestVersion) < 0;
+  const guide = inspectAgentsGuide(project?.root ?? hub?.root ?? cwd);
   if (command.json) {
     dependencies.writeStdout(`${JSON.stringify({
       ok: true,
@@ -20068,6 +20128,7 @@ async function runDocsCommand(command, dependencies) {
       entry: join6(manualDir, "README.md"),
       sdkVersion,
       refreshCommand: SDK_REFRESH_COMMAND,
+      guide,
       ...command.checkLatest ? { latestVersion, outdated } : {},
       project: project ? { root: project.root, pluginId: project.pluginId, version: project.version } : undefined,
       hub: hub ? {
@@ -20093,6 +20154,11 @@ async function runDocsCommand(command, dependencies) {
   } else {
     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} < ${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}`);
     lines.push("After changing version/permissions, run `vetta-plugin-cli sync` at the repository root.");
@@ -20103,6 +20169,24 @@ async function runDocsCommand(command, dependencies) {
   return 0;
 }
 var SDK_REFRESH_COMMAND = "npm i -D @vetta-org/plugin-sdk@latest && npx vetta-plugin-cli docs";
+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, unstamped: false };
+  let revision;
+  try {
+    revision = readAgentsGuideRevision(readFileSync4(path, "utf8"));
+  } catch {
+    return { present: true, stale: false, unstamped: false };
+  }
+  return {
+    present: true,
+    ...revision === undefined ? {} : { revision },
+    stale: revision !== undefined && revision < AGENTS_GUIDE_REVISION,
+    unstamped: revision === undefined
+  };
+}
 function compareSemver(left, right) {
   const parse2 = (value) => {
     const match2 = /^(\d+)\.(\d+)\.(\d+)(-.+)?$/.exec(value.trim());
@@ -20123,11 +20207,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/command.d.ts

@@ -44,6 +44,8 @@ export type PluginInitCommand = {
     type: "refresh-guide";
     targetDir?: string;
     json: boolean;
+    force: boolean;
+    dryRun: boolean;
 } | {
     type: "init-hub";
     targetDir?: string;
@@ -104,5 +106,19 @@ export declare function parsePluginUninstallCommand(argv: string[]): PluginUnins
 export declare function parsePluginSyncCommand(argv: string[]): PluginSyncCommand | undefined;
 export declare function runPluginAddCommand(command: PluginAddCommand, dependencies?: PluginAddCommandDependencies): Promise<number>;
 export declare function runPluginCommand(command: PluginCommand, dependencies?: PluginCommandDependencies): Promise<number>;
+export interface AgentsGuideStatus {
+    /** 本工程有没有 AGENTS.md。 */
+    readonly present: boolean;
+    /** 读到的版本戳；没有戳（模板早于版本戳，或是手写的）时缺省。 */
+    readonly revision?: number;
+    /**
+     * **带戳**且落后于当前 CLI 的模板——只有这一档能安全地一键重写。
+     *
+     * 没有 AGENTS.md 时为 false（那是「没有」，不是「旧」）；没有戳时也为 false，见 {@link unstamped}。
+     */
+    readonly stale: boolean;
+    /** 有文件但没有版本戳：可能是手写的，也可能是版本戳之前的模板，无从区分。 */
+    readonly unstamped: boolean;
+}
 export declare function runPluginCli(argv: string[]): Promise<number>;
 //# sourceMappingURL=command.d.ts.map