Pkl-Gradle项目中包URI无法生成Pkldoc文档的问题分析

在Pkl-Gradle项目的最新开发中，开发者发现了一个关于pkldoc生成器无法处理package类型URI的回归问题。这个问题影响了开发者使用Gradle插件为Pkl包生成文档的能力。

问题现象

当开发者尝试使用pkldoc生成器为package类型的URI生成文档时，例如配置如下：

pkl {
  pkldocGenerators {
    register("pkldoc") {
      sourceModules = listOf(uri("package://pkg.pkl-lang.org/pkl-pantry/pkl.toml@1.0.0"))
    }
  }
}

构建过程会失败，并显示错误信息指出package URI语法无效。这实际上是一个误报，因为package URI本身是合法的Pkl语法。

问题根源

深入分析后发现，问题出在Gradle插件的隐式任务依赖机制上。当配置pkldoc生成器时，插件会自动创建一个名为<taskName>GetImports的隐式任务，该任务会尝试分析源模块的所有导入依赖。

对于package类型的URI，这种导入分析是不必要的，原因有二：

1. package资源通常不包含对本地文件的导入
2. Pkl的安全管理器默认会阻止package资源导入本地文件资源

临时解决方案

目前开发者可以采用以下临时解决方案：通过显式设置transitiveModules属性来禁用隐式的导入分析任务：

pkl {
  pkldocGenerators {
    register("pkldoc") {
      sourceModules = listOf(uri("package://pkg.pkl-lang.org/pkl-pantry/pkl.toml@1.0.0"))
      transitiveModules = files("some_file.txt")
    }
  }
}

这种方法虽然有效，但不够优雅，因为它强制开发者提供一个实际上不会被使用的文件引用。

预期修复方案

从技术实现角度看，更合理的修复方案是修改Gradle插件的行为，使其只对file:类型的URI执行导入分析。这种改进符合Pkl的安全模型设计，也能解决当前的问题而不需要开发者提供额外配置。

对开发者的建议

对于正在使用Pkl-Gradle插件的开发者，如果遇到类似问题，可以：

1. 采用上述临时解决方案继续开发
2. 关注项目更新，等待包含此修复的版本发布
3. 避免在开发中混合使用package URI和本地文件导入，这可能导致意外的安全限制问题

这个问题的出现也提醒我们，在开发工具链时需要考虑不同资源类型的特性和安全限制，确保工具行为与底层语言的设计哲学保持一致。