openwebui-extensions GEMINI.md

OpenWebUI Extensions — Gemini CLI Project Context

This file is loaded automatically by Gemini CLI as project-level instructions. Full engineering spec: .github/copilot-instructions.md

---

Project Overview

openwebui-extensions is a collection of OpenWebUI plugins authored by Fu-Jie.

Repository: https://github.com/Fu-Jie/openwebui-extensions

Plugin types: actions / filters / pipes / pipelines / tools

---

Non-Negotiable Rules

1. No auto-commit. Never run git commit, git push, or gh pr create unless the user says "发布" / "release" / "commit it". Default output = local file changes only.
2. No silent failures. All errors must surface via __event_emitter__ notification or backend logging.
3. No hardcoded model IDs. Default to the current conversation model; let Valves override.
4. Chinese responses. Reply in Simplified Chinese for all planning, explanations, and status summaries. English only for code, commit messages, and docstrings.
5. Knowledge capture. Whenever you discover a non-obvious pattern, gotcha, or workaround (e.g., internal API contracts, mock object requirements, parameter injection quirks), save it to .agent/learnings/{topic}.md before ending the session. See .agent/learnings/README.md for format and existing entries.

---

Plugin File Contract

Every plugin MUST be a single-file i18n Python module:

plugins/{type}/{name}/{name}.py   ← single source file, built-in i18n
plugins/{type}/{name}/README.md   ← English docs
plugins/{type}/{name}/README_CN.md ← Chinese docs

Docstring (required fields)

"""
title: Plugin Display Name
author: Fu-Jie
author_url: https://github.com/Fu-Jie/openwebui-extensions
funding_url: https://github.com/open-webui
version: 0.1.0
description: One-line description.
"""

Required patterns

• Valves(BaseModel) with UPPER_SNAKE_CASE fields
• _get_user_context(__user__) — never access __user__ directly
• _get_chat_context(body, __metadata__) — never infer IDs ad-hoc
• _emit_status(emitter, msg, done) / _emit_notification(emitter, content, type)
• Async I/O only — wrap sync calls with asyncio.to_thread
• logging for backend logs — no bare print() in production