Swift AppIntent：如何让Siri直接识别带参数的语音指令？

问题场景 #

我正尝试在macOS项目中添加Siri语音控制功能，希望说出类似Overlay to the left 10的指令即可实现操作。

预期效果 #

• Siri能识别Overlay to the left 10这条快捷指令
• 同时识别其中的参数to the left和10

实际表现 #

• Siri仅能识别字面表述Overlay Direction，随后会依次询问"What direction"和"How many pixels"

核心问题 #

AppIntent能否直接从语音指令中识别参数，无需逐个确认参数？

相关代码 #

enum Direction:String{
    case left, right, up, down
}

extension Direction: AppEnum{
    static var caseDisplayRepresentations: [Direction : DisplayRepresentation] = [
        .down: "down",
        .up: "up",
        .left: "to the left",
        .right: "to the right",
    ]
    
    static var typeDisplayName: LocalizedStringResource = "Direction"
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Direction"
}

struct MoveGridIntent: AppIntent {
    
    static var title: LocalizedStringResource = "Overlay Direction"
    static var description = IntentDescription("move the grid")
    static var openAppWhenRun: Bool = true

    @Parameter(title: "Direction", description: "the direction the overlay is going to move", requestValueDialog: IntentDialog("Which direction"))
    var direction: Direction
    
    @Parameter(title: "pixels", inclusiveRange: (1, 50))
    var pixels: Int
       
    static var parameterSummary: some ParameterSummary {
        Summary("Overlay \(\.$direction) \(\.$pixels)")
    }
    
    @MainActor
    func perform() async throws -> some IntentResult {
        print("MoveGridIntent", "move overlay", direction, "for \(pixels) pixels !!")
        return .result()
    }
}

解决方案 #

可以实现直接识别带参数的语音指令，问题出在两个核心设置上，调整后即可解决：

1. 优化Intent标题与参数摘要 #

当前title设为"Overlay Direction"会让Siri优先匹配这个固定短语，而非完整带参数的句式。同时参数摘要的表述不够自然，需要让Siri明确完整指令的结构。

修改MoveGridIntent的对应部分：

struct MoveGridIntent: AppIntent {
    // 改用更通用的标题，避免限制Siri的匹配逻辑
    static var title: LocalizedStringResource = "Move Overlay"
    static var description = IntentDescription("Move the overlay in a direction by specific pixels")
    static var openAppWhenRun: Bool = true

    @Parameter(title: "Direction", description: "the direction the overlay is going to move")
    var direction: Direction
    
    @Parameter(title: "Pixels", inclusiveRange: (1, 50))
    var pixels: Int
       
    static var parameterSummary: some ParameterSummary {
        // 用自然句式定义完整指令模板，让Siri理解参数的位置
        Summary("Move overlay \(\.$direction) by \(\.$pixels) pixels")
    }
    
    // 其余代码保持不变
}

2. 扩展AppEnum的识别表述 #

给Direction的每个case补充更多同义表述，提升Siri的识别灵活性：

extension Direction: AppEnum{
    static var caseDisplayRepresentations: [Direction : DisplayRepresentation] = [
        .down: DisplayRepresentation(stringLiteral: "down"),
        .up: DisplayRepresentation(stringLiteral: "up"),
        .left: DisplayRepresentation(stringLiteral: "left, to the left"),
        .right: DisplayRepresentation(stringLiteral: "right, to the right"),
    ]
    
    // 其余代码保持不变
}

3. 重新训练Siri指令 #

修改代码后重新编译App，然后在「快捷指令」App中重新添加该Intent，或者直接对Siri说出完整指令（如"Move overlay to the left 10"），让Siri重新学习该句式的匹配逻辑。

关键逻辑说明 #

AppIntent的parameterSummary是定义Siri指令模板的核心，它告诉Siri完整指令的结构，从而实现一次性解析多个参数。同时Intent标题需要避免过于具体的参数化短语，否则会干扰Siri对完整句式的匹配。

内容的提问来源于stack exchange，提问作者user2485972