path-types

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Path Types

路径类型

Apply this guidance when defining new types. Change existing code only when explicitly requested, and keep edits minimal and proportional. Treat these rules as the target state of an ongoing migration; if compliance is difficult, ask the user how to proceed.

In app-server protocol types, use
```
LegacyAppPathString
```
for backwards compatibility during the URI migration. At the protocol boundary, convert it to
```
PathUri
```
and use
```
PathUri
```
internally. For host-local logic, such as some config values, use
```
AbsolutePathBuf
```
or
```
PathBuf
```
instead.
In exec-server protocol types, use
```
PathUri
```
. Internally, use
```
PathUri
```
or
```
AbsolutePathBuf
```
as appropriate.
In dependencies shared by both servers, use
```
PathUri
```
or separate APIs that decouple their use cases.
Tool call arguments that the model is expected to generate should be deserialized as regular
```
String
```
s with feature-specific path handling code.

定义新类型时遵循本指南。仅在明确要求时修改现有代码，且修改应保持最小范围、与需求相称。将这些规则视为持续迁移的目标状态；如果难以合规，请询问用户如何处理。

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

Migration requirements

迁移要求

Keep these requirements in mind while migrating code to conform with the above guidelines:

existing app-server clients keep sending and receiving legacy native-path strings
app-server can retain and manipulate foreign-platform path URIs
exec-server APIs use file:// URIs
local-only operation must not change model-visible text
model tool arguments may contain raw relative or absolute paths for any OS
path reasoning must work before the related environment has come online
URIs cannot explicitly encode the executor’s path convention or operating system
users must not configure the environment’s OS/path convention explicitly
URIs should not yet be stored in rollouts, databases, or other persistent storage
path conversion errors: fail-closed for security-relevant paths, fail-open for UI/diagnostics
prefer small focused methods on
```
PathUri
```
or
```
LegacyAppPathString
```
over local helpers
represent
```
PathUri
```
values as URIs in diagnostics

It is OK if the conversion between paths and URIs is somewhat lossy as long as it will do the right thing for real users.

Migrating to URIs should not add significant new failure modes. We will need to surface errors in some places that were previously infallible but it should be kept to a minimum.

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

现有 app-server 客户端继续发送和接收传统的原生路径字符串
app-server 可保留和操作跨平台路径 URI
exec-server API 使用 file:// 格式的 URI
仅本地运行的操作不得修改模型可见的文本
模型工具参数可能包含适用于任意操作系统的原始相对或绝对路径
路径推理必须在相关环境上线前即可正常工作
URI 不得显式编码执行器的路径约定或操作系统信息
用户不得显式配置环境的操作系统/路径约定
URI 暂不应存储在发布版本、数据库或其他持久化存储中
路径转换错误处理：与安全相关的路径采用故障关闭策略，UI/诊断相关路径采用故障开放策略
优先为
```
PathUri
```
或
```
LegacyAppPathString
```
编写小型、聚焦的方法，而非使用本地辅助函数
在诊断信息中以 URI 格式展示
```
PathUri
```
值

路径与 URI 之间的转换存在一定信息损耗是可接受的，只要对真实用户而言功能正常即可。

迁移到 URI 不应引入大量新的故障模式。我们需要在一些之前不会出错的位置暴露错误，但应将其控制在最低限度。