feat(workbench): configurable entity types (global default + per-KB override) (#200)

* feat(api): configurable entity_types (global + per-KB) via the config API

entity_types (the entity-extraction vocabulary) is now surfaced through the
config read/write API, layering global.yaml -> KB config.yaml like the other
scalars: a KB list overrides the global list wholesale, an explicit null
inherits, and unset falls back to DEFAULT_ENTITY_TYPES. The compiler already
consumed config["entity_types"] via resolve_entity_types; this just exposes it.

- GLOBAL_SCALAR_KEYS gains "entity_types" (layering + per-key `sources` tracking;
  the value-not-None-wins rule is type-agnostic, so it works for a list).
- _KbConfigWritable / GlobalConfigValues / KbConfigResponse / GlobalConfigResponse
  carry entity_types; read_kb_config/read_global_config report the cleaned
  EFFECTIVE list (resolve_entity_types) plus the raw global value for the badge.
- PATCH /api/v1/kb/config and PATCH /api/v1/config accept entity_types.

Tests: KB override (cleaned + source 'kb') + null revert, global patch, global
inheritance; updated the global-defaults shape assertion. Frontend UI follows.

Claude-Session: https://claude.ai/code/session_01XMxbhmAkxxVV8CFWCZDBaG

* feat(web): entity-types config UI — chips editor (global default + per-KB override)

- EntityTypesEditor: shared controlled chips editor (Enter/comma to add, x to
  remove; "other" is a fixed always-included chip; IME-safe composition).
- KbSettingsSheet: an EntityTypesRow with the same inherit/override Switch as the
  scalar rows — turning override on seeds+persists the KB's own list, off reverts
  via null; inherited state shows the global/default list as a badge. Each chip
  change persists and adopts the server-cleaned response.
- Settings (general tab): a global entity-types chips editor, order-sensitive
  diff into the save patch (joins the existing dirty/SaveBar flow).
- "changes affect future recompiles only" note on both surfaces.

New keys in common/kbSettings/settings (zh + en, identical sets). Build green
(i18n guard OK). Backend was committed in 92f8f41.

Claude-Session: https://claude.ai/code/session_01XMxbhmAkxxVV8CFWCZDBaG

* fix(entity-types): address xhigh review — DEFAULT_CONFIG parity, empty-list inherit, silent reads, set-diff

- config: define DEFAULT_ENTITY_TYPES before DEFAULT_CONFIG and add
  `entity_types` to DEFAULT_CONFIG so the key layers like every other
  GLOBAL_SCALAR_KEY and always appears in the effective config (#1).
- config: resolve_effective_config treats an empty entity_types list the
  same as null → inherit, so a KB that cleared its override doesn't pin an
  empty vocabulary (#2).
- config: resolve_entity_types(config, *, warn=True); config-read paths pass
  warn=False so a plain GET doesn't spam coercion warnings (#4).
- api_config: both read paths call resolve_entity_types(..., warn=False).
- KbSettingsSheet: inherited badge shows the effective list, not
  `globalValue ?? effective`; drop the now-unused globalValue prop (#3).
- Settings: global entity_types diff is order-insensitive — the vocabulary
  is a set, so re-adding a removed type is not a change (#6).

Backend pytest 1240 passed; ruff/format/mypy clean; frontend build green.

Claude-Session: https://claude.ai/code/session_01XMxbhmAkxxVV8CFWCZDBaG

Author: KylinMountain

frontend/src/api/config.ts

@@ -6,6 +6,9 @@ export interface GlobalConfig {
   model: string
   language: string
   pageindex_threshold: number
+  /** CLEANED effective global entity-extraction vocabulary (always includes
+   *  "other"). Mirrors KbConfig.entity_types. */
+  entity_types: string[]
   /** Plaintext global-default LLM base URL (a config value, not a secret);
    *  null if unset. Mirrors KbConfig.openai_api_base. */
   openai_api_base?: string | null
@@ -30,6 +33,9 @@ export interface GlobalConfigPatch {
     model?: string | null
     language?: string | null
     pageindex_threshold?: number | null
+    /** A list sets the global vocabulary; `null` reverts to the built-in
+     *  default. Cleaned server-side (lowercase, `[a-z0-9 _-]`, + "other"). */
+    entity_types?: string[] | null
   }
   api_key?: string | null
   openai_api_base?: string | null

frontend/src/api/kb.ts

@@ -54,17 +54,21 @@ export interface KbConfig {
   model: string
   language: string
   pageindex_threshold: number
+  /** CLEANED effective entity-extraction vocabulary (always includes "other"). */
+  entity_types: string[]
   /** Plaintext LLM base URL (a config value, not a credential); null if unset. */
   openai_api_base: string | null
   /** Presence flag only — the raw key value is NEVER returned by the API. */
   has_api_key: boolean
-  /** Which layer supplied each scalar's effective value. */
-  sources: Record<"model" | "language" | "pageindex_threshold", ConfigSource>
-  /** Raw global-layer scalars (null where global.yaml is silent). */
+  /** Which layer supplied each field's effective value. */
+  sources: Record<"model" | "language" | "pageindex_threshold" | "entity_types", ConfigSource>
+  /** Raw global-layer values (null where global.yaml is silent). */
   global_values: {
     model: string | null
     language: string | null
     pageindex_threshold: number | null
+    /** RAW global list (not cleaned) — for the inherited badge. */
+    entity_types: string[] | null
   }
 }
 
@@ -76,7 +80,11 @@ export interface KbConfig {
  * key" request, not "unchanged" or "clear".
  */
 export interface KbConfigPatch {
-  config?: Partial<Pick<KbConfig, "model" | "language" | "pageindex_threshold">>
+  config?: Partial<Pick<KbConfig, "model" | "language" | "pageindex_threshold">> & {
+    /** A list sets/overrides for this KB; `null` reverts to inherited. Values
+     *  are cleaned server-side (lowercase, `[a-z0-9 _-]`, dedupe, + "other"). */
+    entity_types?: string[] | null
+  }
   api_key?: string | null
   openai_api_base?: string | null
 }

frontend/src/components/EntityTypesEditor.tsx

@@ -0,0 +1,84 @@
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { X } from 'lucide-react'
+
+/** The backend's catch-all bucket: it is re-appended server-side on every
+ *  write, so the editor renders it as a fixed, non-removable chip. */
+const ALWAYS_INCLUDED = 'other'
+
+/**
+ * Chips editor for the entity-extraction vocabulary, shared by the per-KB
+ * override row (KbSettingsSheet) and the global editor (Settings › general).
+ * Controlled: renders `value` as removable chips + an add input (Enter to add,
+ * commas split), and calls `onChange` with the FULL next list on each
+ * add/remove. Client-side it only trims/lowercases and drops empties/dupes —
+ * the authoritative cleaning (charset, dedupe, "other") happens server-side.
+ */
+export default function EntityTypesEditor({
+  value,
+  disabled,
+  onChange,
+}: {
+  /** Current list (server-cleaned effective list, or local draft state). */
+  value: string[]
+  disabled?: boolean
+  /** Receives the complete next list after an add/remove. */
+  onChange: (next: string[]) => void
+}) {
+  const { t } = useTranslation('common')
+  const [draft, setDraft] = useState('')
+
+  const add = () => {
+    const seen = new Set(value.map((v) => v.toLowerCase()))
+    const added: string[] = []
+    for (const part of draft.split(',')) {
+      const v = part.trim().toLowerCase()
+      if (v === '' || seen.has(v)) continue
+      seen.add(v)
+      added.push(v)
+    }
+    setDraft('')
+    if (added.length > 0) onChange([...value, ...added])
+  }
+
+  return (
+    <div className="flex flex-wrap items-center gap-1.5 rounded-md border border-input px-2.5 py-2">
+      {value.map((item) => (
+        <span
+          key={item}
+          className="inline-flex items-center gap-1 rounded-full border border-[hsl(var(--glass-border))] bg-muted px-2.5 py-1 text-[11.5px] font-mono2 text-foreground"
+        >
+          {item}
+          {item === ALWAYS_INCLUDED ? (
+            <span className="text-[10.5px] text-muted-foreground">{t('entityTypes.always')}</span>
+          ) : (
+            <button
+              type="button"
+              onClick={() => onChange(value.filter((x) => x !== item))}
+              disabled={disabled}
+              aria-label={t('entityTypes.removeAria', { type: item })}
+              className="grid h-3.5 w-3.5 place-items-center rounded-full text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:opacity-60"
+            >
+              <X className="h-2.5 w-2.5" />
+            </button>
+          )}
+        </span>
+      ))}
+      <input
+        value={draft}
+        disabled={disabled}
+        onChange={(e) => setDraft(e.target.value)}
+        onKeyDown={(e) => {
+          // Enter confirms IME composition first; only a real Enter adds.
+          if (e.key === 'Enter' && !e.nativeEvent.isComposing) {
+            e.preventDefault()
+            add()
+          }
+        }}
+        placeholder={t('entityTypes.placeholder')}
+        aria-label={t('entityTypes.placeholder')}
+        className="h-6 min-w-[140px] flex-1 bg-transparent text-[12.5px] font-mono2 outline-none placeholder:text-muted-foreground/70 disabled:opacity-60"
+      />
+    </div>
+  )
+}

frontend/src/components/KbSettingsSheet.tsx

@@ -16,6 +16,7 @@ import type { SseEvent } from '@/api/client'
 import { Switch } from '@/components/ui/switch'
 import { cn } from '@/lib/utils'
 import { UnLanguageDatalist, UN_LANG_LIST_ID } from '@/components/UnLanguageDatalist'
+import EntityTypesEditor from '@/components/EntityTypesEditor'
 
 const errMsg = (e: unknown) => (e instanceof Error ? e.message : String(e))
 
@@ -169,6 +170,22 @@ function KbConfigSection({ kb }: { kb: string }) {
     [kb, apply, t],
   )
 
+  // Persist the entity-types override (list) or revert to inherited (null).
+  // Always adopts the response: the row then shows the server-CLEANED list.
+  const setEntityTypesOverride = useCallback(
+    async (value: string[] | null) => {
+      setBusy(true)
+      try {
+        apply(await patchKbConfig(kb, { config: { entity_types: value } }))
+      } catch (e) {
+        toast.error(t('common:saveError', { error: errMsg(e) }))
+      } finally {
+        setBusy(false)
+      }
+    },
+    [kb, apply, t],
+  )
+
   const saveCredentials = useCallback(async () => {
     if (!config) return
     setBusy(true)
@@ -258,6 +275,13 @@ function KbConfigSection({ kb }: { kb: string }) {
         onSet={(v) => setOverride('pageindex_threshold', Number(v))}
         onRevert={() => setOverride('pageindex_threshold', null)}
       />
+      <EntityTypesRow
+        source={config.sources.entity_types}
+        effective={config.entity_types}
+        busy={busy}
+        onSet={setEntityTypesOverride}
+        onRevert={() => setEntityTypesOverride(null)}
+      />
 
       <h3 className="pt-2 text-[12px] font-semibold text-muted-foreground tracking-wide">{t('kbSettings:credHeading')}</h3>
       <div>
@@ -385,6 +409,64 @@ function OverrideRow({
   )
 }
 
+/** OverrideRow's list-shaped sibling for the entity-extraction vocabulary:
+ *  the same 为本库覆盖 switch + inherited badge, but the override editor is a
+ *  chips list (EntityTypesEditor) and every add/remove persists immediately —
+ *  the chips always show the server-cleaned effective list. */
+function EntityTypesRow({
+  source, effective, busy, onSet, onRevert,
+}: {
+  source: ConfigSource
+  /** Cleaned effective list (always includes "other") — shown as-is in the
+   *  inherited badge, so it matches the vocabulary the compiler actually uses. */
+  effective: string[]
+  busy: boolean
+  onSet: (value: string[]) => void
+  onRevert: () => void
+}) {
+  const { t } = useTranslation(['kbSettings', 'common'])
+  const overridden = source === 'kb'
+  const label = t('common:fields.entityTypes')
+
+  const inheritedBadge =
+    source === 'global'
+      ? t('kbSettings:inheritGlobal', { value: effective.join(', ') })
+      : t('kbSettings:inheritDefault', { value: effective.join(', ') })
+
+  return (
+    <div>
+      <div className="flex items-center justify-between">
+        <label className="text-[12px] font-medium text-muted-foreground">{label}</label>
+        <span className="flex items-center gap-2 text-[11px] text-muted-foreground">
+          {t('kbSettings:override')}
+          <Switch
+            checked={overridden}
+            disabled={busy}
+            // ON seeds the override with the current effective list (the
+            // backend then owns it as this KB's own list); OFF reverts to
+            // inherited via an explicit null.
+            onCheckedChange={(v) => (v ? onSet(effective) : onRevert())}
+            aria-label={t('kbSettings:overrideAria', { label })}
+          />
+        </span>
+      </div>
+      {overridden ? (
+        <div className="mt-1.5">
+          <EntityTypesEditor value={effective} disabled={busy} onChange={onSet} />
+        </div>
+      ) : (
+        <div
+          data-field="entity_types"
+          className="mt-1.5 flex min-h-9 items-center rounded-md border border-dashed border-[hsl(var(--glass-border))] px-3 py-1.5 text-[12.5px] text-muted-foreground"
+        >
+          {inheritedBadge}
+        </div>
+      )}
+      <p className="mt-1.5 text-[11.5px] text-muted-foreground">{t('kbSettings:entityTypesNote')}</p>
+    </div>
+  )
+}
+
 /** Per-doc row accumulated from a recompile SSE stream (from the `doc` event).
  *  Moved verbatim from `pages/KbDetail.tsx` (formerly its 任务 tab). */
 interface RecompileDoc {

frontend/src/locales/en/common.json

@@ -13,7 +13,13 @@
   "fields": {
     "model": "Model",
     "wikiLanguage": "Wiki output language",
-    "threshold": "PageIndex threshold (pages)"
+    "threshold": "PageIndex threshold (pages)",
+    "entityTypes": "Entity types"
+  },
+  "entityTypes": {
+    "placeholder": "Add a type, press Enter",
+    "removeAria": "Remove type {{type}}",
+    "always": "always included"
   },
   "errors": {
     "requestFailed": "Request failed",

frontend/src/locales/en/kbSettings.json

@@ -18,6 +18,7 @@
   "inheritDefault": "Inherited · default ({{value}})",
   "override": "Override for this KB",
   "overrideAria": "Override {{label}} for this KB",
+  "entityTypesNote": "Changes apply to future recompiles only; existing entity pages keep their current type.",
   "unnamed": "(unnamed)",
   "recompileFailed": "Recompile failed",
   "watchStarted": "File watching started",

frontend/src/locales/en/settings.json

@@ -21,6 +21,8 @@
   },
   "general": {
     "langDesc": "The output language written into the compile prompt, e.g. en / 中文 / 日本語",
+    "entityTypesDesc": "The vocabulary used to classify entities extracted at compile time; each KB can inherit or override it in its own settings.",
+    "entityTypesNote": "Changes apply to future recompiles only; existing entity pages keep their current type.",
     "kbRootLabel": "Knowledge base root",
     "kbRootDesc": "Default location for new knowledge bases (<root>/<name>); leave empty to restore the built-in default. Individual KBs can set a custom path at creation.",
     "kbRootPlaceholder": "e.g. ~/openkb",

frontend/src/locales/zh/common.json

@@ -13,7 +13,13 @@
   "fields": {
     "model": "模型",
     "wikiLanguage": "Wiki 输出语言",
-    "threshold": "PageIndex 阈值（页数）"
+    "threshold": "PageIndex 阈值（页数）",
+    "entityTypes": "实体类型"
+  },
+  "entityTypes": {
+    "placeholder": "输入类型，按 Enter 添加",
+    "removeAria": "移除类型 {{type}}",
+    "always": "始终包含"
   },
   "errors": {
     "requestFailed": "请求失败",

frontend/src/locales/zh/kbSettings.json

@@ -18,6 +18,7 @@
   "inheritDefault": "继承 · 默认({{value}})",
   "override": "为本库覆盖",
   "overrideAria": "{{label}} 为本库覆盖",
+  "entityTypesNote": "改动仅影响之后的重新编译；已有实体页会保留其当前类型。",
   "unnamed": "(未命名)",
   "recompileFailed": "重新编译失败",
   "watchStarted": "已启动文件监听",

frontend/src/locales/zh/settings.json

@@ -21,6 +21,8 @@
   },
   "general": {
     "langDesc": "写入编译 prompt 的输出语言，例如 en / 中文 / 日本語",
+    "entityTypesDesc": "编译时为抽取出的实体分类所用的类型词表；各知识库可在其设置中继承或覆盖。",
+    "entityTypesNote": "改动仅影响之后的重新编译；已有实体页会保留其当前类型。",
     "kbRootLabel": "知识库根目录",
     "kbRootDesc": "新建知识库的默认位置（<根目录>/<名称>）；留空则恢复内置默认值。单个知识库可在创建时设置自定义路径。",
     "kbRootPlaceholder": "例如 ~/openkb",