让开源，少一点语言距离。
npm包中文文档

@ever-works/gemini-plugin

中文文档
1.0.18发布于 2026/11/03AGPL-3.0TypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 6108

Gemini Generator Plugin - Full pipeline plugin that delegates generation to Gemini CLI

原始使用文档
中文原文
文档目录14 节
  1. Plugin metadata
  2. Pipeline Steps
  3. Authentication
  4. Settings
  5. Supported Models
  6. Form Schema
  7. Prompt System
  8. Binary Management
  9. Error Handling
  10. Project Structure
  11. Development
  12. Troubleshooting
  13. Documentation
  14. License

@ever-works/gemini-plugin

Full pipeline plugin that delegates work generation to the Gemini CLI. A single Gemini CLI session autonomously handles web search, content creation, and file generation inside a temporary workspace.

Note: This is the Gemini CLI pipeline. For the Gemini AI provider (chat completions / embeddings via the Generative Language API), see @ever-works/google-plugin.

Plugin metadata

FieldValue
IDgemini
Categorypipeline
Capabilitiespipeline, form-schema-provider
AuthorEver Works Team
LicenseAGPL-3.0
Built-inyes
Auto-enableno

Pipeline Steps

The plugin runs 6 sequential steps:

#StepDescriptionOptional
1Setup Gemini CLIInstalls/caches the Gemini CLI via npm and resolves authNo
2Prepare ContextCreates a temp workspace, seeds existing items and metadataNo
3Generate ItemsExecutes Gemini CLI to research and generate items as JSON filesNo
4Collect ResultsReads generated JSON files back into the pipeline resultNo
5Capture ScreenshotsTakes screenshots for generated items (via screenshot provider)Yes
6CleanupRemoves the temporary workspaceYes

During step 3, a taxonomy watcher monitors the workspace for new item files and keeps _meta/ taxonomy files (categories, tags, brands) in sync in real time. Progress is reported per item as files appear.

Authentication

Provide a Gemini API key from Google AI Studio in plugin settings (apiKey field).

This plugin does not reuse host machine Gemini CLI login state from ~/.gemini/. Credentials must come from Ever Works user settings so each user keeps isolated auth. The runtime also uses an isolated per-user Gemini home/config work instead of the machine user's home.

Settings

SettingTypeScopeDescription
apiKeystringuserGemini API key (secret, supports env var PLUGIN_GEMINI_API_KEY)
modelstringuserModel for generation (default: gemini-2.5-flash)
versionstringhiddenGemini CLI version to install (default: latest)

Supported Models

  • Gemini 2.5 Flash (default) - 200k context
  • Gemini 2.5 Pro - 200k context
  • Gemini 2.0 Flash - 200k context

Form Schema

The plugin provides a user-facing form with two configurable fields:

FieldTypeDefaultValidationDescription
target_itemsnumber501-500Target number of new items to generate
capture_screenshotsbooleanfalse-Take screenshots for generated items

Prompt System

Prompts are managed through a prompt facade (e.g., Langfuse). When no external prompt is found, hardcoded defaults are used as fallback.

Prompt keys:

  • gemini.system - System prompt template
  • gemini.user - User prompt template

Both support variable substitution for work context, existing items, categories, tags, and brands.

Binary Management

The plugin runs Gemini CLI through npx:

  • Uses npx --yes @google/gemini-cli
  • Supports version pinning through @google/gemini-cli@<version>
  • Default version: latest

Error Handling

  • Non-zero exit codes: Treated as soft warnings. If items were still produced, the result succeeds with warnings attached.
  • Empty results: If Gemini completes without producing any valid item JSON files, an error is thrown with CLI output excerpts for debugging.
  • Masked secrets: The getRealSecret helper filters out UI placeholder values before using credentials.

Project Structure

src/
  gemini.plugin.ts         # Main plugin class (IPlugin, IPipelinePlugin, IFormSchemaProvider)
  types.ts                 # Step IDs, constants
  steps.ts                 # Pipeline step definitions
  form-schema.ts           # Form fields, groups, validation
  prompt-keys.ts           # Prompt facade keys
  index.ts                 # Public exports
  prompt/
    system-prompt.ts       # Default prompts and variable builders
  utils/
    binary-manager.ts      # CLI installation via npm
    pipeline-helpers.ts    # State management, auth resolution, progress reporting
    process-runner.ts      # Gemini CLI subprocess execution
    workspace-manager.ts   # Workspace I/O (create, seed, read, cleanup)
    screenshot-capture.ts  # Screenshot facade integration
    taxonomy-sync.ts       # Merge new categories/tags/brands into _meta files
    taxonomy-watcher.ts    # Filesystem watcher for live taxonomy sync
    platform.ts            # Platform detection helpers

Development

# Build
pnpm build

# Type-check
pnpm type-check

# Run tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage
pnpm test:coverage

Troubleshooting

SymptomLikely causeFix
Generation never starts / stays at 0%gemini not selected as the active pipeline plugin for this workOpen the work → Plugins → pipeline capability and set gemini as the active pipeline; or set it as the global pipeline default in Settings → Plugins
Step fails with No AI / search / screenshot provider configuredPipeline depends on capability plugins that are not enabled or have no credentialsEnable and configure the matching capability plugin (AI provider, search, screenshot, content-extractor) for the work or globally
Step output looks wrong / genericForm-field tuning not set; pipeline using defaults that don't match the work's domainOpen the Generator Form for the work, set domain-specific fields (categories, target keywords, source URLs), and re-run the affected step
Subprocess error: command not foundGemini Generator CLI not installed on the host running the APIInstall the Gemini Generator CLI on the API host and ensure it is on PATH; verify by running which <cli> from the same shell that launches pnpm dev:api
Authentication / device-auth flow stallsDevice-auth code never confirmed in the upstream IDE / browserRe-run the device-auth flow from Settings → Plugins → gemini → Connect, then complete the prompt in the upstream service before the code expires
Pipeline cannot resume after host restartCheckpoint not persisted (only the standard pipeline persists checkpoints today)Cancel the stuck run and re-trigger generation; for production reliability prefer standard-pipeline

Documentation

License

AGPL-3.0

版本与发布记录

@ever-works/gemini-plugin 共发布 15 个版本，首次发布于 2026/06/06；过去 12 个月发布了 15 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本发布日期距今
1.0.18latest2026/11/0310 天前
1.0.172026/10/2817 天前
1.0.162026/10/2717 天前
1.0.152026/10/2717 天前
1.0.142026/10/2420 天前
1.0.132026/10/2025 天前

关于 @ever-works/gemini-plugin 的常见问题

@ever-works/gemini-plugin 是什么？

Gemini Generator Plugin - Full pipeline plugin that delegates generation to Gemini CLI

如何安装 @ever-works/gemini-plugin？

在项目目录运行 npm install @ever-works/gemini-plugin，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@ever-works/plugin（^1.2.16）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

@ever-works/gemini-plugin 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@ever-works/gemini-plugin 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require() 都可以使用，打包工具会自动选择合适的版本。

@ever-works/gemini-plugin 可以商用吗？

@ever-works/gemini-plugin 使用 AGPL-3.0 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

@ever-works/gemini-plugin 的下载量有多少？

根据 npm 官方下载统计，@ever-works/gemini-plugin 在 2026/10/14 – 2026/11/12 这 30 天内被下载 6,108 次，日均约 204 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@ever-works/gemini-plugin 还在维护吗？

最新版本 1.0.18 发布于 2026/11/03（10 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/06/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。