# @ever-works/plugin 中文文档 规范地址：https://npmcn.com/package/%40ever-works/plugin/ 版本：1\.2\.16 npm 元数据更新时间：2026-11-03T08:55:08.346Z 中文译文更新时间：2026-11-14T01:20:15.666Z 软件包许可：AGPL-3\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40ever-works/plugin 原文对照：https://npmcn.com/package/%40ever-works/plugin/?lang=original 项目主页：https://github.com/ever-works/ever-works/tree/main/packages/plugin#readme 源码仓库：https://github.com/ever-works/ever-works ## 关键信息（来自 npm 元数据） - 包体积（解压后）：2.2 MB，96 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：3 个 - peer 依赖：stopword ^3\.1\.5，isomorphic-git ^1\.27\.0，@langchain/core ^1\.3\.0，@langchain/openai ^1\.7\.1 - 首次发布：2026-09-20T22:32:04.502Z - 最新版本发布：2026-11-03T08:55:07.999Z - 近 30 天下载量：7176（2026-10-14 至 2026-11-12，npm 官方下载统计） - 已发布版本数：17（近 12 个月 17 个） ## 中文简介 Ever Works平台的插件系统合同、助手和公用事业 ## 安装 ```sh npm install @ever-works/plugin ``` 也可以使用：`pnpm add @ever-works/plugin`、`yarn add @ever-works/plugin`、`bun add @ever-works/plugin` ## README # @ever-works/ 插件 Ever Works平台的插件系统合同、助手和公用事业. ## 概览 这个软件包提供了为 Ever Works 生态系统构建插件所需的一切: - **合同**: TypeScript 接口定义插件能力 - **摘要类**: 常见插件类型的基础执行 - **帮助者**: 用于设置、验证和上下文的功能 - **测试公用事业**: 用于插件开发的模拟和测试工具 ## 安装 ```bash 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 ``` ## 使用量 ### 创建基本插件 ```typescript 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 { 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`。 。 。 . ```typescript 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 } ``` ### 创建管道修饰插件 管道修饰器在现有管道中添加、替换或禁用步骤: ```typescript 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 { // Your logic here return context; } } ``` ### 测试插件 ```typescript 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-provider` | `IGitProviderPlugin` | Git 仓库和 API 操作 | | `oauth` | `IOAuthPlugin` | 基于 OAuth 认证 | | `deployment` | `IDeploymentPlugin` | 部署到托管平台 | | `screenshot` | `IScreenshotPlugin` | 抓取网页截图 | | `search` | `ISearchPlugin` | 网络搜索集成 | | `content-extractor` | `IContentExtractorPlugin` | 从网页取出内容 | | `data-source` | `IDataSourcePlugin` | 外部数据来源 | | `ai-provider` | `IAiProviderPlugin` | AI/LLM提供者 | | `pipeline` | `IPipelinePlugin` | 管道实施 | | `pipeline-modifier` | `IPipelineModifierPlugin` | 管道步骤修改器 | | `form-field` | `IFormFieldPlugin` | 自定义窗体字段 | | `sub-provider` | `ISubProviderPlugin` | 次级提供者的执行 | | `config-aware` | `IConfigAwarePlugin` | 对配置更改的反应 | | `custom-capability` | `ICustomCapabilityPlugin` | 定义自定义能力 | ## 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. │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ## 类型警卫 ```typescript 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(); } ``` ## 出口 ### 主导出 ```typescript import { IPlugin, BasePlugin, createMockPluginContext } from '@ever-works/plugin'; ``` ### 子路径导出 ```typescript // 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 导弹 ## 常见问题 ### @ever-works/plugin 是什么？ Ever Works平台的插件系统合同、助手和公用事业 ### 如何安装 @ever-works/plugin？ 在项目目录运行 npm install @ever-works/plugin，或使用 pnpm add / yarn add / bun add。 ### @ever-works/plugin 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @ever-works/plugin 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @ever-works/plugin 可以商用吗？ @ever-works/plugin 使用 AGPL-3\.0 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。 ### @ever-works/plugin 的下载量有多少？ 根据 npm 官方下载统计，@ever-works/plugin 在 2026/10/14 – 2026/11/12 这 30 天内被下载 7,176 次，日均约 239 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @ever-works/plugin 还在维护吗？ 最新版本 1\.2\.16 发布于 2026/11/03（10 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/09/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。