open-webui/Fu-Jie_openwebui-extensions
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2fae50a39f8f6e3d8cc4c4ccec497091952e1a03
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

5.0 KiB
Raw Blame History

GitHub Copilot SDK Pipe Detailed Usage Guide

Author: Fu-Jie | Version: 0.9.0 | Project: 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:

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:

Reference in New Issue View Git Blame Copy Permalink