World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
A citation opens before it leaves (#779)
WaylandYang82d0e6ce456f
diff --git a/web/src/citations.test.ts b/web/src/citations.test.tsnew file mode 100644index 00000000..0e5d5c94--- /dev/null+++ b/web/src/citations.test.ts@@ -0,0 +1,114 @@+import { describe, expect, it } from "vitest";+import { citeHref, rehypeCitations, splitCitations } from "./citations";++describe("splitCitations", () => {+ it("keeps plain text in one piece", () => {+ expect(splitCitations("no marks here")).toEqual([{ text: "no marks here" }]);+ });++ it("reads the three shapes the model writes", () => {+ expect(splitCitations("a[1]b[2][3]c[4, 5]d[6,7]")).toEqual([+ { text: "a" },+ { cite: [1] },+ { text: "b" },+ { cite: [2] },+ { cite: [3] },+ { text: "c" },+ { cite: [4, 5] },+ { text: "d" },+ { cite: [6, 7] },+ ]);+ });++ it("leaves an unfinished marker alone while the answer is still streaming", () => {+ expect(splitCitations("risk factors [2")).toEqual([+ { text: "risk factors [2" },+ ]);+ });++ it("is not fooled by brackets that hold words", () => {+ expect(splitCitations("see [note] and [3]")).toEqual([+ { text: "see [note] and " },+ { cite: [3] },+ ]);+ });++ it("starts each call from the beginning", () => {+ // 共用一个 g 正则会让第二段从上一次的 lastIndex 接着找,`[1]` 就丢了+ expect(splitCitations("x[1]")).toEqual([{ text: "x" }, { cite: [1] }]);+ expect(splitCitations("x[1]")).toEqual([{ text: "x" }, { cite: [1] }]);+ });+});++describe("rehypeCitations", () => {+ const run = (tree: unknown) => {+ rehypeCitations()(tree as never);+ return tree;+ };++ it("turns a marker into a cite link and keeps the text around it", () => {+ const tree = {+ type: "root",+ children: [+ {+ type: "element",+ tagName: "p",+ children: [{ type: "text", value: "disclosed [2][3]" }],+ },+ ],+ };+ expect(run(tree)).toEqual({+ type: "root",+ children: [+ {+ type: "element",+ tagName: "p",+ children: [+ { type: "text", value: "disclosed " },+ {+ type: "element",+ tagName: "a",+ properties: { href: "#cite-2" },+ children: [{ type: "text", value: "[2]" }],+ },+ {+ type: "element",+ tagName: "a",+ properties: { href: "#cite-3" },+ children: [{ type: "text", value: "[3]" }],+ },+ ],+ },+ ],+ });+ });++ it("leaves links and code alone", () => {+ const opaque = (tagName: string) => ({+ type: "root",+ children: [+ {+ type: "element",+ tagName,+ children: [{ type: "text", value: "[1]" }],+ },+ ],+ });+ for (const tag of ["a", "code", "pre"]) {+ expect(run(opaque(tag))).toEqual(opaque(tag));+ }+ });+});++describe("citeHref", () => {+ it("reads back what the plugin wrote", () => {+ expect(citeHref("#cite-4")).toEqual([4]);+ expect(citeHref("#cite-4,5")).toEqual([4, 5]);+ });++ it("passes an ordinary link through", () => {+ expect(citeHref("https://example.com")).toBeNull();+ expect(citeHref(undefined)).toBeNull();+ expect(citeHref("#cite-")).toBeNull();+ });+});diff --git a/web/src/citations.ts b/web/src/citations.tsnew file mode 100644index 00000000..ebfaeada--- /dev/null+++ b/web/src/citations.ts@@ -0,0 +1,114 @@+// 正文里的引用标记。+//+// 模型写的是 `[1]`、`[1][2]`、`[1, 2]`、`[1,2]`。**哪些被画成角标,和哪些被列进+// 落款,必须是同一套判定**——否则正文里点得动的那个号在下面找不到对应的行。+// 所以这里只有一处形状,`liveAnswer.citedSources` 与 `rehypeCitations` 共用它。+//+// 每次现造一个正则:`g` 的 `lastIndex` 跟着上一次调用走,共用一个实例会让+// 第二段文本从中间开始匹配。++/** `[1]` / `[1][2]` / `[1, 2]` / `[1,2]`——括号里只有数字与分隔符才算引用 */+export const citeRe = () => /\[(\d+(?:\s*[,,]\s*\d+)*)\]/g;++/** 一个标记里的号:`[1, 2]` 是两个 */+export function citeNumbers(spec: string): number[] {+ return spec+ .split(/[,,]/)+ .map((s) => Number(s.trim()))+ .filter((n) => Number.isInteger(n) && n > 0);+}++export type CitePiece = { text: string } | { cite: number[] };++/** 把一段纯文本切成「文字」与「一组引用号」。+ *+ * 流式中还没收尾的 `[1` 匹配不上——要等右括号,所以角标不会先画出半个再变形。 */+export function splitCitations(text: string): CitePiece[] {+ const out: CitePiece[] = [];+ const re = citeRe();+ let last = 0;+ for (let m = re.exec(text); m; m = re.exec(text)) {+ const ns = citeNumbers(m[1]);+ if (!ns.length) continue;+ if (m.index > last) out.push({ text: text.slice(last, m.index) });+ out.push({ cite: ns });+ last = m.index + m[0].length;+ }+ if (!out.length) return [{ text }];+ if (last < text.length) out.push({ text: text.slice(last) });+ return out;+}++/* ── rehype 插件 ────────────────────────────────────────────────────────── */++/** hast 里我们要动的那两种节点。用结构类型而不是 `@types/hast`:+ * 这里只读 `children` / `value` / `tagName`,不值得为它多一个依赖 */+type HastText = { type: "text"; value: string };+type HastNode = {+ type: string;+ tagName?: string;+ value?: string;+ properties?: Record<string, unknown>;+ children?: HastNode[];+};++/** 这些元素里面的方括号不是引用:链接的锚文本可能正好是一个数字,+ * 代码块里的 `[0]` 是下标 */+const OPAQUE = new Set(["a", "code", "pre"]);++const CITE_PREFIX = "#cite-";++/** 正文里的 `[n]` 变成 `<a href="#cite-n">`。+ *+ * **为什么是 `a` 而不是一个自定义标签**:react-markdown 把 hast 属性转成 JSX+ * 属性,`href` 是它本来就认得的那一个,于是 `components.a` 拿到的是有类型的+ * props;自定义标签得从 `node.properties` 里摸,摸出来的是 `unknown`。+ *+ * **为什么是锚点而不是自造一个 `cite:` 协议**:react-markdown 默认只放行+ * http/https/mailto/tel 与相对地址,别的协议会被洗成空串——角标于是退化成一个+ * 下划线的链接,点不开。`#` 开头是相对地址。 */+export function rehypeCitations() {+ return (tree: HastNode) => walk(tree);+}++function walk(node: HastNode): void {+ const kids = node.children;+ if (!kids?.length) return;+ let changed = false;+ const out: HastNode[] = [];+ for (const child of kids) {+ if (child.type === "text" && typeof child.value === "string") {+ const pieces = splitCitations(child.value);+ if (pieces.length === 1 && "text" in pieces[0]) {+ out.push(child);+ continue;+ }+ changed = true;+ for (const p of pieces) {+ if ("text" in p) {+ if (p.text) out.push({ type: "text", value: p.text } as HastText);+ } else {+ out.push({+ type: "element",+ tagName: "a",+ properties: { href: `${CITE_PREFIX}${p.cite.join(",")}` },+ children: [{ type: "text", value: `[${p.cite.join(", ")}]` }],+ });+ }+ }+ continue;+ }+ if (!(child.type === "element" && OPAQUE.has(child.tagName ?? ""))) {+ walk(child);+ }+ out.push(child);+ }+ if (changed) node.children = out;+}++/** `#cite-1,2` → `[1, 2]`;不是引用链接就给 null */+export function citeHref(href: string | undefined): number[] | null {+ if (!href?.startsWith(CITE_PREFIX)) return null;+ const ns = citeNumbers(href.slice(CITE_PREFIX.length));+ return ns.length ? ns : null;+}diff --git a/web/src/i18n/en.ts b/web/src/i18n/en.tsindex dd315ed8..e217ed95 100644--- a/web/src/i18n/en.ts+++ b/web/src/i18n/en.ts@@ -762,6 +762,8 @@ export const en = {cancel: "Cancel",// 这条回答背后一条来源都没有(#547)。是事实陈述,所以每条都挂,不猜哪条该挂noSources: "No sources consulted",+ // 预览浮窗右上角那条出路:看完这一段还想看整篇的人走这里+ openOriginal: "Open original",},graph: {// 还没判出类型的实体(0009)。不是一个类,是"这一格还空着"diff --git a/web/src/i18n/zh.ts b/web/src/i18n/zh.tsindex 0336f1bb..90c07eeb 100644--- a/web/src/i18n/zh.ts+++ b/web/src/i18n/zh.ts@@ -700,6 +700,7 @@ export const zh: Strings = {deleteBtn: "删除",cancel: "取消",noSources: "未引用任何来源",+ openOriginal: "打开原文",},graph: {untyped: "未分类",diff --git a/web/src/liveAnswer.ts b/web/src/liveAnswer.tsindex e008b310..40a14b24 100644--- a/web/src/liveAnswer.ts+++ b/web/src/liveAnswer.ts@@ -19,6 +19,7 @@// 于是改成一张表:谁开场谁拿句柄,读谁写谁都有名有姓。`send` 的守卫不用改——// 它本来问的就是「这一场在不在流」,现在这个问题终于只关于这一场。import type { ChatStep, Source } from "./api";+import { citeNumbers, citeRe } from "./citations";export interface Turn {role: "user" | "assistant";@@ -37,8 +38,8 @@ export interface Turn {export function citedSources(turn: Turn): Source[] {if (!turn.sources?.length) return [];const cited = new Set<number>();- for (const m of turn.content.matchAll(/\[(\d+(?:\s*[,,]\s*\d+)*)\]/g)) {- for (const n of m[1].split(/[,,]/)) cited.add(Number(n.trim()));+ for (const m of turn.content.matchAll(citeRe())) {+ for (const n of citeNumbers(m[1])) cited.add(n);}return turn.sources.filter((s) => cited.has(s.n));}diff --git a/web/src/pages/Chat.tsx b/web/src/pages/Chat.tsxindex 9841ecd1..432ff985 100644--- a/web/src/pages/Chat.tsx+++ b/web/src/pages/Chat.tsx@@ -3,7 +3,7 @@行动轨迹(steps)与引用(sources)随消息落库,历史回放与实时流共用渲染。 */import { memo, useEffect, useRef, useState, useSyncExternalStore } from "react";import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";-import { Link, useNavigate, useParams } from "@tanstack/react-router";+import { useNavigate, useParams } from "@tanstack/react-router";import Markdown from "react-markdown";import remarkGfm from "remark-gfm";import rehypeHighlight from "rehype-highlight";@@ -33,8 +33,11 @@ import {streamChat,type ChatStep,type ConversationRow,+ type Source,} from "../api";import { S } from "../i18n";+import { rehypeCitations } from "../citations";+import { chatMarkdown, SourceList, SourcesProvider } from "./chatCitations";import { toast } from "../toast";import {DropdownMenu,@@ -53,7 +56,6 @@ import {RAIL_CLS,REVEAL,Row,- ROW_HOVER,Textarea,} from "../ui";import { convMarks, useLive, useUnread } from "../unread";@@ -74,6 +76,10 @@ import { NextStep, nextStep, useReadiness } from "./NextStep";const lastKey = (kbId: string) => `chat:last:${kbId}`;const DRAFT_KEY = "chat:draft";+/** 还没有来源的那一轮共用这一个空数组:新建一个会让 context 每次渲染都变,+ * 正文里每个角标跟着重画 */+const NO_SOURCES: Source[] = [];+export function Chat() {const kbId = useKbId();const { kb, kbs, setKb } = useKb();@@ -770,7 +776,14 @@ function stepIcon(kind: ChatStep["kind"]) {const Segment = memo(function Segment({ text }: { text: string }) {return (<div className="u-chat-prose">- <Markdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeHighlight]}>+ {/* rehypeCitations 把正文里的 `[n]` 变成角标(见 citations.ts)。+ 它在 rehype 这一层跑,所以看得见「这个方括号在链接里还是在代码里」——+ 在正文上做字符串替换看不见,会把 markdown 链接的锚文本也改了 */}+ <Markdown+ remarkPlugins={[remarkGfm]}+ rehypePlugins={[rehypeHighlight, rehypeCitations]}+ components={chatMarkdown}+ >{text}</Markdown></div>@@ -815,6 +828,7 @@ function TurnView({ turn, live }: { turn: Turn; live?: boolean }) {const lastStep = turn.steps?.[turn.steps.length - 1];return (+ <SourcesProvider value={turn.sources ?? NO_SOURCES}><div className="max-w-[95%]">{/* agent 回复无气泡:正文直接落在画布上(用户消息保留气泡以区分角色) */}<div className="py-1 text-title text-ink leading-relaxed">@@ -861,50 +875,15 @@ function TurnView({ turn, live }: { turn: Turn; live?: boolean }) {就挂在一段还没写完的话下面,一边长一边把正文往上推。它是答案的落款,不是过程的一部分——过程已经由上面的轨迹交代了 */}{/* 一个面板装多行(DESIGN.md 6):引用是同构的一组,悬停归行。- 只列正文引到的那几条(见 citedSources):检索到的不等于用到的 */}- {!live && cited.length > 0 && (- <div className="mt-2 glass rounded-panel divide-y divide-line">- {cited.map((s) =>- s.kind === "charter" ? (- /* 手册引用:视觉上与数据引用隔离(BookOpen),跳排版好的 /docs 小节 */- <Link- key={s.n}- to="/docs/$slug"- params={{ slug: s.slug! }}- hash={s.anchor || undefined}- title={s.excerpt}- className={`u-card-link flex items-center gap-2 text-small text-ink-2 px-3 py-2 ${ROW_HOVER}`}- >- <span className="u-num text-accent">[{s.n}]</span>- <BookOpen size={11} className="shrink-0 text-ink-2" />- <span className="truncate">- {/* 引言节 heading 即文章名,避免 "X › X" */}- {s.heading && s.heading !== s.filename- ? `${s.filename} › ${s.heading}`- : s.filename}- </span>- </Link>- ) : (- <Link- key={s.n}- to="/kb/$kbId/doc/$docId"- params={{ kbId, docId: s.document_id! }}- search={{ chunk: s.chunk_id }}- title={s.excerpt}- className={`u-card-link block text-small text-ink-2 px-3 py-2 ${ROW_HOVER}`}- >- <span className="u-num text-accent">[{s.n}]</span> {s.filename} ·{" "}- {s.excerpt.slice(0, 60)}…- </Link>- ),- )}- </div>- )}+ 只列正文引到的那几条(见 citedSources):检索到的不等于用到的。+ 点一行先开预览,不直接跳走——见 chatCitations */}+ {!live && cited.length > 0 && <SourceList sources={cited} />}{/* 没有引用时,引用那一格换成一句「未引用任何来源」(#547):缺席没人读得出来,得写出来。判据见 answeredWithoutSources */}{answeredWithoutSources(turn, !!live) && (<div className="mt-2 text-small text-ink-2">{S.ask.noSources}</div>)}</div>+ </SourcesProvider>);}diff --git a/web/src/pages/chatCitations.tsx b/web/src/pages/chatCitations.tsxnew file mode 100644index 00000000..42f0061e--- /dev/null+++ b/web/src/pages/chatCitations.tsx@@ -0,0 +1,141 @@+/* 对话里的引用:正文角标、落款行、预览浮窗的接线。+ 样子在 ui/citation.tsx,这里只管「哪个号是哪条来源」和「去原文是哪条路」。 */+import { createContext, useContext } from "react";+import { useQuery } from "@tanstack/react-query";+import { Link } from "@tanstack/react-router";+import { ArrowUpRight, BookOpen } from "lucide-react";+import type { Components } from "react-markdown";+import { api, type Source } from "../api";+import { citeHref } from "../citations";+import { S } from "../i18n";+import { useKbId } from "../kb";+import { originLabel } from "../origin";+import { CiteChip, CiteMark, CiteRow, PreviewCard } from "../ui/citation";++/** 这一轮回答的来源。+ *+ * **走 context 而不是 prop**:`Segment` 按文本记忆化(一条长答案每来一个词元都要+ * 重渲染,收了尾的段落不该再解析一遍),而来源是一条条到的。把它当 prop 传下去,+ * 每来一条来源所有段落就全部失效;context 只让角标自己重画。 */+const SourcesCtx = createContext<Source[]>([]);+export const SourcesProvider = SourcesCtx.Provider;++/** 给 react-markdown 的 `components`。**必须是模块级常量**:每次渲染现造一个+ * 对象,react-markdown 认为配置变了,`Segment` 的记忆化就白做了 */+export const chatMarkdown: Components = {+ // `node` 是 react-markdown 递进来的 hast 节点,不是 DOM 属性——落到 <a> 上+ // React 会在控制台里抱怨一次+ a: ({ node: _node, href, children, ...rest }) => {+ /* remend 把流式中还没收尾的 `[2` 补成一个链接(`streamdown:incomplete-link`),+ 于是一个正在打出来的引用会先闪成一个蓝色的「2」再变成角标。它本来就不是+ 链接,按原样的文字画 */+ if (href?.startsWith("streamdown:")) return <>{children}</>;+ const ns = citeHref(href);+ if (!ns) {+ return (+ <a href={href} {...rest}>+ {children}+ </a>+ );+ }+ // `[1, 2]` 是两条来源:画成两个各自可点的角标,别让人点一个号跳出两段原文+ return (+ <>+ {ns.map((n) => (+ <InlineCite key={n} n={n} />+ ))}+ </>+ );+ },+};++function InlineCite({ n }: { n: number }) {+ const sources = useContext(SourcesCtx);+ const s = sources.find((x) => x.n === n);+ // 流式中来源比正文晚到:先画成静的,那条到了自己就变成可点的+ if (!s) return <CiteMark n={n} />;+ return <CiteChip n={n} preview={<SourcePreview s={s} />} />;+}++/** 落款:只列正文引到的那几条(见 citedSources),一个面板装一组 */+export function SourceList({ sources }: { sources: Source[] }) {+ return (+ <div className="mt-2 glass rounded-panel divide-y divide-line">+ {sources.map((s) => (+ <CiteRow key={s.n} preview={<SourcePreview s={s} />}>+ {s.kind === "charter" ? (+ <span className="flex items-center gap-2">+ <span className="u-num text-accent">[{s.n}]</span>+ <BookOpen size={11} className="shrink-0 text-ink-2" />+ <span className="truncate">{charterTitle(s)}</span>+ </span>+ ) : (+ <span className="block truncate">+ <span className="u-num text-accent">[{s.n}]</span> {s.filename} ·{" "}+ {s.excerpt.slice(0, 60)}…+ </span>+ )}+ </CiteRow>+ ))}+ </div>+ );+}++/** 引言节的 heading 就是文章名,避免 "X › X" */+function charterTitle(s: Source): string {+ return s.heading && s.heading !== s.filename+ ? `${s.filename} › ${s.heading}`+ : s.filename;+}++/** 预览:先给检索回来的那段摘录(160 字,立刻有东西看),+ * 整块原文随文档详情到了再换上——同一把 react-query 钥匙,+ * 所以点完「打开原文」那一页是现成的 */+function SourcePreview({ s }: { s: Source }) {+ const kbId = useKbId();+ const doc = useQuery({+ queryKey: ["docDetail", s.document_id],+ queryFn: () => api.documentDetail(s.document_id!),+ enabled: !!s.document_id,+ });+ const chunk = doc.data?.chunks.find((c) => c.id === s.chunk_id);++ if (s.kind === "charter") {+ return (+ <PreviewCard+ title={charterTitle(s)}+ body={s.excerpt}+ action={+ <Link+ to="/docs/$slug"+ params={{ slug: s.slug! }}+ hash={s.anchor || undefined}+ className="u-card-link flex items-center gap-1 text-fine text-ink-2"+ >+ {S.ask.openOriginal}+ <ArrowUpRight size={11} />+ </Link>+ }+ />+ );+ }++ return (+ <PreviewCard+ title={s.filename}+ meta={originLabel(chunk?.origin, chunk?.anchor) ?? undefined}+ body={chunk?.text ?? s.excerpt}+ action={+ <Link+ to="/kb/$kbId/doc/$docId"+ params={{ kbId, docId: s.document_id! }}+ search={{ chunk: s.chunk_id }}+ className="u-card-link flex items-center gap-1 text-fine text-ink-2"+ >+ {S.ask.openOriginal}+ <ArrowUpRight size={11} />+ </Link>+ }+ />+ );+}diff --git a/web/src/ui/citation.tsx b/web/src/ui/citation.tsxnew file mode 100644index 00000000..872e45e8--- /dev/null+++ b/web/src/ui/citation.tsx@@ -0,0 +1,110 @@+/* 引用:角标、落款行,和它们共用的预览浮窗。+ 点一条引用先给一段原文,右上角才是去原文的路——核对一句话多半只要看那一段,+ 而跳转会把人从答案里带走,回来时答案已经滚上去了。 */+import { Popover as RadixPopover } from "radix-ui";+import type { ReactNode } from "react";++/** 正文里的一个 `[n]`。流式中来源还没到的号用 {@link CiteMark} 画成静的 */+export function CiteChip({+ n,+ preview,+}: {+ n: number;+ /** 浮窗内容;只有点开才挂载,所以里面的请求也是点开才发 */+ preview: ReactNode;+}) {+ return (+ <RadixPopover.Root>+ <RadixPopover.Trigger asChild>+ <button+ type="button"+ className="u-num rounded-cell px-1 text-accent transition-colors duration-fast hover:bg-surface-2"+ >+ [{n}]+ </button>+ </RadixPopover.Trigger>+ <PreviewPortal>{preview}</PreviewPortal>+ </RadixPopover.Root>+ );+}++/** 还点不动的号(来源尚未到达)。占同样的位置,只是不发光 */+export function CiteMark({ n }: { n: number }) {+ return <span className="u-num px-1 text-ink-2">[{n}]</span>;+}++/** 落款里的一行。整行是触发器,点开同一个浮窗 */+export function CiteRow({+ children,+ preview,+}: {+ children: ReactNode;+ preview: ReactNode;+}) {+ return (+ <RadixPopover.Root>+ <RadixPopover.Trigger asChild>+ <button+ type="button"+ className="block w-full px-3 py-2 text-left text-small text-ink-2 transition-colors duration-fast hover:bg-surface-2"+ >+ {children}+ </button>+ </RadixPopover.Trigger>+ <PreviewPortal align="start">{preview}</PreviewPortal>+ </RadixPopover.Root>+ );+}++function PreviewPortal({+ children,+ align = "center",+}: {+ children: ReactNode;+ align?: "start" | "center";+}) {+ return (+ <RadixPopover.Portal>+ <RadixPopover.Content+ side="top"+ align={align}+ sideOffset={6}+ collisionPadding={8}+ className="u-pop u-pop-in z-[60] rounded-panel u-lift"+ >+ {children}+ </RadixPopover.Content>+ </RadixPopover.Portal>+ );+}++/** 浮窗的样子:标题一行、原文一段、右上角一条出路 */+export function PreviewCard({+ title,+ meta,+ body,+ action,+}: {+ title: ReactNode;+ /** 标题下面的一行小字(章节名、这段文字的来历) */+ meta?: ReactNode;+ body: ReactNode;+ /** 去原文的链接,放在标题右边 */+ action: ReactNode;+}) {+ return (+ <div className="w-80 max-w-[min(24rem,90vw)]">+ <div className="flex items-start gap-2 border-b border-line px-3 py-2">+ <div className="min-w-0 flex-1">+ <div className="truncate text-small text-ink">{title}</div>+ {meta && <div className="truncate text-fine text-ink-2">{meta}</div>}+ </div>+ <div className="shrink-0">{action}</div>+ </div>+ {/* 原文按原样排(换行是它的一部分),长了自己滚,别把浮窗撑穿屏幕 */}+ <div className="max-h-64 overflow-auto whitespace-pre-wrap px-3 py-2 text-small leading-relaxed text-ink-2">+ {body}+ </div>+ </div>+ );+}