在dotnet/extensions项目中自定义AI工具的系统提示格式

在开发基于AI的应用程序时，我们经常需要将工具定义信息格式化为系统提示的一部分。dotnet/extensions项目中的AITool类提供了强大的功能支持，但开发者有时需要更灵活地控制工具信息的呈现方式。

核心需求分析

许多开发者在使用AI工具调用功能时，会遇到需要自定义工具信息格式的情况。典型的应用场景包括：

1. 将工具定义嵌入系统提示中
2. 控制工具参数的呈现方式
3. 生成特定格式的JSON结构

解决方案实现

我们可以通过扩展方法来实现AITool的自定义格式化。以下是一个完整的实现示例：

public static class AIToolExtensions
{
    public static string FormatAsSystemPrompt(this AITool tool)
    {
        var parameters = GetToolParameters(tool.Name);
        var sb = new StringBuilder();
        
        sb.AppendLine("<|tool|>");
        sb.AppendLine("[");
        sb.AppendLine("  {");
        sb.AppendLine($"    \"name\": \"{EscapeJsonString(tool.Name)}\",");
        sb.AppendLine($"    \"description\": \"{EscapeJsonString(tool.Description)}\",");
        sb.AppendLine("    \"parameters\": {");

        bool isFirstParam = true;
        foreach (var param in parameters)
        {
            if (!isFirstParam) sb.AppendLine(",");
            else isFirstParam = false;

            sb.Append($"      \"{EscapeJsonString(param.Name)}\": {{");
            sb.Append($"\"description\": \"{EscapeJsonString(param.Description)}\", ");
            sb.Append($"\"type\": \"{ConvertToJsonType(param.Type)}\"");
            sb.Append("}");
        }

        sb.AppendLine();
        sb.AppendLine("    }");
        sb.AppendLine("  }");
        sb.AppendLine("]");
        sb.AppendLine("<|/tool|>");

        return sb.ToString();
    }

    private static string ConvertToJsonType(string type) 
        => type.ToLower() == "string" ? "str" : type.ToLower();

    private static string EscapeJsonString(string value)
    {
        return value?
            .Replace("\\", "\\\\")
            .Replace("\"", "\\\"")
            .Replace("\n", "\\n")
            .Replace("\r", "\\r")
            .Replace("\t", "\\t") ?? string.Empty;
    }
}

实际应用示例

在实际应用中，我们可以这样使用这个扩展方法：

var allTools = await client.ListToolsAsync();
var saveFileTool = allTools.First(x => x.Name == "SaveFile");

var systemPrompt = $"""
    <|system|>
    你是一个编码助手，可以使用工具保存文件。
    {saveFileTool.FormatAsSystemPrompt()}
    <|end|>
    """;

chatHistory.Add(new ChatMessage(ChatRole.System, systemPrompt));

技术要点解析

1. JSON Schema转换：dotnet/extensions项目中的AIFunction已经提供了JsonSchema属性，可以直接获取工具定义的JSON结构

2. 自定义格式化：当需要特定格式时，可以通过扩展方法实现自定义格式化逻辑

3. 安全性处理：对JSON字符串进行适当的转义处理，确保生成的JSON结构有效

4. 类型映射：将.NET类型映射为JSON Schema中使用的类型表示

最佳实践建议

1. 优先使用AIFunction提供的JsonSchema属性，它已经包含了完整的工具定义

2. 当需要特殊格式时，可以考虑从JsonSchema出发进行转换，而不是从头构建

3. 对于复杂的格式化需求，可以创建专门的格式化器类，而不是直接在业务代码中处理

4. 考虑将常用的工具定义缓存起来，避免重复生成

通过这种方式，开发者可以灵活地控制AI工具信息的呈现方式，同时保持代码的整洁和可维护性。