# 🚀 GitHub Copilot SDK Pipe v0.8.0：条件工具过滤 & 发布可靠性全面升级 🎛️

**GitHub Copilot SDK Pipe v0.8.0** — 一次重大的权限管控与稳定性升级。本次更新引入了四优先级工具权限体系，使工具访问可按每次对话精细配置；同时彻底修复了所有存储后端的文件发布问题，并确保 CLI 内置工具不再被意外屏蔽。

---

## 📦 快速安装

- **GitHub Copilot SDK (Pipe 插件)**: [安装 v0.8.0](https://openwebui.com/posts/ce96f7b4-12fc-4ac3-9a01-875713e69359)
- **GitHub Copilot SDK (Filter 插件)**: [安装 v0.1.3](https://openwebui.com/posts/403a62ee-a596-45e7-be65-fab9cc249dd6)

---

## 🚀 v0.8.0 更新内容

### 1. 条件工具过滤 (P1~P4) — 核心新特性

本次更新引入了**四优先级工具权限体系**，为您提供对每次对话中可用工具的精确控制。

| 优先级 | 作用域 | 机制描述 |
| :--- | :--- | :--- |
| **P1** | 全局 | Pipe 级 Valve 开关（`ENABLE_OPENWEBUI_TOOLS`、`ENABLE_OPENAPI_SERVER`、`ENABLE_MCP`） |
| **P2** | 服务器级 | 管理员 `config.enable` — 无需修改代码，直接从 OpenWebUI 管理面板禁用某个工具服务器 |
| **P3** | 用户级 | 用户专属 `UserValves` 覆盖设置 |
| **P4** | 对话级 | **Chat UI 工具选择** — 只有用户在输入框明确勾选的工具才会在本次对话中激活 |

**P4 工作原理**：OpenWebUI 会将用户当前选中的工具 ID 通过 `__metadata__` 中的 `tool_ids` 字段传入。插件读取该白名单并对 **OpenWebUI 工具**和 **MCP server** 同时进行过滤。

- **默认全开 (Default ON)**：如果您在 Chat UI 中**未勾选任何工具**（留空），只要 P1 全局 Valve 开启，插件就会默认启用**所有可用工具**。OpenWebUI 工具、OpenAPI Server 和 MCP Server 将默认全部挂载。
- **按需激活 (Whitelist Mode)**：一旦您在输入框主动勾选了至少一个工具（例如只选了“联网搜索”），则**只有您选中的工具会生效**，其他未选中的工具（包括 MCP 服务器）都将被过滤掉。

```
用户在 Chat UI 勾选 ✅ web-search，✅ code-runner
         ↓
chat_tool_ids = ["web-search", "server:code-runner"]
         ↓
过滤后工具列表 = 仅包含上述两个工具
         ↓
白名单外的 MCP server 将被完全跳过
```

**P2 管理员管控**：OpenWebUI 中每个工具服务器条目现在都有 `config.enable` 字段。从管理面板将其设为 `false` 即可全局禁用该服务器，无需修改任何 Valve 配置。

### 2. 文件发布全面修复 — 适配所有存储后端

Agent 发布文件时持续出现的 `{"detail":"[ERROR: Error getting file content]"}` 错误已被彻底解决。

| 根本原因 | 修复方案 |
| :--- | :--- |
| 回退路径使用 `shutil.copy2` + 手动写入 DB，导致 `file.path` 存储的是本地绝对路径，S3 等对象存储后端无法解析 | 回退路径改为直接调用 `Storage.upload_file()`，自动适配 local/S3/GCS/Azure |
| HTML 文件被 OpenWebUI `ALLOWED_FILE_EXTENSIONS` 内容类型检查拦截 | 上传 URL 始终追加 `?process=false`，绕过文件类型限制 |

当发布产物为 HTML 文件时，插件还会返回一个可直接访问的 HTML 链接，便于在聊天中即时打开/预览。

所有发布链接现统一执行严格格式：必须是以 `/api/v1/files/` 开头的相对路径。
`api/...`（缺少前导 `/`）或拼接域名的绝对 URL 都视为无效格式。

### 3. CLI 内置工具始终可用

`available_tools` 现在统一设为 `None`（不再根据已加载的工具 ID 列表过滤），这意味着 Copilot CLI 内置工具 —— 如 `bash`、`create_file`、`read_file`、`list_directory` —— **默认始终可用**。

此前，在未配置/未加载任何 server 工具时，CLI 可能收到 `available_tools=[]`，导致所有内置工具被静默屏蔽。

### 4. 发布工具始终注入

`publish_file_from_workspace` 工具的注入逻辑提前到 `ENABLE_OPENWEBUI_TOOLS` 守卫之前，因此即使通过 Valve 关闭所有 OpenWebUI 工具加载，该工具也**不再丢失**。

### 5. 代码解释器警告（未禁用）

内置的 `code_interpreter` 工具保持**启用**状态，但运行在远程的临时沙箱中。

为了避免混淆，系统提示词中会自动注入一段警告说明：
> "The `code_interpreter` tool executes code in a remote, ephemeral environment. It cannot access files in your local workspace or persist changes."

请仅将其用于纯计算或逻辑验证，勿用于文件操作。

### 6. Bug 修复汇总

- **文件发布后端不匹配**：修复了对象存储场景下因本地路径回退写入导致的 `Error getting file content`。
- **HTML 产物扩展名拦截**：修复了 OpenWebUI 扩展名处理导致 HTML 上传被拒的问题，统一强制 `?process=false`。
- **产物链接格式错误**：修复了链接偶发被生成成 `api/...` 或带域名 URL 的问题，现统一限制为 `/api/v1/files/...` 相对路径。
- **CLI 内置工具被静默屏蔽**：修复了在未配置/未加载任何 server 工具时（最终出现 `available_tools=[]`）导致内置工具不可用的问题，默认保持 `None`。
- **发布工具注入丢失**：修复了 `ENABLE_OPENWEBUI_TOOLS=False` 时 `publish_file_from_workspace` 被遗漏的问题。

### 7. 在 Pipe 文档中整合 Files Filter 指南

本次已将 `GitHub Copilot SDK Files Filter` 的核心说明整合进 Pipe 文档，用户可在单页完成完整配置：

- 阻止默认 RAG 在 Pipe 接手前抢先处理上传文件。
- 通过将上传文件移动到 `copilot_files` 保留原始二进制访问能力。
- 纳入 v0.1.3 重点：BYOK 模型 ID 前缀匹配修复 + 可选双通道调试日志。

---

## 🛠️ 核心能力

| 特性 | 描述 |
| :--- | :--- |
| **条件工具过滤 (P1~P4)** | 多优先级权限体系：全局 Valve → 管理员 config.enable → 用户 Valve → Chat UI 选择 |
| **通用工具协议** | 原生支持 **MCP**、**OpenAPI** 以及 **OpenWebUI 内置工具** |
| **原生工具 UI** | 完美适配 OpenWebUI 内置的工具调用渲染 |
| **物理隔离工作区** | 为每个会话提供严格的沙箱环境，保护数据隐私与安全 |
| **工作区产物工具** | Agent 可生成文件（Excel/CSV/HTML）并提供持久化下载链接 |
| **多存储后端发布** | 文件发布兼容本地磁盘、S3、GCS 及 Azure 后端 |
| **11 国语言本地化** | 自动检测并显示原生语言的状态消息 |

---

## 🔄 迁移说明

- **无破坏性变更**。P4 白名单过滤仅在用户主动在 Chat UI 选择了工具时生效；未做任何选择时，所有已启用的工具照常传递给 Copilot。
- 使用 S3/GCS/Azure 存储后端、曾遭遇文件下载失败的用户，无需任何额外配置即可正常发布文件。
- `ENABLE_TOOL_CACHE` Valve 已移除。工具服务器连接现在始终从数据库实时读取，避免多 Worker 环境下的状态过时。模型列表缓存请使用 `MODEL_CACHE_TTL`。

---

## 📥 导入对话模板

您可以下载并导入真实案例的 JSON 对话日志，直观查看模型如何调用工具：

- [📥 对话日志：GitHub 增长预测](https://fu-jie.github.io/awesome-openwebui/plugins/pipes/star-prediction-chat.json)
- [📥 对话日志：视频高质量 GIF 转换](https://fu-jie.github.io/awesome-openwebui/plugins/pipes/video-processing-chat.json)

*导入方式：前往 `设置 → 数据 → 导入对话`。*

---

## 🔗 相关资源

- **GitHub 仓库**: [openwebui-extensions](https://github.com/Fu-Jie/openwebui-extensions)
- **完整变更日志**: [README_CN.md](https://github.com/Fu-Jie/openwebui-extensions/blob/main/plugins/pipes/github-copilot-sdk/README_CN.md)
