update README.md

.gitea/workflows/sonar-scan.yml

@@ -1,91 +1,82 @@
 name: SonarQube Code Quality Scan
+
 on:
   push:
     branches: [ main, develop ]
   pull_request:
     branches: [ main ]
+
 jobs:
   scan:
-    runs-on: windowsx64
+    runs-on: windows-latest
+
+    env:
+      # PROXY_HOST: 127.0.0.1
+      # PROXY_PORT: 7890
+      DC_VERSION: 11.0.0
+      DC_OUTPUT: ./depcheck
+
     steps:
       - name: Checkout Code (Gitea Direct)
         run: |
           git clone https://git.we965.cn/learning/VectorDBDemo.git .
           git fetch --depth=0
           git checkout ${{ github.ref_name }}
+        shell: pwsh
 
       - name: Add Sonar Scanner to PATH
         run: |
-          $scannerPath = "D:\Paths\sonar-scanner-cli\bin"
-          echo "$scannerPath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8
+          echo "D:\Paths\sonar-scanner-cli\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8
 
-      - name: Verify .NET SDK (Local)
+      - name: Verify .NET SDK
         run: |
           dotnet --list-sdks
           dotnet --version
 
+      - name: Run OWASP Dependency Check
+        env:
+          # HTTP_PROXY: http://127.0.0.1:7890
+          # HTTPS_PROXY: http://127.0.0.1:7890
+        run: |
+          New-Item -Path $env:DC_OUTPUT -ItemType Directory -Force
+          & "D:\Paths\Gitea\dependency-check\bin\dependency-check.bat" `
+            --project "VectorDBDemo" `
+            --scan "." `
+            --format "XML" `
+            --out "$env:DC_OUTPUT"
+        shell: pwsh
+
+
       - name: Build .NET Project
         run: |
           dotnet restore
-          dotnet build --configuration Release
+          dotnet build --configuration Release --no-restore
 
-      # 步骤2：SonarQube 扫描（含代码+依赖漏洞）
       - name: SonarQube Full Scan
         run: |
-          dotnet tool install --global dotnet-sonarscanner
+          dotnet tool install --global dotnet-sonarscanner --no-cache
           dotnet sonarscanner begin `
-            /k:"${{ secrets.SONAR_TOKEN }}" `
+            /k:"vectordbdemo" `
             /d:sonar.host.url="http://127.0.0.1:9000" `
             /d:sonar.login="${{ secrets.SONAR_TOKEN }}" `
             /d:sonar.sources="./" `
-            /d:sonar.language="csharp" `
-            /d:sonar.exclusions="**/obj/**,**/bin/Debug/**" `
-            /d:sonar.dependencyCheck.enabled=true
-          dotnet build --configuration Release
-          dotnet sonarscanner end /d:sonar.login="${{ secrets.SONAR_TOKEN }}"
+            /d:sonar.exclusions="**/obj/**,**/bin/**,depcheck/**" `
+            /d:sonar.dependencyCheck.xmlReportPath="$env:DC_OUTPUT\dependency-check-report.xml" `
+            /d:sonar.verbose=true
+          dotnet build --configuration Release --no-restore
+          dotnet sonarscanner end `
+            /d:sonar.login="${{ secrets.SONAR_TOKEN }}"
 
-      # 步骤3：拉取 SonarQube Blocker 级问题（PowerShell 脚本）
       - name: Fetch SonarQube Blocker Issues
         id: fetch_issues
         run: |
-          # SonarQube API 地址（获取 Blockeer 级问题）
-          $sonarApiUrl = "http://127.0.0.1:9000/api/issues/search?project=${{ secrets.SONAR_TOKEN }}&severities=BLOCKER&statuses=OPEN"
-          # 调用 API 拉取数据
-          $response = Invoke-RestMethod -Uri $sonarApiUrl -Headers @{
-            "Authorization" = "Bearer ${{ secrets.SONAR_API_TOKEN }}"
+          $projectKey = "vectordbdemo"
+          $sonarApiUrl = "http://127.0.0.1:9000/api/issues/search?componentKeys=$projectKey&severities=BLOCKER&statuses=OPEN"
+          $auth = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("${{ secrets.SONAR_TOKEN }}:"))
+          $response = Invoke-RestMethod -Uri $sonarApiUrl -Headers @{ Authorization = "Basic $auth" }
+          $blockerCount = $response.total
+          echo "blocker_issues_count=$blockerCount" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8
+          if ($blockerCount -gt 0) {
+            Write-Error "Found $blockerCount Blocker issues in SonarQube"
+            exit 1
           }
-          # 输出问题数量
-          Write-Host "发现 Blocker 级问题：$($response.total) 个"
-          # 将问题数据存入环境变量（供下一步使用）
-          $issuesJson = $response.issues | ConvertTo-Json -Compress
-          echo "ISSUES_JSON=$issuesJson" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
-
-      # 步骤4：自动创建 Gitea Bug 议题
-      - name: Create Gitea Bug Issues
-        if: fromJson(env.ISSUES_JSON).Count -gt 0  # 有 Blocker 问题才执行
-        run: |
-          $issues = $env:ISSUES_JSON | ConvertFrom-Json
-          $giteaApiUrl = "https://git.we965.cn/api/v1/repos/learning/VectorDBDemo/issues"  # Gitea 仓库 API 地址
-          foreach ($issue in $issues) {
-            # 构造 Bug 内容（包含 SonarQube 问题详情）
-            $issueBody = @"
-          ## SonarQube Blocker 级问题自动创建
-          - **问题 ID**：$($issue.key)
-          - **问题类型**：$($issue.type)
-          - **影响文件**：$($issue.component -replace '.*:', '')
-          - **行号**：$($issue.line)
-          - **问题描述**：$($issue.message)
-          - **修复建议**：$($issue.actions.fixNewValue ?? '无明确修复建议，请查看 SonarQube 详情')
-          - **SonarQube 链接**：http://127.0.0.1:9000/project/issues?id=${{ secrets.SONAR_TOKEN }}&open=$($issue.key)
-          "@
-            # 调用 Gitea API 创建议题（标签设为 Bug）
-            Invoke-RestMethod -Uri $giteaApiUrl -Method Post -Headers @{
-              "Authorization" = "token ${{ secrets.GITEAAPITOKEN }}"
-              "Content-Type" = "application/json"
-            } -Body (@{
-              title = "[BUG] SonarQube Blocker: $($issue.message.Substring(0, [Math]::Min(50, $issue.message.Length)))"  # 标题截取前 50 字
-              body = $issueBody
-              labels = @("Bug")  # 自动添加 Bug 标签
-            } | ConvertTo-Json)
-            Write-Host "已创建 Gitea Bug：$($issue.key)"
-          }

MilvusDemo/MilvusDemo.csproj

@@ -8,6 +8,7 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <PackageReference Include="Newtonsoft.Json" Version="12.0.1" />
     <PackageReference Include="Milvus.Client" Version="2.3.0-preview.1" />
   </ItemGroup>
 

MilvusDemo/Program.cs

@@ -27,6 +27,7 @@ namespace MilvusDemo
         static async Task RunActualMilvusOperations()
         {
             // 初始化MilvusService
+            const string password = "123456789";
             const string host = "localhost";
             const int port = 19530;
             const string collectionName = "csharp_demo_collection";

README.md

@@ -1,4 +1,87 @@
-# MilvusDemo
+# VectorDBDemo
+
+一个基于 .NET 9 的向量数据库与自然语言函数调用示例集合，展示现代 C# 在 AI 相关领域的应用。
+
+## 目录
+
+- [项目简介](#项目简介)
+- [技术栈](#技术栈)
+- [项目结构](#项目结构)
+- [快速开始](#快速开始)
+- [MilvusDemo](#milvusdemo)
+  - [功能特性](#功能特性)
+  - [模块划分](#模块划分)
+  - [运行示例](#运行示例)
+  - [API 说明](#api-说明)
+- [VoiceToFunctionDemo](#voicetofunctiondemo)
+  - [功能特性](#功能特性-1)
+  - [内置函数](#内置函数)
+  - [运行示例](#运行示例-1)
+  - [扩展开发](#扩展开发)
+- [开发指南](#开发指南)
+- [常见问题](#常见问题)
+- [贡献指南](#贡献指南)
+
+## 项目简介
+
+本项目包含两个独立的示例项目，分别演示了不同的技术场景：
+
+1. **MilvusDemo** - 演示如何使用 C# 与 Milvus 向量数据库进行交互，包括集合管理、索引创建、数据插入和向量搜索
+2. **VoiceToFunctionDemo** - 演示如何将自然语言指令解析为函数调用，支持参数提取和类型验证
+
+## 技术栈
+
+- **.NET 9.0** - 使用最新的 .NET 平台
+- **C# 12** - 现代化的 C# 语法特性
+- **Milvus.Client** (v2.3.0-preview.1) - Milvus 向量数据库的 .NET 客户端
+- **Newtonsoft.Json** (v12.0.1) - JSON 序列化支持
+
+## 项目结构
+
+```
+VectorDBDemo/
+├── MilvusDemo/                    # Milvus 向量数据库示例
+│   ├── Program.cs                 # 程序入口，提供交互式菜单
+│   ├── MilvusService.cs           # Milvus 服务封装
+│   ├── MilvusServiceTests.cs      # 模拟测试实现
+│   ├── TestRunner.cs              # 测试运行器
+│   └── MilvusDemo.csproj          # 项目配置
+├── VoiceToFunctionDemo/           # 语音转函数调用示例
+│   ├── Program.cs                 # 程序入口和示例演示
+│   ├── FunctionInfo.cs            # 函数信息定义
+│   ├── ParsedResult.cs            # 解析结果模型
+│   ├── User.cs                    # 用户实体类
+│   └── VoiceToFunctionDemo.csproj # 项目配置
+├── .vscode/                       # VS Code 配置
+├── .gitea/                        # CI/CD 配置
+└── VectorDBDemo.slnx              # 解决方案文件
+```
+
+## 快速开始
+
+### 环境要求
+
+- .NET SDK 9.0 或更高版本
+- （可选）Milvus Server - 仅在运行 MilvusDemo 的实际连接模式时需要
+
+### 安装 .NET 9
+
+访问 [https://dotnet.microsoft.com/download](https://dotnet.microsoft.com/download) 下载并安装 .NET 9 SDK。
+
+### 构建项目
+
+```powershell
+# 构建整个解决方案
+dotnet build
+
+# 或构建特定项目
+dotnet build MilvusDemo
+dotnet build VoiceToFunctionDemo
+```
+
+---
+
+## MilvusDemo
 
 一个使用 C#（.NET 9）与 `Milvus.Client` 的极简示例项目，演示：
 - 初始化集合（存在则删除并重建）
@@ -7,75 +90,106 @@
 - 执行向量相似度搜索
 - 通过内置测试流程验证调用链
 
+### 功能特性
+
+- **双模式运行**
+  - 实际连接模式：连接真实的 Milvus 服务器执行操作
+  - 模拟测试模式：无需 Milvus 实例，验证调用链和参数
+
+- **完整的向量数据库操作**
+  - 集合的创建、删除和重建
+  - 向量索引的创建（支持 Flat 索引类型）
+  - 批量数据插入
+  - 向量相似度搜索（支持 L2 距离度量）
+
+- **清晰的架构设计**
+  - 分层架构：入口层、业务层、测试层
+  - 依赖注入友好的设计
+  - 完善的 XML 文档注释
+
 ### 模块划分
+
 - **App（入口层）**：`Program.cs`
   - 提供交互式入口：输入 1=实际连接 Milvus 执行；输入 2=运行内置测试（无需 Milvus 实例）。
+
 - **Core/Service（业务层）**：`MilvusService.cs`
   - 封装与 Milvus 的连接、集合初始化、索引创建/加载、数据插入与搜索。
+
 - **Test Harness（测试层）**：`TestRunner.cs`、`MilvusServiceTests.cs`
   - `TestRunner` 负责编排测试流程；`MilvusServiceTests` 提供无外部依赖的模拟测试（验证调用链与参数）。
 
-### 环境要求
-- .NET SDK 9.0+
-- 仅当选择“实际运行（选项 1）”时需要：可访问的 Milvus Server（默认 `localhost:19530`）。
+### 运行示例
 
-### 快速开始
-1. 构建
-   ```powershell
-   dotnet build
-   ```
-2. 运行（测试模式，无需 Milvus）
-   - PowerShell：
-     ```powershell
-     echo 2 | dotnet run
-     ```
-   - Bash：
-     ```bash
-     echo 2 | dotnet run
-     ```
-3. 运行（实际连接 Milvus）
-   - 确保本地或可达的 Milvus 实例运行在 `localhost:19530`。
-   - 程序启动后输入 `1`。
-
-### 在解决方案根目录运行（多项目）
-本仓库包含多个示例项目。可在解决方案根目录使用 `--project` 指定要运行的项目：
+#### 1. 测试模式（无需 Milvus）
 
 ```powershell
-# 运行 Milvus 示例（默认交互菜单 1/2）
-dotnet run --project MilvusDemo
+# PowerShell
+echo 2 | dotnet run --project MilvusDemo
 
-# 运行语音到函数示例
-dotnet run --project VoiceToFunctionDemo
+# Bash
+echo 2 | dotnet run --project MilvusDemo
 ```
 
-### 启动 Milvus（可选）
-若需在本机快速启动 Milvus，可参考官方快速开始，或使用 Docker（示例）：
+**预期输出：**
+```
+开始运行MilvusService测试...
+测试完成！
+```
 
-```bash
-# 仅供参考，建议按官方文档选择合适的版本与持久化配置
-docker pull milvusdb/milvus:latest
+#### 2. 实际连接模式（需要 Milvus）
+
+```powershell
+# 启动 Milvus（如果未运行）
 docker run -d --name milvus-standalone -p 19530:19530 milvusdb/milvus:latest
+
+# 运行程序
+dotnet run --project MilvusDemo
+# 然后输入 1
 ```
 
-文档：`https://milvus.io/docs`（查看“Get Started / Install”）。
+**预期输出：**
+```
+Milvus 演示程序
+1. 运行实际的 Milvus 操作
+2. 运行模拟测试
+请选择 (1/2): 1
+Collection 'csharp_demo_collection' dropped.
+Collection 'csharp_demo_collection' created.
+Index created.
+Collection loaded.
+Data inserted.
 
-### 主要参数（实际运行模式）
-- 主机与端口：`localhost:19530`
+Search results:
+- ID: 123
+- ID: 456
+...
+```
+
+### API 说明
+
+#### MilvusService 类
+
+**构造函数**
+```csharp
+public MilvusService(string host, int port, string collectionName, int dim)
+```
+
+**主要方法**
+
+| 方法 | 说明 | 参数 |
+|------|------|------|
+| `InitializeCollectionAsync()` | 初始化集合，存在则删除重建 | 无 |
+| `CreateIndexAndLoadAsync()` | 创建索引并加载集合 | 无 |
+| `InsertRandomDataAsync(int count)` | 插入指定数量的随机向量 | count: 向量数量 |
+| `SearchVectorAsync(int topK)` | 执行向量相似度搜索 | topK: 返回结果数量 |
+
+**默认配置**
+- 主机：`localhost`
+- 端口：`19530`
 - 集合名：`csharp_demo_collection`
 - 向量维度：`8`
-
-> 提示：若需修改连接地址或集合名，请在代码中相应位置调整（例如在连接初始化与集合定义处）。
-
-### 文件说明
-- `Program.cs`：控制台入口与菜单；调用服务或测试。
-- `MilvusService.cs`：核心服务，封装 Milvus 客户端操作。
-- `MilvusServiceTests.cs`：简单的模拟测试实现（不依赖 Milvus）。
-- `TestRunner.cs`：运行测试流程的编排类。
-- `MilvusDemo.csproj`：项目与依赖定义（包含 `Milvus.Client`）。
-
-### 项目结构
-- `MilvusDemo/`：Milvus 向量数据库最小示例，支持实际连接与模拟测试两种模式。
-- `VoiceToFunctionDemo/`：语音（文本）解析为函数调用的示例，展示如何从自然语言中抽取参数并调用预定义函数。
+- 索引类型：`Flat`
+- 相似度度量：`L2`
 
 ---
 
@@ -86,24 +200,228 @@ docker run -d --name milvus-standalone -p 19530:19530 milvusdb/milvus:latest
 - `FILTER(List<User>, Func<User,bool>)`：按条件筛选用户（支持年龄阈值与姓名包含）
 - `COUNTIF(double[], Func<double,bool>)`：按范围统计数量
 
-### 运行
+### 功能特性
+
+- **自然语言解析**
+  - 支持中文指令识别
+  - 同义词匹配机制
+  - 灵活的参数提取
+
+- **类型安全**
+  - 参数类型验证
+  - 编译时类型检查
+  - 运行时类型匹配
+
+- **可扩展架构**
+  - 函数库动态注册
+  - 支持自定义函数
+  - 参数解析器可定制
+
+### 内置函数
+
+| 函数名 | 描述 | 参数类型 | 示例指令 |
+|--------|------|----------|----------|
+| `PRODUCT` | 计算多列对应行的乘积 | `double[]`, `double[]` | "计算C列和D列的乘积，C列是[1,3,5]，D列是[2,4,6]" |
+| `FILTER` | 筛选满足条件的数据 | `List<User>`, `Func<User,bool>` | "筛选出年龄大于28且姓名包含'李'的用户" |
+| `COUNTIF` | 统计满足条件的记录数 | `double[]`, `Func<double,bool>` | "统计销售额在5000到20000之间的订单数" |
+
+### 运行示例
+
 ```powershell
 dotnet run --project VoiceToFunctionDemo
 ```
 
-程序内置了示例输入，启动后会依次演示：
-- 计算两列数值的乘积（如 `[1,3,5]` 与 `[2,4,6]`）
-- 筛选年龄大于某值且姓名包含关键字的用户
-- 统计销售额处于指定区间内的订单数
+**预期输出：**
+```
+=== 语音指令：计算C列和D列的乘积，C列是[1,3,5]，D列是[2,4,6] ===
+匹配函数：PRODUCT
+执行结果：2, 12, 30
 
-如需扩展，请修改 `VoiceToFunctionDemo/Program.cs`：
-- 新增函数：在 `functionLibrary` 中增加 `FunctionInfo`，定义参数类型与执行逻辑。
-- 扩展解析：在 `ParseVoiceCommand` 中为新函数添加参数解析与类型校验。
+=== 语音指令：筛选出年龄大于28且姓名包含'李'的用户 ===
+匹配函数：FILTER
+执行结果：李四(30), 李白(29)
+
+=== 语音指令：统计销售额在5000到20000之间的订单数，数据是[3000, 8000, 15000, 25000] ===
+匹配函数：COUNTIF
+执行结果：2
+```
+
+### 扩展开发
+
+#### 添加新函数
+
+1. 在 `Program.cs` 的 `functionLibrary` 中添加新的 `FunctionInfo`：
+
+```csharp
+new FunctionInfo
+{
+    Name = "SUM",
+    Description = "计算数组的和",
+    Synonyms = new List<string> { "求和", "总和", "合计" },
+    MinParams = 1,
+    ParamTypes = new List<Type> { typeof(double[]) },
+    Execute = (args) =>
+    {
+        double[] data = (double[])args[0];
+        return data.Sum();
+    }
+}
+```
+
+2. 在 `ParseVoiceCommand` 方法中添加参数解析逻辑：
+
+```csharp
+case "SUM":
+    var sumData = Regex.Match(text, @"\[([\d, ]+)\]")
+        .Groups[1].Value.Split(',').Select(double.Parse).ToArray();
+    result.Parameters = new object[] { sumData };
+    result.ParamTypes = new[] { "Double[]" };
+    break;
+```
 
 ---
 
-### 常见问题（FAQ）
-- 无法连接到 Milvus：请确认 Milvus 是否已启动并监听 `19530` 端口，以及本机/容器网络连通性。
-- 还原/编译失败：请确认已安装 .NET 9 SDK，并允许联网下载 NuGet 依赖；必要时执行 `dotnet restore` 后再构建。
-- 端口占用：如 `19530` 已被占用，请修改容器映射或程序连接端口并保持一致。
+## 开发指南
 
+### 在解决方案根目录运行
+
+本仓库包含多个示例项目。可在解决方案根目录使用 `--project` 指定要运行的项目：
+
+```powershell
+# 运行 Milvus 示例（默认交互菜单 1/2）
+dotnet run --project MilvusDemo
+
+# 运行语音到函数示例
+dotnet run --project VoiceToFunctionDemo
+
+# 构建整个解决方案
+dotnet build
+```
+
+### 启动 Milvus（可选）
+
+若需在本机快速启动 Milvus，可参考官方快速开始，或使用 Docker：
+
+```bash
+# 拉取最新镜像
+docker pull milvusdb/milvus:latest
+
+# 启动独立实例
+docker run -d --name milvus-standalone -p 19530:19530 milvusdb/milvus:latest
+
+# 查看日志
+docker logs -f milvus-standalone
+
+# 停止并删除容器
+docker stop milvus-standalone
+docker rm milvus-standalone
+```
+
+**官方文档**：[https://milvus.io/docs](https://milvus.io/docs)（查看"Get Started / Install"）
+
+### 代码规范
+
+- 遵循 C# 编码规范
+- 使用 XML 文档注释
+- 方法名使用 PascalCase
+- 私有字段使用 _camelCase
+- 异步方法以 Async 后缀结尾
+
+### 测试
+
+```powershell
+# 运行 MilvusDemo 模拟测试
+echo 2 | dotnet run --project MilvusDemo
+
+# 运行 VoiceToFunctionDemo（内置测试）
+dotnet run --project VoiceToFunctionDemo
+```
+
+---
+
+## 常见问题（FAQ）
+
+### Milvus 相关
+
+**Q: 无法连接到 Milvus？**
+
+A: 请确认：
+- Milvus 是否已启动并监听 `19530` 端口
+- 使用 `docker ps` 检查容器状态
+- 使用 `docker logs milvus-standalone` 查看日志
+- 确认本机/容器网络连通性
+
+**Q: 端口 19530 已被占用？**
+
+A: 修改容器映射或程序连接端口并保持一致：
+```bash
+# 使用其他端口
+docker run -d --name milvus-standalone -p 19531:19530 milvusdb/milvus:latest
+```
+
+### 构建相关
+
+**Q: 还原/编译失败？**
+
+A: 请确认：
+- 已安装 .NET 9 SDK：`dotnet --version`
+- 允许联网下载 NuGet 依赖
+- 必要时执行 `dotnet restore` 后再构建
+
+**Q: 如何清理构建产物？**
+
+A:
+```powershell
+dotnet clean
+```
+
+### VoiceToFunctionDemo 相关
+
+**Q: 如何添加新的函数？**
+
+A: 参考 [扩展开发](#扩展开发) 部分，主要步骤：
+1. 在 `functionLibrary` 中添加函数定义
+2. 在 `ParseVoiceCommand` 中添加参数解析逻辑
+3. 确保参数类型匹配
+
+**Q: 支持英文指令吗？**
+
+A: 当前版本主要支持中文指令，如需支持英文，请在 `Synonyms` 中添加英文同义词。
+
+---
+
+## 贡献指南
+
+欢迎贡献代码！请遵循以下步骤：
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request
+
+### 提交规范
+
+- feat: 新功能
+- fix: 修复 bug
+- docs: 文档更新
+- style: 代码格式调整
+- refactor: 重构
+- test: 测试相关
+- chore: 构建/工具相关
+
+---
+
+## 许可证
+
+本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
+
+## 联系方式
+
+如有问题或建议，请通过以下方式联系：
+- 提交 Issue
+- 发起 Pull Request
+
+---
+
+**最后更新**: 2026-02-26