@ever-works/ 插件

Ever Works平台的插件系统合同、助手和公用事业.

概览

这个软件包提供了为 Ever Works 生态系统构建插件所需的一切:

• 合同: TypeScript 接口定义插件能力
• 摘要类: 常见插件类型的基础执行
• 帮助者: 用于设置、验证和上下文的功能
• 测试公用事业: 用于插件开发的模拟和测试工具

安装

pnpm add @ever-works/plugin

关键特性

• 独立: 无 NestJS 依赖性 - 插件在任意类型脚本环境中工作
• 类型安全: 编译时间验证 TypeScript 结合和映射类型
• 基于能力的: 插件宣布能力并执行相应的接口
• 可测试: 内置的模拟和测试工具用于综合测试

软件包结构

@ever-works/plugin
├── /contracts      # Plugin interfaces and capability definitions
├── /pipeline       # Pipeline step types and execution context
├── /events         # Event system types
├── /settings       # Settings types and JSON Schema definitions
├── /common         # Shared types (domain, item, form-field)
├── /helpers        # Utility functions
├── /abstract       # Abstract base classes
└── /testing        # Test utilities and mocks

使用量

创建基本插件

import { BasePlugin, type PluginContext, type ValidationResult } from '@ever-works/plugin';

export class MyPlugin extends BasePlugin {
    readonly id = 'my-plugin';
    readonly name = 'My Plugin';
    readonly version = '1.0.0';
    readonly category = 'utility';
    readonly capabilities = ['custom'] as const;

    async onLoad(context: PluginContext): Promise<void> {
        await super.onLoad(context);
        this.log('Plugin loaded!');
    }
}

创建 Git 提供者插件

Git 提供者插件执行 IGitProviderPlugin 包括:

• 认证方法数字 : getAuth(), (中文(简体) ), getCloneUrl(), (中文(简体) ), getWebUrl()
• 仓库 API 操作数字 : createRepository(), (中文(简体) ), getRepository(), (中文(简体) ), deleteRepository()
• 用户/操作数字 : getUser(), (中文(简体) ), getOrganizations()
• 拉动请求操作数字 : createPullRequest(), (中文(简体) ), mergePullRequest()
• 分支业务数字 : listBranches()

本地 git 操作( clone, push, content)由平台提供 GitProvider 基准类 packages/agent。 。 。 .

import { BaseGitProvider, type IGitProviderPlugin, type GitAuth } from '@ever-works/plugin';

export class GitHubPlugin extends BaseGitProvider implements IGitProviderPlugin {
    readonly id = 'github';
    readonly name = 'GitHub';
    readonly version = '1.0.0';
    readonly providerName = 'github';

    // Provider-specific authentication
    getAuth(token: string): GitAuth {
        return { username: 'x-access-token', password: token };
    }

    getCloneUrl(owner: string, repo: string): string {
        return `https://github.com/${owner}/${repo}.git`;
    }

    getWebUrl(owner: string, repo: string): string {
        return `https://github.com/${owner}/${repo}`;
    }

    // API Operations (provider-specific implementation)
    async createRepository(options, token) {
        // Use Octokit or fetch to call GitHub API
    }

    async getRepository(owner, repo, token) {
        // Use Octokit or fetch to call GitHub API
    }

    async getUser(token) {
        // Use Octokit or fetch to call GitHub API
    }

    async getOrganizations(token) {
        // Use Octokit or fetch to call GitHub API
    }

    async listBranches(owner, repo, token) {
        // Use Octokit or fetch to call GitHub API
    }

    async createPullRequest(options, token) {
        // Use Octokit or fetch to call GitHub API
    }

    async mergePullRequest(owner, repo, prNumber, options, token) {
        // Use Octokit or fetch to call GitHub API
    }

    async deleteRepository(owner, repo, token) {
        // Use Octokit or fetch to call GitHub API
    }

    // Local git operations - inherited from platform's GitProvider
    // clone, push, commit, pull, etc. are implemented once and shared
}

创建管道修饰插件

管道修饰器在现有管道中添加、替换或禁用步骤:

import { BasePipelineStep, type IPipelineModifierPlugin, type IPipelineContext } from '@ever-works/plugin';

export class MyModifierPlugin extends BasePipelineStep implements IPipelineModifierPlugin {
    readonly id = 'my-modifier';
    readonly name = 'My Modifier';
    readonly version = '1.0.0';
    readonly targetPipelines = ['standard-pipeline'];

    getStepDefinition() {
        return {
            id: 'custom-step',
            name: 'Custom Step',
            position: { type: 'after', stepId: 'web-search' },
            provides: ['customData']
        };
    }

    async execute(context: IPipelineContext): Promise<IPipelineContext> {
        // Your logic here
        return context;
    }
}

测试插件

import { createMockPluginContext, createTestHarness, testBasePluginContract } from '@ever-works/plugin/testing';

describe('MyPlugin', () => {
    it('passes contract tests', async () => {
        const plugin = new MyPlugin();
        const results = await testBasePluginContract(plugin);
        expect(results.every((r) => r.passed)).toBe(true);
    });

    it('loads correctly', async () => {
        const plugin = new MyPlugin();
        const harness = createTestHarness(plugin, {
            settings: { apiKey: 'test-key' }
        });

        await harness.load();

        expect(harness.isLoaded).toBe(true);
    });
});

可用能力

Git 提供架构

Git提供商系统分别关注:

1. IGitOperations - 当地基特业务(克龙、推、承诺、拉)

   • 在平台上使用同位素基特执行一次
   • 所有git 提供者共享( GitHub, GitLab等)

2. IGitProviderPlugin - 供应商专用API业务

   • 每个提供者执行自己的API呼叫
   • 包括:创建仓库,获取Pullrequest,获取User等.

3. IOAuthPlugin - OAuth认证(独立能力)

   • 支持 OAuth 的提供者
   • 可与提供设备的能力相结合

┌─────────────────────────────────────────────────────────────────┐
│                    GIT PROVIDER ARCHITECTURE                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  IGitOperations (local git - shared implementation)             │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ cloneOrPull(), pull(), push(), commit(), add(), addAll()│    │
│  │ getCurrentBranch(), switchBranch(), getStatus()         │    │
│  │ getLocalDir(), removeLocalDir()                         │    │
│  │                                                          │    │
│  │ Implemented once in platform (packages/agent)           │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  IGitProviderPlugin (provider API - each plugin implements)     │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ getAuth(), getCloneUrl(), getWebUrl()                   │    │
│  │ createRepository(), getRepository(), deleteRepository() │    │
│  │ getUser(), getOrganizations()                           │    │
│  │ createPullRequest(), mergePullRequest(), listBranches() │    │
│  │                                                          │    │
│  │ GitHub uses Octokit, GitLab uses their API, etc.        │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

类型警卫

import { isGitProviderPlugin, isAiProviderPlugin, hasCapability } from '@ever-works/plugin';

if (isGitProviderPlugin(plugin)) {
    const repo = await plugin.getRepository('owner', 'repo', token);
}

if (hasCapability(plugin, 'ai-provider')) {
    const models = await plugin.listModels();
}

出口

主导出

import { IPlugin, BasePlugin, createMockPluginContext } from '@ever-works/plugin';

子路径导出

// Contracts only
import { IPlugin, IGitProviderPlugin, IGitOperations } from '@ever-works/plugin/contracts';

// Pipeline types
import { IPipelineContext, PipelineStepDefinition } from '@ever-works/plugin/pipeline';

// Events
import { PluginEventName, PluginEventPayloads } from '@ever-works/plugin/events';

// Settings
import { JsonSchema, ValidationResult } from '@ever-works/plugin/settings';

// Common types
import { DomainType, ItemData, Category } from '@ever-works/plugin/common';

// Helpers
import { resolveSetting, validateString } from '@ever-works/plugin/helpers';

// Abstract classes
import { BasePlugin, BaseGitProvider } from '@ever-works/plugin/abstract';

// Testing
import { createMockPluginContext, createTestHarness } from '@ever-works/plugin/testing';

许可证

AGPL-3.0 导弹