path-types

路径类型

定义新类型时，请遵循此指南。仅在明确要求时更改现有代码，并确保修改尽可能精简且适度。将这些规则视为持续迁移的目标状态；如果难以遵守，请询问用户如何继续。

• 在 app-server 协议类型中，使用 LegacyAppPathString 在 URI 迁移期间保持向后兼容。在协议边界处，将其转换为 PathUri，并在内部使用 PathUri。对于主机本地逻辑（例如某些配置值），则使用 AbsolutePathBuf 或 PathBuf。
• 在 exec-server 协议类型中，使用 PathUri。在内部根据情况使用 PathUri 或 AbsolutePathBuf。
• 在两个服务共用的依赖中，使用 PathUri，或采用彼此解耦其使用场景的独立 API。
• 对于预期由模型生成的工具调用参数，应将其反序列化为常规 String，并使用特定于功能的路径处理代码。

迁移要求

迁移代码以符合上述指南时，请牢记以下要求：

• 现有 app-server 客户端继续发送和接收旧版原生路径字符串
• app-server 可以保留并操作外来平台的路径 URI
• exec-server API 使用 file:// URI
• 仅本地操作不得更改模型可见文本
• 模型工具参数可以包含任意操作系统的原始相对路径或绝对路径
• 相关环境启动前，路径推理也必须能够正常工作
• URI 无法明确编码执行器的路径约定或操作系统
• 用户不得显式配置环境的操作系统／路径约定
• URI 暂不应存储在 rollout、数据库或其他持久化存储中
• 路径转换错误：安全相关路径采用失败即关闭策略，UI／诊断则采用失败即开放策略
• 优先在 PathUri 或 LegacyAppPathString 上定义小而专注的方法，而不是使用本地辅助函数
• 在诊断信息中将 PathUri 值表示为 URI

只要能为真实用户正确处理，路径与 URI 之间的转换有一定信息损失也可以接受。

迁移到 URI 不应显著增加新的故障模式。某些先前不会失败的地方需要显示错误，但应尽可能减少此类情况。