.NET Interactive 魔法命令 API 重构解析

背景与动机

.NET Interactive 项目近期对其魔法命令（magic command）系统进行了重大重构。这一重构源于两个关键因素：首先，原先依赖的 System.CommandLine 库正在进行架构调整，部分功能将被移除；其次，.NET Interactive 自身的输入系统正在经历一系列改进，需要更灵活的语法支持。

魔法命令是 Jupyter 风格笔记本中的特殊指令，以 #! 开头，用于执行非代码操作或配置内核行为。此次重构旨在提供更简洁、更强大的 API，同时保持对现有用户脚本的向后兼容性。

核心变更点

参数模型简化

原先基于 POSIX 命令行概念的"选项"(options)和"参数"(arguments)现在统一为"参数"(parameters)概念。新的 KernelDirectiveParameter 类型取代了之前的区分设计，使 API 更加直观。

移除的特性

重构移除了以下不太常用或增加复杂度的功能：

• 不再支持多个未命名参数
• 移除了 Windows 风格的 / 参数前缀
• 仅保留空格分隔的参数语法
• 不再支持 POSIX 风格的选项捆绑
• 移除了最小出现次数的配置
• 不再支持魔法命令的内置帮助系统

新增功能

新系统引入了多项实用改进：

• 支持内联 JSON 作为参数值
• 允许 JSON 配置输入提示（如 @input）
• 直接在参数上指定类型提示
• 更精细的错误诊断标记
• 更丰富的自动完成支持

执行模型重构

从 Handler 到 KernelCommand

原先基于 System.CommandLine 的 Handler 机制被替换为更符合 .NET Interactive 整体架构的 KernelCommand 模型。魔法命令现在会被解析为特定的命令对象，通过标准的 Kernel.SendAsync 方法执行。

这种设计带来了额外优势：魔法命令和程序化 API 现在可以相互转换。例如，#r "nuget: Plotly.NET, 5.0.0" 现在对应一个 AddPackage 命令，可以直接通过代码发送。

JSON 序列化支持

新系统使用 System.Text.Json 来处理命令参数的序列化。开发者可以通过标准 JSON 属性来自定义反序列化行为，这比原先的定制绑定方案更加灵活和强大。

SubmitCode 参数支持

对于需要参数化的代码提交（如 T-SQL 和 KQL 内核），新增了 SubmitCode.Parameters 属性。这解决了原先必须通过魔法命令指定参数的局限，为未来 UI 集成提供了更好的基础。

开发者迁移指南

对于扩展开发者，迁移到新 API 主要涉及以下变化：

1. 使用 KernelActionDirective 替代原先的命令定义
2. 通过 KernelDirectiveParameter 配置参数
3. 定义自定义命令类型并实现处理逻辑
4. 利用 System.Text.Json 特性控制序列化行为

示例代码如下：

// 定义参数
var param = new KernelDirectiveParameter("name") 
{
    Description = "参数描述",
    Required = true
};

// 创建指令
var directive = new KernelActionDirective("#!demo") 
{
    Parameters = { param }
};

// 注册处理程序
kernel.AddDirective<DemoCommand>(
    directive,
    async (command, context) => 
    {
        // 处理逻辑
    });

总结

.NET Interactive 的魔法命令重构代表了该项目向更统一、更强大的架构演进的重要一步。通过简化概念模型、增强 JSON 支持、统一执行路径，新系统既降低了学习曲线，又提供了更丰富的功能扩展点。虽然带来了一些兼容性变化，但这些改进为未来的功能扩展奠定了更坚实的基础。

对于现有用户，大多数魔法命令语法仍然保持兼容；对于扩展开发者，新的 API 提供了更符合 .NET Interactive 整体架构的编程模型。这一变化是 .NET Interactive 成熟过程中的重要里程碑，将使其在交互式计算领域保持竞争力。