docs(workflow): optimize release format to English-only changelog
This commit is contained in:
fujie
102
docs/plugins/pipes/github-copilot-sdk-tutorial.md
Normal file
102
docs/plugins/pipes/github-copilot-sdk-tutorial.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# GitHub Copilot SDK Advanced Tutorial
|
||||
|
||||
**Author:** [Fu-Jie](https://github.com/Fu-Jie) | **Version:** 1.0.0 | **Project:** [Awesome OpenWebUI](https://github.com/Fu-Jie/awesome-openwebui)
|
||||
|
||||
This tutorial guides you through unleashing the full potential of the GitHub Copilot SDK plugin, specifically focusing on advanced file generation, BYOK customization, and complex task orchestration.
|
||||
|
||||
---
|
||||
|
||||
## 1. The 3-Step File Delivery Protocol
|
||||
|
||||
This is one of the most powerful features of this plugin. Agents can generate real physical files (e.g., `.xlsx`, `.pdf`, `.csv`) in their isolated workspace and publish them for you to download.
|
||||
|
||||
### Automated Execution Logic:
|
||||
1. **Write (Local)**: The Agent creates a file using code within its isolated directory (the current directory `.` during Python execution).
|
||||
2. **Publish**: The Agent automatically calls `publish_file_from_workspace(filename='report.xlsx')`.
|
||||
3. **Link**: The plugin handles S3 or local storage mapping, bypasses RAG interference, and returns a secure link like `/api/v1/files/.../content`.
|
||||
|
||||
> [!TIP]
|
||||
> **User Command Tip**: You can simply tell the Agent: "Analyze the previous data and export an Excel sheet for me." It will automatically trigger this entire sequence.
|
||||
|
||||
---
|
||||
|
||||
## 2. Advanced BYOK (Bring Your Own Key) Mode
|
||||
|
||||
If you don't have a GitHub Copilot subscription or want to use high-end models from OpenAI/Anthropic directly, you can use the BYOK mode.
|
||||
|
||||
### How to Configure:
|
||||
1. **Set Base URL**: e.g., `https://api.openai.com/v1`.
|
||||
2. **Set API Key**: Enter your key in your personal settings (Valves).
|
||||
3. **Real-time Model Refresh**: The plugin features a **Config-Aware Refresh** mechanism. When you modify the API Key or Base URL, simply refresh the model selector in the UI—the plugin will automatically fetch the latest available models from the backend.
|
||||
|
||||
---
|
||||
|
||||
## 3. Workspace Isolation & Debugging
|
||||
|
||||
Every chat session has a physically isolated folder, ensuring that files from different tasks do not interfere with each other.
|
||||
|
||||
### Physical Path Rules:
|
||||
- **In-Container Path**: `/app/backend/data/copilot_workspace/{user_id}/{chat_id}/`
|
||||
- **Agent's Perspective**: It sees the `.` directory as the path mentioned above.
|
||||
|
||||
### Debugging Pro Tips:
|
||||
1. **Enable DEBUG Valve**: Set `DEBUG` to `True` in the configuration.
|
||||
2. **Check the Console**: Open browser developer tools (F12) -> Console.
|
||||
3. **Capture Paths**: You will see logs like `📂 Workspace Resolved: /.../`, which helps you confirm exactly where the Agent is writing its files.
|
||||
|
||||
---
|
||||
|
||||
## 4. Deep Analysis Bypassing RAG
|
||||
|
||||
Traditional file uploads in OpenWebUI trigger vectorization (RAG), which might not be precise enough for large-scale data analysis.
|
||||
|
||||
**Advantages of this Plugin**:
|
||||
- When used with the [Files Filter](https://openwebui.com/posts/403a62ee-a596-45e7-be65-fab9cc249dd6) plugin, the Agent can **directly read every byte** of the raw file.
|
||||
- It can analyze every row of a CSV as if it were running a script locally, preventing information loss caused by retrieval-based slicing.
|
||||
|
||||
---
|
||||
|
||||
## 5. Common Interaction Examples
|
||||
|
||||
- **Data Conversion**: "Convert this JSON content into a beautifully formatted Word document and provide a download link."
|
||||
- **Code Review**: "Read all `.py` files in the workspace, find potential bugs, and publish the suggestions as a Markdown report."
|
||||
- **Chart Generation**: "Generate an Excel report based on the financial data and use Python to draw a trend chart for me."
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Real-world Example: Automated Financial Analysis
|
||||
|
||||
### Scenario
|
||||
A user uploads a raw sales log named `sales_data.csv` and asks the AI to generate a summarized Excel report.
|
||||
|
||||
### 1. User Command
|
||||
> "Analyze `sales_data.csv` in the current directory, calculate total revenue per product category, and export an Excel file named `category_summary.xlsx` for me."
|
||||
|
||||
### 2. Agent Execution Flow
|
||||
The Agent performs the following steps autonomously:
|
||||
|
||||
* **Step 1: Write and Run Python Code**
|
||||
```python
|
||||
import pandas as pd
|
||||
# Direct file access in the isolated workspace (Bypassing RAG for 100% accuracy)
|
||||
df = pd.read_csv('sales_data.csv')
|
||||
summary = df.groupby('Category')['Revenue'].sum().reset_index()
|
||||
# Save the result locally
|
||||
summary.to_excel('category_summary.xlsx', index=False)
|
||||
```
|
||||
* **Step 2: Call the Publishing Tool**
|
||||
The Agent calls: `publish_file_from_workspace(filename="category_summary.xlsx")`
|
||||
* **Step 3: Deliver the Link**
|
||||
The tool returns a `download_url`, which the Agent presents to the user.
|
||||
|
||||
### 3. Final Result
|
||||
The Agent responds:
|
||||
> "Analysis complete! I have summarized the revenue by category. You can download your report here:
|
||||
>
|
||||
> [📊 Download: Category_Summary.xlsx](/api/v1/files/uuid-hash/content)"
|
||||
|
||||
---
|
||||
|
||||
## ⭐ Continuous Improvement
|
||||
|
||||
If you encounter any issues or have suggestions for new features, feel free to submit an Issue or participate in discussions on [Awesome OpenWebUI](https://github.com/Fu-Jie/awesome-openwebui).
|
||||
102
docs/plugins/pipes/github-copilot-sdk-tutorial.zh.md
Normal file
102
docs/plugins/pipes/github-copilot-sdk-tutorial.zh.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# GitHub Copilot SDK 插件进阶实战教程
|
||||
|
||||
**作者:** [Fu-Jie](https://github.com/Fu-Jie) | **版本:** 1.0.0 | **项目:** [Awesome OpenWebUI](https://github.com/Fu-Jie/awesome-openwebui)
|
||||
|
||||
本教程旨在指导您如何深度发挥 GitHub Copilot SDK 插件的全部潜力，特别是在自动化文件生成、BYOK 模式自定义以及复杂任务调度方面的进阶用法。
|
||||
|
||||
---
|
||||
|
||||
## 1. 核心协议：文件交付三步法 (File Delivery Protocol)
|
||||
|
||||
这是本插件最强大的功能之一。Agent 不再只是“说话”，它可以在其隔离的工作区内生成真正的物理文件（如 `.xlsx`, `.pdf`, `.csv`），并将其发布给您下载。
|
||||
|
||||
### 自动化执行逻辑：
|
||||
1. **本地写入 (Write)**：Agent 在其隔离目录（即 Python 执行的当前目录 `.`）下通过代码生成文件。
|
||||
2. **显式发布 (Publish)**：Agent 自动调用 `publish_file_from_workspace(filename='report.xlsx')`。
|
||||
3. **获取链接 (Link)**：插件会自动处理 S3 或本地存储映射，绕过 RAG 干扰，并返回一个类似 `/api/v1/files/.../content` 的安全链接。
|
||||
|
||||
> [!TIP]
|
||||
> **用户指令技巧**：您可以直接对 Agent 说：“分析刚才的表格并导出一份 Excel 给我”。它会自动触发这一连串动作。
|
||||
|
||||
---
|
||||
|
||||
## 2. BYOK (自带 Key) 模式进阶
|
||||
|
||||
如果您没有 GitHub Copilot 订阅，或者希望使用自己购买的 OpenAI/Anthropic 高阶模型，可以使用 BYOK 模式。
|
||||
|
||||
### 如何配置：
|
||||
1. **设置 Base URL**：如 `https://api.openai.com/v1`。
|
||||
2. **设置 API Key**：在个人设置中填入您的密钥。
|
||||
3. **模型实时刷新**：插件具备**配置感知刷新**机制。当您在 Valve 中修改了 API Key 或 Base URL 后，无需重启，只需刷新模型选择器，插件会自动向后端拉取最新的可用模型列表。
|
||||
|
||||
---
|
||||
|
||||
## 3. 工作区隔离与调试 (Workspace & Debugging)
|
||||
|
||||
每个聊天会话都有一个物理上隔离的文件夹，确保不同任务的文件互不干扰。
|
||||
|
||||
### 物理路径规则：
|
||||
- **容器内路径**：`/app/backend/data/copilot_workspace/{user_id}/{chat_id}/`
|
||||
- **Agent 的视角**：它看到的 `.` 目录即是上述路径。
|
||||
|
||||
### 调试秘籍：
|
||||
1. **开启 DEBUG Valve**：在配置中将 `DEBUG` 设为 `True`。
|
||||
2. **查看控制台**：打开浏览器开发者工具 (F12) -> Console。
|
||||
3. **捕获路径**：您会看到类似 `📂 Workspace Resolved: /.../` 的日志，这能帮您确认 Agent 到底把文件写到了哪里。
|
||||
|
||||
---
|
||||
|
||||
## 4. 绕过 RAG 的深度分析
|
||||
|
||||
传统的 OpenWebUI 文件上传会触发向量化（RAG），这对于大批量数据分析往往不够精确。
|
||||
|
||||
**本插件的优势**：
|
||||
- 配合 [Files Filter](https://openwebui.com/posts/403a62ee-a596-45e7-be65-fab9cc249dd6) 插件使用时，Agent 可以**直接读取**原始文件的每一个字节。
|
||||
- 它能像在本地运行脚本一样分析 CSV 的每一行，而不会因为切片检索（Retrieval）导致信息丢失。
|
||||
|
||||
---
|
||||
|
||||
## 5. 常见交互指令示例
|
||||
|
||||
- **数据转换**：“把这个 JSON 内容转换成格式精美的 Word 文档并提供下载链接。”
|
||||
- **代码审查**：“读取工作区内的所有 `.py` 文件，找出潜在的 Bug，并把修改建议发布为 Markdown 报告。”
|
||||
- **图表生成**：“根据刚才的财务数据生成一份 Excel 报表，并用 Python 画一个趋势图给我。”
|
||||
|
||||
---
|
||||
|
||||
## 🚀 实战示例：全自动财务分析报告
|
||||
|
||||
### 场景描述
|
||||
用户上传了一个名为 `sales_data.csv` 的原始销售清单，要求 AI 进行汇总统计，并生成一份带样式的 Excel 报表。
|
||||
|
||||
### 1. 用户的指令
|
||||
> “请分析当前目录下的 `sales_data.csv`，按产品类别统计总销售额，并导出一份名为 `category_summary.xlsx` 的 Excel 给我就好。”
|
||||
|
||||
### 2. Agent 的自动化执行过程
|
||||
Agent 会在后台连续执行以下动作：
|
||||
|
||||
* **步骤 1: 编写并运行 Python 脚本**
|
||||
```python
|
||||
import pandas as pd
|
||||
# 直接在隔离工作区读取原始文件（绕过 RAG，保证数据 100% 准确）
|
||||
df = pd.read_csv('sales_data.csv')
|
||||
summary = df.groupby('Category')['Revenue'].sum().reset_index()
|
||||
# 保存结果到当前目录
|
||||
summary.to_excel('category_summary.xlsx', index=False)
|
||||
```
|
||||
* **步骤 2: 调用发布工具**
|
||||
Agent 自动执行工具调用：`publish_file_from_workspace(filename="category_summary.xlsx")`
|
||||
* **步骤 3: 交付链接**
|
||||
工具返回 `download_url`，Agent 最终回复用户。
|
||||
|
||||
### 3. 最终交付效果
|
||||
Agent 会向用户展示：
|
||||
> “分析完成！我已经为您统计了产品类别的销售额。您可以点击下方链接下载报表：
|
||||
>
|
||||
> [📊 点击下载：分类销售统计报表.xlsx](/api/v1/files/uuid-hash/content)”
|
||||
|
||||
---
|
||||
|
||||
## ⭐ 持续改进
|
||||
|
||||
如果您在使用过程中发现任何问题，或有新的功能建议，欢迎到 [Awesome OpenWebUI](https://github.com/Fu-Jie/awesome-openwebui) 提交 Issue 或参与讨论。
|
||||
@@ -32,7 +32,8 @@ This is an advanced Pipe function for [OpenWebUI](https://github.com/open-webui/
|
||||
- **🧠 Deep Database Integration**: Real-time persistence of TOD·O lists for long-running workflows.
|
||||
- **🌊 Advanced Streaming**: Full support for thinking process/Chain of Thought visualization.
|
||||
- **🖼️ Intelligent Multimodal**: Vision capabilities and raw file analysis support.
|
||||
- **⚡ Full-Lifecycle File Agent**: Supports receiving uploaded files for raw bypass analysis and publishing generated results (e.g., analyzed Excel/reports) as downloadable links—a complete closed-loop agentic workflow.
|
||||
- **⚡ Full-Lifecycle File Agent**: Supports receiving uploaded files for raw bypass analysis and publishing results (Excel/reports) as downloadable links.
|
||||
- **🖼️ Interactive Artifacts**: Automatically renders HTML/JS apps generated by the agent directly in the chat interface.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -32,7 +32,8 @@
|
||||
- **🧠 深度数据库集成**: 实时持久化 TOD·O 列表到 UI 进度条。
|
||||
- **🌊 深度推理展示**: 完整支持模型思考过程 (Thinking Process) 的流式渲染。
|
||||
- **🖼️ 智能多模态**: 完整支持图像识别与附件上传分析。
|
||||
- **⚡ 全生命周期文件 Agent**: 支持接收上传文件进行绕过 RAG 的深度分析，并将处理结果（如分析后的 Excel/报告）发布为可下载链接，实现完整的闭环 Agent 工作流。
|
||||
- **⚡ 全生命周期文件 Agent**: 支持接收上传文件进行绕过 RAG 的深度分析，并将处理结果（如 Excel/报告）发布为下载链接实现闭环。
|
||||
- **🖼️ 交互式伪影 (Artifacts)**: 自动渲染 Agent 生成的 HTML/JS 应用程序，直接在聊天界面交互。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ Pipes allow you to:
|
||||
|
||||
## Available Pipe Plugins
|
||||
|
||||
- [GitHub Copilot SDK](github-copilot-sdk.md) (v0.6.2) - Official GitHub Copilot SDK integration. Features **Workspace Isolation**, **Database Persistence**, **Zero-config OpenWebUI Tool Bridge**, **BYOK** support, and **dynamic MCP discovery**. Supports streaming, multimodal, and infinite sessions.
|
||||
- [GitHub Copilot SDK](github-copilot-sdk.md) (v0.6.2) - Official GitHub Copilot SDK integration. Features **Workspace Isolation**, **Database Persistence**, **Zero-config OpenWebUI Tool Bridge**, **BYOK** support, and **dynamic MCP discovery**. Supports streaming, multimodal, and infinite sessions. [View Deep Dive](github-copilot-sdk-deep-dive.md) | [**View Advanced Tutorial**](github-copilot-sdk-tutorial.md).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ Pipes 可以用于：
|
||||
|
||||
## 可用的 Pipe 插件
|
||||
|
||||
- [GitHub Copilot SDK](github-copilot-sdk.zh.md) (v0.6.2) - GitHub Copilot SDK 官方集成。具备**工作区安全隔离**、**数据库持久化**、**零配置工具桥接**与**BYOK (自带 Key) 支持**。支持流式输出、打字机思考过程及无限会话。[查看深度架构解析](github-copilot-sdk-deep-dive.zh.md)。
|
||||
- [GitHub Copilot SDK](github-copilot-sdk.zh.md) (v0.6.2) - GitHub Copilot SDK 官方集成。具备**工作区安全隔离**、**数据库持久化**、**零配置工具桥接**与**BYOK (自带 Key) 支持**。支持流式输出、打字机思考过程及无限会话。[查看深度架构解析](github-copilot-sdk-deep-dive.zh.md) | [**查看进阶实战教程**](github-copilot-sdk-tutorial.zh.md)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user