155 lines
4.2 KiB
Markdown
155 lines
4.2 KiB
Markdown
|
# 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.
|