.NET AgentFramework集成Shell命令实现自动化技能

1. 项目背景与核心概念解析

在.NET生态中，AgentFramework是一个用于构建智能体(Agent)应用的框架，而Agent Skill则是智能体可执行的具体能力单元。这个项目通过集成Shell命令能力，实现了名为"小龙虾mini版峡"的功能模块。听起来像是个有趣的昵称，实际上它可能是一个轻量级的命令行交互工具或自动化脚本集合。

智能体技术近年来在企业自动化、DevOps工具链等领域应用广泛。通过将Shell命令封装为Agent Skill，我们可以在.NET应用中直接调用系统级操作，实现诸如文件处理、服务管理、批处理等复杂功能。这种集成方式打破了应用与操作系统之间的壁垒，为自动化工作流提供了新的可能性。

注意：在Windows环境下集成Shell命令需要特别注意权限管理和安全边界，避免执行危险命令导致系统风险。

2. AgentFramework环境搭建与基础配置

2.1 开发环境准备

首先需要安装.NET SDK（建议6.0或以上版本），然后通过NuGet添加AgentFramework核心包：

bash复制dotnet add package Microsoft.AgentFramework --version 1.0.0

创建基础的Agent项目结构：

code复制MyAgentProject/
├── Skills/          # 技能实现目录
├── AgentCore/       # 智能体核心逻辑
├── appsettings.json # 配置文件
└── Program.cs       # 入口文件

2.2 基础Agent实现

在Program.cs中初始化Agent宿主：

csharp复制using Microsoft.AgentFramework;

var builder = Host.CreateDefaultBuilder(args);
builder.ConfigureServices(services => {
    services.AddAgentHost();
});

var host = builder.Build();
await host.RunAsync();

3. Shell命令技能实现详解

3.1 创建基础ShellSkill类

新建一个ShellCommandSkill类，继承自ISkill接口：

csharp复制using System.Diagnostics;
using Microsoft.AgentFramework.Skills;

public class ShellCommandSkill : ISkill
{
    public string Name => "ShellCommand";
    
    public async Task<SkillExecutionResult> ExecuteAsync(SkillContext context)
    {
        var command = context.Parameters["command"]?.ToString();
        if(string.IsNullOrEmpty(command))
            return SkillExecutionResult.Failure("Command parameter is required");
            
        return await ExecuteShellCommand(command);
    }
    
    private async Task<SkillExecutionResult> ExecuteShellCommand(string command)
    {
        try {
            var process = new Process {
                StartInfo = new ProcessStartInfo {
                    FileName = "cmd.exe",
                    Arguments = $"/C {command}",
                    RedirectStandardOutput = true,
                    RedirectStandardError = true,
                    UseShellExecute = false,
                    CreateNoWindow = true
                }
            };
            
            process.Start();
            var output = await process.StandardOutput.ReadToEndAsync();
            await process.WaitForExitAsync();
            
            return SkillExecutionResult.Success(output);
        }
        catch(Exception ex) {
            return SkillExecutionResult.Failure(ex.Message);
        }
    }
}

3.2 增强型Shell执行器

基础版本存在命令注入风险，我们需要增加安全校验：

csharp复制private static readonly Regex SafeCommandRegex = new Regex(@"^[a-zA-Z0-9 _\\\/\.:\-]+$");

private bool ValidateCommand(string command)
{
    // 检查是否包含危险字符
    if(command.Contains("&") || command.Contains("|") || command.Contains(">"))
        return false;
        
    // 检查命令格式是否合法
    return SafeCommandRegex.IsMatch(command);
}

4. "小龙虾mini版峡"功能实现

4.1 功能架构设计

这个昵称可能指的是一个轻量级命令行工具集，我们可以设计如下功能模块：

1. 文件操作模块：封装常用文件操作命令
2. 系统信息模块：获取系统状态信息
3. 网络工具模块：基本的网络诊断命令
4. 批处理模块：支持简单的脚本执行

4.2 具体实现示例

以文件操作模块为例：

csharp复制public class FileOperationsSkill : ISkill
{
    public string Name => "FileOperations";
    
    private readonly ShellCommandSkill _shellSkill;
    
    public FileOperationsSkill(ShellCommandSkill shellSkill)
    {
        _shellSkill = shellSkill;
    }
    
    public async Task<SkillExecutionResult> ExecuteAsync(SkillContext context)
    {
        var operation = context.Parameters["operation"]?.ToString();
        var path = context.Parameters["path"]?.ToString();
        
        switch(operation?.ToLower())
        {
            case "list":
                return await _shellSkill.ExecuteAsync(new SkillContext {
                    Parameters = new Dictionary<string, object> {
                        {"command", $"dir {path}"}
                    }
                });
                
            case "delete":
                // 添加额外的安全检查
                if(!path.EndsWith(".tmp")) {
                    return SkillExecutionResult.Failure("Only .tmp files can be deleted");
                }
                return await _shellSkill.ExecuteAsync(new SkillContext {
                    Parameters = new Dictionary<string, object> {
                        {"command", $"del {path}"}
                    }
                });
                
            default:
                return SkillExecutionResult.Failure($"Unsupported operation: {operation}");
        }
    }
}

5. 安全加固与最佳实践

5.1 命令白名单机制

建立可执行的命令白名单：

csharp复制private static readonly HashSet<string> AllowedCommands = new() {
    "dir", "copy", "del", "ping", "ipconfig", 
    "systeminfo", "tasklist", "netstat"
};

public bool IsCommandAllowed(string command)
{
    var firstToken = command.Split(' ')[0];
    return AllowedCommands.Contains(firstToken.ToLower());
}

5.2 执行上下文隔离

为每个命令执行创建独立的工作目录：

csharp复制private async Task<SkillExecutionResult> ExecuteInIsolation(string command)
{
    var tempDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString());
    Directory.CreateDirectory(tempDir);
    
    try {
        var process = new Process {
            StartInfo = new ProcessStartInfo {
                FileName = "cmd.exe",
                Arguments = $"/C cd /D {tempDir} && {command}",
                // 其他配置...
            }
        };
        
        // 执行过程...
    }
    finally {
        Directory.Delete(tempDir, true);
    }
}

6. 实际应用场景示例

6.1 自动化部署流程

结合Shell命令技能实现简单的部署流程：

csharp复制public async Task DeployApplication(string sourcePath, string targetPath)
{
    // 停止现有服务
    await _shellSkill.ExecuteAsync(new SkillContext {
        Parameters = { {"command", "net stop MyService"} }
    });
    
    // 备份旧版本
    await _shellSkill.ExecuteAsync(new SkillContext {
        Parameters = { {"command", $"robocopy {targetPath} {targetPath}_bak /MIR"} }
    });
    
    // 部署新版本
    await _shellSkill.ExecuteAsync(new SkillContext {
        Parameters = { {"command", $"robocopy {sourcePath} {targetPath} /MIR"} }
    });
    
    // 启动服务
    await _shellSkill.ExecuteAsync(new SkillContext {
        Parameters = { {"command", "net start MyService"} }
    });
}

6.2 系统监控看板

创建简单的系统监控面板：

csharp复制public async Task<SystemInfo> GetSystemInfo()
{
    var cpuResult = await _shellSkill.ExecuteAsync(new SkillContext {
        Parameters = { {"command", "wmic cpu get loadpercentage /Value"} }
    });
    
    var memoryResult = await _shellSkill.ExecuteAsync(new SkillContext {
        Parameters = { {"command", "wmic OS get FreePhysicalMemory,TotalVisibleMemorySize /Value"} }
    });
    
    return new SystemInfo {
        CpuUsage = ParseCpuInfo(cpuResult.Output),
        MemoryUsage = ParseMemoryInfo(memoryResult.Output)
    };
}

7. 调试与问题排查

7.1 常见问题及解决方案

问题1：命令执行无响应

• 检查是否在UI线程执行了同步等待
• 确认命令没有弹出交互式窗口
• 验证命令是否在独立终端中可以执行

问题2：权限不足

• 确保应用以适当权限运行
• 对于需要管理员权限的命令，考虑使用任务计划程序

问题3：中文路径/输出乱码

• 设置正确的代码页：chcp 65001
• 在ProcessStartInfo中指定编码：

  csharp复制StartInfo = {
      StandardOutputEncoding = Encoding.UTF8,
      StandardErrorEncoding = Encoding.UTF8
  }
  

7.2 日志记录增强

为Shell命令执行添加详细日志：

csharp复制private readonly ILogger<ShellCommandSkill> _logger;

public async Task<SkillExecutionResult> ExecuteAsync(SkillContext context)
{
    _logger.LogInformation("Executing shell command: {Command}", 
        context.Parameters["command"]);
    
    var stopwatch = Stopwatch.StartNew();
    try {
        var result = await ExecuteCommandInternal(context);
        _logger.LogInformation("Command executed in {Elapsed}ms", 
            stopwatch.ElapsedMilliseconds);
        return result;
    }
    catch(Exception ex) {
        _logger.LogError(ex, "Command execution failed");
        return SkillExecutionResult.Failure(ex.Message);
    }
}

8. 性能优化技巧

8.1 命令批处理

将多个相关命令合并执行：

csharp复制public async Task ExecuteBatchCommands(IEnumerable<string> commands)
{
    var batchFile = Path.GetTempFileName() + ".bat";
    try {
        await File.WriteAllLinesAsync(batchFile, commands);
        
        await _shellSkill.ExecuteAsync(new SkillContext {
            Parameters = { {"command", batchFile} }
        });
    }
    finally {
        File.Delete(batchFile);
    }
}

8.2 异步流式输出

对于长时间运行的命令，实现流式输出：

csharp复制public async IAsyncEnumerable<string> ExecuteStreamingCommand(string command)
{
    var process = new Process {
        StartInfo = new ProcessStartInfo {
            FileName = "cmd.exe",
            Arguments = $"/C {command}",
            RedirectStandardOutput = true,
            UseShellExecute = false,
            CreateNoWindow = true
        }
    };
    
    process.Start();
    
    while(!process.StandardOutput.EndOfStream) {
        var line = await process.StandardOutput.ReadLineAsync();
        if(line != null) yield return line;
    }
    
    await process.WaitForExitAsync();
}

9. 扩展与集成思路

9.1 与其它Agent Skill协作

将Shell命令技能与其他技能结合使用：

csharp复制public async Task BackupAndNotify(string path)
{
    // 执行备份
    var result = await _shellSkill.ExecuteAsync(new SkillContext {
        Parameters = { {"command", $"robocopy {path} {path}_bak /MIR"} }
    });
    
    // 根据结果发送通知
    if(result.IsSuccess) {
        await _notificationSkill.ExecuteAsync(new SkillContext {
            Parameters = {
                {"message", "Backup completed successfully"},
                {"channel", "operations"}
            }
        });
    }
}

9.2 构建技能市场

设计可动态加载的技能包系统：

csharp复制public class SkillPackageManager
{
    private readonly ISkillLoader _skillLoader;
    
    public async Task LoadSkillPackage(string packagePath)
    {
        // 解压技能包
        await _shellSkill.ExecuteAsync(new SkillContext {
            Parameters = { {"command", $"tar -xzf {packagePath} -C ./Skills"} }
        });
        
        // 加载技能程序集
        var assembly = Assembly.LoadFrom(Path.Combine("./Skills", Path.GetFileNameWithoutExtension(packagePath), "skill.dll"));
        
        // 注册技能
        foreach(var type in assembly.GetTypes().Where(t => typeof(ISkill).IsAssignableFrom(t))) {
            _skillLoader.RegisterSkill(type);
        }
    }
}

10. 项目部署与运维

10.1 容器化部署

创建Dockerfile进行容器化部署：

dockerfile复制FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["MyAgent/MyAgent.csproj", "MyAgent/"]
RUN dotnet restore "MyAgent/MyAgent.csproj"
COPY . .
WORKDIR "/src/MyAgent"
RUN dotnet build "MyAgent.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "MyAgent.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MyAgent.dll"]

10.2 性能监控配置

添加性能计数器监控：

csharp复制public class PerformanceMonitorSkill : ISkill
{
    public async Task<SkillExecutionResult> ExecuteAsync(SkillContext context)
    {
        var counterName = context.Parameters["counter"]?.ToString() ?? "Processor";
        var instanceName = context.Parameters["instance"]?.ToString() ?? "_Total";
        var categoryName = context.Parameters["category"]?.ToString() ?? "Processor";
        
        using var counter = new PerformanceCounter(
            categoryName, 
            "% Processor Time", 
            instanceName);
            
        counter.NextValue();
        await Task.Delay(1000);
        var value = counter.NextValue();
        
        return SkillExecutionResult.Success(new {
            Counter = $"{categoryName}\\{instanceName}\\{counterName}",
            Value = value
        });
    }
}

在实际项目中，我发现Shell命令执行的超时控制特别重要。曾经遇到过一个场景，某个网络诊断命令在特定环境下会无限期挂起，导致整个Agent无响应。后来我们为所有Shell命令执行添加了默认超时机制：

csharp复制private async Task<SkillExecutionResult> ExecuteWithTimeout(string command, int timeoutMs = 30000)
{
    using var cts = new CancellationTokenSource(timeoutMs);
    try {
        var process = new Process { /* 配置 */ };
        process.Start();
        
        var outputTask = process.StandardOutput.ReadToEndAsync();
        var completionTask = process.WaitForExitAsync(cts.Token);
        
        await Task.WhenAll(outputTask, completionTask);
        
        return SkillExecutionResult.Success(outputTask.Result);
    }
    catch(TaskCanceledException) {
        process?.Kill();
        return SkillExecutionResult.Failure("Command timed out");
    }
}