open-webui/Fu-Jie_openwebui-extensions
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9e4195a556e920974d19e264c59b3c0ed99a6b65
Fu-Jie_openwebui-extensions/docs/plugins/pipes/github-copilot-sdk-usage-guide.md
Fu-Jie 0c7201902c feat(github-copilot-sdk): add workspace skills support (v0.9.0) (#51) 
* feat(github-copilot-sdk): add workspace skills support

- Introduce ENABLE_WORKSPACE_SKILLS valve to enable/disable workspace custom tools discovery
- Modify _build_session_config() to auto-load tools from .copilot-skills/ directory
- Add workspace_skills_example.py template with 3 working example tools
- Update README.md and README_CN.md with Workspace Skills guide and usage examples
- Create v0.9.0.md and v0.9.0_CN.md release notes
- Sync version to all docs files (index.md, index.zh.md, and main docs)
- Bump version from 0.8.0 to 0.9.0 across all 7+ locations

* docs: establish temp files handling policy (project-based, not /tmp)

- Add TEMP_FILES_POLICY.md guideline for all skills and workflows
- Update pr-submitter skill to use .temp/ directory instead of /tmp
- Update release-prep skill documentation with temp file convention
- Add .temp/ and .build/ entries to .gitignore
- Create internal policy memo in /memories/repo/

This policy ensures:
- All temporary files stay within project workspace (not system /tmp)
- Alignment with OpenWebUI workspace isolation principles
- Multi-user safety and cleanup traceability
- Consistent handling across all skills and development workflows

* fix(terminology): rename 'workspace skills' to 'workspace custom tools' for accuracy

The term 'Skills' in Anthropic context refers to instruction-based frameworks
(SKILL.md files with YAML frontmatter + markdown), not custom tool functions.

Our implementation uses @define_tool decorator to define custom tools that the
SDK auto-discovers from .copilot-skills/ directory. These are Tools, not Skills.

Changes:
- Rename ENABLE_WORKSPACE_SKILLS valve -> ENABLE_WORKSPACE_TOOLS
- Update all documentation (README, README_CN, docs, release notes)
- Fix section headings and descriptions throughout
- Ensure consistent terminology across all files

This is a terminology-only change; functionality remains identical.

* feat(pipes): release v0.9.0 of GitHub Copilot SDK Pipe

- Integrated OpenWebUI Skills Bridge and manage_skills tool
- Reinforced status bar stability with session_finalized logic
- Added persistent SDK config directory support

* docs(pipes): add comprehensive guides and v0.9.0 notes for Copilot SDK

- Added skill manager and best practices guides
- Added publishing tool documentation
- Included v0.9.0 release notes and deployment script
- Updated usage guides
2026-02-28 03:50:56 +08:00

186 lines
5.0 KiB
Markdown
Raw Blame History

# GitHub Copilot SDK Pipe Detailed Usage Guide
**Author:** [Fu-Jie](https://github.com/Fu-Jie/openwebui-extensions) | **Version:** 0.9.0 | **Project:** [OpenWebUI Extensions](https://github.com/Fu-Jie/openwebui-extensions)
This guide is for production usage. README remains community-facing and concise; this page focuses on step-by-step operations and troubleshooting.
---
## 1. When to Use This Guide
Use this manual if you need to:
- Run GitHub Copilot official models in OpenWebUI
- Use BYOK providers (OpenAI/Anthropic)
- Generate and publish artifacts (Excel/CSV/HTML/PDF)
- Manage Skills with OpenWebUI bridge and `manage_skills`
---
## 2. Pre-flight Checklist
### 2.1 Required components
- OpenWebUI is running (recommended `v0.8.0+` for Rich UI)
- Pipe is installed: `plugins/pipes/github-copilot-sdk/github_copilot_sdk.py`
- Recommended companion filter:
- [GitHub Copilot SDK Files Filter](https://openwebui.com/posts/403a62ee-a596-45e7-be65-fab9cc249dd6)
### 2.2 Authentication (at least one)
You must configure one of the following:
1. `GH_TOKEN` for official GitHub Copilot models
2. `BYOK_API_KEY` for OpenAI/Anthropic style providers
---
## 3. Installation Flow
1. Open OpenWebUI → **Workspace → Functions**
2. Create function and paste `github_copilot_sdk.py`
3. Save and enable
4. In chat model selector, choose:
- `github_copilot_official_sdk_pipe.*` (official)
- or your BYOK model entries
---
## 4. Configuration Baseline
### 4.1 Minimal admin setup
- `GH_TOKEN` or `BYOK_API_KEY`
- `ENABLE_OPENWEBUI_TOOLS = True`
- `ENABLE_MCP_SERVER = True`
- `ENABLE_OPENWEBUI_SKILLS = True`
- `SHOW_THINKING = True`
### 4.2 Recommended production settings
- `COPILOTSDK_CONFIG_DIR=/app/backend/data/.copilot`
- Persists SDK config/session state across restarts
- `OPENWEBUI_SKILLS_SHARED_DIR=/app/backend/data/cache/copilot-openwebui-skills`
- Shared skill cache directory
- `DEBUG=True` during troubleshooting only
### 4.3 User-level overrides
Users can override `GH_TOKEN`, `REASONING_EFFORT`, `BYOK_API_KEY`, `DISABLED_SKILLS`, etc.
---
## 5. Model Access Modes
## 5.1 Official Copilot mode
- Set `GH_TOKEN`
- Use official model catalog
- Supports reasoning effort, tools, infinite session features
## 5.2 BYOK mode
- Set `BYOK_TYPE`, `BYOK_BASE_URL`, `BYOK_API_KEY`
- Leave `BYOK_MODELS` empty for auto-fetch, or set explicit list
- Best when no Copilot subscription is available
---
## 6. Artifact Publishing Workflow (Critical)
Use `publish_file_from_workspace` with the sequence: write → publish → return links.
### 6.1 HTML delivery modes
- `artifacts` (default)
- Returns `[Preview]` + `[Download]`
- `html_embed` can be rendered in a full-height iframe block
- `richui`
- Returns `[Preview]` + `[Download]`
- Rich UI renders automatically (no iframe block in message)
### 6.2 PDF delivery rule
- Output Markdown links only (`[Preview]` + `[Download]` when available)
- **Do not** embed PDF via iframe/html blocks
### 6.3 Images and other files
- Images: prefer direct display + download
- Other artifacts (`xlsx/csv/docx`): provide download links
---
## 7. Skills Operations
> Key rule: `manage_skills` is a **tool**, not a skill; all skills are installed in **one directory**: `OPENWEBUI_SKILLS_SHARED_DIR/shared/`.
## 7.1 OpenWebUI Skills bridge
With `ENABLE_OPENWEBUI_SKILLS=True`:
- Skills from UI sync into SDK directories
- Directory-side updates sync back according to sync policy
## 7.2 `manage_skills` quick actions
- `list`, `install`, `create`, `edit`, `show`, `delete`
## 7.3 Operational tips
- Use `DISABLED_SKILLS` to reduce noisy skill routing
- Keep skill descriptions explicit for better intent matching
---
## 8. First-run Validation Checklist
1. Basic chat response works
2. Tool call can be triggered
3. CSV/XLSX can be published and downloaded
4. HTML mode works (`artifacts` or `richui`)
5. PDF returns links only (no embed)
6. `manage_skills list` returns skill inventory
---
## 9. Troubleshooting
### 9.1 Empty model list
- Ensure at least one of `GH_TOKEN` / `BYOK_API_KEY` is set
- Validate BYOK base URL and model names
### 9.2 Tools not executing
- Check `ENABLE_OPENWEBUI_TOOLS`, `ENABLE_MCP_SERVER`, `ENABLE_OPENAPI_SERVER`
- Confirm session/model has tool access
### 9.3 Publish succeeded but link unavailable
- Use the original URLs returned by tool output
- Verify storage/backend access policy
- For PDF, do not attempt iframe embedding
### 9.4 Status appears stuck
- Upgrade to latest plugin code
- Enable `DEBUG=True` temporarily
- Verify frontend version compatibility for Rich UI
---
## 10. Practical Prompt Templates
- “Analyze `sales.csv`, summarize by month, export `monthly_summary.xlsx`, and give me the download link.”
- “Generate an interactive HTML dashboard and publish it with Preview and Download links.”
- “Create a reusable skill named `finance-reporting` from this workflow.”
---
For deeper architecture and examples:
- [Deep Dive](github-copilot-sdk-deep-dive.md)
- [Advanced Tutorial](github-copilot-sdk-tutorial.md)
- [Main Plugin Doc](github-copilot-sdk.md)
Reference in New Issue View Git Blame Copy Permalink