@allbluecn/web-app 0.12.0 → 0.12.3

package/src/components/harness/composer/composer-editor.tsx

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"use client"
+
+import { useEffect, useRef, useMemo } from "react"
+import { EditorContent, useEditor } from "@tiptap/react"
+import StarterKit from "@tiptap/starter-kit"
+import { MentionExtension } from "@/components/tiptap/node/mention-extension"
+import { MentionSuggestionMenu } from "./mention/mention-suggestion-menu"
+import { draftsStore } from "./use-drafts"
+import { m } from "@/paraglide/messages.js"
+
+const DRAFT_KEY_PREFIX = "draft"
+
+export interface ComposerEditorProps {
+  threadId: string
+  editable: boolean
+  onTextChange: (isEmpty: boolean) => void
+  editorRef?: (editor: ReturnType<typeof useEditor>) => void
+  scrollContainerRef?: React.RefObject<HTMLDivElement | null>
+  /** 由 @mention chip 上报的 kbId 列表（用于发送时合并到 knowledgeBaseIds） */
+  onMentionKbIds?: (ids: string[]) => void
+  /** handoff 预填文本，挂载时自动追加到编辑器内容开头 */
+  prefillText?: string | null
+}
+
+export function ComposerEditor({
+  threadId,
+  editable,
+  onTextChange,
+  editorRef,
+  scrollContainerRef,
+  onMentionKbIds,
+  prefillText,
+}: ComposerEditorProps) {
+  const draftKey = `${DRAFT_KEY_PREFIX}:${threadId}`
+  const mentionKbIdsRef = useRef<string[]>([])
+  // 在草稿基础上追加 handoff 预填文本
+  const resolvedDraft = useMemo(() => {
+    const draft = draftsStore.load(draftKey) ?? ""
+    return prefillText ? prefillText + draft : draft
+  }, [draftKey, prefillText])
+  const editor = useEditor({
+    editable,
+    extensions: [
+      StarterKit.configure({
+        heading: false,
+        bulletList: false,
+        orderedList: false,
+        blockquote: false,
+        codeBlock: false,
+        horizontalRule: false,
+      }),
+      MentionExtension,
+    ],
+    content: resolvedDraft ?? "",
+    editorProps: {
+      attributes: {
+        class:
+          "focus:outline-none max-h-[calc(14*1.625rem)] overflow-y-auto text-sm",
+        "aria-label": m.harness_composer_ariaLabel(),
+      },
+      handleDOMEvents: {
+        wheel: (view, event) => {
+          const wheelEvent = event as WheelEvent
+          const el = view.dom
+          const atTop = el.scrollTop === 0
+          const atBottom = el.scrollTop + el.clientHeight >= el.scrollHeight - 1
+          if (
+            (wheelEvent.deltaY < 0 && atTop) ||
+            (wheelEvent.deltaY > 0 && atBottom)
+          ) {
+            const target = scrollContainerRef?.current
+            if (target) {
+              target.scrollTop += wheelEvent.deltaY
+              return true
+            }
+          }
+          return false
+        },
+      },
+    },
+    onUpdate: ({ editor }) => {
+      draftsStore.save(
+        draftKey,
+        editor.getJSON() ? JSON.stringify(editor.getJSON()) : "",
+      )
+      onTextChange(editor.isEmpty)
+      // 收集当前编辑器中所有 @mention chip 的 kbId
+      const doc = editor.getJSON()
+      const ids: string[] = []
+      const walk = (nodes: unknown[]) => {
+        for (const n of nodes) {
+          if (!n || typeof n !== "object") continue
+          const node = n as Record<string, unknown>
+          if (node.type === "mention") {
+            const kbId = node["data-kb-id"] as string | undefined
+            if (kbId) ids.push(kbId)
+          }
+          if (Array.isArray(node.content)) walk(node.content as unknown[])
+        }
+      }
+      if (Array.isArray(doc?.content)) walk(doc.content)
+      const unique = [...new Set(ids)]
+      mentionKbIdsRef.current = unique
+      onMentionKbIds?.(unique)
+    },
+  })
+  const editorRefHolder = useRef(editor)
+  editorRefHolder.current = editor
+  useEffect(() => {
+    editorRef?.(editor)
+  }, [editor, editorRef])
+  if (!editor) return null
+  return (
+    <div className="relative">
+      <EditorContent editor={editor} />
+      <MentionSuggestionMenu editor={editor} />
+    </div>
+  )
+}

package/src/components/harness/composer/context-meter.tsx

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"use client"
+
+import { useState } from "react"
+import { m } from "@/paraglide/messages.js"
+import type { UIMessage } from "@tanstack/ai-client"
+
+interface ContextMeterProps {
+  messages: UIMessage[]
+  capacity?: number
+}
+
+const DEFAULT_CAPACITY = 128_000
+
+export function ContextMeter({ messages, capacity = DEFAULT_CAPACITY }: ContextMeterProps) {
+  const [open, setOpen] = useState(false)
+
+  const estTokens = Math.round(
+    messages.reduce(
+      (s, msg) =>
+        s +
+        msg.parts.reduce(
+          (acc, p) => acc + (p.type === "text" ? String(p.content ?? "").length : 400),
+          0,
+        ),
+      0,
+    ) / 4,
+  )
+
+  const pct = Math.min(1, estTokens / capacity)
+  const circumference = 2 * Math.PI * 6
+  const strokeDashoffset = circumference * (1 - pct)
+
+  const formatTokens = (n: number) => {
+    if (n < 1000) return String(n)
+    return `${(n / 1000).toFixed(1)}K`
+  }
+
+  return (
+    <div className="relative">
+      <button
+        className="flex items-center gap-1 text-muted-foreground hover:text-foreground"
+        onClick={() => setOpen(!open)}
+        aria-label={m.harness_context_meter_label({ percent: Math.round(pct * 100) })}
+      >
+        <svg width="14" height="14" viewBox="0 0 14 14">
+          <circle
+            cx="7"
+            cy="7"
+            r="6"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.5"
+            className="text-muted"
+          />
+          <circle
+            cx="7"
+            cy="7"
+            r="6"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.5"
+            strokeDasharray={circumference}
+            strokeDashoffset={strokeDashoffset}
+            className="text-primary transition-all"
+            transform="rotate(-90 7 7)"
+          />
+        </svg>
+        <span className="text-xs">{formatTokens(estTokens)}</span>
+      </button>
+
+      {open && (
+        <div className="absolute bottom-full left-0 mb-2 w-48 rounded-lg border bg-popover p-3 text-xs shadow-md">
+          <p className="font-medium">
+            {formatTokens(estTokens)} / {formatTokens(capacity)}
+          </p>
+          <div className="mt-2 h-2 rounded-full bg-muted">
+            <div
+              className="h-full rounded-full bg-primary transition-all"
+              style={{ width: `${pct * 100}%` }}
+            />
+          </div>
+          <p className="mt-1 text-muted-foreground">
+            {m.harness_context_meter_hint()}
+          </p>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/harness/composer/fuzzy.ts

@@ -0,0 +1,21 @@
+export interface FuzzyResult {
+  score: number
+}
+
+export function fuzzyMatch(query: string, target: string): FuzzyResult | null {
+  const q = query.toLowerCase()
+  const t = target.toLowerCase()
+  let qi = 0
+  let score = 0
+  let streak = 0
+  for (let ti = 0; ti < t.length && qi < q.length; ti++) {
+    if (t[ti] === q[qi]) {
+      qi++
+      streak++
+      score += 1 + streak * 2 + (ti === 0 ? 4 : 0)
+    } else {
+      streak = 0
+    }
+  }
+  return qi === q.length ? { score } : null
+}

package/src/components/harness/composer/harness-composer.tsx

@@ -0,0 +1,385 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"use client"
+
+import { useState, useRef, useEffect, useCallback } from "react"
+import { toast } from "@/components/ui/toast"
+import type { Editor } from "@tiptap/core"
+import { decideSubmit, type BusyAction } from "./submit-machine"
+import { useAttachments } from "./attachments/use-attachments"
+import { AttachmentTray } from "./attachments/attachment-tray"
+import { ModelSelect } from "./model-select"
+import { ContextMeter } from "./context-meter"
+import { InterruptApproval } from "@/components/harness/interrupt-approval"
+import { ComposerEditor } from "./composer-editor"
+import { Button } from "@/components/ui/button"
+import { FeatureGate } from "@/components/billing/feature-gate"
+import { generatePrototypeFn } from "@/server/serverFns/harness/media"
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select"
+import { ShieldCheck, Sparkles } from "lucide-react"
+import { SANDBOX_POLICY_LEVELS, type SandboxPolicyLevel } from "@/server/ai-gateway/sandbox/policy-levels"
+import type { UseChatReturn } from "@tanstack/ai-react"
+import { m } from "@/paraglide/messages.js"
+
+export interface MentionCandidate {
+  kind: string
+  label: string
+  id: string
+  kbId?: string
+}
+
+export interface PrefillMentionEntity {
+  kind: string
+  id: string
+  label: string
+  kbId?: string
+}
+
+/** 映射 handoff board 为 mention 原子节点的 docType（kb-doc→doc，story/prd 原样） */
+function resolveMentionDocType(kind: string): string {
+  return kind === "kb-doc" ? "doc" : kind
+}
+
+type PrefillOutcome =
+  | { kind: "chip"; entity: PrefillMentionEntity }
+  | { kind: "text"; text: string }
+
+/**
+ * 映射 handoff board 为 prefill 产出：workspaces/agents/apps 注入 mention chip；
+ * dashboard 仅纯文本（P4e 任务 7 复审 P1-4：不插 chip、不落到 chip 注入链路）。
+ * 默认仍走 kb-doc（kb-doc→doc，kbId=entityId）。
+ */
+export function resolveHandoffPrefill(board: string, entityId: string): PrefillOutcome {
+  if (board === "prd") {
+    return { kind: "chip", entity: { kind: "prd", id: entityId, label: `PRD ${entityId}` } }
+  }
+  if (board === "story") {
+    return { kind: "chip", entity: { kind: "story", id: entityId, label: `Story ${entityId}` } }
+  }
+  if (board === "workspaces") {
+    return { kind: "chip", entity: { kind: "workspace", id: entityId, label: `Workspace ${entityId}` } }
+  }
+  if (board === "agents") {
+    return { kind: "chip", entity: { kind: "agent", id: entityId, label: `Agent ${entityId}` } }
+  }
+  if (board === "apps") {
+    return { kind: "chip", entity: { kind: "app", id: entityId, label: `App ${entityId}` } }
+  }
+  if (board === "dashboard") {
+    return { kind: "text", text: `Dashboard ${entityId}` }
+  }
+  return { kind: "chip", entity: { kind: "kb-doc", id: entityId, label: `KB ${entityId}`, kbId: entityId } }
+}
+
+/** 经 TipTap 实例注入 @mention 原子节点 + 换行（替代 DOM value hack） */
+export function insertMentionChip(editor: Editor, entity: PrefillMentionEntity) {
+  const attrs: Record<string, string> = {
+    id: entity.id,
+    label: entity.label,
+    docType: resolveMentionDocType(entity.kind),
+    docGroup: "",
+  }
+  if (entity.kbId) attrs["data-kb-id"] = entity.kbId
+  editor.commands.insertContent([
+    { type: "mention", attrs },
+    { type: "text", text: "\n" },
+  ])
+}
+
+export interface HarnessComposerProps {
+  threadId: string | null
+  isRunning: boolean
+  hasAiKey: boolean
+  isLoading: boolean
+  busyPreference: BusyAction
+  onBusyPreferenceChange: (pref: BusyAction) => void
+  onSend: (
+    text: string,
+    opts?: {
+      whenBusy?: "queue" | "interrupt"
+      knowledgeBaseIds?: string[]
+      attachments?: Array<{ type: "image"; source: { type: "data"; value: string; mimeType: string } }>
+    }
+  ) => void
+  onStop: () => void
+  messages: Array<{ id: string; role: string; parts: Array<{ type: string; content?: unknown }> }>
+  scrollContainerRef?: React.RefObject<HTMLDivElement | null>
+  model?: string
+  onModelChange?: (model: string) => void
+  knowledgeBaseIds?: string[]
+  onMentionQuery?: (query: string) => MentionCandidate[] | undefined
+  className?: string
+  /** 待审批的中断列表（来自 chat.interrupts） */
+  interrupts?: UseChatReturn["interrupts"]
+  sandboxPolicy?: "readonly" | "workspace-write" | "full"
+  onSandboxPolicyChange?: (policy: "readonly" | "workspace-write" | "full") => void
+  /** 媒体生成路线：code（HTML/Tailwind）| spec（结构化 UI spec） */
+  mediaRoute?: "code" | "spec"
+  onMediaRouteChange?: (route: "code" | "spec") => void
+  /** handoff 携带的板块上下文，用于自动插入 @chip */
+  handoffContext?: { board: string; entityId: string } | null
+  /** 纯文本 handoff 预填值（dashboard 等 board：跳过 chip 插入，直接写入编辑器文本） */
+  handoffPrefillText?: string | null
+}
+
+export function HarnessComposer({
+  threadId,
+  isRunning,
+  hasAiKey,
+  isLoading,
+  busyPreference,
+  onSend,
+  onStop,
+  messages,
+  model,
+  onModelChange,
+  knowledgeBaseIds,
+  onMentionQuery,
+  className,
+  interrupts,
+  sandboxPolicy,
+  onSandboxPolicyChange,
+  mediaRoute,
+  onMediaRouteChange,
+   scrollContainerRef,
+   handoffContext,
+   handoffPrefillText,
+}: HarnessComposerProps) {
+  const [input, setInput] = useState("")
+  const [pendingPrefillEntity, setPendingPrefillEntity] = useState<PrefillMentionEntity | null>(null)
+  const [pendingPrefillText, setPendingPrefillText] = useState<string | null>(null)
+  const editorRef = useRef<Editor | null>(null)
+  const receiveEditor = useCallback((editor: Editor | null) => {
+    editorRef.current = editor ?? null
+    setInput(editor?.getText() ?? "")
+    if (editor && hasAiKey) {
+      if (pendingPrefillEntity) {
+        insertMentionChip(editor, pendingPrefillEntity)
+        setPendingPrefillEntity(null)
+      } else if (pendingPrefillText) {
+        editor.commands.insertContent(pendingPrefillText)
+        setPendingPrefillText(null)
+      }
+    }
+  }, [pendingPrefillEntity, pendingPrefillText, hasAiKey])
+  const { attachments, addFiles, removeAttachment, clearAttachments } = useAttachments()
+  // @mention chip 中携带的 kbId（由 ComposerEditor 通过 onMentionKbIds 回调上报）
+  const [editorMentionKbIds, setEditorMentionKbIds] = useState<string[]>([])
+
+  useEffect(() => {
+    if (handoffPrefillText != null) {
+      setPendingPrefillText(handoffPrefillText)
+      if (editorRef.current) {
+        editorRef.current.commands.insertContent(handoffPrefillText)
+        setPendingPrefillText(null)
+      }
+      setPendingPrefillEntity(null)
+      return
+    }
+    if (!handoffContext) return
+    const { board, entityId } = handoffContext
+    const prefill = resolveHandoffPrefill(board, entityId)
+    if (prefill.kind === "text") {
+      setPendingPrefillText(prefill.text)
+      if (editorRef.current) {
+        editorRef.current.commands.insertContent(prefill.text)
+        setPendingPrefillText(null)
+      }
+      setPendingPrefillEntity(null)
+      return
+    }
+    const entity: PrefillMentionEntity = prefill.entity
+    setPendingPrefillEntity(entity)
+    if (editorRef.current && hasAiKey) {
+      insertMentionChip(editorRef.current, entity)
+      setPendingPrefillEntity(null)
+    }
+  }, [handoffContext, handoffPrefillText, hasAiKey])
+
+  // placeholder 五态
+  const placeholder = computePlaceholder({
+    hasAiKey,
+    isRunning,
+    busyPreference,
+  })
+
+  const handleSend = useCallback(
+    (text: string) => {
+      if (!text.trim() || !hasAiKey) return
+
+      if (mediaRoute === "spec") {
+        if (!threadId) {
+          toast.info(m.harness_spec_needThread())
+          editorRef.current?.commands.clearContent()
+          setInput("")
+          clearAttachments()
+          return
+        }
+        void generatePrototypeFn({ data: { prompt: text, threadId } }).catch(() =>
+          toast.error(m.harness_spec_generateFailed())
+        )
+        editorRef.current?.commands.clearContent()
+        setInput("")
+        clearAttachments()
+        return
+      }
+
+      // 将 editor mention chip 的 kbId 与 agent 预设合并
+      const mergedKbIds = [
+        ...new Set([...(knowledgeBaseIds ?? []), ...editorMentionKbIds]),
+      ]
+
+      onSend(text, {
+        whenBusy: "queue",
+        knowledgeBaseIds: mergedKbIds.length ? mergedKbIds : undefined,
+        // 透传板块上下文（如果存在），服务端可据此注入系统提示词
+        ...(handoffContext ? { board: handoffContext.board, entityId: handoffContext.entityId } : {}),
+      })
+      editorRef.current?.commands.clearContent()
+      setInput("")
+      clearAttachments()
+    },
+    [hasAiKey, onSend, knowledgeBaseIds, editorMentionKbIds, handoffContext, clearAttachments, mediaRoute, threadId]
+  )
+
+  const handleStop = useCallback(() => {
+    onStop()
+  }, [onStop])
+
+  const decision = decideSubmit({
+    text: input,
+    hasUploadingAttachments: false,
+    isRunning,
+    busyPreference,
+    modifierKey: false,
+    composerLocked: false,
+  })
+
+  const busyLabel =
+    busyPreference === "queue"
+      ? m.harness_composer_queueLabel()
+      : m.harness_composer_steerLabel()
+
+  // 有挂起审批时替换整个输入区为审批卡
+  const hasPendingInterrupts =
+    interrupts !== undefined && interrupts.length > 0
+
+  if (hasPendingInterrupts) {
+    return (
+      <div className={className}>
+        <InterruptApproval interrupts={interrupts} />
+      </div>
+    )
+  }
+
+  return (
+    <div className={className}>
+      <div className="flex items-center gap-2">
+        <ModelSelect onModelChange={onModelChange} />
+        <ContextMeter messages={messages as any} />
+        <FeatureGate feature="sandboxExecution" mode="disable" fallback={
+          <span className="text-xs text-muted-foreground">{m.harness_sandbox_pro()}</span>
+        }>
+          <Select
+            value={sandboxPolicy}
+            onValueChange={(v) => onSandboxPolicyChange?.(v as SandboxPolicyLevel)}
+          >
+            <SelectTrigger className="h-7 w-auto text-xs">
+              <ShieldCheck className="mr-1 size-3" />
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              {SANDBOX_POLICY_LEVELS.map((level) => (
+                <SelectItem key={level} value={level}>
+                  {level === "readonly" ? m.harness_sandbox_readonly()
+                    : level === "workspace-write" ? m.harness_sandbox_workspaceWrite()
+                    : m.harness_sandbox_full()}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </FeatureGate>
+        <FeatureGate feature="mediaGeneration" mode="disable" fallback={
+          <span className="text-xs text-muted-foreground">{m.harness_media_pro()}</span>
+        }>
+          <Select
+            value={mediaRoute}
+            onValueChange={(v) => onMediaRouteChange?.(v as "code" | "spec")}
+          >
+            <SelectTrigger className="h-7 w-auto text-xs">
+              <Sparkles className="mr-1 size-3" />
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="code">{m.harness_media_code()}</SelectItem>
+              <SelectItem value="spec">{m.harness_media_spec()}</SelectItem>
+            </SelectContent>
+          </Select>
+        </FeatureGate>
+      </div>
+      {/* TipTap 编辑器：支持 @mention 数据源接线，handoff 经 insertContent 原子 chip 注入 */}
+      <div onKeyDownCapture={(event) => {
+        if (event.key !== "Enter" || event.shiftKey || event.nativeEvent.isComposing) return
+        if (event.target instanceof HTMLElement && !event.target.isContentEditable && event.target.getAttribute("contenteditable") !== "true") return
+        event.preventDefault()
+        handleSend(editorRef.current?.getText() ?? "")
+      }}>
+        <ComposerEditor
+          threadId={threadId ?? "default"}
+          editable={hasAiKey}
+          editorRef={receiveEditor}
+          onTextChange={() => setInput(editorRef.current?.getText() ?? "")}
+          onMentionKbIds={setEditorMentionKbIds}
+          scrollContainerRef={scrollContainerRef}
+        />
+      </div>
+      <Button disabled={!hasAiKey || !input.trim()} onClick={() => handleSend(editorRef.current?.getText() ?? "")}>
+        {m.harness_composer_send()}
+      </Button>
+      {attachments.length > 0 && (
+        <AttachmentTray
+          attachments={attachments}
+          onRemove={removeAttachment}
+        />
+      )}
+      {isLoading && (
+        <div className="mt-1 flex items-center gap-2 px-1">
+          <span className="text-xs text-muted-foreground">{busyLabel}</span>
+        </div>
+      )}
+    </div>
+  )
+}
+
+interface PlaceholderState {
+  hasAiKey: boolean
+  isRunning: boolean
+  busyPreference: BusyAction
+}
+
+function computePlaceholder(s: PlaceholderState): string {
+  if (!s.hasAiKey) return m.harness_composer_placeholderNoKey()
+  if (s.isRunning && s.busyPreference === "queue") return m.harness_composer_placeholderQueue()
+  return m.harness_composer_placeholderDefault()
+}

package/src/components/harness/composer/mention/mention-resolvers.ts

@@ -0,0 +1,35 @@
+export type MentionKind = "file" | "kb-doc" | "prd" | "story" | "plugin-tool" | "thread"
+
+export interface MentionCandidate {
+  kind: MentionKind
+  label: string
+  id: string
+  kbId?: string
+}
+
+const GROUP_ORDER: MentionKind[] = ["file", "kb-doc", "prd", "story", "plugin-tool", "thread"]
+
+export function groupMentionCandidates(
+  query: string,
+  all: readonly MentionCandidate[],
+) {
+  const q = query.trim().toLowerCase()
+  return GROUP_ORDER
+    .map((kind) => ({
+      kind,
+      items: all.filter(
+        (c) => c.kind === kind && (!q || c.label.toLowerCase().includes(q)),
+      ),
+    }))
+    .filter((g) => g.items.length > 0)
+}
+
+export function extractKbIds(
+  chips: { kind: string; kbId?: string }[],
+): string[] {
+  return [
+    ...new Set(
+      chips.filter((c) => c.kind === "kb-doc" && c.kbId).map((c) => c.kbId!),
+    ),
+  ]
+}