description: "原生目录选择表面：驱动 Host 操作系统选择器的浏览器半部，用于工作区目录流程；供选择拾取交互的用户与维护者阅读。" kind: "package-reference"

@xfcodeai/dsh-client-ui-directory-picker-native

English | 中文

概述

本包提供 Web GUI 的原生目录拾取表面：当工作区流程请求一个目录时，一个无渲染的浏览器填充会在运行 Host 的机器上打开操作系统自带的选择器，并回报唯一结果——拾取的路径、取消或失败。它填充 ui-workspace 声明的两个目录流程 slot，用一行 cordis.yml 组合出原生拾取交互的客户端一侧。当浏览器与 Host 运行在同一台机器上时选择它；进程内与远程浏览器部署则需要 -browse 表面。

目录

• 使用本包
• 理解实现
• 进一步探索
• 模型体验
• 已知限制与延期工作
• 开发备注

使用本包

与 ui-workspace 及 Host 后端 dsh-host-directory-picker-native 一起挂载本插件；一行 cordis.yml 随即组合出完整的原生拾取交互。当工作区添加或选择器流程发起目录请求时，用户看到操作系统的文件夹对话框；拾取的路径被工作区流程采纳，取消则关闭对话框。

何时选择

当浏览器与 Host 运行在同一台机器上、操作系统对话框可以在那里打开时，选择此表面。当浏览器为远程或进程内、没有本地选择器时，选择 -browse 表面。两个表面填充相同的 slot，因此切换只是组合改动，而非代码改动。

理解实现

两个 slot 注册经嵌套的 ctx.slots.inject() 调用作为一个事务性 effect 安装，因为任一声明条目都可能晚些激活或替换其声明。填充在每个上升沿 open 时只武装一次，因此重渲染永远不会再拉起一个选择器；结算结果挂在 ref 上，让答复到达持有方最新的处理器。HMR（热模块替换）导致填充被替换时，卸载会整体丢弃结算：wire 没有按请求中止的机制，因此 Host 侧选择器会一直存活到被答复，而它的答复无处落地。node 半部是一个空 apply，让插件留在 Host 名单上。

进一步探索

当拾取面不够用时阅读以下页面。它们从浏览器半部进入 Host 后端与它所填充的 slot。

• dsh-host-directory-picker-native——本表面驱动的操作系统选择器后端。
• ui-workspace——声明目录流程 slot 并拥有拾取对话。
• ui-directory-picker-browse——面向远程与进程内部署的应用内浏览替代方案。
• Web 客户端架构——浏览器插件行如何加载并注册 slot。

模型体验

无，因为目录选择器属于浏览器界面；本包中的任何内容都不会进入模型请求。

KV Cache 影响

无；本包既不组装也不发送提供方请求。

已知限制与延期工作

这些限制界定了原生选择器的适用时机。它们是当前包约束，不是通用选择器对比或任务积压。

• 无法取消已打开的选择器——wire 没有按请求中止的机制，因此已显示在 Host 上的选择器无法从浏览器关闭；被丢弃的结算会被忽略。
• 仅限本地 Host 承载——操作系统对话框在运行 Host 的机器上打开，因此进程内与远程浏览器部署需要 -browse 组合。平台失败经由持有方的可重试文件夹对话框呈现。

开发备注

无。

运行时不变式： 不发布伴生入口。插件将一个无渲染 flow occupant 作为一个事务性 effect 注册到两个 workspace hole；HMR 安全性规范证明该 effect 的释放行为，并且插件在各次 pick 之间不保留状态。