Fu-Jie_openwebui-extensions/plugins/pipes/github-copilot-sdk/v0.8.0_CN.md

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

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

---

📦 快速安装

• GitHub Copilot SDK (Pipe 插件): 安装 v0.8.0
• GitHub Copilot SDK (Filter 插件): 安装 v0.1.3

---

🚀 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 增长预测
• 📥 对话日志：视频高质量 GIF 转换

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

---

🔗 相关资源

• GitHub 仓库: openwebui-extensions
• 完整变更日志: README_CN.md