@modesto_ma/dsh-channels 0.1.0 → 0.3.0

package/src/settings/contract.ts

@@ -12,10 +12,15 @@ export const STATUS_ROUTE = '/dsh-channels/status'
 export const PANEL_ROUTE = '/dsh-channels/panel'
 export const CONFIG_ROUTE = '/dsh-channels/config'
 export const CREDENTIALS_ROUTE = '/dsh-channels/credentials'
+/**
+ * Connection lifecycle action (POST). While the channel runs it restarts the
+ * long connection; while it is stopped it opens one — so the panel has exactly
+ * one "connect / reconnect" button. Credentials are resolved again either way.
+ */
 export const RECONNECT_ROUTE = '/dsh-channels/reconnect'
 /** 模型/推理档位/预设选择器的宿主目录（provider → model → effort 级联刷新）。 */
 export const CATALOG_ROUTE = '/dsh-channels/catalog'
-/** 手动执行一次过期工作区清理（POST，无请求体）。 */
+/** 手动执行一次过期目录清理（POST，无请求体）。 */
 export const CLEANUP_ROUTE = '/dsh-channels/cleanup'
 /** 访问与授权只读快照（GET/HEAD）：准入模式、管理员、群/用户白名单、待处理申请。 */
 export const ACCESS_ROUTE = '/dsh-channels/access'
@@ -25,6 +30,14 @@ export const ACCESS_GROUPS_ROUTE = '/dsh-channels/access/groups'
 export const ACCESS_USERS_ROUTE = '/dsh-channels/access/users'
 /** 结算一条待处理授权申请（POST，body `{ token, decision }`）。 */
 export const ACCESS_REQUESTS_ROUTE = '/dsh-channels/access/requests'
+/**
+ * 打开宿主机的系统目录选择框（POST，无请求体），返回绝对路径。
+ *
+ * 只有宿主挂载了 `directoryPicker` 的 native 后端（桌面/本地 GUI 会话）才
+ * 会注册实际选择逻辑；远程/无头会话的 browse 后端不可用，面板不下发
+ * [`EditableFieldWire.browse`]，保留手写输入。
+ */
+export const PICK_DIRECTORY_ROUTE = '/dsh-channels/pick-directory'
 
 /**
  * 可由 Web 面板覆盖的配置项。全部是 `src/config.ts` 里已存在的字段；
@@ -36,7 +49,7 @@ export const ACCESS_REQUESTS_ROUTE = '/dsh-channels/access/requests'
  * 因此不会落进覆盖层文件。
  *
  * `baseDir`（工作区根目录 = 模型/工具产生文件的落点）可覆盖，但面板只接受
- * **绝对路径**（`~` 会展开）；已有 Session / 工作区不迁移，只影响之后新建的
+ * **绝对路径**（`~` 会展开）；已有 Session / 目录不迁移，只影响之后新建的
  * 会话。校验与保存时建目录见 `src/workspaces.ts`。
  */
 export const EDITABLE_KEYS = [
@@ -86,8 +99,12 @@ export type RestartKey = (typeof RESTART_KEYS)[number]
 /** Render kinds the generic panel form understands. */
 export type FieldKind = 'boolean' | 'number' | 'text' | 'select'
 
-/** Field groups map one-to-one onto panel cards. */
-export type FieldGroup = 'workspace' | 'behavior' | 'content' | 'model' | 'streaming'
+/**
+ * Field groups partition the editable form. Each group is rendered inside one
+ * panel tab (see {@link TAB_FIELD_GROUPS}); the Host is the source of truth for
+ * which key belongs to which group.
+ */
+export type FieldGroup = 'workspace' | 'behavior' | 'content' | 'model' | 'streaming' | 'access'
 
 /** One selectable value rendered by the generic form. */
 export interface FieldOptionWire {
@@ -111,6 +128,12 @@ export interface EditableFieldWire {
   placeholder?: string
   /** Render across the whole form width (long paths). */
   wide?: boolean
+  /**
+   * `directory`：给这个 text 字段加一个「选择目录…」按钮，点击后由 Host
+   * 打开宿主机系统目录选择框并把绝对路径写回草稿。仅当宿主提供 native
+   * 目录选择器时下发；缺省（含 browse 后端）保持纯手写输入。
+   */
+  browse?: 'directory'
   /** 保存后需重连飞书通道才生效。 */
   restartRequired: boolean
 }
@@ -178,9 +201,36 @@ export interface ConnectionWire {
   reconnectAttempts: number
 }
 
+/**
+ * The panel-facing lifecycle phase, derived by the Host from configuration
+ * readiness and runtime state. Enabling the plugin starts in `unconfigured`
+ * (or `idle` when credentials already resolve) and never forces a connection
+ * before the Feishu application credentials are complete.
+ */
+export type ChannelPhaseWire =
+  /** Credentials are incomplete: the plugin is loaded but deliberately not connected. */
+  | 'unconfigured'
+  /** Credentials are complete, no connection is open yet. */
+  | 'idle'
+  /** A connection attempt / reconnect is in flight. */
+  | 'connecting'
+  /** The Feishu long connection is open. */
+  | 'connected'
+  /** The last connection attempt failed; the reason is in `lastStartError`. */
+  | 'error'
+
 /** Runtime connection/liveness facts. */
 export interface ChannelStatusWire {
   running: boolean
+  /**
+   * Whether the Feishu application credentials are complete. When false the
+   * plugin stays loaded (settings panel usable) but opens no long connection.
+   */
+  configured: boolean
+  /** Display phase derived from `configured` / `running` / `lastStartError`. */
+  phase: ChannelPhaseWire
+  /** Human-readable config items that are still missing (names only, never values). */
+  missingConfig: string[]
   level: 'healthy' | 'degraded' | 'unhealthy'
   startedAt?: number
   uptimeMs?: number
@@ -189,7 +239,7 @@ export interface ChannelStatusWire {
   routeCount: number
   liveAgentCount: number
   inflightTurnCount: number
-  /** 最近一次启动失败的原因（成功后清空）。 */
+  /** 最近一次连接失败的原因（成功后清空）。 */
   lastStartError?: string
   /** 健康判定的原因说明（空数组 = 健康）；由 Host 的 health 折叠给出。 */
   reasons: string[]
@@ -197,7 +247,7 @@ export interface ChannelStatusWire {
   version: string
   /** Web 覆盖文件绝对路径（用户可直接编辑）。 */
   overlayPath: string
-  /** 正在重连时为 true，此时面板按钮禁用。 */
+  /** 正在连接或重连时为 true，此时面板的写操作按钮禁用。 */
   busy: boolean
 }
 
@@ -274,6 +324,12 @@ export interface AccessWire {
     /** false while guarded mode would refuse every conversation (fail closed). */
     configured: boolean
   }
+  /**
+   * Whether the persisted whitelists were loaded. While the channel holds no
+   * connection the plugin storage domain is closed, so the lists are unknown
+   * (not empty) and the panel must not offer mutations.
+   */
+  loaded: boolean
   groups: AccessGroupWire[]
   users: AccessUserWire[]
   requests: AccessRequestWire[]
@@ -305,9 +361,9 @@ export interface CleanupPreviewWire {
   thresholdMs?: number
   /** Periodic cleanup runs at startup and once per day. */
   auto: boolean
-  /** Plugin-created workspaces under the current baseDir. */
+  /** Plugin-created workspaces under the current baseDir (user projects). */
   workspaces: number
-  /** Workspaces older than the threshold (the deletable set). */
+  /** Directories older than the threshold (legacy topic workspaces + per-topic dirs). */
   candidates: number
   /** Total bytes currently occupied by the candidates. */
   candidateBytes: number
@@ -319,9 +375,11 @@ export interface CleanupPreviewWire {
 export interface CleanupRunWire {
   ok: boolean
   deletedWorkspaces: number
+  /** Per-topic working directories removed (current layout). */
+  deletedSessionDirs: number
   retiredRoutes: number
   freedBytes: number
-  /** One `path: message` line per workspace that could not be deleted. */
+  /** One `path: message` line per directory that could not be deleted. */
   failures: string[]
   error?: string
 }
@@ -331,6 +389,16 @@ export type CleanupResponse =
   | { ok: true; panel: PanelWire; result: CleanupRunWire }
   | { ok: false; error: string }
 
+/**
+ * `POST /dsh-channels/pick-directory` response. `canceled` is a normal
+ * outcome (the operator dismissed the OS dialog), not an error; `path` is an
+ * absolute directory the Host's native chooser returned.
+ */
+export type PickDirectoryResponse =
+  | { ok: true; path: string }
+  | { ok: true; canceled: true }
+  | { ok: false; error: string }
+
 /** `PUT /dsh-channels/config` body. */
 export interface SaveConfigRequest {
   values: EditableValues
@@ -350,7 +418,8 @@ export type SaveConfigResponse =
 /** `POST /dsh-channels/reconnect` response. */
 export type ReconnectResponse =
   | { ok: true; panel: PanelWire }
-  | { ok: false; error: string }
+  /** `unconfigured` tells the panel to route the user to the credentials form. */
+  | { ok: false; error: string; unconfigured?: boolean }
 
 /** `DELETE /dsh-channels/config` response. */
 export type ClearConfigResponse =
@@ -368,8 +437,19 @@ export interface ClearCredentialRequest {
   field: CredentialField
 }
 
-/** How a saved credential reached the running channel. */
-export type CredentialReconnectState = 'auto' | 'pending' | 'not-needed'
+/**
+ * How a saved credential reached the running channel.
+ *
+ * - `auto`: the channel was stopped and connected immediately after the save.
+ * - `pending`: the channel is running; reconnect for the value to take effect.
+ * - `not-needed`: removed while stopped, nothing to reconnect.
+ * - `unconfigured`: saved, but the other credential of the pair is still
+ *   missing — the plugin keeps waiting (no connection attempt) until it is
+ *   configured.
+ * - `failed`: the pair is complete and a connection was attempted, but it
+ *   failed; the value is stored and `autoReconnectError` explains why.
+ */
+export type CredentialReconnectState = 'auto' | 'pending' | 'not-needed' | 'unconfigured' | 'failed'
 
 export interface CredentialsSavedPayload {
   panel: PanelWire
@@ -387,25 +467,97 @@ export type ClearCredentialResponse =
   | ({ ok: true } & CredentialsSavedPayload)
   | { ok: false; error: string; issues?: FieldIssueWire[] }
 
+/**
+ * Top-level panel tabs, in render order. The panel shows the connection state
+ * header above every tab, so switching tabs never hides whether the bridge is
+ * connected.
+ */
+export const PANEL_TABS = [
+  { id: 'connection', label: '连接' },
+  { id: 'sessions', label: '会话与行为' },
+  { id: 'model', label: '模型' },
+  { id: 'workspace', label: '工作区' },
+  { id: 'access', label: '访问授权' },
+  { id: 'advanced', label: '高级' },
+] as const
+
+export type PanelTabId = (typeof PANEL_TABS)[number]['id']
+
+/** Which editable field groups each tab renders (the tabs own one or two). */
+export const TAB_FIELD_GROUPS: Readonly<Record<PanelTabId, readonly FieldGroup[]>> = {
+  connection: [],
+  sessions: ['behavior', 'content'],
+  model: ['model'],
+  workspace: ['workspace'],
+  access: ['access'],
+  advanced: ['streaming'],
+}
+
+/** Section heading for one field group inside its tab. */
+export const FIELD_GROUP_LABELS: Readonly<Record<FieldGroup, string>> = {
+  workspace: '工作区与文件',
+  behavior: '行为',
+  content: '内容与附件',
+  model: '模型与推理',
+  streaming: '流式卡片与日志',
+  access: '准入与授权',
+}
+
 /** Display labels for the panel header/cards (kept on the wire so the client owns no copy). */
 export const PANEL_COPY = {
   title: '飞书渠道',
-  description: '飞书长连接状态、应用凭据与常用配置。凭据写入 DSH 凭据库且不回显；标注「需重连」的项需重启飞书连接生效。',
+  description: '飞书长连接、应用凭据与渠道配置。凭据只写入 DSH 凭据库且不回显；标注「需重连」的项在连接建立时读取。',
+  // ---- lifecycle / status -------------------------------------------------
   statusCard: '连接状态',
+  phaseUnconfigured: '待配置',
+  phaseIdle: '未连接',
+  phaseConnecting: '连接中',
+  phaseConnected: '已连接',
+  phaseError: '连接失败',
+  configuredBadge: '凭据已配置',
+  unconfiguredBadge: '凭据未配置',
+  statusSummaryConnected: '飞书长连接已建立，机器人可以收发消息。',
+  statusSummaryUnconfigured: '尚未配置飞书应用凭据：插件已加载，但不会连接飞书。填写凭据并保存后会自动连接。',
+  statusSummaryIdle: '飞书应用凭据已就绪，但当前没有建立长连接。',
+  statusSummaryConnecting: '正在连接飞书长连接…',
+  statusSummaryError: '最近一次连接飞书失败，请检查凭据与网络后重试。',
+  lastError: '最近一次连接失败',
+  missingConfig: '缺少配置',
+  statusHintUnconfigured: '配置完成后插件会自动连接；也可以稍后在本页手动连接。',
+  connectionInfo: '连接信息',
+  connectionStateLabel: '飞书长连接',
+  botOpenId: 'Bot open_id',
+  uptime: '运行时长',
+  routeCount: '话题路由',
+  liveAgentCount: '活动会话',
+  inflightTurnCount: '在途回复',
+  healthReasons: '健康判定',
+  unknownValue: '—',
+  connect: '连接飞书',
+  connecting: '连接中…',
+  // ---- onboarding ---------------------------------------------------------
+  onboardingTitle: '开始使用飞书渠道',
+  onboardingIntro: '只需三步：在飞书开放平台创建自建应用，把 App ID / App Secret 填入本页，保存后自动连接。',
+  onboardingStep1Title: '创建飞书自建应用',
+  onboardingStep1Text: '在飞书开放平台创建企业自建应用，开启机器人能力；事件订阅选择「长连接」，订阅 im.message.receive_v1（接收消息）。',
+  onboardingStep2Title: '填写应用凭据',
+  onboardingStep2Text: '把应用的 App ID（cli_ 开头）与 App Secret 填入下方「飞书应用凭据」，值会写入 DSH 凭据库。',
+  onboardingStep3Title: '保存并等待连接',
+  onboardingStep3Text: '两项凭据都保存后插件会自动连接；状态变为「已连接」即可在飞书里私聊机器人。',
+  onboardingDocsHint: '开放平台地址：open.feishu.cn/app；应用需要开通 im:message、im:message:send_as_bot 等消息权限。',
+  // ---- credentials --------------------------------------------------------
   credentialsCard: '飞书应用凭据',
-  modelCard: '模型与推理',
-  modelCardHelp: '模型服务商、模型 id、推理档位与新会话的 Agent 预设。下拉选项来自宿主机实时目录；保存后对新会话生效。',
-  configCard: '常用配置',
-  advancedCard: '只读与高级信息',
+  credentialsCardHelp: '凭据值经 DSH 凭据服务写入本机凭据库；面板只显示「已配置 / 未配置」，永不回显已存值。两项都配置后才会连接飞书。',
   appIdLabel: '飞书 App ID',
   appSecretLabel: '飞书 App Secret',
-  credentialsHelp: '值通过 DSH 凭据服务写入本机凭据库；面板只显示是否已配置，永不回显已存值。留空表示保持当前值。',
   credentialsRef: '凭据引用',
   saveCredentials: '保存凭据',
   savingCredentials: '保存中…',
   credentialSaved: '凭据已保存',
-  credentialSavedReconnected: '凭据已保存，已自动重连飞书通道',
+  credentialSavedReconnected: '凭据已保存，飞书已连接',
   credentialSavedPending: '凭据已保存，重启飞书连接后生效',
+  credentialSavedUnconfigured: '凭据已保存；还缺少另一项凭据，补齐后会自动连接',
+  credentialAutoConnectFailed: '凭据已保存，但自动连接失败',
   credentialRemoved: '已移除存储的凭据',
   credentialRemovedPending: '已移除存储的凭据，重启飞书连接后生效',
   removeCredential: '移除已存值',
@@ -415,40 +567,65 @@ export const PANEL_COPY = {
   credentialReadOnly: '当前凭据存储不可写',
   appIdPlaceholder: '输入 App ID（cli_…）',
   appSecretPlaceholder: '输入 App Secret',
-  save: '保存配置',
-  saveAll: '保存全部配置',
-  saveModel: '保存模型配置',
-  modelActionsHint: '只保存模型与推理字段',
+  credentialsPendingHint: '填写后点「保存凭据」；两项齐全时插件会自动连接飞书。',
+  // ---- tabs / forms -------------------------------------------------------
+  connectionTabHelp: '连接状态与飞书应用凭据。凭据不完整时不会连接飞书。',
+  sessionsTabHelp: '私聊、群聊触发方式与入站内容；「需重连」项在下次连接时读取。',
+  modelTabHelp: '飞书会话使用的模型服务商、模型、推理档位与 Agent 预设；下拉选项来自宿主机实时目录，保存后对新会话生效。',
+  workspaceTabHelp: '每个用户一个工作区（模型/工具产生文件的落点），每个话题在其中拥有独立工作目录；只影响之后新建的话题。',
+  accessTabHelp: '准入采用 fail-closed：管理员不受白名单限制，非管理员私聊会被拒绝，群聊需要「群已授权 + 用户在白名单」两层同时命中。',
+  advancedTabHelp: '流式刷新等低层参数、Web 覆盖文件与只读信息。',
+  save: '保存更改',
   saving: '保存中…',
+  saveHintDirty: '只保存改动过的字段；标注「需重连」的项在下次连接时生效。',
+  discardTab: '放弃本页更改',
+  saveHintClean: '没有未保存的更改。',
+  dirtyCount: '未保存项',
+  browseDirectory: '选择目录…',
+  browsingDirectory: '选择中…',
+  directoryPicked: '已选择目录',
+  directoryPickFailed: '无法打开系统目录选择器',
+  saved: '已保存',
+  cleared: '已清除 Web 覆盖，恢复为 profile 配置',
   clear: '清除 Web 覆盖',
   clearing: '清除中…',
+  noOverrides: '当前没有 Web 覆盖',
+  overridden: 'Web 覆盖',
+  inherited: '继承 profile',
+  restartTag: '需重连',
+  restartBanner: '以下配置需重启飞书连接后生效：',
+  restartWarning: '重启会断开当前飞书长连接并中断进行中的回复，请确认空闲时操作。',
   reconnect: '重启飞书连接',
   reconnecting: '重连中…',
   refresh: '刷新状态',
   retry: '重试',
+  pollFailed: '状态刷新失败',
+  connectDone: '已连接飞书',
+  reconnectDone: '已重启飞书连接',
+  saveInvalid: '请先修正标红的配置项',
+  enabled: '已启用',
+  disabled: '已关闭',
+  credentialRemoveConfirm: '确定移除已存储的凭据值？移除后不会回显，需要时须重新填写。',
+  accessNotLoaded: '飞书连接建立后加载授权列表',
   loading: '加载中…',
   loadFailed: '设置面板加载失败',
-  saved: '已保存',
-  savedModel: '模型配置已保存',
-  cleared: '已清除 Web 覆盖，恢复为 profile 配置',
   catalogFailed: '模型目录加载失败，已退回手填。',
   catalogLoading: '正在读取宿主机选项…',
   catalogUnavailable: '宿主机未提供可选项，请手填。',
-  noOverrides: '当前没有 Web 覆盖',
-  overridden: 'Web 覆盖',
-  inherited: '继承 profile',
-  restartTag: '需重连',
-  restartBanner: '以下配置需重启飞书连接后生效：',
-  restartWarning: '重启会断开当前飞书长连接并中断进行中的回复，请确认空闲时操作。',
-  lastError: '最近一次启动失败',
-  notRunning: '未运行',
   version: '插件版本',
   overlayPath: '覆盖文件',
-  cleanupCard: '工作区清理',
-  cleanupCardHelp: '删除超过保留期且不再活跃的飞书工作区目录；只会删除本插件在「工作区根目录」下创建的目录，DSH 会话日志不删除。删除不可恢复：相关旧话题会失效并提示已过期，工作区列表记录同步移除。',
+  overlayPathHelp: '可以直接编辑该 JSON 文件；面板保存会整体重写它，「清除 Web 覆盖」会删除它并回落到 profile 配置。',
+  advancedCard: '只读与高级信息',
+  advancedHelp: '这些值来自 profile 配置，不能在面板里编辑。',
+  readOnlyCard: '部署级参数',
+  // ---- model --------------------------------------------------------------
+  // ---- cleanup ------------------------------------------------------------
+  cleanupCard: '目录清理',
+  cleanupCardHelp: '删除超过保留期且不再活跃的飞书话题目录（以及旧版本按话题建立的工作区目录）；用户工作区本身、DSH 会话日志都不会删除。删除不可恢复：相关旧话题会失效并提示已过期。',
   cleanupRetention: '保留期',
   cleanupAutoLabel: '自动清理',
-  cleanupCandidates: '可清理工作区',
+  cleanupCandidates: '可清理目录',
+  cleanupWorkspaces: '插件工作区',
   cleanupCandidateBytes: '预计释放空间',
   cleanupRetentionOff: '关闭（不删除）',
   cleanupAutoOn: '已开启（启动时 + 每天一次）',
@@ -456,24 +633,23 @@ export const PANEL_COPY = {
   cleanupAutoInactive: '未执行（保留期为关闭）',
   cleanupNow: '立即清理',
   cleanupRunning: '清理中…',
-  cleanupConfirm: '确定清理过期工作区吗？该操作不可恢复，会删除这些工作区内的全部文件（包括 attachments/ 附件）。',
-  cleanupConfirmHint: '删除前会再次确认；保留期为「关闭」或没有过期工作区时按钮不可用。',
-  cleanupDisabledOff: '保留策略为「关闭」：请先在「常用配置 → 工作区与文件」中选择保留天数。',
-  cleanupDisabledEmpty: '没有超过保留期的过期工作区。',
+  cleanupConfirm: '确定清理过期目录吗？该操作不可恢复，会删除这些目录内的全部文件（包括 attachments/ 附件）。',
+  cleanupConfirmHint: '删除前会再次确认；保留期为「关闭」或没有过期目录时按钮不可用。',
+  cleanupDisabledOff: '保留策略为「关闭」：请先在上方「过期目录保留期」中选择保留天数。',
+  cleanupDisabledEmpty: '没有超过保留期的过期目录。',
   cleanupPreviewFailed: '无法读取清理预览',
   cleanupDone: '清理完成',
   cleanupFailed: '清理失败',
   cleanupDeleted: '已删除工作区',
+  cleanupDeletedDirs: '话题目录',
   cleanupRetired: '已清理话题路由',
   cleanupFreed: '释放空间',
-  cleanupFailures: '以下工作区未能删除：',
+  cleanupFailures: '以下目录未能删除：',
+  // ---- access -------------------------------------------------------------
   accessCard: '访问与授权',
-  accessCardHelp: '准入采用 fail-closed：管理员不受白名单限制（私聊、任意群聊都可直接对话）；非管理员私聊会被拒绝，群聊需要「群已授权 + 用户在白名单」两层同时命中。管理员 open_id 在「常用配置 → 行为」中填写，私聊机器人发送 /userid 获取。',
+  accessCardHelp: '准入采用 fail-closed：管理员不受白名单限制（私聊、任意群聊都可直接对话）；非管理员私聊会被拒绝，群聊需要「群已授权 + 用户在白名单」两层同时命中。管理员与准入模式在上方「准入与授权」中编辑；私聊机器人发送 /userid 获取自己的 open_id。',
   accessModeOpenWarning: '当前准入模式为开放（open）：应用可用范围内的任何人都能开启对话。该模式不安全，仅建议调试时使用。',
-  accessAdminMissingWarning: '当前准入=guarded 但未配置管理员，所有对话都会被拒绝。请先在「常用配置 → 行为 → 管理员 open_id」填写。',
-  accessAdminLabel: '管理员',
-  accessAdminMissing: '未配置',
-  accessAdminHint: '修改管理员请到「常用配置 → 行为 → 管理员 open_id」；私聊机器人发送 /userid 可查看自己的 open_id（ou_ 开头，不是 user_id/邮箱）。',
+  accessAdminMissingWarning: '当前准入=guarded 但未配置管理员，所有对话都会被拒绝。请在上方「准入与授权」填写管理员 open_id。',
   accessGroupsTitle: '已授权群',
   accessGroupsEmpty: '尚未授权任何群。机器人被拉进群后，管理员会收到带 chat_id 的群信息卡；也可在群内发送 /groupid 获取。',
   accessUsersTitle: '已授权用户',

package/src/settings/directory-picker.ts

@@ -0,0 +1,121 @@
+/**
+ * 系统目录选择器的 Host 适配层：把宿主可选的 `directoryPicker` 服务折叠成
+ * 设置面板的最小 picker。
+ *
+ * 宿主的目录选择 seam 有两种后端（`native` / `browse`，见
+ * `@deepseek-ai/dsh-host-directory-picker-auto` 的启动判定）：
+ *
+ * - `native`：桌面/本地 GUI 会话，`pick(signal)` 打开操作系统的目录选择框；
+ *   面板据此给「工作区根目录」加「选择目录…」按钮。
+ * - `browse`：远程/无头/SSH 会话，没有可服务的显示会话，只能由前端自绘
+ *   目录浏览器；本插件不实现那套 UI，`browse` 后端按“不可用”处理，字段
+ *   保持手写输入。
+ *
+ * 与 `src/host/` 的其余桥接一致：这里只声明消费到的结构类型，不 import
+ * 任何 DSH 内部包，因此宿主缺该服务（旧版本/无 GUI）时插件照常加载。
+ *
+ * @module dsh-channels/settings/directory-picker
+ */
+
+import type { HostContext } from '../dsh-types.ts'
+
+/** 宿主 native 能力的最小结构副本（`kind` + `pick`，其余字段不关心）。 */
+export interface NativeDirectoryPickerCapability {
+  kind: 'native'
+  /**
+   * 打开系统目录选择框。
+   * @param signal - 调用方生命周期；中止会关闭选择框。
+   * @returns 绝对路径；操作者取消时为 `null`。
+   */
+  pick(signal: AbortSignal): Promise<string | null>
+}
+
+/** 宿主能力联合的保守副本：只识别 `native`，其余后端一律视为不可用。 */
+export type HostDirectoryPickerCapability =
+  | NativeDirectoryPickerCapability
+  | { kind: string; [key: string]: unknown }
+
+/** `ctx.directoryPicker` 的结构副本（抽象服务，只有一个 `capability()`）。 */
+export interface HostDirectoryPickerService {
+  capability(): HostDirectoryPickerCapability
+}
+
+/** 设置面板消费的最小 picker（surface / routes 只依赖这个接口，便于单测）。 */
+export interface SettingsDirectoryPicker {
+  /** 宿主是否提供可用的系统目录选择框。 */
+  readonly available: boolean
+  /**
+   * 打开系统目录选择框；同一 picker 同时只允许一个选择框。
+   * @param signal - 调用方生命周期；中止会关闭选择框。
+   * @returns 绝对路径；操作者取消时为 `null`。
+   */
+  pick(signal: AbortSignal): Promise<string | null>
+}
+
+/** 取出 native 能力；服务缺失、后端为 browse 或 capability 抛错都返回 undefined。 */
+function nativeCapability(
+  service: HostDirectoryPickerService | undefined,
+): NativeDirectoryPickerCapability | undefined {
+  if (service === undefined || typeof service.capability !== 'function') return undefined
+  let capability: unknown
+  try {
+    capability = service.capability()
+  } catch {
+    // A broken picker seam must not break the settings panel: fall back to text.
+    return undefined
+  }
+  if (typeof capability !== 'object' || capability === null) return undefined
+  const record = capability as { kind?: unknown; pick?: unknown }
+  if (record.kind !== 'native' || typeof record.pick !== 'function') return undefined
+  return capability as NativeDirectoryPickerCapability
+}
+
+/**
+ * 从宿主上下文取出可用的系统目录选择器。
+ *
+ * 解析是**惰性**的：插件可能先于 `dsh-web-app` 的 directory-picker 行完成
+ * apply，而设置面板只会在宿主全部加载完成后被请求。因此 `available` 与
+ * `pick()` 每次都按需解析（成功结果缓存；失败不缓存，晚挂载的服务仍能被
+ * 发现），避免把加载时序固化成「永远没有按钮」。
+ *
+ * @param ctx - 宿主上下文；`ctx.get('directoryPicker')` 是可选服务。
+ * @returns picker；`available` 为 false 时面板保留手写输入。
+ */
+export function createSettingsDirectoryPicker(ctx: HostContext): SettingsDirectoryPicker {
+  let resolved: NativeDirectoryPickerCapability | undefined
+  const resolve = (): NativeDirectoryPickerCapability | undefined => {
+    if (resolved !== undefined) return resolved
+    try {
+      const service = ctx.get?.('directoryPicker') as HostDirectoryPickerService | undefined
+      resolved = nativeCapability(service)
+    } catch {
+      // A throwing service lookup must not take the settings panel down.
+      resolved = undefined
+    }
+    return resolved
+  }
+  /** 互斥：一个原生模态框同时只应存在一个（双击/多标签页不得叠窗）。 */
+  let picking = false
+  return {
+    get available(): boolean {
+      return resolve() !== undefined
+    },
+    async pick(signal: AbortSignal): Promise<string | null> {
+      const capability = resolve()
+      if (capability === undefined) throw new Error('当前宿主机不提供系统目录选择器')
+      if (picking) throw new Error('已有目录选择窗口正在打开')
+      if (signal.aborted) return null
+      picking = true
+      try {
+        const picked = await capability.pick.call(capability, signal)
+        if (picked === null || picked === undefined) return null
+        if (typeof picked !== 'string' || picked.trim() === '') {
+          throw new Error('目录选择器返回了无效路径')
+        }
+        return picked
+      } finally {
+        picking = false
+      }
+    },
+  }
+}

package/src/settings/routes.ts

@@ -24,10 +24,16 @@ import {
   CONFIG_ROUTE,
   CREDENTIALS_ROUTE,
   PANEL_ROUTE,
+  PICK_DIRECTORY_ROUTE,
   RECONNECT_ROUTE,
   STATUS_ROUTE,
 } from './contract.ts'
-import type { CredentialField, EditableValues, SaveCredentialsRequest } from './contract.ts'
+import type {
+  CredentialField,
+  EditableValues,
+  PickDirectoryResponse,
+  SaveCredentialsRequest,
+} from './contract.ts'
 import type { SettingsSurface } from './surface.ts'
 
 /** The narrow `ctx.webServer` surface this module registers into. */
@@ -299,7 +305,9 @@ export function registerSettingsRoutes(server: HostWebServer, surface: SettingsS
           return
         }
         const result = await surface.reconnect()
-        sendJson(res, result.ok ? 200 : 500, result)
+        // An incomplete configuration is a client-side state (the panel routes
+        // the user to the credentials form), not a server failure.
+        sendJson(res, result.ok ? 200 : (result.unconfigured === true ? 400 : 500), result)
       }),
     }),
     server.register({
@@ -315,6 +323,45 @@ export function registerSettingsRoutes(server: HostWebServer, surface: SettingsS
         sendJson(res, result.ok ? 200 : 500, result)
       }),
     }),
+    server.register({
+      kind: 'exact',
+      path: PICK_DIRECTORY_ROUTE,
+      handler: guarded(async (req, res) => {
+        if (!allowOnly(req, res, ['POST'])) return
+        if (!isSameOriginRequest(req)) {
+          forbiddenWrite(res)
+          return
+        }
+        // The chooser is a local desktop modal: it can stay open far longer
+        // than a normal request, and the operator may close the page instead
+        // of the dialog. Abort the host picker when the response socket goes
+        // away so no orphaned modal outlives its panel.
+        const controller = new AbortController()
+        let answered = false
+        if (typeof res.on === 'function') {
+          res.on('close', () => {
+            if (!answered) controller.abort()
+          })
+        }
+        let path: string | null
+        try {
+          path = await surface.pickDirectory(controller.signal)
+        } catch (error) {
+          answered = true
+          // A request the browser already dropped has nobody left to answer.
+          if (controller.signal.aborted) {
+            res.end()
+            return
+          }
+          throw error
+        }
+        answered = true
+        const payload: PickDirectoryResponse = path === null
+          ? { ok: true, canceled: true }
+          : { ok: true, path }
+        sendJson(res, 200, payload)
+      }),
+    }),
     server.register({
       kind: 'exact',
       path: ACCESS_ROUTE,