开发插件

概述

OpenVort 的扩展系统支持两种类型：Plugin（代码扩展）和 Skill（知识注入），均可通过扩展市场分发。

Plugin 开发

方式一：标准 Python 包 (PyPI)

基于 Python entry_points 机制，适合正式发布的插件。

插件结构

openvort-plugin-example/
├── src/
│   └── openvort_plugin_example/
│       ├── __init__.py
│       ├── plugin.py      # 插件主类
│       ├── tools.py       # 工具定义
│       └── prompts.py     # Prompt 定义
├── pyproject.toml
└── README.md

实现插件

1. 定义 Tool

from openvort.plugin import BaseTool

class MyTool(BaseTool):
    name = "my_tool"
    description = "A description of what this tool does"

    parameters = {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The search query"
            }
        },
        "required": ["query"]
    }

    async def execute(self, query: str) -> str:
        return f"Result for: {query}"

2. 定义 Plugin

from openvort.plugin import BasePlugin

class MyPlugin(BasePlugin):
    name = "my_plugin"
    description = "My custom plugin"

    def get_tools(self):
        return [MyTool()]

    def get_prompts(self):
        return ["You have access to my_tool for..."]

3. 注册入口点

在 pyproject.toml 中注册：

[project.entry-points."openvort.plugins"]
my_plugin = "openvort_plugin_example:MyPlugin"

4. 安装和使用

pip install -e .

插件会被自动发现和加载，无需额外配置。

方式二：Bundle 模式 (推荐新手)

无需发布到 PyPI，直接将代码打包上传到扩展市场。

插件结构

my-plugin/
├── plugin.py          # 插件主类
├── tools.py           # 工具定义
├── manifest.json      # 元数据（可选）
├── README.md
└── requirements.txt   # 依赖（可选）

manifest.json 示例

{
  "displayName": "My Plugin",
  "description": "A brief description",
  "version": "1.0.0",
  "entryPoint": "plugin:MyPlugin",
  "packageName": "",
  "category": "general",
  "tags": ["example"],
  "license": "MIT-0",
  "toolsCount": 1,
  "promptsCount": 0,
  "configSchema": [],
  "compatVersion": ">=0.1.0"
}

发布到市场

# 自动检测类型、打包上传
openvort marketplace publish ./my-plugin

# 指定类型和 Slug
openvort marketplace publish ./my-plugin --type plugin --slug my-plugin

Skill 开发

方式一：网页表单

在 扩展市场 直接填写 Markdown 内容。适合简单的单文件 Skill。

方式二：Bundle 模式

适合需要附带脚本、配置模板、示例文件的 Skill。

Skill 结构

my-skill/
├── SKILL.md           # 核心内容（必须）
├── README.md          # 详细说明（可选）
├── manifest.json      # 元数据（可选）
├── templates/         # 配置模板
│   └── config.yaml
├── examples/          # 示例文件
│   └── usage.md
└── scripts/           # 辅助脚本
    └── setup.sh

SKILL.md 示例

# 代码审查专家

你是一名资深代码审查专家。

## 职责

- 审查代码质量和规范性
- 识别潜在的安全漏洞
- 给出具体的改进建议

## 审查标准

1. 代码风格一致性
2. 错误处理完整性
3. 性能优化建议
4. 安全性检查

manifest.json 示例

{
  "displayName": "Code Review Expert",
  "description": "AI-powered code review skill",
  "version": "1.0.0",
  "skillType": "role",
  "category": "development",
  "tags": ["code-review", "development"],
  "license": "MIT-0",
  "compatVersion": ">=0.1.0"
}

发布到市场

openvort marketplace publish ./my-skill

系统会自动检测到 SKILL.md 并将类型设为 Skill。

CLI 命令参考

# 发布扩展
openvort marketplace publish ./folder [--type auto|skill|plugin] [--slug name]

# 搜索市场
openvort marketplace search "keyword" [--type skill|plugin]

# 安装扩展
openvort marketplace install skill author/slug
openvort marketplace install plugin author/slug

# 同步更新
openvort marketplace sync [--all]

# 列出已安装
openvort marketplace list

# 卸载扩展
openvort marketplace uninstall slug

最佳实践

1. Tool 命名 — 使用清晰的动词+名词格式，如 create_task、search_issues
2. 参数描述 — 为每个参数提供详细的 description，这直接影响 AI 的调用准确性
3. 错误处理 — 返回用户友好的错误信息，AI 会基于此向用户解释
4. 幂等性 — 尽量保证 Tool 的幂等性，避免重复调用产生副作用
5. 内容 Hash — 修改内容后无需手动改版本号，系统自动通过 SHA-256 Hash 检测变更