科学数据库连接器 Registry 深度解析

14import { ConnectorRegistry } from "./types"
15
16export const registry = new ConnectorRegistry()
17
18// ── connector imports ──────────────────────────────────────────────────────
19// AUTO: connectors registered here by integration
20// (feature agents: create ./impl/<id>.ts, then add an import + registry.register
21//  call inside the block below during the integration stage — do NOT edit this
22//  file yourself.)
23import proteins from "./proteins"
24import genomics from "./genomics"
25import chemistry from "./chemistry"
26import pathways from "./pathways"
27import literature from "./literature"
28import omics from "./omics"
29
30for (const c of [...proteins, ...genomics, ...chemistry, ...pathways, ...literature, ...omics]) {
31  registry.register(c)
32}

42/** Options accepted by `search`. Connectors ignore fields they don't support. */
43export interface SearchOptions {
44  /** Max hits to return. Connectors clamp to their own ceiling. */
45  limit?: number
46  /** Organism / taxon filter where meaningful (e.g. NCBI taxon id). */
47  organism?: string
48  /** Free-form per-source knobs. */
49  params?: Record<string, unknown>
50  /** Abort signal wired through from the tool context. */
51  signal?: AbortSignal
52}
53
54/** Options accepted by `fetch`. */
55export interface FetchOptions {
56  /** Desired representation, e.g. "json" | "pdb" | "fasta" | "sdf". */
57  format?: string
58  params?: Record<string, unknown>
59  signal?: AbortSignal
60}
61
62/**
63 * Per-host politeness limits a connector can request for its HTTP calls.
64 *
65 * Applied per URL host by the shared http layer, so a multi-DB fan-out is never
66 * over-serialized. arXiv, for example, asks for ~1 request every 3s
67 * (`minIntervalMs: 3000`); keyless Semantic Scholar wants ~1000ms.
68 */
69export interface RateLimit {
70  /** Minimum spacing between the START of requests to the same host, in ms. */
71  minIntervalMs?: number
72  /** Max concurrent in-flight requests to the same host. */
73  maxConcurrent?: number
74}
75
76/** The uniform contract every scientific data source implements. */
77export interface Connector {
78  /** Unique, stable, lowercase id used to route (e.g. "uniprot", "rcsb-pdb"). */
79  id: string
80  /** Display name (e.g. "UniProt", "RCSB PDB"). */
81  name: string
82  /** Primary domain for grouping in the catalog. */
83  domain: ConnectorDomain
84  /** One-line description shown in `science_list_dbs`. */
85  description: string
86  /** Homepage / docs URL. */
87  homepage?: string
88  /** Search the source; returns normalized hits. */
89  search(query: string, opts?: SearchOptions): Promise<ConnectorHit[]>
90  /** Fetch a single record by id. Return shape is source-specific. */
91  fetch(id: string, opts?: FetchOptions): Promise<unknown>
92}

103/**
104 * In-memory registry of connectors. A single shared instance lives in
105 * `./index.ts`; feature agents call `.register()` there.
106 */
107export class ConnectorRegistry {
108  private readonly connectors = new Map<string, Connector>()
109
110  register(connector: Connector): void {
111    if (this.connectors.has(connector.id)) {
112      throw new Error(`Connector "${connector.id}" is already registered`)
113    }
114    this.connectors.set(connector.id, connector)
115  }
116
117  get(id: string): Connector | undefined {
118    return this.connectors.get(id)
119  }
120
121  has(id: string): boolean {
122    return this.connectors.has(id)
123  }
124
125  all(): Connector[] {
126    return [...this.connectors.values()]
127  }
128
129  byDomain(domain: ConnectorDomain): Connector[] {
130    return this.all().filter((c) => c.domain === domain)
131  }
132
133  /** Serializable catalog for tools / UI (drops the search/fetch functions). */
134  catalog(): CatalogEntry[] {
135    return this.all().map(({ id, name, domain, description, homepage }) => ({
136      id,
137      name,
138      domain,
139      description,
140      homepage,
141    }))
142  }