一份清单，就能扩展 Velo

给 AI 用的 Skill

把下面两个目录复制到你自己项目的 .agents/skills/。Cursor / Claude / Codex / Pi 都能读 SKILL.md。划词插件适用于 Velo 0.1.0+，主题包需要 0.2.0+。

• velo-plugin-authoring 划词插件 · Velo 0.1.0+
• velo-theme-authoring 主题包 · Velo 0.2.0+

机器可读目录：

/skills/index.json

能做什么

打开搜索、改写选区、按当前网页隐藏动作、调用已声明的 HTTPS API。不能弹自己的窗口、读盘、起进程、继承环境变量，或连接未声明的地址。一个包只占一行插件，多个功能走子菜单。

最小例子

id 用反转域名，不要用 velo.*（官方保留）。权限只声明实际用到的。未知字段会被拒绝。

{
  "schema": 2,
  "id": "com.example.lookup",
  "name": "Lookup",
  "version": "1.0.0",
  "api_version": "1.0.0",
  "min_host_version": "0.1.0",
  "permissions": ["selection_read", "open_url"],
  "targets": ["selection"],
  "actions": [{
    "id": "google",
    "label": "Google",
    "icon": "icon:search",
    "action": {
      "type": "open_url",
      "url": "https://www.google.com/search?q={sel_enc}"
    }
  }]
}

主题包

主题包是另一种独立类型，只替换外观令牌，不进入划词浮条。需要 Velo Desktop 0.2.0 或更新版本；旧版 0.1.0 无法安装。

id 用反转域名，不要用 velo.*。permissions 和 actions 必须为空。min_host_version 必须是 0.2.0 或更高。

{
  "schema": 2,
  "id": "com.example.theme.paper",
  "name": "Paper",
  "version": "1.0.0",
  "api_version": "1.0.0",
  "min_host_version": "0.2.0",
  "permissions": [],
  "targets": ["theme"],
  "theme": {
    "appearance": "light",
    "swatch": ["#3f6f5b", "#fffcf5", "#f4f1ea"],
    "tokens": {
      "--color-bg": "#f4f1ea",
      "--color-bg-elevated": "#fbf8f1",
      "--color-surface": "#fffcf5",
      "--color-surface-2": "#efebe1",
      "--color-surface-3": "#e4ddd0",
      "--color-panel": "#f7f3ea",
      "--color-panel-elevated": "#fffdf7",
      "--color-field": "#fffdf8",
      "--color-border": "rgb(50 44 32 / 0.16)",
      "--color-border-strong": "rgb(50 44 32 / 0.3)",
      "--color-text": "#2a2620",
      "--color-text-2": "#5c564a",
      "--color-text-3": "#827b6d",
      "--color-accent": "#3f6f5b",
      "--color-accent-foreground": "#f7f4ea",
      "--color-accent-soft": "#2f5646"
    }
  },
  "actions": []
}

在仓库根目录：velo-plugin init --theme ./my-theme com.example.theme.paper "Paper"。然后打开 Velo 0.2.0 → 外观 → 导入 .vplugz。

命令

在仓库根目录安装一次独立 CLI，之后直接运行 velo-plugin：

./scripts/install-plugin-cli.sh
velo-plugin init ./my-plugin com.example.lookup "Lookup"
velo-plugin init --theme ./my-theme com.example.theme.paper "Paper"
velo-plugin validate ./my-plugin
velo-plugin pack ./my-plugin ./my-plugin.vplugz

然后打开 Velo → 划词 → 导入 .vplugz。也可以选中 #velo 片段，浮条点「安装」，或用「粘贴片段」。含密钥或 Shell 的包必须先 keygen 再 sign，私钥不要上传。

片段导入

把 #velo 加在 plugin.json 前面，选中后浮条会出现「安装」。#popclip 静态片段同样走预览确认。片段不能带脚本、联网、密钥或 Shell。

#velo
{
  "schema": 2,
  "id": "com.example.lookup",
  "name": "Lookup",
  "version": "1.0.0",
  "api_version": "1.0.0",
  "min_host_version": "0.1.0",
  "permissions": ["selection_read", "open_url"],
  "targets": ["selection"],
  "actions": [{
    "id": "google",
    "label": "Google",
    "action": {
      "type": "open_url",
      "url": "https://www.google.com/search?q={sel_enc}"
    }
  }]
}

从 PopClip 过来

URL / 按键 / 编码 / 当前网站 / 邮箱能直接写成 plugin.json。JS、Shell、Config.js 不要搬，改写成声明式动作或受控 Rhai 脚本。完整对照见仓库 docs/PLUGIN_POPCLIP.md。

何时写 Rhai 脚本

只有声明式做不到时才写脚本。可编程 Guest 只有 Rhai（plugin.rhai），没有 JS、WASM 或 WASI：没有文件系统、进程或环境变量；网络必须写在清单 origins 里；结果由 Host 再次校验并展示（show / preview / copy / paste），插件不能自己开窗口。

fn prepare(ctx) {
    [#{ actionId: "run", label: "Run" }]
}

fn execute(action_id, ctx) {
    plugin_text(ctx.text, "preview")
}

宿主函数：option_get / secret_get / state_get / state_set / state_delete / progress / network_request / log / url_encode / parse_json / to_json / plugin_text / plugin_fail。完整教程与 Rhai 语义陷阱：

/skills/velo-plugin-authoring/references/script.md

上架社区

把签名包放到允许的 HTTPS 地址 → 授权站领取 challenge → velo-plugin attest 生成 submission.json → 粘贴提交 → 审核通过后出现在插件社区。完整步骤与陷阱见仓库 docs/PLUGIN_AUTHORING.md。