Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

17.5 KB
Raw Blame
/**
 * 把回答正文里对「沙箱生成文件」的引用,接到 artifact 下载链路上。
 *
 * 模型会用 Markdown 图片语法引用它在沙箱里生成的文件(提示词规定写成
 * `![说明](sandbox:文件名)`),服务端在落库前把它改写成该文件的稳定句柄
 * `resource://<handle>` —— 与知识库图片、聊天附件同一种引用形式。两种写法
 * 都指向同一份 `Message.Artifacts`:
 *
 *   - `resource://<handle>` —— 落库后的权威形式,历史会话读到的就是它;
 *   - `sandbox:<文件名>`    —— 模型原始写法,本轮流式输出尚未改写时用到。
 *
 * 由于句柄形式与知识库图片完全一致,一条回答里同时出现「检索到的知识库图」
 * 和「技能生成的图」是常态。所以句柄对不上本消息产物列表时必须返回 null,
 * 交回默认的受保护图片渲染,而不是显示「文件不可用」。
 *
 * 图片类产物内联显示(带鉴权拉取后换成 blob),其余类型(HTML 图表、CSV、
 * 文档等)渲染成一张卡片,点击后交给右侧沙箱面板的产物页预览——正文里塞一个
 * 1MB 的自包含 HTML iframe 既慢又不安全。
 *
 * 已被用户删除的产物在列表里是墓碑(带 deleted_at),渲染成一张置灰的不可点击
 * 卡片。调用方**不要**把墓碑过滤掉再传进来:过滤了句柄就对不上本条回答的产物,
 * 会被当成知识库图片走受保护图片渲染,最终显示成一张拉不出来的裂图。
 */

import type { Renderer } from 'marked';

import { escapeHTML } from './security.ts';
import { renderArtifactFileIcon } from './artifactFileIcon';

/** 与后端 artifactListItem / SSE publicArtifactViews 对齐的最小字段集。 */
export interface ArtifactRefMeta {
  index: number;
  file_name: string;
  file_type?: string;
  /** `resource://<handle>`。后端未启用资源目录时为空,此时只能按文件名解析。 */
  handle?: string;
  /**
   * 历史消息直接携带 `Message.Artifacts`,其中的存储引用叫 `url`。与 handle
   * 同义,取其一即可。
   */
  url?: string;
  /**
   * 用户删除该文件的时间。墓碑条目**必须**留在传给渲染器的列表里:一是下标就是
   * 下载地址,抽掉会让后面的文件整体错位;二是句柄只有对得上才知道它属于本条
   * 回答,对不上会被当成知识库图片走受保护图片渲染,最后显示成一张裂图。
   */
  deleted_at?: string | null;
}

export interface ArtifactRefContext {
  sessionId: string;
  messageId: string;
}

export interface ArtifactRefLabels {
  /** 卡片副标题,如「点击预览」。 */
  previewHint: string;
  /** 本轮已结束但引用对不上任何产物时的副标题,如「文件不可用」。 */
  missingHint: string;
  /** 文件已被用户删除时的副标题,如「文件已删除」。 */
  deletedHint: string;
}

const RESOURCE_HANDLE_RE = /^resource:\/\/([A-Za-z0-9_-]{22})$/;
const SANDBOX_NAME_RE = /^sandbox:(?:\/\/)?(.+)$/i;
const IMAGE_EXTENSIONS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'avif']);
const TRANSPARENT_PIXEL =
  'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==';

type ArtifactRef = { kind: 'handle'; handle: string } | { kind: 'name'; name: string };

function parseArtifactRef(href: string): ArtifactRef | null {
  const trimmed = (href || '').trim();
  if (!trimmed) return null;

  const handleMatch = trimmed.match(RESOURCE_HANDLE_RE);
  if (handleMatch) {
    return { kind: 'handle', handle: handleMatch[1] };
  }

  const nameMatch = trimmed.match(SANDBOX_NAME_RE);
  if (!nameMatch) return null;
  let name = nameMatch[1].trim();
  try {
    name = decodeURIComponent(name);
  } catch {
    // 保留原样:文件名里出现裸 % 时 decodeURIComponent 会抛错。
  }
  // 目录前缀不带信息量,产物是按文件名索引的。
  name = name.split('/').pop() || '';
  return name ? { kind: 'name', name } : null;
}

/**
 * 该链接目标是否可能是沙箱产物引用。
 *
 * 句柄形式与知识库图片同形,因此这里为真只说明「值得交给产物解析试一次」,
 * 不代表本消息真有这个文件。
 */
export function isArtifactRefHref(href: string): boolean {
  return parseArtifactRef(href) !== null;
}

function artifactHandle(artifact: ArtifactRefMeta): string {
  const raw = (artifact.handle || artifact.url || '').trim();
  return raw.match(RESOURCE_HANDLE_RE)?.[1] || '';
}

const CODE_SPAN_OR_FENCE_RE = /(```[\s\S]*?```|~~~[\s\S]*?~~~|`[^`\n]*`)/g;

/**
 * 扫描一个 Markdown 链接目标,返回括号内的原文与右括号位置。
 *
 * 用括号配对而不是正则,是因为技能生成的文件名经常带括号和空格
 * (`腾讯控股(00700) 成交量_838ccc.html`)。marked 会在第一个空格处把目标截断,
 * 于是引用永远匹配不上产物;而按深度扫描能准确找到真正闭合链接的那个右括号。
 */
function scanLinkDestination(text: string, openIndex: number): { inner: string; end: number } | null {
  let depth = 1;
  for (let i = openIndex + 1; i < text.length; i += 1) {
    const ch = text[i];
    if (ch === '\n') return null;
    if (ch === '(') depth += 1;
    else if (ch === ')') {
      depth -= 1;
      if (depth === 0) return { inner: text.slice(openIndex + 1, i), end: i };
    }
  }
  return null;
}

/** 把目标里可选的标题部分(`dest "title"`)拆出来。 */
function splitDestinationTitle(inner: string): { destination: string; title: string } {
  const match = inner.match(/^([\s\S]*?)(\s+(?:"[^"]*"|'[^']*'))$/);
  if (!match) return { destination: inner.trim(), title: '' };
  return { destination: match[1].trim(), title: match[2] };
}

/** `](` 之前必须是同一行上闭合的 `[...]`,否则这不是一个链接。 */
function hasLinkLabelBefore(text: string, closeBracketIndex: number): boolean {
  for (let i = closeBracketIndex - 1; i >= 0; i -= 1) {
    const ch = text[i];
    if (ch === '\n') return false;
    if (ch === '[') return true;
  }
  return false;
}

function normalizeSegment(segment: string): string {
  if (!segment.includes('](')) return segment;

  let out = '';
  let cursor = 0;
  while (cursor < segment.length) {
    const relative = segment.slice(cursor).indexOf('](');
    if (relative < 0) break;
    const closeBracket = cursor + relative;
    const open = closeBracket + 1;

    if (!hasLinkLabelBefore(segment, closeBracket)) {
      out += segment.slice(cursor, open + 1);
      cursor = open + 1;
      continue;
    }
    const scanned = scanLinkDestination(segment, open);
    if (!scanned) {
      out += segment.slice(cursor, open + 1);
      cursor = open + 1;
      continue;
    }

    const { destination, title } = splitDestinationTitle(scanned.inner);
    const ref = parseArtifactRef(destination);
    if (!ref || ref.kind !== 'name') {
      out += segment.slice(cursor, scanned.end + 1);
      cursor = scanned.end + 1;
      continue;
    }

    // Percent-encode so marked sees a single whitespace-free token;
    // parseArtifactRef decodes it again on the way out.
    out += `${segment.slice(cursor, open + 1)}sandbox:${encodeURIComponent(ref.name)}${title})`;
    cursor = scanned.end + 1;
  }
  return out + segment.slice(cursor);
}

/**
 * 在 marked 解析前,把 `sandbox:` 引用的目标规整成不含空格的单个 token。
 *
 * 不做这一步的话,带空格的文件名会被 marked 从空格处切开,目标只剩前半截,
 * 后半截漏成正文——正是「卡片名字被截断 + 尾巴变成裸文本」那个现象。
 * 代码块内的示例原样保留。
 */
export function normalizeSandboxArtifactRefs(markdown: string): string {
  if (!markdown || !markdown.includes('](')) return markdown;
  if (!/\]\(\s*sandbox:/i.test(markdown)) return markdown;

  const parts = markdown.split(CODE_SPAN_OR_FENCE_RE);
  for (let i = 0; i < parts.length; i += 2) {
    parts[i] = normalizeSegment(parts[i]);
  }
  return parts.join('');
}

/** 把引用解析成具体产物;解析不到(尚未收集完/文件名对不上)返回 null。 */
export function resolveArtifactRef(
  href: string,
  artifacts: ArtifactRefMeta[] | undefined | null,
): ArtifactRefMeta | null {
  const ref = parseArtifactRef(href);
  if (!ref || !artifacts?.length) return null;

  if (ref.kind === 'handle') {
    return artifacts.find((item) => artifactHandle(item) === ref.handle) || null;
  }
  return artifacts.find((item) => (item.file_name || '').trim() === ref.name) || null;
}

function fileExtension(fileName: string): string {
  const base = (fileName || '').trim().toLowerCase();
  const dot = base.lastIndexOf('.');
  return dot > 0 ? base.slice(dot + 1) : '';
}

/**
 * 是否按图片内联渲染。SVG 刻意排除:它是可执行内容,走卡片 + 预览的沙箱路径。
 */
function rendersAsImage(artifact: ArtifactRefMeta): boolean {
  const ext = fileExtension(artifact.file_name);
  if (ext) return IMAGE_EXTENSIONS.has(ext);
  const type = (artifact.file_type || '').toLowerCase();
  return type.startsWith('image/') && !type.includes('svg');
}

// blob URL 按 (会话, 消息, 下标) 缓存,并挂在 window 上:Vite 热更新会替换模块
// 但不会重建文档,模块级 Map 会让已加载的图片退回占位图。
type ArtifactBlobState = { blobByKey: Map<string, string>; inflight: Map<string, Promise<string | null>> };

const artifactBlobState: ArtifactBlobState = (() => {
  const fresh = (): ArtifactBlobState => ({ blobByKey: new Map(), inflight: new Map() });
  if (typeof window === 'undefined') return fresh();
  const scope = window as typeof window & { __weknoraArtifactBlobCacheV1__?: ArtifactBlobState };
  scope.__weknoraArtifactBlobCacheV1__ ||= fresh();
  return scope.__weknoraArtifactBlobCacheV1__;
})();

function blobCacheKey(ctx: ArtifactRefContext, index: number): string {
  return `${ctx.sessionId}\u0000${ctx.messageId}\u0000${index}`;
}

// 与 chatMarkdownRenderer 的流式图片骨架同一个类名,样式复用。
const STREAMING_PLACEHOLDER =
  '<span class="streaming-image-loading"><span class="streaming-image-loading__skeleton"></span></span>';

/**
 * 卡片的三种状态:
 *   - `ready`   —— 正常,可点击打开预览;
 *   - `pending` —— 本轮已结束但引用对不上任何产物(模型引用了不存在的文件);
 *   - `deleted` —— 文件确实生成过,但已被用户删除,字节已回收。
 * 后两种都不可点击,但要能区分开:一个是「从来没有过」,一个是「你自己删掉了」。
 */
type ArtifactCardVariant = 'ready' | 'pending' | 'deleted';

function renderCard(
  fileName: string,
  hint: string,
  index: number | null,
  variant: ArtifactCardVariant,
): string {
  const safeName = escapeHTML(fileName);
  const safeHint = escapeHTML(hint);
  // 卡片必须是内联元素:marked 会把图片包在 <p> 里,块级元素会被 HTML 解析器
  // 提到段落外面,破坏正文结构。
  const interactive = variant === 'ready' && index !== null
    ? ` data-artifact-index="${index}" role="button" tabindex="0"`
    : '';
  const state = variant === 'ready' ? '' : ` artifact-ref-card--${variant}`;
  return (
    `<span class="artifact-ref-card${state}"${interactive} title="${safeName}">`
    + `<span class="artifact-ref-card__icon" aria-hidden="true">${renderArtifactFileIcon(fileName)}</span>`
    + '<span class="artifact-ref-card__text">'
    + `<span class="artifact-ref-card__name">${safeName}</span>`
    + `<span class="artifact-ref-card__hint">${safeHint}</span>`
    + '</span></span>'
  );
}

function renderImage(
  artifact: ArtifactRefMeta,
  alt: string,
  ctx: ArtifactRefContext | null,
): string {
  const safeAlt = escapeHTML(alt || artifact.file_name || '');
  // 已经拉取过就直接给 blob:流式重渲染会重建 <img>,否则每帧都会闪回占位图。
  const cached = ctx ? artifactBlobState.blobByKey.get(blobCacheKey(ctx, artifact.index)) : undefined;
  const src = cached || TRANSPARENT_PIXEL;
  const loading = cached ? '' : ' data-img-loading="1"';
  return (
    `<img class="markdown-image artifact-ref-image" src="${src}" alt="${safeAlt}"`
    + ` data-artifact-index="${artifact.index}"${loading}>`
  );
}

/**
 * 渲染一个 Markdown 图片/链接目标。
 *
 * 返回 null 表示这不是沙箱产物引用,调用方应回落到默认渲染(普通图片、
 * `resource://` 受保护图片、外链等一律不受影响)。
 * 返回空字符串表示目标为空,调用方不应再画裂图。
 */
export function renderArtifactReference(args: {
  href: string;
  alt?: string;
  artifacts?: ArtifactRefMeta[] | null;
  labels: ArtifactRefLabels;
  context?: ArtifactRefContext | null;
  /** 本轮回答还在生成中。产物要到本轮结束才会收集,此时解析不到是正常的。 */
  streaming?: boolean;
}): string | null {
  const href = (args.href || '').trim();
  if (!href) return '';
  const ref = parseArtifactRef(href);
  if (!ref) return null;

  const artifact = resolveArtifactRef(href, args.artifacts);
  if (!artifact) {
    // 句柄对不上本消息的产物,说明这是别的受保护文件(知识库检索图、
    // 附件图……)。交回默认渲染,由 hydrateProtectedFileImages 带鉴权拉取。
    if (ref.kind === 'handle') return null;
    // 产物列表要到本轮结束才随 complete 事件到达,流式期间必然解析不到。
    // 这时给骨架屏而不是卡片:既避免半截文件名闪一下,也不会把「生成中」
    // 这种状态留在一个其实已经结束的回答里。
    if (args.streaming) return STREAMING_PLACEHOLDER;
    // 本轮已结束仍对不上,说明模型引用了并不存在的文件。如实说明,不要
    // 继续显示「生成中」。
    const fallbackName = ref.name || (args.alt || '').trim();
    if (!fallbackName) return '';
    return renderCard(fallbackName, args.labels.missingHint, null, 'pending');
  }

  // 用户删过的文件字节已经回收,下载会 404。图片类产物同样降级成卡片:走
  // renderImage 只会拉取失败,留下一张永远加载不出来的裂图。
  if (artifact.deleted_at) {
    const name = artifact.file_name || (args.alt || '').trim();
    if (!name) return '';
    return renderCard(name, args.labels.deletedHint, null, 'deleted');
  }

  if (rendersAsImage(artifact)) {
    return renderImage(artifact, args.alt || '', args.context ?? null);
  }
  return renderCard(artifact.file_name, args.labels.previewHint, artifact.index, 'ready');
}

async function loadArtifactBlobURL(ctx: ArtifactRefContext, index: number): Promise<string | null> {
  const key = blobCacheKey(ctx, index);
  const cached = artifactBlobState.blobByKey.get(key);
  if (cached) return cached;

  let task = artifactBlobState.inflight.get(key);
  if (!task) {
    task = (async () => {
      try {
        // Imported lazily so parsing/rendering stays free of the axios
        // transport — those parts run in plain Node during unit tests.
        const { downloadArtifact } = await import('@/api/chat');
        const blob = await downloadArtifact(ctx.sessionId, ctx.messageId, index);
        const blobURL = URL.createObjectURL(blob);
        artifactBlobState.blobByKey.set(key, blobURL);
        return blobURL;
      } catch (error) {
        console.warn('[sandboxArtifactRefs] artifact image load failed:', error);
        return null;
      } finally {
        artifactBlobState.inflight.delete(key);
      }
    })();
    artifactBlobState.inflight.set(key, task);
  }
  return task;
}

/**
 * 把正文里的产物图片换成带鉴权拉取的 blob。
 *
 * 与 hydrateProtectedFileImages 同样是幂等的:已换过的元素带 authHydrated 标记,
 * 相同文件的并发请求共享同一个 Promise。
 */
export async function hydrateArtifactImages(
  root: ParentNode | null | undefined,
  ctx: ArtifactRefContext | null | undefined,
): Promise<void> {
  if (!root || !ctx?.sessionId || !ctx?.messageId) return;

  const images = Array.from(
    root.querySelectorAll<HTMLImageElement>('img.artifact-ref-image[data-artifact-index]'),
  ).filter((img) => img.dataset.authHydrated !== '1');
  if (!images.length) return;

  await Promise.all(images.map(async (img) => {
    const index = Number(img.getAttribute('data-artifact-index'));
    if (!Number.isInteger(index) || index < 0) return;
    img.dataset.authHydrated = '1';

    const blobURL = await loadArtifactBlobURL(ctx, index);
    if (!blobURL) {
      img.dataset.authHydrated = '0';
      return;
    }
    img.src = blobURL;
    img.removeAttribute('data-img-loading');
  }));
}

/**
 * 从点击/键盘事件里取出被激活的产物卡片下标;返回 null 表示事件与卡片无关。
 */
export function artifactIndexFromEventTarget(target: EventTarget | null): number | null {
  if (!(target instanceof Element)) return null;
  const card = target.closest('.artifact-ref-card[data-artifact-index]');
  if (!card) return null;
  const index = Number(card.getAttribute('data-artifact-index'));
  return Number.isInteger(index) && index >= 0 ? index : null;
}

/** Links and images referencing a generated file must share its authorized
 * preview path. Leave unrelated links to the original Markdown renderer. */
export function installArtifactLinkRenderer(
  renderer: Renderer,
  options: () => Omit<Parameters<typeof renderArtifactReference>[0], 'href' | 'alt'>,
): void {
  const defaultLink = renderer.link;
  renderer.link = function (token) {
    const artifact = renderArtifactReference({ ...options(), href: token.href, alt: token.text });
    return artifact ?? defaultLink.call(this, token);
  };
}