@vetta-org/plugin-sdk 0.3.0 → 0.3.2

package/docs/file-explorer.md

@@ -0,0 +1,118 @@
+# 文件列表扩展
+
+`ctx.fileExplorer` 扩展宿主自带的项目文件列表。插件可以贡献右键菜单、工具栏动作和文件装饰，也可以读取当前工作区/选中项、定位文件、刷新目录并订阅文件事件。
+
+文件列表 API 只暴露文件名、路径、类型、大小和修改时间等元数据。读取文件内容仍需 `fs.read`，修改文件仍需 `fs.write`。
+
+## 权限
+
+| 权限 | 能力 |
+| --- | --- |
+| `ui.file-explorer.context-menu` | 注册文件或目录右键菜单动作 |
+| `ui.file-explorer.toolbar` | 注册文件列表顶部工具栏动作 |
+| `ui.file-explorer.decorations` | 注册图标、徽标和提示信息提供者 |
+| `workspace.read` | 查询根目录/选中项、定位、刷新和订阅事件 |
+
+上述 API 缺权限时会抛 `Plugin permission denied: <permission>`。它们不会隐式授予 `fs.read` 或 `fs.write`。
+
+## 右键菜单
+
+```tsx
+ctx.fileExplorer.registerContextMenuAction({
+  id: "format-file",
+  label: "%explorer.format%",
+  icon: <span className="icon-[solar--magic-stick-3-linear] h-3.5 w-3.5" />,
+  order: 50,
+  when: {
+    resourceType: "file",
+    extensions: ["ts", "tsx"],
+  },
+  async run({ entry, workspaceRoot }) {
+    // 读取内容需要插件另外声明 fs.read。
+    const source = await ctx.fs.readFile(entry.path);
+    console.info(workspaceRoot?.path, source.content.length);
+  },
+});
+```
+
+`when` 支持：
+
+- `resourceType`: `file` 或 `directory`
+- `extensions`: 不带点的扩展名数组，大小写不敏感
+- `fileNames`: 精确文件名数组，大小写不敏感
+
+多个动作按 `order` 升序显示，缺省为 `100`。
+
+## 工具栏动作
+
+```tsx
+ctx.fileExplorer.registerToolbarAction({
+  id: "sync",
+  label: "%explorer.sync%",
+  icon: <SyncIcon />,
+  async run({ workspaceRoot, selection }) {
+    await synchronize(workspaceRoot.path, selection.map((entry) => entry.path));
+  },
+});
+```
+
+工具栏动作只在文件列表存在活动工作区时显示。`selection` 是当前文件列表选中项的只读快照。
+
+## 文件装饰
+
+```tsx
+ctx.fileExplorer.registerDecorationProvider({
+  id: "git-status",
+  priority: 100,
+  when: { resourceType: "file" },
+  provideDecoration(entry) {
+    const status = statusByPath.get(entry.path);
+    if (!status) return null;
+    return {
+      badge: status,
+      tooltip: `%explorer.gitStatus.${status}%`,
+    };
+  },
+});
+```
+
+`provideDecoration` 在文件树渲染时同步调用，必须快速且无副作用。网络、命令和文件读取应提前完成并缓存在插件内；状态变化后可调用 `ctx.fileExplorer.refresh()` 触发目录刷新。多个提供者命中时，宿主采用 `priority` 最高且返回非空结果的提供者。
+
+装饰可返回：
+
+- `icon`: 替换内置文件/文件夹图标的 React 节点
+- `badge`: 文件名后的紧凑状态文本，建议一到两个字符
+- `tooltip`: 文件行提示信息
+
+## 工作区、选择与定位
+
+```ts
+const roots = ctx.fileExplorer.getWorkspaceRoots();
+const selection = ctx.fileExplorer.getSelection();
+
+await ctx.fileExplorer.reveal("C:/workspace/src/index.ts", {
+  select: true,
+  focus: true,
+});
+
+await ctx.fileExplorer.refresh();        // 刷新根目录
+await ctx.fileExplorer.refresh(dirPath); // 刷新工作区内指定目录
+```
+
+当前版本的内置文件列表只有一个活动根目录，因此 `getWorkspaceRoots()` 返回零项或一项。`reveal` 和 `refresh(path)` 只接受当前工作区内路径。
+
+## 事件
+
+```ts
+const selectionHandle = ctx.fileExplorer.onDidChangeSelection((selection) => {
+  console.info("selection", selection);
+});
+
+const filesHandle = ctx.fileExplorer.onDidChangeFiles((changes) => {
+  for (const change of changes) console.info(change.type, change.path);
+});
+```
+
+文件事件类型为 `changed`、`created`、`deleted` 或 `moved`；`moved` 额外包含 `oldPath`。文件系统监听只能确定目录发生变化时，宿主会发送该目录的 `changed` 事件。
+
+所有注册和订阅都返回 `Disposable`。插件可以主动调用 `dispose()`；插件停用、重载或卸载时宿主也会统一清理贡献和订阅。

package/docs/getting-started.md

@@ -0,0 +1,295 @@
+# 快速开始
+
+从零搭建、构建、安装、调试一个 Vetta 桌面插件。
+
+## 0. 在仓库外开发（推荐给 Agent）
+
+你不需要 Vetta 的源码仓库，也不需要插件工作台。任意空目录里：
+
+```bash
+npx @vetta-org/plugin-cli init --id my-plugin --name "My Plugin"
+cd my-plugin && npm install
+```
+
+脚手架会落下一份 `AGENTS.md`，把「先读手册再写代码」这条规矩和构建安装闭环交代清楚。
+
+**手册就在工程里**——它随 `@vetta-org/plugin-sdk` 一起装进 `node_modules`：
+
+```bash
+npx vetta-plugin-cli docs      # 装完依赖后可用；未装时用 npx @vetta-org/plugin-cli docs + 它对应的 SDK 版本
+```
+
+**不要硬编码那个路径**：工作区可能把依赖提升到仓库根，一仓多插件时各插件还可能钉不同的
+SDK 版本。这条命令按 Node 的解析规则找，拿回来的永远是当前工程实际编译所针对的那一份。
+
+这一点很重要：手册与 SDK 同版本发布，因此它描述的合同**就是你即将编译的合同**。从网络现取
+最新文档做不到这一点——那会教你写出用户宿主还不支持的东西，而 UI 槽位这类缺失不会在构建期
+暴露，装上去只是静默跳过。
+
+装进正在运行的 Vetta：
+
+```bash
+npm run install:vetta          # = vite build && vetta-plugin pack && vetta-plugin-cli add .
+npx vetta-plugin-cli reload my-plugin   # 提示有 pending 版本时
+```
+
+`add` 传目录即可（`add .`）：它向上找到最近的 `plugin.json`，再定位该工程打出来的归档，
+交给正在运行的 Desktop 校验、授权、安装，**不直接写** `~/.vetta/plugins`。
+
+### 一仓多插件（能力市场 hub）
+
+仓库根有 `.vetta/marketplace.json` 时（如官方能力市场那种布局），命令一律作用于「最近的那个
+插件」，所以先 `cd` 进目标插件目录。在 hub 里 `init` 还会把新插件登记进那份索引——手动维护它
+是最容易漏的一步，插件建好了能装能跑、市场上却看不到。
+
+站在 hub 根执行 `add .` 会被拒绝并要求指明插件：一仓多插件时猜一个出来比报错更糟。
+
+## 前置条件
+
+- Node / Bun（仓库统一用 [Bun](https://bun.sh)）。
+- 一个 Vetta 桌面 App（用于安装调试）。
+- 插件用 React 19 + TypeScript + Vite，经 **Module Federation** 打成 remote。
+
+## 1. 项目结构
+
+一个最小插件项目：
+
+```text
+my-plugin/
+  plugin.json          # 清单（见 manifest.md）
+  ability.json         # 可选：能力详情页（见 ability-details.md）
+  presentation/        # 可选：详情页 Markdown 与图片
+    README.md
+  package.json
+  tsconfig.json
+  vite.config.ts       # Module Federation + Tailwind
+  src/
+    index.tsx          # 插件入口：export default definePlugin(...)
+    style.css          # Tailwind 入口，也可包含插件业务 CSS
+```
+
+构建产物（`dist/`）形如：
+
+```text
+dist/
+  mf-manifest.json     # MF 清单（plugin.json 的 entry 指向它）
+  remoteEntry.js       # MF remote 入口
+  style.css            # Tailwind 生成的 utilities（由入口 import 产出）
+```
+
+## 2. package.json
+
+```json
+{
+  "name": "my-plugin",
+  "private": true,
+  "type": "module",
+  "scripts": {
+	"dev": "vetta-plugin dev",
+    "build": "bunx vite build",
+    "check": "bunx tsc --noEmit"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.1.12",
+    "@types/react": "^19.1.1",
+    "@types/react-dom": "^19.1.1",
+    "@vetta-org/plugin-sdk": "workspace:*",
+    "@vetta-org/plugin-vite": "workspace:*",
+    "react": "19.1.1",
+    "react-dom": "19.1.1",
+    "tailwindcss": "^4.1.12",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.7"
+  }
+}
+```
+
+> `react` / `react-dom` 仅用于类型与本地构建——运行时由**宿主作为共享单例提供**，不会打进你的 bundle（见 [styling-and-pitfalls.md](./styling-and-pitfalls.md)）。`@vetta-org/plugin-sdk` 同理：构建时被 external 化，运行时由宿主提供。可选 UI primitives `@vetta-org/ui`（`Button` / `Dialog` / `Switch`…）同样由宿主单例提供，需要时在 `devDependencies` 加类型依赖即可。仓库内插件用 `workspace:*` 直链源码；仓库外插件改用发布版本号。
+
+## 3. vite.config.ts
+
+用 `@vetta-org/plugin-vite` 的 `vettaPluginFederation` 封装 Module Federation；**UI 插件请始终接 Tailwind**（样式只走 className，见 [styling-and-pitfalls.md](./styling-and-pitfalls.md)）：
+
+```ts
+import tailwindcss from "@tailwindcss/vite";
+import { vettaPluginFederation } from "@vetta-org/plugin-vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    tailwindcss(),
+    vettaPluginFederation({
+      name: "my_plugin",        // MF remoteName，与 plugin.json.moduleFederation.remoteName 一致
+      entry: "./src/index.tsx", // 入口（默认即此）
+      expose: "./plugin",       // 暴露名（默认 "./plugin"，与 plugin.json.moduleFederation.expose 一致）
+      // package: true,         // 见 §5：构建后自动产出 release/<id>-<version>.zip
+    }),
+  ],
+  esbuild: { jsx: "automatic", jsxImportSource: "react" },
+});
+```
+
+`vettaPluginFederation` 自动：把 `react` / `react-dom` / `@vetta-org/plugin-sdk` / `@vetta-org/ui` 设为 `singleton`、`import:false`（用宿主的），生产构建时把 SDK 与 UI external 化，产出 `mf-manifest.json` + `remoteEntry.js`，CSS 落 `dist/style.css`。
+
+它还会在插件 Tailwind 编译前自动接入 plugin-sdk 的宿主主题 Token 契约，因此
+`text-foreground`、`text-muted-foreground/50`、`bg-card` 等语义类可以直接使用；
+无需在插件中导入 Desktop CSS 或手写 `@theme` 映射。
+
+## 4. 样式入口 src/style.css
+
+插件 CSS 会由 `vettaPluginFederation` 自动限定到插件根节点，并由宿主放入低优先级 layer；
+不需要手写插件 id 前缀或 `@layer`。需要 Tailwind 时可以直接：
+
+```css
+@import "tailwindcss";
+
+/* 可选：正常编写插件业务 CSS */
+.panel button {
+  min-width: 6rem;
+}
+```
+
+## 5. 入口 src/index.tsx
+
+```tsx
+import { definePlugin } from "@vetta-org/plugin-sdk";
+import { useState } from "react";
+import "./style.css";
+
+function MyPanel() {
+  const [open, setOpen] = useState(true);
+  if (!open) return null;
+  // 可以使用 Tailwind className，也可以使用插件自己的 CSS
+  return (
+    <div className="flex flex-col gap-2 p-3 text-sm text-foreground">
+      <button
+        type="button"
+        className="rounded-md border border-border bg-accent px-2 py-1"
+        onClick={() => setOpen(false)}
+      >
+        关闭
+      </button>
+    </div>
+  );
+}
+
+export default definePlugin({
+  activate(ctx) {
+    // ctx 提供全部能力出口，按需注册贡献 / 调用能力
+    ctx.ui.registerGlobalSlot({ id: "root", component: MyPanel });
+    const subscription = createMySubscription();
+    // cleanup 只属于本次 activation；热更新的新旧实例不会互相清理。
+    return () => subscription.dispose();
+  },
+});
+```
+
+`definePlugin` 只是身份函数。`activate()` 可返回 cleanup 函数或 `Disposable`；有状态资源优先使用这种 activation-scoped cleanup。旧插件的模块级 `deactivate()` 仍兼容。也可不用它、直接 `export function activate(ctx) {}` —— 宿主两种形态都认。
+
+> **顶层禁用共享依赖（含 JSX）**：MF 的 react / jsx-runtime 是异步填充的，bootstrap 完成前为 `undefined`。模块顶层写 `const ICON = <svg/>` 会在求值时抛 `TypeError: ... is not a function`，整个插件加载失败。把这类 JSX 放进 `activate()` 或组件函数体内。详见 [styling-and-pitfalls.md](./styling-and-pitfalls.md)。
+
+## 6. 构建与打包
+
+```bash
+bunx vite build      # 产出 dist/（mf-manifest.json + remoteEntry.js + style.css）
+```
+
+发布需要一个 **zip**：根目录放 `plugin.json`，其下 `dist/`。两种方式：
+
+- **自动**：`vettaPluginFederation({ ..., package: true })`，`vite build` 后自动产出 `release/<id>-<version>.zip`（打包 `plugin.json` + `dist/` + 清单声明的 `styles` / `agent.promptPaths` / `agent.skillPaths`；存在 `ability.json` 时也打包它和 `presentation/`）。
+- **手动**：自行把 `plugin.json` 与 `dist/` 一起 zip：
+
+  ```text
+  my-plugin.zip
+    plugin.json
+    ability.json                 # 可选
+    presentation/               # 使用 ability.json 时可选
+      README.md
+    dist/
+      mf-manifest.json
+      remoteEntry.js
+      style.css
+  ```
+
+> 归档根目录必须有 `plugin.json`，或只含**一个**顶层文件夹、`plugin.json` 在其中。
+> 能力详情是可选的；需要 showcase、功能网格、图片或长篇 Markdown 时见 [ability-details.md](./ability-details.md)。
+
+## 7. 安装
+
+### GUI
+
+通过桌面 App **设置 → 插件**（或独立插件页）安装：
+
+- **本地 zip**：选择本地 `.zip` 文件（`installFromArchive`）。
+- **远程 URL**：填写 zip 下载地址（`installFromUrl`）。
+
+安装后用户插件落在：
+
+```text
+~/.vetta/plugins/<id>/versions/<version>/
+```
+
+`listPlugins()` 中每条记录含 **`rootPath`**（该版本包的绝对根路径）。
+
+随后在该页**授予声明权限**并启用（缺权限时 API 会抛错或 warn，见 [permissions.md](./permissions.md)）。
+
+### Agent / 脚本：`install-from-path`（ADR-0042）
+
+宿主 Action `plugins.manage`：
+
+```json
+{
+  "operation": "install-from-path",
+  "path": "/abs/path/to/my-plugin-0.1.2.zip"
+}
+```
+
+- 路径：本机可读 **`.zip` 绝对路径**（不限 cwd）。
+- 用户确认后：按 `plugin.json` **一次授予声明权限**并默认**启用**。
+- Desktop API：`window.vetta.plugins.installFromPath(path, { grantedPermissions?, enable? })`。
+- 不可覆盖系统插件 id。
+
+> **系统插件（presets）**不经此安装流，见 [system-plugins.md](./system-plugins.md)。
+
+### 依赖注意（用户机）
+
+仓库内 preset / external 可用 `workspace:*` 链本地 SDK。**用户自建工程**应使用发布到 registry 的 `@vetta-org/plugin-sdk` / `@vetta-org/plugin-vite` **semver**（sdk `^0.3.1`，手册随该版本进 node_modules；版本化热更新协议对应 vite `^0.2.0`，两者版本独立）。推出包含该脚手架的 Desktop 前，必须先发布对应的 vite 版本并确认 registry 可达。
+
+## 8. 调试闭环（dev loop）
+
+1. 插件工作台制作的用户插件首次先点「应用到 Vetta」；安装、授权和启用完成后，工作台会等待工程内的 `vetta-plugin dev` 真正就绪，再把热更新标为运行中。
+2. 后续可在插件工作台开关热更新；开发进程由 Desktop 主进程持有，关闭工作台面板不会中止，不需要另开 `vite build --watch`。
+3. 修改 React 组件或 CSS 后由 Vite HMR 直接更新，组件状态在 Fast Refresh 可保留时不会丢失。
+4. 修改插件入口、`plugin.json`、locale 或 agent 资源时，宿主只替换当前插件的 activation，其他插件不重载。
+5. permissions、commands 等安装态能力需要正式同步时，再重新构建并安装 zip。
+
+宿主会一直保留安装版或系统插件 staging 作为稳定基线；工程内开发服务器确认 manifest 可访问并完成插件本地入口模块图转换后，才发送版本化 ready 握手并原子切换到源码 overlay。ready 前的依赖编译失败不会替换当前插件，运行中的服务器异常退出会先回退稳定版本并有限重启。React 等宿主共享依赖仍在 Renderer 的真实 share scope 中加载。
+
+`bun run dev` 可单独启动同一个开发服务器并输出 NDJSON 状态，主要用于宿主或工具集成；使用插件工作台时不要重复启动。安装更新版本仍会记为 **pending**，直到 `reload` 才切换正式安装态的 `activeVersion`。
+
+开发 Desktop 仓库内的 preset 时，不需要打开插件工作台。`apps/desktop` 的开发启动器默认会为当前
+`VETTA_TENANT` 包含的全部 preset 启动开发服务器；直接运行即可：
+
+```powershell
+bun run --cwd apps/desktop dev
+```
+
+需要缩小启动范围时，可显式指定逗号分隔的插件 id；显式设置为空字符串则关闭插件开发服务器，回落到
+staging 制品：
+
+```powershell
+$env:VETTA_PLUGIN_DEV="git,content-creation"
+bun run --cwd apps/desktop dev
+```
+
+仓库外工程使用 `VETTA_PLUGIN_DEV_ROOTS`，多个绝对路径以当前平台的 PATH 分隔符分开。该入口只在未打包的 Desktop 中生效；显式选择但尚未安装的 external 使用纯内存开发记录，退出 App 后不会写入插件注册表。
+
+## 下一步
+
+- 清单全字段：[manifest.md](./manifest.md)
+- 权限：[permissions.md](./permissions.md)
+- UI 扩展点：[ui-slots.md](./ui-slots.md)
+- 消息卡片：[message-cards.md](./message-cards.md)
+- 对话 / 命令 / 文件 / 图像 / i18n：[conversation-and-agent.md](./conversation-and-agent.md)
+- **MCP 三源聚合**：[mcp.md](./mcp.md)
+- 样式与陷阱：[styling-and-pitfalls.md](./styling-and-pitfalls.md)

package/docs/guiding-the-agent.md

@@ -0,0 +1,183 @@
+# 引导模型用好你的扩展：重心偏移与优质扩展设计
+
+> 适用对象：往仓库里新增 tools / MCP / skills / 系统插件的内部开发者，以及第三方插件开发者。
+> 背景决策：[ADR-0071](../adr/0071-agent-mode-is-a-task-interpretation-prior.md)（工作模式是任务解释的先验）。
+
+## 先建立正确的心智模型
+
+模型处理一次请求有三个可施力的层：
+
+```text
+① 解释层   「这句话是什么任务？」——工作模式先验、工作区事实、路线声明在这里博弈
+② 选择层   任务定了之后选哪个工具/skill——由 name + description 的语义匹配决定
+③ 执行层   副作用发生前可不可以拦——execution mode 沙盒、插件权限、工具自身的业务校验
+```
+
+设计时应遵循以下约束：
+
+1. **不能依靠注册顺序控制工具选择。** 模型会结合请求、上下文与 description 选择工具；`agent_mode`
+   字段已整体废弃（解析容忍、语义为零），声明它不会让你的工具在任何模式下更靠前或更靠后。
+2. **模式不隐藏也不降权任何能力。** 你的扩展在 Work / Coding（以及未来的任何模式）下完整可用、
+   顺序一致。引导应帮助模型识别真实适用的任务，而不是把不相关请求解释成自己的使用场景。
+3. **description 占用模型上下文。** 工具 description 随工具定义提供，不在系统提示词中重复列出；缓存和计费取决于 Provider。
+   完整方法与流程属于 skill（按需加载）；description 保留准确的功能摘要、适用任务与必要前提，避免重复长篇教程。
+
+## 四个工具引导面
+
+前三个作用在工具选择前的语义匹配上；返回值在工具执行后引导后续决策。
+
+### 1. name：动词化、具体、无歧义
+
+模型对工具名做的第一件事是语义联想。`render_chart` 好于 `chart`；`vetd_create` 带产品前缀避免
+与通用词碰撞；`content_creation_edit` 一眼可知归属与动作。坏名字（`process`、`handle_data`）
+迫使模型完全依赖 description，等于自废一半匹配信号。
+
+### 2. description 正向触发段：用用户的语言描述任务
+
+触发条件应说明用户想要的结果和被操作的资源，并考虑前文已建立的目标。使用用户会说的任务措辞，
+不要只匹配原话里的主题词，也不要只罗列实现功能：
+
+```text
+✅ Use for a standalone design mockup or edits to an existing design canvas.
+   For working UI code in a repository, use that project's framework instead.
+❌ Provides vetd document scaffolding and frame management capabilities.
+```
+
+参数上同理：`vetd_create` 要求调用前先判断 `product` 品类，并把判断依据写进参数
+description——「Take it from the user's request in whatever language they wrote it」。
+这把一次容易做错的隐式判断变成了 schema 强制的显式判断。
+
+### 3. description 反向触发段：在选择前说明边界
+
+这是被最多人忽视、却是重心偏移最关键的一半。想收窄使用场景，**不要**指望模式、排序或任何
+声明式字段——把「什么时候不该用我 + 该用什么替代」直接写进 description。仓库里的范本：
+
+```text
+Do NOT use when the user is writing or modifying code in an existing codebase —
+implement the page directly in that repo's own framework instead.
+Only for standalone visual exploration decoupled from any codebase,
+when the user asked for a design/mockup rather than working code.
+```
+
+（`vetd_create`，packages/plugins/presets/vetta-ui-design/src/tools.ts）
+
+```text
+Do NOT use to read or move media that belongs to the user's codebase — assets a
+repository ships (public/, assets/, src/) stay where they are and are handled
+with the ordinary file tools instead.
+```
+
+（`content_creation_assets`）
+
+写反向触发段的三条纪律：
+
+- **给替代路径，不只给禁令。** "别用我"之后必须跟"改用什么"，否则模型在无路可走时还是会用你。
+- **针对真实误调场景写**，不是防御性堆砌。问自己：模型最可能在哪句用户指令上错选我？
+  （`vetd_create` 的答案是"写个页面"——注释里就是这么记录的。）
+- **与 mode md 的路线声明对齐措辞。** 宿主的 coding.md 用 "design-exploration tools /
+  standalone design documents / canvas mockups" 这类**类别措辞**描述次要路线（宿主永不点名
+  具体插件）；你的反向触发段把自己归入类别（"standalone visual exploration"），两边就接上了。
+  这是插件与模式之间唯一的、也是刻意设计的接口：**自然语言归类，而不是字段注册**。
+
+工具描述应与真实误调风险匹配：会创建工程、产生费用或对外发送内容的工具，要写清适用场景与替代路径。
+只读工具没有明确误调场景时，不必堆砌防御性说明。这些描述帮助模型选择工具，不构成权限保证。
+
+### 4. 工具返回值：被低估的最强引导面
+
+description 与返回值承担不同职责：前者帮助选择，后者提供执行后状态和恢复依据。返回值仍可能被截断或压缩，
+不能假定模型每次都完整阅读。范本是 `vetd_status`：
+
+- 返回里带 `sharedShell`（已有的公共外壳与组件清单）+ 一句 note："This design already has
+  shared UI — reuse it instead of writing a second copy."。这解决了"模型一屏一屏写、写到第三屏
+  早忘了第一屏抽过公共导航"的真实问题——**在返回值里把该复用的东西端到眼前，比在 skill 里
+  多写一段规则管用**，因为返回值是每次都会读的。
+- note 按「此刻最该做的一件事」给，不叠加——三条并列的建议等于没有重点。
+- 出错时返回可执行的下一步（"Fix these first, with a targeted edit at the reported line"），
+  而不是裸错误。
+
+设计返回值时问自己：模型拿到这个返回后，下一步最容易做错什么？把纠偏信息放在那里。
+
+## 执行边界
+
+工具注册不再提供副作用等级，也不再触发会话首次调用确认。宿主不会替插件依据工具名分类或请求整段会话授权。
+沙盒、插件权限、输入校验和工具已有的业务确认继续独立生效，例如内容生成计划仍须由用户在全局弹窗确认。
+工具描述应说明实际会发生的文件写入、费用和外部动作，不能承诺宿主会自动拦截误调用。
+
+## Skill 的引导设计
+
+Skill 走渐进披露：清单里只有 name + description（每轮都在 prompt 里），正文按 `invoke_skill`
+加载（只在被选中时付费）。所以：
+
+- **description 是功能与选择入口**，完整描述 Skill 自身能完成的任务和专业方法。
+  不要为了防误调用删减功能、把创意与审查能力限定为已有工作流，或要求用户显式点名 Skill。任务匹配应由选择层结合用户目标与上下文完成。
+- **规则、流程、约束全部放正文。** 任何"你想让模型每次用你的工具前都知道"的长内容，都属于
+  skill 正文而不是工具 description；用工具 description 的一句话把模型引到 skill
+  （"invoke the vetta-ui-design skill for the rules before writing any of them"）。
+- frontmatter 的 `agent_mode` 已废弃，写了会被忽略。
+- 选用相关 Skill 后，正常执行完成用户目标所需的步骤；加载方法本身不代表授权执行与目标无关的动作。
+
+## App Action 的发现说明
+
+App Action 还应声明 `usage.target`、`useWhen`、`avoidWhen`、`alternatives`，随 search / describe 返回。
+例如 Vetta 主题设置与网站深色模式、Vetta 定时 Agent 与业务 cron、插件安装与插件源码开发，需要明确区分。
+检索候选不是执行指令；查询/解释不等于修改，不要先调用写入 Action 再把意图判断交给审批框。
+usage 不参与权限决策，也不进入正向检索文本。合同见 [app-actions.md](./app-actions.md#模型选择边界)。
+
+## 系统插件 / 宿主侧作者的额外杠杆
+
+以下两个面属于宿主，第三方插件碰不到；内部开发者新增一条"路线级"能力（新的画布、新的重交付
+形态）时应当考虑：
+
+1. **mode md 的路线段**（`apps/desktop/src/main/agent-modes/modes/*.md`）：如果你的能力构成一条
+   与"仓库内写代码 / 文档交付"并列的新路线，需要在相关模式的路线段用**类别措辞**声明它的
+   默认位次与准入条件（参考 coding.md 的 "Default route for UI work" 段）。纪律：永不出现具体
+   工具名或插件名——宿主描述任务类别，插件用 description 自归类。
+2. **工作区事实探测**（`packages/coding-agent/src/model-context/workspace-facts.ts`）：为模型提供实际存在的项目形态与资源。
+   文件或画布的存在只能辅助识别上下文，不能单凭标记就推断用户希望编辑它，更不能据此创建或运行新任务。
+   注意它在会话创建时探测一次并固化。
+
+## 第三方插件作者的边界
+
+- 你**不能**改 mode md、workspace facts——你的全部引导面是：name、
+  description（正反触发段）、参数 schema、返回值、skill。这个约束是
+  刻意的：它保证任何插件都不能为自己抢占解释层。
+- `ctx.getAgentMode()` 读到的是**新会话默认模式**，不是当前会话固化的模式——只能用于
+  展示层软性定制（不同文案、不同默认视图），**禁止**在 tool / hook handler 里用它做行为
+  分支（handler 可能跑在一个模式与默认值不同的会话里）。未知模式 id 一律按通用处理。
+- Hook 按 `scope_use` + 事件/工具 matcher 触发，与模式无关——你的 hook 在所有模式下都会跑，
+  按此设计幂等性。
+
+## 反模式清单
+
+| 反模式 | 为什么无效/有害 | 正解 |
+| --- | --- | --- |
+| 写 `agent_mode` 期待模式偏好 | 字段语义为零，纯装饰 | 反向触发段自归类 |
+| 把使用规则塞进 description | 每轮计费、稀释触发信号 | 规则进 skill 正文，description 引流 |
+| 用 `toolPolicy.deny` 表达"不推荐" | deny 是硬闸，模型连看都看不到 | 反向触发段 + 替代路径 |
+| 依赖清单位置/注册顺序 | 无法稳定表达适用条件 | 明确目标与排除场景 |
+| handler 里读 `getAgentMode()` 分支行为 | 读的是默认值不是会话值，必然出错 | 行为分支由输入参数或工作区状态驱动 |
+| 返回裸数据/裸错误 | 浪费每轮必读的引导面 | 返回值带"下一步该做什么" |
+
+## 发布前自检清单
+
+- [ ] 工具名是动词化的具体名，带产品前缀避免碰撞
+- [ ] description 有正向触发段（用户任务措辞）
+- [ ] 有真实误调场景的，写了反向触发段 + 替代路径
+- [ ] Skill frontmatter 完整保留自身功能，不以收窄能力替代选择判断；App Action 的 search / describe 能看到 usage
+- [ ] 成对验证相似措辞下不同目标的选择，以及查询不会自动变成修改；合同测试不冒充模型效果评估
+- [ ] 长规则在 skill 正文，description 不超过一段
+- [ ] 返回值在引导下一步，错误返回可执行
+- [ ] 描述写明实际副作用，已有业务确认与权限校验仍然有效
+- [ ] 没有写 `agent_mode`，没有在 handler 里读 `getAgentMode()`
+- [ ] （宿主侧）构成新路线的能力更新了 mode md 类别措辞 / facts 探测，并保持零插件点名
+
+## Vetta 扩展设计的八荣八耻
+
+- 以描述任务为荣，以罗列功能为耻。
+- 以指明何时别用为荣，以逢场必荐自己为耻。
+- 以返回值引路为荣，以裸数据甩锅为耻。
+- 以规则归入 skill 为荣，以 description 灌水为耻。
+- 以说明实际影响为荣，以隐瞒费用和外部动作为耻。
+- 以类别措辞自归类为荣，以字段注册求偏爱为耻。
+- 以一句 note 点睛为荣，以三条建议并列为耻。
+- 以放手让模型判断为荣，以硬闸藏匿能力为耻。