跳转至

GitHub Copilot SDK Pipe 详细使用手册

Author: Fu-Jie | Version: 0.9.0 | Project: OpenWebUI Extensions

本手册面向“实际落地使用”，覆盖从安装、鉴权、模型选择到文件发布、Skills 管理、故障排查的完整流程。README 侧重社区展示，本页专注操作细节。

1. 适用场景

适合以下需求：

  • 在 OpenWebUI 内使用 GitHub Copilot 官方模型（含流式、工具调用、多轮会话）
  • 使用 BYOK（OpenAI/Anthropic）替代官方订阅
  • 让 Agent 生成并发布文件（Excel/CSV/HTML/PDF）
  • 使用 OpenWebUI Skills 与 manage_skills 做技能工程化管理

2. 部署前检查

2.1 OpenWebUI 与插件文件

  • 已运行 OpenWebUI（建议 v0.8.0+ 以获得 Rich UI 体验）
  • 已导入 Pipe 文件：plugins/pipes/github-copilot-sdk/github_copilot_sdk.py
  • 建议同时安装 Files Filter：
  • GitHub Copilot SDK Files Filter

2.2 必要鉴权（至少一种）

你必须配置下列其中一种凭据，否则模型列表为空：

  1. GH_TOKEN（访问 GitHub Copilot 官方模型）
  2. BYOK_API_KEY（访问 OpenAI/Anthropic 等自有供应商）

3. 安装与启用

  1. 进入 OpenWebUI：工作区 → 函数
  2. 新建函数并粘贴 github_copilot_sdk.py 全量内容
  3. 保存并启用
  4. 回到聊天页，在模型列表选择：
  5. github_copilot_official_sdk_pipe.*（官方）
  6. 或 BYOK 对应模型

4. 配置建议（先跑起来再精调）

4.1 管理员最小可用配置

  • GH_TOKEN 或 BYOK_API_KEY
  • ENABLE_OPENWEBUI_TOOLS = True
  • ENABLE_MCP_SERVER = True
  • ENABLE_OPENWEBUI_SKILLS = True
  • SHOW_THINKING = True

4.2 推荐增强项

  • COPILOTSDK_CONFIG_DIR=/app/backend/data/.copilot
  • 用于 SDK 配置/会话状态持久化（重启不丢）
  • OPENWEBUI_SKILLS_SHARED_DIR=/app/backend/data/cache/copilot-openwebui-skills
  • 统一 skills 缓存目录
  • DEBUG=True（排障阶段）

4.3 用户级覆盖（Profile）

普通用户可按需覆盖：GH_TOKEN、REASONING_EFFORT、BYOK_API_KEY、DISABLED_SKILLS 等。

5. 两种模型接入模式

5.1 官方模式（GitHub Copilot）

  • 配置 GH_TOKEN
  • 模型来自 Copilot 官方可用列表
  • 支持推理强度、工具调用、无限会话等插件能力

5.2 BYOK 模式（OpenAI/Anthropic）

  • 配置 BYOK_TYPE、BYOK_BASE_URL、BYOK_API_KEY
  • BYOK_MODELS 留空可自动拉取，或手动逗号分隔指定
  • 适合无官方订阅、或需要指定厂商模型时使用

6. 文件发布完整工作流（重点）

插件内置 publish_file_from_workspace，推荐遵循“写入 → 发布 → 返回链接”。

6.1 HTML 交付模式

  • artifacts（默认）
  • 返回 [Preview] + [Download]
  • 可输出 html_embed（iframe）用于完整交互展示
  • richui
  • 返回 [Preview] + [Download]
  • 由 Rich UI 自动渲染，不在消息中输出 iframe 代码块

6.2 PDF 交付规则（务必遵守）

  • 仅输出 Markdown 链接（可用时 [Preview] + [Download]）
  • **不要**输出 PDF iframe/embed HTML

6.3 图片与其他文件

  • 图片：优先直接展示 + 下载
  • 其他文件（xlsx/csv/docx 等）：返回下载链接为主

7. Skills 使用与管理

关键原则：manage_skills 是 工具（tool），不是 skill；所有 skills 统一安装在 一个目录：OPENWEBUI_SKILLS_SHARED_DIR/shared/。

7.1 OpenWebUI Skills 双向桥接

当 ENABLE_OPENWEBUI_SKILLS=True 时：

  • UI 中创建/编辑的 Skills 会同步到 SDK 目录
  • 目录内技能更新可回写到 OpenWebUI（按同步规则）

7.2 manage_skills 常用动作

  • list：列出现有技能
  • install：从 GitHub URL / .zip / .tar.gz 安装
  • create：从当前上下文创建技能
  • edit：更新技能内容与附加文件
  • show：查看 SKILL.md 与附属文件
  • delete：删除本地目录并清理关联记录

7.3 生产建议

  • 用 DISABLED_SKILLS 关闭不需要的技能，降低误触发
  • Skill 描述尽量明确（包含 Use when 语义），提高路由准确率

8. 首次验收清单

完成部署后，建议按顺序验证：

  1. 基础对话：确认模型能正常响应
  2. 工具调用：执行一条会触发工具的指令（如文件分析）
  3. 文件发布：生成一个 csv 并确认可下载
  4. HTML 发布：验证 artifacts/richui 至少一种模式
  5. PDF 发布：确认仅返回链接，无 iframe
  6. Skills：执行 manage_skills list，确认可见

9. 常见问题排查

9.1 模型列表为空

  • 检查 GH_TOKEN / BYOK_API_KEY 是否至少配置一个
  • 检查 BYOK BASE_URL 是否可达、模型名是否有效

9.2 工具似乎不可用

  • 检查 ENABLE_OPENWEBUI_TOOLS、ENABLE_MCP_SERVER、ENABLE_OPENAPI_SERVER
  • 检查当前模型/会话是否有工具权限

9.3 文件发布成功但无法打开

  • 检查返回链接是否来自工具原始输出
  • 检查对象存储/本地存储权限与可访问性
  • PDF 场景不要尝试 iframe 嵌入

9.4 状态栏“卡住”

  • 升级到最新插件代码
  • 打开 DEBUG=True 查看事件流
  • 确认前端版本与 Rich UI 能力匹配

10. 推荐操作模板（可直接对 AI 说）

  • “读取当前目录下的 sales.csv，按月份汇总并导出 monthly_summary.xlsx，最后给我下载链接。”
  • “生成一个交互式 HTML 仪表盘并发布，给我 Preview 和 Download 链接。”
  • “把本次流程固化成一个 skill，命名为 finance-reporting，并写入使用说明。”

如需架构细节，请结合阅读：