项目概述
核心功能
- 多策略支持:提供 5 种工具调用策略(禁用/空白/混合/优先/强制)
- 多服务器管理:支持配置多个 MCP 服务器,动态发现和管理工具
- 可视化配置:完整的设置界面,支持服务器管理、工具开关、测试连接
技术栈
- .NET 8.0 - 运行时
- WPF - 用户界面
- CommunityToolkit.Mvvm - MVVM 框架
- iNKORE.UI.WPF.Modern - 现代 UI 组件
- Newtonsoft.Json - JSON 序列化
- MCP Protocol - 模型上下文协议
MCP 工具调用能力
支持的工具类型
- 搜索类:网络搜索、知识库查询、代码库检索
- 数据处理:数据库查询、文件读取、格式转换
- 计算执行:代码执行、数学计算、逻辑处理
- 外部服务:API 调用、认证服务、业务系统集成
典型应用场景
两层优先级架构
插件采用两层优先级策略系统,提供精细化的 MCP 控制:```
第1层:MCP服务功能(总开关)
└─ 控制所有MCP功能的启用/禁用
└─ 禁用后,所有提示词策略和命令系统均不可用
第2层:提示词级策略绑定
└─ 为每个提示词独立设置MCP策略
└─ 支持5种策略:禁用服务/空白策略/混合判断/工具优先/工具强制
└─ 新提示词默认使用"禁用服务"策略
**优先级规则:**
- MCP 服务功能关闭时,所有策略绑定和命令系统失效
- 提示词独立绑定策略,互不干扰
- 新提示词默认使用"禁用服务"策略(可通过命令系统或设置界面修改)
### 5 种工具调用策略
| 策略 | 说明 | 适用场景 |
| ------------ | ---------------------------------- | ------------------ |
| **混合判断** | 可选使用工具,灵活适应不同场景 | 混合类型内容 |
| **工具强制** | 强制使用工具,确保工具链参与 | 高质量要求场景 |
### 命令系统
插件支持通过命令快速切换 MCP 策略,无需打开设置界面:
**设置界面命令列表(表格形式):**
在插件设置的“命令列表”卡片中,以表格形式展示所有可用命令,便于新手快速查阅:
| 中文命令 | 英文命令 | 功能描述 |
| ---------------- | ------------------ | ---------------------------- |
| `/当前` | `/now` | 查看当前提示词的策略和工具设置 |
| `/切换 [策略]` | `/switch [策略]` | 切换当前提示词的 MCP 策略 |
| `/状态` | `/status` | 查看 MCP 服务状态、服务器列表和策略 |
| `/工具链` | `/chain` | 切换当前策略的工具链显示开关 |
| `/工具结果 [模式]`| `/result [模式]` | 查看/切换当前策略的工具结果显示模式 |
| `/mcp` | `/mcp` | 开启或关闭 MCP 服务功能 |
| `/帮助` | `/help` | 显示命令帮助信息 |
**使用示例:**
| 命令 | 功能 | 示例 |
| ------------------------ | ------------------------------ | ---------------------------- |
| `/now` / `/当前` | 查看当前提示词的策略、工具结果模式和工具链状态 | `/当前` |
| `/switch [策略]` / `/切换 [策略]` | 切换当前提示词的 MCP 策略 | `/切换 工具强制` 或 `/switch hybrid` |
| `/status` / `/状态` | 查看 MCP 服务状态、服务器列表和策略 | `/状态` |
| `/chain` / `/工具链` | 切换当前策略的工具链显示 | `/工具链` |
| `/result [模式]` / `/工具结果 [模式]` | 切换工具结果显示模式 | `/工具结果 混合` 或 `/result mixed` |
| `/mcp` | 开启或关闭 MCP 服务功能 | `/mcp` |
| `/help` / `/帮助` | 显示命令帮助 | `/帮助` |
**使用规则:**
- 命令以 `/` 开头,触发命令系统
- 语言需一致(中文或英文),如 `/切换 工具强制` 或 `/switch hybrid`
- 命令系统受 MCP 服务功能开关统辖,MCP 禁用后命令系统不可用
- `/工具链`、`/工具结果`命令需要选择提示词后才可生效
**工具结果显示模式:**
| 模式 | 说明 |
| ------ | ----------------------- |
| `禁用` | 不显示工具结果和内联标记 |
| `粗略` | 仅内联显示工具名 |
| `混合` | 内联+截断显示结果 |
| `详细` | 内联+完整显示结果 |
👉 查看 MCP 工具调用完整文档
👉 查看策略系统详细文档
👉 查看命令系统文档
## 项目结构```
STranslate.Plugin.Translate.DeepSeek/
│
├── Main.cs # 核心:翻译逻辑、MCP管理和命令系统
├── Settings.cs # 数据模型:配置定义
├── McpClient.cs # MCP客户端:连接和调用
├── McpServerConfig.cs # MCP服务器配置类
├── McpToolConfig.cs # MCP工具配置类
├── StrategyEvents.cs # 命令系统与UI同步事件
│
├── View/
│ └── SettingsView.xaml # UI布局:设置界面
│
├── ViewModel/
│ └── SettingsViewModel.cs # 视图模型:界面逻辑
│
├── Converters/
│ └── StrategyConverters.cs # 枚举转换器
│
├── Languages/ # 多语言支持(JSON格式)
│ ├── en.json # 英文名称和描述
│ ├── zh-cn.json # 简体中文名称和描述
│ └── zh-tw.json # 繁体中文名称和描述
│
├── docs/ # 详细文档
│ ├── README.md # 文档入口
│ ├── modules/ # 功能模块文档
│ │ ├── project-structure.md # 项目结构
│ │ ├── main-logic.md # 主翻译逻辑
│ │ ├── settings-system.md # 设置系统
│ │ ├── ui-layout.md # UI布局
│ │ ├── mcp-client.md # MCP客户端
│ │ ├── tool-strategy.md # 工具策略
│ │ └── command-system.md # 命令系统
│ ├── guides/ # 开发指南
│ │ ├── build-deploy.md # 构建部署
│ │ └── troubleshooting.md # 故障排除
│ └── api/ # API参考
│ └── interfaces.md # 接口定义
│
├── artifacts/ # 构建输出
│ └── Debug/
│ └── STranslate.Plugin.DeepSeek.MCP.dll
│
└── plugin.json # 插件元数据
关键文件说明
- 主要方法:
InitializeMcpAndGetSystemPrompt()- 初始化 MCP 连接GetSystemPromptByStrategy()- 根据策略生成系统提示词- 状态管理:
_mcpClients- MCP 客户端列表 - 行数:约 900 行
Settings.cs(数据模型)
- 职责:定义所有配置数据结构
- 核心类:
Settings- 主配置(API 密钥、MCP 设置等)McpServerConfig- 单个服务器配置McpToolConfig- 单个工具配置McpToolStrategy- 工具策略枚举(5 种策略)
McpClient.cs(MCP 协议实现)
- 职责:管理单个 MCP 服务器连接
- 主要方法:
ConnectAsync()- 连接服务器(JSON-RPC 握手)ListToolsAsync()- 获取可用工具列表CallToolAsync()- 调用指定工具- 协议:MCP over HTTP (JSON-RPC 2.0)
SettingsViewModel.cs(界面逻辑)
- 职责:设置界面的数据绑定和命令处理
- 核心功能:
- 服务器 CRUD 操作(增删改查)
- 工具发现和测试连接
- 设置自动保存(防抖 300ms)
- 使用:
CommunityToolkit.Mvvm源生成器
SettingsView.xaml(用户界面)
- 职责:设置界面的布局和样式
- 布局结构:
- API 配置区(URL、密钥、模型选择)
- 提示词配置区(提示词选择 + MCP 策略绑定 + 编辑)
- MCP 服务功能卡片(启用/禁用开关 + 显示工具链开关)
- MCP 全局设置区(全局策略 + 日志级别)
- MCP 服务器配置区(7 行 Grid 布局)
- 服务器配置行(下拉框 + 按钮 + 启用开关)
- 删除确认提示
- 服务器名称输入
- 服务器地址输入
- 请求体输入(API 密钥)
- 工具列表下拉(带启用开关)
- 测试连接按钮 + 结果
- 布局原则:标签右对齐(70px/110px 列宽),输入框左对齐拉伸
核心工作流程```
用户输入文本
↓
检查是否以"/"开头且命令系统已启用
↓
├─ 是 → 解析并执行命令 → 返回命令结果
└─ 否 → 继续翻译流程
↓
TranslateAsync()
↓
检查MCP是否启用
↓
├─ 禁用 → TranslateWithTraditionalApi() → DeepSeek API
└─ 启用 → TranslateWithMcpTools()
↓
初始化MCP(连接服务器、获取工具)
↓
构建系统提示词(根据提示词绑定策略)
↓
发送请求到DeepSeek(非流式)
↓
AI判断是否调用工具
↓
├─ 直接回答 → 返回结果
└─ 调用工具 → 执行工具 → 加入上下文 → 再次请求(循环)
### 2. 策略系统
| 策略 | 连接时机 | 工具使用 | 系统提示词特点 |
| ------------ | ---------- | ------------ | ------------------------------ |
| **Disabled** | 不连接 | 不使用 | 无 |
| **Blank** | 立即连接 | AI 自行判断 | 只列出工具 |
| **Hybrid** | 立即连接 | 可选使用 | "Tools are OPTIONAL" |
| **ToolFirst**| 立即连接 | 优先使用 | "PRIORITIZE using tools" |
| **ToolForced**| 立即连接 | 必须使用 | "MUST use tools" |
### 3. 命令系统流程```
用户输入命令(如"/切换 工具强制")
↓
ExecuteCommandAsync()
↓
解析命令和参数
↓
验证当前提示词是否存在
↓
更新 PromptStrategyMap
↓
触发 StrategyEvents(通知UI更新)
↓
返回命令执行结果
4. 设置持久化```
用户修改设置 → ViewModel属性变更
↓
OnPropertyChanged() → 防抖定时器(300ms)
↓
SaveSettings() → Context.SaveSettings()
↓
保存到 STranslate\current\PortableConfig\Settings\Plugins\STranslate.Plugin.DeepSeek.MCP_d99c702e39b44be5a9e49983ff0f4fff
## 开发指南
### 环境要求
- **.NET SDK 8.0** 或更高
- **Visual Studio 2022** / VS Code / Rider
- **Windows 10/11**
### 构建项目```bash
# 还原依赖
dotnet restore
# 构建Debug版本(开发调试)
dotnet build --configuration Debug
# 构建Release版本(正式发布)
dotnet build --configuration Release
快捷安装
获取 .spkg 文件。
打开 STranslate 软件,进入 设置 > 插件。
将下载的文件拖入窗口即可安装。
开发规范
- 修改设置界面 → 编辑
SettingsView.xaml和SettingsViewModel.cs - 添加配置项 → 编辑
Settings.cs→ ViewModel → XAML - 修改 MCP 功能 → 编辑
McpClient.cs
常见修改场景
- 在
Settings.cs的McpToolStrategy枚举添加新值 - 在
Main.cs的GetSystemPromptByStrategy()添加提示词 - 在
Converters/StrategyConverters.cs添加名称和描述 - 在
SettingsView.xaml更新策略下拉框绑定 - 在
Main.cs的ExecuteCommandAsync()添加策略名称映射
场景2:修改工具链显示格式
- 找到
Main.cs中的FormatToolChainItem()方法 - 修改返回格式(当前:
toolName✅/toolName❌) - 修改
TranslateWithMcpTools()中的显示逻辑
场景3:调整 UI 布局
- 打开
View/SettingsView.xaml - 修改 Grid 的 ColumnDefinition 宽度(标签列默认 110px)
- 调整 Margin 值(标签右边距默认 20px)
- 确保所有行的列定义保持一致
场景4:添加新的 MCP 功能
- 在
McpClient.cs添加新方法(如GetResourceAsync()) - 添加相应的配置项(如果需要)
调试技巧
启用详细日志
在设置界面选择“日志级别:详细”,将输出:
- MCP 连接状态
- 工具调用详情
- API 请求/响应
查看日志位置```
STranslate\current\PortableConfig\Logs
```
常见调试断点
Main.cs:InitializeMcpAndGetSystemPrompt()- MCP 初始化SettingsViewModel.cs:SaveSettings()- 设置保存McpClient.cs:ConnectAsync()- MCP 连接
相关资源
- STranslate 主项目:
- 本项目基于 STranslate.Plugin.Translate.DeepSeek 修改而来,遵循 MIT 许可证。
- DeepSeek API 文档:
- MCP 协议规范:
- 项目详细文档:见
docs/目录
问题反馈
遇到问题请:
- 查看
docs/guides/troubleshooting.md故障排除指南 - 检查
STranslate\current\PortableConfig\Logs中的日志 - 提交 Issue 时提供(因作者使用 AI 制作本插件项目,故不保证及时处理问题):
- 环境信息(Windows/.NET 版本)
- 复现步骤
- 相关日志片段
- 配置文件(删除敏感信息)
注意:本文档是 AI 友好的项目概述。详细的实现细节和修改指南请查看 docs/ 目录下的完整文档。
最后更新:2025年2月
