@tutti-os/workspace-file-reference 0.0.13 → 0.0.14

package/dist/contracts/index.d.ts

@@ -1,3 +1,122 @@
+/**
+ * Reference Source Services 契约。
+ *
+ * 设计见 docs/architecture/agent-reference-source-services.md。
+ * 把「+」文件引用弹窗从单一数据源升级为可插拔的多源服务层:
+ * 本地文件 / 应用内产物 / 任务中心产物,每个一个 ReferenceSourceService。
+ */
+/**
+ * 不透明、源内作用域的节点句柄。
+ * picker 永不解析 nodeId —— 只整体持有、原样回传给所属源。
+ */
+interface NodeRef {
+    /** "workspace-file" | "app-artifact" | "task-artifact" ... */
+    sourceId: string;
+    /** 源内不透明标识。本地源 = path;应用产物源 = 编码后的 app/group/file 句柄。 */
+    nodeId: string;
+}
+/** 统一树节点。identity = NodeRef。folder 可有子节点,file 不可。 */
+interface ReferenceNode {
+    ref: NodeRef;
+    kind: "folder" | "file";
+    displayName: string;
+    /** folder 是否可下钻(懒加载箭头)。 */
+    hasChildren?: boolean;
+    /** 可选数量,如 app group 的 referenceCount。 */
+    childCount?: number | null;
+    /** 可选图标(data URL / 远程 URL),如应用产物源的 app 图标;有则替代默认文件夹图标。 */
+    iconUrl?: string | null;
+    sizeBytes?: number | null;
+    mtimeMs?: number | null;
+    mimeType?: string | null;
+}
+/** 所有源操作的上下文。 */
+type ReferenceScope = WorkspaceFileReferenceScope;
+interface ListChildrenInput {
+    /** null = 该源根层级。 */
+    node: NodeRef | null;
+    /** 续页游标;本地源恒不返回。 */
+    cursor?: string | null;
+    /** 当前层过滤(可选)。协议层只过滤直接子项,非递归。 */
+    filter?: string | null;
+    signal?: AbortSignal;
+}
+interface ListChildrenResult {
+    entries: ReferenceNode[];
+    /** null/undefined 表示无更多。 */
+    nextCursor?: string | null;
+    /**
+     * 源已自行排序、picker 不应再重排时置 true(如「最近访问」按访问时间倒序)。
+     * 缺省/false:picker 首屏按 folder 在前 + 名称排序。
+     */
+    ordered?: boolean;
+}
+interface SearchInput {
+    query: string;
+    cursor?: string | null;
+    limit?: number;
+    signal?: AbortSignal;
+}
+interface SearchResult {
+    entries: ReferenceNode[];
+    nextCursor?: string | null;
+}
+/** 预览内容(复用 workspace 预览结构)。 */
+type ReferencePreview = WorkspaceFileReferencePreview;
+/**
+ * 选中 → 插入 composer 的产物。
+ * 统一形态:所有源最终都归一为一个文件路径,与现有 picker 逐字段一致,
+ * composer / 序列化 / agent 侧零改动。
+ */
+interface SelectedReference {
+    /** 应用产物 = daemon 解析的绝对路径;本地 = /workspace 逻辑路径。 */
+    path: string;
+    kind: "file" | "folder";
+    displayName?: string;
+}
+interface ReferenceSourceMetadata {
+    id: string;
+    label: string;
+    icon?: string;
+    /** 根层级排序,小者在前。 */
+    order: number;
+}
+interface ReferenceSourceCapabilities {
+    searchable: boolean;
+    previewable: boolean;
+    paginated: boolean;
+    /** 是否展示左侧分组导航(master-detail)。本地源 false;应用/任务源 true。 */
+    navigable?: boolean;
+    /** 是否展示文件类型筛选(网页/文档/图片…)。本地源 false;应用源 true。 */
+    typeFilterable?: boolean;
+}
+/**
+ * 单源契约。各源自治:取数 / open / preview 各自负责。
+ * 形状处理(kind 映射、排序去重、预览类型、cursor 累积、nodeKey 归一)走共享 base 工具。
+ */
+interface ReferenceSourceService {
+    readonly metadata: ReferenceSourceMetadata;
+    readonly capabilities: ReferenceSourceCapabilities;
+    /** 动态可用性。如:无支持 references 的 app 时应用产物源返回 false。 */
+    isAvailable(scope: ReferenceScope): boolean | Promise<boolean>;
+    /**
+     * 可选:源自带的左栏二级分组(固定「位置」),返回顺序即展示顺序。
+     * 返回时 picker 直接用这些节点作为二级分组,不再从源根推导。
+     * 缺省:picker 取源根下的 folder 作为分组(navigable 源默认行为)。
+     */
+    listSidebarGroups?(scope: ReferenceScope): ReferenceNode[];
+    listChildren(scope: ReferenceScope, input: ListChildrenInput): Promise<ListChildrenResult>;
+    search?(scope: ReferenceScope, input: SearchInput): Promise<SearchResult>;
+    open?(scope: ReferenceScope, node: ReferenceNode): Promise<void>;
+    readPreview?(scope: ReferenceScope, node: ReferenceNode): Promise<ReferencePreview | null>;
+    /** 选中产物归一,见 SelectedReference。 */
+    resolveSelection(node: ReferenceNode): SelectedReference;
+}
+interface ReferenceSourceRegistry {
+    /** 已按 isAvailable 过滤、按 metadata.order 排序。 */
+    getSources(scope: ReferenceScope): Promise<ReferenceSourceService[]>;
+}
+
 interface WorkspaceFileReference {
     displayName?: string;
     kind: "file" | "folder" | (string & {});
@@ -49,6 +168,10 @@ interface WorkspaceFileReferenceAdapter {
     listDirectory?(input: WorkspaceFileReferenceScope & {
         path?: string | null;
     }): Promise<WorkspaceFileReferenceDirectoryListing>;
+    listRecentReferences?(input: WorkspaceFileReferenceScope & {
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<WorkspaceFileReference[]>;
     openReference?(reference: WorkspaceFileReference): Promise<void> | void;
     readReferencePreview?(input: WorkspaceFileReferenceScope & {
         reference: WorkspaceFileReference;
@@ -68,4 +191,4 @@ interface WorkspaceFileReferenceCopy {
     t(key: string, values?: Record<string, number | string>): string;
 }
 
-export type { WorkspaceFileReference, WorkspaceFileReferenceAdapter, WorkspaceFileReferenceCopy, WorkspaceFileReferenceDirectoryListing, WorkspaceFileReferencePrefetchReason, WorkspaceFileReferencePrefetchState, WorkspaceFileReferencePreview, WorkspaceFileReferencePreviewKind, WorkspaceFileReferenceScope, WorkspaceFileReferenceTreeDirectory, WorkspaceFileReferenceTreeEntry, WorkspaceFileReferenceTreeSnapshot };
+export type { ListChildrenInput, ListChildrenResult, NodeRef, ReferenceNode, ReferencePreview, ReferenceScope, ReferenceSourceCapabilities, ReferenceSourceMetadata, ReferenceSourceRegistry, ReferenceSourceService, SearchInput, SearchResult, SelectedReference, WorkspaceFileReference, WorkspaceFileReferenceAdapter, WorkspaceFileReferenceCopy, WorkspaceFileReferenceDirectoryListing, WorkspaceFileReferencePrefetchReason, WorkspaceFileReferencePrefetchState, WorkspaceFileReferencePreview, WorkspaceFileReferencePreviewKind, WorkspaceFileReferenceScope, WorkspaceFileReferenceTreeDirectory, WorkspaceFileReferenceTreeEntry, WorkspaceFileReferenceTreeSnapshot };

package/dist/core/index.d.ts

@@ -1,5 +1,100 @@
-import { WorkspaceFileReference } from '../contracts/index.js';
+import { ReferenceNode, NodeRef, SelectedReference, WorkspaceFileReference, ReferenceSourceCapabilities, ReferenceScope, WorkspaceFileReferenceAdapter, ReferenceSourceService } from '../contracts/index.js';
+export { R as ReferenceSourceAggregator, a as ReferenceSourceTab, S as SOURCE_ROOT_NODE_ID, c as createReferenceSourceAggregator, b as createStaticReferenceSourceRegistry, i as isSourceRootNode } from '../referenceSourceAggregator-yyyLVOPi.js';
+
+/**
+ * Reference Source Services 的共享 base 工具(形状处理,非取数)。
+ * 设计见 docs/architecture/agent-reference-source-services.md §1 / §2。
+ */
+/**
+ * 「回到源根」哨兵 nodeId。源在 listSidebarGroups 里用它表示一个等价于源根的
+ * 二级分组(如本地源的「个人」= 用户 home 根);picker 选中它走 navigateToRoot
+ * 而非 ensureChildren,避免把哨兵当真实路径打后端。
+ */
+declare const WORKSPACE_ROOT_GROUP_NODE_ID = "__workspace_root__";
+/** 节点的全局 key,用于 picker 树状态索引与去重。picker 不解析其内部结构。 */
+declare function nodeRefKey(ref: NodeRef): string;
+declare function nodeKey(node: ReferenceNode): string;
+/** 任意输入归一为 "file" | "folder"。 */
+declare function normalizeReferenceNodeKind(kind: string | null | undefined): "file" | "folder";
+/** folder 在前、同类按 displayName 本地化排序。 */
+declare function sortReferenceNodes(nodes: readonly ReferenceNode[]): ReferenceNode[];
+/** 按 node key 去重,保留首次出现。支持 cursor append 的稳定去重。 */
+declare function dedupeReferenceNodes(nodes: readonly ReferenceNode[]): ReferenceNode[];
+/** 续页累积:把新一页 append 到已有项后并去重(cursor 语义,不重排)。 */
+declare function appendReferencePage(current: readonly ReferenceNode[], next: readonly ReferenceNode[]): ReferenceNode[];
+/** SelectedReference 与现有 WorkspaceFileReference 形状兼容,便于下游零改动复用。 */
+declare function selectedReferenceToWorkspaceFileReference(selected: SelectedReference): WorkspaceFileReference;
+
+/**
+ * 统一的「引用列表协议」—— 与 app references 同一套 group/reference/parentGroupId/cursor 形状。
+ * 各源(应用 / issue / 任务…)各自实现一个 ReferenceListBackend 把自家数据映射成此协议;
+ * createReferenceListSource 把协议 item 映射成 ReferenceNode,各源前端逻辑完全复用。
+ * 设计见 docs/architecture/agent-reference-source-services.md。
+ */
+interface ReferenceListGroup {
+    type: "group";
+    /** 不透明分组 id;作为下钻的 parentGroupId 原样回传。 */
+    id: string;
+    displayName: string;
+    referenceCount?: number | null;
+    /** 可选分组图标(data URL / 远程 URL),如应用产物源的 app 图标。 */
+    iconUrl?: string | null;
+}
+interface ReferenceListFile {
+    /** daemon/host 可解析的文件路径。 */
+    path: string;
+    displayName?: string | null;
+    sizeBytes?: number | null;
+    mtimeMs?: number | null;
+    mimeType?: string | null;
+}
+interface ReferenceListReference {
+    type: "reference";
+    reference: ReferenceListFile;
+}
+type ReferenceListItem = ReferenceListGroup | ReferenceListReference;
+interface ReferenceListRequest {
+    /** null = 根层级。 */
+    parentGroupId: string | null;
+    cursor?: string | null;
+    filter?: string | null;
+    signal?: AbortSignal;
+}
+interface ReferenceListResult {
+    items: ReferenceListItem[];
+    nextCursor?: string | null;
+}
+/** 递归搜索请求(跨整源,非当前层 filter)。 */
+interface ReferenceListSearchRequest {
+    query: string;
+    cursor?: string | null;
+    limit?: number;
+    signal?: AbortSignal;
+}
+/** 各源自治的取数适配器:把自家数据映射成统一协议。 */
+interface ReferenceListBackend {
+    list(scope: ReferenceScope, request: ReferenceListRequest): Promise<ReferenceListResult>;
+    /**
+     * 可选:递归搜索。实现即代表该源支持全局搜索(对应 capabilities.searchable)。
+     * 返回 flat reference items(协议层不返回 group)。
+     */
+    search?(scope: ReferenceScope, request: ReferenceListSearchRequest): Promise<ReferenceListResult>;
+}
+interface CreateReferenceListSourceInput {
+    sourceId: string;
+    label: string;
+    order?: number;
+    capabilities: ReferenceSourceCapabilities;
+    isAvailable: (scope: ReferenceScope) => boolean | Promise<boolean>;
+    backend: ReferenceListBackend;
+    /** open/preview 复用 host 链路(协议返回的 path 可被解析打开)。 */
+    adapter: WorkspaceFileReferenceAdapter;
+}
+declare function createReferenceListSource(input: CreateReferenceListSourceInput): ReferenceSourceService;
+/** UTF-8 安全的 base64url(浏览器/Node 通用)。 */
+declare function base64UrlEncode(value: string): string;
+declare function base64UrlDecode(value: string): string;
 
 declare function uniqueWorkspaceFileReferences(refs: readonly WorkspaceFileReference[]): WorkspaceFileReference[];
 
-export { uniqueWorkspaceFileReferences };
+export { type CreateReferenceListSourceInput, type ReferenceListBackend, type ReferenceListFile, type ReferenceListGroup, type ReferenceListItem, type ReferenceListReference, type ReferenceListRequest, type ReferenceListResult, type ReferenceListSearchRequest, WORKSPACE_ROOT_GROUP_NODE_ID, appendReferencePage, base64UrlDecode, base64UrlEncode, createReferenceListSource, dedupeReferenceNodes, nodeKey, nodeRefKey, normalizeReferenceNodeKind, selectedReferenceToWorkspaceFileReference, sortReferenceNodes, uniqueWorkspaceFileReferences };

package/dist/core/index.js

@@ -1,7 +1,37 @@
 import {
+  SOURCE_ROOT_NODE_ID,
+  WORKSPACE_ROOT_GROUP_NODE_ID,
+  appendReferencePage,
+  base64UrlDecode,
+  base64UrlEncode,
+  createReferenceListSource,
+  createReferenceSourceAggregator,
+  createStaticReferenceSourceRegistry,
+  dedupeReferenceNodes,
+  isSourceRootNode,
+  nodeKey,
+  nodeRefKey,
+  normalizeReferenceNodeKind,
+  selectedReferenceToWorkspaceFileReference,
+  sortReferenceNodes,
   uniqueWorkspaceFileReferences
-} from "../chunk-PAR2R2G5.js";
+} from "../chunk-7C3RZYQE.js";
 export {
+  SOURCE_ROOT_NODE_ID,
+  WORKSPACE_ROOT_GROUP_NODE_ID,
+  appendReferencePage,
+  base64UrlDecode,
+  base64UrlEncode,
+  createReferenceListSource,
+  createReferenceSourceAggregator,
+  createStaticReferenceSourceRegistry,
+  dedupeReferenceNodes,
+  isSourceRootNode,
+  nodeKey,
+  nodeRefKey,
+  normalizeReferenceNodeKind,
+  selectedReferenceToWorkspaceFileReference,
+  sortReferenceNodes,
   uniqueWorkspaceFileReferences
 };
 //# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export { WorkspaceFileReference, WorkspaceFileReferenceAdapter, WorkspaceFileReferenceCopy, WorkspaceFileReferenceDirectoryListing, WorkspaceFileReferencePrefetchReason, WorkspaceFileReferencePrefetchState, WorkspaceFileReferencePreview, WorkspaceFileReferencePreviewKind, WorkspaceFileReferenceScope, WorkspaceFileReferenceTreeDirectory, WorkspaceFileReferenceTreeEntry, WorkspaceFileReferenceTreeSnapshot } from './contracts/index.js';
-export { uniqueWorkspaceFileReferences } from './core/index.js';
+export { ListChildrenInput, ListChildrenResult, NodeRef, ReferenceNode, ReferencePreview, ReferenceScope, ReferenceSourceCapabilities, ReferenceSourceMetadata, ReferenceSourceRegistry, ReferenceSourceService, SearchInput, SearchResult, SelectedReference, WorkspaceFileReference, WorkspaceFileReferenceAdapter, WorkspaceFileReferenceCopy, WorkspaceFileReferenceDirectoryListing, WorkspaceFileReferencePrefetchReason, WorkspaceFileReferencePrefetchState, WorkspaceFileReferencePreview, WorkspaceFileReferencePreviewKind, WorkspaceFileReferenceScope, WorkspaceFileReferenceTreeDirectory, WorkspaceFileReferenceTreeEntry, WorkspaceFileReferenceTreeSnapshot } from './contracts/index.js';
+export { CreateReferenceListSourceInput, ReferenceListBackend, ReferenceListFile, ReferenceListGroup, ReferenceListItem, ReferenceListReference, ReferenceListRequest, ReferenceListResult, ReferenceListSearchRequest, WORKSPACE_ROOT_GROUP_NODE_ID, appendReferencePage, base64UrlDecode, base64UrlEncode, createReferenceListSource, dedupeReferenceNodes, nodeKey, nodeRefKey, normalizeReferenceNodeKind, selectedReferenceToWorkspaceFileReference, sortReferenceNodes, uniqueWorkspaceFileReferences } from './core/index.js';
+export { R as ReferenceSourceAggregator, a as ReferenceSourceTab, S as SOURCE_ROOT_NODE_ID, c as createReferenceSourceAggregator, b as createStaticReferenceSourceRegistry, i as isSourceRootNode } from './referenceSourceAggregator-yyyLVOPi.js';

package/dist/index.js

@@ -1,7 +1,37 @@
 import {
+  SOURCE_ROOT_NODE_ID,
+  WORKSPACE_ROOT_GROUP_NODE_ID,
+  appendReferencePage,
+  base64UrlDecode,
+  base64UrlEncode,
+  createReferenceListSource,
+  createReferenceSourceAggregator,
+  createStaticReferenceSourceRegistry,
+  dedupeReferenceNodes,
+  isSourceRootNode,
+  nodeKey,
+  nodeRefKey,
+  normalizeReferenceNodeKind,
+  selectedReferenceToWorkspaceFileReference,
+  sortReferenceNodes,
   uniqueWorkspaceFileReferences
-} from "./chunk-PAR2R2G5.js";
+} from "./chunk-7C3RZYQE.js";
 export {
+  SOURCE_ROOT_NODE_ID,
+  WORKSPACE_ROOT_GROUP_NODE_ID,
+  appendReferencePage,
+  base64UrlDecode,
+  base64UrlEncode,
+  createReferenceListSource,
+  createReferenceSourceAggregator,
+  createStaticReferenceSourceRegistry,
+  dedupeReferenceNodes,
+  isSourceRootNode,
+  nodeKey,
+  nodeRefKey,
+  normalizeReferenceNodeKind,
+  selectedReferenceToWorkspaceFileReference,
+  sortReferenceNodes,
   uniqueWorkspaceFileReferences
 };
 //# sourceMappingURL=index.js.map

package/dist/react/index.d.ts

@@ -1,6 +1,7 @@
-import { WorkspaceFileReference, WorkspaceFileReferencePrefetchReason, WorkspaceFileReferencePrefetchState, WorkspaceFileReferenceTreeSnapshot, WorkspaceFileReferenceAdapter } from '../contracts/index.js';
+import { WorkspaceFileReference, WorkspaceFileReferencePrefetchReason, WorkspaceFileReferencePrefetchState, WorkspaceFileReferenceTreeSnapshot, WorkspaceFileReferenceAdapter, ReferenceScope, ReferenceNode, SelectedReference } from '../contracts/index.js';
 import * as react from 'react';
 import { WorkspaceFilePreviewReadonlyReason } from '@tutti-os/workspace-file-preview';
+import { R as ReferenceSourceAggregator, a as ReferenceSourceTab } from '../referenceSourceAggregator-yyyLVOPi.js';
 
 declare const workspaceFileReferenceDefaultExpandedDepth = 4;
 interface WorkspaceFileReferenceDirectoryState {
@@ -89,4 +90,76 @@ declare function useWorkspaceFileReferencePickerView({ fileAdapter, initialPath,
     toggleRef: (ref: WorkspaceFileReference) => void;
 };
 
-export { type UseWorkspaceFileReferencePickerViewInput, type WorkspaceFileReferenceDirectoryState, type WorkspaceFileReferencePreviewState, collectVisibleTreeEntries, createWorkspaceFileReferenceDirectoryStateFromSnapshot, mergeExpandedFolderPaths, mergePrefetchedDirectoryState, normalizeDirectoryPath, prefetchReferenceTree, useWorkspaceFileReferencePickerView, workspaceFileReferenceDefaultExpandedDepth };
+/**
+ * node-keyed 多源 picker 的逻辑层 controller(顶部分源 tab)。
+ * 独立于现有 WorkspaceFileReferencePickerController —— issue-manager 不受影响。
+ * 设计见 docs/architecture/agent-reference-source-services.md §2 / §3。
+ *
+ * 本层只管:tabs、per-source inline 展开树(node-keyed)、cursor 加载更多、
+ * per-tab 搜索、跨 tab 选中集、confirm。预览/打开留待 UI 接入步骤。
+ */
+type ReferenceSourcePickerMode = "browse" | "search";
+interface ReferenceSourceNodeChildrenState {
+    /** 已累积的子节点(含多页 append)。 */
+    entries: ReferenceNode[];
+    nextCursor: string | null;
+    loaded: boolean;
+    loading: boolean;
+    error: Error | null;
+}
+interface ReferenceSourceTabState {
+    sourceId: string;
+    expandedKeys: Record<string, boolean>;
+    /** key = nodeRefKey;源根用 ROOT_CHILDREN_KEY。 */
+    childrenByKey: Record<string, ReferenceSourceNodeChildrenState>;
+    mode: ReferenceSourcePickerMode;
+    searchQuery: string;
+    searchEntries: ReferenceNode[];
+    searchNextCursor: string | null;
+    isSearchLoading: boolean;
+    searchError: Error | null;
+}
+interface ReferenceSourcePickerSnapshot {
+    isLoadingTabs: boolean;
+    tabsError: Error | null;
+    tabs: ReferenceSourceTab[];
+    activeSourceId: string | null;
+    bySource: Record<string, ReferenceSourceTabState>;
+    /** 跨 tab 累积的选中文件节点,按选中顺序。 */
+    selection: ReferenceNode[];
+}
+interface ReferenceSourcePickerController {
+    readonly store: ReferenceSourcePickerSnapshot;
+    getSnapshot(): ReferenceSourcePickerSnapshot;
+    open(): void;
+    close(): void;
+    reset(): void;
+    setActiveSource(sourceId: string): void;
+    /** 确保某节点(null=当前源根)的子节点已加载(抽屉式导航进入用,不切换展开态)。 */
+    ensureChildren(node: ReferenceNode | null): void;
+    /** 确保指定源的根层级已加载(左栏可同时展开多源时,为非 active 源预载分组)。 */
+    ensureSourceRoot(sourceId: string): void;
+    toggleNode(node: ReferenceNode): void;
+    loadMore(node: ReferenceNode | null): void;
+    setSearchQuery(query: string): void;
+    toggleSelection(node: ReferenceNode): void;
+    clearSelection(): void;
+    /**
+     * 选中归一。文件 → 单条;文件夹按所属源区分:
+     *  - 本地(非 navigable)源:保持单条 folder 引用(filesystem 路径与目录一一对应);
+     *  - app/issue(navigable)源:其文件夹下文件在 filesystem 里不一定落在该目录路径下,
+     *    故递归 listChildren 枚举,展开成多条文件引用。
+     * 含异步枚举,故返回 Promise;结果按 path 去重、保序。
+     */
+    confirm(): Promise<SelectedReference[]>;
+}
+interface CreateReferenceSourcePickerControllerInput {
+    aggregator: ReferenceSourceAggregator;
+    scope: ReferenceScope;
+    searchDebounceMs?: number;
+}
+/** 源根 children 的 key(node===null 时)。 */
+declare const ROOT_CHILDREN_KEY: string;
+declare function createReferenceSourcePickerController(input: CreateReferenceSourcePickerControllerInput): ReferenceSourcePickerController;
+
+export { type CreateReferenceSourcePickerControllerInput, ROOT_CHILDREN_KEY, type ReferenceSourceNodeChildrenState, type ReferenceSourcePickerController, type ReferenceSourcePickerMode, type ReferenceSourcePickerSnapshot, type ReferenceSourceTabState, type UseWorkspaceFileReferencePickerViewInput, type WorkspaceFileReferenceDirectoryState, type WorkspaceFileReferencePreviewState, collectVisibleTreeEntries, createReferenceSourcePickerController, createWorkspaceFileReferenceDirectoryStateFromSnapshot, mergeExpandedFolderPaths, mergePrefetchedDirectoryState, normalizeDirectoryPath, prefetchReferenceTree, useWorkspaceFileReferencePickerView, workspaceFileReferenceDefaultExpandedDepth };

package/dist/react/index.js

@@ -1,5 +1,7 @@
 import {
+  ROOT_CHILDREN_KEY,
   collectVisibleTreeEntries,
+  createReferenceSourcePickerController,
   createWorkspaceFileReferenceDirectoryStateFromSnapshot,
   mergeExpandedFolderPaths,
   mergePrefetchedDirectoryState,
@@ -7,10 +9,12 @@ import {
   prefetchReferenceTree,
   useWorkspaceFileReferencePickerView,
   workspaceFileReferenceDefaultExpandedDepth
-} from "../chunk-LS7P3J6Z.js";
-import "../chunk-PAR2R2G5.js";
+} from "../chunk-CD3YNHYJ.js";
+import "../chunk-7C3RZYQE.js";
 export {
+  ROOT_CHILDREN_KEY,
   collectVisibleTreeEntries,
+  createReferenceSourcePickerController,
   createWorkspaceFileReferenceDirectoryStateFromSnapshot,
   mergeExpandedFolderPaths,
   mergePrefetchedDirectoryState,

package/dist/referenceSourceAggregator-yyyLVOPi.d.ts

@@ -0,0 +1,42 @@
+import { ReferenceScope, ReferenceSourceService, ReferenceNode, NodeRef, ListChildrenResult, SearchInput, SearchResult, ReferencePreview, SelectedReference, ReferenceSourceRegistry } from './contracts/index.js';
+
+/**
+ * 多源聚合器:根层级 = 每个可用源一个 folder 节点;其余按 node.ref.sourceId 委派。
+ * 设计见 docs/architecture/agent-reference-source-services.md §3 / §4.4。
+ */
+/**
+ * 源根节点的 nodeId 哨兵。由聚合器创建源根节点时使用;
+ * 任何真实源都不会产出 nodeId 等于此值的子节点(workspace 源 nodeId 是路径,
+ * app 源 nodeId 以 "app:" 开头),因此路由无歧义。
+ */
+declare const SOURCE_ROOT_NODE_ID = "\0source-root";
+/** 顶部 tab 的描述(source 身份 + 能力)。 */
+interface ReferenceSourceTab {
+    sourceId: string;
+    label: string;
+    icon?: string;
+    capabilities: ReferenceSourceService["capabilities"];
+}
+interface ReferenceSourceAggregator {
+    /** 顶部 tab 列表:每个可用源一个 tab(已过滤 isAvailable、按 order 排序)。 */
+    listSources(scope: ReferenceScope): Promise<ReferenceSourceTab[]>;
+    /** (备用,单树多根形态)根层级:每个可用源一个 folder 节点。 */
+    listRoot(scope: ReferenceScope): Promise<ReferenceNode[]>;
+    listChildren(scope: ReferenceScope, node: NodeRef, input?: {
+        cursor?: string | null;
+        filter?: string | null;
+        signal?: AbortSignal;
+    }): Promise<ListChildrenResult>;
+    search(scope: ReferenceScope, sourceId: string, input: SearchInput): Promise<SearchResult>;
+    open(scope: ReferenceScope, node: ReferenceNode): Promise<void>;
+    readPreview(scope: ReferenceScope, node: ReferenceNode): Promise<ReferencePreview | null>;
+    resolveSelection(node: ReferenceNode): SelectedReference;
+    /** 取已加载的源(用于读取 capabilities/metadata)。需先 listRoot 触发加载。 */
+    getLoadedSource(sourceId: string): ReferenceSourceService | undefined;
+}
+declare function isSourceRootNode(ref: NodeRef): boolean;
+declare function createReferenceSourceAggregator(registry: ReferenceSourceRegistry): ReferenceSourceAggregator;
+/** 静态 registry:持有一组源,按 isAvailable 过滤、按 order 排序。 */
+declare function createStaticReferenceSourceRegistry(sources: readonly ReferenceSourceService[]): ReferenceSourceRegistry;
+
+export { type ReferenceSourceAggregator as R, SOURCE_ROOT_NODE_ID as S, type ReferenceSourceTab as a, createStaticReferenceSourceRegistry as b, createReferenceSourceAggregator as c, isSourceRootNode as i };

package/dist/ui/index.d.ts

@@ -1,5 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { WorkspaceFileReferenceCopy, WorkspaceFileReferenceAdapter, WorkspaceFileReference } from '../contracts/index.js';
+import { JSX } from 'react';
+import { R as ReferenceSourceAggregator } from '../referenceSourceAggregator-yyyLVOPi.js';
 
 interface WorkspaceFileReferencePickerProps {
     copy: WorkspaceFileReferenceCopy;
@@ -12,4 +14,14 @@ interface WorkspaceFileReferencePickerProps {
 }
 declare function WorkspaceFileReferencePicker({ copy, fileAdapter, initialPath, onClose, onConfirm, open, workspaceId }: WorkspaceFileReferencePickerProps): react_jsx_runtime.JSX.Element | null;
 
-export { WorkspaceFileReferencePicker, type WorkspaceFileReferencePickerProps };
+interface ReferenceSourcePickerProps {
+    aggregator: ReferenceSourceAggregator;
+    copy: WorkspaceFileReferenceCopy;
+    onClose: () => void;
+    onConfirm: (refs: WorkspaceFileReference[]) => void;
+    open: boolean;
+    workspaceId: string;
+}
+declare function ReferenceSourcePicker({ aggregator, copy, onClose, onConfirm, open, workspaceId }: ReferenceSourcePickerProps): JSX.Element | null;
+
+export { ReferenceSourcePicker, type ReferenceSourcePickerProps, WorkspaceFileReferencePicker, type WorkspaceFileReferencePickerProps };