源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)

packages/agent/gui/agent-gui/agentGuiNode/agentRichText/agentFileMentionContracts.ts

@@ -0,0 +1,185 @@
+import type { Editor, Range } from "@tiptap/core";
+
+export type AgentFileMentionKind = "file" | "directory" | "unknown";
+export type AgentMentionFileNavigationAction =
+  | "agent-generated-folder"
+  | "agent-generated-folder-back"
+  | "workspace-folder"
+  | "workspace-folder-back";
+export type AgentMentionScope = "my_sessions" | "collab_sessions";
+export type AgentMentionKind =
+  | "file"
+  | "agent-target"
+  | "session"
+  | "workspace-app"
+  | "workspace-reference"
+  | "workspace-app-factory"
+  | "workspace-issue"
+  | "custom";
+
+export type AgentMentionReferenceSource = "app" | "task";
+
+export interface AgentMentionFileItem {
+  kind: "file";
+  path: string;
+  href: string;
+  name: string;
+  entryKind: AgentFileMentionKind;
+  directoryPath: string;
+  /** Present only for a regular file attached from the local composer. */
+  attachmentId?: string;
+  attachmentStatus?: AgentComposerFileMentionStatus;
+  attachmentErrorCode?: string;
+  score?: number;
+  thumbnailUrl?: string | null;
+  mentionNavigation?: AgentMentionFileNavigationAction;
+  childCount?: number;
+  /** Ephemeral picker-only relative path and owning-workspace presentation. */
+  contextLabel?: string;
+}
+
+export type AgentComposerFileMentionStatus = "uploading" | "ready" | "error";
+
+export interface AgentMentionSessionItem {
+  kind: "session";
+  href: string;
+  workspaceId: string;
+  targetId: string;
+  agentTargetId?: string;
+  name: string;
+  title: string;
+  scope: AgentMentionScope;
+  initiatorUserId?: string;
+  initiatorName: string;
+  initiatorAvatarUrl?: string;
+  agentName: string;
+  /** Structured owner segment from the matching provenance Agent option. */
+  agentOwnerLabel?: string;
+  /** Structured Agent segment from the matching provenance Agent option. */
+  agentLabel?: string;
+  agentIconUrl?: string;
+  status?: string;
+  inputPreview?: string;
+  summaryPreview?: string;
+  updatedAtUnixMs?: number;
+}
+
+export interface AgentMentionWorkspaceIssueItem {
+  kind: "workspace-issue";
+  href: string;
+  workspaceId: string;
+  targetId: string;
+  topicId?: string;
+  name: string;
+  title: string;
+  creatorName?: string;
+  iconUrl?: string;
+  status?: string;
+  contentPreview?: string;
+  updatedAtUnixMs?: number;
+}
+
+export interface AgentMentionWorkspaceAppItem {
+  kind: "workspace-app";
+  href: string;
+  workspaceId: string;
+  targetId: string;
+  appId: string;
+  name: string;
+  description?: string;
+  iconUrl?: string;
+  /** 应用是否能够提供产物文件(reference),决定 @ 面板行末尾是否展示「查看产物」入口。 */
+  referencesListSupported?: boolean;
+}
+
+export interface AgentMentionAgentTargetItem {
+  kind: "agent-target";
+  href: string;
+  workspaceId: string;
+  targetId: string;
+  name: string;
+  description?: string;
+  agentProviderId?: string;
+  iconUrl?: string;
+  availabilityStatus?: string;
+}
+
+export interface AgentMentionWorkspaceReferenceItem {
+  kind: "workspace-reference";
+  href: string;
+  workspaceId: string;
+  /** URI path id:source=app 时为 appId,source=task 时为 topicId。 */
+  targetId: string;
+  source: AgentMentionReferenceSource;
+  /** 子级 id:app 子分组 / issueId。缺省表示整个 app / topic。 */
+  groupId?: string;
+  name: string;
+  iconUrl?: string;
+  /** 展示用文件数(来自 picker 节点 childCount);序列化不再展开文件。 */
+  fileCount: number;
+}
+
+export interface AgentMentionWorkspaceAppFactoryItem {
+  kind: "workspace-app-factory";
+  href: string;
+  workspaceId: string;
+  targetId: string;
+  jobId: string;
+  name: string;
+  action?: string;
+  contextPath?: string;
+}
+
+// 宿主注册的自定义 mention(见 shared/agentCustomMentionKinds):href 是完整信息源
+// (round-trip 无损),item 只承载通用展示字段;业务细节由宿主在注册的钩子里从 href 还原。
+export interface AgentMentionCustomItem {
+  kind: "custom";
+  /** 注册表里的 kind(= mention:// providerId)。 */
+  customKind: string;
+  href: string;
+  workspaceId: string;
+  targetId: string;
+  /** Canonical Markdown label, kept separate from the host's chip presentation. */
+  sourceLabel: string;
+  /** chip 第一行。 */
+  name: string;
+  /** chip 第二行(通用双行卡)。 */
+  summary?: string;
+}
+
+export type AgentContextMentionItem =
+  | AgentMentionFileItem
+  | AgentMentionAgentTargetItem
+  | AgentMentionSessionItem
+  | AgentMentionWorkspaceAppItem
+  | AgentMentionWorkspaceReferenceItem
+  | AgentMentionWorkspaceAppFactoryItem
+  | AgentMentionWorkspaceIssueItem
+  | AgentMentionCustomItem;
+
+export type AgentFileMentionItem = AgentContextMentionItem;
+
+export interface AgentMentionSuggestionState {
+  editor: Editor;
+  range: Range;
+  query: string;
+  text: string;
+  command: (item: AgentContextMentionItem) => void;
+  clientRect?: (() => DOMRect | null) | null;
+}
+
+export type AgentFileMentionSuggestionState = AgentMentionSuggestionState;
+
+export interface AgentFileMentionExtensionOptions {
+  enableSuggestions?: boolean;
+  onSuggestionChange?: (state: AgentMentionSuggestionState | null) => void;
+  onSuggestionKeyDown?: (event: KeyboardEvent) => boolean;
+  removeActionAriaLabel?: string;
+  renderAsLink?: boolean;
+  shouldSuppressSuggestion?: () => boolean;
+}
+
+export interface ParsedAgentMentionMarkdown {
+  item: AgentContextMentionItem;
+  end: number;
+}