creatixchu
5245182db2
One list call now materializes at most maxEntries child rows (config, default 1000 - GitHub's web-UI directory-listing bound). Candidates sort before probing so a cut level keeps the name-sorted head and symlink probing stops with the bound, and DirectoryListing carries a required truncated flag on the seam and the wire so clients can state incompleteness instead of silently missing tail entries.
23 lines
2.9 KiB
Markdown
23 lines
2.9 KiB
Markdown
# @deepseek-ai/dsh-host-directory-picker-browse
|
||
|
||
[English](README.md) | 中文
|
||
|
||
[目录选择 seam](../directory-picker/README.md) 的**应用内浏览后端**：`BrowseDirectoryPicker` 以 `browse` 能力注册 `ctx.directoryPicker`——基于 Node 标准库（跨 OS 适配本就由它承担）提供单层目录列举与子目录创建。宿主屏幕上不渲染任何东西，因此该后端能服务 native 后端无法触及的远程客户端。
|
||
|
||
行为事实：列举**只返回目录**、按名称排序，指向目录的符号链接会被跟随（断链／循环链接被跳过——探测 `stat` 失败即"不可进入"），并携带宿主判定的 `hidden` 标志（POSIX 点前缀约定），展示决策留给客户端；`crumbs` 是从根到目标的祖先链，根 crumb 以完整路径标注（`/`、`C:\`）；`list` 不带路径即列举宿主账户的家目录。`createDirectory` 不递归（父目录缺失是真实失败，不是要补造的层级），且即便被直接调用也把名称校验为单个非空段，与协议 schema 的栅栏一致。两个原语都拒绝非完全限定的显式路径——相对形态，以及 Windows 上 `isAbsolute` 会放行的无盘符有根形态（`\foo`、`/foo`）与不完整的 UNC 前缀（`\\`、`\\server`）——报 `directory-unreadable`／`directory-create-failed`，而不是任由 `resolve` 把它重定位到宿主进程 cwd 或当前盘符之下。单次 `list` 至多物化 `maxEntries` 行（配置项，默认 1000——GitHub 网页端对目录列举采用的同一上限）：被截断的层级保留按名排序的头部、隐藏行计入上限、达到上限即停止探测，并报告 `truncated: true`，供客户端提示层级不完整。失败抛出 seam 的类型化 `DirectoryPickerError`。策略依据：[目录选择能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md)。
|
||
|
||
## 模型体验
|
||
|
||
无。该后端服务于 GUI 宿主的目录选择；这里没有任何内容进入模型请求。
|
||
|
||
#### KV 缓存影响
|
||
|
||
无；该包既不组装也不发送提供方请求。
|
||
|
||
## 已知限制与延期工作
|
||
|
||
- **尚无 client half**——消费这些原语的应用内浏览对话框在本栈的下一个 PR 落地；在那之前 `-browse` 组合会完全隐藏选目录入口（ui-workspace 文档化的空洞默认行为），列举／创建 RPC 无消费者。
|
||
- **不读取 Windows 隐藏属性**——Node 的 dirent 不暴露 `FILE_ATTRIBUTE_HIDDEN`，因此在所有平台上 `hidden` 都意味着点前缀，直到原生探测值回其成本为止。
|
||
- **不枚举盘符根**——Windows 上祖先链止于盘符根；跨盘依赖浏览器 UI 的路径输入入口，而不是这里的枚举原语。
|
||
- **全盘可浏览**——没有按部署限定的浏览根；`workspace.create` 今天就接受任意路径，这里的根只会是 UX 范围而非边界——等到有部署需要时再做。
|