dsh-projects-panel 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# dsh-projects-panel
+
+DeepSeek Harness（DSH）项目面板插件。宿主（Node）侧管理插件数据根
+（`DSH_PROJECTS_ROOT_DIR`，缺省 `~/.dsh/dsh-projects-panel`）下的项目树并
+提供 HTTP 接口；客户端（浏览器）侧向 `sidebar.workspaces`
+槽位注入「项目 / 工作区」混合树浏览器（搜索、筛选、新建、归档）。添加工作区统一调用官方幂等 `create`，再按 `workspaceId` 判断项目归属；已存在工作区直接在其下新建/复用会话。
+
+版本：0.1.0（peer 依赖
+`@deepseek-ai/cordis ^4.0.2`、`@deepseek-ai/dsh-client-locale ^0.1.5-rc.2`）。
+React / React DOM 为浏览器第三方依赖（`devDependencies`），由 Web 壳平台表提供
+共享实例，client 产物经 `tsdown.config.ts` 显式 `external` 外部化。
+
+## 架构
+
+双端插件：Host（Node，构建为 `lib/index.js`）+ Client（浏览器，构建为
+`lib/client.js`，经 `scripts/wrap-client.mjs` 包裹为模块加载器格式）。
+
+### Host 侧（数据与服务）
+
+| 模块 | 职责 |
+| --- | --- |
+| `src/index.ts` | 插件入口：注册 `/projects-panel/*` 路由，解析并校验请求体（wire 边界），汇聚公共导出 |
+| `src/host-tree.ts` | 项目树持久层：结构校验（循环/重复/归档一致性）、原子 JSON 读写、首启与损坏时的目录扫描恢复、工作区归属挂载/摘除（attach/detach，支持项目内排序锚点）、项目移动（moveProject，UUID 不变，只改树不碰目录）、整树工作区唯一与换父拒绝断言 |
+| `src/host-project.ts` | 项目生命周期：创建 / 更新（改名只改 name 字段，不碰目录）/ 归档（只改树，不动目录）、link 文件白名单读取 |
+| `src/host-settings.ts` | `settings.json` 读写（读侧与默认值合并并容忍损坏） |
+| `src/core/` | `types.ts`（纯类型，只放类型）+ `workspace.ts`（工作区稳定键解析） |
+
+数据根目录 `projectsRoot()`：优先读取 `DSH_PROJECTS_ROOT_DIR`（支持 `~` 缩写），
+缺省时回落到 `DSH_HOME`（缺省 `~/.dsh`）下的 `dsh-projects-panel` 目录。
+布局：根下 `projects.json`（嵌套项目树，项目身份为 UUID）与 `settings.json`，
+项目目录统一存放于根下 `projects/` 子目录，目录名 = 项目 ID（UUID），
+项目目录之间无层级，父子关系只记录在 `projects.json`。
+
+HTTP 路由（host webServer，精确匹配；仅 GET 与 POST）：
+
+| 路由 | 方法 | 语义 |
+| --- | --- | --- |
+| `/projects-panel/tree` | GET / POST | 读 / 整树改写（仅排序与字段，换父请走移动路由；写边界含后代环与工作区唯一兜底） |
+| `/projects-panel/project` | POST | 建 / 归档（携带 `action: "archive"`） |
+| `/projects-panel/project-update` | POST | 改（改名只改 name 字段，顶层与子级均做同级重名检查 / 描述 / 关联目录） |
+| `/projects-panel/project-move` | POST | 移动项目归属与排序（UUID 不变；纯排序与换父均只改树，不碰磁盘目录；`parentId` 省略=回顶层，`beforeId` 省略=末尾） |
+| `/projects-panel/workspace-attach` | POST | 挂载工作区到项目（`parentId` 省略=移到顶层，此时不允许 `beforeId`；顶层排序请走官方工作区排序） |
+| `/projects-panel/workspace-detach` | POST | 摘除工作区归属（官方删除后清理） |
+| `/projects-panel/settings` | GET / POST | 读 / 写设置 |
+| `/projects-panel/version` | GET | DSH 官方版本号（解析 `@deepseek-ai/dsh` 清单，与 `dsh --version` 同源；解析失败回退插件版本） |
+| `/projects-panel/health` | GET | 健康检查（插件存活 + 版本） |
+
+### Client 侧（浏览器 UI）
+
+| 模块 | 职责 |
+| --- | --- |
+| `src/client/index.tsx` | 渲染层：注册 `projects-panel` 文案字典与样式，把官方 `ctx.workspaces`/`ctx.sessions` 绑定为 `BrowserActions`，向 `sidebar.workspaces`（priority -1）挂载 `ProjectsBrowser` |
+| `src/client/tree.ts` | 树视图推导纯函数：聚合会话/工作区、展开/收起、搜索裁剪、筛选裁剪 |
+| `src/client/tree-dnd.ts` | 拖拽落点推导纯函数：三类节点可拖性、落点合法性（自身/后代/归档/跨父/跨工作区拒绝）、排序锚点解析（DOM-insertBefore 语义） |
+| `src/client/stores.ts` | 浏览器端视图状态 store（不可变更新 + 残留键清理） |
+| `src/client/dialogs.tsx` | 对话框：项目表单、删除确认、文本输入（重命名）、移动失败单确认、应用内目录浏览/手工路径选择 |
+
+## 开发
+
+环境：Node `^22.19 || >=24`；pnpm 由 `packageManager: pnpm@11.25.0` 声明
+（corepack 自动选用）。
+
+```sh
+pnpm install        # 安装；prepare 自动安装 lefthook git 钩子
+pnpm typecheck      # 严格类型检查
+pnpm test           # 单元测试（vitest）
+pnpm test:coverage  # 覆盖率门禁：src 非渲染逻辑逐文件 100%（v8 per-file 阈值）
+pnpm lint           # oxlint 静态检查
+pnpm check:style    # 行长 ≤140 / 文件尾单换行 / 无行尾空白
+pnpm build          # typecheck + tsdown（host/client）+ wrap-client + 产物守卫
+pnpm check:bundle   # 单独跑产物守卫（需先 build）：无内联 React / 平台表闭包 / 体积上限
+pnpm verify:i18n    # 校验 zh/en 字典已注册
+```
+
+门禁（全部强制）：
+
+- **pre-commit**（lefthook，仅暂存文件）：oxlint、check-style、空白检查；
+- **pre-push**（lefthook）：typecheck + test:coverage + build（build 末尾内置产物守卫）；
+- **CI**（`.github/workflows/ci.yml`，GitHub Actions）：typecheck、lint、
+  check:style、test:coverage、build，推送与 PR 触发。
+
+门禁设施：`vitest.config.ts`、`.oxlintrc.json`、`scripts/check-style.mjs`、
+`scripts/check-client-bundle.mjs`、`lefthook.yml`、`.github/workflows/ci.yml`。
+
+依赖注意：`pnpm-workspace.yaml` 已放行 lefthook/esbuild 构建脚本并关闭
+运行前依赖自检；若镜像对个别 tarball 报 integrity 错误，改用官方 registry
+（`pnpm install --registry=https://registry.npmjs.org`）或
+`pnpm install --update-checksums`。
+
+## 文档入口
+
+- **AI 入口**：根 `AGENTS.md`（standing orders，指向开发规范）；
+- **开发规范**：`docs/CODING_STANDARDS.md`（注释 / 风格命名 / 测试 / 文档
+  通用标准 + AI 加载约定）；
+- **设计文档索引**：`docs/README.md`（需求与设计 00–09，含官方源码落点映射，
+  实现核验以 `docs/设计/08` 为准）。

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+- insert:
+    - id: projects-panel
+      name: 'dsh-projects-panel'
+      config: {}

package/lib/client.d.ts

@@ -0,0 +1,462 @@
+import { ReactElement } from "react";
+import { Context } from "@deepseek-ai/cordis";
+
+//#region src/core/types.d.ts
+
+/** 会话级待用户应答交互的类型（官方 ui-approval / ui-user-questions 注册的 kind 收敛）。 */
+type SessionPendingKind = 'approval' | 'plan-review' | 'question';
+/** 目录浏览的一行（官方 host.listDirectory 投影）：只承载展示字段。 */
+interface DirectoryEntryLike {
+  name: string;
+  path: string;
+  hidden: boolean;
+}
+/** 目录浏览结果（官方 host.listDirectory 响应投影）。 */
+interface DirectoryListingLike {
+  path: string;
+  home: string;
+  crumbs: readonly DirectoryEntryLike[];
+  entries: readonly DirectoryEntryLike[];
+  truncated: boolean;
+}
+/**
+ * 工作区/会话的官方客户端动作集（渲染层注入，纯接口）。
+ *
+ * 方法语义与官方 IWorkspaces/ISessions 一致；实现绑定在插件入口
+ * （client/index.tsx），由宿主注册的官方运行时提供。目录浏览能力
+ * 缺失（browse 能力未启用）时 listDirectory/createDirectory 为
+ * undefined，界面降级为手工输入路径。
+ */
+interface BrowserActions {
+  /** 打开（并选中）会话。 */
+  openSession(sessionId: string): void;
+  /** 在指定工作区（或默认目标）新建/复用空白会话并打开。 */
+  startSession(workspaceId?: string): Promise<void>;
+  /** 幂等创建或解析已存在目录的工作区；返回官方 workspaceId。 */
+  createWorkspace(path: string): Promise<string>;
+  /** 重命名工作区（官方持久化标题）。 */
+  renameWorkspace(workspaceId: string, title: string): Promise<void>;
+  /** 删除工作区注册（目录与会话日志保留）。 */
+  deleteWorkspace(workspaceId: string): Promise<void>;
+  /** 重命名会话（官方持久化标题）。 */
+  renameSession(sessionId: string, title: string): Promise<void>;
+  /** 分叉会话并在完成后打开子会话。 */
+  forkSession(sessionId: string): Promise<void>;
+  /** 归档会话（registry 全局归档集）。 */
+  archiveSession(sessionId: string): Promise<void>;
+  /**
+   * 官方工作区排序（顶层悬浮工作区与按工作区分组模式专用）。
+   *
+   * 语义与官方 insertBefore 一致：省略锚点追加末尾；缺失时界面降级为不可排序。
+   */
+  insertWorkspaceBefore?(workspaceId: string, beforeId?: string): Promise<void>;
+  /**
+   * 官方会话排序（同工作区内专用，不写插件树）。
+   *
+   * 语义与官方 insertSessionBefore 一致；缺失时界面降级为不可排序。
+   */
+  insertSessionBefore?(workspaceId: string, sessionId: string, beforeId?: string): Promise<void>;
+  /** 应用内目录浏览能力（可选）。 */
+  listDirectory?(path?: string, signal?: AbortSignal): Promise<DirectoryListingLike>;
+  /** 应用内新建目录能力（可选）。 */
+  createDirectory?(path: string, name: string): Promise<string>;
+}
+//#endregion
+//#region src/client/locales.d.ts
+/**
+ * 客户端文案字典（zh / en）与翻译函数。
+ *
+ * 职责：集中维护全部客户端可见文案，供 apply 注册到宿主 locale；
+ * 导出 ProjectsTranslate 翻译函数类型与 dictTranslate 包装器（把字典
+ * 包成官方 Translate 形状，供组件独立测试与无宿主 locale 时兜底）。
+ * 渲染层一律经翻译函数取词，禁止硬编码文案。
+ * 边界：只承载文案与翻译包装，不含组件逻辑。
+ */
+/** 文案键：按界面区域分组，键名即语义。 */
+interface ProjectsKey {
+  'title': string;
+  'all': string;
+  'filter.searchPlaceholder': string;
+  'filter.empty': string;
+  'searchSessions.placeholder': string;
+  'newProject': string;
+  'newWorkspace': string;
+  'newSession': string;
+  'session.new': string;
+  'session.untitled': string;
+  'session.status.running': string;
+  'session.status.subagents.one': string;
+  'session.status.subagents.other': string;
+  'session.status.idle': string;
+  'session.status.completed': string;
+  'session.status.archived': string;
+  'session.status.waitingApproval': string;
+  'session.status.planReview': string;
+  'session.status.waitingAnswer': string;
+  'session.schedule.active': string;
+  'session.hover.copy': string;
+  'session.hover.copied': string;
+  'toolbar.actions': string;
+  'viewOptions': string;
+  'view.grouping': string;
+  'view.byProject': string;
+  'view.byWorkspace': string;
+  'view.showArchived': string;
+  'view.other': string;
+  'empty': string;
+  'project.menu.newChildProject': string;
+  'project.menu.newChildWorkspace': string;
+  'project.menu.edit': string;
+  'project.menu.delete': string;
+  'workspace.menu.rename': string;
+  'workspace.menu.delete': string;
+  'session.menu.rename': string;
+  'session.menu.fork': string;
+  'session.menu.archive': string;
+  'project.dialog.create.title': string;
+  'project.dialog.edit.title': string;
+  'project.dialog.name': string;
+  'project.dialog.description': string;
+  'project.dialog.link': string;
+  'project.dialog.linkBrowse': string;
+  'project.dialog.submit.create': string;
+  'project.dialog.submit.save': string;
+  'project.dialog.nameRequired': string;
+  'project.dialog.nameInvalid': string;
+  'project.dialog.descriptionTooLong': string;
+  'project.delete.title': string;
+  'project.delete.message': string;
+  'project.delete.submit': string;
+  'dialog.cancel': string;
+  'dialog.save': string;
+  'dialog.delete': string;
+  'dialog.confirm': string;
+  'move.failed.title': string;
+  'field.nameLabel': string;
+  'field.required': string;
+  'notReady.message': string;
+  'workspace.create.title': string;
+  'workspace.create.titleInProject': string;
+  'workspace.create.submit': string;
+  'workspace.rename.title': string;
+  'workspace.delete.title': string;
+  'workspace.delete.message': string;
+  'workspace.delete.submit': string;
+  'session.rename.title': string;
+  'directory.select': string;
+  'directory.enter': string;
+  'directory.newFolder': string;
+  'directory.newFolderPlaceholder': string;
+  'directory.createFolder': string;
+  'directory.empty': string;
+  'directory.listFailed': string;
+  'directory.createFailed': string;
+  'directory.unavailable': string;
+  'directory.manualPlaceholder': string;
+  'browser.title': string;
+  'browser.home': string;
+  'browser.newFolder': string;
+  'browser.folderName': string;
+  'browser.createIn': string;
+  'browser.untitledFolder': string;
+  'browser.create': string;
+  'browser.cancel': string;
+  'browser.open': string;
+  'browser.editPath': string;
+  'browser.loading': string;
+  'browser.truncated': string;
+  'browser.showHidden': string;
+  'time.now': string;
+  'time.ago': string;
+  'time.minutes': string;
+  'time.hours': string;
+  'time.days': string;
+  'time.months': string;
+  'time.years': string;
+  /** 绝对日期模板（hover 卡创建时间；与官方 date.ymd 同语义）。 */
+  'date.ymd': string;
+  /** hover 卡创建时间包装（含时分）。 */
+  'hover.created': string;
+  'error.loadTree': string;
+  'error.createProject': string;
+  'error.updateProject': string;
+  'error.archiveProject': string;
+  'error.startSession': string;
+  'error.createWorkspace': string;
+  'error.renameWorkspace': string;
+  'error.deleteWorkspace': string;
+  'error.renameSession': string;
+  'error.forkSession': string;
+  'error.archiveSession': string;
+  'error.attachWorkspace': string;
+  'error.moveProject': string;
+  'error.reorderProject': string;
+  'error.reorderOfficial': string;
+  'user.menu.language': string;
+  'user.menu.theme': string;
+  'user.menu.notification': string;
+  'user.menu.workspace': string;
+  'user.menu.version': string;
+  'user.menu.logout': string;
+  'user.menu.anonymous': string;
+  'user.menu.settings': string;
+  'user.menu.language.zh': string;
+  'user.menu.language.en': string;
+  'user.menu.theme.system': string;
+  'user.menu.theme.light': string;
+  'user.menu.theme.dark': string;
+  'user.menu.notification.on': string;
+  'user.menu.notification.off': string;
+  'user.menu.workspace.default': string;
+  'user.menu.workspace.projects': string;
+  'notification.title': string;
+  'notification.session.completed': string;
+  'notification.session.pending': string;
+  'notification.test.enabled': string;
+  'notification.test.disabled': string;
+}
+/**
+ * 翻译函数：读取当前语言的字典并解析键，支持 `{name}` 模板参数。
+ * 由宿主 locale 注入（与官方 Translate 形状一致），语言切换时返回新函数
+ * 触发重渲染。
+ */
+type ProjectsTranslate = (key: keyof ProjectsKey, params?: Record<string, unknown>) => string;
+//#endregion
+//#region src/client/session-facts.d.ts
+
+/** 会话实时展示事实：树会话节点在其上叠加（仅含有的字段参与覆盖）。 */
+interface SessionLiveFacts {
+  running: boolean;
+  completed: boolean;
+  runningSubagentCount: number;
+  pendingInteraction?: SessionPendingKind;
+  hasActiveSchedule: boolean;
+  /** 官方客户端空会话位（实时真源；RPC 快照可能停留在创建时的 true）。 */
+  blank: boolean;
+  /** 官方持久标题（非空才投影；空标题时保留 RPC 权威补读值）。 */
+  title?: string;
+  /** 官方列表的最后活动时间（新于 RPC 快照时覆盖行尾相对时间）。 */
+  updatedAt?: number;
+}
+//#endregion
+//#region src/client/ProjectsBrowser.d.ts
+/** 项目浏览器组件属性。 */
+interface ProjectsBrowserProps {
+  /** 打开会话（官方客户端会话服务）；未提供时仅做选中高亮。 */
+  openSession?: (sessionId: string) => void;
+  /**
+   * 当前打开的会话 id（官方会话列表快照 current）。
+   * 首次加载时收起全部节点、只展开包含它的工作区与上级项目并选中它；
+   * 之后 current 变化只展开对应链路并跟随选中。
+   */
+  currentSessionId?: string | null;
+  /**
+   * 官方客户端动作（会话/工作区 CRUD 与目录浏览），由插件入口注入。
+   * 缺失时对应动作回退为占位提示（组件可独立测试）。
+   */
+  actions?: BrowserActions;
+  /**
+   * 客户端实时事实表（官方 sessions.list + uiSession 推导，见 index.tsx）。
+   * 结构/成员仍以 /tree RPC 为准；本表叠加 running/completed/子代理计数/
+   * 待应答/闹钟等客户端域事实，并覆盖空会话位与标题、最后活动时间——
+   * RPC 只在面板动作后重拉，官方侧的新建会话与首轮对话只有本表是实时的。
+   * undefined 表示无客户端快照（独立渲染/测试兜底走 RPC 字段）。
+   */
+  liveFacts?: ReadonlyMap<string, SessionLiveFacts>;
+  /**
+   * 官方客户端列表的成员键（`membershipKeyOf` 产出，见 index.tsx）。
+   * 结构/成员以 /tree RPC 为准，而 RPC 只在挂载与面板动作后重拉；本键与
+   * 快照成员不一致（面板外入口新建、会话被删除/移出工作区）时防抖重拉
+   * 树，让成员变化即时反映。undefined 表示无客户端快照，不做成员跟踪。
+   */
+  membershipKey?: string;
+  /**
+   * 当前语言翻译函数，由宿主 slot 经 locale 声明注入（官方 Translate 形状）；
+   * 语言切换时注入新函数，组件随之重渲染。未注入时回退为中文。
+   */
+  t?: ProjectsTranslate;
+}
+/** 项目浏览器主组件。 */
+declare function ProjectsBrowser({
+  openSession,
+  currentSessionId,
+  actions,
+  liveFacts,
+  membershipKey,
+  t
+}?: ProjectsBrowserProps): ReactElement;
+//#endregion
+//#region src/client/settings/user-prefs.d.ts
+/**
+ * 用户菜单偏好存储（官方 settings.yaml 主通道 + localStorage 兜底）。
+ *
+ * 职责：读写系统通知开关、工作区模式开关。主通道为官方 projects-panel
+ * 设置命名空间 scope（落盘 $DSH_HOME/settings.yaml，client 侧经
+ * settingsScope.bind + getSnapshot/set）；scope 不可用（宿主未装配/
+ * 尚未就绪）时回退 localStorage，保证 UI 可用性。
+ * 边界：纯存储，不含业务逻辑。
+ */
+/** 设置命名空间 scope 的最小投影（settingsScope.bind 返回）。 */
+interface PrefsScope {
+  /** 当前快照：value = 命名空间解析值（schema 默认 + base + 用户层）。 */
+  getSnapshot(): {
+    value?: unknown;
+    status?: string;
+    revision?: number;
+  };
+  /** 订阅快照变化。 */
+  subscribe(listener: () => void): () => void;
+  /** 写入一个顶层字段（整值覆盖）。 */
+  set(field: string, value: unknown): Promise<void>;
+}
+//#endregion
+//#region src/client/index.d.ts
+type LocaleService = {
+  register(namespace: string, dictionaries: {
+    zh: ProjectsKey;
+    en: ProjectsKey;
+  }): void;
+};
+type SlotService = {
+  /** 声明依赖注册：等待槽声明就绪后执行 callback，返回可注销的 disposer。 */
+  inject(name: string, callback: () => () => void): () => void;
+  register(options: Record<string, unknown>, component: (props: Record<string, unknown>) => ReactElement): () => void;
+};
+/** 会话列表快照：官方会话列表投影（含 current/ids/byId/phase）。 */
+type SessionListSnapshot = {
+  current?: string | null;
+  ids?: readonly string[];
+  byId?: Record<string, SessionSummaryLike>;
+  phase?: string;
+};
+/** 会话行摘要最小投影（官方 SessionSummary 子集）。 */
+type SessionSummaryLike = {
+  blank?: boolean;
+  cwd?: string;
+  running?: boolean;
+  /** 完成提醒：官方 manager 边沿事实（真值才投影）。 */
+  completed?: boolean;
+  parentId?: string;
+  /** 官方 origin：子代理会话为 'subagent'。 */
+  origin?: string;
+  /** 官方持久标题投影（实时真源；面板树据此覆盖 RPC 快照里的空标题）。 */
+  title?: string;
+  /** 官方列表最后活动时间（覆盖 RPC 快照里落后的相对时间）。 */
+  updatedAt?: number;
+  /** 官方投影值（schedule 键携带活动定时任务数组）。 */
+  projectionValues?: Record<string, unknown>;
+};
+/** ctx.sessions 客户端服务的本地最小投影（官方 ClientSessions 子集）。 */
+type SessionsService = {
+  open(sessionId: string): void;
+  clear(): void;
+  /** 创建/复用空白会话并返回会话 id（官方 ClientSessions.create）。 */
+  create(opts: {
+    workspaceId?: string;
+    cwd?: string;
+  }): Promise<string>;
+  /** 官方列表快照（含 current）；缺失时视为无当前会话。 */
+  list?: {
+    getSnapshot(): SessionListSnapshot;
+    subscribe(fn: () => void): () => void;
+  };
+  /** 分叉会话：返回子会话 id。 */
+  fork(opts: {
+    sessionId: string;
+    increaseTitle?: boolean;
+  }): Promise<string>;
+  /** 会话绑定（含重命名 face）；未知 id 返回 undefined。 */
+  binding(sessionId: string): {
+    session?: SessionRenameFace;
+  } | undefined;
+};
+/** 会话重命名 face 的最小投影（官方 SessionFace.rename 的 RpcResult）。 */
+type SessionRenameFace = {
+  rename(title: string): Promise<{
+    ok: boolean;
+    error?: {
+      message: string;
+    };
+  }>;
+};
+/** 官方工作区行（WorkspaceView）最小投影。 */
+type WorkspaceRowLike = {
+  workspaceId: string;
+  path: string;
+  title?: string;
+  sessionIds?: readonly string[];
+};
+/** 官方工作区快照最小投影（WorkspaceSnapshot 子集）。 */
+type WorkspaceListSnapshot = {
+  items: readonly WorkspaceRowLike[];
+  archivedSessionIds: readonly string[];
+  phase?: string;
+};
+/** 官方 workspace 域服务（ctx.workspaces = 纯工作区控制器）的最小投影。 */
+type WorkspacesService = {
+  create(input: {
+    path: string;
+  }): Promise<{
+    workspaceId: string;
+  }>;
+  rename(workspaceId: string, title: string): Promise<unknown>;
+  delete(workspaceId: string): Promise<void>;
+  archiveSession(sessionId: string): Promise<void>;
+  insertBefore?(workspaceId: string, beforeId?: string): Promise<unknown>;
+  insertSessionBefore?(workspaceId: string, sessionId: string, beforeId?: string): Promise<unknown>;
+  /** 官方工作区列表快照（items + 归档集）；缺失时视为空。 */
+  list?: {
+    getSnapshot(): WorkspaceListSnapshot;
+    subscribe(fn: () => void): () => void;
+  };
+};
+/** 目录选择远程命名空间（ctx.remote.directoryPicker）的最小投影。 */
+type DirectoryPickerRemote = {
+  list(path?: string, signal?: AbortSignal): Promise<{
+    ok: true;
+    value: DirectoryListingLike;
+  } | {
+    ok: false;
+    error: {
+      message: string;
+    };
+  }>;
+  createDirectory(path: string, name: string): Promise<{
+    ok: true;
+    value: {
+      path: string;
+    };
+  } | {
+    ok: false;
+    error: {
+      message: string;
+    };
+  }>;
+};
+type ClientContext = Context & {
+  locale: LocaleService;
+  slots: SlotService;
+  sessions: SessionsService;
+  workspaces: WorkspacesService;
+  /** 远程命名空间装配（dsh-api-remotes）；目录选择在其中。 */
+  remote?: {
+    directoryPicker?: DirectoryPickerRemote;
+  };
+  /** 官方 settings scope（绑定 projects-panel 命名空间读写 settings.yaml）。 */
+  settingsScope: {
+    bind(opts: {
+      namespace: string;
+    }): PrefsScope;
+  };
+  effect(effect: () => void | (() => void), label?: string): void;
+  /**
+   * Cordis 上下文反射读取（官方服务未注入时抛错，故先探测再读；
+   * 本项目不从 inject 硬依赖 uiSession，缺失时降级无待应答态）。
+   */
+  get<T = unknown>(name: string): T | undefined;
+};
+declare const inject: string[];
+/** 插件入口：注册字典、注入样式，向侧栏槽位挂载浏览器并注入官方动作。 */
+declare function apply(ctx: ClientContext): void;
+//#endregion
+export { ProjectsBrowser, apply, inject };