用途:本技能用于在 Codex 仓库中为操作系统路径选择合适的 Rust 类型,适用于定义新的承载路径的类型,或在明确要求时迁移现有类型。修改现有代码须经明确请求,并保持改动最小、与需求成比例。
主要规则:在 app-server 协议类型中,URI 迁移期间为向后兼容使用 LegacyAppPathString,在协议边界转换为 PathUri 并在内部使用 PathUri;本机逻辑(如部分配置值)改用 AbsolutePathBuf 或 PathBuf。exec-server 协议类型使用 PathUri,内部按需使用 PathUri 或 AbsolutePathBuf。两个服务器共享的依赖使用 PathUri,或拆分 API 以解耦用途。模型需生成的工具调用参数应以普通 String 反序列化,并配合功能专属的路径处理代码。
迁移要求:app-server 客户端仍收发旧的本机路径字符串;app-server 可保留并操作外部平台的路径 URI;exec-server API 使用 file:// URI;纯本地操作不得改变模型可见文本;模型工具参数可含任意操作系统的相对或绝对路径;路径推理需在相关环境上线前即可工作;URI 不能显式编码执行器的路径约定或操作系统;用户不得显式配置环境的 OS/路径约定;URI 暂不应存入 rollout、数据库或其他持久存储;路径转换错误对安全相关路径 fail-closed,对 UI/诊断 fail-open;优先在 PathUri 或 LegacyAppPathString 上添加小型聚焦方法,而非本地辅助函数;诊断中以 URI 形式表示 PathUri。
限制与容错:路径与 URI 之间的转换允许有一定信息损失,只要对真实用户行为正确;迁移到 URI 不应引入大量新失败模式,原本不会失败的位置若需报错应尽量减少。若难以满足这些规则,应询问用户如何处理。