dsh-data-domain-knowledge 0.1.0-alpha.1

package/src/client/styles.ts

@@ -0,0 +1,11 @@
+/**
+ * The plugins ship plain CSS (no CSS modules), so a style key is simply its
+ * `tita-` class. The proxy keeps `styles.foo` / `styles[`foo${Tone}`]` readable
+ * at the call site without a hand-maintained lookup table.
+ */
+export const styles: Record<string, string> = new Proxy({}, { get: (_target, key) => `tita-${String(key)}` })
+
+/** `blue` → `Blue`, used to build tone-suffixed class names. */
+export function toneSuffix(tone: string): string {
+  return `${tone[0]!.toUpperCase()}${tone.slice(1)}`
+}

package/src/client/useFitScale.ts

@@ -0,0 +1,68 @@
+/**
+ * 画布的「适应宽度 / 1:1」两档缩放。
+ *
+ * **为什么不用 G6 的 `fitView` / `zoomTo`**：这版 G6（5.1.1）对 HTML 节点算不出内容
+ * 包围盒，两个 API 都实测无效 —— 画布按 0.45 定了尺寸，内容仍按 1:1 画出去被裁掉。
+ * 所以做法是：**画布永远按设计尺寸渲染，再缩整块板**。比例是我们算出来的，
+ * 不依赖 G6 对内容边界的判断；命中判定不受影响（g 用元素的 bounding rect 反算坐标，
+ * 均匀缩放对它透明，点选已在浏览器里验证过）。
+ *
+ * 两个画布（Agent 概览的架构图、知识库的知识图谱）都用它 —— 两处各写一份，
+ * 迟早会出现「一张图能适应、另一张不能」。
+ */
+
+import { useEffect, useState, type RefObject } from 'react'
+
+/** 窄栏下的两档。`fit` = 整图缩到容器，`actual` = 1:1（滚动查看）。 */
+export type ZoomMode = 'fit' | 'actual'
+
+export interface FitScale {
+  scale: number
+  /** 缩放后的板高；容器高度就用它（`fit` 档下正好没有可滚的余量）。 */
+  boardH: number
+}
+
+/**
+ * `scroller` 由调用方持有并挂到滚动容器上 —— 组件自己拥有它的 DOM，
+ * 这里只负责量。
+ *
+ * @param contentW 设计宽度
+ * @param contentH 设计高度
+ * @param enabled  容器不可见时不要量（隐藏容器尺寸为 0，算出来的比例是 0）
+ * @param fullscreen 全屏时两个方向都按容器算；窄栏只有宽度可用
+ * @param mode 缩放档
+ */
+export function useFitScale(
+  scroller: RefObject<HTMLDivElement | null>,
+  contentW: number,
+  contentH: number,
+  enabled: boolean,
+  fullscreen: boolean,
+  mode: ZoomMode,
+): FitScale {
+  /**
+   * 可视尺寸。用 `offsetWidth/Height` 而不是 `clientWidth/clientHeight`：后者会随
+   * 滚动条的有无变化，而板高又由缩放比算出来 —— 那是一条会自己来回抖的回路。
+   */
+  const [viewport, setViewport] = useState({ w: 0, h: 0 })
+
+  useEffect(() => {
+    const el = scroller.current
+    if (!el || !enabled) return undefined
+    const update = (): void => setViewport(prev => {
+      const next = { w: el.offsetWidth, h: el.offsetHeight }
+      return prev.w === next.w && prev.h === next.h ? prev : next
+    })
+    update()
+    const ro = new ResizeObserver(update)
+    ro.observe(el)
+    return () => ro.disconnect()
+  }, [enabled, fullscreen])
+
+  // 窄栏只有宽度是可用的：高度由板高自己决定，拿它去算比例就成了一条回路，
+  // 所以那里高度按设计高度算（即「只按宽度适应」）。
+  const availW = viewport.w || contentW
+  const availH = fullscreen ? (viewport.h || contentH) : contentH
+  const scale = mode === 'actual' ? 1 : Math.min(1, availW / contentW, availH / contentH)
+  return { scale, boardH: contentH * scale }
+}

package/src/config-schema.ts

@@ -0,0 +1,45 @@
+/**
+ * 插件 entry 的配置 schema（0.1.7）。
+ *
+ * ## 为什么单独一个模块
+ *
+ * 0.1.7 删掉了「设置命名空间 + `settings.installSection`」这一整套 API，改成
+ * **设置就是插件自己 entry 的 config**：schema 在这里声明，初值由 profile patch 的
+ * `config:` 提供，设置页里的改动由 `configEditor` 写回同一处，客户端按**路径**寻址
+ * （`{op:'set', path:['intent','categories']}`）。
+ *
+ * 三组沿用原来的三个命名空间边界，因为它们在语义上确实是三块（知识库 / 意图引擎 /
+ * 转换内核），缓存键与默认值各不相同 —— 变的只是「它们住在同一个 entry 下」。
+ *
+ * 「单独一个模块」的理由和 `settings-schema.ts`、`intent/settings-schema.ts` 一样，
+ * 是**可测**：`tests/settings-schema.test.mjs` 要能 import 这个 schema 并把它解析
+ * 一遍，而 `index.ts` 会拉进工具层（`dsh-tools` 的 `dsh-sandbox` peer 没有安装，
+ * `node --test` 里拉不起来）。所以组合必须发生在没有工具依赖的地方。
+ *
+ * @module
+ */
+
+import z from '@deepseek-ai/schemastery'
+import { KNOWLEDGE_SETTINGS_SCHEMA } from './settings-schema.js'
+import { INTENT_SETTINGS_SCHEMA } from './intent/settings-schema.js'
+import { CONVERT_SETTINGS_SCHEMA } from './convert/settings-schema.js'
+import type { KnowledgeConfig } from './types.js'
+import type { IntentSettings } from './intent/types.js'
+import type { ConvertPluginConfig } from './convert/types.js'
+
+/**
+ * 标注 `Schemastery` 是 TS2742 的要求（见 `intent/settings-schema.ts`）：导出物必须
+ * 有一个能被命名的类型，否则 `.d.ts` 里会写进 cosmokit 的 `.pnpm` 路径。
+ */
+export const Config: Schemastery = z.object({
+  knowledge: KNOWLEDGE_SETTINGS_SCHEMA,
+  intent: INTENT_SETTINGS_SCHEMA,
+  convert: CONVERT_SETTINGS_SCHEMA,
+})
+
+/** `Config` 的取值形态。三组都可选：缺的字段由 schema 默认值补齐。 */
+export interface KnowledgePluginConfig {
+  knowledge?: Partial<KnowledgeConfig>
+  intent?: Partial<IntentSettings>
+  convert?: Partial<ConvertPluginConfig>
+}

package/src/convert/core-loader.ts

@@ -0,0 +1,68 @@
+/**
+ * Lazy, optional access to the conversion kernel.
+ *
+ * `dsh-convert-core` is declared as an **optionalDependency**: it
+ * pulls in `@firecrawl/anydoc`, which ships a platform-specific prebuilt native
+ * binding. A user who only wants to ingest Markdown must still be able to
+ * install and run the knowledge plugin, so the kernel is imported on first use
+ * and a missing kernel degrades to one actionable error instead of taking the
+ * whole plugin (SourceRaw, compile, recall) down with it.
+ *
+ * Guardrail this file exists to enforce: nothing else in the plugin may import
+ * the kernel eagerly.
+ */
+
+export type ConvertCoreModule = typeof import('dsh-convert-core')
+
+export type ConvertCoreLoader = () => Promise<ConvertCoreModule>
+
+const INSTALL_HINT = '转换内核是可选依赖：装上 dsh-convert-core 后重试（pnpm --filter dsh-data-domain-knowledge install）。knowledge 的录入、编译与召回不依赖它。'
+
+/** Raised when the optional kernel cannot be loaded. */
+export class ConvertCoreMissingError extends Error {
+  readonly code = 'DEPENDENCY_MISSING'
+  readonly retryable = true
+  readonly suggestion = INSTALL_HINT
+  constructor(cause?: unknown) {
+    const detail = cause instanceof Error ? cause.message : cause === undefined ? '' : String(cause)
+    super(`转换内核 dsh-convert-core 不可用${detail ? `：${detail}` : ''}`)
+    this.name = 'ConvertCoreMissingError'
+  }
+}
+
+async function importKernel(): Promise<ConvertCoreModule> {
+  return await import('dsh-convert-core')
+}
+
+let loader: ConvertCoreLoader = importKernel
+let cached: ConvertCoreModule | undefined
+let inflight: Promise<ConvertCoreModule> | undefined
+
+/** Load (and memoise) the kernel, or throw `ConvertCoreMissingError`. */
+export async function loadConvertCore(): Promise<ConvertCoreModule> {
+  if (cached) return cached
+  inflight ??= loader()
+  try {
+    const module = await inflight
+    cached = module
+    return module
+  } catch (cause) {
+    inflight = undefined
+    throw cause instanceof ConvertCoreMissingError ? cause : new ConvertCoreMissingError(cause)
+  }
+}
+
+/** Whether the kernel is already loaded; used by capabilities reporting. */
+export function convertCoreLoaded(): boolean {
+  return cached !== undefined
+}
+
+/**
+ * Test seam. Pass a loader to simulate a missing/broken kernel, or `undefined`
+ * to restore the real dynamic import. Never used by production code.
+ */
+export function setConvertCoreLoader(next?: ConvertCoreLoader): void {
+  loader = next ?? importKernel
+  cached = undefined
+  inflight = undefined
+}