chore: update default port from 3003 to 3000 and improve installation docs

- Change all default port references from 3003 to 3000 across scripts and documentation - Add quick installation guide for batch plugin installation to main README (EN & CN) - Simplify installation options by removing manual installation instructions - Update deployment guides and examples to reflect new default port
2026-03-09 21:42:17 +08:00
parent 62e78ace5c
commit ae0fa1d39a
16 changed files with 1712 additions and 691 deletions
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -1,70 +1,84 @@
-# 🚀 部署脚本使用指南 (Deployment Scripts Guide)
+# 🚀 Deployment Scripts Guide

-## 📁 新增部署工具
+## 📁 Deployment Tools

-为了支持快速本地部署 async_context_compression 和其他 Filter 插件，我们添加了以下文件：
+To support quick local deployment of async_context_compression and other Filter plugins, we've added the following files:

-### 具体文件列表
+### File Inventory

 ```
 scripts/
-├── deploy_filter.py                        ✨ 通用 Filter 部署工具
-├── deploy_async_context_compression.py     ✨ Async Context Compression 快捷部署
-├── deploy_pipe.py                          (已有) Pipe 部署工具
-├── DEPLOYMENT_GUIDE.md                     ✨ 完整部署指南
-├── DEPLOYMENT_SUMMARY.md                   ✨ 部署功能总结
-├── QUICK_START.md                          ✨ 快速参考卡片
-├── .env                                    (需要创建) API 密钥配置
-└── ...其他现有脚本
+├── install_all_plugins.py                  ✨ Batch install Action/Filter/Pipe/Tool plugins
+├── deploy_filter.py                        ✨ Generic Filter deployment tool
+├── deploy_tool.py                          ✨ Tool plugin deployment tool
+├── deploy_async_context_compression.py     ✨ Async Context Compression quick deploy
+├── deploy_pipe.py                          (existing) Pipe deployment tool
+├── DEPLOYMENT_GUIDE.md                     ✨ Complete deployment guide
+├── DEPLOYMENT_SUMMARY.md                   ✨ Deploy feature summary
+├── QUICK_START.md                          ✨ Quick reference card
+├── .env                                    (create as needed) API key configuration
+└── ...other existing scripts
 ```

-## ⚡ 快速开始 (30 秒)
+## ⚡ Quick Start (30 seconds)

-### 步骤 1: 准备 API 密钥
+### Step 1: Prepare Your API Key

 ```bash
 cd scripts

-# 获取你的 OpenWebUI API 密钥：
-# 1. 打开 OpenWebUI → 用户菜单 → Settings
-# 2. 找到 "API Keys" 部分
-# 3. 复制你的密钥（以 sk- 开头）
+# Get your OpenWebUI API key:
+# 1. Open OpenWebUI → User menu → Settings
+# 2. Find the "API Keys" section
+# 3. Copy your key (starts with sk-)

-# 创建 .env 文件
-echo "api_key=sk-你的密钥" > .env
+# Create .env file
+cat > .env <<'EOF'
+api_key=sk-your-key-here
+url=http://localhost:3000
+EOF
 ```

-### 步骤 2: 部署异步上下文压缩
+### Step 2a: Install All Plugins (Recommended)

 ```bash
-# 最简单的方式 - 专用脚本
+python install_all_plugins.py
+```
+
+### Step 2b: Or Deploy Individual Plugins
+
+```bash
+# Easiest way - dedicated script
 python deploy_async_context_compression.py

-# 或使用通用脚本
+# Or use generic script
 python deploy_filter.py

-# 或指定插件名称
+# Or specify plugin name
 python deploy_filter.py async-context-compression
+
+# Or deploy a Tool
+python deploy_tool.py
 ```

-## 📋 部署工具详解
+## 📋 Deployment Tools Detailed

-### 1️⃣ `deploy_async_context_compression.py` — 专用部署脚本
+### 1️⃣ `deploy_async_context_compression.py` — Dedicated Deployment Script

-**最简单的部署方式！**
+**The simplest way to deploy!**

 ```bash
 cd scripts
 python deploy_async_context_compression.py
 ```

-**特点**:
- ✅ 专为 async_context_compression 优化
- ✅ 清晰的部署步骤和确认
- ✅ 友好的错误提示
- ✅ 部署成功后显示后续步骤
+**Features**:
+- ✅ Optimized specifically for async_context_compression
+- ✅ Clear deployment steps and confirmation
+- ✅ Friendly error messages
+- ✅ Shows next steps after successful deployment

-**输出样例**:
+**Sample Output**:
 ```
 ======================================================================
 🚀 Deploying Async Context Compression Filter Plugin
@@ -79,269 +93,314 @@ python deploy_async_context_compression.py
 ======================================================================

 Next steps:
-  1. Open OpenWebUI in your browser: http://localhost:3003
+  1. Open OpenWebUI in your browser: http://localhost:3000
  2. Go to Settings → Filters
  3. Enable 'Async Context Compression'
  4. Configure Valves as needed
  5. Start using the filter in conversations
 ```

-### 2️⃣ `deploy_filter.py` — 通用 Filter 部署工具
+### 2️⃣ `deploy_filter.py` — Generic Filter Deployment Tool

-**支持所有 Filter 插件！**
+**Supports all Filter plugins!**

 ```bash
-# 部署默认的 async_context_compression
+# Deploy default async_context_compression
 python deploy_filter.py

-# 部署其他 Filter
+# Deploy other Filters
 python deploy_filter.py folder-memory
 python deploy_filter.py context_enhancement_filter

-# 列出所有可用 Filter
+# List all available Filters
 python deploy_filter.py --list
 ```

-**特点**:
- ✅ 通用的 Filter 部署工具
- ✅ 支持多个插件
- ✅ 自动元数据提取
- ✅ 智能更新/创建逻辑
- ✅ 完整的错误诊断
+**Features**:
+- ✅ Generic Filter deployment tool
+- ✅ Supports multiple plugins
+- ✅ Auto metadata extraction
+- ✅ Smart update/create logic
+- ✅ Complete error diagnostics

-### 3️⃣ `deploy_pipe.py` — Pipe 部署工具
+### 3️⃣ `deploy_pipe.py` — Pipe Deployment Tool

 ```bash
 python deploy_pipe.py
 ```

-用于部署 Pipe 类型的插件（如 GitHub Copilot SDK）。
+Used to deploy Pipe-type plugins (like GitHub Copilot SDK).

-## 🔧 工作原理
-
-```
-你的代码变更
-    ↓
-运行部署脚本
-    ↓
-脚本读取对应插件文件
-    ↓
-从代码自动提取元数据 (title, version, author, etc.)
-    ↓
-构建 API 请求
-    ↓
-发送到本地 OpenWebUI
-    ↓
-OpenWebUI 更新或创建插件
-    ↓
-立即生效！（无需重启）
-```
-
-## 📊 可部署的 Filter 列表
-
-使用 `python deploy_filter.py --list` 查看所有可用 Filter：
-
-| Filter 名称 | Python 文件 | 描述 |
-|-----------|-----------|------|
-| **async-context-compression** | async_context_compression.py | 异步上下文压缩 |
-| chat-session-mapping-filter | chat_session_mapping_filter.py | 聊天会话映射 |
-| context_enhancement_filter | context_enhancement_filter.py | 上下文增强 |
-| folder-memory | folder_memory.py | 文件夹记忆 |
-| github_copilot_sdk_files_filter | github_copilot_sdk_files_filter.py | Copilot SDK Files |
-| markdown_normalizer | markdown_normalizer.py | Markdown 规范化 |
-| web_gemini_multimodel_filter | web_gemini_multimodel_filter.py | Gemini 多模态 |
-
-## 🎯 常见使用场景
-
-### 场景 1: 开发新功能后部署
+### 3️⃣+ `deploy_tool.py` — Tool Deployment Tool

 ```bash
-# 1. 修改代码
+# Deploy default Tool
+python deploy_tool.py
+
+# Or specify a specific Tool
+python deploy_tool.py openwebui-skills-manager
+```
+
+**Features**:
+- ✅ Supports Tools plugin deployment
+- ✅ Auto-detects `Tools` class definition
+- ✅ Smart update/create logic
+- ✅ Complete error diagnostics
+
+**Use Case**:
+Deploy or reinstall a specific Tool individually, or deploy only Tools without running full batch installation. The script now calls OpenWebUI's native `/api/v1/tools/*` endpoints.
+
+### 4️⃣ `install_all_plugins.py` — Batch Installation Script
+
+One-command installation of all repository plugins that meet these criteria:
+
+- Located in `plugins/actions`, `plugins/filters`, `plugins/pipes`, `plugins/tools`
+- Plugin header contains `openwebui_id`
+- Filename is not in Chinese characters
+- Filename does not end with `_cn.py`
+
+```bash
+# Check which plugins will be installed
+python install_all_plugins.py --list
+
+# Dry-run without calling API
+python install_all_plugins.py --dry-run
+
+# Actually install all supported types (including Action/Filter/Pipe/Tool)
+python install_all_plugins.py
+
+# Install only specific types
+python install_all_plugins.py --types pipe action
+```
+
+The script prioritizes updating existing plugins and automatically creates new ones.
+
+**Tool Integration**: Tool-type plugins now automatically use OpenWebUI's native `/api/v1/tools/create` and `/api/v1/tools/id/{id}/update` endpoints, no longer reusing the `functions` endpoint.
+
+## 🔧 How It Works
+
+```
+Your code changes
+    ↓
+Run deployment script
+    ↓
+Script reads the corresponding plugin file
+    ↓
+Auto-extracts metadata from code (title, version, author, etc.)
+    ↓
+Builds API request
+    ↓
+Sends to local OpenWebUI
+    ↓
+OpenWebUI updates or creates plugin
+    ↓
+Takes effect immediately! (no restart needed)
+```
+
+## 📊 Available Filter List
+
+Use `python deploy_filter.py --list` to see all available Filters:
+
+| Filter Name | Python File | Description |
+|-----------|-----------|------|
+| **async-context-compression** | async_context_compression.py | Async context compression |
+| chat-session-mapping-filter | chat_session_mapping_filter.py | Chat session mapping |
+| context_enhancement_filter | context_enhancement_filter.py | Context enhancement |
+| folder-memory | folder_memory.py | Folder memory |
+| github_copilot_sdk_files_filter | github_copilot_sdk_files_filter.py | Copilot SDK Files |
+| markdown_normalizer | markdown_normalizer.py | Markdown normalization |
+| web_gemini_multimodel_filter | web_gemini_multimodel_filter.py | Gemini multimodal |
+
+## 🎯 Common Use Cases
+
+### Scenario 1: Deploy After Feature Development
+
+```bash
+# 1. Modify code
 vim ../plugins/filters/async-context-compression/async_context_compression.py

-# 2. 更新版本号（可选）
+# 2. Update version number (optional)
 # version: 1.3.0 → 1.3.1

-# 3. 部署
+# 3. Deploy
 python deploy_async_context_compression.py

-# 4. 在 OpenWebUI 中测试
-# → 无需重启，立即生效！
+# 4. Test in OpenWebUI
+# → No restart needed, takes effect immediately!

-# 5. 继续开发，重复上述步骤
+# 5. Continue development and repeat
 ```

-### 场景 2: 修复 Bug 并快速验证
+### Scenario 2: Fix Bug and Verify Quickly

 ```bash
-# 1. 定位并修复 Bug
+# 1. Find and fix bug
 vim ../plugins/filters/async-context-compression/async_context_compression.py

-# 2. 快速部署验证
+# 2. Quick deploy to verify
 python deploy_async_context_compression.py

-# 3. 在 OpenWebUI 测试 Bug 修复
-# 一键部署，秒级反馈！
+# 3. Test bug fix in OpenWebUI
+# One-command deploy, instant feedback!
 ```

-### 场景 3: 部署多个 Filter
+### Scenario 3: Deploy Multiple Filters

 ```bash
-# 部署所有需要更新的 Filter
+# Deploy all Filters that need updates
 python deploy_filter.py async-context-compression
 python deploy_filter.py folder-memory
 python deploy_filter.py context_enhancement_filter
 ```

-## 🔐 安全提示
+## 🔐 Security Tips

-### 管理 API 密钥
+### Manage API Keys

 ```bash
-# 1. 创建 .env（只在本地）
+# 1. Create .env (local only)
 echo "api_key=sk-your-key" > .env

-# 2. 添加到 .gitignore（防止提交）
+# 2. Add to .gitignore (prevent commit)
 echo "scripts/.env" >> ../.gitignore

-# 3. 验证不会被提交
-git status  # 应该看不到 .env
+# 3. Verify it won't be committed
+git status  # should not show .env

-# 4. 定期轮换密钥
-# → 在 OpenWebUI Settings 中生成新密钥
-# → 更新 .env 文件
+# 4. Rotate keys regularly
+# → Generate new key in OpenWebUI Settings
+# → Update .env file
 ```

-### ✅ 安全检查清单
+### ✅ Security Checklist

- [ ] `.env` 文件在 `.gitignore` 中
- [ ] 从不在代码中硬编码 API 密钥
- [ ] 定期轮换 API 密钥
- [ ] 仅在可信网络中使用
- [ ] 生产环境使用 CI/CD 秘密管理
+- [ ] `.env` file is in `.gitignore`
+- [ ] Never hardcode API keys in code
+- [ ] Rotate API keys periodically
+- [ ] Use only on trusted networks
+- [ ] Use CI/CD secret management in production

-## ❌ 故障排除
+## ❌ Troubleshooting

-### 问题 1: "Connection error"
+### Issue 1: "Connection error"

 ```
-❌ Connection error: Could not reach OpenWebUI at localhost:3003
+❌ Connection error: Could not reach OpenWebUI at localhost:3000
   Make sure OpenWebUI is running and accessible.
 ```

-**解决方案**:
+**Solution**:
 ```bash
-# 1. 检查 OpenWebUI 是否运行
-curl http://localhost:3003
+# 1. Check if OpenWebUI is running
+curl http://localhost:3000

-# 2. 如果端口不同，编辑脚本中的 URL
-# 默认: http://localhost:3003
-# 修改位置: deploy_filter.py 中的 "localhost:3003"
+# 2. If port is different, edit URL in script
+# Default: http://localhost:3000
+# Location: "localhost:3000" in deploy_filter.py

-# 3. 检查防火墙设置
+# 3. Check firewall settings
 ```

-### 问题 2: ".env file not found"
+### Issue 2: ".env file not found"

 ```
 ❌ [ERROR] .env file not found at .env
   Please create it with: api_key=sk-xxxxxxxxxxxx
 ```

-**解决方案**:
+**Solution**:
 ```bash
 echo "api_key=sk-your-api-key" > .env
-cat .env  # 验证文件已创建
+cat .env  # verify file created
 ```

-### 问题 3: "Filter not found"
+### Issue 3: "Filter not found"

 ```
 ❌ [ERROR] Filter 'xxx' not found in .../plugins/filters
 ```

-**解决方案**:
+**Solution**:
 ```bash
-# 列出所有可用 Filter
+# List all available Filters
 python deploy_filter.py --list

-# 使用正确的名称重试
+# Retry with correct name
 python deploy_filter.py async-context-compression
 ```

-### 问题 4: "Status 401" (Unauthorized)
+### Issue 4: "Status 401" (Unauthorized)

 ```
 ❌ Failed to update or create. Status: 401
   Error: {"error": "Unauthorized"}
 ```

-**解决方案**:
+**Solution**:
 ```bash
-# 1. 验证 API 密钥是否正确
+# 1. Verify API key is correct
 grep "api_key=" .env

-# 2. 在 OpenWebUI 中检查密钥是否仍然有效
-# Settings → API Keys → 检查
+# 2. Check if key is still valid in OpenWebUI
+# Settings → API Keys → Check

-# 3. 生成新密钥并更新 .env
+# 3. Generate new key and update .env
 echo "api_key=sk-new-key" > .env
 ```

-## 📖 文档导航
+## 📖 Documentation Navigation

-| 文档 | 描述 |
+| Document | Description |
 |------|------|
-| **README.md** (本文件) | 快速参考和常见问题 |
-| [QUICK_START.md](QUICK_START.md) | 一页速查表 |
-| [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) | 完整详细指南 |
-| [DEPLOYMENT_SUMMARY.md](DEPLOYMENT_SUMMARY.md) | 技术架构说明 |
+| **README.md** (this file) | Quick reference and FAQs |
+| [QUICK_START.md](QUICK_START.md) | One-page cheat sheet |
+| [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) | Complete detailed guide |
+| [DEPLOYMENT_SUMMARY.md](DEPLOYMENT_SUMMARY.md) | Technical architecture |

-## 🧪 验证部署成功
+## 🧪 Verify Deployment Success

-### 方式 1: 检查脚本输出
+### Method 1: Check Script Output

 ```bash
 python deploy_async_context_compression.py

-# 成功标志:
+# Success indicator:
 ✅ Successfully updated 'Async Context Compression' filter!
 ```

-### 方式 2: 在 OpenWebUI 中验证
+### Method 2: Verify in OpenWebUI

-1. 打开 OpenWebUI: http://localhost:3003
-2. 进入 Settings → Filters
-3. 查看 "Async Context Compression" 是否列出
-4. 查看版本号是否正确（应该是最新的）
+1. Open OpenWebUI: http://localhost:3000
+2. Go to Settings → Filters
+3. Check if 'Async Context Compression' is listed
+4. Verify version number is correct (should be latest)

-### 方式 3: 测试插件功能
+### Method 3: Test Plugin Functionality

-1. 打开一个新对话
-2. 启用 "Async Context Compression" Filter
-3. 进行多轮对话，验证压缩和总结功能正常
+1. Open a new conversation
+2. Enable 'Async Context Compression' Filter
+3. Have multiple-turn conversation and verify compression/summarization works
+## 💡 Advanced Usage

-## 💡 高级用法
-
-### 自动化部署测试
+### Automated Deploy & Test

 ```bash
 #!/bin/bash
 # deploy_and_test.sh

-echo "部署插件..."
+echo "Deploying plugin..."
 python scripts/deploy_async_context_compression.py

 if [ $? -eq 0 ]; then
-    echo "✅ 部署成功，运行测试..."
+    echo "✅ Deploy successful, running tests..."
    python -m pytest tests/plugins/filters/async-context-compression/ -v
 else
-    echo "❌ 部署失败"
+    echo "❌ Deploy failed"
    exit 1
 fi
 ```

-### CI/CD 集成
+### CI/CD Integration

 ```yaml
 # .github/workflows/deploy.yml
@@ -362,55 +421,56 @@ jobs:
          api_key: ${{ secrets.OPENWEBUI_API_KEY }}
 ```

-## 📞 获取帮助
+## 📞 Getting Help

-### 检查脚本状态
+### Check Script Status

 ```bash
-# 列出所有可用脚本
+# List all available scripts
 ls -la scripts/*.py

-# 检查部署脚本是否存在
+# Check if deployment scripts exist
 ls -la scripts/deploy_*.py
 ```

-### 查看脚本版本
+### View Script Help

 ```bash
-# 查看脚本帮助
-python scripts/deploy_filter.py --help  # 如果支持的话
+# View help (if supported)
+python scripts/deploy_filter.py --help  # if supported
 python scripts/deploy_async_context_compression.py --help
 ```

-### 调试模式
+### Debug Mode

 ```bash
-# 保存输出到日志文件
+# Save output to log file
 python scripts/deploy_async_context_compression.py | tee deploy.log

-# 检查日志
+# Check log
 cat deploy.log
 ```

 ---

-## 📝 文件清单
+## 📝 File Checklist

-新增的部署相关文件：
+Newly created deployment-related files:

 ```
-✨ scripts/deploy_filter.py                     (新增) ~300 行
-✨ scripts/deploy_async_context_compression.py  (新增) ~70 行
-✨ scripts/DEPLOYMENT_GUIDE.md                  (新增) 完整指南
-✨ scripts/DEPLOYMENT_SUMMARY.md                (新增) 技术总结
-✨ scripts/QUICK_START.md                       (新增) 快速参考
-📄 tests/scripts/test_deploy_filter.py          (新增) 10 个单元测试 ✅
+✨ scripts/deploy_filter.py                     (new) ~300 lines
+✨ scripts/deploy_async_context_compression.py  (new) ~70 lines
+✨ scripts/DEPLOYMENT_GUIDE.md                  (new) complete guide
+✨ scripts/DEPLOYMENT_SUMMARY.md                (new) technical summary
+✨ scripts/QUICK_START.md                       (new) quick reference
+📄 tests/scripts/test_deploy_filter.py          (new) 10 unit tests ✅

-✅ 所有文件已创建并测试通过！
+✅ All files created and tested successfully!
 ```

 ---

-**最后更新**: 2026-03-09  
-**脚本状态**: ✅ Ready for production  
-**测试覆盖**: 10/10 通过 ✅
+**Last Updated**: 2026-03-09  
+**Script Status**: ✅ Ready for production  
+**Test Coverage**: 10/10 passed ✅
+