description: "面向 web GUI 宿主的工作区目录选择 seam：原生与浏览后端所实现的服务约定、能力词汇与错误码。" kind: "package-reference"

@xfcodeai/dsh-host-directory-picker

English | 中文

概述

web GUI 让操作者通过 OS 选择器或应用内浏览器选择工作区目录。操作者能接触宿主屏幕时使用原生选项；远程客户端或需要在应用内列举和创建目录时使用浏览选项。消费方会获得交互类型，并能呈现匹配的工作流。目录选择仅限 GUI 宿主，不会影响 agent loop（智能体循环）。浏览工作流一次只公开一棵目录树；不支持多根目录。

目录

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

使用本包

挂载且只挂载一个目录选择后端，然后让工作区流程驱动它：seam 本身只是服务约定，因此没有后端的组合就无从选择目录。

选择后端

当操作者坐在宿主屏幕前时，原生后端是正确选择：directoryPicker/pick 打开一个 OS 选择器，返回所选绝对路径，取消时返回 null。浏览后端处处可用——它在浏览器中列举一个目录层级并创建子目录，因此无法触达 OS 对话框的远程客户端依然能选择工作区。当宿主处境在两次启动之间变化时，组合自适应选择器，它在启动时判定一次处境并挂载匹配的后端。

能力约定

capability() 返回一个可辨识联合类型，说明操作者如何选择目录：OS 选择器为 { kind: 'native', pick(signal) }，应用内浏览器为 { kind: 'browse', list(path?), createDirectory(path, name) }。消费方按 kind 分支；遇到未知能力类型时，界面会隐藏选择入口，而不是失败。浏览失败抛出带类型的 DirectoryPickerError，其错误码集合是封闭的——directory-unreadable、directory-exists 或 directory-create-failed——每个都携带出错对象的路径，目录选择 Remote 控制器将其 1:1 映射为协议错误码。

行携带什么

DirectoryEntry 行暴露绝对 path 与宿主判定的 hidden 标志（POSIX 上为点前缀约定），展示策略留在客户端；客户端绝不自行拼接路径段。DirectoryListing.crumbs 是从文件系统根到被列举目录的祖先链——每个 crumb 都是跳转目标，根 crumb 以完整路径标注。

理解实现

设计理念

该 seam 建立在一个分离之上：后端提供的交互形态是约定，而不是实现细节。DirectoryPicker 是只有一个 capability() 方法的抽象 Cordis 服务；后端子类以 ctx.directoryPicker 注册，加载第二个实现会抛出标准的重复服务错误。能力对象在服务生命周期内必须保持稳定，因为消费方可能跨调用持有它。

可合并扩展的词汇

DirectoryPickerCapabilities 是以能力类型为键的可合并扩展映射，DirectoryPickerCapability 从它派生联合类型。新后端通过声明合并将其形态加入此映射（条目的 kind 字面量必须等于其键），而无需改动本包。每个后端包还随附一个 browser 入口，在 ui-workspace 的 directory-flow slot 中注册匹配的交互，因此一行组合配置同时选择宿主能力与客户端流程。

源码地图

| 文件 | 职责 | |---|---| | src/index.ts | Service Definition：抽象 DirectoryPicker、能力词汇、类型化错误、Context 合并 |

失败词汇

DirectoryPickerError 携带封闭的 DirectoryPickerErrorCode 加出错对象的绝对路径，消费方无需字符串匹配即可映射业务错误码。设计依据、与 ctx.fs 的切分与策略裁决见 seam Agent Note。

进一步探索

当 seam 约定不够用时阅读以下内容：先看决策记录，再看组合它的两个后端与自适应选择器。

• 目录选择能力 seam 决策——设计依据、ctx.fs 切分与策略裁决。
• 原生后端——OS 选择器交互及其平台工具。
• 浏览后端——面向远程客户端的应用内列举与创建交互。
• 自适应选择器——两个后端之间的启动时判定。
• 工作区子系统——接收所选目录的工作区记录。

模型体验

无。GUI 宿主的目录选择 seam 不注册任何面向模型的内容。

KV Cache 影响

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

已知限制与延期工作

这些限制说明 seam 约定何时把决定留给未来的消费方。它们是当前包约束，不是任务积压。

• 不支持多根目录——浏览约定每次列举只公开一条祖先链；按部署限定浏览根（以及在盘符根的上一级枚举 Windows 各盘符根目录）等到出现需要它的消费方再做，见 DirectoryPicker Agent Note。

开发备注

无。

运行时不变式： 不发布伴生入口。这个无状态 Service Definition 只定义 capability vocabulary，观察由 backend 与 Remote controller 负责。