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
This commit is contained in:
Fu-Jie
GitHub
192
docs/plugins/pipes/github-copilot-sdk-usage-guide.zh.md
Normal file
192
docs/plugins/pipes/github-copilot-sdk-usage-guide.zh.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# GitHub Copilot SDK Pipe 详细使用手册
|
||||
|
||||
**Author:** [Fu-Jie](https://github.com/Fu-Jie/openwebui-extensions) | **Version:** 0.9.0 | **Project:** [OpenWebUI Extensions](https://github.com/Fu-Jie/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](https://openwebui.com/posts/403a62ee-a596-45e7-be65-fab9cc249dd6)
|
||||
|
||||
### 2.2 必要鉴权（至少一种）
|
||||
|
||||
你必须配置下列其中一种凭据，否则模型列表为空：
|
||||
|
||||
1. `GH_TOKEN`（访问 GitHub Copilot 官方模型）
|
||||
2. `BYOK_API_KEY`（访问 OpenAI/Anthropic 等自有供应商）
|
||||
|
||||
---
|
||||
|
||||
## 3. 安装与启用
|
||||
|
||||
1. 进入 OpenWebUI：**工作区 → 函数**
|
||||
2. 新建函数并粘贴 `github_copilot_sdk.py` 全量内容
|
||||
3. 保存并启用
|
||||
4. 回到聊天页，在模型列表选择：
|
||||
- `github_copilot_official_sdk_pipe.*`（官方）
|
||||
- 或 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`，并写入使用说明。”
|
||||
|
||||
---
|
||||
|
||||
如需架构细节，请结合阅读：
|
||||
|
||||
- [深度解析](github-copilot-sdk-deep-dive.zh.md)
|
||||
- [进阶实战教程](github-copilot-sdk-tutorial.zh.md)
|
||||
- [插件主文档](github-copilot-sdk.zh.md)
|
||||
Reference in New Issue
Block a user