Fu-Jie_openwebui-extensions/docs/development/copilot-engineering-plan.md

Copilot Engineering Configuration Plan

This document defines production-grade engineering configuration for plugin development with GitHub Copilot, Gemini CLI, and antigravity development mode.

---

1. Goals

• Standardize plugin engineering workflow for AI-assisted development.
• Support dual assistant stack:
  • GitHub Copilot (primary in-editor agent)
  • Gemini CLI (secondary external execution/research lane)
• Introduce antigravity development mode for safer, reversible, high-velocity iteration.

---

2. Scope

This plan applies to:

• Plugin development (actions, filters, pipes, pipelines, tools)
• Documentation synchronization
• File generation/delivery workflow in OpenWebUI
• Streaming/tool-call rendering compatibility

---

3. Engineering Configuration (Copilot-centered)

3.1 Source of truth

• Primary standard file: .github/copilot-instructions.md
• Agent workflow file: .agent/workflows/plugin-development.md
• Runtime guidance docs:
  • docs/development/plugin-guide.md
  • docs/development/plugin-guide.zh.md

3.2 Required development contract

• Single-file i18n plugin source.
• Bilingual README (README.md + README_CN.md).
• Safe context extraction (_get_user_context, _get_chat_context).
• Structured event handling (status, notification, execute).
• No silent failures; logging + user-visible status.

3.3 Tool definition contract (Copilot SDK)

• Define tool params explicitly with pydantic.BaseModel.
• Use params_type in tool registration.
• Preserve defaults by avoiding forced null overrides.
• Keep tool names normalized and deterministic.

---

4. Gemini CLI Compatibility Profile

Gemini CLI is treated as a parallel capability channel, not a replacement.

4.1 Usage boundary

• Use for:
  • rapid drafts
  • secondary reasoning
  • cross-checking migration plans
• Do not bypass repository conventions or plugin contracts.

4.2 Output normalization

All Gemini CLI outputs must be normalized before merge:

• Match repository style and naming rules.
• Preserve OpenWebUI plugin signatures and context methods.
• Convert speculative outputs into explicit, testable implementation points.

4.3 Conflict policy

When Copilot and Gemini suggestions differ:

1. Prefer repository standard compliance.
2. Prefer safer fallback behavior.
3. Prefer lower integration risk.

---

5. Antigravity Development Mode

Antigravity mode means high-speed delivery with strict reversibility.

5.1 Core principles

• Small, isolated edits
• Deterministic interfaces
• Multi-level fallback paths
• Roll-forward and rollback both feasible

5.2 Required patterns

• Timeout guards on frontend execution calls.
• Path sandbox validation for all workspace file operations.
• Dual-channel upload fallback (API first, local/DB fallback).
• Progressive status reporting for long-running tasks.

---

6. File Creation & Delivery Standard

6.1 Create files in controlled workspace

• Write artifacts in current workspace scope.
• Never use paths outside workspace boundary for deliverables.

6.2 Publish protocol

Use 3-step delivery:

1. local write
2. publish from workspace
3. present /api/v1/files/{id}/content link

6.3 Metadata policy

• Set skip_rag=true for generated downloadable artifacts where applicable.
• Keep filename generation deterministic (chat_title -> markdown_title -> user+date).

---

7. Plugin Development Norms for Multi-Agent Stack

• Compatible with GitHub Copilot and Gemini CLI under same coding contract.
• Keep streaming compatible with OpenWebUI native blocks (<think>, <details type="tool_calls">).
• Escape tool card attributes safely (") for parser stability.
• Preserve async non-blocking behavior.

---

8. Documentation Sync Rule

Any meaningful plugin engineering change must sync:

1. plugin code
2. plugin bilingual README
3. docs plugin detail pages (EN/ZH)
4. docs plugin indexes (EN/ZH)
5. root README update badge/date when release is prepared

---

9. Acceptance Checklist

• Copilot config and workflow references are valid.
• Gemini CLI outputs can be merged without violating conventions.
• Antigravity safety mechanisms are present.
• File creation and publication flow is reproducible.
• Streaming/tool-card output format remains OpenWebUI-compatible.