diff --git a/.gitignore b/.gitignore
index 8116c345..59120dbe 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,3 +19,6 @@ playwright-report/
 blob-report/
 playwright/.cache/
 playwright/.auth/
+
+# tsc incremental build artifact
+tsconfig.tsbuildinfo
diff --git a/Dockerfile b/Dockerfile
index 7dc6cc43..7391929b 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -4,10 +4,11 @@ WORKDIR /app
 
 # --- Install ---
 FROM base AS deps
+ENV BUN_CONFIG_MAX_HTTP_REQUESTS=12
 COPY package.json bun.lock .npmrc ./
 COPY patches/ patches/
 COPY tools/ tools/
-RUN bun install --frozen-lockfile
+RUN ok=0; for i in $(seq 1 12); do bun install --frozen-lockfile && ok=1 && break; echo "network retry $i"; done; [ "$ok" = 1 ]
 
 # --- Build ---
 FROM base AS build
@@ -20,11 +21,11 @@ RUN bun run build
 
 # --- Production dependencies (patches applied, then devDeps stripped) ---
 FROM base AS prod-deps
+ENV BUN_CONFIG_MAX_HTTP_REQUESTS=12
 COPY package.json bun.lock .npmrc ./
 COPY patches/ patches/
 COPY tools/ tools/
-RUN bun install --frozen-lockfile \
-    && bun install --frozen-lockfile --production
+RUN ok=0; for i in $(seq 1 12); do bun install --frozen-lockfile && bun install --frozen-lockfile --production && ok=1 && break; echo "network retry $i"; done; [ "$ok" = 1 ]
 
 # --- Runtime ---
 FROM base AS runtime
diff --git a/bun.lock b/bun.lock
index ec864745..c9fed38c 100644
--- a/bun.lock
+++ b/bun.lock
@@ -6,6 +6,10 @@
       "name": "tanstack-start-app",
       "dependencies": {
         "@clickhouse/click-ui": "0.9.1",
+        "@dnd-kit/core": "^6.3.1",
+        "@dnd-kit/modifiers": "9.0.0",
+        "@dnd-kit/sortable": "^10.0.0",
+        "@dnd-kit/utilities": "^3.2.2",
         "@librechat/data-schemas": "^0.0.56",
         "@radix-ui/react-dialog": "1.1.15",
         "@tailwindcss/vite": "^4.3.1",
@@ -178,6 +182,16 @@
 
     "@dabh/diagnostics": ["@dabh/diagnostics@2.0.8", "", { "dependencies": { "@so-ric/colorspace": "^1.1.6", "enabled": "2.0.x", "kuler": "^2.0.0" } }, "sha512-R4MSXTVnuMzGD7bzHdW2ZhhdPC/igELENcq5IjEverBvq5hn1SXCWcsi6eSsdWP0/Ur+SItRRjAktmdoX/8R/Q=="],
 
+    "@dnd-kit/accessibility": ["@dnd-kit/accessibility@3.1.1", "", { "dependencies": { "tslib": "^2.0.0" }, "peerDependencies": { "react": ">=16.8.0" } }, "sha512-2P+YgaXF+gRsIihwwY1gCsQSYnu9Zyj2py8kY5fFvUM1qm2WA2u639R6YNVfU4GWr+ZM5mqEsfHZZLoRONbemw=="],
+
+    "@dnd-kit/core": ["@dnd-kit/core@6.3.1", "", { "dependencies": { "@dnd-kit/accessibility": "^3.1.1", "@dnd-kit/utilities": "^3.2.2", "tslib": "^2.0.0" }, "peerDependencies": { "react": ">=16.8.0", "react-dom": ">=16.8.0" } }, "sha512-xkGBRQQab4RLwgXxoqETICr6S5JlogafbhNsidmrkVv2YRs5MLwpjoF2qpiGjQt8S9AoxtIV603s0GIUpY5eYQ=="],
+
+    "@dnd-kit/modifiers": ["@dnd-kit/modifiers@9.0.0", "", { "dependencies": { "@dnd-kit/utilities": "^3.2.2", "tslib": "^2.0.0" }, "peerDependencies": { "@dnd-kit/core": "^6.3.0", "react": ">=16.8.0" } }, "sha512-ybiLc66qRGuZoC20wdSSG6pDXFikui/dCNGthxv4Ndy8ylErY0N3KVxY2bgo7AWwIbxDmXDg3ylAFmnrjcbVvw=="],
+
+    "@dnd-kit/sortable": ["@dnd-kit/sortable@10.0.0", "", { "dependencies": { "@dnd-kit/utilities": "^3.2.2", "tslib": "^2.0.0" }, "peerDependencies": { "@dnd-kit/core": "^6.3.0", "react": ">=16.8.0" } }, "sha512-+xqhmIIzvAYMGfBYYnbKuNicfSsk4RksY2XdmJhT+HAC01nix6fHCztU68jooFiMUB01Ky3F0FyOvhG/BZrWkg=="],
+
+    "@dnd-kit/utilities": ["@dnd-kit/utilities@3.2.2", "", { "dependencies": { "tslib": "^2.0.0" }, "peerDependencies": { "react": ">=16.8.0" } }, "sha512-+MKAJEOfaBe5SmV6t34p80MMKhjvUz0vRrvVJbPT0WElzaOJ/1xs+D+KDv+tD/NE5ujfrChEcshd4fLn0wpiqg=="],
+
     "@emnapi/core": ["@emnapi/core@1.10.0", "", { "dependencies": { "@emnapi/wasi-threads": "1.2.1", "tslib": "^2.4.0" } }, "sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw=="],
 
     "@emnapi/runtime": ["@emnapi/runtime@1.10.0", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA=="],
diff --git a/package.json b/package.json
index f46add31..cfd2bbb8 100644
--- a/package.json
+++ b/package.json
@@ -23,6 +23,10 @@
   },
   "dependencies": {
     "@clickhouse/click-ui": "0.9.1",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/modifiers": "9.0.0",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@librechat/data-schemas": "^0.0.56",
     "@radix-ui/react-dialog": "1.1.15",
     "@tailwindcss/vite": "^4.3.1",
diff --git a/src/components/SettingsDialog.tsx b/src/components/SettingsDialog.tsx
index e14d01dc..cc6471fa 100644
--- a/src/components/SettingsDialog.tsx
+++ b/src/components/SettingsDialog.tsx
@@ -1,4 +1,5 @@
-import { Dialog } from '@clickhouse/click-ui';
+import { Dialog, Select } from '@clickhouse/click-ui';
+import { useTranslation } from 'react-i18next';
 import type * as t from '@/types';
 import { useTheme } from '@/contexts/ThemeContext';
 import { useLocalize } from '@/hooks';
@@ -11,9 +12,26 @@ const THEME_LABEL_KEYS: Record<t.ThemeOption, string> = {
   dark: 'com_nav_theme_dark',
 };
 
+const LANGUAGE_OPTIONS = ['en', 'zh-Hans'] as const;
+type LanguageOption = (typeof LANGUAGE_OPTIONS)[number];
+const LANGUAGE_LABEL_KEYS: Record<LanguageOption, string> = {
+  en: 'com_ui_language_english',
+  'zh-Hans': 'com_ui_language_zh_hans',
+};
+
 export function SettingsDialog({ open, onClose }: t.SettingsDialogProps) {
   const localize = useLocalize();
   const { theme, setTheme } = useTheme();
+  const { i18n } = useTranslation();
+
+  const resolvedLanguage = i18n.resolvedLanguage ?? i18n.language ?? 'en';
+  const currentLanguage: LanguageOption = resolvedLanguage.startsWith('zh') ? 'zh-Hans' : 'en';
+
+  const setLanguage = (language: LanguageOption) => {
+    i18n.changeLanguage(language);
+    localStorage.setItem('i18nextLng', language);
+    document.documentElement.lang = language;
+  };
 
   return (
     <Dialog
@@ -23,6 +41,7 @@ export function SettingsDialog({ open, onClose }: t.SettingsDialogProps) {
       }}
     >
       <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
         title={localize('com_ui_settings')}
         showClose
         onClose={onClose}
@@ -57,6 +76,26 @@ export function SettingsDialog({ open, onClose }: t.SettingsDialogProps) {
               ))}
             </div>
           </div>
+          <div className="flex items-center justify-between">
+            <div className="flex flex-col gap-0.5">
+              <span className="text-sm font-medium text-(--cui-color-text-default)">
+                {localize('com_ui_language')}
+              </span>
+            </div>
+            <div className="w-40 shrink-0">
+              <Select
+                value={currentLanguage}
+                onSelect={(v) => setLanguage(v as LanguageOption)}
+                aria-label={localize('com_ui_language')}
+              >
+                {LANGUAGE_OPTIONS.map((opt) => (
+                  <Select.Item key={opt} value={opt}>
+                    {localize(LANGUAGE_LABEL_KEYS[opt])}
+                  </Select.Item>
+                ))}
+              </Select>
+            </div>
+          </div>
         </div>
       </Dialog.Content>
     </Dialog>
diff --git a/src/components/Sidebar.tsx b/src/components/Sidebar.tsx
index ce99c1e2..1a37e722 100644
--- a/src/components/Sidebar.tsx
+++ b/src/components/Sidebar.tsx
@@ -31,6 +31,9 @@ const navItems: t.NavItem[] = [
     capability: [SystemCapabilities.READ_ROLES, SystemCapabilities.READ_GROUPS],
   },
   { labelKey: 'com_nav_grants', path: '/grants', icon: 'lock' },
+  { labelKey: 'com_nav_tools', path: '/tools', icon: 'plug' },
+  // 使用统计并入 /tools?tab=usage（2.16.0），侧栏不再单列
+  { labelKey: 'com_nav_services', path: '/services', icon: 'server' },
   { labelKey: 'com_nav_help', path: '/help', icon: 'question' },
 ];
 
diff --git a/src/components/access/CreateGroupDialog.tsx b/src/components/access/CreateGroupDialog.tsx
index f383777a..45b87c37 100644
--- a/src/components/access/CreateGroupDialog.tsx
+++ b/src/components/access/CreateGroupDialog.tsx
@@ -81,6 +81,7 @@ export function CreateGroupDialog({ open, onClose }: t.CreateGroupDialogProps) {
       }}
     >
       <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
         title={localize('com_access_create_group')}
         showClose
         onClose={resetAndClose}
diff --git a/src/components/access/CreateRoleDialog.tsx b/src/components/access/CreateRoleDialog.tsx
index 836f3534..8e9a4de8 100644
--- a/src/components/access/CreateRoleDialog.tsx
+++ b/src/components/access/CreateRoleDialog.tsx
@@ -84,6 +84,7 @@ export function CreateRoleDialog({ open, onClose }: t.CreateRoleDialogProps) {
       }}
     >
       <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
         title={localize('com_access_create_role')}
         showClose
         onClose={resetAndClose}
diff --git a/src/components/access/EditGroupDialog.tsx b/src/components/access/EditGroupDialog.tsx
index 8c0d6cfb..b726d129 100644
--- a/src/components/access/EditGroupDialog.tsx
+++ b/src/components/access/EditGroupDialog.tsx
@@ -131,6 +131,7 @@ export function EditGroupDialog({ group, canManage, onClose }: t.EditGroupDialog
       }}
     >
       <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
         title={localize('com_access_edit_group')}
         showClose
         onClose={onClose}
diff --git a/src/components/access/EditRoleDialog.tsx b/src/components/access/EditRoleDialog.tsx
index 891c1ac2..0d48aece 100644
--- a/src/components/access/EditRoleDialog.tsx
+++ b/src/components/access/EditRoleDialog.tsx
@@ -177,6 +177,7 @@ export function EditRoleDialog({ role, canManage, onClose }: t.EditRoleDialogPro
       }}
     >
       <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
         title={localize('com_access_edit_role')}
         showClose
         onClose={onClose}
diff --git a/src/components/configuration/ConfirmSaveDialog.tsx b/src/components/configuration/ConfirmSaveDialog.tsx
index 6946b968..f8470525 100644
--- a/src/components/configuration/ConfirmSaveDialog.tsx
+++ b/src/components/configuration/ConfirmSaveDialog.tsx
@@ -29,6 +29,7 @@ export function ConfirmSaveDialog({
       }}
     >
       <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
         title={localize('com_config_confirm_save_title')}
         showClose
         onClose={onCancel}
diff --git a/src/components/configuration/DeleteProfileValueModal.tsx b/src/components/configuration/DeleteProfileValueModal.tsx
index f67ce196..178022ce 100644
--- a/src/components/configuration/DeleteProfileValueModal.tsx
+++ b/src/components/configuration/DeleteProfileValueModal.tsx
@@ -21,6 +21,7 @@ export function DeleteProfileValueModal({
       }}
     >
       <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
         title={localize('com_scope_confirm_remove')}
         showClose
         onClose={onCancel}
diff --git a/src/components/configuration/ImportYamlDialog.tsx b/src/components/configuration/ImportYamlDialog.tsx
index 0cdd5ae9..3d841668 100644
--- a/src/components/configuration/ImportYamlDialog.tsx
+++ b/src/components/configuration/ImportYamlDialog.tsx
@@ -199,6 +199,7 @@ export function ImportYamlDialog({
       }}
     >
       <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
         title={localize('com_config_import_yaml_title')}
         showClose
         onClose={handleClose}
diff --git a/src/components/configuration/ProfileIndicator.tsx b/src/components/configuration/ProfileIndicator.tsx
index c7a499a9..6ebdcaa2 100644
--- a/src/components/configuration/ProfileIndicator.tsx
+++ b/src/components/configuration/ProfileIndicator.tsx
@@ -86,6 +86,7 @@ export function ProfileIndicator({
         }}
       >
         <Dialog.Content
+          onInteractOutside={(event) => event.preventDefault()}
           title={localize('com_scope_cascade_title')}
           showClose
           onClose={handleClose}
diff --git a/src/components/configuration/ProfileValueModal.tsx b/src/components/configuration/ProfileValueModal.tsx
index 560bbf65..52e6b152 100644
--- a/src/components/configuration/ProfileValueModal.tsx
+++ b/src/components/configuration/ProfileValueModal.tsx
@@ -37,7 +37,8 @@ export function ProfileValueModal({
         if (!isOpen) onCancel();
       }}
     >
-      <Dialog.Content title={title} showClose onClose={onCancel} className="modal-frost">
+      <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()} title={title} showClose onClose={onCancel} className="modal-frost">
         <div className="flex flex-col gap-4">
           <div className="flex items-center gap-2">
             {scopeConfig && (
diff --git a/src/components/configuration/ResetBaseConfigDialog.tsx b/src/components/configuration/ResetBaseConfigDialog.tsx
index c53dca8f..16f60c31 100644
--- a/src/components/configuration/ResetBaseConfigDialog.tsx
+++ b/src/components/configuration/ResetBaseConfigDialog.tsx
@@ -19,6 +19,7 @@ export function ResetBaseConfigDialog({
       }}
     >
       <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
         title={localize('com_config_reset_base_title')}
         showClose
         onClose={onCancel}
diff --git a/src/components/dashboard/DashboardPage.tsx b/src/components/dashboard/DashboardPage.tsx
index 36507312..b1f1e24a 100644
--- a/src/components/dashboard/DashboardPage.tsx
+++ b/src/components/dashboard/DashboardPage.tsx
@@ -26,6 +26,18 @@ const QUICK_LINKS: (t.NavItem & { descKey: string })[] = [
     icon: 'lock',
     descKey: 'com_dash_grants_desc',
   },
+  {
+    labelKey: 'com_nav_tools',
+    path: '/tools',
+    icon: 'plug',
+    descKey: 'com_dash_tools_desc',
+  },
+  {
+    labelKey: 'com_nav_services',
+    path: '/services',
+    icon: 'server',
+    descKey: 'com_dash_services_desc',
+  },
   {
     labelKey: 'com_nav_help',
     path: '/help',
diff --git a/src/components/grants/AuditLogDetailDrawer.tsx b/src/components/grants/AuditLogDetailDrawer.tsx
index 9c42eea2..a03644a9 100644
--- a/src/components/grants/AuditLogDetailDrawer.tsx
+++ b/src/components/grants/AuditLogDetailDrawer.tsx
@@ -223,6 +223,7 @@ export function AuditLogDetailDrawer({
             )}
           />
           <Dialog.Content
+            onInteractOutside={(event) => event.preventDefault()}
             aria-label={localize('com_audit_detail_title')}
             onEscapeKeyDown={() => onClose()}
             className={cn(
@@ -270,6 +271,7 @@ export function AuditLogDetailDrawer({
             )}
           />
           <Dialog.Content
+            onInteractOutside={(event) => event.preventDefault()}
             aria-label={localize('com_audit_detail_title')}
             onEscapeKeyDown={() => onClose()}
             className={cn(
@@ -322,6 +324,7 @@ export function AuditLogDetailDrawer({
             )}
           />
           <Dialog.Content
+            onInteractOutside={(event) => event.preventDefault()}
             aria-label={localize('com_audit_detail_title')}
             onEscapeKeyDown={() => onClose()}
             className={cn(
@@ -387,6 +390,7 @@ export function AuditLogDetailDrawer({
           )}
         />
         <Dialog.Content
+          onInteractOutside={(event) => event.preventDefault()}
           aria-label={localize('com_audit_detail_title')}
           onEscapeKeyDown={() => onClose()}
           className={cn(
diff --git a/src/components/grants/AuditLogTab.tsx b/src/components/grants/AuditLogTab.tsx
index ce2021e5..378e9980 100644
--- a/src/components/grants/AuditLogTab.tsx
+++ b/src/components/grants/AuditLogTab.tsx
@@ -24,6 +24,7 @@ import {
   exportAuditLogServerFn,
 } from '@/server';
 import {
+  DatePickerCell,
   EmptyState,
   LoadingState,
   Pagination,
@@ -36,58 +37,20 @@ import { AuditLogDetailDrawer } from './AuditLogDetailDrawer';
 import { cn } from '@/utils';
 
 const AUDIT_ACTIONS: readonly AuditAction[] = ['grant.assigned', 'grant.removed'] as const;
-const TARGET_TYPE_OPTIONS: readonly PrincipalType[] = [
+const TARGET_TYPE_OPTIONS = [
   PrincipalType.USER,
   PrincipalType.GROUP,
   PrincipalType.ROLE,
 ] as const;
+const TARGET_TYPE_LABEL_KEYS: Record<(typeof TARGET_TYPE_OPTIONS)[number], string> = {
+  [PrincipalType.USER]: 'com_audit_target_user',
+  [PrincipalType.GROUP]: 'com_audit_target_group',
+  [PrincipalType.ROLE]: 'com_audit_target_role',
+};
 /** Radix `Select.Item` cannot use `value=""` (Radix reserves empty string for
  * "no selection"). Use a non-empty sentinel and translate to `''` in state. */
 const TARGET_TYPE_ALL = '__all__';
 
-/**
- * Wraps a click-ui DatePicker so only the trigger button is tab-focusable.
- * click-ui renders both a PopoverTrigger button AND an inner readonly input,
- * which produces two stops in the tab order. The input has no exposed `tabIndex`
- * prop, so we reach for the DOM node and set it to -1. The class hooks the
- * CSS rule that rounds the trigger's focus outline to match the wrapper border.
- *
- * `resetKey` is the caller's signal that the inner DatePicker has been keyed
- * to remount (e.g. the Clear button bumping a nonce): the inner `<input>` is
- * replaced and the previous patch is lost, so the effect must re-run and
- * re-apply `tabIndex = -1` against the fresh DOM node.
- */
-function DatePickerCell({
-  children,
-  resetKey,
-  inputId,
-}: {
-  children: React.ReactNode;
-  resetKey?: unknown;
-  /**
-   * Stamps the click-ui-rendered `<input>` with an `id` so an external
-   * `<label htmlFor={...}>` (and the e2e WCAG check) can target it. click-ui
-   * has no `id` prop, so we apply it via DOM ref in the same effect that
-   * removes the input from the tab order.
-   */
-  inputId?: string;
-}) {
-  const ref = useRef<HTMLDivElement>(null);
-  useEffect(() => {
-    const node = ref.current;
-    if (!node) return;
-    const input = node.querySelector('input');
-    if (!input) return;
-    input.tabIndex = -1;
-    if (inputId) input.id = inputId;
-  }, [resetKey, inputId]);
-  return (
-    <div ref={ref} className="audit-date-cell contents">
-      {children}
-    </div>
-  );
-}
-
 function downloadBlob(blob: Blob): void {
   const url = URL.createObjectURL(blob);
   const a = document.createElement('a');
@@ -510,7 +473,7 @@ export function AuditLogTab() {
             <Select.Item value={TARGET_TYPE_ALL}>{localize('com_ui_all')}</Select.Item>
             {TARGET_TYPE_OPTIONS.map((pt) => (
               <Select.Item key={pt} value={pt}>
-                {pt}
+                {localize(TARGET_TYPE_LABEL_KEYS[pt])}
               </Select.Item>
             ))}
           </Select>
diff --git a/src/components/grants/EditCapabilitiesDialog.tsx b/src/components/grants/EditCapabilitiesDialog.tsx
index 42662e1c..f9317477 100644
--- a/src/components/grants/EditCapabilitiesDialog.tsx
+++ b/src/components/grants/EditCapabilitiesDialog.tsx
@@ -101,6 +101,7 @@ export function EditCapabilitiesDialog({
       }}
     >
       <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
         title={dialogTitle}
         showClose
         onClose={onClose}
diff --git a/src/components/services/BasemapsManager.tsx b/src/components/services/BasemapsManager.tsx
new file mode 100644
index 00000000..b0fe090a
--- /dev/null
+++ b/src/components/services/BasemapsManager.tsx
@@ -0,0 +1,257 @@
+import { useEffect, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import type { TerraVoxService } from '@/server';
+import { getBasemapsFn, getServicesFn, listServiceMapsFn, replaceBasemapsFn } from '@/server';
+import { useLocalize } from '@/hooks';
+import { CheckIndicator, InlineAction, LoadingState, SearchInput } from '@/components/shared';
+import { cn } from '@/utils';
+import { splitServiceUrl } from './ServiceEditDialog';
+
+/**
+ * 底图管理（2.20.0）：从已绑定的地图服务里选地图加入底图组。数组顺序即
+ * 叠放顺序（前者在下，如影像在下、注记在上）；支持一幅或多幅。
+ * 选择区为双列表（2.21.1，同前端添加图层弹窗）：左列服务（可搜索），右列
+ * 该服务下的地图（可搜索、多选勾选），切换服务时清空本服务的选择。
+ */
+
+const match = (text: string, q: string) => text.toLowerCase().includes(q.trim().toLowerCase());
+
+export function BasemapsManager() {
+  const localize = useLocalize();
+  const queryClient = useQueryClient();
+  const [serviceId, setServiceId] = useState('');
+  const [svcFilter, setSvcFilter] = useState('');
+  const [mapFilter, setMapFilter] = useState('');
+  const [picked, setPicked] = useState<string[]>([]);
+
+  const servicesQuery = useQuery({
+    queryFn: getServicesFn,
+    queryKey: ['terravox', 'admin', 'services'],
+  });
+  const services = (servicesQuery.data?.services ?? []).filter(
+    (s: TerraVoxService) => s.type === 'iserver_map' && s.enabled,
+  );
+
+  useEffect(() => {
+    if (!serviceId && services.length > 0) {
+      setServiceId(services[0].id);
+    }
+  }, [services, serviceId]);
+
+  const groupQuery = useQuery({
+    queryKey: ['terravox', 'admin', 'basemaps'],
+    queryFn: getBasemapsFn,
+  });
+  const mapsQuery = useQuery({
+    queryKey: ['terravox', 'admin', 'basemap-source', serviceId],
+    queryFn: () => listServiceMapsFn({ data: { serviceId } }),
+    enabled: !!serviceId,
+  });
+
+  const save = useMutation({
+    mutationFn: (items: { base_url: string; service_path: string; map_name: string }[]) =>
+      replaceBasemapsFn({ data: { basemaps: items } }),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: ['terravox', 'admin', 'basemaps'] });
+    },
+  });
+
+  const maps = mapsQuery.data?.maps ?? [];
+  const shownMaps = maps.filter((m) => match(m.name, mapFilter));
+  const shownServices = services.filter((s) => match(s.name, svcFilter));
+  /* 当前组里属于本服务的地图名（打开清单时默认勾上，便于增删） */
+  const currentNames = new Set(
+    (groupQuery.data?.basemaps ?? [])
+      .filter((b) => maps.some((m) => m.name === b.map_name))
+      .map((b) => b.map_name),
+  );
+  const effectivePicked =
+    picked.length > 0 || maps.length === 0
+      ? picked
+      : maps.filter((m) => currentNames.has(m.name)).map((m) => m.name);
+
+  const saveGroup = () => {
+    const byName = new Map(maps.map((m) => [m.name, m]));
+    /* 保留其他服务贡献的底图 + 本服务勾选的（按组内原序，新增的追加在后） */
+    const keep = (groupQuery.data?.basemaps ?? []).filter(
+      (b) => !maps.some((m) => m.name === b.map_name) || effectivePicked.includes(b.map_name),
+    );
+    const added = effectivePicked
+      .filter((name) => !keep.some((b) => b.map_name === name))
+      .map((name) => {
+        const m = byName.get(name)!;
+        const { baseUrl, servicePath } = splitServiceUrl(m.path || '');
+        return { base_url: baseUrl, service_path: servicePath, map_name: m.name };
+      });
+    save.mutate([
+      ...keep.map((b) => ({
+        base_url: b.base_url,
+        service_path: b.service_path,
+        map_name: b.map_name,
+      })),
+      ...added,
+    ]);
+  };
+
+  const removeAt = (index: number) => {
+    const rest = (groupQuery.data?.basemaps ?? []).filter((_, i) => i !== index);
+    save.mutate(
+      rest.map((b) => ({
+        base_url: b.base_url,
+        service_path: b.service_path,
+        map_name: b.map_name,
+      })),
+    );
+  };
+
+  const group = groupQuery.data?.basemaps ?? [];
+  const pickedCount = effectivePicked.length;
+  const activeService = services.find((s) => s.id === serviceId);
+
+  return (
+    <div className="flex flex-col gap-4">
+      <p className="text-xs text-(--cui-color-text-muted)">{localize('com_basemaps_hint')}</p>
+
+      <div className="flex flex-col gap-2 rounded-lg border border-(--cui-color-stroke-default) p-4">
+        <div className="flex items-center gap-2">
+          <span className="font-medium text-(--cui-color-text-default)">
+            {localize('com_basemaps_current')}
+          </span>
+          <span className="text-xs text-(--cui-color-text-muted)">
+            {localize('com_basemaps_order_hint')}
+          </span>
+        </div>
+        {groupQuery.isLoading && <LoadingState />}
+        {!groupQuery.isLoading && group.length === 0 && (
+          <p className="text-xs text-(--cui-color-text-muted)">
+            {localize('com_services_basemap_none')}
+          </p>
+        )}
+        <div className="flex flex-col gap-1">
+          {group.map((b, i) => (
+            <div
+              key={b.id}
+              className="flex items-center gap-2 rounded-md border border-(--cui-color-stroke-default) px-2 py-1.5 text-sm"
+            >
+              <span className="text-xs text-(--cui-color-text-muted)">{i}</span>
+              <span className="min-w-0 flex-1 truncate font-medium text-(--cui-color-text-default)">
+                {b.map_name}
+              </span>
+              <code className="min-w-0 flex-1 truncate text-xs text-(--cui-color-text-muted)">
+                {b.url}
+              </code>
+              <InlineAction label={localize('com_ui_delete')} danger onClick={() => removeAt(i)}>
+                ✕
+              </InlineAction>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      <div className="flex flex-col gap-2 rounded-lg border border-(--cui-color-stroke-default) p-4">
+        <span className="font-medium text-(--cui-color-text-default)">
+          {localize('com_basemaps_pick')}
+        </span>
+        <div className="grid grid-cols-2 gap-3">
+          {/* ── 左列：服务（可搜索，点击选中） ── */}
+          <div className="flex flex-col gap-1">
+            <p className="text-xs font-semibold text-(--cui-color-text-muted) uppercase">
+              {localize('com_basemaps_pick_service')}
+            </p>
+            <SearchInput
+              value={svcFilter}
+              onChange={setSvcFilter}
+              placeholder={localize('com_basemaps_search')}
+              ariaLabel={localize('com_basemaps_search')}
+              className="w-full"
+            />
+            <div className="flex max-h-80 min-h-40 flex-col gap-0.5 overflow-y-auto rounded-md border border-(--cui-color-stroke-default) p-1">
+              {shownServices.map((s) => (
+                <button
+                  key={s.id}
+                  type="button"
+                  className={cn(
+                    'flex items-center gap-2 rounded px-2 py-1.5 text-start text-sm transition-colors hover:bg-(--cui-color-background-hover)',
+                    serviceId === s.id && 'bg-(--cui-color-background-hover)',
+                  )}
+                  onClick={() => {
+                    setServiceId(s.id);
+                    setPicked([]);
+                  }}
+                >
+                  <span className="min-w-0 flex-1 truncate">{s.name}</span>
+                </button>
+              ))}
+              {services.length === 0 && (
+                <p className="p-2 text-center text-xs text-(--cui-color-text-muted)">—</p>
+              )}
+            </div>
+          </div>
+          {/* ── 右列：所选服务的地图（可搜索，多选勾选） ── */}
+          <div className="flex flex-col gap-1">
+            <p className="text-xs font-semibold text-(--cui-color-text-muted) uppercase">
+              {activeService
+                ? localize('com_basemaps_pick_layer_of', { service: activeService.name })
+                : localize('com_basemaps_pick_layer')}
+            </p>
+            <SearchInput
+              value={mapFilter}
+              onChange={setMapFilter}
+              placeholder={localize('com_basemaps_search')}
+              ariaLabel={localize('com_basemaps_search')}
+              className="w-full"
+            />
+            <div className="flex max-h-80 min-h-40 flex-col gap-0.5 overflow-y-auto rounded-md border border-(--cui-color-stroke-default) p-1">
+              {mapsQuery.isLoading && <LoadingState />}
+              {mapsQuery.isError && (
+                <p className="p-2 text-xs text-(--cui-color-text-danger)">
+                  {(mapsQuery.error as Error).message}
+                </p>
+              )}
+              {shownMaps.map((m) => {
+                const on = effectivePicked.includes(m.name);
+                return (
+                  <button
+                    key={m.name}
+                    type="button"
+                    aria-pressed={on}
+                    className="flex items-center gap-2 rounded px-1 py-1 text-start text-sm hover:bg-(--cui-color-background-hover)"
+                    onClick={() =>
+                      setPicked((prev) =>
+                        prev.includes(m.name)
+                          ? prev.filter((x) => x !== m.name)
+                          : [...prev, m.name],
+                      )
+                    }
+                  >
+                    <CheckIndicator on={on} />
+                    <span className="min-w-0 flex-1 truncate">{m.name}</span>
+                  </button>
+                );
+              })}
+              {!mapsQuery.isLoading && maps.length === 0 && !!serviceId && (
+                <p className="p-2 text-center text-xs text-(--cui-color-text-muted)">—</p>
+              )}
+            </div>
+          </div>
+        </div>
+        <div className="flex items-center justify-end gap-2">
+          <button
+            type="button"
+            disabled={save.isPending}
+            onClick={saveGroup}
+            className="rounded-lg border border-(--cui-color-accent-primary) px-3 py-1.5 text-sm font-medium text-(--cui-color-accent-primary) transition-colors hover:bg-(--cui-color-background-hover) disabled:opacity-50"
+          >
+            {localize('com_services_basemap_save')}
+            {pickedCount > 0 ? ` (${pickedCount})` : ''}
+          </button>
+          {save.isError && (
+            <span className="text-xs text-(--cui-color-text-danger)">
+              {(save.error as Error).message}
+            </span>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/services/DiscoverDialog.tsx b/src/components/services/DiscoverDialog.tsx
new file mode 100644
index 00000000..18ecce45
--- /dev/null
+++ b/src/components/services/DiscoverDialog.tsx
@@ -0,0 +1,372 @@
+import { useEffect, useState } from 'react';
+import { useMutation } from '@tanstack/react-query';
+import type { DiscoveredService } from '@/server';
+import { createServiceFn, discoverServicesFn } from '@/server';
+import { Button, Dialog } from '@clickhouse/click-ui';
+import { useLocalize } from '@/hooks';
+import { CheckIndicator, SearchInput } from '@/components/shared';
+import { cn, notifySuccess } from '@/utils';
+
+/**
+ * 服务自动发现（2.18.0）：输入 iServer 基地址 → 枚举 REST 地图/数据服务 →
+ * 勾选绑定。地图服务整体勾选（服务级绑定，地图在添加图层时列出）；数据服务
+ * 展开数据源，按数据源逐个绑定（对齐既有绑定粒度）。
+ */
+
+const labelClass = 'text-sm font-medium text-(--cui-color-text-default)';
+const hintClass = 'text-xs text-(--cui-color-text-muted)';
+
+type PickState = {
+  maps: Set<string>; // 服务级地图绑定（name）
+  datasources: Set<string>; // 数据源绑定（`${svc}/${ds}`）
+};
+
+export function DiscoverDialog({
+  open,
+  onClose,
+  onBound,
+  onError,
+}: {
+  open: boolean;
+  onClose: () => void;
+  onBound: () => void;
+  onError: (message: string) => void;
+}) {
+  const localize = useLocalize();
+  const [baseUrl, setBaseUrl] = useState('');
+  const [results, setResults] = useState<DiscoveredService[]>([]);
+  const [base, setBase] = useState('');
+  const [pick, setPick] = useState<PickState>({ maps: new Set(), datasources: new Set() });
+  const [expanded, setExpanded] = useState<Set<string>>(new Set());
+  const [filter, setFilter] = useState('');
+  const [clientError, setClientError] = useState<string | null>(null);
+  const [progress, setProgress] = useState('');
+
+  useEffect(() => {
+    if (open) {
+      setResults([]);
+      setBase('');
+      setPick({ maps: new Set(), datasources: new Set() });
+      setExpanded(new Set());
+      setClientError(null);
+      setProgress('');
+      setFilter('');
+    }
+  }, [open]);
+
+  const discover = useMutation({
+    mutationFn: () => discoverServicesFn({ data: { baseUrl } }),
+    onSuccess: (data) => {
+      setResults(data.services);
+      setBase(data.base);
+      const maps = new Set<string>();
+      const dss = new Set<string>();
+      for (const svc of data.services) {
+        if (svc.status !== 'available') {
+          continue;
+        }
+        if (svc.type === 'iserver_map') {
+          maps.add(svc.name);
+        }
+        for (const ds of svc.datasources) {
+          dss.add(`${svc.name}/${ds}`);
+        }
+      }
+      setPick({ maps, datasources: dss });
+      setClientError(null);
+    },
+    onError: (error: Error) => setClientError(error.message),
+  });
+
+  const bind = useMutation({
+    mutationFn: async () => {
+      const targets: { name: string; type: string; service_path: string; datasource: string }[] =
+        [];
+      /* 只绑当前搜索过滤下可见的勾选项（所见即所绑）：搜索框只过滤显示曾
+       * 导致过滤后点绑定把被隐藏的预勾选服务一并绑入（2026-09-30 误绑事故）。 */
+      const needle = filter.trim().toLowerCase();
+      for (const svc of results) {
+        if (svc.status !== 'available') {
+          continue;
+        }
+        if (needle && !svc.name.toLowerCase().includes(needle)) {
+          continue;
+        }
+        if (svc.type === 'iserver_map' && pick.maps.has(svc.name)) {
+          targets.push({
+            name: svc.name,
+            type: svc.type,
+            service_path: svc.service_path,
+            datasource: '',
+          });
+        }
+        if (svc.type === 'iserver_data') {
+          for (const ds of svc.datasources) {
+            if (pick.datasources.has(`${svc.name}/${ds}`)) {
+              targets.push({
+                name: svc.datasources.length > 1 ? `${svc.name}·${ds}` : svc.name,
+                type: svc.type,
+                service_path: svc.service_path,
+                datasource: ds,
+              });
+            }
+          }
+        }
+      }
+      let done = 0;
+      const failures: string[] = [];
+      for (const target of targets) {
+        setProgress(`${done}/${targets.length}`);
+        try {
+          await createServiceFn({
+            data: {
+              service: {
+                name: target.name,
+                type: target.type,
+                base_url: base,
+                service_path: target.service_path,
+                datasource: target.datasource,
+                map_name: '',
+                allowed_groups: ['*'],
+                enabled: true,
+              },
+            },
+          });
+        } catch (error) {
+          failures.push(`${target.name}: ${(error as Error).message}`);
+        }
+        done += 1;
+      }
+      if (failures.length > 0) {
+        throw new Error(failures.join('；'));
+      }
+      return targets.length;
+    },
+    onSuccess: (count) => {
+      onError('');
+      onBound();
+      notifySuccess(localize('com_services_discover_bind') + ' (' + count + ')');
+    },
+    onError: (error: Error) => setClientError(error.message),
+  });
+
+  const toggleMap = (name: string) =>
+    setPick((prev) => {
+      const maps = new Set(prev.maps);
+      if (maps.has(name)) {
+        maps.delete(name);
+      } else {
+        maps.add(name);
+      }
+      return { ...prev, maps };
+    });
+
+  const toggleDs = (key: string) =>
+    setPick((prev) => {
+      const datasources = new Set(prev.datasources);
+      if (datasources.has(key)) {
+        datasources.delete(key);
+      } else {
+        datasources.add(key);
+      }
+      return { ...prev, datasources };
+    });
+
+  const pickedCount = pick.maps.size + pick.datasources.size;
+  const available = results.filter((s) => s.status === 'available');
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(isOpen) => {
+        if (!isOpen) onClose();
+      }}
+    >
+      <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
+        title={localize('com_services_discover_title')}
+        showClose
+        className="modal-frost"
+      >
+        <div className="flex flex-col gap-3">
+          <div className="flex items-end gap-2">
+            <label className="flex min-w-0 flex-1 flex-col gap-1">
+              <span className={labelClass}>{localize('com_services_discover_base')}</span>
+              <input
+                className="config-input w-full"
+                value={baseUrl}
+                placeholder={localize('com_services_discover_base_hint')}
+                onChange={(e) => setBaseUrl(e.target.value)}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter' && baseUrl.trim() && !discover.isPending) {
+                    discover.mutate();
+                  }
+                }}
+              />
+            </label>
+            <Button
+              type="primary"
+              label={
+                discover.isPending
+                  ? localize('com_services_discover_running')
+                  : localize('com_services_discover_run')
+              }
+              disabled={!baseUrl.trim() || discover.isPending}
+              onClick={() => discover.mutate()}
+            />
+          </div>
+          <p className={hintClass}>{localize('com_services_discover_base_hint')}</p>
+
+          {clientError && (
+            <p role="alert" className="text-sm text-(--cui-color-text-danger)">
+              {clientError}
+            </p>
+          )}
+
+          {results.length > 0 && (
+            <SearchInput
+              value={filter}
+              onChange={setFilter}
+              placeholder={localize('com_toolbox_map_search')}
+              ariaLabel={localize('com_toolbox_map_search')}
+              className="w-full"
+            />
+          )}
+          {results.length > 0 && (
+            <div className="flex max-h-[45vh] flex-col gap-1 overflow-y-auto rounded-lg border border-(--cui-color-stroke-default) p-2">
+              {available.length === 0 && (
+                <p className="p-3 text-center text-xs text-(--cui-color-text-muted)">
+                  {localize('com_services_discover_empty')}
+                </p>
+              )}
+              {available
+                .filter((svc) => svc.name.toLowerCase().includes(filter.trim().toLowerCase()))
+                .map((svc) => {
+                  const isMap = svc.type === 'iserver_map';
+                  const dsKeys = svc.datasources.map((ds) => `${svc.name}/${ds}`);
+                  const checked = isMap
+                    ? pick.maps.has(svc.name)
+                    : dsKeys.length > 0 && dsKeys.every((k) => pick.datasources.has(k));
+                  return (
+                    <div
+                      key={svc.name}
+                      className="rounded-md border border-(--cui-color-stroke-default) px-2 py-1.5"
+                    >
+                      <div className="flex items-center gap-2">
+                        <button
+                          type="button"
+                          aria-pressed={checked}
+                          className="flex min-w-0 flex-1 items-center gap-2 text-start"
+                          onClick={() => {
+                            if (isMap) {
+                              toggleMap(svc.name);
+                            } else {
+                              const allOn = dsKeys.every((k) => pick.datasources.has(k));
+                              setPick((prev) => {
+                                const datasources = new Set(prev.datasources);
+                                for (const k of dsKeys) {
+                                  if (allOn) {
+                                    datasources.delete(k);
+                                  } else {
+                                    datasources.add(k);
+                                  }
+                                }
+                                return { ...prev, datasources };
+                              });
+                            }
+                          }}
+                        >
+                          <CheckIndicator on={checked} />
+                          <span className="min-w-0 flex-1 truncate font-medium text-(--cui-color-text-default)">
+                            {svc.name}
+                          </span>
+                          <span className="shrink-0 text-xs text-(--cui-color-text-muted)">
+                            {isMap
+                              ? localize('com_services_discover_maps_n', {
+                                  n: String(svc.maps.length),
+                                })
+                              : localize('com_services_discover_ds_n', {
+                                  n: String(svc.datasources.length),
+                                })}
+                          </span>
+                        </button>
+                        {!isMap && svc.datasources.length > 0 && (
+                          <button
+                            type="button"
+                            className="text-xs text-(--cui-color-text-muted) hover:text-(--cui-color-text-default)"
+                            onClick={() =>
+                              setExpanded((prev) => {
+                                const next = new Set(prev);
+                                if (next.has(svc.name)) {
+                                  next.delete(svc.name);
+                                } else {
+                                  next.add(svc.name);
+                                }
+                                return next;
+                              })
+                            }
+                          >
+                            {expanded.has(svc.name) ? '▾' : '▸'}
+                          </button>
+                        )}
+                      </div>
+                      {isMap && svc.maps.length > 0 && (
+                        <p className={cn('truncate pt-1', hintClass)} title={svc.maps.join('、')}>
+                          {svc.maps.slice(0, 6).join('、')}
+                          {svc.maps.length > 6 ? ' …' : ''}
+                        </p>
+                      )}
+                      {!isMap && expanded.has(svc.name) && (
+                        <div className="mt-1 flex flex-col gap-0.5 border-t border-(--cui-color-stroke-default) pt-1">
+                          {svc.datasources.map((ds) => {
+                            const key = `${svc.name}/${ds}`;
+                            const on = pick.datasources.has(key);
+                            return (
+                              <button
+                                key={ds}
+                                type="button"
+                                aria-pressed={on}
+                                className="flex items-center gap-2 rounded px-1 py-0.5 text-start text-xs hover:bg-(--cui-color-background-hover)"
+                                onClick={() => toggleDs(key)}
+                              >
+                                <CheckIndicator on={on} />
+                                <span className="min-w-0 flex-1 truncate">{ds}</span>
+                              </button>
+                            );
+                          })}
+                        </div>
+                      )}
+                    </div>
+                  );
+                })}
+              {results.some((s) => s.status !== 'available') && (
+                <p className={cn('px-1 pt-1', hintClass)}>
+                  {results.filter((s) => s.status !== 'available').length}{' '}
+                  {localize('com_services_discover_unavailable')}
+                </p>
+              )}
+            </div>
+          )}
+
+          <div className="flex items-center justify-between gap-2">
+            <span className={hintClass}>
+              {bind.isPending ? `${localize('com_services_discover_bind')} ${progress}` : ''}
+            </span>
+            <div className="flex gap-2">
+              <Button type="secondary" label={localize('com_ui_cancel')} onClick={onClose} />
+              <Button
+                type="primary"
+                label={
+                  localize('com_services_discover_bind') +
+                  (pickedCount > 0 ? ` (${pickedCount})` : '')
+                }
+                disabled={pickedCount === 0 || bind.isPending}
+                onClick={() => bind.mutate()}
+              />
+            </div>
+          </div>
+        </div>
+      </Dialog.Content>
+    </Dialog>
+  );
+}
diff --git a/src/components/services/ServiceEditDialog.tsx b/src/components/services/ServiceEditDialog.tsx
new file mode 100644
index 00000000..1d13ac9c
--- /dev/null
+++ b/src/components/services/ServiceEditDialog.tsx
@@ -0,0 +1,342 @@
+import { useEffect, useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { Switch } from '@clickhouse/click-ui';
+import type { TerraVoxService } from '@/server';
+import { getServiceDatasourcesFn } from '@/server';
+import { useLocalize } from '@/hooks';
+import { cn } from '@/utils';
+import { FormDialog } from '@/components/shared';
+
+/** Nextcloud OIDC carries these role groups (assembled-platform-plan section 5). */
+const KNOWN_GROUPS = ['team-manager', 'team-editor', 'team-viewer'];
+
+interface Draft {
+  name: string;
+  type: 'iserver_map' | 'iserver_data';
+  /** 完整服务地址（2.19.0）：…/iserver/services/<服务>/rest[/maps|/data]，提交时拆分入库。 */
+  serviceUrl: string;
+  datasource: string;
+  /** 地图绑定可指定服务内具体地图（2.18.0）；空 = 服务级（添加图层时列出选择）。 */
+  mapName: string;
+  allowedGroups: string[];
+  enabled: boolean;
+}
+
+/** 完整地址 → {base_url, service_path}（存储仍是两列，UI 只暴露一个框）。 */
+export function splitServiceUrl(url: string): { baseUrl: string; servicePath: string } {
+  const clean = url.trim().replace(/\/+$/, '');
+  const marker = '/iserver/services/';
+  const i = clean.indexOf(marker);
+  if (i < 0) {
+    return { baseUrl: clean, servicePath: '' };
+  }
+  return { baseUrl: clean.slice(0, i), servicePath: clean.slice(i + marker.length) };
+}
+
+export function joinServiceUrl(baseUrl: string, servicePath: string): string {
+  return baseUrl.replace(/\/+$/, '') + '/iserver/services/' + servicePath.replace(/^\/+/, '');
+}
+
+interface Props {
+  open: boolean;
+  service: TerraVoxService | null;
+  saving: boolean;
+  error?: string;
+  onSubmit: (input: Draft & { baseUrl: string; servicePath: string }) => void;
+  onClose: () => void;
+}
+
+const labelClass = 'text-sm font-medium text-(--cui-color-text-default)';
+const hintClass = 'mt-1 text-xs text-(--cui-color-text-muted)';
+
+export function ServiceEditDialog({ open, service, saving, error, onSubmit, onClose }: Props) {
+  const localize = useLocalize();
+  const [draft, setDraft] = useState<Draft>(() => toDraft(service));
+  const [customGroup, setCustomGroup] = useState('');
+  const [clientError, setClientError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (open) {
+      setDraft(toDraft(service));
+      setCustomGroup('');
+      setClientError(null);
+    }
+  }, [open, service]);
+
+  const set = <K extends keyof Draft>(field: K, value: Draft[K]) =>
+    setDraft((prev) => ({ ...prev, [field]: value }));
+
+  const toggleGroup = (name: string) =>
+    setDraft((prev) => ({
+      ...prev,
+      allowedGroups: prev.allowedGroups.includes(name)
+        ? prev.allowedGroups.filter((g) => g !== name)
+        : [...prev.allowedGroups, name],
+    }));
+
+  const addCustomGroup = () => {
+    const name = customGroup.trim();
+    if (name && !draft.allowedGroups.includes(name)) {
+      set('allowedGroups', [...draft.allowedGroups, name]);
+    }
+    setCustomGroup('');
+  };
+
+  const submit = () => {
+    const { baseUrl, servicePath } = splitServiceUrl(draft.serviceUrl);
+    if (!draft.name.trim() || !baseUrl || !servicePath) {
+      setClientError(localize('com_services_err_required'));
+      return;
+    }
+    if (draft.type === 'iserver_data' && !draft.datasource.trim()) {
+      setClientError(localize('com_services_err_datasource'));
+      return;
+    }
+    if (draft.allowedGroups.length === 0) {
+      setClientError(localize('com_services_err_groups'));
+      return;
+    }
+    setClientError(null);
+    /* 用当前表单整体覆盖旧记录：按类型剥离无关字段，避免旧数据源/地图名
+     * 残留导致类型切换后保存被网关 400 拒绝 */
+    onSubmit({
+      ...draft,
+      baseUrl,
+      servicePath,
+      datasource: draft.type === 'iserver_data' ? draft.datasource.trim() : '',
+      mapName: draft.type === 'iserver_map' ? (draft.mapName ?? '').trim() : '',
+    });
+  };
+
+  const groupChips = [
+    '*',
+    ...KNOWN_GROUPS,
+    ...draft.allowedGroups.filter((g) => g !== '*' && !KNOWN_GROUPS.includes(g)),
+  ];
+
+  return (
+    <FormDialog
+      open={open}
+      size="lg"
+      title={service ? localize('com_services_edit_title') : localize('com_services_add_title')}
+      submitLabel={localize('com_ui_save')}
+      saving={saving}
+      error={clientError ?? error}
+      onSubmit={submit}
+      onClose={onClose}
+    >
+      <div className="flex flex-col gap-4 text-sm">
+        <div>
+          <span className={labelClass}>{localize('com_services_field_type')}</span>
+          <div className="mt-1 flex gap-2">
+            {(['iserver_map', 'iserver_data'] as const).map((type) => (
+              <button
+                key={type}
+                type="button"
+                aria-pressed={draft.type === type}
+                onClick={() =>
+                  setDraft((prev) => ({
+                    ...prev,
+                    type,
+                    /* 覆盖清空另一类型的字段：地图服务不带数据源、数据服务不带地图名 */
+                    datasource: type === 'iserver_map' ? '' : prev.datasource,
+                    mapName: type === 'iserver_data' ? '' : prev.mapName,
+                  }))
+                }
+                className={cn(
+                  'rounded-lg border px-3 py-1.5 transition-colors',
+                  draft.type === type
+                    ? 'border-(--cui-color-accent-primary) bg-(--cui-color-accent-primary-muted) text-(--cui-color-text-default)'
+                    : 'border-(--cui-color-stroke-default) text-(--cui-color-text-muted)',
+                )}
+              >
+                {localize(
+                  type === 'iserver_map' ? 'com_services_type_map' : 'com_services_type_data',
+                )}
+              </button>
+            ))}
+          </div>
+          <p className={hintClass}>{localize('com_services_type_hint')}</p>
+        </div>
+
+        <label className="flex flex-col gap-1">
+          <span className={labelClass}>{localize('com_services_field_name')}</span>
+          <input
+            className="config-input w-full"
+            value={draft.name}
+            onChange={(e) => set('name', e.target.value)}
+          />
+        </label>
+
+        <label className="flex flex-col gap-1">
+          <span className={labelClass}>{localize('com_services_field_service_url')}</span>
+          <input
+            className="config-input w-full"
+            value={draft.serviceUrl}
+            placeholder={localize('com_services_service_url_hint')}
+            onChange={(e) => set('serviceUrl', e.target.value)}
+          />
+          <span className={hintClass}>{localize('com_services_service_url_hint')}</span>
+        </label>
+
+        {draft.type === 'iserver_map' && (
+          <label className="flex flex-col gap-1">
+            <span className={labelClass}>{localize('com_services_field_map_name')}</span>
+            <input
+              className="config-input w-full"
+              value={draft.mapName}
+              placeholder={localize('com_services_map_name_hint')}
+              onChange={(e) => set('mapName', e.target.value)}
+            />
+            <span className={hintClass}>{localize('com_services_map_name_hint2')}</span>
+          </label>
+        )}
+
+        {/* 数据服务：列出数据源，点选回填 */}
+        {draft.type === 'iserver_data' && service?.id && (
+          <DatasourceSection serviceId={service.id} onPick={(ds) => set('datasource', ds)} />
+        )}
+
+        {draft.type === 'iserver_data' && (
+          <label className="flex flex-col gap-1">
+            <span className={labelClass}>{localize('com_services_field_datasource')}</span>
+            <input
+              className="config-input w-full"
+              value={draft.datasource}
+              placeholder="BeiJing"
+              onChange={(e) => set('datasource', e.target.value)}
+            />
+            <span className={hintClass}>{localize('com_services_datasource_hint')}</span>
+          </label>
+        )}
+
+        <div>
+          <span className={labelClass}>{localize('com_services_field_allowed_groups')}</span>
+          <div className="mt-1 flex flex-wrap gap-2">
+            {groupChips.map((name) => {
+              const active = draft.allowedGroups.includes(name);
+              return (
+                <button
+                  key={name}
+                  type="button"
+                  aria-pressed={active}
+                  onClick={() => toggleGroup(name)}
+                  className={cn(
+                    'rounded-full border px-3 py-1 text-xs transition-colors',
+                    active
+                      ? 'border-(--cui-color-accent-primary) bg-(--cui-color-accent-primary-muted) text-(--cui-color-text-default)'
+                      : 'border-(--cui-color-stroke-default) text-(--cui-color-text-muted) hover:bg-(--cui-color-background-hover)',
+                  )}
+                >
+                  {name === '*' ? localize('com_tools_all_groups') : name}
+                </button>
+              );
+            })}
+          </div>
+          <div className="mt-2 flex gap-2">
+            <input
+              className="config-input w-full max-w-48"
+              value={customGroup}
+              placeholder={localize('com_services_group_custom_placeholder')}
+              onChange={(e) => setCustomGroup(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter') {
+                  e.preventDefault();
+                  addCustomGroup();
+                }
+              }}
+            />
+            <button
+              type="button"
+              onClick={addCustomGroup}
+              className="rounded-lg border border-(--cui-color-stroke-default) px-3 py-1.5 text-xs text-(--cui-color-text-muted) hover:bg-(--cui-color-background-hover)"
+            >
+              {localize('com_services_group_add')}
+            </button>
+          </div>
+          <p className={hintClass}>{localize('com_services_groups_hint')}</p>
+        </div>
+
+        <div className="flex items-center justify-between gap-2">
+          <span className={labelClass}>{localize('com_services_field_enabled')}</span>
+          <Switch
+            checked={draft.enabled}
+            onCheckedChange={(v) => set('enabled', v)}
+            aria-label={localize('com_services_field_enabled')}
+          />
+        </div>
+      </div>
+    </FormDialog>
+  );
+}
+
+function toDraft(service: TerraVoxService | null): Draft {
+  if (!service) {
+    return {
+      name: '',
+      type: 'iserver_map',
+      serviceUrl: '',
+      datasource: '',
+      mapName: '',
+      allowedGroups: ['*'],
+      enabled: true,
+    };
+  }
+  return {
+    name: service.name,
+    type: service.type,
+    serviceUrl: joinServiceUrl(service.base_url, service.service_path),
+    datasource: service.datasource,
+    mapName: service.map_name ?? '',
+    allowedGroups: service.allowed_groups,
+    enabled: service.enabled,
+  };
+}
+
+/** 数据服务：列出数据源清单，点选回填 datasource 输入框。 */
+function DatasourceSection({
+  serviceId,
+  onPick,
+}: {
+  serviceId: string;
+  onPick: (ds: string) => void;
+}) {
+  const localize = useLocalize();
+  const [open, setOpen] = useState(false);
+  const query = useQuery({
+    queryKey: ['terravox', 'admin', 'service-datasources', serviceId],
+    queryFn: () => getServiceDatasourcesFn({ data: { serviceId } }),
+    enabled: open,
+  });
+  const names: string[] =
+    (query.data as { datasource_names?: string[]; datasources?: string[] } | undefined)
+      ?.datasource_names ??
+    (query.data as { datasources?: string[] } | undefined)?.datasources ??
+    [];
+  return (
+    <div className="flex flex-col gap-1">
+      <button
+        type="button"
+        className="self-start rounded-lg border border-(--cui-color-stroke-default) px-2 py-1 text-xs text-(--cui-color-text-muted) hover:bg-(--cui-color-background-hover)"
+        onClick={() => setOpen((v) => !v)}
+      >
+        {localize('com_services_list_datasources')}
+      </button>
+      {open && (
+        <div className="flex flex-wrap gap-1">
+          {names.map((ds) => (
+            <button
+              key={ds}
+              type="button"
+              onClick={() => onPick(ds)}
+              className="rounded-full border border-(--cui-color-stroke-default) px-2 py-0.5 text-xs text-(--cui-color-text-muted) hover:bg-(--cui-color-background-hover)"
+            >
+              {ds}
+            </button>
+          ))}
+          {names.length === 0 && !query.isLoading && <span className={hintClass}>—</span>}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/components/services/ServicesPage.tsx b/src/components/services/ServicesPage.tsx
new file mode 100644
index 00000000..7178b120
--- /dev/null
+++ b/src/components/services/ServicesPage.tsx
@@ -0,0 +1,337 @@
+import { useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Icon, Tabs } from '@clickhouse/click-ui';
+import type { TerraVoxService } from '@/server';
+import {
+  createServiceFn,
+  deleteServiceFn,
+  probeServiceFn,
+  servicesQueryOptions,
+  updateServiceFn,
+} from '@/server';
+import { EmptyState, InlineAction, LoadingState } from '@/components/shared';
+import { ConfirmDialog } from '@/components/access';
+import { useLocalize } from '@/hooks';
+import { cn } from '@/utils';
+import { ServiceEditDialog } from './ServiceEditDialog';
+import { DiscoverDialog } from './DiscoverDialog';
+import { BasemapsManager } from './BasemapsManager';
+
+const TAG =
+  'rounded-full border border-(--cui-color-stroke-default) px-2 py-0.5 text-xs text-(--cui-color-text-muted)';
+
+const STATUS_STYLE: Record<string, string> = {
+  available: 'bg-(--cui-color-icon-success)',
+  unavailable: 'bg-(--cui-color-icon-critical)',
+  unprobed: 'bg-(--cui-color-icon-warning)',
+};
+
+/** Bindings list: one row = one map (iserver_map) or one datasource
+ * (iserver_data). Create/ edit runs an immediate probe; probe re-checks. */
+export function ServicesPage() {
+  const localize = useLocalize();
+  const queryClient = useQueryClient();
+  const [editOpen, setEditOpen] = useState(false);
+  const [editing, setEditing] = useState<TerraVoxService | null>(null);
+  const [deleteTarget, setDeleteTarget] = useState<TerraVoxService | null>(null);
+  const [mutError, setMutError] = useState<string | null>(null);
+  const [discoverOpen, setDiscoverOpen] = useState(false);
+  /* 服务管理两个标签：服务绑定 / 底图管理（2.20.0） */
+  const [tab, setTab] = useState<'bindings' | 'basemaps'>('bindings');
+  /* 绑定列表按类型筛选（2.21.1）：全部 / 地图服务 / 数据服务 */
+  const [typeFilter, setTypeFilter] = useState<'all' | 'iserver_map' | 'iserver_data'>('all');
+
+  const servicesQuery = useQuery(servicesQueryOptions);
+  const services = servicesQuery.data?.services ?? [];
+  const shownServices =
+    typeFilter === 'all' ? services : services.filter((s) => s.type === typeFilter);
+
+  const invalidate = () => {
+    void queryClient.invalidateQueries({ queryKey: ['terravox', 'admin', 'services'] });
+  };
+
+  const toInput = (draft: {
+    name: string;
+    type: string;
+    baseUrl: string;
+    servicePath: string;
+    datasource: string;
+    mapName?: string;
+    allowedGroups: string[];
+    enabled: boolean;
+  }) => ({
+    name: draft.name.trim(),
+    type: draft.type,
+    base_url: draft.baseUrl.trim(),
+    service_path: draft.servicePath.trim(),
+    datasource: draft.datasource.trim(),
+    map_name: (draft.mapName ?? '').trim(),
+    allowed_groups: draft.allowedGroups,
+    enabled: draft.enabled,
+  });
+
+  const saveMutation = useMutation({
+    mutationFn: async (draft: Parameters<typeof toInput>[0]) =>
+      editing
+        ? updateServiceFn({ data: { serviceId: editing.id, service: toInput(draft) } })
+        : createServiceFn({ data: { service: toInput(draft) } }),
+    onSuccess: () => {
+      setEditOpen(false);
+      setEditing(null);
+      setMutError(null);
+      invalidate();
+    },
+    onError: () => {
+      /* dialog stays open and shows the error */
+    },
+  });
+
+  const probeMutation = useMutation({
+    mutationFn: (serviceId: string) => probeServiceFn({ data: { serviceId } }),
+    onSuccess: () => {
+      setMutError(null);
+      invalidate();
+    },
+    onError: (error: Error) => setMutError(error.message),
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: (serviceId: string) => deleteServiceFn({ data: { serviceId } }),
+    onSuccess: () => {
+      setDeleteTarget(null);
+      setMutError(null);
+      invalidate();
+    },
+    onError: (error: Error) => setMutError(error.message),
+  });
+
+  /* 类型筛选 chips：全部 / 地图服务 / 数据服务，带实时计数 */
+  const mapCount = services.filter((s) => s.type === 'iserver_map').length;
+  const filterChips = [
+    ['all', localize('com_services_type_all'), services.length],
+    ['iserver_map', localize('com_services_type_map'), mapCount],
+    ['iserver_data', localize('com_services_type_data'), services.length - mapCount],
+  ] as const;
+
+  return (
+    <div
+      role="region"
+      aria-label={localize('com_services_title')}
+      className="flex min-h-0 flex-1 flex-col overflow-hidden px-4 pt-2"
+    >
+      {' '}
+      <Tabs
+        value={tab}
+        onValueChange={(v) => setTab(v as typeof tab)}
+        ariaLabel={localize('com_services_title')}
+      >
+        <Tabs.TriggersList>
+          <Tabs.Trigger value="bindings">{localize('com_services_tab_bindings')}</Tabs.Trigger>
+          <Tabs.Trigger value="basemaps">{localize('com_services_tab_basemaps')}</Tabs.Trigger>
+        </Tabs.TriggersList>
+      </Tabs>
+      <div className="flex min-h-0 flex-1 flex-col overflow-y-auto pt-4 pb-6">
+        {tab === 'basemaps' && <BasemapsManager />}
+
+        {tab === 'bindings' && (
+          <div className="flex flex-col gap-4">
+            <div className="flex flex-wrap items-center gap-3">
+              <p className="text-xs text-(--cui-color-text-muted)">
+                {localize('com_services_hint')}
+              </p>
+              <button
+                type="button"
+                onClick={() => {
+                  setEditing(null);
+                  setEditOpen(true);
+                }}
+                className="ms-auto flex items-center gap-1.5 rounded-lg bg-(--cui-color-accent-primary) px-3 py-1.5 text-sm font-medium text-white transition-colors hover:opacity-90"
+              >
+                <Icon name="plus" size="sm" />
+                {localize('com_services_add_button')}
+              </button>
+              <button
+                type="button"
+                onClick={() => setDiscoverOpen(true)}
+                className="flex items-center gap-1.5 rounded-lg border border-(--cui-color-stroke-default) px-3 py-1.5 text-sm font-medium text-(--cui-color-text-default) transition-colors hover:bg-(--cui-color-background-hover)"
+              >
+                {localize('com_services_discover')}
+              </button>
+            </div>
+
+            {mutError && (
+              <p role="alert" className="text-sm text-(--cui-color-text-danger)">
+                {mutError}
+              </p>
+            )}
+
+            {/* 类型筛选 chips：全部 / 地图服务 / 数据服务，带计数 */}
+            {services.length > 0 && (
+              <div className="flex flex-wrap items-center gap-2">
+                {filterChips.map(([key, label, count]) => (
+                  <button
+                    key={key}
+                    type="button"
+                    aria-pressed={typeFilter === key}
+                    onClick={() => setTypeFilter(key)}
+                    className={cn(
+                      'flex items-center gap-1.5 rounded-full border px-3 py-1 text-xs transition-colors',
+                      typeFilter === key
+                        ? 'border-(--cui-color-accent-primary) bg-(--cui-color-background-hover) font-medium text-(--cui-color-text-default)'
+                        : 'border-(--cui-color-stroke-default) text-(--cui-color-text-muted) hover:bg-(--cui-color-background-hover) hover:text-(--cui-color-text-default)',
+                    )}
+                  >
+                    {label}
+                    <span
+                      className={cn(
+                        'rounded-full px-1.5 text-[10px]',
+                        typeFilter === key
+                          ? 'bg-(--cui-color-accent-primary) text-white'
+                          : 'bg-(--cui-color-background-hover) text-(--cui-color-text-muted)',
+                      )}
+                    >
+                      {count}
+                    </span>
+                  </button>
+                ))}
+              </div>
+            )}
+
+            {servicesQuery.isLoading && <LoadingState />}
+            {servicesQuery.isError && (
+              <EmptyState
+                message={
+                  (servicesQuery.error as Error)?.message ?? localize('com_tools_retry_later')
+                }
+              />
+            )}
+            {!servicesQuery.isLoading && !servicesQuery.isError && services.length === 0 && (
+              <EmptyState message={localize('com_services_empty')} />
+            )}
+
+            <div className="grid grid-cols-1 gap-3 xl:grid-cols-2">
+              {shownServices.map((service) => (
+                <div
+                  key={service.id}
+                  className="flex flex-col gap-2 rounded-lg border border-(--cui-color-stroke-default) p-4"
+                >
+                  <div className="flex items-start justify-between gap-2">
+                    <div className="min-w-0">
+                      <div className="flex flex-wrap items-center gap-2">
+                        <span className="font-medium text-(--cui-color-text-default)">
+                          {service.name}
+                        </span>
+                        <span className={TAG}>
+                          {localize(
+                            service.type === 'iserver_map'
+                              ? 'com_services_type_map'
+                              : 'com_services_type_data',
+                          )}
+                        </span>
+                        <span
+                          className="flex items-center gap-1"
+                          title={service.probe_detail ?? ''}
+                        >
+                          <span
+                            aria-hidden="true"
+                            className={cn(
+                              'inline-block h-2 w-2 rounded-full',
+                              STATUS_STYLE[service.status] ?? STATUS_STYLE.unprobed,
+                            )}
+                          />
+                          <span className="text-xs text-(--cui-color-text-muted)">
+                            {localize(`com_services_status_${service.status}`)}
+                          </span>
+                        </span>
+                        {!service.enabled && (
+                          <span className={TAG}>{localize('com_services_disabled')}</span>
+                        )}
+                      </div>
+                      <code className="block truncate pt-0.5 text-xs text-(--cui-color-text-muted)">
+                        {service.base_url}/iserver/services/{service.service_path}
+                        {service.type === 'iserver_data' && service.datasource
+                          ? ` · ${service.datasource}`
+                          : ''}
+                      </code>
+                    </div>
+                    {/* 行内操作（2.19.0）：平铺按钮替代三点菜单，减少操作成本 */}
+                    <div className="flex shrink-0 items-center gap-1">
+                      <InlineAction
+                        label={localize('com_ui_edit')}
+                        onClick={() => {
+                          setEditing(service);
+                          setEditOpen(true);
+                        }}
+                      >
+                        ✎
+                      </InlineAction>
+                      <InlineAction
+                        label={localize('com_services_probe')}
+                        onClick={() => probeMutation.mutate(service.id)}
+                      >
+                        ⟳
+                      </InlineAction>
+                      <InlineAction
+                        label={localize('com_ui_delete')}
+                        danger
+                        onClick={() => setDeleteTarget(service)}
+                      >
+                        ✕
+                      </InlineAction>
+                    </div>
+                  </div>
+                  {service.probe_detail && (
+                    <p className="line-clamp-2 text-xs text-(--cui-color-text-muted)">
+                      {service.probe_detail}
+                    </p>
+                  )}
+                  <div className="mt-auto flex flex-wrap items-center gap-2 pt-1">
+                    {service.allowed_groups.map((group) => (
+                      <span key={group} className={TAG}>
+                        {group === '*' ? localize('com_tools_all_groups') : group}
+                      </span>
+                    ))}
+                  </div>
+                </div>
+              ))}
+            </div>
+
+            <ServiceEditDialog
+              open={editOpen}
+              service={editing}
+              saving={saveMutation.isPending}
+              error={saveMutation.isError ? (saveMutation.error as Error).message : undefined}
+              onSubmit={(draft) => saveMutation.mutate(draft)}
+              onClose={() => {
+                setEditOpen(false);
+                setEditing(null);
+              }}
+            />
+
+            <DiscoverDialog
+              open={discoverOpen}
+              onClose={() => setDiscoverOpen(false)}
+              onBound={() => {
+                setDiscoverOpen(false);
+                setMutError(null);
+                invalidate();
+              }}
+              onError={(message) => setMutError(message)}
+            />
+
+            <ConfirmDialog
+              open={deleteTarget !== null}
+              title={localize('com_services_delete_title')}
+              description={localize('com_services_delete_desc', { name: deleteTarget?.name ?? '' })}
+              confirmLabel={localize('com_ui_delete')}
+              saving={deleteMutation.isPending}
+              error={deleteMutation.isError ? (deleteMutation.error as Error).message : undefined}
+              onConfirm={() => deleteTarget && deleteMutation.mutate(deleteTarget.id)}
+              onCancel={() => setDeleteTarget(null)}
+            />
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/services/index.ts b/src/components/services/index.ts
new file mode 100644
index 00000000..52f20e06
--- /dev/null
+++ b/src/components/services/index.ts
@@ -0,0 +1 @@
+export { ServicesPage } from './ServicesPage';
diff --git a/src/components/shared/CheckIndicator.tsx b/src/components/shared/CheckIndicator.tsx
new file mode 100644
index 00000000..d7806ab9
--- /dev/null
+++ b/src/components/shared/CheckIndicator.tsx
@@ -0,0 +1,19 @@
+import { cn } from '@/utils';
+
+const check =
+  'flex size-4 shrink-0 items-center justify-center rounded border border-(--cui-color-stroke-default)';
+
+/** 装饰性勾选指示（整行可点击的场景）：非交互控件，勾选状态由外层行表达。 */
+export function CheckIndicator({ on }: { on: boolean }) {
+  return (
+    <span
+      className={cn(
+        check,
+        on && 'border-(--cui-color-accent-primary) bg-(--cui-color-accent-primary)',
+      )}
+      aria-hidden="true"
+    >
+      {on && <span className="size-2 rounded-sm bg-white" />}
+    </span>
+  );
+}
diff --git a/src/components/shared/DatePickerCell.tsx b/src/components/shared/DatePickerCell.tsx
new file mode 100644
index 00000000..940cc30d
--- /dev/null
+++ b/src/components/shared/DatePickerCell.tsx
@@ -0,0 +1,42 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * Wraps a click-ui DatePicker so only the trigger button is tab-focusable.
+ * click-ui renders both a PopoverTrigger button AND an inner readonly input,
+ * which produces two stops in the tab order. The input has no exposed `tabIndex`
+ * prop, so we reach for the DOM node and set it to -1. The class hooks the
+ * CSS rule that rounds the trigger's focus outline to match the wrapper border.
+ *
+ * `resetKey` is the caller's signal that the inner DatePicker has been keyed
+ * to remount (e.g. the Clear button bumping a nonce): the inner `<input>` is
+ * replaced and the previous patch is lost, so the effect must re-run and
+ * re-apply `tabIndex = -1` against the fresh DOM node.
+ *
+ * `inputId` stamps the click-ui-rendered `<input>` with an `id` so an external
+ * `<label htmlFor={...}>` (and the e2e WCAG check) can target it. click-ui
+ * has no `id` prop, so it is applied via the same DOM-ref effect.
+ */
+export function DatePickerCell({
+  children,
+  resetKey,
+  inputId,
+}: {
+  children: React.ReactNode;
+  resetKey?: unknown;
+  inputId?: string;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+    const input = node.querySelector('input');
+    if (!input) return;
+    input.tabIndex = -1;
+    if (inputId) input.id = inputId;
+  }, [resetKey, inputId]);
+  return (
+    <div ref={ref} className="audit-date-cell contents">
+      {children}
+    </div>
+  );
+}
diff --git a/src/components/shared/FormDialog.tsx b/src/components/shared/FormDialog.tsx
index 23d2a50d..d56764c2 100644
--- a/src/components/shared/FormDialog.tsx
+++ b/src/components/shared/FormDialog.tsx
@@ -35,6 +35,7 @@ export function FormDialog({
       }}
     >
       <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
         title={title}
         showClose
         onClose={onClose}
diff --git a/src/components/shared/InlineAction.tsx b/src/components/shared/InlineAction.tsx
new file mode 100644
index 00000000..cb155c71
--- /dev/null
+++ b/src/components/shared/InlineAction.tsx
@@ -0,0 +1,29 @@
+import { cn } from '@/utils';
+
+/** 行内小操作按钮（工具清单/工具分组/服务管理统一样式，2.19.0 平铺替代三点菜单）。 */
+export function InlineAction({
+  label,
+  danger,
+  onClick,
+  children,
+}: {
+  label: string;
+  danger?: boolean;
+  onClick: () => void;
+  children: React.ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      title={label}
+      aria-label={label}
+      onClick={onClick}
+      className={cn(
+        'rounded-md border border-(--cui-color-stroke-default) px-1.5 py-0.5 text-xs leading-5 text-(--cui-color-text-muted) transition-colors hover:bg-(--cui-color-background-hover)',
+        danger ? 'hover:text-(--cui-color-text-danger)' : 'hover:text-(--cui-color-text-default)',
+      )}
+    >
+      {children}
+    </button>
+  );
+}
diff --git a/src/components/shared/index.ts b/src/components/shared/index.ts
index b85774a8..87bb3705 100644
--- a/src/components/shared/index.ts
+++ b/src/components/shared/index.ts
@@ -1,6 +1,8 @@
 export { AccessDenied } from './AccessDenied';
 export { AddItemButton } from './AddItemButton';
 export { Avatar } from './Avatar';
+export { CheckIndicator } from './CheckIndicator';
+export { DatePickerCell } from './DatePickerCell';
 export { EditButton } from './EditButton';
 export { EmptyState } from './EmptyState';
 export { FormDialog } from './FormDialog';
@@ -17,3 +19,4 @@ export { StatusToggle } from './StatusToggle';
 export { StickyActionBar } from './StickyActionBar';
 export { TrashButton } from './TrashButton';
 export { UserSearchInline } from './UserSearchInline';
+export { InlineAction } from './InlineAction';
diff --git a/src/components/tools/GiteaImportDialog.tsx b/src/components/tools/GiteaImportDialog.tsx
new file mode 100644
index 00000000..acda6735
--- /dev/null
+++ b/src/components/tools/GiteaImportDialog.tsx
@@ -0,0 +1,520 @@
+import { useEffect, useMemo, useState } from 'react';
+import { useMutation, useQuery } from '@tanstack/react-query';
+import { Button, Dialog, Select } from '@clickhouse/click-ui';
+import type { GiteaCheckResult, JsonValue, TerraVoxTool } from '@/server';
+import { giteaCheckRepoFn, giteaReposQueryOptions } from '@/server';
+import type * as t from '@/types';
+import { cn, notifyError, notifySuccess } from '@/utils';
+import { useLocalize } from '@/hooks';
+
+type Step = 'select' | 'report';
+
+const CHECK_DOT: Record<string, string> = {
+  error: 'bg-(--cui-color-text-danger)',
+  warn: 'bg-(--cui-color-text-warning)',
+  ok: 'bg-(--cui-color-text-success)',
+};
+
+/** repo 工具描述（tool.json）取字符串字段的兜底助手 */
+const str = (value: JsonValue | undefined): string => (typeof value === 'string' ? value : '');
+
+/** release tag（惯带 v 前缀）→ semver */
+const tagToVersion = (tag: string): string => (tag.startsWith('v') ? tag.slice(1) : tag);
+
+/** owner.repo → 建议工具 ID：小写、非法字符转 - */
+const suggestToolId = (owner: string, repo: string): string =>
+  `${owner}.${repo}`.toLowerCase().replace(/[^a-z0-9_.-]/g, '-');
+
+/** 检查结果 → ToolEditDialog 预填（TerraVoxTool 形状；tool_id 创建模式仍可改）。
+ *  导入与「待确认更新」共用：更新确认时治理字段以已批准 manifest 为准。
+ *  kind=plugin（2.11.0）：execution 登记为插件包，补充 host_launcher 等字段。 */
+export function buildPrefill(
+  result: GiteaCheckResult,
+  kind: 'desktop' | 'plugin' = 'desktop',
+): TerraVoxTool {
+  const toolJson = (result.tool_json ?? {}) as Record<string, JsonValue>;
+  const version = str(toolJson.version) || tagToVersion(result.release?.tag ?? '');
+  const distribution: { [key: string]: JsonValue } = {
+    source: { type: 'gitea_release', owner: result.owner, repo: result.repo },
+  };
+  if (version) {
+    distribution.version = version;
+  }
+  if (/^[a-f0-9]{64}$/.test(str(toolJson.package_sha256))) {
+    distribution.package_sha256 = str(toolJson.package_sha256);
+  }
+  if (str(toolJson.launcher)) {
+    distribution.launcher = str(toolJson.launcher);
+  }
+  if (str(toolJson.runtime)) {
+    distribution.runtime = str(toolJson.runtime);
+  }
+  if (kind === 'plugin') {
+    if (str(toolJson.host_launcher)) {
+      distribution.host_launcher = str(toolJson.host_launcher);
+    }
+    if (Array.isArray(toolJson.host_root_hints)) {
+      const hints = (toolJson.host_root_hints as unknown[]).map(String).filter(Boolean);
+      if (hints.length > 0) {
+        distribution.host_root_hints = hints;
+      }
+    }
+    if (str(toolJson.install_script)) {
+      distribution.install_script = str(toolJson.install_script);
+    }
+    if (str(toolJson.uninstall_script)) {
+      distribution.uninstall_script = str(toolJson.uninstall_script);
+    }
+  }
+  const timeoutMinutes =
+    typeof toolJson.timeout_minutes === 'number' ? toolJson.timeout_minutes : undefined;
+  return {
+    tool_id: suggestToolId(result.owner, result.repo),
+    version: version || '1.0.0',
+    display_name: str(toolJson.display_name) || result.repo,
+    description: str(toolJson.description) || result.repo_description || '',
+    expose: ['ui'],
+    allowed_groups: ['*'],
+    dangerous: toolJson.dangerous === true,
+    enabled: true,
+    parameters: toolJson.parameters as { [key: string]: JsonValue } | undefined,
+    form: toolJson.form as { [key: string]: JsonValue } | undefined,
+    execution: { kind, distribution },
+    result: toolJson.result as { [key: string]: JsonValue } | undefined,
+    ...(timeoutMinutes && timeoutMinutes > 0 ? { timeout_seconds: timeoutMinutes * 60 } : {}),
+  };
+}
+
+/** web 型工具（2.11.0）：不走检查流程——地址必填，owner/repo 仅为可选预填。
+ *  display_name 回退链：repo 描述 → URL 主机名。 */
+export function buildWebPrefill(input: {
+  url: string;
+  owner?: string;
+  repo?: string;
+  repoDescription?: string;
+}): TerraVoxTool {
+  let host = '';
+  try {
+    host = new URL(input.url).hostname;
+  } catch {
+    host = input.url;
+  }
+  const toolId =
+    input.owner && input.repo
+      ? suggestToolId(input.owner, input.repo)
+      : `web.${host.replace(/[^a-z0-9_.-]/gi, '-').toLowerCase()}`;
+  return {
+    tool_id: toolId,
+    version: '1.0.0',
+    display_name: input.repo || host,
+    description: input.repoDescription || '',
+    expose: ['ui'],
+    allowed_groups: ['*'],
+    dangerous: false,
+    enabled: true,
+    execution: { kind: 'web', url: input.url },
+  };
+}
+
+/** 「待确认更新」确认合并（2026-09-28 修复）：
+ *  - 版本以待确认目标（release tag，即 resolver/Toolhost 取包的标识）为准 ——
+ *    tool.json@tag 落后时按 tag 落库，version_mismatch 已在检查告警中可见；
+ *  - 仓库**提供**的内容字段覆盖旧值；tool.json 缺省的项（parameters/form/
+ *    result/dangerous/描述/sha256/launcher/runtime 等）**保留已批准值**，
+ *    不被 undefined/空串/回退值清掉；
+ *  - 治理字段（tool_id/expose/allowed_groups/enabled）保持已批准值。 */
+export function buildUpdateMerge(
+  existing: TerraVoxTool,
+  result: GiteaCheckResult,
+  targetVersion: string,
+): TerraVoxTool {
+  const prefill = buildPrefill(result);
+  const toolJson = (result.tool_json ?? {}) as Record<string, JsonValue>;
+  const repoDistribution = ((prefill.execution ?? {}).distribution ?? {}) as Record<
+    string,
+    unknown
+  >;
+  const existingDistribution = ((existing.execution ?? {}).distribution ?? {}) as Record<
+    string,
+    unknown
+  >;
+  return {
+    ...existing,
+    version: targetVersion,
+    /* repo 名回退不算「仓库提供」——display_name/description 仅在 tool.json 或
+     * 仓库描述真实给出时覆盖，否则保留已批准值 */
+    display_name: str(toolJson.display_name) || existing.display_name,
+    description: str(toolJson.description) || result.repo_description || existing.description,
+    ...(toolJson.dangerous !== undefined ? { dangerous: toolJson.dangerous === true } : {}),
+    ...(prefill.parameters !== undefined ? { parameters: prefill.parameters } : {}),
+    ...(prefill.form !== undefined ? { form: prefill.form } : {}),
+    ...(prefill.result !== undefined ? { result: prefill.result } : {}),
+    ...(prefill.timeout_seconds !== undefined ? { timeout_seconds: prefill.timeout_seconds } : {}),
+    execution: {
+      ...(existing.execution ?? {}),
+      kind: 'desktop',
+      distribution: {
+        ...existingDistribution,
+        ...repoDistribution,
+        version: targetVersion,
+      },
+    },
+    tool_id: existing.tool_id,
+    expose: existing.expose,
+    allowed_groups: existing.allowed_groups,
+    enabled: existing.enabled,
+  };
+}
+
+export function GiteaImportDialog({
+  open,
+  onClose,
+  onManualCreate,
+  onContinue,
+}: t.GiteaImportDialogProps) {
+  const localize = useLocalize();
+  const [step, setStep] = useState<Step>('select');
+  const [urlInput, setUrlInput] = useState('');
+  const [appliedUrl, setAppliedUrl] = useState(''); // '' = 网关默认地址
+  const [owner, setOwner] = useState('');
+  const [repo, setRepo] = useState('');
+  const [checkResult, setCheckResult] = useState<GiteaCheckResult | null>(null);
+  const [importKind, setImportKind] = useState<'desktop' | 'plugin' | 'web'>('desktop');
+  const [webUrl, setWebUrl] = useState('');
+  const [webError, setWebError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (open) {
+      setStep('select');
+      setUrlInput('');
+      setAppliedUrl('');
+      setOwner('');
+      setRepo('');
+      setCheckResult(null);
+      setImportKind('desktop');
+      setWebUrl('');
+      setWebError(null);
+    }
+  }, [open]);
+
+  const reposQuery = useQuery({
+    ...giteaReposQueryOptions(appliedUrl),
+    enabled: open,
+  });
+  const owners = reposQuery.data?.owners ?? [];
+  const ownerRepos = useMemo(
+    () => owners.find((o) => o.login === owner)?.repos ?? [],
+    [owners, owner],
+  );
+
+  const applyUrl = () => {
+    const normalized = urlInput.trim().replace(/\/+$/, '');
+    if (normalized !== appliedUrl) {
+      setAppliedUrl(normalized);
+      setOwner('');
+      setRepo('');
+    }
+  };
+
+  const checkMutation = useMutation({
+    mutationFn: () => giteaCheckRepoFn({ data: { owner, repo, baseUrl: appliedUrl || undefined } }),
+    onSuccess: (result) => {
+      setCheckResult(result);
+      setStep('report');
+      if (result.checks.some((c) => c.level === 'error')) {
+        notifyError(localize('com_tools_gitea_check_failed'));
+      } else if (result.installable) {
+        notifySuccess(localize('com_tools_gitea_installable'));
+      }
+    },
+    onError: (error: Error) => notifyError(error.message),
+  });
+
+  const hasError = (checkResult?.checks ?? []).some((c) => c.level === 'error');
+  const labelClass = 'mb-1 block font-medium text-(--cui-color-text-default)';
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(isOpen) => {
+        if (!isOpen && !checkMutation.isPending) {
+          onClose();
+        }
+      }}
+    >
+      <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
+        title={localize('com_tools_gitea_import_title')}
+        showClose
+        onClose={onClose}
+        className="modal-frost max-w-2xl!"
+      >
+        {step === 'select' ? (
+          <div className="flex max-h-[55vh] flex-col gap-4 overflow-y-auto pe-1 text-sm">
+            <div
+              role="radiogroup"
+              aria-label={localize('com_tools_gitea_import_kind')}
+              className="flex gap-2"
+            >
+              {(
+                [
+                  ['desktop', 'com_tools_gitea_kind_desktop'],
+                  ['plugin', 'com_tools_gitea_kind_plugin'],
+                  ['web', 'com_tools_gitea_kind_web'],
+                ] as const
+              ).map(([value, labelKey]) => (
+                <button
+                  key={value}
+                  type="button"
+                  role="radio"
+                  aria-checked={importKind === value}
+                  className={cn(
+                    'rounded-full border px-3 py-1 text-xs transition-colors',
+                    importKind === value
+                      ? 'border-(--cui-color-stroke-intense) bg-(--cui-color-background-active) font-medium text-(--cui-color-text-default)'
+                      : 'border-(--cui-color-stroke-default) text-(--cui-color-text-muted) hover:bg-(--cui-color-background-hover)',
+                  )}
+                  onClick={() => setImportKind(value)}
+                >
+                  {localize(labelKey)}
+                </button>
+              ))}
+            </div>
+            {importKind === 'web' && (
+              <div>
+                <label className={labelClass} htmlFor="web-tool-url">
+                  {localize('com_tools_field_web_url')}
+                </label>
+                <input
+                  id="web-tool-url"
+                  className="config-input-mono config-input w-full font-mono text-xs"
+                  spellCheck={false}
+                  value={webUrl}
+                  onChange={(e) => {
+                    setWebUrl(e.target.value);
+                    setWebError(null);
+                  }}
+                  placeholder="https://gis.example.local/app"
+                />
+                <p className="mt-1 text-xs text-(--cui-color-text-muted)">
+                  {localize('com_tools_gitea_web_url_hint')}
+                </p>
+                {webError && (
+                  <p role="alert" className="text-(--cui-color-text-danger)">
+                    {webError}
+                  </p>
+                )}
+              </div>
+            )}
+            <div>
+              <label className={labelClass} htmlFor="gitea-url">
+                {localize('com_tools_gitea_url')}
+              </label>
+              <input
+                id="gitea-url"
+                className="config-input-mono config-input w-full font-mono text-xs"
+                spellCheck={false}
+                value={urlInput}
+                onChange={(e) => setUrlInput(e.target.value)}
+                onBlur={applyUrl}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter') {
+                    e.preventDefault();
+                    applyUrl();
+                  }
+                }}
+                placeholder={reposQuery.data?.base_url ?? 'https://gitea.gislife.local'}
+              />
+              <p className="mt-1 text-xs text-(--cui-color-text-muted)">
+                {localize(
+                  importKind === 'web'
+                    ? 'com_tools_gitea_url_hint_web'
+                    : 'com_tools_gitea_url_hint',
+                )}
+              </p>
+            </div>
+
+            {reposQuery.isLoading && (
+              <p className="text-(--cui-color-text-muted)">{localize('com_tools_gitea_loading')}</p>
+            )}
+            {reposQuery.isError && (
+              <p role="alert" className="text-(--cui-color-text-danger)">
+                {(reposQuery.error as Error).message}
+              </p>
+            )}
+
+            {owners.length > 0 && (
+              <div className="grid grid-cols-2 gap-4">
+                <div>
+                  <span className={labelClass}>{localize('com_tools_gitea_owner')}</span>
+                  <Select
+                    value={owner || undefined}
+                    onSelect={(v) => {
+                      setOwner(v);
+                      setRepo('');
+                    }}
+                    placeholder={localize('com_tools_gitea_select_owner')}
+                    showSearch
+                    aria-label={localize('com_tools_gitea_owner')}
+                  >
+                    {owners.map((o) => (
+                      <Select.Item key={o.login} value={o.login}>
+                        {o.login}
+                      </Select.Item>
+                    ))}
+                  </Select>
+                </div>
+                <div>
+                  <span className={labelClass}>{localize('com_tools_gitea_repo')}</span>
+                  <Select
+                    value={repo || undefined}
+                    onSelect={(v) => setRepo(v)}
+                    placeholder={localize('com_tools_gitea_select_repo')}
+                    showSearch
+                    disabled={!owner}
+                    aria-label={localize('com_tools_gitea_repo')}
+                  >
+                    {ownerRepos.map((r) => (
+                      <Select.Item key={r.name} value={r.name}>
+                        {r.description ? `${r.name} — ${r.description}` : r.name}
+                      </Select.Item>
+                    ))}
+                  </Select>
+                </div>
+              </div>
+            )}
+          </div>
+        ) : (
+          checkResult && (
+            <div className="flex max-h-[55vh] flex-col gap-3 overflow-y-auto pe-1 text-sm">
+              <p>
+                <code className="config-input-mono rounded border border-(--cui-color-stroke-default) px-1.5 py-0.5 text-xs">
+                  {checkResult.owner}/{checkResult.repo}
+                </code>
+                {checkResult.release?.tag && (
+                  <span className="ms-2 text-(--cui-color-text-muted)">
+                    {localize('com_tools_gitea_release')}:{' '}
+                    <code className="text-xs">{checkResult.release.tag}</code>
+                    {checkResult.release.zip_asset && (
+                      <code className="ms-2 text-xs">{checkResult.release.zip_asset}</code>
+                    )}
+                  </span>
+                )}
+              </p>
+              <span
+                className={cn(
+                  'w-fit rounded-full px-2 py-0.5 text-xs',
+                  checkResult.installable
+                    ? 'bg-(--cui-color-background-success-muted) text-(--cui-color-text-success)'
+                    : 'bg-(--cui-color-background-warning-muted) text-(--cui-color-text-warning)',
+                )}
+              >
+                {localize(
+                  checkResult.installable
+                    ? 'com_tools_gitea_installable'
+                    : 'com_tools_gitea_not_installable',
+                )}
+              </span>
+              <ul className="flex flex-col gap-1.5">
+                {checkResult.checks.map((c) => (
+                  <li key={c.key} className="flex items-start gap-2">
+                    <span
+                      aria-hidden="true"
+                      className={cn('mt-1.5 h-2 w-2 shrink-0 rounded-full', CHECK_DOT[c.level])}
+                    />
+                    <span className="break-all">
+                      <code className="me-1 text-xs text-(--cui-color-text-muted)">{c.key}</code>
+                      {c.message}
+                    </span>
+                  </li>
+                ))}
+              </ul>
+              {!hasError && (
+                <p className="text-xs text-(--cui-color-text-muted)">
+                  {localize('com_tools_gitea_prefill_hint')}
+                </p>
+              )}
+            </div>
+          )
+        )}
+
+        <div className="mt-4 flex items-center gap-2">
+          {step === 'select' ? (
+            <Button
+              type="secondary"
+              label={localize('com_tools_gitea_manual_create')}
+              onClick={onManualCreate}
+              disabled={checkMutation.isPending}
+            />
+          ) : (
+            <Button
+              type="secondary"
+              label={localize('com_tools_gitea_back')}
+              onClick={() => setStep('select')}
+              disabled={checkMutation.isPending}
+            />
+          )}
+          <div className="ms-auto flex items-center gap-2">
+            <Button
+              type="secondary"
+              label={localize('com_ui_cancel')}
+              onClick={onClose}
+              disabled={checkMutation.isPending}
+            />
+            {(() => {
+              if (step === 'select' && importKind === 'web') {
+                return (
+                  <Button
+                    type="primary"
+                    label={localize('com_tools_gitea_continue')}
+                    disabled={checkMutation.isPending}
+                    onClick={() => {
+                      const trimmed = webUrl.trim();
+                      if (!trimmed.startsWith('http')) {
+                        setWebError(localize('com_tools_err_web_url'));
+                        return;
+                      }
+                      const repoMeta = ownerRepos.find((r) => r.name === repo);
+                      onContinue(
+                        buildWebPrefill({
+                          url: trimmed,
+                          owner: owner || undefined,
+                          repo: repo || undefined,
+                          repoDescription: repoMeta?.description,
+                        }),
+                      );
+                    }}
+                  />
+                );
+              }
+              if (step === 'select') {
+                return (
+                  <Button
+                    type="primary"
+                    label={localize('com_tools_gitea_check')}
+                    disabled={!owner || !repo || checkMutation.isPending}
+                    onClick={() => checkMutation.mutate()}
+                  />
+                );
+              }
+              return (
+                <Button
+                  type="primary"
+                  label={localize('com_tools_gitea_continue')}
+                  disabled={hasError || checkMutation.isPending}
+                  onClick={() => {
+                    if (checkResult) {
+                      onContinue(
+                        buildPrefill(checkResult, importKind === 'plugin' ? 'plugin' : 'desktop'),
+                      );
+                    }
+                  }}
+                />
+              );
+            })()}
+          </div>
+        </div>
+      </Dialog.Content>
+    </Dialog>
+  );
+}
diff --git a/src/components/tools/ImportToolsDialog.tsx b/src/components/tools/ImportToolsDialog.tsx
new file mode 100644
index 00000000..dbc7e58e
--- /dev/null
+++ b/src/components/tools/ImportToolsDialog.tsx
@@ -0,0 +1,409 @@
+import { useRef, useState } from 'react';
+import { Button, Dialog, Switch, Tabs } from '@clickhouse/click-ui';
+import type { TerraVoxTool, ImportResult } from '@/server';
+import { importToolsFn } from '@/server';
+import { useLocalize } from '@/hooks';
+import { cn } from '@/utils';
+
+type Step = 'input' | 'review' | 'done';
+
+/** Live count of manifests in the paste box (0 until it parses). */
+const countParsed = (text: string): number => {
+  try {
+    const parsed = JSON.parse(text);
+    if (Array.isArray(parsed)) {
+      return parsed.length;
+    }
+    if (
+      parsed &&
+      typeof parsed === 'object' &&
+      Array.isArray((parsed as { tools?: unknown }).tools)
+    ) {
+      return (parsed as { tools: unknown[] }).tools.length;
+    }
+    return parsed && typeof parsed === 'object' ? 1 : 0;
+  } catch {
+    return 0;
+  }
+};
+
+const ACTION_STYLE: Record<string, string> = {
+  created:
+    'rounded-full bg-(--cui-color-background-success-muted) px-2 py-0.5 text-xs text-(--cui-color-text-success)',
+  updated:
+    'rounded-full bg-(--cui-color-accent-primary-muted) px-2 py-0.5 text-xs text-(--cui-color-text-default)',
+  skipped:
+    'rounded-full bg-(--cui-color-background-muted) px-2 py-0.5 text-xs text-(--cui-color-text-muted)',
+  failed:
+    'rounded-full bg-(--cui-color-background-danger-muted) px-2 py-0.5 text-xs text-(--cui-color-text-danger)',
+};
+
+/**
+ * Two-step import: parse manifests (upload .json files or paste JSON) →
+ * dry-run preview against the gateway → optional overwrite → apply.
+ * The gateway validates each manifest; per-item outcomes come back in
+ * `results` for both the preview and the real run.
+ */
+export function ImportToolsDialog({
+  open,
+  onClose,
+  onImported,
+}: {
+  open: boolean;
+  onClose: () => void;
+  onImported: () => void;
+}) {
+  const localize = useLocalize();
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const [step, setStep] = useState<Step>('input');
+  const [mode, setMode] = useState('upload');
+  const [files, setFiles] = useState<{ name: string; manifest: unknown }[]>([]);
+  const [pasted, setPasted] = useState('');
+  const [parseError, setParseError] = useState<string | null>(null);
+  const [overwrite, setOverwrite] = useState(false);
+  const [results, setResults] = useState<ImportResult[] | null>(null);
+  /** Manifests that passed local parsing and the dry run — the apply step
+   * re-sends exactly this list (possibly with a different overwrite flag). */
+  const [pendingTools, setPendingTools] = useState<Record<string, unknown>[] | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [requestError, setRequestError] = useState<string | null>(null);
+
+  const reset = () => {
+    setStep('input');
+    setMode('upload');
+    setFiles([]);
+    setPasted('');
+    setParseError(null);
+    setOverwrite(false);
+    setResults(null);
+    setPendingTools(null);
+    setBusy(false);
+    setRequestError(null);
+  };
+
+  const close = () => {
+    if (busy) {
+      return;
+    }
+    const wasDone = step === 'done';
+    reset();
+    onClose();
+    if (wasDone) {
+      onImported();
+    }
+  };
+
+  const readFiles = async (fileList: FileList | null) => {
+    if (!fileList || fileList.length === 0) {
+      return;
+    }
+    setParseError(null);
+    const loaded: { name: string; manifest: unknown }[] = [];
+    const errors: string[] = [];
+    for (const file of Array.from(fileList)) {
+      try {
+        const manifest = JSON.parse(await file.text());
+        loaded.push({ name: file.name, manifest });
+      } catch (error) {
+        errors.push(`${file.name}: ${(error as Error).message}`);
+      }
+    }
+    setFiles((prev) => [...prev, ...loaded]);
+    if (errors.length > 0) {
+      setParseError(errors.join('\n'));
+    }
+    if (fileInputRef.current) {
+      fileInputRef.current.value = '';
+    }
+  };
+
+  const collectTools = (): { tools: Record<string, unknown>[]; error?: string } => {
+    if (mode === 'upload') {
+      if (files.length === 0) {
+        return { tools: [], error: localize('com_tools_import_no_files') };
+      }
+      return { tools: files.map((f) => f.manifest as Record<string, unknown>) };
+    }
+    const text = pasted.trim();
+    if (!text) {
+      return { tools: [], error: localize('com_tools_import_no_paste') };
+    }
+    try {
+      const parsed = JSON.parse(text);
+      if (Array.isArray(parsed)) {
+        return { tools: parsed as Record<string, unknown>[] };
+      }
+      if (parsed && typeof parsed === 'object') {
+        /* A catalog export `{tools: [...]}` is accepted too. */
+        const inner = (parsed as { tools?: unknown }).tools;
+        if (Array.isArray(inner)) {
+          return { tools: inner as Record<string, unknown>[] };
+        }
+        return { tools: [parsed as Record<string, unknown>] };
+      }
+      return { tools: [], error: localize('com_tools_import_bad_json') };
+    } catch (error) {
+      return {
+        tools: [],
+        error: `${localize('com_tools_import_bad_json')}: ${(error as Error).message}`,
+      };
+    }
+  };
+
+  const preview = async () => {
+    const { tools, error } = collectTools();
+    if (error || tools.length === 0) {
+      setParseError(error ?? localize('com_tools_import_no_files'));
+      return;
+    }
+    setParseError(null);
+    setBusy(true);
+    setRequestError(null);
+    try {
+      const response = await importToolsFn({
+        data: { tools, overwrite, dryRun: true },
+      });
+      setPendingTools(tools);
+      setResults(response.results);
+      setStep('review');
+    } catch (error) {
+      setRequestError((error as Error).message);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const apply = async () => {
+    if (!pendingTools) {
+      return;
+    }
+    setBusy(true);
+    setRequestError(null);
+    try {
+      const response = await importToolsFn({
+        data: { tools: pendingTools, overwrite, dryRun: false },
+      });
+      setResults(response.results);
+      setStep('done');
+    } catch (error) {
+      setRequestError((error as Error).message);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const skippedCount = results?.filter((r) => r.action === 'skipped').length ?? 0;
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(isOpen) => {
+        if (!isOpen) {
+          close();
+        }
+      }}
+    >
+      <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
+        title={localize('com_tools_import_title')}
+        showClose
+        onClose={close}
+        className="modal-frost max-w-2xl!"
+      >
+        {step === 'input' && (
+          <div className="flex flex-col gap-4 text-sm">
+            <p className="text-(--cui-color-text-muted)">{localize('com_tools_import_hint')}</p>
+            <Tabs
+              value={mode}
+              onValueChange={setMode}
+              ariaLabel={localize('com_tools_import_title')}
+            >
+              <Tabs.TriggersList>
+                <Tabs.Trigger value="upload">{localize('com_tools_import_upload')}</Tabs.Trigger>
+                <Tabs.Trigger value="paste">{localize('com_tools_import_paste')}</Tabs.Trigger>
+              </Tabs.TriggersList>
+            </Tabs>
+            {mode === 'upload' ? (
+              <div className="flex flex-col gap-3">
+                <button
+                  type="button"
+                  onClick={() => fileInputRef.current?.click()}
+                  className="flex flex-col items-center justify-center gap-1 rounded-lg border border-dashed border-(--cui-color-stroke-default) px-4 py-6 text-(--cui-color-text-muted) transition-colors hover:bg-(--cui-color-background-hover)"
+                >
+                  {localize('com_tools_import_pick')}
+                  <span className="text-xs">{localize('com_tools_import_pick_hint')}</span>
+                </button>
+                <input
+                  ref={fileInputRef}
+                  type="file"
+                  accept=".json,application/json"
+                  multiple
+                  className="hidden"
+                  onChange={(e) => void readFiles(e.target.files)}
+                />
+                {files.length > 0 && (
+                  <ul className="flex flex-col gap-1">
+                    {files.map((f, i) => (
+                      <li
+                        key={`${f.name}-${i}`}
+                        className="flex items-center justify-between rounded border border-(--cui-color-stroke-default) px-2 py-1"
+                      >
+                        <span className="truncate font-mono text-xs">{f.name}</span>
+                        <span className="ms-2 shrink-0 text-xs text-(--cui-color-text-muted)">
+                          {(f.manifest as TerraVoxTool).tool_id ?? '—'}
+                        </span>
+                        <button
+                          type="button"
+                          className="ms-2 shrink-0 text-xs text-(--cui-color-text-muted) hover:text-(--cui-color-text-danger)"
+                          onClick={() => setFiles((prev) => prev.filter((_, j) => j !== i))}
+                        >
+                          ✕
+                        </button>
+                      </li>
+                    ))}
+                  </ul>
+                )}
+              </div>
+            ) : (
+              <textarea
+                className="config-input-mono config-input min-h-40 w-full resize-y font-mono text-xs"
+                spellCheck={false}
+                aria-label={localize('com_tools_import_paste')}
+                placeholder='{ "schema_version": 1, "tool_id": "demo.example", ... }'
+                value={pasted}
+                onChange={(e) => setPasted(e.target.value)}
+              />
+            )}
+            {parseError && (
+              <p
+                role="alert"
+                className="text-xs whitespace-pre-wrap text-(--cui-color-text-danger)"
+              >
+                {parseError}
+              </p>
+            )}
+            {requestError && (
+              <p role="alert" className="text-sm text-(--cui-color-text-danger)">
+                {requestError}
+              </p>
+            )}
+            <div className="flex items-center justify-between gap-2">
+              <span className="text-xs text-(--cui-color-text-muted)">
+                {localize('com_tools_import_count', {
+                  count: mode === 'upload' ? files.length : countParsed(pasted),
+                })}
+              </span>
+              <div className="flex gap-2">
+                <Button
+                  type="secondary"
+                  label={localize('com_ui_cancel')}
+                  onClick={close}
+                  disabled={busy}
+                />
+                <Button
+                  type="primary"
+                  label={localize('com_tools_import_preview')}
+                  onClick={() => void preview()}
+                  disabled={busy || (mode === 'upload' ? files.length === 0 : !pasted.trim())}
+                />
+              </div>
+            </div>
+          </div>
+        )}
+
+        {(step === 'review' || step === 'done') && results && (
+          <div className="flex flex-col gap-4 text-sm">
+            <p className="text-(--cui-color-text-muted)">
+              {step === 'review'
+                ? localize('com_tools_import_preview_desc')
+                : localize('com_tools_import_done')}
+            </p>
+            <div className="overflow-x-auto rounded-lg border border-(--cui-color-stroke-default)">
+              <table className="w-full text-left text-sm">
+                <thead>
+                  <tr className="border-b border-(--cui-color-stroke-default) bg-(--cui-color-background-muted)">
+                    <th scope="col" className="px-3 py-2 font-medium text-(--cui-color-text-muted)">
+                      {localize('com_tools_col_tool')}
+                    </th>
+                    <th scope="col" className="px-3 py-2 font-medium text-(--cui-color-text-muted)">
+                      {localize('com_tools_import_action')}
+                    </th>
+                    <th scope="col" className="px-3 py-2 font-medium text-(--cui-color-text-muted)">
+                      {localize('com_tools_import_detail')}
+                    </th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {results.map((r) => (
+                    <tr
+                      key={r.tool_id}
+                      className="border-b border-(--cui-color-stroke-default) last:border-b-0"
+                    >
+                      <td className="px-3 py-2 font-mono text-xs">{r.tool_id}</td>
+                      <td className="px-3 py-2">
+                        <span className={cn(ACTION_STYLE[r.action])}>
+                          {localize(`com_tools_import_${r.action}`)}
+                        </span>
+                      </td>
+                      <td className="px-3 py-2 text-xs text-(--cui-color-text-muted)">
+                        {r.error ?? '—'}
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+
+            {step === 'review' && skippedCount > 0 && (
+              <label className="flex items-center gap-2">
+                <Switch
+                  checked={overwrite}
+                  onCheckedChange={(v) => {
+                    setOverwrite(v);
+                  }}
+                  aria-label={localize('com_tools_import_overwrite')}
+                />
+                {localize('com_tools_import_overwrite')}
+              </label>
+            )}
+            {requestError && (
+              <p role="alert" className="text-sm text-(--cui-color-text-danger)">
+                {requestError}
+              </p>
+            )}
+            <div className="flex items-center justify-end gap-2">
+              {step === 'review' && (
+                <Button
+                  type="secondary"
+                  label={localize('com_ui_back')}
+                  onClick={() => setStep('input')}
+                  disabled={busy}
+                />
+              )}
+              <Button
+                type={step === 'review' ? 'primary' : 'secondary'}
+                label={
+                  step === 'review'
+                    ? localize(
+                        overwrite || skippedCount === 0
+                          ? 'com_tools_import_apply'
+                          : 'com_tools_import_apply_skip',
+                      )
+                    : localize('com_ui_close')
+                }
+                onClick={() => {
+                  if (step === 'review') {
+                    void apply();
+                  } else {
+                    close();
+                  }
+                }}
+                disabled={busy}
+              />
+            </div>
+          </div>
+        )}
+      </Dialog.Content>
+    </Dialog>
+  );
+}
diff --git a/src/components/tools/ParamBuilder.test.ts b/src/components/tools/ParamBuilder.test.ts
new file mode 100644
index 00000000..9aae4be4
--- /dev/null
+++ b/src/components/tools/ParamBuilder.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { parseManifest, serialize } from './ParamBuilder';
+
+/* ParamBuilder 双向序列化契约：parse ⇄ serialize 必须保真，且输出符合
+ * manifest v1（accept=带点扩展名数组、choices_from={tool,...} 对象）。 */
+
+const P = (properties: unknown) => JSON.stringify({ type: 'object', properties });
+const F = (fields: unknown) => JSON.stringify({ fields });
+
+describe('ParamBuilder serialize/parse round-trip', () => {
+  it('preserves contract-shaped choices_from object and accept array', () => {
+    const hint = {
+      widget: 'file',
+      label: '输入数据',
+      accept: ['.gdb', '.shp'],
+      choices_from: { tool: 'spatial.registry_layers', value_field: 'id', label_field: 'name' },
+    };
+    const { rows } = parseManifest(P({ src: { type: 'string' } }), F({ src: hint }));
+    expect(rows).toHaveLength(1);
+    expect(rows[0].choicesFrom).toBe('spatial.registry_layers');
+    expect(rows[0].choicesFromOpts).toEqual({ value_field: 'id', label_field: 'name' });
+    expect(rows[0].accept).toBe('.gdb, .shp');
+
+    const out = JSON.parse(serialize(rows).formJson);
+    expect(out.fields.src.choices_from).toEqual({
+      tool: 'spatial.registry_layers',
+      value_field: 'id',
+      label_field: 'name',
+    });
+    expect(out.fields.src.accept).toEqual(['.gdb', '.shp']);
+  });
+
+  it('rescues legacy string choices_from into a contract-valid object', () => {
+    const { rows } = parseManifest(
+      P({ src: { type: 'string' } }),
+      F({ src: { choices_from: 'spatial.registry_layers' } }),
+    );
+    const out = JSON.parse(serialize(rows).formJson);
+    expect(out.fields.src.choices_from).toEqual({ tool: 'spatial.registry_layers' });
+  });
+
+  it('normalizes accept text input to dot-extension array (both separators)', () => {
+    const { rows } = parseManifest(P({ f: { type: 'string' } }), F({ f: { widget: 'file' } }));
+    const patched = rows.map((r) => ({ ...r, accept: 'gdb, .shp，csv' }));
+    const out = JSON.parse(serialize(patched).formJson);
+    expect(out.fields.f.accept).toEqual(['.gdb', '.shp', '.csv']);
+  });
+
+  it('drops empty accept/choices_from instead of writing contract-invalid empties', () => {
+    const { rows } = parseManifest(P({ f: { type: 'string' } }), F({ f: {} }));
+    const out = JSON.parse(serialize(rows).formJson);
+    expect(out.fields.f).not.toHaveProperty('accept');
+    expect(out.fields.f).not.toHaveProperty('choices_from');
+  });
+
+  it('keeps upload-only form fields (no properties entry) through round-trip', () => {
+    const { rows } = parseManifest(
+      JSON.stringify({ type: 'object', properties: {}, required: ['att'] }),
+      JSON.stringify({ order: ['att'], fields: { att: { widget: 'upload' } } }),
+    );
+    expect(rows).toHaveLength(1);
+    expect(rows[0].required).toBe(true);
+    const out = serialize(rows);
+    expect(JSON.parse(out.parametersJson).properties).toEqual({});
+    expect(JSON.parse(out.formJson).fields.att.widget).toBe('upload');
+  });
+});
diff --git a/src/components/tools/ParamBuilder.tsx b/src/components/tools/ParamBuilder.tsx
new file mode 100644
index 00000000..97621593
--- /dev/null
+++ b/src/components/tools/ParamBuilder.tsx
@@ -0,0 +1,820 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { PointerEvent as ReactPointerEvent } from 'react';
+import { Button, Checkbox, Dropdown, RadioGroup, Select } from '@clickhouse/click-ui';
+import { useLocalize } from '@/hooks';
+import { cn } from '@/utils';
+
+/**
+ * 参数构建器（2.21.1）：工具参数（JSON Schema）与前端表单提示（form hints）
+ * 的可视化双向编辑器。数据流：
+ *
+ *   ParamRow[] ⇄ serialize() ⇄ parametersJson + formJson（字符串，双向）
+ *
+ * - 可视化编辑即时序列化回 JSON（保存通道零改动）
+ * - 外部 JSON 变化（打开对话框/JSON 模式手改）且与上次序列化输出不同时
+ *   反向 parse
+ * - round-trip 保真：properties/hints 的未知键原样保留（raw/rawHint）
+ * - JSON 语法错误时锁定可视化（错误条 + 保持 JSON 模式）
+ */
+
+type ParamType = 'string' | 'number' | 'integer' | 'boolean' | 'array';
+type ParamWidget =
+  | ''
+  | 'textarea'
+  | 'multiselect'
+  | 'date'
+  | 'datetime'
+  | 'file'
+  | 'directory'
+  | 'upload'
+  | 'hidden';
+
+interface ParamRow {
+  name: string;
+  type: ParamType;
+  required: boolean;
+  def: unknown;
+  label: string;
+  help: string;
+  placeholder: string;
+  widget: ParamWidget;
+  enumValues: string[];
+  choices: string[];
+  /** choices_from.tool（UI 文本框只暴露 tool 名）；可选字段随 parse 保全。 */
+  choicesFrom: string;
+  choicesFromOpts: { value_field?: string; label_field?: string };
+  /** 逗号分隔文本（UI）；序列化为契约要求的带点扩展名数组。 */
+  accept: string;
+  /** properties 上未被构建器覆盖的原始键（round-trip 保真）。 */
+  raw: Record<string, unknown>;
+  /** form.fields 上未被构建器覆盖的原始键。 */
+  rawHint: Record<string, unknown>;
+}
+
+interface Manifest {
+  parameters: {
+    type: 'object';
+    properties: Record<string, Record<string, unknown>>;
+    required?: string[];
+  };
+  form: {
+    order?: string[];
+    fields: Record<string, Record<string, unknown>>;
+  };
+}
+
+const NAME_RE = /^[\w.-]+$/;
+function inferWidget(hint: Record<string, unknown>): ParamWidget {
+  return typeof hint.widget === 'string' ? (hint.widget as ParamWidget) : '';
+}
+
+/** choices_from 解析：契约形态是 {tool,...} 对象（value_field/label_field 随行
+ * 保全）；旧版构建器曾产出纯字符串——一律救援为 tool 名，round-trip 后升格为
+ * 合法对象。opts 由调用方传入并被就地填充。 */
+function choicesFromOf(
+  hint: Record<string, unknown>,
+  opts: { value_field?: string; label_field?: string },
+): string {
+  const cf = hint.choices_from;
+  if (typeof cf === 'string') {
+    return cf;
+  }
+  if (cf && typeof cf === 'object') {
+    const rec = cf as Record<string, unknown>;
+    if (typeof rec.value_field === 'string') {
+      opts.value_field = rec.value_field;
+    }
+    if (typeof rec.label_field === 'string') {
+      opts.label_field = rec.label_field;
+    }
+    return typeof rec.tool === 'string' ? rec.tool : '';
+  }
+  return '';
+}
+
+export function parseManifest(pJson: string, fJson: string): { rows: ParamRow[]; error: string | null } {
+  try {
+    const p = JSON.parse(pJson || '{}') as Manifest['parameters'];
+    const f = (JSON.parse(fJson || '{}') || {}) as Partial<Manifest['form']>;
+    const props = p.properties ?? {};
+    const hints = f.fields ?? {};
+    const declared = Array.isArray(f.order) ? f.order : [];
+    const names = [...declared, ...Object.keys(props).filter((n) => !declared.includes(n))];
+    const required = new Set(p.required ?? []);
+    const rows: ParamRow[] = names
+      .filter((n) => props[n] || hints[n]?.widget === 'upload')
+      .map((name) => {
+        const prop = { ...((props[name] as Record<string, unknown> | undefined) ?? {}) };
+        const hint = { ...((hints[name] as Record<string, unknown> | undefined) ?? {}) };
+        const choicesFromOpts: { value_field?: string; label_field?: string } = {};
+        const type = (
+          typeof prop.type === 'string' && prop.type !== 'object' ? prop.type : 'string'
+        ) as ParamType;
+        return {
+          name,
+          type,
+          required: required.has(name),
+          def: prop.default,
+          label: typeof hint.label === 'string' ? hint.label : '',
+          help: typeof hint.help === 'string' ? hint.help : '',
+          placeholder: typeof hint.placeholder === 'string' ? hint.placeholder : '',
+          widget: inferWidget(hint),
+          enumValues: Array.isArray(prop.enum) ? (prop.enum as string[]).map(String) : [],
+          choices: Array.isArray(hint.choices) ? (hint.choices as string[]).map(String) : [],
+          choicesFrom: choicesFromOf(hint, choicesFromOpts),
+          accept: Array.isArray(hint.accept)
+            ? (hint.accept as unknown[]).map(String).join(', ')
+            : '',
+          choicesFromOpts,
+          raw: prop,
+          rawHint: hint,
+        };
+      });
+    return { rows, error: null };
+  } catch (e) {
+    return { rows: [], error: String((e as Error).message).slice(0, 160) };
+  }
+}
+
+export function serialize(rows: ParamRow[]): { parametersJson: string; formJson: string } {
+  const properties: Record<string, Record<string, unknown>> = {};
+  const fields: Record<string, Record<string, unknown>> = {};
+  const order: string[] = [];
+  const required: string[] = [];
+  for (const r of rows) {
+    order.push(r.name);
+    if (r.required) {
+      required.push(r.name);
+    }
+    if (r.widget !== 'upload') {
+      const prop: Record<string, unknown> = { ...r.raw, type: r.type };
+      if (r.enumValues.length > 0 && r.type === 'string') {
+        prop.enum = r.enumValues;
+      } else {
+        delete prop.enum;
+      }
+      if (r.def !== undefined && r.def !== '') {
+        prop.default = r.def;
+      } else {
+        delete prop.default;
+      }
+      properties[r.name] = prop;
+    }
+    const hint: Record<string, unknown> = { ...r.rawHint };
+    if (r.widget) {
+      hint.widget = r.widget;
+    } else {
+      delete hint.widget;
+    }
+    const setText = (key: string, value: string) => {
+      if (value) {
+        hint[key] = value;
+      } else {
+        delete hint[key];
+      }
+    };
+    setText('label', r.label);
+    setText('help', r.help);
+    setText('placeholder', r.placeholder);
+    /* accept：契约要求数组且每项带前导点（tool-manifest.schema.json ^\.[A-Za-z0-9_-]+$） */
+    const exts = r.accept
+      .split(/[,，]/)
+      .map((s) => s.trim())
+      .filter(Boolean)
+      .map((s) => (s.startsWith('.') ? s : `.${s}`));
+    if (exts.length > 0) {
+      hint.accept = exts;
+    } else {
+      delete hint.accept;
+    }
+    /* choices_from：契约要求对象（additionalProperties=false，缺省字段不写） */
+    const tool = r.choicesFrom.trim();
+    if (tool) {
+      hint.choices_from = { tool, ...r.choicesFromOpts };
+    } else {
+      delete hint.choices_from;
+    }
+    if (r.choices.length > 0) {
+      hint.choices = r.choices;
+    } else {
+      delete hint.choices;
+    }
+    fields[r.name] = hint;
+  }
+  const manifest: Manifest = {
+    parameters: { type: 'object', properties, ...(required.length ? { required } : {}) },
+    form: { fields, ...(order.length ? { order } : {}) },
+  };
+  return {
+    parametersJson: JSON.stringify(manifest.parameters, null, 2),
+    formJson: JSON.stringify(manifest.form, null, 2),
+  };
+}
+
+/** 默认值按类型强转（数字/整数转数值，空串为未设置）。 */
+function coerceDefault(raw: string, type: ParamType): unknown {
+  if (type === 'number' || type === 'integer') {
+    return raw === '' ? undefined : Number(raw);
+  }
+  return raw;
+}
+
+/** 卡片折叠态类型徽章文案（locale key）。 */
+const TYPE_LABEL: Record<ParamType, string> = {
+  string: 'com_param_type_string',
+  number: 'com_param_type_number',
+  integer: 'com_param_type_integer',
+  boolean: 'com_param_type_boolean',
+  array: 'com_param_type_array',
+};
+
+interface AddPreset {
+  key: string;
+  label: string;
+  make: () => Pick<ParamRow, 'type' | 'widget'> & Partial<ParamRow>;
+}
+
+export function ParamBuilder({
+  parametersJson,
+  formJson,
+  onChange,
+}: {
+  parametersJson: string;
+  formJson: string;
+  onChange: (parametersJson: string, formJson: string) => void;
+}) {
+  const localize = useLocalize();
+  const lastEmitted = useRef<{ p: string; f: string } | null>(null);
+  const [rows, setRows] = useState<ParamRow[]>([]);
+  const [mode, setMode] = useState<'visual' | 'json'>('visual');
+  const [jsonError, setJsonError] = useState<string | null>(null);
+  const [expanded, setExpanded] = useState<Set<number>>(new Set());
+
+  /* 外部 JSON → 行（仅在與上次输出不同时 parse：打开对话框 / JSON 模式手改） */
+  useEffect(() => {
+    const same =
+      lastEmitted.current &&
+      lastEmitted.current.p === parametersJson &&
+      lastEmitted.current.f === formJson;
+    if (same) {
+      return;
+    }
+    const { rows: parsed, error } = parseManifest(parametersJson, formJson);
+    if (!error) {
+      setRows(parsed);
+      setJsonError(null);
+    } else {
+      setJsonError(error);
+      setMode('json');
+    }
+  }, [parametersJson, formJson]);
+
+  const emit = (next: ParamRow[]) => {
+    setRows(next);
+    const out = serialize(next);
+    lastEmitted.current = { p: out.parametersJson, f: out.formJson };
+    onChange(out.parametersJson, out.formJson);
+  };
+
+  const patchRow = (index: number, patch: Partial<ParamRow>) => {
+    emit(rows.map((r, i) => (i === index ? { ...r, ...patch } : r)));
+  };
+
+  const uniqueName = (base: string) => {
+    let n = base;
+    let i = 2;
+    while (rows.some((r) => r.name === n)) {
+      n = `${base}${i}`;
+      i += 1;
+    }
+    return n;
+  };
+
+  const ADD_PRESETS: AddPreset[] = useMemo(
+    () => [
+      {
+        key: 'string',
+        label: localize('com_param_add_string'),
+        make: () => ({ type: 'string', widget: '' }),
+      },
+      {
+        key: 'number',
+        label: localize('com_param_add_number'),
+        make: () => ({ type: 'number', widget: '' }),
+      },
+      {
+        key: 'integer',
+        label: localize('com_param_add_integer'),
+        make: () => ({ type: 'integer', widget: '' }),
+      },
+      {
+        key: 'boolean',
+        label: localize('com_param_add_boolean'),
+        make: () => ({ type: 'boolean', widget: '' }),
+      },
+      {
+        key: 'array',
+        label: localize('com_param_add_array_multiselect'),
+        make: () => ({ type: 'array', widget: 'multiselect', choices: [] }),
+      },
+      {
+        key: 'textarea',
+        label: localize('com_param_add_textarea'),
+        make: () => ({ type: 'string', widget: 'textarea' }),
+      },
+      {
+        key: 'date',
+        label: localize('com_param_add_date'),
+        make: () => ({ type: 'string', widget: 'date' }),
+      },
+      {
+        key: 'datetime',
+        label: localize('com_param_add_datetime'),
+        make: () => ({ type: 'string', widget: 'datetime' }),
+      },
+      {
+        key: 'file',
+        label: localize('com_param_add_file'),
+        make: () => ({ type: 'string', widget: 'file' }),
+      },
+      {
+        key: 'directory',
+        label: localize('com_param_add_directory'),
+        make: () => ({ type: 'string', widget: 'directory' }),
+      },
+      {
+        key: 'upload',
+        label: localize('com_param_add_upload'),
+        make: () => ({ type: 'string', widget: 'upload', required: true }),
+      },
+      {
+        key: 'hidden',
+        label: localize('com_param_add_hidden'),
+        make: () => ({ type: 'string', widget: 'hidden' }),
+      },
+    ],
+    [],
+  );
+
+  const addParam = (preset: AddPreset) => {
+    const name = uniqueName('param');
+    const row: ParamRow = {
+      name,
+      def: undefined,
+      label: '',
+      help: '',
+      placeholder: '',
+      enumValues: [],
+      choicesFrom: '',
+      choicesFromOpts: {},
+      accept: '',
+      raw: {},
+      rawHint: {},
+      required: false,
+      ...preset.make(),
+    };
+    setExpanded((prev) => new Set(prev).add(rows.length));
+    emit([...rows, row]);
+  };
+
+  const removeRow = (index: number) => {
+    emit(rows.filter((_, i) => i !== index));
+  };
+
+  const renameRow = (index: number, name: string) => {
+    emit(rows.map((r, i) => (i === index ? { ...r, name } : r)));
+  };
+
+  const move = (from: number, to: number) => {
+    if (to < 0 || to >= rows.length || to === from) {
+      return;
+    }
+    const next = [...rows];
+    const [moved] = next.splice(from, 1);
+    next.splice(to, 0, moved);
+    emit(next);
+  };
+
+  /* 拖拽重排（Pointer 捕获，同图层树把手） */
+  const dragFrom = useRef<number | null>(null);
+  const onDragPointerDown = (e: React.PointerEvent<HTMLElement>, index: number) => {
+    if (e.button !== 0) {
+      return;
+    }
+    e.preventDefault();
+    (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+    dragFrom.current = index;
+  };
+  const onDragPointerMove = (e: React.PointerEvent<HTMLElement>) => {
+    if (dragFrom.current === null) {
+      return;
+    }
+    const target = document.elementFromPoint(e.clientX, e.clientY)?.closest('[data-param-index]');
+    if (target) {
+      const to = Number((target as HTMLElement).dataset.paramIndex);
+      if (!Number.isNaN(to) && to !== dragFrom.current) {
+        move(dragFrom.current, to);
+        dragFrom.current = to;
+      }
+    }
+  };
+  const onDragPointerUp = () => {
+    dragFrom.current = null;
+  };
+
+  return (
+    <div className="flex flex-col gap-3">
+      {/* 工具条：模式切换 + 添加参数 */}
+      <div className="flex items-center justify-between gap-2">
+        <div className="flex rounded-md border border-(--cui-color-stroke-default) p-0.5 text-xs">
+          {(['visual', 'json'] as const).map((m) => (
+            <button
+              key={m}
+              type="button"
+              className={cn(
+                'rounded px-2.5 py-1 transition-colors',
+                mode === m
+                  ? 'bg-(--cui-color-background-hover) font-medium text-(--cui-color-text-default)'
+                  : 'text-(--cui-color-text-muted) hover:text-(--cui-color-text-default)',
+              )}
+              onClick={() => setMode(m)}
+            >
+              {m === 'visual' ? localize('com_param_mode_visual') : localize('com_param_mode_json')}
+            </button>
+          ))}
+        </div>
+        <div>
+          <Dropdown>
+            <Dropdown.Trigger asChild>
+              <Button
+                variant="secondary"
+                size="sm"
+                label={localize('com_param_add')}
+                disabled={mode !== 'visual' || jsonError !== null}
+              />
+            </Dropdown.Trigger>
+            <Dropdown.Content className="param-add-menu">
+              {ADD_PRESETS.map((preset) => (
+                <Dropdown.Item key={preset.key} onSelect={() => addParam(preset)}>
+                  {preset.label}
+                </Dropdown.Item>
+              ))}
+            </Dropdown.Content>
+          </Dropdown>
+        </div>
+      </div>
+
+      {jsonError && (
+        <p className="rounded-md border border-(--cui-color-text-danger) px-2 py-1 text-xs text-(--cui-color-text-danger)">
+          {localize('com_param_json_error')}: {jsonError}
+        </p>
+      )}
+
+      {mode === 'json' ? (
+        <div className="flex flex-col gap-2">
+          <textarea
+            id="tool-parameters"
+            className="config-input-mono config-input min-h-40 w-full resize-y font-mono text-xs"
+            spellCheck={false}
+            value={parametersJson}
+            onChange={(e) => {
+              setMode('json');
+              lastEmitted.current = null;
+              onChange(e.target.value, formJson);
+            }}
+          />
+          <textarea
+            id="tool-form"
+            className="config-input-mono config-input min-h-32 w-full resize-y font-mono text-xs"
+            spellCheck={false}
+            value={formJson}
+            onChange={(e) => {
+              lastEmitted.current = null;
+              onChange(parametersJson, e.target.value);
+            }}
+          />
+        </div>
+      ) : (
+        <div className="flex flex-col gap-2">
+          {rows.map((row, index) => {
+            const open = expanded.has(index);
+            const nameBad =
+              !NAME_RE.test(row.name) || rows.some((r, i) => i !== index && r.name === row.name);
+            return (
+              <div
+                key={`${row.name}:${index}`}
+                data-param-index={index}
+                className={cn(
+                  'rounded-lg border border-(--cui-color-stroke-default) bg-(--cui-color-background-primary) text-sm',
+                  nameBad && 'border-(--cui-color-text-danger)',
+                )}
+              >
+                {/* 折叠态行头 */}
+                <div className="flex items-center gap-1.5 px-2 py-1.5">
+                  <span
+                    className="cursor-grab touch-none px-0.5 text-(--cui-color-text-muted) select-none active:cursor-grabbing"
+                    onPointerDown={(e) =>
+                      onDragPointerDown(e as ReactPointerEvent<HTMLElement>, index)
+                    }
+                    onPointerMove={onDragPointerMove}
+                    onPointerUp={onDragPointerUp}
+                    aria-hidden="true"
+                  >
+                    ⠿
+                  </span>
+                  <button
+                    type="button"
+                    className="min-w-0 flex-1 truncate text-start font-medium"
+                    onClick={() =>
+                      setExpanded((prev) => {
+                        const next = new Set(prev);
+                        if (next.has(index)) {
+                          next.delete(index);
+                        } else {
+                          next.add(index);
+                        }
+                        return next;
+                      })
+                    }
+                  >
+                    {open ? '▾' : '▸'} {row.name}
+                    <span className="ms-2 text-xs font-normal text-(--cui-color-text-muted)">
+                      {localize(TYPE_LABEL[row.type])}
+                      {row.widget ? ` · ${row.widget}` : ''}
+                    </span>
+                  </button>
+                  <Checkbox
+                    className="shrink-0"
+                    checked={row.required}
+                    onCheckedChange={(v) => patchRow(index, { required: v === true })}
+                    label={localize('com_param_required')}
+                  />
+                  <button
+                    type="button"
+                    className="rounded p-0.5 text-(--cui-color-text-muted) transition-colors hover:text-(--cui-color-text-danger)"
+                    aria-label={localize('com_ui_delete')}
+                    onClick={() => removeRow(index)}
+                  >
+                    ✕
+                  </button>
+                </div>
+                {/* 展开态字段 */}
+                {open && (
+                  <div className="flex flex-col gap-2 border-t border-(--cui-color-stroke-default) px-3 py-2 text-xs">
+                    <div className="grid grid-cols-2 gap-2">
+                      <label className="flex flex-col gap-1">
+                        <span className="text-(--cui-color-text-muted)">
+                          {localize('com_param_field_name')}
+                        </span>
+                        <input
+                          className={cn(
+                            'config-input h-7 px-2',
+                            nameBad && 'border-(--cui-color-text-danger)',
+                          )}
+                          value={row.name}
+                          onChange={(e) => renameRow(index, e.target.value)}
+                        />
+                      </label>
+                      <label className="flex flex-col gap-1">
+                        <span className="text-(--cui-color-text-muted)">
+                          {localize('com_param_type')}
+                        </span>
+                        <Select
+                          value={row.type}
+                          onSelect={(v) => patchRow(index, { type: v as ParamType })}
+                          disabled={row.widget === 'upload'}
+                        >
+                          {(Object.keys(TYPE_LABEL) as ParamType[]).map((t) => (
+                            <Select.Item key={t} value={t}>
+                              {localize(TYPE_LABEL[t])}
+                            </Select.Item>
+                          ))}
+                        </Select>
+                      </label>
+                      <label className="flex flex-col gap-1">
+                        <span className="text-(--cui-color-text-muted)">
+                          {localize('com_param_field_label')}
+                        </span>
+                        <input
+                          className="config-input h-7 px-2"
+                          value={row.label}
+                          onChange={(e) => patchRow(index, { label: e.target.value })}
+                        />
+                      </label>
+                      <label className="flex flex-col gap-1">
+                        <span className="text-(--cui-color-text-muted)">
+                          {localize('com_param_field_placeholder')}
+                        </span>
+                        <input
+                          className="config-input h-7 px-2"
+                          value={row.placeholder}
+                          onChange={(e) => patchRow(index, { placeholder: e.target.value })}
+                        />
+                      </label>
+                      <label className="flex flex-col gap-1">
+                        <span className="text-(--cui-color-text-muted)">
+                          {localize('com_param_field_help')}
+                        </span>
+                        <input
+                          className="config-input h-7 px-2"
+                          value={row.help}
+                          onChange={(e) => patchRow(index, { help: e.target.value })}
+                        />
+                      </label>
+                      {row.type !== 'boolean' && row.type !== 'array' && (
+                        <label className="flex flex-col gap-1">
+                          <span className="text-(--cui-color-text-muted)">
+                            {localize('com_param_field_default')}
+                          </span>
+                          <input
+                            className="config-input h-7 px-2"
+                            value={String(row.def ?? '')}
+                            onChange={(e) =>
+                              patchRow(index, {
+                                def: coerceDefault(e.target.value, row.type),
+                              })
+                            }
+                          />
+                        </label>
+                      )}
+                    </div>
+                    {/* 控件类型（字符串类） */}
+                    {row.type === 'string' && (
+                      <label className="flex flex-col gap-1">
+                        <span className="text-(--cui-color-text-muted)">
+                          {localize('com_param_field_widget')}
+                        </span>
+                        <Select
+                          value={row.widget || ''}
+                          onSelect={(v) => patchRow(index, { widget: (v || '') as ParamWidget })}
+                        >
+                          <Select.Item value="">{localize('com_param_widget_auto')}</Select.Item>
+                          <Select.Item value="textarea">
+                            {localize('com_param_widget_textarea')}
+                          </Select.Item>
+                          <Select.Item value="date">
+                            {localize('com_param_widget_date')}
+                          </Select.Item>
+                          <Select.Item value="datetime">
+                            {localize('com_param_widget_datetime')}
+                          </Select.Item>
+                          <Select.Item value="file">
+                            {localize('com_param_widget_file')}
+                          </Select.Item>
+                          <Select.Item value="directory">
+                            {localize('com_param_widget_directory')}
+                          </Select.Item>
+                          <Select.Item value="upload">
+                            {localize('com_param_widget_upload')}
+                          </Select.Item>
+                          <Select.Item value="hidden">
+                            {localize('com_param_widget_hidden')}
+                          </Select.Item>
+                        </Select>
+                      </label>
+                    )}
+                    {row.widget === 'file' && (
+                      <label className="flex flex-col gap-1">
+                        <span className="text-(--cui-color-text-muted)">
+                          {localize('com_param_field_accept')}
+                        </span>
+                        <input
+                          className="config-input h-7 px-2"
+                          placeholder=".csv,.xlsx"
+                          value={row.accept}
+                          onChange={(e) => patchRow(index, { accept: e.target.value })}
+                        />
+                      </label>
+                    )}
+                    {/* 枚举（字符串 + 选项列表） */}
+                    {row.type === 'string' && row.enumValues.length > 0 && (
+                      <div className="flex flex-col gap-1">
+                        <span className="text-(--cui-color-text-muted)">
+                          {localize('com_param_enum')}
+                        </span>
+                        <div className="flex flex-wrap items-center gap-1">
+                          {row.enumValues.map((v, ei) => (
+                            <span
+                              key={`${v}:${ei}`}
+                              className="flex items-center gap-1 rounded border border-(--cui-color-stroke-default) px-1.5 py-0.5"
+                            >
+                              {v}
+                              <button
+                                type="button"
+                                className="text-(--cui-color-text-muted) hover:text-(--cui-color-text-danger)"
+                                onClick={() =>
+                                  patchRow(index, {
+                                    enumValues: row.enumValues.filter((_, x) => x !== ei),
+                                  })
+                                }
+                              >
+                                ✕
+                              </button>
+                            </span>
+                          ))}
+                        </div>
+                      </div>
+                    )}
+                    {/* 数组：静态选项或动态来源 */}
+                    {row.type === 'array' && (
+                      <div className="flex flex-col gap-1">
+                        <span className="text-(--cui-color-text-muted)">
+                          {localize('com_param_choices')}
+                        </span>
+                        <RadioGroup
+                          inline
+                          value={row.choicesFrom ? 'from' : 'static'}
+                          onValueChange={(v) =>
+                            patchRow(index, {
+                              choicesFrom: v === 'from' ? row.choicesFrom : '',
+                            })
+                          }
+                        >
+                          <RadioGroup.Item
+                            value="static"
+                            label={localize('com_param_choices_static')}
+                          />
+                          <RadioGroup.Item
+                            value="from"
+                            label={localize('com_param_choices_from')}
+                          />
+                        </RadioGroup>
+                        {!row.choicesFrom && (
+                          <div className="flex flex-col gap-1">
+                            <div className="flex flex-wrap items-center gap-1">
+                              {row.choices.map((c, ci) => (
+                                <span
+                                  key={`${c}:${ci}`}
+                                  className="flex items-center gap-1 rounded border border-(--cui-color-stroke-default) px-1.5 py-0.5"
+                                >
+                                  {c}
+                                  <button
+                                    type="button"
+                                    className="text-(--cui-color-text-muted) hover:text-(--cui-color-text-danger)"
+                                    onClick={() =>
+                                      patchRow(index, {
+                                        choices: row.choices.filter((_, x) => x !== ci),
+                                      })
+                                    }
+                                  >
+                                    ✕
+                                  </button>
+                                </span>
+                              ))}
+                              <button
+                                type="button"
+                                className="rounded border border-(--cui-color-stroke-default) px-1.5 py-0.5 hover:bg-(--cui-color-background-hover)"
+                                onClick={() => patchRow(index, { choices: [...row.choices, ''] })}
+                              >
+                                {localize('com_param_enum_add')}
+                              </button>
+                            </div>
+                            <div className="flex flex-col gap-1">
+                              {row.choices.map((c, ci) => (
+                                <input
+                                  key={`edit:${ci}`}
+                                  className="config-input h-7 px-2"
+                                  value={c}
+                                  placeholder={`${localize('com_param_choices')} ${ci + 1}`}
+                                  onChange={(e) =>
+                                    patchRow(index, {
+                                      choices: row.choices.map((x, xi) =>
+                                        xi === ci ? e.target.value : x,
+                                      ),
+                                    })
+                                  }
+                                />
+                              ))}
+                            </div>
+                          </div>
+                        )}
+                        {row.choicesFrom !== '' && (
+                          <input
+                            className="config-input h-7 px-2"
+                            value={row.choicesFrom}
+                            placeholder={localize('com_param_choices_from_hint')}
+                            onChange={(e) => patchRow(index, { choicesFrom: e.target.value })}
+                          />
+                        )}
+                      </div>
+                    )}
+                    {nameBad && (
+                      <p className="text-(--cui-color-text-danger)">
+                        {localize('com_param_name_invalid')}
+                      </p>
+                    )}
+                  </div>
+                )}
+              </div>
+            );
+          })}
+          {rows.length === 0 && (
+            <p className="rounded-lg border border-dashed border-(--cui-color-stroke-default) p-4 text-center text-xs text-(--cui-color-text-muted)">
+              {localize('com_param_empty')}
+            </p>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/components/tools/ToolCatalogTab.tsx b/src/components/tools/ToolCatalogTab.tsx
new file mode 100644
index 00000000..74e3b35e
--- /dev/null
+++ b/src/components/tools/ToolCatalogTab.tsx
@@ -0,0 +1,835 @@
+import { useMemo, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Button, Checkbox, Icon, Select } from '@clickhouse/click-ui';
+import {
+  DndContext,
+  KeyboardSensor,
+  PointerSensor,
+  closestCenter,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+} from '@dnd-kit/core';
+import { restrictToVerticalAxis } from '@dnd-kit/modifiers';
+import {
+  SortableContext,
+  arrayMove,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable';
+import { CSS } from '@dnd-kit/utilities';
+import type { PendingToolUpdate, TerraVoxTool } from '@/server';
+import {
+  createToolFn,
+  deleteToolFn,
+  giteaCheckRepoFn,
+  handlersQueryOptions,
+  pendingUpdatesQueryOptions,
+  toolGroupsQueryOptions,
+  toolsQueryOptions,
+  updateToolFn,
+  toggleToolFn,
+} from '@/server';
+import {
+  EmptyState,
+  InlineAction,
+  LoadingState,
+  SearchInput,
+  StatusToggle,
+} from '@/components/shared';
+import { ConfirmDialog } from '@/components/access';
+import { useLocalize } from '@/hooks';
+import { notifySuccess } from '@/utils';
+import { ToolEditDialog } from './ToolEditDialog';
+import { buildUpdateMerge, GiteaImportDialog } from './GiteaImportDialog';
+import { ImportToolsDialog } from './ImportToolsDialog';
+
+const DANGER_STYLE =
+  'rounded-full bg-(--cui-color-background-warning-muted) px-2 py-0.5 text-xs text-(--cui-color-text-warning)';
+
+/** 行内分组单元格：配置页同款标准下拉（click-ui Select，与编辑对话框的
+ *  展示分组控件同款）；未分组以「未分组」项表示，选中即提交。 */
+function GroupCell({
+  value,
+  groups,
+  disabled,
+  label,
+  placeholder,
+  onCommit,
+}: {
+  value: string;
+  groups: string[];
+  disabled: boolean;
+  label: string;
+  placeholder: string;
+  onCommit: (group: string) => void;
+}) {
+  const localize = useLocalize();
+  return (
+    <div className="w-40">
+      <Select
+        value={value || '__none__'}
+        onSelect={(v) => onCommit(v === '__none__' ? '' : v)}
+        disabled={disabled}
+        aria-label={label}
+        placeholder={placeholder}
+      >
+        {[{ value: '__none__', label: localize('com_tools_display_group_none') }]
+          .concat(groups.map((g) => ({ value: g, label: g })))
+          .map((o) => (
+            <Select.Item key={o.value || '__none__'} value={o.value}>
+              {o.label}
+            </Select.Item>
+          ))}
+      </Select>
+    </div>
+  );
+}
+
+export function ToolCatalogTab() {
+  const localize = useLocalize();
+  const queryClient = useQueryClient();
+  const [search, setSearch] = useState('');
+  const [editOpen, setEditOpen] = useState(false);
+  const [editing, setEditing] = useState<TerraVoxTool | null>(null);
+  /** Gitea 导入解析出的预填数据（创建模式打开编辑对话框）。 */
+  const [prefill, setPrefill] = useState<TerraVoxTool | null>(null);
+  const [giteaOpen, setGiteaOpen] = useState(false);
+  const [deleteTarget, setDeleteTarget] = useState<TerraVoxTool | null>(null);
+  const [importOpen, setImportOpen] = useState(false);
+  const [mutError, setMutError] = useState<string | null>(null);
+  /** 待确认更新的检查告警（琥珀色，不影响继续确认）。 */
+  const [updateNotice, setUpdateNotice] = useState<string | null>(null);
+
+  const toolsQuery = useQuery(toolsQueryOptions);
+  const groupsQuery = useQuery(toolGroupsQueryOptions);
+  const handlersQuery = useQuery(handlersQueryOptions);
+  const pendingQuery = useQuery(pendingUpdatesQueryOptions);
+  const tools = toolsQuery.data?.tools ?? [];
+  const groups = groupsQuery.data ?? [];
+
+  const invalidate = () => {
+    void queryClient.invalidateQueries({ queryKey: ['terravox'] });
+  };
+
+  const saveMutation = useMutation({
+    mutationFn: async (manifest: Record<string, unknown>) =>
+      editing
+        ? updateToolFn({ data: { toolId: editing.tool_id, manifest } })
+        : createToolFn({ data: { manifest } }),
+    onSuccess: () => {
+      setEditOpen(false);
+      setEditing(null);
+      setPrefill(null);
+      setMutError(null);
+      invalidate();
+    },
+    onError: () => {
+      /* Stay open so the admin can fix the manifest — the dialog shows it. */
+    },
+  });
+
+  const toggleMutation = useMutation({
+    mutationFn: (vars: { toolId: string; enabled: boolean }) => toggleToolFn({ data: vars }),
+    onSuccess: () => {
+      setMutError(null);
+      invalidate();
+    },
+    onError: (error: Error) => setMutError(error.message),
+  });
+
+  /** 行内快速改暴露面（2.20.0）：manifest 原样回写，仅设置 expose。 */
+  const exposeMutation = useMutation({
+    mutationFn: async (vars: { tool: TerraVoxTool; expose: string[] }) => {
+      const manifest: Record<string, unknown> = { ...vars.tool };
+      manifest.expose = vars.expose;
+      await updateToolFn({ data: { toolId: vars.tool.tool_id, manifest } });
+    },
+    onSuccess: () => {
+      setMutError(null);
+      invalidate();
+    },
+    onError: (error: Error) => setMutError(error.message),
+  });
+
+  /** 行内快速改展示分组：manifest 原样回写，仅增删 display_group（2.16.0）。 */
+  const moveGroupMutation = useMutation({
+    mutationFn: async (vars: { tool: TerraVoxTool; group: string }) => {
+      const manifest: Record<string, unknown> = { ...vars.tool };
+      if (vars.group) {
+        manifest.display_group = vars.group;
+      } else {
+        delete manifest.display_group;
+      }
+      await updateToolFn({ data: { toolId: vars.tool.tool_id, manifest } });
+    },
+    onSuccess: () => {
+      setMutError(null);
+      invalidate();
+    },
+    onError: (error: Error) => setMutError(error.message),
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: (toolId: string) => deleteToolFn({ data: { toolId } }),
+    onSuccess: () => {
+      setDeleteTarget(null);
+      setMutError(null);
+      invalidate();
+    },
+    onError: (error: Error) => setMutError(error.message),
+  });
+
+  /** 待确认更新 → check 端点预填新参数 → 以编辑模式打开对话框（提交 = PUT 确认）。
+   *  检查告警（如 tool.json@tag 版本落后 version_mismatch）以通知形式展示；
+   *  硬项 error（仓库不可达/无 Release/多 zip）不打开对话框。 */
+  const confirmUpdateMutation = useMutation({
+    mutationFn: (update: PendingToolUpdate) =>
+      giteaCheckRepoFn({
+        data: { owner: update.owner ?? '', repo: update.repo ?? '' },
+      }),
+    onMutate: () => setUpdateNotice(null),
+    onSuccess: (result, update) => {
+      const existing = tools.find((tool) => tool.tool_id === update.tool_id);
+      if (!existing) {
+        /* 目录已漂移（工具被删）——刷新后该待确认行自然消失 */
+        invalidate();
+        return;
+      }
+      if (result.checks.some((c) => c.level === 'error')) {
+        setUpdateNotice(
+          localize('com_tools_pending_check_failed', {
+            detail: result.checks
+              .filter((c) => c.level === 'error')
+              .map((c) => `${c.key}: ${c.message}`)
+              .join(' · '),
+          }),
+        );
+        return;
+      }
+      const warns = result.checks.filter((c) => c.level === 'warn');
+      if (warns.length > 0) {
+        setUpdateNotice(
+          localize('com_tools_pending_check_warns', {
+            detail: warns.map((c) => `${c.key}: ${c.message}`).join(' · '),
+          }),
+        );
+      }
+      /* 版本以待确认目标（release tag）为准；仓库缺省字段保留已批准值 */
+      setEditing(buildUpdateMerge(existing, result, update.package.version));
+      setPrefill(null);
+      setEditOpen(true);
+    },
+    onError: (error: Error) => setMutError(error.message),
+  });
+
+  /* 分组内显示顺序（2.22.0）：display_order 升序，未设置者沉到已设置者之后
+   * （再按 tool_id 稳定排序）；拖拽产生的本地覆盖优先于已落库值。 */
+  const [orderOverride, setOrderOverride] = useState<Record<string, number>>({});
+  const [savingOrder, setSavingOrder] = useState(false);
+  const toolById = useMemo(() => new Map(tools.map((t) => [t.tool_id, t])), [tools]);
+
+  const effOrder = (tool: TerraVoxTool) =>
+    orderOverride[tool.tool_id] ??
+    (typeof tool.display_order === 'number' ? tool.display_order : Number.MAX_SAFE_INTEGER);
+
+  const filtered = useMemo(() => {
+    const q = search.trim().toLowerCase();
+    const sorted = [...tools].sort(
+      (a, b) => effOrder(a) - effOrder(b) || a.tool_id.localeCompare(b.tool_id),
+    );
+    if (!q) {
+      return sorted;
+    }
+    return sorted.filter((tool) =>
+      [tool.tool_id, tool.display_name, tool.description].some((s) => s?.toLowerCase().includes(q)),
+    );
+  }, [tools, search]);
+
+  /** 分组选项（2.17.0）：注册分组清单（网关已排序：显式按 sort_order，隐式沉底）。
+   *  未注册的 display_group 值由网关以隐式分组形态出现在同一清单里。 */
+  const displayGroups = useMemo(
+    () => (groupsQuery.data ?? []).map((g) => g.name),
+    [groupsQuery.data],
+  );
+
+  /** 按展示分组分节（管理端分组维度统一为 display_group，2.16.0）；
+   *  未分组的沉底成节，节内按 tool_id 稳定排序。 */
+  const grouped = useMemo(() => {
+    const byGroup = new Map<string, TerraVoxTool[]>();
+    for (const tool of filtered) {
+      const group = tool.display_group?.trim() ?? '';
+      const list = byGroup.get(group) ?? [];
+      list.push(tool);
+      byGroup.set(group, list);
+    }
+    for (const list of byGroup.values()) {
+      list.sort((a, b) => effOrder(a) - effOrder(b) || a.tool_id.localeCompare(b.tool_id));
+    }
+    return [...byGroup.entries()].sort(([a], [b]) => {
+      if (a === '') return 1;
+      if (b === '') return -1;
+      return a.localeCompare(b);
+    });
+  }, [filtered, orderOverride]);
+
+  /** 「手动创建」/ 清空预填：以空白创建模式打开编辑对话框 */
+  const openCreate = () => {
+    setEditing(null);
+    setPrefill(null);
+    setEditOpen(true);
+  };
+
+  const copyId = async (tool: TerraVoxTool) => {
+    try {
+      await navigator.clipboard.writeText(tool.tool_id);
+    } catch {
+      /* clipboard may be denied — non-critical convenience action */
+    }
+  };
+
+  /* ── 组内/跨组工具拖拽（2.22.0，dnd-kit）：松手后按目标节顺序重建
+   * display_order（×10）；跨节拖动同时改写 display_group（拖入「未分组」
+   * 即清空）。乐观覆盖即时反映新序，落库成功后清空。 ── */
+  const toolSensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  );
+  /* 表格单列：拖动锁定竖直轴，横向位移不触发重排 */
+  const toolModifiers = [restrictToVerticalAxis];
+
+  const onToolDragEnd = ({ active, over }: DragEndEvent) => {
+    if (!over || active.id === over.id) {
+      return;
+    }
+    const activeId = String(active.id);
+    const overId = String(over.id);
+    const sourceSection = grouped.find(([, items]) => items.some((t) => t.tool_id === activeId));
+    const overSection = grouped.find(([, items]) => items.some((t) => t.tool_id === overId));
+    if (!sourceSection || !overSection) {
+      return;
+    }
+    const [sourceName, sourceItems] = sourceSection;
+    const [targetName, targetItems] = overSection;
+    const updates: { tool: TerraVoxTool; manifest: Record<string, unknown> }[] = [];
+    const overridePatch: Record<string, number> = {};
+
+    const buildManifest = (tool: TerraVoxTool, order: number, group: string) => {
+      const manifest: Record<string, unknown> = { ...tool, display_order: order };
+      if (group) {
+        manifest.display_group = group;
+      } else {
+        delete manifest.display_group;
+      }
+      return manifest;
+    };
+
+    if (sourceName === targetName) {
+      const ids = sourceItems.map((t) => t.tool_id);
+      const next = arrayMove(ids, ids.indexOf(activeId), ids.indexOf(overId));
+      next.forEach((id, idx) => {
+        overridePatch[id] = idx * 10;
+      });
+      for (let idx = 0; idx < next.length; idx++) {
+        const tool = toolById.get(next[idx]);
+        if (tool && tool.display_order !== idx * 10) {
+          updates.push({ tool, manifest: buildManifest(tool, idx * 10, sourceName) });
+        }
+      }
+    } else {
+      const targetIds = targetItems.map((t) => t.tool_id);
+      targetIds.splice(Math.max(0, targetIds.indexOf(overId)), 0, activeId);
+      targetIds.forEach((id, idx) => {
+        overridePatch[id] = idx * 10;
+      });
+      const moved = toolById.get(activeId);
+      if (moved) {
+        updates.push({
+          tool: moved,
+          manifest: buildManifest(moved, overridePatch[activeId], targetName),
+        });
+      }
+      for (let idx = 0; idx < targetIds.length; idx++) {
+        const tool = toolById.get(targetIds[idx]);
+        if (!tool || tool.tool_id === activeId) {
+          continue;
+        }
+        if ((tool.display_group?.trim() ?? '') !== targetName || tool.display_order !== idx * 10) {
+          updates.push({
+            tool,
+            manifest: buildManifest(tool, idx * 10, targetName),
+          });
+        }
+      }
+    }
+
+    if (updates.length === 0) {
+      return;
+    }
+    setOrderOverride((prev) => ({ ...prev, ...overridePatch }));
+    void (async () => {
+      setSavingOrder(true);
+      setMutError(null);
+      try {
+        for (const { tool, manifest } of updates) {
+          await updateToolFn({ data: { toolId: tool.tool_id, manifest } });
+        }
+        void queryClient.invalidateQueries({ queryKey: ['terravox'] });
+        setOrderOverride((prev) => {
+          const next = { ...prev };
+          for (const id of Object.keys(overridePatch)) {
+            delete next[id];
+          }
+          return next;
+        });
+      } catch (error) {
+        setMutError((error as Error).message);
+      } finally {
+        setSavingOrder(false);
+      }
+    })();
+  };
+
+  const renderBody = () => {
+    if (toolsQuery.isLoading) {
+      return <LoadingState />;
+    }
+    if (toolsQuery.isError) {
+      const detail = (toolsQuery.error as Error)?.message;
+      return (
+        <EmptyState
+          message={
+            detail
+              ? `${localize('com_tools_load_error')} — ${detail}`
+              : localize('com_tools_retry_later')
+          }
+        />
+      );
+    }
+    if (filtered.length === 0) {
+      return (
+        <EmptyState
+          message={search ? localize('com_tools_no_match') : localize('com_tools_empty_hint')}
+        />
+      );
+    }
+    return (
+      <DndContext
+        sensors={toolSensors}
+        collisionDetection={closestCenter}
+        modifiers={toolModifiers}
+        onDragEnd={onToolDragEnd}
+      >
+        <div className="overflow-x-auto rounded-lg border border-(--cui-color-stroke-default)">
+          <table className="w-full text-left text-sm">
+            <thead>
+              <tr className="border-b border-(--cui-color-stroke-default) bg-(--cui-color-background-muted)">
+                <th scope="col" className="px-4 py-2.5 font-medium text-(--cui-color-text-muted)">
+                  {localize('com_tools_col_tool')}
+                </th>
+                <th scope="col" className="px-4 py-2.5 font-medium text-(--cui-color-text-muted)">
+                  {localize('com_tools_col_group')}
+                </th>
+                <th scope="col" className="px-4 py-2.5 font-medium text-(--cui-color-text-muted)">
+                  {localize('com_tools_col_version')}
+                </th>
+                <th scope="col" className="px-4 py-2.5 font-medium text-(--cui-color-text-muted)">
+                  {localize('com_tools_col_expose')}
+                </th>
+                <th scope="col" className="px-4 py-2.5 font-medium text-(--cui-color-text-muted)">
+                  {localize('com_tools_col_status')}
+                </th>
+                <th scope="col" className="px-4 py-2.5 font-medium text-(--cui-color-text-muted)">
+                  <span className="sr-only">{localize('com_ui_actions')}</span>
+                </th>
+              </tr>
+            </thead>
+            <tbody>
+              {grouped.map(([group, items]) => (
+                <SortableContext
+                  key={group || '__ungrouped__'}
+                  items={items.map((t) => t.tool_id)}
+                  strategy={verticalListSortingStrategy}
+                >
+                  <tr className="bg-(--cui-color-background-muted)">
+                    <td
+                      colSpan={6}
+                      className="px-4 py-2 text-xs font-semibold text-(--cui-color-text-muted)"
+                    >
+                      {group || localize('com_tools_group_ungrouped')}
+                      <span className="ms-2 font-normal">{items.length}</span>
+                    </td>
+                  </tr>
+                  {items.map((tool) => (
+                    <ToolRow
+                      key={tool.tool_id}
+                      tool={tool}
+                      groups={displayGroups}
+                      moving={
+                        moveGroupMutation.isPending &&
+                        moveGroupMutation.variables?.tool.tool_id === tool.tool_id
+                      }
+                      onMoveGroup={(group) => moveGroupMutation.mutate({ tool, group })}
+                      toggling={
+                        toggleMutation.isPending &&
+                        toggleMutation.variables?.toolId === tool.tool_id
+                      }
+                      onExposeToggle={(tool, front) => {
+                        const expose = (tool.expose ?? []).includes(front)
+                          ? (tool.expose ?? []).filter((f) => f !== front)
+                          : [...(tool.expose ?? []), front];
+                        exposeMutation.mutate({ tool, expose });
+                      }}
+                      onToggle={(enabled) =>
+                        toggleMutation.mutate({ toolId: tool.tool_id, enabled })
+                      }
+                      onEdit={() => {
+                        setEditing(tool);
+                        setEditOpen(true);
+                      }}
+                      onCopy={() => void copyId(tool)}
+                      onDelete={() => setDeleteTarget(tool)}
+                    />
+                  ))}
+                </SortableContext>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </DndContext>
+    );
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-wrap items-center gap-3">
+        <SearchInput
+          value={search}
+          onChange={setSearch}
+          placeholder={localize('com_tools_search')}
+          className="relative max-w-xs flex-1"
+        />
+        <span className="text-xs text-(--cui-color-text-muted)">
+          {localize('com_tools_count', { count: filtered.length })}
+        </span>
+        <div className="ms-auto flex items-center gap-2">
+          <button
+            type="button"
+            onClick={() => setImportOpen(true)}
+            className="flex items-center gap-1.5 rounded-lg border border-(--cui-color-stroke-default) px-3 py-1.5 text-sm text-(--cui-color-text-default) transition-colors hover:bg-(--cui-color-background-hover)"
+          >
+            <Icon name="upload" size="sm" />
+            {localize('com_tools_import_button')}
+          </button>
+          <button
+            type="button"
+            onClick={() => setGiteaOpen(true)}
+            className="flex items-center gap-1.5 rounded-lg bg-(--cui-color-accent-primary) px-3 py-1.5 text-sm font-medium text-white transition-colors hover:opacity-90"
+          >
+            <Icon name="plus" size="sm" />
+            {localize('com_tools_add_button')}
+          </button>
+        </div>
+      </div>
+
+      <PendingUpdatesPanel
+        updates={pendingQuery.data ?? []}
+        checkingToolId={
+          confirmUpdateMutation.isPending
+            ? (confirmUpdateMutation.variables?.tool_id ?? null)
+            : null
+        }
+        error={pendingQuery.isError ? (pendingQuery.error as Error).message : null}
+        notice={updateNotice}
+        onConfirm={(update) => confirmUpdateMutation.mutate(update)}
+      />
+
+      {mutError && (
+        <p role="alert" className="text-sm text-(--cui-color-text-danger)">
+          {mutError}
+        </p>
+      )}
+      {savingOrder && (
+        <p className="text-xs text-(--cui-color-text-muted)">
+          {localize('com_tools_group_order_saving')}
+        </p>
+      )}
+
+      {renderBody()}
+
+      <ToolEditDialog
+        open={editOpen}
+        tool={editing}
+        prefill={prefill}
+        groups={groups}
+        displayGroupOptions={displayGroups}
+        handlers={handlersQuery.data ?? []}
+        saving={saveMutation.isPending}
+        error={
+          saveMutation.isError
+            ? {
+                message: (saveMutation.error as Error).message,
+                errors: (
+                  saveMutation.error as Error & { errors?: { path?: string; message: string }[] }
+                ).errors,
+              }
+            : undefined
+        }
+        onSubmit={(manifest) => {
+          const wasEdit = editing !== null;
+          saveMutation.mutate(manifest, {
+            onSuccess: () =>
+              notifySuccess(
+                localize(wasEdit ? 'com_toast_tool_updated' : 'com_toast_tool_created'),
+              ),
+          });
+        }}
+        onClose={() => {
+          setEditOpen(false);
+          setEditing(null);
+          setPrefill(null);
+        }}
+      />
+
+      <GiteaImportDialog
+        open={giteaOpen}
+        onClose={() => setGiteaOpen(false)}
+        onManualCreate={() => {
+          setGiteaOpen(false);
+          openCreate();
+        }}
+        onContinue={(data) => {
+          setGiteaOpen(false);
+          setEditing(null);
+          setPrefill(data);
+          setEditOpen(true);
+        }}
+      />
+
+      <ConfirmDialog
+        open={deleteTarget !== null}
+        title={localize('com_tools_delete_title')}
+        description={localize('com_tools_delete_desc', {
+          name: deleteTarget?.tool_id ?? '',
+        })}
+        confirmLabel={localize('com_ui_delete')}
+        saving={deleteMutation.isPending}
+        error={deleteMutation.isError ? (deleteMutation.error as Error).message : undefined}
+        onConfirm={() => deleteTarget && deleteMutation.mutate(deleteTarget.tool_id)}
+        onCancel={() => setDeleteTarget(null)}
+      />
+
+      <ImportToolsDialog
+        open={importOpen}
+        onClose={() => setImportOpen(false)}
+        onImported={invalidate}
+      />
+    </div>
+  );
+}
+
+/** zip 字节数 → 可读大小（KB/MB） */
+const formatSize = (bytes: number): string =>
+  bytes >= 1024 * 1024
+    ? `${(bytes / 1024 / 1024).toFixed(1)} MB`
+    : `${Math.max(1, Math.round(bytes / 1024))} KB`;
+
+/** 顶部待确认更新区：仓库领先版本经管理员确认前不下发前端（2.8.0 治理决策）。 */
+function PendingUpdatesPanel({
+  updates,
+  checkingToolId,
+  error,
+  notice,
+  onConfirm,
+}: {
+  updates: PendingToolUpdate[];
+  checkingToolId: string | null;
+  error: string | null;
+  notice: string | null;
+  onConfirm: (update: PendingToolUpdate) => void;
+}) {
+  const localize = useLocalize();
+  if (updates.length === 0 && !error && !notice) {
+    return null;
+  }
+  return (
+    <section
+      aria-label={localize('com_tools_pending_title')}
+      className="rounded-lg border border-(--cui-color-stroke-default) bg-(--cui-color-background-warning-muted) p-4"
+    >
+      <div className="flex flex-col gap-1">
+        <h3 className="text-sm font-medium text-(--cui-color-text-warning)">
+          {localize('com_tools_pending_title')}
+        </h3>
+        <p className="text-xs text-(--cui-color-text-muted)">
+          {localize('com_tools_pending_hint')}
+        </p>
+      </div>
+      {error && (
+        <p role="alert" className="mt-2 text-sm text-(--cui-color-text-danger)">
+          {error}
+        </p>
+      )}
+      {notice && <p className="mt-2 text-xs text-(--cui-color-text-warning)">{notice}</p>}
+      <ul className="mt-3 flex flex-col gap-2">
+        {updates.map((update) => {
+          const checking = checkingToolId === update.tool_id;
+          return (
+            <li
+              key={update.tool_id}
+              className="flex flex-wrap items-center gap-x-3 gap-y-1 rounded-lg border border-(--cui-color-stroke-default) bg-(--cui-color-background-default) px-3 py-2 text-sm"
+            >
+              <span className="flex min-w-0 flex-col">
+                <span className="font-medium text-(--cui-color-text-default)">
+                  {update.display_name}
+                </span>
+                <code className="text-xs text-(--cui-color-text-muted)">{update.tool_id}</code>
+              </span>
+              <span className="font-mono text-xs text-(--cui-color-text-default)">
+                {localize('com_tools_pending_versions', {
+                  current: `v${update.current_version}`,
+                  latest: `v${update.package.version}`,
+                })}
+              </span>
+              <span className="text-xs text-(--cui-color-text-muted)">
+                {`${formatSize(update.package.size)} · ${new Date(
+                  update.package.updated_at,
+                ).toLocaleDateString()}`}
+              </span>
+              <span className="ms-auto flex items-center gap-2">
+                {checking && (
+                  <span className="text-xs text-(--cui-color-text-muted)">
+                    {localize('com_tools_pending_checking')}
+                  </span>
+                )}
+                <Button
+                  type="primary"
+                  label={localize('com_tools_pending_confirm')}
+                  disabled={checking}
+                  onClick={() => onConfirm(update)}
+                />
+              </span>
+            </li>
+          );
+        })}
+      </ul>
+    </section>
+  );
+}
+
+function ToolRow({
+  tool,
+  groups,
+  moving,
+  onMoveGroup,
+  toggling,
+  onToggle,
+  onExposeToggle,
+  onEdit,
+  onCopy,
+  onDelete,
+}: {
+  tool: TerraVoxTool;
+  groups: string[];
+  moving: boolean;
+  onMoveGroup: (group: string) => void;
+  toggling: boolean;
+  onToggle: (enabled: boolean) => void;
+  onExposeToggle: (tool: TerraVoxTool, front: 'ui' | 'mcp') => void;
+  onEdit: () => void;
+  onCopy: () => void;
+  onDelete: () => void;
+}) {
+  const localize = useLocalize();
+  const enabled = tool.enabled !== false;
+  const current = tool.display_group?.trim() ?? '';
+  const options =
+    current && !groups.includes(current)
+      ? [...groups, current].sort((a, b) => a.localeCompare(b))
+      : groups;
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+    id: tool.tool_id,
+    data: { section: tool.display_group?.trim() ?? '' },
+  });
+  return (
+    <tr
+      ref={setNodeRef}
+      style={{ transform: CSS.Transform.toString(transform), transition }}
+      className={
+        'group/row border-b border-(--cui-color-stroke-default) last:border-b-0' +
+        (isDragging ? ' opacity-40' : '')
+      }
+    >
+      <td className="px-4 py-3">
+        <div className="flex flex-col">
+          <span className="flex items-center gap-2 font-medium text-(--cui-color-text-default)">
+            {tool.display_name}
+            {tool.dangerous && (
+              <span className={DANGER_STYLE}>{localize('com_tools_dangerous')}</span>
+            )}
+          </span>
+          <code className="text-xs text-(--cui-color-text-muted)">{tool.tool_id}</code>
+        </div>
+      </td>
+      <td className="px-4 py-3">
+        {/* 展示分组：标准下拉直改（= display_group），清空即未分组；选中即
+            提交，避免逐键 PATCH。 */}
+        <GroupCell
+          value={current}
+          groups={options}
+          disabled={moving}
+          label={localize('com_tools_col_group')}
+          placeholder={localize('com_tools_group_ungrouped')}
+          onCommit={(group) => onMoveGroup(group)}
+        />
+      </td>
+      <td className="px-4 py-3 text-(--cui-color-text-muted)">{tool.version}</td>
+      <td className="px-4 py-3">
+        {/* 暴露面直编（2.20.0）：ui / mcp 两个开关直接落在行上 */}
+        <div className="flex items-center gap-3">
+          {(['ui', 'mcp'] as const).map((front) => (
+            <Checkbox
+              key={front}
+              checked={(tool.expose ?? []).includes(front)}
+              disabled={moving}
+              onCheckedChange={() => onExposeToggle(tool, front)}
+              label={front}
+            />
+          ))}
+        </div>
+      </td>
+      <td className="px-4 py-3">
+        <StatusToggle
+          id={tool.tool_id}
+          isActive={enabled}
+          disabled={toggling}
+          onChange={onToggle}
+        />
+      </td>
+      <td className="px-4 py-3 text-end">
+        {/* 行内操作（2.19.0）：平铺按钮替代三点菜单；首位拖拽把手（2.22.0 组内排序） */}
+        <div className="flex items-center justify-end gap-1">
+          <span
+            title={localize('com_tools_drag_handle')}
+            aria-label={localize('com_tools_drag_handle')}
+            className="hidden shrink-0 cursor-grab touch-none px-1 text-(--cui-color-text-disabled) opacity-0 transition-opacity select-none group-hover/row:opacity-100 md:block"
+            {...attributes}
+            {...listeners}
+          >
+            ⠿
+          </span>
+          <InlineAction label={localize('com_ui_edit')} onClick={onEdit}>
+            ✎
+          </InlineAction>
+          <InlineAction label={localize('com_tools_copy_id')} onClick={onCopy}>
+            ⧉
+          </InlineAction>
+          <InlineAction label={localize('com_ui_delete')} danger onClick={onDelete}>
+            ✕
+          </InlineAction>
+        </div>
+      </td>
+    </tr>
+  );
+}
diff --git a/src/components/tools/ToolEditDialog.tsx b/src/components/tools/ToolEditDialog.tsx
new file mode 100644
index 00000000..3c22a99f
--- /dev/null
+++ b/src/components/tools/ToolEditDialog.tsx
@@ -0,0 +1,928 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Button, Dialog, Switch, Tabs } from '@clickhouse/click-ui';
+import type * as t from '@/types';
+import type { TerraVoxTool } from '@/server';
+import { useLocalize } from '@/hooks';
+import { SelectField } from '@/components/configuration';
+import { ParamBuilder } from './ParamBuilder';
+
+/** Editable draft of a manifest: scalars as strings, JSON blocks as text. */
+interface Draft {
+  prefix: string;
+  customPrefix: string;
+  suffix: string;
+  version: string;
+  displayName: string;
+  description: string;
+  displayGroup: string;
+  helpUrl: string;
+  usageStats: boolean;
+  exposeUi: boolean;
+  exposeMcp: boolean;
+  allowedGroups: string[];
+  dangerous: boolean;
+  enabled: boolean;
+  parametersJson: string;
+  formJson: string;
+  execKind: 'server' | 'desktop' | 'plugin' | 'web';
+  handler: string;
+  webUrl: string;
+  distOwner: string;
+  distRepo: string;
+  distVersion: string;
+  distSha256: string;
+  distLauncher: string;
+  distRuntime: string;
+  distHostLauncher: string;
+  distHostRootHints: string;
+  distInstallScript: string;
+  distUninstallScript: string;
+  timeout: string;
+  renderer: string;
+  resultConfigJson: string;
+  redactParams: string;
+}
+
+/** Draft → execution block per kind (contracts 2.11.0). `distribution` is the
+ * desktop/plugin shared Gitea registration (source + supplemental fields). */
+function buildExecution(
+  draft: Draft,
+  distribution: Record<string, unknown>,
+): Record<string, unknown> {
+  if (draft.execKind === 'server') {
+    return { kind: 'server', handler: draft.handler };
+  }
+  if (draft.execKind === 'web') {
+    return { kind: 'web', url: draft.webUrl.trim() };
+  }
+  const dist: Record<string, unknown> = { ...distribution };
+  if (draft.execKind === 'plugin') {
+    dist.host_launcher = draft.distHostLauncher.trim();
+    const hints = draft.distHostRootHints
+      .split('\n')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    if (hints.length > 0) {
+      dist.host_root_hints = hints;
+    }
+    if (draft.distInstallScript.trim()) {
+      dist.install_script = draft.distInstallScript.trim();
+    }
+    if (draft.distUninstallScript.trim()) {
+      dist.uninstall_script = draft.distUninstallScript.trim();
+    }
+  }
+  return { kind: draft.execKind, distribution: dist };
+}
+
+const toEditableJson = (value: unknown): string =>
+  value === undefined || value === null ? '' : JSON.stringify(value, null, 2);
+
+const parseJsonBlock = (text: string): { value?: unknown; error?: string } => {
+  if (!text.trim()) {
+    return { value: undefined };
+  }
+  try {
+    return { value: JSON.parse(text) };
+  } catch (error) {
+    return { error: (error as Error).message };
+  }
+};
+
+export function ToolEditDialog({
+  open,
+  tool,
+  prefill,
+  groups,
+  displayGroupOptions,
+  handlers,
+  saving,
+  error,
+  onSubmit,
+  onClose,
+}: t.ToolEditDialogProps) {
+  const localize = useLocalize();
+  const isEdit = tool !== null;
+  const existingNames = useMemo(() => groups.map((g) => g.name), [groups]);
+
+  const [draft, setDraft] = useState<Draft>(() =>
+    initDraft(tool ?? prefill ?? null, existingNames),
+  );
+  const [clientError, setClientError] = useState<string | null>(null);
+  const [tab, setTab] = useState('basic');
+
+  useEffect(() => {
+    if (open) {
+      setDraft(initDraft(tool ?? prefill ?? null, existingNames));
+      setClientError(null);
+      setTab('basic');
+    }
+  }, [open, tool, prefill, existingNames]);
+
+  const set = <K extends keyof Draft>(key: K, value: Draft[K]) =>
+    setDraft((prev) => ({ ...prev, [key]: value }));
+
+  const toolId = isEdit ? tool.tool_id : buildToolId(draft);
+
+  const handleSubmit = () => {
+    setClientError(null);
+    if (!toolId) {
+      setClientError(localize('com_tools_err_tool_id'));
+      setTab('basic');
+      return;
+    }
+    if (!draft.displayName.trim()) {
+      setClientError(localize('com_tools_err_display_name'));
+      setTab('basic');
+      return;
+    }
+    const parameters = parseJsonBlock(draft.parametersJson);
+    if (
+      parameters.error ||
+      (parameters.value !== undefined && typeof parameters.value !== 'object')
+    ) {
+      setClientError(localize('com_tools_err_parameters_json'));
+      setTab('params');
+      return;
+    }
+    const form = parseJsonBlock(draft.formJson);
+    if (form.error || (form.value !== undefined && typeof form.value !== 'object')) {
+      setClientError(localize('com_tools_err_form_json'));
+      setTab('params');
+      return;
+    }
+    const resultConfig = parseJsonBlock(draft.resultConfigJson);
+    if (resultConfig.error) {
+      setClientError(localize('com_tools_err_result_config_json'));
+      setTab('exec');
+      return;
+    }
+    if (draft.execKind === 'server' && !draft.handler) {
+      setClientError(localize('com_tools_err_handler'));
+      setTab('exec');
+      return;
+    }
+    if (draft.execKind === 'web' && !draft.webUrl.trim().startsWith('http')) {
+      setClientError(localize('com_tools_err_web_url'));
+      setTab('exec');
+      return;
+    }
+    if (draft.execKind === 'plugin' && !draft.distHostLauncher.trim()) {
+      setClientError(localize('com_tools_err_host_launcher'));
+      setTab('exec');
+      return;
+    }
+    if (draft.execKind === 'desktop' && (!draft.distOwner.trim() || !draft.distRepo.trim())) {
+      setClientError(localize('com_tools_err_owner_repo'));
+      setTab('exec');
+      return;
+    }
+    if (
+      draft.execKind === 'desktop' &&
+      draft.distSha256.trim() &&
+      !/^[a-f0-9]{64}$/.test(draft.distSha256.trim())
+    ) {
+      setClientError(localize('com_tools_err_sha256'));
+      setTab('exec');
+      return;
+    }
+    if (!draft.renderer.trim()) {
+      setClientError(localize('com_tools_err_renderer'));
+      setTab('exec');
+      return;
+    }
+
+    const timeout = Number(draft.timeout);
+    const redact = draft.redactParams
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    /** desktop：登记 用户/仓库；补充字段仅在 tool.json 缺失时兜底（可全空） */
+    const distribution: Record<string, unknown> = {
+      source: {
+        type: 'gitea_release',
+        owner: draft.distOwner.trim(),
+        repo: draft.distRepo.trim(),
+      },
+    };
+    if (draft.distVersion.trim()) {
+      distribution.version = draft.distVersion.trim();
+    }
+    if (draft.distSha256.trim()) {
+      distribution.package_sha256 = draft.distSha256.trim();
+    }
+    if (draft.distLauncher.trim()) {
+      distribution.launcher = draft.distLauncher.trim();
+    }
+    if (draft.distRuntime.trim()) {
+      distribution.runtime = draft.distRuntime.trim();
+    }
+
+    const manifest: Record<string, unknown> = {
+      schema_version: 1,
+      tool_id: toolId,
+      version: draft.version.trim() || '1.0.0',
+      display_name: draft.displayName.trim(),
+      description: draft.description.trim(),
+      expose: [draft.exposeUi && 'ui', draft.exposeMcp && 'mcp'].filter(Boolean),
+      allowed_groups: draft.allowedGroups,
+      dangerous: draft.dangerous,
+      usage_stats: draft.usageStats,
+      enabled: draft.enabled,
+      parameters: parameters.value ?? { type: 'object', properties: {} },
+      execution: buildExecution(draft, distribution),
+      result: {
+        renderer: draft.renderer.trim(),
+        ...(resultConfig.value !== undefined ? { config: resultConfig.value } : {}),
+      },
+    };
+    if (form.value !== undefined) {
+      manifest.form = form.value;
+    }
+    if (Number.isFinite(timeout) && timeout > 0) {
+      manifest.timeout_seconds = Math.round(timeout);
+    }
+    if (redact.length > 0) {
+      manifest.audit = { redact_params: redact };
+    }
+    if (draft.displayGroup.trim()) {
+      manifest.display_group = draft.displayGroup.trim();
+    }
+    if (draft.helpUrl.trim()) {
+      manifest.help_url = draft.helpUrl.trim();
+    }
+    onSubmit(manifest);
+  };
+
+  const shownError = clientError ?? error?.message;
+  const fieldErrors = error?.errors;
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(isOpen) => {
+        if (!isOpen && !saving) {
+          onClose();
+        }
+      }}
+    >
+      <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
+        title={isEdit ? localize('com_tools_edit_title') : localize('com_tools_add_title')}
+        showClose
+        onClose={onClose}
+        className="modal-frost max-w-3xl!"
+      >
+        <Tabs value={tab} onValueChange={setTab} ariaLabel={localize('com_tools_edit_title')}>
+          <Tabs.TriggersList>
+            <Tabs.Trigger value="basic">{localize('com_tools_tab_basic')}</Tabs.Trigger>
+            <Tabs.Trigger value="params">{localize('com_tools_tab_params')}</Tabs.Trigger>
+            <Tabs.Trigger value="exec">{localize('com_tools_tab_exec')}</Tabs.Trigger>
+          </Tabs.TriggersList>
+        </Tabs>
+
+        <div className="mt-4 flex max-h-[65vh] min-h-[35vh] flex-col gap-4 overflow-y-auto pe-1 text-sm">
+          {tab === 'basic' && (
+            <BasicTab
+              draft={draft}
+              isEdit={isEdit}
+              toolId={toolId}
+              displayGroupOptions={displayGroupOptions}
+              groups={existingNames}
+              onSet={set}
+            />
+          )}
+          {tab === 'params' && <ParamsTab draft={draft} onSet={set} />}
+          {tab === 'exec' && <ExecTab draft={draft} handlers={handlers} onSet={set} />}
+        </div>
+
+        {shownError && (
+          <p role="alert" className="mt-3 text-sm text-(--cui-color-text-danger)">
+            {shownError}
+          </p>
+        )}
+        {fieldErrors && fieldErrors.length > 0 && (
+          <ul className="mt-2 list-inside list-disc text-xs text-(--cui-color-text-danger)">
+            {fieldErrors.map((e, i) => (
+              <li key={i}>
+                {e.path && <code className="me-1">{e.path}</code>}
+                {e.message}
+              </li>
+            ))}
+          </ul>
+        )}
+
+        <div className="mt-4 flex items-center justify-end gap-2">
+          <Button
+            type="secondary"
+            label={localize('com_ui_cancel')}
+            onClick={onClose}
+            disabled={saving}
+          />
+          <Button
+            type="primary"
+            label={localize(isEdit ? 'com_tools_save' : 'com_tools_create')}
+            onClick={handleSubmit}
+            disabled={saving}
+          />
+        </div>
+      </Dialog.Content>
+    </Dialog>
+  );
+}
+
+// ── Tab: 基本信息 ────────────────────────────────────────────────────
+
+function BasicTab({
+  draft,
+  isEdit,
+  toolId,
+  displayGroupOptions,
+  groups,
+  onSet,
+}: {
+  draft: Draft;
+  isEdit: boolean;
+  toolId: string;
+  displayGroupOptions: string[];
+  /** tool_id 命名空间前缀候选（与分组/权限无关）。 */
+  groups: string[];
+  onSet: <K extends keyof Draft>(key: K, value: Draft[K]) => void;
+}) {
+  const localize = useLocalize();
+  const labelClass = 'mb-1 block font-medium text-(--cui-color-text-default)';
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <label className={labelClass} htmlFor="tool-id">
+          {localize('com_tools_field_tool_id')}
+        </label>
+        {isEdit ? (
+          <code className="config-input-mono block w-full rounded-md border border-(--cui-color-stroke-default) bg-(--cui-color-background-muted) px-2.5 py-1.5 text-xs">
+            {toolId}
+          </code>
+        ) : (
+          <div className="flex items-center gap-2">
+            {/* SelectField 无宽度约束时在 flex 行里收缩到当前值宽度（实测 77px），
+                定宽防选项截断；SelectField 自身无 className 通道，按 KeyValueField
+                惯例外包一层宽度 div。 */}
+            <div className="w-44 shrink-0">
+              <SelectField
+                id="tool-prefix"
+                value={draft.prefix}
+                options={[
+                  ...groups.map((name) => ({ value: name, label: name })),
+                  { value: '__custom__', label: localize('com_tools_custom_group') },
+                ]}
+                onChange={(v) => onSet('prefix', v)}
+                aria-label={localize('com_tools_field_group')}
+              />
+            </div>
+            <span aria-hidden="true" className="text-(--cui-color-text-muted)">
+              .
+            </span>
+            {draft.prefix === '__custom__' ? (
+              <input
+                className="config-input flex-1"
+                placeholder={localize('com_tools_field_group')}
+                aria-label={localize('com_tools_field_group')}
+                value={draft.customPrefix}
+                onChange={(e) => onSet('customPrefix', e.target.value)}
+              />
+            ) : (
+              <input
+                className="config-input flex-1"
+                placeholder="tool_name"
+                aria-label={localize('com_tools_field_tool_suffix')}
+                value={draft.suffix}
+                onChange={(e) => onSet('suffix', e.target.value)}
+              />
+            )}
+            {(draft.prefix === '__custom__' || draft.suffix) && (
+              <code className="config-input-mono shrink-0 rounded border border-(--cui-color-stroke-default) px-2 py-1.5 text-xs text-(--cui-color-text-muted)">
+                {toolId}
+              </code>
+            )}
+          </div>
+        )}
+      </div>
+
+      <div className="grid grid-cols-2 gap-4">
+        <div>
+          <label className={labelClass} htmlFor="tool-version">
+            {localize('com_tools_field_version')}
+          </label>
+          <input
+            id="tool-version"
+            className="config-input w-full"
+            value={draft.version}
+            onChange={(e) => onSet('version', e.target.value)}
+            placeholder="1.0.0"
+          />
+        </div>
+        <div>
+          <label className={labelClass} htmlFor="tool-name">
+            {localize('com_tools_field_display_name')}
+          </label>
+          <input
+            id="tool-name"
+            className="config-input w-full"
+            value={draft.displayName}
+            onChange={(e) => onSet('displayName', e.target.value)}
+          />
+        </div>
+      </div>
+
+      <div>
+        <label className={labelClass} htmlFor="tool-desc">
+          {localize('com_tools_field_description')}
+        </label>
+        <textarea
+          id="tool-desc"
+          className="config-input min-h-20 w-full resize-y"
+          value={draft.description}
+          onChange={(e) => onSet('description', e.target.value)}
+        />
+      </div>
+
+      <div className="grid grid-cols-2 gap-4">
+        <div>
+          <label className={labelClass} htmlFor="tool-display-group">
+            {localize('com_tools_field_display_group')}
+          </label>
+          {/* 配置页同款标准下拉（click-ui Select）：不再用 datalist 自由文本 */}
+          <SelectField
+            id="tool-display-group"
+            value={draft.displayGroup || '__none__'}
+            options={[
+              { value: '__none__', label: localize('com_tools_display_group_none') },
+              ...displayGroupOptions
+                .filter((g) => g !== draft.displayGroup)
+                .map((g) => ({ value: g, label: g })),
+            ]}
+            onChange={(v) => onSet('displayGroup', v === '__none__' ? '' : v)}
+            placeholder={localize('com_tools_display_group_hint')}
+            aria-label={localize('com_tools_field_display_group')}
+          />
+        </div>
+        <div>
+          <label className={labelClass} htmlFor="tool-help-url">
+            {localize('com_tools_field_help_url')}
+          </label>
+          <input
+            id="tool-help-url"
+            className="config-input w-full"
+            value={draft.helpUrl}
+            placeholder="https://..."
+            onChange={(e) => onSet('helpUrl', e.target.value)}
+          />
+        </div>
+      </div>
+
+      {/* 暴露面（ui/mcp）已直编在工具清单行上（2.20.0），对话框不再重复 */}
+      <div className="grid grid-cols-1 gap-4">
+        <div>
+          <span className={labelClass}>{localize('com_tools_field_flags')}</span>
+          <div className="flex flex-col gap-2">
+            <span className="flex items-center justify-between gap-2">
+              <span>{localize('com_tools_field_enabled')}</span>
+              <Switch
+                checked={draft.enabled}
+                onCheckedChange={(v) => onSet('enabled', v)}
+                aria-label={localize('com_tools_field_enabled')}
+              />
+            </span>
+            <span className="flex items-center justify-between gap-2">
+              <span>{localize('com_tools_field_dangerous')}</span>
+              <Switch
+                checked={draft.dangerous}
+                onCheckedChange={(v) => onSet('dangerous', v)}
+                aria-label={localize('com_tools_field_dangerous')}
+              />
+            </span>
+            <span className="flex items-center justify-between gap-2">
+              <span>{localize('com_tools_field_usage_stats')}</span>
+              <Switch
+                checked={draft.usageStats}
+                onCheckedChange={(v) => onSet('usageStats', v)}
+                aria-label={localize('com_tools_field_usage_stats')}
+              />
+            </span>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// ── Tab: 参数与表单 ──────────────────────────────────────────────────
+
+function ParamsTab({
+  draft,
+  onSet,
+}: {
+  draft: Draft;
+  onSet: <K extends keyof Draft>(key: K, value: Draft[K]) => void;
+}) {
+  return (
+    <ParamBuilder
+      parametersJson={draft.parametersJson}
+      formJson={draft.formJson}
+      onChange={(parametersJson, formJson) => {
+        onSet('parametersJson', parametersJson);
+        onSet('formJson', formJson);
+      }}
+    />
+  );
+}
+
+// ── Tab: 执行与结果 ──────────────────────────────────────────────────
+
+function ExecTab({
+  draft,
+  handlers,
+  onSet,
+}: {
+  draft: Draft;
+  handlers: string[];
+  onSet: <K extends keyof Draft>(key: K, value: Draft[K]) => void;
+}) {
+  const localize = useLocalize();
+  const labelClass = 'mb-1 block font-medium text-(--cui-color-text-default)';
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="grid grid-cols-3 gap-4">
+        <div>
+          <label className={labelClass} htmlFor="exec-kind">
+            {localize('com_tools_field_exec_kind')}
+          </label>
+          <div className="w-full">
+            <SelectField
+              id="exec-kind"
+              value={draft.execKind}
+              options={[
+                { value: 'server', label: 'server' },
+                { value: 'desktop', label: 'desktop' },
+                { value: 'plugin', label: 'plugin' },
+                { value: 'web', label: 'web' },
+              ]}
+              onChange={(v) => onSet('execKind', v as Draft['execKind'])}
+              aria-label={localize('com_tools_field_exec_kind')}
+            />
+          </div>
+        </div>
+        {draft.execKind === 'web' && (
+          <div className="col-span-2">
+            <label className={labelClass} htmlFor="exec-web-url">
+              {localize('com_tools_field_web_url')}
+            </label>
+            <input
+              id="exec-web-url"
+              className="config-input-mono config-input w-full font-mono text-xs"
+              value={draft.webUrl}
+              onChange={(e) => onSet('webUrl', e.target.value)}
+              placeholder="https://"
+              spellCheck={false}
+            />
+          </div>
+        )}
+        {draft.execKind === 'server' ? (
+          <div>
+            <label className={labelClass} htmlFor="exec-handler">
+              {localize('com_tools_field_handler')}
+            </label>
+            <div className="w-full">
+              <SelectField
+                id="exec-handler"
+                value={draft.handler || '__none__'}
+                options={[
+                  { value: '__none__', label: '—' },
+                  ...handlers.map((name) => ({ value: name, label: name })),
+                ]}
+                onChange={(v) => onSet('handler', v === '__none__' ? '' : v)}
+                aria-label={localize('com_tools_field_handler')}
+              />
+            </div>
+          </div>
+        ) : (
+          <div>
+            <label className={labelClass} htmlFor="exec-dist-owner">
+              {localize('com_tools_field_dist_owner')}
+            </label>
+            <input
+              id="exec-dist-owner"
+              className="config-input w-full"
+              value={draft.distOwner}
+              onChange={(e) => onSet('distOwner', e.target.value)}
+              placeholder="terravox"
+            />
+          </div>
+        )}
+      </div>
+      {draft.execKind === 'plugin' && (
+        <div className="grid grid-cols-2 gap-4">
+          <div>
+            <label className={labelClass} htmlFor="exec-dist-host-launcher">
+              {localize('com_tools_field_dist_host_launcher')}
+            </label>
+            <input
+              id="exec-dist-host-launcher"
+              className="config-input-mono config-input w-full font-mono text-xs"
+              value={draft.distHostLauncher}
+              onChange={(e) => onSet('distHostLauncher', e.target.value)}
+              placeholder="bin/ArcGISPro.exe"
+              spellCheck={false}
+            />
+          </div>
+          <div>
+            <label className={labelClass} htmlFor="exec-dist-host-hints">
+              {localize('com_tools_field_dist_host_hints')}
+            </label>
+            <textarea
+              id="exec-dist-host-hints"
+              className="config-input-mono config-input h-20 w-full font-mono text-xs"
+              value={draft.distHostRootHints}
+              onChange={(e) => onSet('distHostRootHints', e.target.value)}
+              placeholder={'C:\\Program Files\\ArcGIS\\Pro\nD:\\SuperMap\\iDesktop'}
+              spellCheck={false}
+            />
+          </div>
+          <div>
+            <label className={labelClass} htmlFor="exec-dist-install-script">
+              {localize('com_tools_field_dist_install_script')}
+            </label>
+            <input
+              id="exec-dist-install-script"
+              className="config-input-mono config-input w-full font-mono text-xs"
+              value={draft.distInstallScript}
+              onChange={(e) => onSet('distInstallScript', e.target.value)}
+              placeholder="install.bat / install.ps1（缺省自动识别）"
+              spellCheck={false}
+            />
+          </div>
+          <div>
+            <label className={labelClass} htmlFor="exec-dist-uninstall-script">
+              {localize('com_tools_field_dist_uninstall_script')}
+            </label>
+            <input
+              id="exec-dist-uninstall-script"
+              className="config-input-mono config-input w-full font-mono text-xs"
+              value={draft.distUninstallScript}
+              onChange={(e) => onSet('distUninstallScript', e.target.value)}
+              placeholder="uninstall.bat / uninstall.ps1"
+              spellCheck={false}
+            />
+          </div>
+        </div>
+      )}
+      <div>
+        <label className={labelClass} htmlFor="exec-timeout">
+          {localize('com_tools_field_timeout')}
+        </label>
+        <input
+          id="exec-timeout"
+          type="number"
+          min={1}
+          className="config-input w-full"
+          value={draft.timeout}
+          onChange={(e) => onSet('timeout', e.target.value)}
+        />
+      </div>
+
+      {(draft.execKind === 'desktop' || draft.execKind === 'plugin') && (
+        <>
+          <div>
+            <label className={labelClass} htmlFor="exec-dist-repo">
+              {localize('com_tools_field_dist_repo')}
+            </label>
+            <input
+              id="exec-dist-repo"
+              className="config-input w-full"
+              value={draft.distRepo}
+              onChange={(e) => onSet('distRepo', e.target.value)}
+              placeholder="batch-export"
+            />
+            <p className="mt-1 text-xs text-(--cui-color-text-muted)">
+              {localize('com_tools_dist_hint')}
+            </p>
+          </div>
+          <div className="flex flex-col gap-3 rounded-lg border border-(--cui-color-stroke-default) p-3">
+            <span className="text-xs font-medium text-(--cui-color-text-muted)">
+              {localize('com_tools_field_dist_extra')}
+            </span>
+            <div className="grid grid-cols-2 gap-4">
+              <div>
+                <label className={labelClass} htmlFor="exec-dist-version">
+                  {localize('com_tools_field_dist_version')}
+                </label>
+                <input
+                  id="exec-dist-version"
+                  className="config-input w-full"
+                  value={draft.distVersion}
+                  onChange={(e) => onSet('distVersion', e.target.value)}
+                  placeholder="1.0.0"
+                />
+              </div>
+              <div>
+                <label className={labelClass} htmlFor="exec-dist-runtime">
+                  {localize('com_tools_field_dist_runtime')}
+                </label>
+                <div className="w-full">
+                  <SelectField
+                    id="exec-dist-runtime"
+                    value={draft.distRuntime || '__none__'}
+                    options={[
+                      { value: '__none__', label: '—' },
+                      { value: 'self-contained', label: 'self-contained' },
+                      { value: 'standard-python', label: 'standard-python' },
+                      { value: 'arcpy3', label: 'arcpy3' },
+                    ]}
+                    onChange={(v) => onSet('distRuntime', v === '__none__' ? '' : v)}
+                    aria-label={localize('com_tools_field_dist_runtime')}
+                  />
+                </div>
+              </div>
+              <div>
+                <label className={labelClass} htmlFor="exec-dist-launcher">
+                  {localize('com_tools_field_dist_launcher')}
+                </label>
+                <input
+                  id="exec-dist-launcher"
+                  className="config-input w-full"
+                  value={draft.distLauncher}
+                  onChange={(e) => onSet('distLauncher', e.target.value)}
+                  placeholder="main.py"
+                />
+              </div>
+              <div>
+                <label className={labelClass} htmlFor="exec-dist-sha256">
+                  {localize('com_tools_field_dist_sha256')}
+                </label>
+                <input
+                  id="exec-dist-sha256"
+                  className="config-input-mono config-input w-full font-mono text-xs"
+                  spellCheck={false}
+                  value={draft.distSha256}
+                  onChange={(e) => onSet('distSha256', e.target.value)}
+                  placeholder="<64 hex>"
+                />
+              </div>
+            </div>
+          </div>
+        </>
+      )}
+
+      <div className="grid grid-cols-2 gap-4">
+        <div>
+          <label className={labelClass} htmlFor="result-renderer">
+            {localize('com_tools_field_renderer')}
+          </label>
+          <input
+            id="result-renderer"
+            className="config-input w-full"
+            value={draft.renderer}
+            onChange={(e) => onSet('renderer', e.target.value)}
+            placeholder="json | markdown | table | map | file | text"
+          />
+        </div>
+        <div>
+          <label className={labelClass} htmlFor="result-redact">
+            {localize('com_tools_field_redact')}
+          </label>
+          <input
+            id="result-redact"
+            className="config-input w-full"
+            value={draft.redactParams}
+            onChange={(e) => onSet('redactParams', e.target.value)}
+            placeholder="path, token"
+          />
+          <p className="mt-1 text-xs text-(--cui-color-text-muted)">
+            {localize('com_tools_redact_hint')}
+          </p>
+        </div>
+      </div>
+
+      <div>
+        <label className={labelClass} htmlFor="result-config">
+          {localize('com_tools_field_result_config')}
+        </label>
+        <textarea
+          id="result-config"
+          className="config-input-mono config-input min-h-28 w-full resize-y font-mono text-xs"
+          spellCheck={false}
+          value={draft.resultConfigJson}
+          onChange={(e) => onSet('resultConfigJson', e.target.value)}
+          placeholder='{ "columns": ["col1", "col2"] }'
+        />
+        <p className="mt-1 text-xs text-(--cui-color-text-muted)">
+          {localize('com_tools_result_config_hint')}
+        </p>
+      </div>
+    </div>
+  );
+}
+
+// ── helpers ──────────────────────────────────────────────────────────
+
+function buildToolId(draft: Draft): string {
+  const prefix = draft.prefix === '__custom__' ? draft.customPrefix.trim() : draft.prefix;
+  const suffix = draft.suffix.trim();
+  if (!prefix) {
+    return suffix; /* still typing the prefix — show what exists */
+  }
+  return suffix ? `${prefix}.${suffix}` : prefix;
+}
+
+function initDraft(tool: TerraVoxTool | null, existingNames: string[]): Draft {
+  if (!tool) {
+    return {
+      prefix: existingNames[0] ?? '__custom__',
+      customPrefix: '',
+      suffix: '',
+      version: '1.0.0',
+      displayName: '',
+      description: '',
+      displayGroup: '',
+      helpUrl: '',
+      usageStats: true,
+      exposeUi: true,
+      exposeMcp: false,
+      allowedGroups: ['*'],
+      dangerous: false,
+      enabled: true,
+      parametersJson: '{\n  "type": "object",\n  "properties": {}\n}',
+      formJson: '',
+      execKind: 'server',
+      handler: '',
+      webUrl: '',
+      distOwner: '',
+      distRepo: '',
+      distVersion: '',
+      distSha256: '',
+      distLauncher: '',
+      distRuntime: '',
+      distHostLauncher: '',
+      distHostRootHints: '',
+      distInstallScript: '',
+      distUninstallScript: '',
+      timeout: '60',
+      renderer: 'json',
+      resultConfigJson: '',
+      redactParams: '',
+    };
+  }
+  const execution = (tool.execution ?? {}) as Record<string, unknown>;
+  const kind =
+    execution.kind === 'desktop' || execution.kind === 'plugin' || execution.kind === 'web'
+      ? execution.kind
+      : 'server';
+  const distribution = (execution.distribution ?? {}) as Record<string, unknown>;
+  const source = (distribution.source ?? {}) as Record<string, unknown>;
+  const hostHints = Array.isArray(distribution.host_root_hints)
+    ? (distribution.host_root_hints as unknown[]).map(String)
+    : [];
+  const [prefix, ...rest] = tool.tool_id.split('.');
+  return {
+    prefix: existingNames.includes(prefix) ? prefix : '__custom__',
+    customPrefix: existingNames.includes(prefix) ? '' : prefix,
+    suffix: rest.join('.'),
+    version: tool.version ?? '1.0.0',
+    displayName: tool.display_name ?? '',
+    description: tool.description ?? '',
+    displayGroup: typeof tool.display_group === 'string' ? tool.display_group : '',
+    helpUrl: typeof tool.help_url === 'string' ? tool.help_url : '',
+    usageStats: tool.usage_stats !== false,
+    exposeUi: (tool.expose ?? []).includes('ui'),
+    exposeMcp: (tool.expose ?? []).includes('mcp'),
+    allowedGroups: tool.allowed_groups ?? ['*'],
+    dangerous: tool.dangerous === true,
+    enabled: tool.enabled !== false,
+    parametersJson: toEditableJson(tool.parameters),
+    formJson: toEditableJson(tool.form),
+    execKind: kind,
+    handler: typeof execution.handler === 'string' ? execution.handler : '',
+    webUrl: typeof execution.url === 'string' ? execution.url : '',
+    distOwner: typeof source.owner === 'string' ? source.owner : '',
+    distRepo: typeof source.repo === 'string' ? source.repo : '',
+    distVersion: typeof distribution.version === 'string' ? distribution.version : '',
+    distSha256: typeof distribution.package_sha256 === 'string' ? distribution.package_sha256 : '',
+    distLauncher: typeof distribution.launcher === 'string' ? distribution.launcher : '',
+    distRuntime: typeof distribution.runtime === 'string' ? distribution.runtime : '',
+    distHostLauncher:
+      typeof distribution.host_launcher === 'string' ? distribution.host_launcher : '',
+    distHostRootHints: hostHints.join('\n'),
+    distInstallScript:
+      typeof distribution.install_script === 'string' ? distribution.install_script : '',
+    distUninstallScript:
+      typeof distribution.uninstall_script === 'string' ? distribution.uninstall_script : '',
+    timeout: String(tool.timeout_seconds ?? 60),
+    renderer: (tool.result?.renderer as string | undefined) ?? 'json',
+    resultConfigJson: toEditableJson((tool.result as Record<string, unknown>)?.config),
+    redactParams: (((tool.audit as Record<string, unknown>)?.redact_params as string[]) ?? []).join(
+      ', ',
+    ),
+  };
+}
diff --git a/src/components/tools/ToolGroupEditDialog.tsx b/src/components/tools/ToolGroupEditDialog.tsx
new file mode 100644
index 00000000..a716766c
--- /dev/null
+++ b/src/components/tools/ToolGroupEditDialog.tsx
@@ -0,0 +1,202 @@
+import { useEffect, useState } from 'react';
+import type * as t from '@/types';
+import { cn } from '@/utils';
+import { FormDialog } from '@/components/shared';
+import { useLocalize } from '@/hooks';
+
+/** 组名：1..64 个非空白字符（2.17.0 放宽，允许中文显示组名）。 */
+const NAME_RE = /^[^|\s]{1,64}$/;
+/** 常用 Nextcloud 角色组；"*"=全部。 */
+const KNOWN_GROUPS = ['team-manager', 'team-editor', 'team-viewer'];
+
+/** Create / edit a display group (2.17.0): metadata + the group's visibility
+ * domains. Name is only settable at creation. An empty allowed_groups list
+ * means "no restriction" — every logged-in user sees the group's tools. */
+export function ToolGroupEditDialog({
+  open,
+  group,
+  saving,
+  error,
+  onSubmit,
+  onClose,
+}: t.ToolGroupEditDialogProps) {
+  const localize = useLocalize();
+  const isEdit = group !== null;
+  const [name, setName] = useState('');
+  const [displayName, setDisplayName] = useState('');
+  const [description, setDescription] = useState('');
+  const [sortOrder, setSortOrder] = useState('0');
+  const [allowedGroups, setAllowedGroups] = useState<string[]>([]);
+  const [customGroup, setCustomGroup] = useState('');
+  const [clientError, setClientError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (open) {
+      setName(group?.name ?? '');
+      setDisplayName(group?.display_name ?? '');
+      setDescription(group?.description ?? '');
+      setSortOrder(String(group?.sort_order ?? 0));
+      setAllowedGroups(group?.allowed_groups ?? []);
+      setCustomGroup('');
+      setClientError(null);
+    }
+  }, [open, group]);
+
+  const chipNames = [...new Set(['*', ...KNOWN_GROUPS, ...allowedGroups.filter((g) => g !== '*')])];
+
+  const toggleGroup = (name: string) =>
+    setAllowedGroups((prev) =>
+      prev.includes(name) ? prev.filter((g) => g !== name) : [...prev, name],
+    );
+
+  const addCustomGroup = () => {
+    const next = customGroup.trim();
+    if (next && !allowedGroups.includes(next)) {
+      setAllowedGroups((prev) => [...prev, next]);
+    }
+    setCustomGroup('');
+  };
+
+  const handleSubmit = () => {
+    setClientError(null);
+    if (!isEdit && !NAME_RE.test(name.trim())) {
+      setClientError(localize('com_tools_group_err_name'));
+      return;
+    }
+    onSubmit({
+      ...(isEdit ? {} : { name: name.trim() }),
+      display_name: displayName.trim(),
+      description: description.trim(),
+      sort_order: Number(sortOrder) || 0,
+      allowed_groups: allowedGroups,
+    });
+  };
+
+  return (
+    <FormDialog
+      open={open}
+      title={localize(isEdit ? 'com_tools_group_edit_title' : 'com_tools_group_add_title')}
+      submitLabel={localize(isEdit ? 'com_tools_save' : 'com_tools_create')}
+      saving={saving}
+      error={clientError ?? error}
+      onSubmit={handleSubmit}
+      onClose={onClose}
+    >
+      <div className="flex flex-col gap-4 text-sm">
+        {isEdit ? (
+          <div>
+            <label className="mb-1 block font-medium" htmlFor="group-name">
+              {localize('com_tools_group_field_name')}
+            </label>
+            <code className="config-input-mono block w-full rounded-md border border-(--cui-color-stroke-default) bg-(--cui-color-background-muted) px-2.5 py-1.5 text-xs">
+              {group.name}
+            </code>
+          </div>
+        ) : (
+          <div>
+            <label className="mb-1 block font-medium" htmlFor="group-name">
+              {localize('com_tools_group_field_name')}
+            </label>
+            <input
+              id="group-name"
+              className="config-input w-full"
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+              placeholder="spatial"
+            />
+            <p className="mt-1 text-xs text-(--cui-color-text-muted)">
+              {localize('com_tools_group_name_hint')}
+            </p>
+          </div>
+        )}
+        <div>
+          <label className="mb-1 block font-medium" htmlFor="group-display">
+            {localize('com_tools_group_field_display_name')}
+          </label>
+          <input
+            id="group-display"
+            className="config-input w-full"
+            value={displayName}
+            onChange={(e) => setDisplayName(e.target.value)}
+          />
+        </div>
+        <div>
+          <label className="mb-1 block font-medium" htmlFor="group-desc">
+            {localize('com_tools_group_field_description')}
+          </label>
+          <textarea
+            id="group-desc"
+            className="config-input min-h-16 w-full resize-y"
+            value={description}
+            onChange={(e) => setDescription(e.target.value)}
+          />
+        </div>
+        <div>
+          <label className="mb-1 block font-medium" htmlFor="group-sort">
+            {localize('com_tools_group_field_sort_order')}
+          </label>
+          <input
+            id="group-sort"
+            type="number"
+            className="config-input w-32"
+            value={sortOrder}
+            onChange={(e) => setSortOrder(e.target.value)}
+          />
+          <p className="mt-1 text-xs text-(--cui-color-text-muted)">
+            {localize('com_tools_group_sort_hint')}
+          </p>
+        </div>
+        <div>
+          <span className="mb-1 block font-medium">
+            {localize('com_tools_group_allowed_groups')}
+          </span>
+          <div className="flex flex-wrap gap-2">
+            {chipNames.map((name) => {
+              const active = allowedGroups.includes(name);
+              return (
+                <button
+                  key={name}
+                  type="button"
+                  aria-pressed={active}
+                  onClick={() => toggleGroup(name)}
+                  className={cn(
+                    'rounded-full border px-3 py-1 text-xs transition-colors',
+                    active
+                      ? 'border-(--cui-color-accent-primary) bg-(--cui-color-accent-primary-muted) text-(--cui-color-text-default)'
+                      : 'border-(--cui-color-stroke-default) text-(--cui-color-text-muted) hover:bg-(--cui-color-background-hover)',
+                  )}
+                >
+                  {name === '*' ? localize('com_tools_all_groups') : name}
+                </button>
+              );
+            })}
+          </div>
+          <div className="mt-2 flex gap-2">
+            <input
+              className="config-input w-full max-w-48"
+              value={customGroup}
+              placeholder={localize('com_services_group_custom_placeholder')}
+              onChange={(e) => setCustomGroup(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter') {
+                  e.preventDefault();
+                  addCustomGroup();
+                }
+              }}
+            />
+            <button
+              type="button"
+              className="shrink-0 rounded-lg border border-(--cui-color-stroke-default) px-3 py-1 text-xs transition-colors hover:bg-(--cui-color-background-hover)"
+              onClick={addCustomGroup}
+            >
+              {localize('com_services_group_add')}
+            </button>
+          </div>
+          <p className="mt-1 text-xs text-(--cui-color-text-muted)">
+            {localize('com_tools_group_allowed_hint')}
+          </p>
+        </div>
+      </div>
+    </FormDialog>
+  );
+}
diff --git a/src/components/tools/ToolGroupsTab.tsx b/src/components/tools/ToolGroupsTab.tsx
new file mode 100644
index 00000000..e89957de
--- /dev/null
+++ b/src/components/tools/ToolGroupsTab.tsx
@@ -0,0 +1,767 @@
+import { useEffect, useMemo, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Dialog, Icon } from '@clickhouse/click-ui';
+import {
+  DndContext,
+  PointerSensor,
+  closestCenter,
+  closestCorners,
+  useDroppable,
+  KeyboardSensor,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+  type DragOverEvent,
+} from '@dnd-kit/core';
+import {
+  SortableContext,
+  arrayMove,
+  rectSortingStrategy,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable';
+import { CSS } from '@dnd-kit/utilities';
+import type { TerraVoxGroup, TerraVoxTool } from '@/server';
+import {
+  createToolGroupFn,
+  deleteToolGroupFn,
+  toolGroupsQueryOptions,
+  toolsQueryOptions,
+  updateToolFn,
+  updateToolGroupFn,
+} from '@/server';
+import { EmptyState, InlineAction, LoadingState, SearchInput } from '@/components/shared';
+import { ConfirmDialog } from '@/components/access';
+import { cn } from '@/utils';
+import { useLocalize } from '@/hooks';
+import { ToolGroupEditDialog } from './ToolGroupEditDialog';
+
+const TAG_STYLE =
+  'rounded-full border border-(--cui-color-stroke-default) px-2 py-0.5 text-xs text-(--cui-color-text-muted)';
+const IMPLICIT_STYLE =
+  'rounded-full bg-(--cui-color-background-muted) px-2 py-0.5 text-xs text-(--cui-color-text-muted)';
+
+/**
+ * Group cards: each group is a tool_id namespace. Explicit groups carry admin
+ * metadata; implicit ones exist only because tools with that prefix exist —
+ * editing one promotes it to explicit (upsert on the gateway), deleting is
+ * blocked while any tool still lives in the namespace.
+ *
+ * 排序（2.22.0，dnd-kit）：显式分组卡片拖拽调整先后（松手落库 sort_order）；
+ * 卡片 ☰ 打开分组工具详情——双列表并排拖拽（左=未加入、右=组内），跨列拖拽
+ * 即添加/移除，右列内拖拽即组内排序（display_order）。
+ */
+export function ToolGroupsTab() {
+  const localize = useLocalize();
+  const queryClient = useQueryClient();
+  const [editOpen, setEditOpen] = useState(false);
+  const [editing, setEditing] = useState<TerraVoxGroup | null>(null);
+  const [deleteTarget, setDeleteTarget] = useState<TerraVoxGroup | null>(null);
+  const [mutError, setMutError] = useState<string | null>(null);
+  const [detailGroup, setDetailGroup] = useState<TerraVoxGroup | null>(null);
+
+  const groupsQuery = useQuery(toolGroupsQueryOptions);
+  const groups = groupsQuery.data ?? [];
+
+  const invalidate = () => {
+    void queryClient.invalidateQueries({ queryKey: ['terravox'] });
+  };
+
+  const saveMutation = useMutation({
+    mutationFn: async (input: {
+      name?: string;
+      display_name: string;
+      description: string;
+      sort_order: number;
+      allowed_groups: string[];
+    }) =>
+      input.name
+        ? createToolGroupFn({ data: input })
+        : updateToolGroupFn({
+            data: {
+              name: editing!.name,
+              display_name: input.display_name,
+              description: input.description,
+              sort_order: input.sort_order,
+              allowed_groups: input.allowed_groups,
+            },
+          }),
+    onSuccess: () => {
+      setEditOpen(false);
+      setEditing(null);
+      setMutError(null);
+      invalidate();
+    },
+    onError: () => {
+      /* dialog stays open and shows the error */
+    },
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: (name: string) => deleteToolGroupFn({ data: { name } }),
+    onSuccess: () => {
+      setDeleteTarget(null);
+      setMutError(null);
+      invalidate();
+    },
+    onError: (error: Error) => setMutError(error.message),
+  });
+
+  const explicitGroups = groups.filter((g) => g.explicit);
+  const implicitGroups = groups.filter((g) => !g.explicit);
+  /* 服务端已按 (sort_order, name) 排序；拖拽产生的本地顺序优先展示 */
+  const [localOrder, setLocalOrder] = useState<string[] | null>(null);
+  const [savingOrder, setSavingOrder] = useState(false);
+  const orderedExplicit = useMemo(
+    () =>
+      localOrder
+        ? explicitGroups
+            .slice()
+            .sort((a, b) => localOrder.indexOf(a.name) - localOrder.indexOf(b.name))
+        : explicitGroups,
+    [explicitGroups, localOrder],
+  );
+  const orderedGroups = [...orderedExplicit, ...implicitGroups];
+
+  /* 分组集合变化（增删/刷新）时丢弃本地顺序，回退服务端序 */
+  useEffect(() => {
+    const serverNames = groups.filter((g) => g.explicit).map((g) => g.name);
+    setLocalOrder((prev) =>
+      prev && (prev.length !== serverNames.length || prev.some((n) => !serverNames.includes(n)))
+        ? null
+        : prev,
+    );
+  }, [groups]);
+
+  const persistOrder = async (order: string[]) => {
+    const byName = new Map(explicitGroups.map((g) => [g.name, g]));
+    const changed = order
+      .map((name, idx) => ({ group: byName.get(name), sort_order: idx * 10 }))
+      .filter(
+        (x): x is { group: (typeof explicitGroups)[number]; sort_order: number } =>
+          !!x.group && x.group.sort_order !== x.sort_order,
+      );
+    if (changed.length === 0) {
+      return;
+    }
+    setSavingOrder(true);
+    setMutError(null);
+    try {
+      for (const { group, sort_order } of changed) {
+        await updateToolGroupFn({
+          data: {
+            name: group.name,
+            display_name: group.display_name,
+            description: group.description,
+            sort_order,
+            allowed_groups: group.allowed_groups,
+          },
+        });
+      }
+      invalidate();
+    } catch (error) {
+      setMutError((error as Error).message);
+    } finally {
+      setSavingOrder(false);
+    }
+  };
+
+  const cardSensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 6 } }),
+  );
+
+  const onCardDragEnd = ({ active, over }: DragEndEvent) => {
+    if (!over || active.id === over.id) {
+      return;
+    }
+    const base = orderedExplicit.map((g) => g.name);
+    const from = base.indexOf(String(active.id));
+    const to = base.indexOf(String(over.id));
+    if (from < 0 || to < 0) {
+      return;
+    }
+    const next = arrayMove(base, from, to);
+    setLocalOrder(next);
+    void persistOrder(next);
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-wrap items-center gap-3">
+        <p className="text-xs text-(--cui-color-text-muted)">{localize('com_tools_groups_hint')}</p>
+        <button
+          type="button"
+          onClick={() => {
+            setEditing(null);
+            setEditOpen(true);
+          }}
+          className="ms-auto flex items-center gap-1.5 rounded-lg bg-(--cui-color-accent-primary) px-3 py-1.5 text-sm font-medium text-white transition-colors hover:opacity-90"
+        >
+          <Icon name="plus" size="sm" />
+          {localize('com_tools_group_add_button')}
+        </button>
+      </div>
+
+      {mutError && (
+        <p role="alert" className="text-sm text-(--cui-color-text-danger)">
+          {mutError}
+        </p>
+      )}
+
+      {groupsQuery.isLoading && <LoadingState />}
+      {groupsQuery.isError && (
+        <EmptyState
+          message={(groupsQuery.error as Error)?.message ?? localize('com_tools_retry_later')}
+        />
+      )}
+      {!groupsQuery.isLoading && !groupsQuery.isError && groups.length === 0 && (
+        <EmptyState message={localize('com_tools_groups_empty')} />
+      )}
+
+      {savingOrder && (
+        <p className="text-xs text-(--cui-color-text-muted)">
+          {localize('com_tools_group_order_saving')}
+        </p>
+      )}
+      <DndContext
+        sensors={cardSensors}
+        collisionDetection={closestCenter}
+        onDragEnd={onCardDragEnd}
+      >
+        <SortableContext items={orderedExplicit.map((g) => g.name)} strategy={rectSortingStrategy}>
+          <div className="grid grid-cols-1 gap-3 md:grid-cols-2 xl:grid-cols-3">
+            {orderedGroups.map((group) => (
+              <SortableGroupCard
+                key={group.name}
+                group={group}
+                dragging={false}
+                onManage={() => setDetailGroup(group)}
+                onEdit={() => {
+                  setEditing(group);
+                  setEditOpen(true);
+                }}
+                onDelete={() => setDeleteTarget(group)}
+              />
+            ))}
+          </div>
+        </SortableContext>
+      </DndContext>
+
+      {detailGroup && <GroupToolsDialog group={detailGroup} onClose={() => setDetailGroup(null)} />}
+
+      <ToolGroupEditDialog
+        open={editOpen}
+        group={editing}
+        saving={saveMutation.isPending}
+        error={saveMutation.isError ? (saveMutation.error as Error).message : undefined}
+        onSubmit={(input) => saveMutation.mutate(input)}
+        onClose={() => {
+          setEditOpen(false);
+          setEditing(null);
+        }}
+      />
+
+      <ConfirmDialog
+        open={deleteTarget !== null}
+        title={localize('com_tools_group_delete_title')}
+        description={
+          (deleteTarget?.tool_count ?? 0) > 0
+            ? localize('com_tools_group_delete_not_empty', { count: deleteTarget?.tool_count ?? 0 })
+            : localize('com_tools_group_delete_desc', { name: deleteTarget?.name ?? '' })
+        }
+        confirmLabel={localize('com_ui_delete')}
+        saving={deleteMutation.isPending}
+        error={deleteMutation.isError ? (deleteMutation.error as Error).message : undefined}
+        onConfirm={() => deleteTarget && deleteMutation.mutate(deleteTarget.name)}
+        onCancel={() => setDeleteTarget(null)}
+      />
+    </div>
+  );
+}
+
+/** 显式分组卡：dnd-kit sortable（网格策略）；隐式分组 plain 渲染、固定沉底。 */
+function SortableGroupCard({
+  group,
+  onManage,
+  onEdit,
+  onDelete,
+}: {
+  group: TerraVoxGroup;
+  onManage: () => void;
+  onEdit: () => void;
+  onDelete: () => void;
+}) {
+  const localize = useLocalize();
+  const sortable = useSortable({ id: group.name, disabled: !group.explicit });
+  const style = {
+    transform: CSS.Transform.toString(sortable.transform),
+    transition: sortable.transition,
+  };
+  return (
+    <div
+      ref={sortable.setNodeRef}
+      style={style}
+      className={cn(
+        'group flex flex-col gap-2 rounded-lg border border-(--cui-color-stroke-default) p-4',
+        sortable.isDragging && 'border-(--cui-color-accent-primary) opacity-60',
+      )}
+    >
+      <div className="flex items-start justify-between gap-2">
+        <div className="flex min-w-0 items-start gap-1">
+          {group.explicit && (
+            <span
+              title={localize('com_tools_drag_handle')}
+              aria-label={localize('com_tools_drag_handle')}
+              {...sortable.listeners}
+              {...sortable.attributes}
+              className="mt-0.5 shrink-0 cursor-grab touch-none px-0.5 text-(--cui-color-text-disabled) opacity-0 transition-opacity select-none group-hover:opacity-100 active:cursor-grabbing"
+            >
+              ⠿
+            </span>
+          )}
+          <div className="min-w-0">
+            <div className="flex items-center gap-2">
+              <span className="truncate font-medium text-(--cui-color-text-default)">
+                {group.display_name || group.name}
+              </span>
+              {!group.explicit && (
+                <span className={IMPLICIT_STYLE}>{localize('com_tools_group_implicit')}</span>
+              )}
+            </div>
+            <code className="text-xs text-(--cui-color-text-muted)">{group.name}</code>
+          </div>
+        </div>
+        {/* 行内操作（2.19.0）：平铺按钮替代三点菜单；☰ = 分组工具详情（2.22.0） */}
+        <div className="flex shrink-0 items-center gap-1">
+          <InlineAction label={localize('com_tools_group_detail_manage')} onClick={onManage}>
+            ☰
+          </InlineAction>
+          <InlineAction label={localize('com_ui_edit')} onClick={onEdit}>
+            ✎
+          </InlineAction>
+          <InlineAction label={localize('com_ui_delete')} danger onClick={onDelete}>
+            ✕
+          </InlineAction>
+        </div>
+      </div>
+      {group.description && (
+        <p className="line-clamp-2 text-xs text-(--cui-color-text-muted)">{group.description}</p>
+      )}
+      {group.allowed_groups.length > 0 && (
+        <div className="flex flex-wrap gap-1">
+          {group.allowed_groups.map((name) => (
+            <span key={name} className={TAG_STYLE}>
+              {name === '*' ? localize('com_tools_all_groups') : name}
+            </span>
+          ))}
+        </div>
+      )}
+      <div className="mt-auto flex items-center gap-2 pt-1">
+        <span className={TAG_STYLE}>
+          {localize('com_tools_group_tool_count', { count: group.tool_count })}
+        </span>
+        <span className={TAG_STYLE}>
+          {localize('com_tools_group_sort', { order: group.sort_order })}
+        </span>
+      </div>
+    </div>
+  );
+}
+
+const LEFT = 'available';
+const RIGHT = 'members';
+/* 稳定空数组：data 未到时 `?? []` 的每轮新引用会让派生 useMemo 失效 →
+ * 同步 effect 无限 setState（Maximum update depth，实测崩整页） */
+const EMPTY_TOOLS: TerraVoxTool[] = [];
+
+/** 分组工具详情（2.22.0，dnd-kit 双列表）：左列=未加入分组的工具，右列=组内
+ * 工具（按 display_order）；跨列拖拽即添加/移除，右列内拖拽即排序。落库：
+ * 添加=设 display_group、移除=清 display_group+display_order、排序=display_order
+ * ×10 重建。改动即时落库并失效清单缓存。 */
+function GroupToolsDialog({ group, onClose }: { group: TerraVoxGroup; onClose: () => void }) {
+  const localize = useLocalize();
+  const queryClient = useQueryClient();
+  const toolsQuery = useQuery(toolsQueryOptions);
+  const [search, setSearch] = useState('');
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const tools = toolsQuery.data?.tools ?? EMPTY_TOOLS;
+  const byId = useMemo(() => new Map(tools.map((t) => [t.tool_id, t])), [tools]);
+
+  /* 服务端数据 → 两列初始内容（useMemo 派生；tools/byId 身份稳定时不重算，
+   * 拖拽进行中不发生 refetch，不会打断拖拽） */
+  const initialAvailable = useMemo(() => {
+    const available: string[] = [];
+    for (const tool of tools) {
+      if ((tool.display_group?.trim() || '') !== group.name) {
+        available.push(tool.tool_id);
+      }
+    }
+    available.sort(
+      (a, b) =>
+        (byId.get(a)?.display_name ?? '').localeCompare(byId.get(b)?.display_name ?? '') ||
+        a.localeCompare(b),
+    );
+    return available;
+  }, [tools, group.name, byId]);
+  const initialMembers = useMemo(() => {
+    const members: string[] = [];
+    for (const tool of tools) {
+      if ((tool.display_group?.trim() || '') === group.name) {
+        members.push(tool.tool_id);
+      }
+    }
+    members.sort(
+      (a, b) =>
+        (byId.get(a)?.display_order ?? Number.MAX_SAFE_INTEGER) -
+          (byId.get(b)?.display_order ?? Number.MAX_SAFE_INTEGER) || a.localeCompare(b),
+    );
+    return members;
+  }, [tools, group.name, byId]);
+  /* 拖拽改动的本地列状态：数据刷新（identity 变化）时从服务端重建 */
+  const [memberIds, setMemberIds] = useState<string[]>(initialMembers);
+  const [availableIds, setAvailableIds] = useState<string[]>(initialAvailable);
+  useEffect(() => {
+    setMemberIds(initialMembers);
+    setAvailableIds(initialAvailable);
+  }, [initialMembers, initialAvailable]);
+
+  const invalidate = () => {
+    void queryClient.invalidateQueries({ queryKey: ['terravox'] });
+  };
+
+  const commit = async () => {
+    setBusy(true);
+    setError(null);
+    try {
+      /* 移除：右列消失、服务端仍在本组 → 清 display_group + display_order */
+      for (const id of availableIds) {
+        const tool = byId.get(id);
+        if (tool && (tool.display_group?.trim() || '') === group.name) {
+          const manifest: Record<string, unknown> = { ...tool };
+          delete manifest.display_group;
+          delete manifest.display_order;
+          await updateToolFn({ data: { toolId: id, manifest } });
+        }
+      }
+      /* 添加 + 排序：右列成员统一重建 display_order = idx×10 */
+      for (let idx = 0; idx < memberIds.length; idx++) {
+        const tool = byId.get(memberIds[idx]);
+        if (!tool) {
+          continue;
+        }
+        const order = idx * 10;
+        if ((tool.display_group?.trim() || '') !== group.name || tool.display_order !== order) {
+          await updateToolFn({
+            data: {
+              toolId: tool.tool_id,
+              manifest: { ...tool, display_group: group.name, display_order: order },
+            },
+          });
+        }
+      }
+      invalidate();
+    } catch (err) {
+      setError((err as Error).message);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  );
+
+  const findContainer = (id: string): string | undefined => {
+    if (id === LEFT || id === RIGHT) {
+      return id;
+    }
+    if (memberIds.includes(id)) {
+      return RIGHT;
+    }
+    if (availableIds.includes(id)) {
+      return LEFT;
+    }
+    return undefined;
+  };
+
+  const onDragOver = ({ active, over }: DragOverEvent) => {
+    if (!over) {
+      return;
+    }
+    const from = findContainer(String(active.id));
+    const to = findContainer(String(over.id));
+    if (!from || !to || from === to) {
+      return;
+    }
+    /* 跨列：把 active.id 移到目标列（over 项之前/末尾）——官方多容器模式 */
+    const move = (ids: string[]) => ids.filter((id) => id !== String(active.id));
+    const overIdx =
+      to === RIGHT ? memberIds.indexOf(String(over.id)) : availableIds.indexOf(String(over.id));
+    if (from === RIGHT) {
+      setMemberIds(move(memberIds));
+      setAvailableIds((prev) => {
+        const next = prev.filter((id) => id !== String(active.id));
+        next.splice(overIdx < 0 ? next.length : overIdx, 0, String(active.id));
+        return next;
+      });
+    } else {
+      setAvailableIds(move(availableIds));
+      setMemberIds((prev) => {
+        const next = prev.filter((id) => id !== String(active.id));
+        next.splice(overIdx < 0 ? next.length : overIdx, 0, String(active.id));
+        return next;
+      });
+    }
+  };
+
+  const onDragEnd = ({ active, over }: DragEndEvent) => {
+    if (!over) {
+      return;
+    }
+    const container = findContainer(String(active.id));
+    if (!container || findContainer(String(over.id)) !== container) {
+      return;
+    }
+    if (container === RIGHT) {
+      const from = memberIds.indexOf(String(active.id));
+      const to = memberIds.indexOf(String(over.id));
+      if (from >= 0 && to >= 0 && from !== to) {
+        setMemberIds(arrayMove(memberIds, from, to));
+      }
+    }
+    void commit();
+  };
+
+  const q = search.trim().toLowerCase();
+  const visibleAvailable = availableIds.filter((id) => {
+    const tool = byId.get(id);
+    if (!tool) {
+      return false;
+    }
+    return (
+      !q ||
+      tool.display_name.toLowerCase().includes(q) ||
+      tool.tool_id.toLowerCase().includes(q) ||
+      (tool.display_group ?? '').toLowerCase().includes(q)
+    );
+  });
+
+  return (
+    <Dialog
+      open
+      onOpenChange={(isOpen) => {
+        if (!isOpen) onClose();
+      }}
+    >
+      <Dialog.Content
+        onInteractOutside={(event) => event.preventDefault()}
+        title={`${localize('com_tools_group_detail_manage')} · ${group.display_name || group.name}`}
+        showClose
+        className="modal-frost max-w-3xl!"
+      >
+        <div className="flex flex-col gap-3 text-sm">
+          {error && (
+            <p role="alert" className="text-sm text-(--cui-color-text-danger)">
+              {error}
+            </p>
+          )}
+          {toolsQuery.isLoading && <LoadingState />}
+          {!toolsQuery.isLoading && (
+            // 双列表跨列=添加/移除：closestCorners 按被拖项矩形算碰撞，
+            // 不能加 restrictToVerticalAxis（锁轴即锁死跨列，实测）
+            <DndContext
+              sensors={sensors}
+              collisionDetection={closestCorners}
+              onDragOver={onDragOver}
+              onDragEnd={onDragEnd}
+            >
+              <div className="grid grid-cols-2 gap-3">
+                <ListPane
+                  containerId={LEFT}
+                  title={localize('com_tools_group_detail_left')}
+                  count={availableIds.length}
+                >
+                  <SortableContext items={visibleAvailable} strategy={verticalListSortingStrategy}>
+                    {visibleAvailable.map((id) => (
+                      <PickableToolRow key={id} tool={byId.get(id) as TerraVoxTool} />
+                    ))}
+                  </SortableContext>
+                  {visibleAvailable.length === 0 && (
+                    <p className="p-3 text-center text-xs text-(--cui-color-text-muted)">—</p>
+                  )}
+                </ListPane>
+                <ListPane
+                  containerId={RIGHT}
+                  title={localize('com_tools_group_detail_right')}
+                  count={memberIds.length}
+                >
+                  <SortableContext items={memberIds} strategy={verticalListSortingStrategy}>
+                    {memberIds.map((id) => {
+                      const tool = byId.get(id);
+                      return tool ? (
+                        <MemberToolRow
+                          key={id}
+                          tool={tool}
+                          busy={busy}
+                          onRemove={() => {
+                            setMemberIds((prev) => prev.filter((x) => x !== id));
+                            setAvailableIds((prev) => [...prev, id]);
+                            void commit();
+                          }}
+                        />
+                      ) : null;
+                    })}
+                  </SortableContext>
+                  {memberIds.length === 0 && (
+                    <p className="p-3 text-center text-xs text-(--cui-color-text-muted)">
+                      {localize('com_tools_group_detail_empty')}
+                    </p>
+                  )}
+                </ListPane>
+              </div>
+            </DndContext>
+          )}
+
+          <div className="flex items-center justify-between gap-2">
+            <SearchInput
+              value={search}
+              onChange={setSearch}
+              placeholder={localize('com_tools_group_detail_add_ph')}
+              ariaLabel={localize('com_tools_group_detail_add_ph')}
+              className="w-full"
+            />
+            <button
+              type="button"
+              onClick={onClose}
+              disabled={busy}
+              className="shrink-0 rounded-lg border border-(--cui-color-stroke-default) px-3 py-1.5 text-sm transition-colors hover:bg-(--cui-color-background-hover) disabled:opacity-50"
+            >
+              {localize('com_ui_close')}
+            </button>
+          </div>
+        </div>
+      </Dialog.Content>
+    </Dialog>
+  );
+}
+
+/** 双列表的列容器：droppable（空列也能接收拖入），悬停拖拽时高亮边框。 */
+function ListPane({
+  containerId,
+  title,
+  count,
+  children,
+}: {
+  containerId: string;
+  title: string;
+  count: number;
+  children: React.ReactNode;
+}) {
+  const localize = useLocalize();
+  const { setNodeRef, isOver } = useDroppable({ id: containerId });
+  return (
+    <div className="flex min-w-0 flex-col gap-1">
+      <p className="text-xs font-semibold text-(--cui-color-text-muted) uppercase">
+        {title}
+        <span className="ms-1.5 font-normal">{localize('com_tools_count', { count })}</span>
+      </p>
+      <div
+        ref={setNodeRef}
+        className={cn(
+          'flex max-h-[46vh] min-h-40 flex-col gap-1 overflow-y-auto rounded-lg border p-1 transition-colors',
+          isOver
+            ? 'border-(--cui-color-accent-primary) bg-(--cui-color-background-hover)'
+            : 'border-(--cui-color-stroke-default)',
+        )}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}
+
+/** 左列行：跨列拖到右列 = 添加。 */
+function PickableToolRow({ tool }: { tool: TerraVoxTool }) {
+  const localize = useLocalize();
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+    id: tool.tool_id,
+    data: { container: LEFT },
+  });
+  return (
+    <div
+      ref={setNodeRef}
+      style={{ transform: CSS.Transform.toString(transform), transition }}
+      className={cn(
+        'flex items-center gap-2 rounded-md border border-(--cui-color-stroke-default) px-2 py-1.5 text-xs',
+        isDragging && 'opacity-40',
+      )}
+    >
+      <span
+        {...attributes}
+        {...listeners}
+        title={localize('com_tools_drag_handle')}
+        className="shrink-0 cursor-grab touch-none px-0.5 text-(--cui-color-text-disabled) select-none active:cursor-grabbing"
+      >
+        ⠿
+      </span>
+      <span className="min-w-0 flex-1 truncate text-(--cui-color-text-default)">
+        {tool.display_name}
+      </span>
+      <code className="min-w-0 flex-1 truncate text-(--cui-color-text-muted)">{tool.tool_id}</code>
+      <span className="shrink-0 text-xs text-(--cui-color-text-muted)">
+        {tool.display_group?.trim() ? tool.display_group : localize('com_tools_group_ungrouped')}
+      </span>
+    </div>
+  );
+}
+
+/** 右列行：组内成员——列内拖拽排序；✕ 快捷移除（同拖回左列）。 */
+function MemberToolRow({
+  tool,
+  busy,
+  onRemove,
+}: {
+  tool: TerraVoxTool;
+  busy: boolean;
+  onRemove: () => void;
+}) {
+  const localize = useLocalize();
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+    id: tool.tool_id,
+    data: { container: RIGHT },
+  });
+  return (
+    <div
+      ref={setNodeRef}
+      style={{ transform: CSS.Transform.toString(transform), transition }}
+      className={cn(
+        'flex items-center gap-2 rounded-md border border-(--cui-color-stroke-default) px-2 py-1.5 text-xs',
+        isDragging && 'opacity-40',
+      )}
+    >
+      <span
+        {...attributes}
+        {...listeners}
+        title={localize('com_tools_drag_handle')}
+        className="shrink-0 cursor-grab touch-none px-0.5 text-(--cui-color-text-disabled) select-none active:cursor-grabbing"
+      >
+        ⠿
+      </span>
+      <span className="min-w-0 flex-1 truncate font-medium text-(--cui-color-text-default)">
+        {tool.display_name}
+      </span>
+      <code className="min-w-0 flex-1 truncate text-(--cui-color-text-muted)">{tool.tool_id}</code>
+      <InlineAction
+        label={localize('com_tools_group_detail_remove')}
+        danger
+        disabled={busy}
+        onClick={onRemove}
+      >
+        ✕
+      </InlineAction>
+    </div>
+  );
+}
diff --git a/src/components/tools/ToolsPage.tsx b/src/components/tools/ToolsPage.tsx
new file mode 100644
index 00000000..20f9bb20
--- /dev/null
+++ b/src/components/tools/ToolsPage.tsx
@@ -0,0 +1,38 @@
+import { Tabs } from '@clickhouse/click-ui';
+import type * as t from '@/types';
+import { useLocalize } from '@/hooks';
+import { ToolCatalogTab } from './ToolCatalogTab';
+import { UsagePage } from '@/components/usage';
+import { ToolGroupsTab } from './ToolGroupsTab';
+
+/**
+ * Tool management surface. The page title lives in the top Header
+ * (ROUTE_TITLE_KEYS '/tools'); this component starts with the tab bar —
+ * 工具清单 (catalog CRUD + import)、工具分组 (namespace group metadata) and
+ * 使用统计 (run reports, moved here from its own sidebar route 2.16.0).
+ */
+export function ToolsPage({ activeTab, onTabChange }: t.ToolsPageProps) {
+  const localize = useLocalize();
+
+  return (
+    <div
+      role="region"
+      aria-label={localize('com_tools_title')}
+      className="flex min-h-0 flex-1 flex-col overflow-hidden px-4 pt-2"
+    >
+      <Tabs value={activeTab} onValueChange={onTabChange} ariaLabel={localize('com_tools_title')}>
+        <Tabs.TriggersList>
+          <Tabs.Trigger value="catalog">{localize('com_tools_tab_catalog')}</Tabs.Trigger>
+          <Tabs.Trigger value="groups">{localize('com_tools_tab_groups')}</Tabs.Trigger>
+          <Tabs.Trigger value="usage">{localize('com_tools_tab_usage')}</Tabs.Trigger>
+        </Tabs.TriggersList>
+      </Tabs>
+
+      <div className="flex min-h-0 flex-1 flex-col overflow-y-auto pt-4 pb-6">
+        {activeTab === 'catalog' && <ToolCatalogTab />}
+        {activeTab === 'groups' && <ToolGroupsTab />}
+        {activeTab === 'usage' && <UsagePage />}
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/tools/__tests__/ToolCatalogTab.realDnd.test.tsx b/src/components/tools/__tests__/ToolCatalogTab.realDnd.test.tsx
new file mode 100644
index 00000000..1885ca98
--- /dev/null
+++ b/src/components/tools/__tests__/ToolCatalogTab.realDnd.test.tsx
@@ -0,0 +1,77 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ToolCatalogTab } from '../ToolCatalogTab';
+
+/* 用真实 dnd-kit（importOriginal）渲染 ToolCatalogTab，复现浏览器端 /tools 路由崩溃。 */
+
+vi.mock('@dnd-kit/core', async (importOriginal) => await importOriginal());
+vi.mock('@dnd-kit/modifiers', async (importOriginal) => await importOriginal());
+vi.mock('@dnd-kit/sortable', async (importOriginal) => await importOriginal());
+vi.mock('@dnd-kit/utilities', async (importOriginal) => await importOriginal());
+
+const mocks = vi.hoisted(() => ({
+  state: { tools: [] as Array<Record<string, unknown>> },
+}));
+
+vi.mock('@/hooks/useLocalize', () => {
+  const localize = (key: string) => key;
+  return { default: () => localize, useLocalize: () => localize };
+});
+
+vi.mock('@/server', () => ({
+  toolsQueryOptions: {
+    queryKey: ['t', 'tools'],
+    queryFn: () => Promise.resolve({ tools: mocks.state.tools, groups: [] }),
+  },
+  toolGroupsQueryOptions: { queryKey: ['t', 'groups'], queryFn: () => Promise.resolve([]) },
+  handlersQueryOptions: { queryKey: ['t', 'handlers'], queryFn: () => Promise.resolve([]) },
+  pendingUpdatesQueryOptions: {
+    queryKey: ['t', 'pending'],
+    queryFn: () => Promise.resolve([]),
+  },
+  createToolFn: vi.fn(),
+  updateToolFn: vi.fn(),
+  deleteToolFn: vi.fn(),
+  toggleToolFn: vi.fn(),
+  giteaCheckRepoFn: vi.fn(),
+  giteaReposQueryOptions: () => ({
+    queryKey: ['t', 'gitea'],
+    queryFn: () => Promise.resolve({ base_url: '', owners: [] }),
+  }),
+}));
+
+vi.mock('@/utils', () => ({
+  cn: (...parts: Array<string | false | null | undefined>) => parts.filter(Boolean).join(' '),
+  notifySuccess: vi.fn(),
+  notifyError: vi.fn(),
+}));
+
+const TOOLS = [
+  {
+    schema_version: 1,
+    tool_id: 'demo.echo',
+    version: '1.0.0',
+    display_name: '回声',
+    description: '',
+    expose: ['ui'],
+    allowed_groups: ['*'],
+    enabled: true,
+    dangerous: false,
+    display_group: 'demo',
+  },
+];
+
+describe('ToolCatalogTab with REAL dnd-kit', () => {
+  it('renders the catalog table without crashing', async () => {
+    mocks.state.tools = TOOLS;
+    const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    render(
+      <QueryClientProvider client={client}>
+        <ToolCatalogTab />
+      </QueryClientProvider>,
+    );
+    await screen.findByText('回声');
+    expect(screen.getByText('demo.echo')).toBeInTheDocument();
+  });
+});
diff --git a/src/components/tools/__tests__/ToolCatalogTab.test.tsx b/src/components/tools/__tests__/ToolCatalogTab.test.tsx
new file mode 100644
index 00000000..22c4605e
--- /dev/null
+++ b/src/components/tools/__tests__/ToolCatalogTab.test.tsx
@@ -0,0 +1,398 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, act } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ToolCatalogTab } from '../ToolCatalogTab';
+
+/* Mutable per-test state + fns — vi.hoisted keeps them usable inside the
+ * hoisted vi.mock factories below. */
+const mocks = vi.hoisted(() => ({
+  checkRepo: vi.fn(),
+  state: {
+    tools: [] as Array<Record<string, unknown>>,
+    pending: [] as Array<Record<string, unknown>>,
+    failPending: false,
+    hangTools: false,
+  },
+}));
+
+vi.mock('@/hooks/useLocalize', () => {
+  /* Interpolation params render space-joined so version transitions are
+   * assertable in the panel text. */
+  const localize = (key: string, params?: Record<string, unknown>) =>
+    params ? Object.values(params).join(' ') : key;
+  return { default: () => localize, useLocalize: () => localize };
+});
+
+vi.mock('@/server', () => ({
+  toolsQueryOptions: {
+    queryKey: ['t', 'tools'],
+    queryFn: () =>
+      mocks.state.hangTools
+        ? new Promise(() => {})
+        : Promise.resolve({ tools: mocks.state.tools, groups: [] }),
+  },
+  toolGroupsQueryOptions: { queryKey: ['t', 'groups'], queryFn: () => Promise.resolve([]) },
+  handlersQueryOptions: { queryKey: ['t', 'handlers'], queryFn: () => Promise.resolve([]) },
+  pendingUpdatesQueryOptions: {
+    queryKey: ['t', 'pending'],
+    queryFn: () =>
+      mocks.state.failPending
+        ? Promise.reject(new Error('pending boom'))
+        : Promise.resolve(mocks.state.pending),
+  },
+  giteaReposQueryOptions: (baseUrl: string) => ({
+    queryKey: ['t', 'gitea', baseUrl],
+    queryFn: () => Promise.resolve({ base_url: '', owners: [] }),
+  }),
+  createToolFn: vi.fn(),
+  updateToolFn: vi.fn(),
+  deleteToolFn: vi.fn(),
+  toggleToolFn: vi.fn(),
+  giteaCheckRepoFn: mocks.checkRepo,
+}));
+
+vi.mock('@/components/tools/ToolEditDialog', () => ({
+  ToolEditDialog: ({ open, tool }: { open: boolean; tool: unknown }) =>
+    open ? <div data-testid="edit-dialog">{JSON.stringify(tool)}</div> : null,
+}));
+
+vi.mock('@/components/tools/ImportToolsDialog', () => ({
+  ImportToolsDialog: () => null,
+}));
+
+/* Keep the real buildPrefill (the confirm flow reuses it); stub only the UI. */
+vi.mock('@/components/tools/GiteaImportDialog', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  GiteaImportDialog: () => null,
+}));
+
+vi.mock('@/components/access', () => ({
+  ConfirmDialog: () => null,
+}));
+
+vi.mock('@/components/shared', () => ({
+  EmptyState: ({ message }: { message?: string }) => <div>{message}</div>,
+  InlineAction: ({ label, onClick }: { label: string; onClick?: () => void }) => (
+    <button aria-label={label} onClick={onClick} />
+  ),
+  LoadingState: () => <div>loading</div>,
+  SearchInput: () => <input aria-label="search" />,
+  StatusToggle: () => <div />,
+}));
+
+interface MockButtonProps {
+  label?: string;
+  disabled?: boolean;
+  onClick?: () => void;
+}
+
+vi.mock('@clickhouse/click-ui', () => ({
+  Icon: () => <span />,
+  Button: ({ label, disabled, onClick }: MockButtonProps) => (
+    <button type="button" disabled={disabled} onClick={onClick}>
+      {label}
+    </button>
+  ),
+  Dialog: Object.assign(({ children }: { children: React.ReactNode }) => <div>{children}</div>, {
+    Content: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  }),
+  Select: Object.assign(({ children }: { children: React.ReactNode }) => <div>{children}</div>, {
+    Item: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
+  }),
+  Checkbox: ({
+    label,
+    checked,
+    disabled,
+    onCheckedChange,
+  }: {
+    label?: string;
+    checked?: boolean;
+    disabled?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+  }) => (
+    <input
+      type="checkbox"
+      checked={checked ?? false}
+      disabled={disabled}
+      onChange={(e) => onCheckedChange?.(e.target.checked)}
+      aria-label={label}
+    />
+  ),
+}));
+
+/* dnd-kit 在 vitest 的 CJS 互操作下命名导出为 undefined——桩化（测试不模拟拖拽） */
+vi.mock('@dnd-kit/core', () => ({
+  DndContext: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  PointerSensor: class {},
+  KeyboardSensor: class {},
+  closestCenter: {},
+  useSensor: () => undefined,
+  useSensors: () => [],
+}));
+vi.mock('@dnd-kit/sortable', () => ({
+  SortableContext: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  arrayMove: (arr: unknown[], from: number, to: number) => {
+    const next = [...arr];
+    const [moved] = next.splice(from, 1);
+    next.splice(to, 0, moved);
+    return next;
+  },
+  sortableKeyboardCoordinates: () => undefined,
+  useSortable: () => ({
+    attributes: {},
+    listeners: undefined,
+    setNodeRef: () => undefined,
+    transform: null,
+    transition: undefined,
+    isDragging: false,
+  }),
+  verticalListSortingStrategy: undefined,
+}));
+vi.mock('@dnd-kit/utilities', () => ({
+  CSS: { Transform: { toString: () => undefined } },
+}));
+
+vi.mock('@/utils', () => ({
+  cn: (...parts: Array<string | false | null | undefined>) => parts.filter(Boolean).join(' '),
+  notifySuccess: vi.fn(),
+  notifyError: vi.fn(),
+}));
+
+const EXISTING: Record<string, unknown> = {
+  schema_version: 1,
+  tool_id: 'wangjianbo.toolsdemo',
+  version: '1.0.0',
+  enabled: true,
+  display_name: 'Tools Demo',
+  description: 'approved description',
+  expose: ['ui'],
+  allowed_groups: ['team-editor'],
+  dangerous: true,
+  parameters: { type: 'object', properties: { old: { type: 'string' } } },
+  result: { renderer: 'table', config: { columns: ['a'] } },
+  execution: {
+    kind: 'desktop',
+    distribution: {
+      source: { type: 'gitea_release', owner: 'wangjianbo', repo: 'toolsdemo' },
+      version: '1.0.0',
+      package_sha256: 'a'.repeat(64),
+      launcher: 'main.py',
+      runtime: 'self-contained',
+    },
+  },
+};
+
+const PENDING_UPDATE: Record<string, unknown> = {
+  tool_id: 'wangjianbo.toolsdemo',
+  display_name: 'Tools Demo',
+  owner: 'wangjianbo',
+  repo: 'toolsdemo',
+  current_version: '1.0.0',
+  package: { version: '1.0.1', size: 753, updated_at: '2026-09-28T08:52:55Z' },
+};
+
+/* 2026-09-28：gateway 将显式版本与 tag 不一致升为硬项 error（Toolhost 安装侧
+ * 同样硬校验 version == tag）—— 确认流程必须挡住，不能等安装时才失败 */
+const MISMATCH_ERROR = {
+  key: 'version_mismatch',
+  level: 'error',
+  message: 'tool.json version 1.0.0 != release tag v1.0.1',
+} as const;
+
+const CHECK_RESULT = {
+  owner: 'wangjianbo',
+  repo: 'toolsdemo',
+  release: { tag: 'v1.0.1' },
+  tool_json: {
+    display_name: 'Tools Demo',
+    version: '1.0.1',
+    parameters: { type: 'object', properties: { query: { type: 'string' } } },
+  },
+  checks: [
+    { key: 'launcher_missing', level: 'warn', message: 'launcher not defined in tool.json' },
+  ],
+  installable: true,
+};
+
+/* tool.json 只有版本号，其余全缺 —— 确认时已批准值必须保留 */
+const CHECK_RESULT_SPARSE = {
+  owner: 'wangjianbo',
+  repo: 'toolsdemo',
+  release: { tag: 'v1.0.1' },
+  tool_json: { version: '1.0.1' },
+  checks: [],
+  installable: false,
+};
+
+const CHECK_RESULT_ERROR = {
+  owner: 'wangjianbo',
+  repo: 'toolsdemo',
+  release: { tag: 'v1.0.1' },
+  checks: [
+    { key: 'zip_asset_count', level: 'error', message: 'expected exactly 1 zip asset, found 2' },
+  ],
+  installable: false,
+};
+
+/* tag 与 tool.json 版本不一致（用户场景 2026-09-28：tag v1.0.1 指向 tool.json
+ * 仍是 1.0.0 的 commit）—— Toolhost 会拒装，确认必须在此挡住 */
+const CHECK_RESULT_MISMATCH = {
+  owner: 'wangjianbo',
+  repo: 'toolsdemo',
+  release: { tag: 'v1.0.1' },
+  tool_json: { version: '1.0.0' },
+  checks: [MISMATCH_ERROR],
+  installable: false,
+};
+
+const renderTab = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ToolCatalogTab />
+    </QueryClientProvider>,
+  );
+};
+
+describe('ToolCatalogTab pending updates', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.state.tools = [];
+    mocks.state.pending = [];
+    mocks.state.failPending = false;
+    mocks.state.hangTools = false;
+  });
+
+  it('shows the pending section with the version transition; hidden with nothing to confirm', async () => {
+    mocks.state.tools = [EXISTING];
+    mocks.state.pending = [PENDING_UPDATE];
+    const first = renderTab();
+
+    const section = await screen.findByRole('region', { name: 'com_tools_pending_title' });
+    expect(section.textContent).toContain('v1.0.0');
+    expect(section.textContent).toContain('v1.0.1');
+    expect(screen.getByRole('button', { name: 'com_tools_pending_confirm' })).toBeEnabled();
+
+    first.unmount();
+    mocks.state.pending = [];
+    renderTab();
+    await screen.findByText('Tools Demo');
+    expect(screen.queryByRole('region', { name: 'com_tools_pending_title' })).toBeNull();
+  });
+
+  it('confirm merges repo fields at the pending target version and shows check warns', async () => {
+    /* 2026-09-28 regression: the confirmed version is the pending target (tag,
+     * the distribution identity) and repo-provided params win; soft warns stay
+     * visible in the pending panel without blocking. */
+    mocks.state.tools = [EXISTING];
+    mocks.state.pending = [PENDING_UPDATE];
+    mocks.checkRepo.mockResolvedValue(CHECK_RESULT);
+    renderTab();
+
+    await act(async () => {
+      fireEvent.click(await screen.findByRole('button', { name: 'com_tools_pending_confirm' }));
+    });
+    const dialog = await screen.findByTestId('edit-dialog');
+    expect(mocks.checkRepo).toHaveBeenCalledWith({
+      data: { owner: 'wangjianbo', repo: 'toolsdemo' },
+    });
+    expect(await screen.findByText(/launcher_missing/)).toBeInTheDocument();
+
+    const merged = JSON.parse(dialog.textContent ?? '{}') as Record<string, unknown>;
+    expect(merged.version).toBe('1.0.1');
+    /* repo-provided params win */
+    const parameters = merged.parameters as { properties: Record<string, unknown> };
+    expect(parameters.properties.query).toBeDefined();
+    expect(parameters.properties.old).toBeUndefined();
+    const execution = merged.execution as { distribution: { version: string } };
+    expect(execution.distribution.version).toBe('1.0.1');
+    /* governance fields keep the approved values */
+    expect(merged.tool_id).toBe('wangjianbo.toolsdemo');
+    expect(merged.allowed_groups).toEqual(['team-editor']);
+    expect(merged.enabled).toBe(true);
+  });
+
+  it('confirm blocks when tool.json@tag version mismatches the release tag', async () => {
+    /* Toolhost refuses to install a package whose declared version differs
+     * from the tag — approving it would dead-end at install time. */
+    mocks.state.tools = [EXISTING];
+    mocks.state.pending = [PENDING_UPDATE];
+    mocks.checkRepo.mockResolvedValue(CHECK_RESULT_MISMATCH);
+    renderTab();
+
+    await act(async () => {
+      fireEvent.click(await screen.findByRole('button', { name: 'com_tools_pending_confirm' }));
+    });
+    expect(await screen.findByText(/version_mismatch/)).toBeInTheDocument();
+    expect(screen.queryByTestId('edit-dialog')).toBeNull();
+  });
+
+  it('confirm keeps approved values for everything the repo does not provide', async () => {
+    mocks.state.tools = [EXISTING];
+    mocks.state.pending = [PENDING_UPDATE];
+    mocks.checkRepo.mockResolvedValue(CHECK_RESULT_SPARSE);
+    renderTab();
+
+    await act(async () => {
+      fireEvent.click(await screen.findByRole('button', { name: 'com_tools_pending_confirm' }));
+    });
+    const merged = JSON.parse(
+      (await screen.findByTestId('edit-dialog')).textContent ?? '{}',
+    ) as Record<string, unknown>;
+
+    expect(merged.version).toBe('1.0.1');
+    expect(merged.display_name).toBe('Tools Demo');
+    expect(merged.description).toBe('approved description');
+    expect(merged.dangerous).toBe(true);
+    const parameters = merged.parameters as { properties: Record<string, unknown> };
+    expect(parameters.properties.old).toBeDefined();
+    expect(merged.result).toEqual({ renderer: 'table', config: { columns: ['a'] } });
+    const distribution = (merged.execution as { distribution: Record<string, string> })
+      .distribution;
+    expect(distribution.package_sha256).toBe('a'.repeat(64));
+    expect(distribution.launcher).toBe('main.py');
+    expect(distribution.runtime).toBe('self-contained');
+  });
+
+  it('confirm does not open the dialog when the repo check has hard errors', async () => {
+    mocks.state.tools = [EXISTING];
+    mocks.state.pending = [PENDING_UPDATE];
+    mocks.checkRepo.mockResolvedValue(CHECK_RESULT_ERROR);
+    renderTab();
+
+    await act(async () => {
+      fireEvent.click(await screen.findByRole('button', { name: 'com_tools_pending_confirm' }));
+    });
+    expect(await screen.findByText(/zip_asset_count/)).toBeInTheDocument();
+    expect(screen.queryByTestId('edit-dialog')).toBeNull();
+  });
+
+  it('surfaces a failed repo check as an alert', async () => {
+    mocks.state.tools = [EXISTING];
+    mocks.state.pending = [PENDING_UPDATE];
+    mocks.checkRepo.mockRejectedValue(new Error('Gitea unreachable'));
+    renderTab();
+
+    await act(async () => {
+      fireEvent.click(await screen.findByRole('button', { name: 'com_tools_pending_confirm' }));
+    });
+    expect(await screen.findByRole('alert')).toHaveTextContent('Gitea unreachable');
+  });
+
+  it('shows the error inside the panel when the pending query fails', async () => {
+    mocks.state.tools = [EXISTING];
+    mocks.state.failPending = true;
+    renderTab();
+
+    const section = await screen.findByRole('region', { name: 'com_tools_pending_title' });
+    expect(section.querySelector('[role="alert"]')).toHaveTextContent('pending boom');
+  });
+
+  it('renders a loading state while the catalog loads', () => {
+    mocks.state.hangTools = true;
+    renderTab();
+    expect(screen.getByText('loading')).toBeInTheDocument();
+  });
+});
diff --git a/src/components/tools/__tests__/ToolGroupsTab.realDnd.test.tsx b/src/components/tools/__tests__/ToolGroupsTab.realDnd.test.tsx
new file mode 100644
index 00000000..8320e70d
--- /dev/null
+++ b/src/components/tools/__tests__/ToolGroupsTab.realDnd.test.tsx
@@ -0,0 +1,106 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ToolGroupsTab } from '../ToolGroupsTab';
+
+/* 用真实 dnd-kit 渲染 ToolGroupsTab 并打开分组详情弹窗，
+ * 复现浏览器端点 ☰ 后整路由崩溃的问题。 */
+
+vi.mock('@dnd-kit/core', async (importOriginal) => await importOriginal());
+vi.mock('@dnd-kit/modifiers', async (importOriginal) => await importOriginal());
+vi.mock('@dnd-kit/sortable', async (importOriginal) => await importOriginal());
+vi.mock('@dnd-kit/utilities', async (importOriginal) => await importOriginal());
+
+const mocks = vi.hoisted(() => ({
+  state: {
+    groups: [] as Array<Record<string, unknown>>,
+    tools: [] as Array<Record<string, unknown>>,
+  },
+}));
+
+vi.mock('@/hooks/useLocalize', () => {
+  const localize = (key: string, params?: Record<string, unknown>) => {
+    if (!params) return key;
+    return key + ' ' + Object.values(params).join(' ');
+  };
+  return { default: () => localize, useLocalize: () => localize };
+});
+
+vi.mock('@/server', () => ({
+  toolGroupsQueryOptions: {
+    queryKey: ['t', 'groups'],
+    queryFn: () => Promise.resolve(mocks.state.groups),
+  },
+  toolsQueryOptions: {
+    queryKey: ['t', 'tools'],
+    queryFn: () => Promise.resolve({ tools: mocks.state.tools, groups: [] }),
+  },
+  createToolGroupFn: vi.fn(),
+  deleteToolGroupFn: vi.fn(),
+  updateToolGroupFn: vi.fn(),
+  updateToolFn: vi.fn(),
+}));
+
+vi.mock('@/utils', () => ({
+  cn: (...parts: Array<string | false | null | undefined>) => parts.filter(Boolean).join(' '),
+  notifySuccess: vi.fn(),
+  notifyError: vi.fn(),
+}));
+
+const GROUPS = [
+  {
+    name: 'data',
+    display_name: '数据处理',
+    description: '',
+    sort_order: 0,
+    allowed_groups: ['*'],
+    explicit: true,
+    tool_count: 1,
+  },
+];
+
+const TOOLS = [
+  {
+    schema_version: 1,
+    tool_id: 'echo.hello',
+    version: '1.0.0',
+    display_name: '回声测试',
+    description: '',
+    expose: ['ui'],
+    allowed_groups: ['*'],
+    enabled: true,
+    display_group: 'data',
+  },
+  {
+    schema_version: 1,
+    tool_id: 'demo.echo',
+    version: '1.0.0',
+    display_name: '另一个工具',
+    description: '',
+    expose: ['ui'],
+    allowed_groups: ['*'],
+    enabled: true,
+  },
+];
+
+describe('ToolGroupsTab detail dialog with REAL dnd-kit', () => {
+  it('opens the dual-list dialog without crashing', async () => {
+    mocks.state.groups = GROUPS;
+    mocks.state.tools = TOOLS;
+    const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    render(
+      <QueryClientProvider client={client}>
+        <ToolGroupsTab />
+      </QueryClientProvider>,
+    );
+    await screen.findByText('数据处理');
+    // 点 ☰ 打开 GroupToolsDialog
+    fireEvent.click(screen.getByRole('button', { name: 'com_tools_group_detail_manage' }));
+    // 双列表挂载：左右两列标题都出现
+    await screen.findByText('com_tools_group_detail_left');
+    expect(screen.getByText('com_tools_group_detail_right')).toBeInTheDocument();
+    // 组内工具行与候选行都在
+    expect(screen.getByText('回声测试')).toBeInTheDocument();
+    expect(screen.getByText('另一个工具')).toBeInTheDocument();
+  });
+});
diff --git a/src/components/tools/index.ts b/src/components/tools/index.ts
new file mode 100644
index 00000000..fd3a3f57
--- /dev/null
+++ b/src/components/tools/index.ts
@@ -0,0 +1 @@
+export { ToolsPage } from './ToolsPage';
diff --git a/src/components/usage/UsagePage.test.tsx b/src/components/usage/UsagePage.test.tsx
new file mode 100644
index 00000000..966f6dfa
--- /dev/null
+++ b/src/components/usage/UsagePage.test.tsx
@@ -0,0 +1,246 @@
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { RunReport, RunReportFilters } from '@/server';
+
+/**
+ * UsagePage behavior with every heavy dependency mocked: react-query serves
+ * fixture pages, the server fns are spies, click-ui controls collapse into
+ * native elements. `buildRunReportsCsv` stays real so the exported CSV content
+ * is asserted end-to-end (only the DOM download is stubbed).
+ */
+
+let reportsState: { reports: RunReport[]; total: number } | undefined;
+let reportsError = false;
+let toolsState: { tools: { tool_id: string; display_name: string }[] } | undefined;
+let mockUserValue = '';
+let capturedQuery: { page: number; filters: RunReportFilters } | null = null;
+
+const exportRunReportsFn = vi.fn();
+const mockAnnounce = vi.fn();
+
+vi.mock('@/server', () => ({
+  RUN_REPORTS_PAGE_SIZE: 50,
+  RUN_REPORTS_EXPORT_CAP: 10_000,
+  exportRunReportsFn: (...args: unknown[]) => exportRunReportsFn(...args),
+  runReportsQueryOptions: (page: number, filters: RunReportFilters) => {
+    capturedQuery = { page, filters };
+    return { queryKey: ['terravox', 'runReports', page, filters] };
+  },
+  /** Shape-faithful: the real export is a static queryOptions OBJECT, not a
+   * factory — a `() => ({...})` mock here once hid a production-only
+   * "toolsQueryOptions is not a function" crash (fixed 2026-09-28). */
+  toolsQueryOptions: { queryKey: ['terravox', 'tools', 'all'] },
+}));
+
+vi.mock('@tanstack/react-query', () => ({
+  useQuery: vi.fn((options: { queryKey: unknown[] }) =>
+    options.queryKey[1] === 'runReports'
+      ? {
+          data: reportsState,
+          isPending: reportsState === undefined && !reportsError,
+          isFetching: false,
+          isError: reportsError,
+        }
+      : { data: toolsState, isPending: false, isFetching: false, isError: false },
+  ),
+  keepPreviousData: Symbol('keepPreviousData'),
+  useQueryClient: () => ({
+    invalidateQueries: vi.fn(),
+  }),
+}));
+
+vi.mock('@/hooks', () => ({
+  useLocalize: () => (key: string, options?: Record<string, unknown>) =>
+    options ? `${key}:${Object.values(options).join(',')}` : key,
+  useAnnouncement: () => ({ message: '', announce: mockAnnounce }),
+  useDebouncedFilter: () => ({
+    value: mockUserValue,
+    onChange: (value: string) => {
+      mockUserValue = value;
+    },
+    debouncedValue: mockUserValue,
+  }),
+}));
+
+vi.mock('@clickhouse/click-ui', () => {
+  const SelectMock = ({
+    label,
+    value,
+    onSelect,
+    children,
+  }: {
+    label: string;
+    value: string;
+    onSelect: (value: string) => void;
+    children: React.ReactNode;
+  }) => (
+    <div>
+      <span>{label}</span>
+      <select aria-label={label} value={value} onChange={(e) => onSelect(e.target.value)}>
+        {children}
+      </select>
+    </div>
+  );
+  SelectMock.Item = ({ value, children }: { value: string; children: React.ReactNode }) => (
+    <option value={value}>{children}</option>
+  );
+  return {
+    Badge: ({ text }: { text: React.ReactNode }) => <span data-testid="cui-badge">{text}</span>,
+    Button: ({
+      label,
+      onClick,
+      disabled,
+      loading,
+    }: {
+      label: React.ReactNode;
+      onClick?: () => void;
+      disabled?: boolean;
+      loading?: boolean;
+    }) => (
+      <button type="button" disabled={disabled || loading} onClick={onClick}>
+        {label}
+      </button>
+    ),
+    DatePicker: ({ placeholder }: { placeholder?: string }) => (
+      <button type="button">{placeholder}</button>
+    ),
+    Icon: ({ name }: { name?: string }) => <span aria-hidden="true">{name}</span>,
+    Select: SelectMock,
+    TextField: ({
+      label,
+      value,
+      onChange,
+    }: {
+      label: string;
+      value: string;
+      onChange: (value: string) => void;
+    }) => <input aria-label={label} value={value} onChange={(e) => onChange(e.target.value)} />,
+  };
+});
+
+vi.mock('@/components/usage/usageUtils', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./usageUtils')>()),
+  downloadTextCsv: vi.fn(),
+}));
+
+import { UsagePage } from './UsagePage';
+import { downloadTextCsv } from './usageUtils';
+
+const report = (id: string, over: Partial<RunReport> = {}): RunReport => ({
+  id,
+  user_sub: 'user-wang',
+  username: 'wangjianbo',
+  tool_id: 'wangjianbo.toolsdemo',
+  version: '1.0.0',
+  status: 'succeeded',
+  duration_ms: 8500,
+  argument_keys: ['text'],
+  source: 'toolbox',
+  created_at: '2026-09-28T10:00:00Z',
+  ...over,
+});
+
+const renderPage = () => render(<UsagePage />);
+
+describe('UsagePage', () => {
+  beforeEach(() => {
+    reportsState = undefined;
+    reportsError = false;
+    toolsState = undefined;
+    mockUserValue = '';
+    capturedQuery = null;
+    exportRunReportsFn.mockReset();
+    mockAnnounce.mockReset();
+    vi.mocked(downloadTextCsv).mockClear();
+  });
+
+  it('renders rows with user, tool, status label, duration and total count', () => {
+    reportsState = {
+      reports: [report('r1'), report('r2', { status: 'failed', duration_ms: 300, version: null })],
+      total: 2,
+    };
+    renderPage();
+
+    expect(screen.getAllByText('wangjianbo').length).toBeGreaterThanOrEqual(2);
+    expect(screen.getAllByText('wangjianbo.toolsdemo').length).toBeGreaterThanOrEqual(2);
+    expect(screen.getByText('com_usage_status_succeeded')).toBeInTheDocument();
+    expect(screen.getByText('com_usage_status_failed')).toBeInTheDocument();
+    expect(screen.getByText('8.5s')).toBeInTheDocument();
+    expect(screen.getByText('300ms')).toBeInTheDocument();
+    expect(screen.getByText('com_usage_count:2')).toBeInTheDocument();
+  });
+
+  it('feeds the tool filter and first-page reset into the query', () => {
+    toolsState = { tools: [{ tool_id: 'wangjianbo.toolsdemo', display_name: 'Demo' }] };
+    reportsState = { reports: [report('r1')], total: 1 };
+    renderPage();
+
+    fireEvent.change(screen.getByLabelText('com_usage_filter_tool'), {
+      target: { value: 'wangjianbo.toolsdemo' },
+    });
+
+    expect(capturedQuery).toEqual({
+      page: 1,
+      filters: {
+        tool_id: 'wangjianbo.toolsdemo',
+        user_sub: undefined,
+        since: undefined,
+        until: undefined,
+      },
+    });
+  });
+
+  it('export: server fn gets the visible filter, download gets a BOM’d CSV', async () => {
+    toolsState = { tools: [{ tool_id: 'wangjianbo.toolsdemo', display_name: 'Demo' }] };
+    reportsState = { reports: [report('r1', { status: 'failed' })], total: 1 };
+    renderPage();
+    fireEvent.change(screen.getByLabelText('com_usage_filter_tool'), {
+      target: { value: 'wangjianbo.toolsdemo' },
+    });
+
+    exportRunReportsFn.mockResolvedValue({
+      reports: [report('r1', { status: 'failed' })],
+      truncated: false,
+    });
+    fireEvent.click(screen.getByRole('button', { name: 'com_usage_export' }));
+
+    await waitFor(() => expect(downloadTextCsv).toHaveBeenCalledTimes(1));
+    expect(exportRunReportsFn).toHaveBeenCalledWith({
+      data: {
+        tool_id: 'wangjianbo.toolsdemo',
+        user_sub: undefined,
+        since: undefined,
+        until: undefined,
+      },
+    });
+    const [filename, csv] = vi.mocked(downloadTextCsv).mock.calls[0];
+    expect(filename).toMatch(/^tool-usage-\d{4}-\d{2}-\d{2}\.csv$/);
+    expect(csv.charCodeAt(0)).toBe(0xfeff);
+    expect(csv).toContain('com_usage_col_time');
+    expect(csv).toContain('wangjianbo,user-wang,wangjianbo.toolsdemo,wangjianbo.toolsdemo,1.0.0,failed');
+  });
+
+  it('export failure announces instead of dying silently', async () => {
+    reportsState = { reports: [report('r1')], total: 1 };
+    exportRunReportsFn.mockRejectedValue(new Error('gateway down'));
+    renderPage();
+
+    fireEvent.click(screen.getByRole('button', { name: 'com_usage_export' }));
+    await waitFor(() => expect(mockAnnounce).toHaveBeenCalledWith('com_usage_export_failed'));
+    expect(downloadTextCsv).not.toHaveBeenCalled();
+  });
+
+  it('empty result: placeholder row and a disabled export', () => {
+    reportsState = { reports: [], total: 0 };
+    renderPage();
+    expect(screen.getByText('com_usage_empty')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'com_usage_export' })).toBeDisabled();
+  });
+
+  it('load error: error state with export disabled', () => {
+    reportsError = true;
+    renderPage();
+    expect(screen.getByText('com_usage_error')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'com_usage_export' })).toBeDisabled();
+  });
+});
diff --git a/src/components/usage/UsagePage.tsx b/src/components/usage/UsagePage.tsx
new file mode 100644
index 00000000..40fcaf40
--- /dev/null
+++ b/src/components/usage/UsagePage.tsx
@@ -0,0 +1,397 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { keepPreviousData, useQuery, useQueryClient } from '@tanstack/react-query';
+import { Badge, Button, DatePicker, Select, TextField } from '@clickhouse/click-ui';
+import type { RunReport, RunReportFilters } from '@/server';
+import {
+  RUN_REPORTS_EXPORT_CAP,
+  RUN_REPORTS_PAGE_SIZE,
+  exportRunReportsFn,
+  runReportsQueryOptions,
+  toolsQueryOptions,
+} from '@/server';
+import {
+  DatePickerCell,
+  EmptyState,
+  LoadingState,
+  Pagination,
+  ScreenReaderAnnouncer,
+} from '@/components/shared';
+import { useAnnouncement, useDebouncedFilter, useLocalize } from '@/hooks';
+/* Generic local-day/date helpers (shared with the audit-log filters). */
+import {
+  dateToIsoDate,
+  formatTimestamp,
+  isoDateToDate,
+  localDayBoundaryIso,
+} from '@/components/grants/auditLogUtils';
+import {
+  RUN_STATUS_BADGE_STATE,
+  RUN_STATUS_LABEL_KEY,
+  SOURCE_LABEL_KEY,
+  buildRunReportsCsv,
+  downloadTextCsv,
+  formatRunDuration,
+} from './usageUtils';
+
+/** Radix `Select.Item` cannot use `value=""` (Radix reserves empty string for
+ * "no selection") — sentinel translated to "no tool filter" in state. */
+const TOOL_ALL = '__all__';
+
+/**
+ * Tool usage statistics (local-tool-plan §11 步骤 3): who ran which desktop
+ * tool, when, and how it ended. Rows come from the gateway `run_reports` table
+ * (browser best-effort reports from the toolbox); the CSV export pages the
+ * whole filter result server-side, capped at 10k rows.
+ */
+export function UsagePage() {
+  const localize = useLocalize();
+  const queryClient = useQueryClient();
+  const [toolId, setToolId] = useState('');
+  const [dateFrom, setDateFrom] = useState('');
+  const [dateTo, setDateTo] = useState('');
+  /** Bumped each clear so DatePicker remounts and drops its internal selection state. */
+  const [dateResetNonce, setDateResetNonce] = useState(0);
+  const [currentPage, setCurrentPage] = useState(1);
+  const [exporting, setExporting] = useState(false);
+  const { message: announcement, announce } = useAnnouncement();
+
+  const resetToFirstPage = useCallback(() => setCurrentPage(1), []);
+  const userFilter = useDebouncedFilter('', resetToFirstPage);
+
+  /** The gateway matches `user_sub` exactly — label the field as an ID, not a
+   * free-text name search, so admins are not surprised by empty results. */
+  const filters = useMemo<RunReportFilters>(
+    () => ({
+      tool_id: toolId || undefined,
+      user_sub: userFilter.debouncedValue.trim() || undefined,
+      since: localDayBoundaryIso(dateFrom, 'start'),
+      until: localDayBoundaryIso(dateTo, 'end'),
+    }),
+    [toolId, userFilter.debouncedValue, dateFrom, dateTo],
+  );
+
+  const { data, isPending, isFetching, isError } = useQuery({
+    ...runReportsQueryOptions(currentPage, filters),
+    placeholderData: keepPreviousData,
+  });
+
+  /** Tool dropdown options from the catalog (display_name + tool_id).
+   * `toolsQueryOptions` is a static queryOptions object, not a factory. */
+  const toolsQuery = useQuery(toolsQueryOptions);
+
+  const pageReports = useMemo<RunReport[]>(() => data?.reports ?? [], [data]);
+  const total = data?.total ?? 0;
+  const totalPages = Math.max(1, Math.ceil(total / RUN_REPORTS_PAGE_SIZE));
+  /** On error the table shows an EmptyState, so the footer/pagination counts
+   * collapse to zero rather than contradicting it with stale keepPreviousData. */
+  const displayTotal = isError ? 0 : total;
+  const displayTotalPages = isError ? 1 : totalPages;
+
+  useEffect(() => {
+    if (currentPage > totalPages) {
+      setCurrentPage(totalPages);
+    }
+  }, [currentPage, totalPages]);
+
+  /** Announce the full match count once per filter change (not per refetch). */
+  const filterSignature = useMemo(
+    () => JSON.stringify({ toolId, user: userFilter.debouncedValue, dateFrom, dateTo }),
+    [toolId, userFilter.debouncedValue, dateFrom, dateTo],
+  );
+  const lastAnnouncedSignature = useRef<string | null>(null);
+  useEffect(() => {
+    if (isFetching || isError) return;
+    if (lastAnnouncedSignature.current === filterSignature) return;
+    lastAnnouncedSignature.current = filterSignature;
+    announce(localize('com_usage_count', { count: total }));
+  }, [filterSignature, isFetching, isError, total, announce, localize]);
+
+  const buildExportFilters = useCallback(
+    (immediateUser: string): RunReportFilters => ({
+      tool_id: toolId || undefined,
+      /** Immediate input, not the debounced snapshot — an export click within
+       * the 300 ms window must match exactly what the user sees. */
+      user_sub: immediateUser.trim() || undefined,
+      since: localDayBoundaryIso(dateFrom, 'start'),
+      until: localDayBoundaryIso(dateTo, 'end'),
+    }),
+    [toolId, dateFrom, dateTo],
+  );
+
+  const handleExport = useCallback(async () => {
+    setExporting(true);
+    try {
+      const { reports: rows, truncated } = await exportRunReportsFn({
+        data: buildExportFilters(userFilter.value),
+      });
+      if (truncated) {
+        announce(localize('com_usage_export_truncated', { count: RUN_REPORTS_EXPORT_CAP }));
+      }
+      downloadTextCsv(
+        `tool-usage-${new Date().toISOString().slice(0, 10)}.csv`,
+        buildRunReportsCsv(rows, [
+          localize('com_usage_col_time'),
+          localize('com_usage_col_user'),
+          localize('com_usage_col_user_sub'),
+          localize('com_usage_col_tool'),
+          localize('com_usage_col_version'),
+          localize('com_usage_col_status'),
+          localize('com_usage_col_duration'),
+          localize('com_usage_col_arguments'),
+          localize('com_usage_col_source'),
+          localize('com_usage_col_id'),
+        ]),
+      );
+    } catch {
+      announce(localize('com_usage_export_failed'));
+    } finally {
+      setExporting(false);
+    }
+  }, [buildExportFilters, userFilter.value, announce, localize]);
+
+  const showLoading = isPending && !data;
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto p-4">
+      <div className="flex flex-wrap items-end gap-3">
+        <div className="select-field-a11y w-60">
+          <Select
+            label={localize('com_usage_filter_tool')}
+            value={toolId === '' ? TOOL_ALL : toolId}
+            onSelect={(value) => {
+              setToolId(value === TOOL_ALL ? '' : value);
+              resetToFirstPage();
+            }}
+            placeholder={localize('com_ui_all')}
+          >
+            <Select.Item value={TOOL_ALL}>{localize('com_ui_all')}</Select.Item>
+            {(toolsQuery.data?.tools ?? []).map((tool) => (
+              <Select.Item key={tool.tool_id} value={tool.tool_id}>
+                {tool.display_name ? `${tool.display_name} (${tool.tool_id})` : tool.tool_id}
+              </Select.Item>
+            ))}
+          </Select>
+        </div>
+
+        <div className="w-60">
+          <TextField
+            label={localize('com_usage_filter_user')}
+            value={userFilter.value}
+            onChange={userFilter.onChange}
+            placeholder={localize('com_usage_filter_user')}
+          />
+        </div>
+
+        <div className="flex items-center gap-1.5">
+          <label htmlFor="usage-date-from" className="text-xs text-(--cui-color-text-muted)">
+            {localize('com_audit_date_from')}
+          </label>
+          <DatePickerCell resetKey={dateResetNonce} inputId="usage-date-from">
+            <DatePicker
+              key={`from-${dateResetNonce}`}
+              date={isoDateToDate(dateFrom)}
+              onSelectDate={(d) => {
+                setDateFrom(d ? dateToIsoDate(d) : '');
+                resetToFirstPage();
+              }}
+              placeholder={localize('com_audit_date_from')}
+            />
+          </DatePickerCell>
+        </div>
+        <div className="flex items-center gap-1.5">
+          <label htmlFor="usage-date-to" className="text-xs text-(--cui-color-text-muted)">
+            {localize('com_audit_date_to')}
+          </label>
+          <DatePickerCell resetKey={dateResetNonce} inputId="usage-date-to">
+            <DatePicker
+              key={`to-${dateResetNonce}`}
+              date={isoDateToDate(dateTo)}
+              onSelectDate={(d) => {
+                setDateTo(d ? dateToIsoDate(d) : '');
+                resetToFirstPage();
+              }}
+              placeholder={localize('com_audit_date_to')}
+            />
+          </DatePickerCell>
+        </div>
+        {(dateFrom || dateTo) && (
+          <Button
+            type="danger"
+            iconLeft="cross"
+            label={localize('com_ui_clear')}
+            aria-label={localize('com_a11y_clear_dates')}
+            onClick={() => {
+              setDateFrom('');
+              setDateTo('');
+              setDateResetNonce((n) => n + 1);
+              resetToFirstPage();
+            }}
+          />
+        )}
+
+        <div className="ml-auto flex items-center gap-2">
+          <Button
+            type="secondary"
+            iconLeft="refresh"
+            onClick={() => void queryClient.invalidateQueries({ queryKey: ['terravox'] })}
+            label={localize('com_usage_refresh')}
+          />
+          <Button
+            type="secondary"
+            iconLeft="download"
+            onClick={() => void handleExport()}
+            disabled={displayTotal === 0 || exporting}
+            loading={exporting}
+            label={localize('com_usage_export')}
+          />
+        </div>
+      </div>
+
+      <div
+        className="overflow-x-auto rounded-lg border border-(--cui-color-stroke-default)"
+        role="region"
+        aria-label={localize('com_usage_title')}
+      >
+        <table className="w-full text-left text-sm">
+          <caption className="sr-only">{localize('com_usage_title')}</caption>
+          <thead className="sticky top-0 z-(--z-sticky)">
+            <tr className="border-b border-(--cui-color-stroke-default) bg-(--cui-color-background-muted)">
+              <th
+                scope="col"
+                className="px-4 py-2.5 font-medium whitespace-nowrap text-(--cui-color-text-muted)"
+              >
+                {localize('com_usage_col_time')}
+              </th>
+              <th scope="col" className="px-4 py-2.5 font-medium text-(--cui-color-text-muted)">
+                {localize('com_usage_col_user')}
+              </th>
+              <th scope="col" className="px-4 py-2.5 font-medium text-(--cui-color-text-muted)">
+                {localize('com_usage_col_tool')}
+              </th>
+              <th scope="col" className="px-4 py-2.5 font-medium text-(--cui-color-text-muted)">
+                {localize('com_usage_col_version')}
+              </th>
+              <th scope="col" className="px-4 py-2.5 font-medium text-(--cui-color-text-muted)">
+                {localize('com_usage_col_status')}
+              </th>
+              <th
+                scope="col"
+                className="px-4 py-2.5 font-medium whitespace-nowrap text-(--cui-color-text-muted)"
+              >
+                {localize('com_usage_col_duration')}
+              </th>
+              <th scope="col" className="px-4 py-2.5 font-medium text-(--cui-color-text-muted)">
+                {localize('com_usage_col_source')}
+              </th>
+            </tr>
+          </thead>
+          <tbody>
+            {showLoading && (
+              <tr>
+                <td colSpan={7}>
+                  <LoadingState />
+                </td>
+              </tr>
+            )}
+            {!showLoading && isError && (
+              <tr>
+                <td colSpan={7}>
+                  <EmptyState message={localize('com_usage_error')} />
+                </td>
+              </tr>
+            )}
+            {!showLoading &&
+              !isError &&
+              pageReports.map((report) => (
+                <UsageTableRow key={report.id} report={report} localize={localize} />
+              ))}
+            {!showLoading && !isError && pageReports.length === 0 && (
+              <tr>
+                <td colSpan={7}>
+                  <EmptyState message={localize('com_usage_empty')} />
+                </td>
+              </tr>
+            )}
+          </tbody>
+        </table>
+      </div>
+
+      <Pagination
+        currentPage={currentPage}
+        totalPages={displayTotalPages}
+        onPageChange={setCurrentPage}
+      />
+
+      {!isError && (
+        <div className="flex items-center justify-between gap-3 pb-4">
+          <p
+            className="text-xs text-(--cui-color-text-muted)"
+            aria-live="polite"
+            aria-atomic="true"
+          >
+            {localize('com_usage_count', { count: displayTotal })}
+          </p>
+        </div>
+      )}
+
+      <ScreenReaderAnnouncer message={announcement} />
+    </div>
+  );
+}
+
+/** Rows are read-only — no drawer, no activation handler. */
+function UsageTableRow({
+  report,
+  localize,
+}: {
+  report: RunReport;
+  localize: ReturnType<typeof useLocalize>;
+}) {
+  return (
+    <tr className="border-b border-(--cui-color-stroke-default) bg-(--cui-color-background-panel) last:border-b-0">
+      <td className="px-4 py-3 text-xs whitespace-nowrap text-(--cui-color-text-muted)">
+        <time dateTime={report.created_at}>{formatTimestamp(report.created_at)}</time>
+      </td>
+      <td className="px-4 py-3">
+        <div className="flex flex-col">
+          <span className="font-medium text-(--cui-color-text-default)">
+            {report.user_name || report.username || report.user_sub}
+          </span>
+          {(report.user_name || report.username) && (
+            <span aria-hidden="true" className="text-[10px] text-(--cui-color-text-muted)">
+              {report.user_sub}
+            </span>
+          )}
+        </div>
+      </td>
+      <td className="px-4 py-3">
+        <div className="flex flex-col">
+          <span className="text-(--cui-color-text-default)">
+            {report.tool_name || report.tool_id}
+          </span>
+          {report.tool_name && (
+            <span aria-hidden="true" className="font-mono text-[10px] text-(--cui-color-text-muted)">
+              {report.tool_id}
+            </span>
+          )}
+        </div>
+      </td>
+      <td className="px-4 py-3 text-(--cui-color-text-default)">{report.version ?? '—'}</td>
+      <td className="px-4 py-3">
+        <Badge
+          size="sm"
+          state={RUN_STATUS_BADGE_STATE[report.status]}
+          text={localize(RUN_STATUS_LABEL_KEY[report.status])}
+        />
+      </td>
+      <td className="px-4 py-3 text-xs whitespace-nowrap text-(--cui-color-text-muted)">
+        {formatRunDuration(report.duration_ms)}
+      </td>
+      <td className="px-4 py-3 text-(--cui-color-text-default)">
+        {SOURCE_LABEL_KEY[report.source]
+          ? localize(SOURCE_LABEL_KEY[report.source])
+          : (report.source || '—')}
+      </td>
+    </tr>
+  );
+}
diff --git a/src/components/usage/index.ts b/src/components/usage/index.ts
new file mode 100644
index 00000000..c48ccba8
--- /dev/null
+++ b/src/components/usage/index.ts
@@ -0,0 +1 @@
+export { UsagePage } from './UsagePage';
diff --git a/src/components/usage/usageUtils.test.ts b/src/components/usage/usageUtils.test.ts
new file mode 100644
index 00000000..43da5858
--- /dev/null
+++ b/src/components/usage/usageUtils.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import type { RunReport } from '@/server';
+import {
+  RUN_STATUS_BADGE_STATE,
+  RUN_STATUS_LABEL_KEY,
+  buildRunReportsCsv,
+  formatRunDuration,
+} from './usageUtils';
+
+const report = (over: Partial<RunReport> = {}): RunReport => ({
+  id: 'rep1',
+  user_sub: 'user-wang',
+  username: 'wangjianbo',
+  tool_id: 'wangjianbo.toolsdemo',
+  version: '1.0.0',
+  status: 'succeeded',
+  duration_ms: 8500,
+  argument_keys: ['text'],
+  source: 'toolbox',
+  created_at: '2026-09-28T10:00:00Z',
+  ...over,
+});
+
+describe('formatRunDuration', () => {
+  it('renders sub-second as milliseconds, above as one-decimal seconds', () => {
+    expect(formatRunDuration(420)).toBe('420ms');
+    expect(formatRunDuration(8500)).toBe('8.5s');
+    expect(formatRunDuration(1000)).toBe('1.0s');
+  });
+
+  it('missing duration renders the em dash', () => {
+    expect(formatRunDuration(null)).toBe('—');
+    expect(formatRunDuration(undefined)).toBe('—');
+  });
+});
+
+describe('status presentation', () => {
+  it('every status maps to a badge state and a label key (never color alone)', () => {
+    for (const status of ['succeeded', 'failed', 'stopped', 'timeout'] as const) {
+      expect(RUN_STATUS_BADGE_STATE[status]).toBeTruthy();
+      expect(RUN_STATUS_LABEL_KEY[status]).toMatch(/^com_usage_status_/);
+    }
+    expect(RUN_STATUS_BADGE_STATE.failed).toBe('danger');
+    expect(RUN_STATUS_BADGE_STATE.timeout).toBe('warning');
+  });
+});
+
+describe('buildRunReportsCsv', () => {
+  it('starts with the UTF-8 BOM and carries the header row', () => {
+    const csv = buildRunReportsCsv([], ['Time', 'User']);
+    expect(csv.charCodeAt(0)).toBe(0xfeff);
+    expect(csv.slice(1)).toBe('Time,User\r\n');
+  });
+
+  it('serializes rows in the documented column order', () => {
+    const csv = buildRunReportsCsv(
+      [report({ argument_keys: ['text', 'count'], version: null, duration_ms: null })],
+      ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'h7', 'h8', 'h9', 'h10'],
+    );
+    const lines = csv.slice(1).trimEnd().split('\r\n');
+    expect(lines).toHaveLength(2);
+    expect(lines[1]).toBe(
+      '2026-09-28T10:00:00Z,wangjianbo,user-wang,wangjianbo.toolsdemo,wangjianbo.toolsdemo,,succeeded,,text;count,toolbox,rep1',
+    );
+  });
+
+  it('RFC 4180-escapes commas, quotes and newlines (zh usernames included)', () => {
+    const csv = buildRunReportsCsv(
+      [report({ username: '王,建"波\n二行' })],
+      ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'h7', 'h8', 'h9', 'h10'],
+    );
+    expect(csv).toContain('"王,建""波\n二行"');
+  });
+});
diff --git a/src/components/usage/usageUtils.ts b/src/components/usage/usageUtils.ts
new file mode 100644
index 00000000..aa2f0d5c
--- /dev/null
+++ b/src/components/usage/usageUtils.ts
@@ -0,0 +1,86 @@
+import type { RunReport } from '@/server';
+
+/** Status → Badge state (color) paired with a label key — the label always
+ * renders beside the color, never color alone. */
+export const RUN_STATUS_BADGE_STATE: Record<RunReport['status'], 'success' | 'danger' | 'warning'> =
+  {
+    succeeded: 'success',
+    failed: 'danger',
+    stopped: 'warning',
+    timeout: 'warning',
+  };
+
+export const RUN_STATUS_LABEL_KEY: Record<RunReport['status'], string> = {
+  succeeded: 'com_usage_status_succeeded',
+  failed: 'com_usage_status_failed',
+  stopped: 'com_usage_status_stopped',
+  timeout: 'com_usage_status_timeout',
+};
+
+/** 调用方式（2.24.0）：mcp=AI 经 MCP facade，server=人工表单执行，toolbox=浏览器直跑。 */
+export const SOURCE_LABEL_KEY: Record<string, string> = {
+  mcp: 'com_usage_source_mcp',
+  server: 'com_usage_source_server',
+  toolbox: 'com_usage_source_toolbox',
+};
+
+/** 8500 → "8.5s", 420 → "420ms", null → "—" (not recorded / still unknown). */
+export function formatRunDuration(ms: number | null | undefined): string {
+  if (ms == null) {
+    return '—';
+  }
+  return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+
+/** RFC 4180 field escaping: quote-wrap on comma/quote/newline, double quotes. */
+function csvField(value: string): string {
+  if (value === '') {
+    return '';
+  }
+  if (/[",\r\n]/.test(value)) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+
+/** CSV column order — keep in sync with the table (time/user/tool/version/
+ * status/duration) plus export-only detail columns (user_sub, argument key
+ * names, source, row id). */
+export function buildRunReportsCsv(reports: RunReport[], header: string[]): string {
+  const escape = (fields: (string | number | null | undefined)[]) =>
+    fields.map((field) => csvField(field == null ? '' : String(field))).join(',');
+  const lines = [escape(header)];
+  for (const report of reports) {
+    lines.push(
+      escape([
+        report.created_at,
+        report.user_name || report.username,
+        report.user_sub,
+        report.tool_name || report.tool_id,
+        report.tool_id,
+        report.version ?? '',
+        report.status,
+        report.duration_ms == null ? '' : String(report.duration_ms),
+        report.argument_keys.join(';'),
+        report.source,
+        report.id,
+      ]),
+    );
+  }
+  /** BOM first so Excel detects UTF-8 (zh text garbles without it); CRLF line
+   * endings per RFC 4180 for the same reason. */
+  return `\uFEFF${lines.join('\r\n')}\r\n`;
+}
+
+/** Trigger a browser download of the CSV text as a UTF-8 blob. */
+export function downloadTextCsv(filename: string, csv: string): void {
+  const blob = new Blob([csv], { type: 'text/csv;charset=utf-8' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}
diff --git a/src/components/users/CreateUserDialog.tsx b/src/components/users/CreateUserDialog.tsx
index 9a2e79aa..0b776a90 100644
--- a/src/components/users/CreateUserDialog.tsx
+++ b/src/components/users/CreateUserDialog.tsx
@@ -97,8 +97,8 @@ export function CreateUserDialog({ open, onClose }: t.CreateUserDialogProps) {
           onChange={(e) => setRole(e.target.value as SystemRoles)}
           className="rounded-lg border border-(--cui-color-stroke-default) bg-(--cui-color-background-default) px-3 py-2 text-sm text-(--cui-color-text-default)"
         >
-          <option value={SystemRoles.USER}>{SystemRoles.USER}</option>
-          <option value={SystemRoles.ADMIN}>{SystemRoles.ADMIN}</option>
+          <option value={SystemRoles.USER}>{localize('com_users_role_user')}</option>
+          <option value={SystemRoles.ADMIN}>{localize('com_users_role_admin')}</option>
         </select>
       </div>
     </FormDialog>
diff --git a/src/components/users/UserDetailDialog.tsx b/src/components/users/UserDetailDialog.tsx
index c218491b..3493d432 100644
--- a/src/components/users/UserDetailDialog.tsx
+++ b/src/components/users/UserDetailDialog.tsx
@@ -209,6 +209,7 @@ export function UserDetailDialog({
         }}
       >
         <Dialog.Content
+          onInteractOutside={(event) => event.preventDefault()}
           title={dialogTitle}
           showClose
           onClose={handleClose}
diff --git a/src/locales/en/translation.json b/src/locales/en/translation.json
index e3922958..f766b91e 100644
--- a/src/locales/en/translation.json
+++ b/src/locales/en/translation.json
@@ -13,6 +13,8 @@
   "com_ui_create": "Create",
   "com_ui_retry": "Retry",
   "com_ui_done": "Done",
+  "com_ui_back": "Back",
+  "com_ui_close": "Close",
   "com_ui_enabled": "Enabled",
   "com_ui_disabled": "Disabled",
   "com_ui_no_items": "No {{item}}s configured",
@@ -139,6 +141,8 @@
   "com_toast_capabilities_saved": "Capabilities for \"{{name}}\" saved",
   "com_toast_profile_value_saved": "Profile value saved",
   "com_toast_profile_value_removed": "Profile value removed",
+  "com_toast_tool_created": "Tool created",
+  "com_toast_tool_updated": "Tool updated",
   "com_config_import_yaml": "Import YAML",
   "com_config_import_yaml_title": "Import configuration",
   "com_config_import_yaml_desc": "Upload or paste a librechat.yaml file to populate configuration values across the UI.",
@@ -622,7 +626,6 @@
   "com_config_field_selectPlaceholder": "Select placeholder",
   "com_config_field_searchPlaceholderCode": "Search placeholder code",
   "com_config_field_selectPlaceholderCode": "Select placeholder code",
-
   "com_config_field_grant_types_supported_item": "grant type",
   "com_config_field_token_endpoint_auth_methods_supported_item": "method",
   "com_config_field_response_types_supported_item": "response type",
@@ -634,7 +637,6 @@
   "com_config_field_custom_item": "item",
   "com_config_field_paramDefinitions_item": "parameter definition",
   "com_config_field_options_item": "option",
-
   "com_config_field_dropParams_item": "parameter",
   "com_config_field_supportedIds_item": "ID",
   "com_config_field_excludedIds_item": "ID",
@@ -693,7 +695,7 @@
   "com_config_field_buildInfo": "Build info",
   "com_config_field_isTemporary": "Is temporary",
   "com_config_field_hideBadgeRow": "Hide badge row",
-  "com_config_field_guardrailConfig": "Guardrail config",
+  "com_config_field_guardrailConfig": "Guardrail",
   "com_config_field_guardrailIdentifier": "Guardrail identifier",
   "com_config_field_guardrailVersion": "Guardrail version",
   "com_config_field_trace": "Trace",
@@ -704,7 +706,6 @@
   "com_config_field_agent_ids": "Agent IDs",
   "com_config_field_agent_ids_item": "agent ID",
   "com_config_field_allowSelf": "Allow self",
-  "com_config_field_buildInfo": "Build info",
   "com_config_field_cacheRead": "Cache read",
   "com_config_field_cacheWrite": "Cache write",
   "com_config_field_code": "Code",
@@ -717,20 +718,13 @@
   "com_config_field_currency": "Currency",
   "com_config_field_customPatterns": "Custom patterns",
   "com_config_field_customPatterns_item": "pattern",
-  "com_config_field_forward_audience_on_refresh": "Forward audience on refresh",
   "com_config_field_github": "GitHub",
-  "com_config_field_guardrailConfig": "Guardrail",
-  "com_config_field_guardrailIdentifier": "Guardrail identifier",
-  "com_config_field_guardrailVersion": "Guardrail version",
-  "com_config_field_hideBadgeRow": "Hide badge row",
   "com_config_field_intervalMinutes": "Interval (minutes)",
-  "com_config_field_isTemporary": "Is temporary",
   "com_config_field_maxCatalogSkills": "Max catalog skills",
   "com_config_field_maxInputTokens": "Max input tokens",
   "com_config_field_messageFilter": "Message filter",
   "com_config_field_obo": "On-Behalf-Of",
   "com_config_field_pii": "Personally Identifiable Information",
-  "com_config_field_proxy": "Proxy",
   "com_config_field_rate": "Rate",
   "com_config_field_reasoningFormat": "Reasoning format",
   "com_config_field_reasoningKey": "Reasoning key",
@@ -738,7 +732,6 @@
   "com_config_field_includeReasoningHistory": "Include reasoning history",
   "com_config_field_regex": "Regex",
   "com_config_field_retainAgentFiles": "Retain agent files",
-  "com_config_field_retentionMode": "Retention mode",
   "com_config_field_runOnStartup": "Run on startup",
   "com_config_field_sensitive": "Sensitive",
   "com_config_field_sharedLinks": "Shared links",
@@ -749,11 +742,9 @@
   "com_config_field_sources_item": "source",
   "com_config_field_starterPatterns": "Starter patterns",
   "com_config_field_starterPatterns_item": "pattern",
-  "com_config_field_streamProcessingMode": "Stream processing mode",
   "com_config_field_subagents": "Subagents",
   "com_config_field_titleTiming": "Title timing",
   "com_config_field_tokenConfig": "Token configuration",
-  "com_config_field_trace": "Trace",
   "com_config_section_fileStrategies": "File strategies",
   "com_config_section_fileStrategies_desc": "Configure file handling strategies per endpoint",
   "com_config_section_cloudfront": "CloudFront",
@@ -1247,5 +1238,330 @@
   "com_kv_type_number": "123",
   "com_kv_type_boolean": "T/F",
   "com_kv_type_json": "{ }",
-  "com_a11y_logo_alt": "LibreChat logo"
+  "com_a11y_logo_alt": "LibreChat logo",
+  "com_ui_language": "Language",
+  "com_ui_language_english": "English",
+  "com_ui_language_zh_hans": "中文（简体）",
+  "com_audit_target_user": "User",
+  "com_audit_target_group": "Group",
+  "com_audit_target_role": "Role",
+  "com_users_role_admin": "Administrator",
+  "com_users_role_user": "User",
+  "com_nav_tools": "Tools",
+  "com_tools_title": "Tool Management",
+  "com_tools_subtitle": "TerraVox Tool Gateway catalog, including disabled tools",
+  "com_tools_search": "Search tools",
+  "com_tools_count": "{{count}} tools",
+  "com_tools_col_tool": "Tool",
+  "com_tools_col_version": "Version",
+  "com_tools_col_expose": "Exposed to",
+  "com_tools_col_groups": "Allowed groups",
+  "com_tools_col_renderer": "Renderer",
+  "com_tools_col_status": "Status",
+  "com_tools_enabled": "Enabled",
+  "com_tools_disabled": "Disabled",
+  "com_tools_dangerous": "Dangerous",
+  "com_tools_all_groups": "All groups",
+  "com_tools_empty": "No tools",
+  "com_tools_empty_hint": "The Tool Gateway returned an empty catalog. Seed manifests on the gateway side first.",
+  "com_tools_no_match": "No tools match the search.",
+  "com_tools_load_error": "Failed to load tools",
+  "com_tools_retry_later": "Something went wrong. Please try again later.",
+  "com_tools_tab_catalog": "Tool catalog",
+  "com_tools_tab_groups": "Tool groups",
+  "com_tools_group_ungrouped": "Ungrouped",
+  "com_usage_refresh": "Refresh",
+  "com_tools_tab_usage": "Usage",
+  "com_tools_col_group": "Group",
+  "com_tools_add_button": "Add tool",
+  "com_tools_import_button": "Import",
+  "com_tools_copy_id": "Copy tool ID",
+  "com_tools_delete_title": "Delete tool",
+  "com_tools_delete_desc": "Permanently delete {{name}}? It is removed from the catalog and will not be re-seeded on gateway restart; audit records are kept.",
+  "com_tools_add_title": "Add tool",
+  "com_tools_edit_title": "Edit tool",
+  "com_tools_save": "Save",
+  "com_tools_create": "Create",
+  "com_tools_tab_basic": "Basic info",
+  "com_tools_tab_params": "Parameters & form",
+  "com_tools_tab_exec": "Execution & result",
+  "com_tools_custom_group": "Custom…",
+  "com_tools_field_tool_id": "Tool ID",
+  "com_tools_field_group": "Group",
+  "com_tools_field_tool_suffix": "Tool name (suffix)",
+  "com_tools_field_version": "Version",
+  "com_tools_field_display_name": "Display name",
+  "com_tools_field_description": "Description",
+  "com_tools_field_expose": "Exposed to",
+  "com_tools_field_flags": "Switches",
+  "com_tools_field_enabled": "Enabled",
+  "com_tools_field_dangerous": "Dangerous (requires confirmation)",
+  "com_tools_field_parameters": "Parameters (JSON Schema)",
+  "com_tools_parameters_hint": "Must be a type:object JSON Schema; the tool form and the MCP inputSchema derive from it.",
+  "com_tools_field_form": "Form hints (JSON)",
+  "com_tools_form_hint": "Optional UI hints: field order, labels, widgets.",
+  "com_tools_field_exec_kind": "Execution",
+  "com_tools_field_handler": "Handler",
+  "com_tools_field_dist_owner": "Gitea owner (user / org)",
+  "com_tools_field_dist_repo": "Gitea repository",
+  "com_tools_field_dist_extra": "Supplementary fields (fill manually when repo tool.json is missing)",
+  "com_tools_field_dist_version": "Version",
+  "com_tools_field_dist_sha256": "Package SHA-256",
+  "com_tools_field_dist_launcher": "Launcher entry",
+  "com_tools_field_dist_runtime": "Runtime",
+  "com_tools_dist_hint": "The tool package is distributed via this repo's Releases: description/version/hash come from the repo's tool.json, with these fields as fallback.",
+  "com_tools_field_timeout": "Timeout (seconds)",
+  "com_tools_field_renderer": "Result renderer",
+  "com_tools_field_redact": "Redact params",
+  "com_tools_redact_hint": "Comma-separated parameter names to mask in audit summaries.",
+  "com_tools_field_result_config": "Renderer config (JSON)",
+  "com_tools_result_config_hint": "Renderer-private config, e.g. table columns.",
+  "com_tools_err_tool_id": "Tool ID is required.",
+  "com_tools_err_display_name": "Display name is required.",
+  "com_tools_err_parameters_json": "Parameters must be valid JSON.",
+  "com_tools_err_form_json": "Form hints must be valid JSON.",
+  "com_tools_err_result_config_json": "Renderer config must be valid JSON.",
+  "com_tools_err_handler": "Select a handler.",
+  "com_tools_err_owner_repo": "Desktop tools require the Gitea owner and repository.",
+  "com_tools_err_sha256": "SHA-256 must be 64 hexadecimal characters.",
+  "com_tools_err_renderer": "Result renderer is required.",
+  "com_tools_gitea_import_title": "Import tool from Gitea",
+  "com_tools_gitea_url": "Gitea URL",
+  "com_tools_gitea_url_hint": "Leave empty for the gateway default; press Enter or blur to re-fetch the listing.",
+  "com_tools_gitea_loading": "Loading visible owners and repositories…",
+  "com_tools_gitea_owner": "Owner (user / org)",
+  "com_tools_gitea_repo": "Repository",
+  "com_tools_gitea_select_owner": "Select owner",
+  "com_tools_gitea_select_repo": "Select repository",
+  "com_tools_gitea_check": "Check & import",
+  "com_tools_gitea_manual_create": "Create manually",
+  "com_tools_gitea_release": "Release",
+  "com_tools_gitea_installable": "Ready to install",
+  "com_tools_gitea_not_installable": "Needs supplementary fields before install",
+  "com_tools_gitea_check_failed": "Check failed: hard problems (red items) must be fixed in the repo first.",
+  "com_tools_gitea_back": "Back to selection",
+  "com_tools_gitea_continue": "Continue editing",
+  "com_tools_gitea_prefill_hint": "The information above will be prefilled into the edit dialog — review, adjust and save.",
+  "com_tools_import_title": "Import tools",
+  "com_tools_import_hint": "Import tool manifests (JSON) from the gateway seed directory or another environment.",
+  "com_tools_import_upload": "Upload files",
+  "com_tools_import_paste": "Paste JSON",
+  "com_tools_import_pick": "Choose .json files",
+  "com_tools_import_pick_hint": "One manifest per file; multiple files allowed",
+  "com_tools_import_no_files": "No manifest files selected.",
+  "com_tools_import_no_paste": "Paste at least one manifest.",
+  "com_tools_import_bad_json": "Not valid JSON",
+  "com_tools_import_count": "{{count}} manifests",
+  "com_tools_import_preview": "Preview import",
+  "com_tools_import_preview_desc": "Dry-run results — nothing has been written yet. Existing tools are skipped unless overwrite is checked.",
+  "com_tools_import_overwrite": "Overwrite existing tools",
+  "com_tools_import_apply": "Import",
+  "com_tools_import_apply_skip": "Import (skip existing)",
+  "com_tools_import_done": "Import finished.",
+  "com_tools_import_action": "Action",
+  "com_tools_import_detail": "Detail",
+  "com_tools_import_created": "Create",
+  "com_tools_import_updated": "Update",
+  "com_tools_import_skipped": "Skip",
+  "com_tools_import_failed": "Failed",
+  "com_tools_groups_hint": "Tool groups (display_group): both the arrangement and the visibility domain — a registered group can restrict which user groups see its tools (same semantics as service bindings). Sort order controls the toolbox sidebar.",
+  "com_tools_group_add_button": "Add group",
+  "com_tools_groups_empty": "No groups yet.",
+  "com_tools_group_implicit": "implicit",
+  "com_tools_drag_handle": "Drag to reorder",
+  "com_tools_group_detail_manage": "Manage group tools",
+  "com_tools_group_detail_left": "Not in group",
+  "com_tools_group_detail_right": "In group",
+  "com_tools_group_detail_add_ph": "Search and add tools to this group…",
+  "com_tools_group_detail_remove": "Remove from group",
+  "com_tools_group_detail_empty": "No tools in this group",
+  "com_tools_group_detail_add": "Add",
+  "com_tools_group_order_saving": "Saving order…",
+  "com_tools_group_tool_count": "{{count}} tools",
+  "com_tools_group_sort": "sort {{order}}",
+  "com_tools_group_add_title": "Add group",
+  "com_tools_group_edit_title": "Edit group",
+  "com_tools_group_field_name": "Namespace",
+  "com_tools_group_name_hint": "1–64 characters, no spaces or '|'; Chinese allowed. Immutable after creation.",
+  "com_tools_group_field_display_name": "Display name",
+  "com_tools_group_field_description": "Description",
+  "com_tools_group_field_sort_order": "Sort order",
+  "com_tools_group_sort_hint": "Smaller values appear first; implicit groups default to 1000.",
+  "com_tools_group_err_name": "Namespace may only contain lowercase letters, digits, - and _.",
+  "com_tools_group_delete_title": "Delete group",
+  "com_tools_group_delete_desc": "Delete group {{name}}? Only the metadata is removed; tools keep their IDs.",
+  "com_tools_group_delete_not_empty": "This group still contains {{count}} tools. Move or delete them first.",
+  "com_tools_pending_title": "Pending updates",
+  "com_tools_pending_hint": "Repo releases ahead of the approved manifest stay hidden from users until you review and confirm them here.",
+  "com_tools_pending_versions": "{{current}} → {{latest}}",
+  "com_tools_pending_checking": "Fetching repo details…",
+  "com_tools_pending_confirm": "Review & confirm",
+  "com_tools_pending_check_failed": "Repo check failed, update not opened: {{detail}}",
+  "com_tools_pending_check_warns": "Check warnings: {{detail}}",
+  "com_nav_usage": "Usage",
+  "com_usage_title": "Usage Statistics",
+  "com_usage_filter_tool": "Tool",
+  "com_usage_filter_user": "User ID",
+  "com_usage_col_time": "Time",
+  "com_usage_col_user": "User",
+  "com_usage_col_user_sub": "User ID",
+  "com_usage_col_tool": "Tool",
+  "com_usage_col_version": "Version",
+  "com_usage_col_status": "Status",
+  "com_usage_col_duration": "Duration",
+  "com_usage_source_mcp": "AI call (MCP)",
+  "com_usage_source_server": "Manual (toolbox)",
+  "com_usage_source_toolbox": "Local run",
+  "com_usage_col_arguments": "Argument keys",
+  "com_usage_col_source": "Source",
+  "com_usage_col_id": "Record ID",
+  "com_usage_status_succeeded": "Succeeded",
+  "com_usage_status_failed": "Failed",
+  "com_usage_status_stopped": "Stopped",
+  "com_usage_status_timeout": "Timed out",
+  "com_usage_empty": "No tool runs recorded yet.",
+  "com_usage_error": "Failed to load usage statistics.",
+  "com_usage_export": "Export CSV",
+  "com_usage_export_failed": "Export failed.",
+  "com_usage_export_truncated": "Export limited to the first {{count}} records.",
+  "com_usage_count": "{{count}} runs in total",
+  "com_tools_gitea_import_kind": "Tool type",
+  "com_tools_gitea_kind_desktop": "Desktop automation",
+  "com_tools_gitea_kind_plugin": "Extension plugin",
+  "com_tools_gitea_kind_web": "Web link",
+  "com_tools_field_web_url": "Tool URL",
+  "com_tools_gitea_web_url_hint": "Running a web tool opens this address in a new browser tab.",
+  "com_tools_gitea_url_hint_web": "Optional — picking a repo only prefills the name/description; the URL above is the tool itself.",
+  "com_tools_err_web_url": "Tool URL must start with http(s)://",
+  "com_tools_err_host_launcher": "Plugin requires the host executable path (relative to the host root)",
+  "com_tools_field_dist_host_launcher": "Host executable (relative to host root)",
+  "com_tools_field_dist_host_hints": "Host root candidates (one per line)",
+  "com_tools_field_dist_install_script": "Install script (optional)",
+  "com_tools_field_dist_uninstall_script": "Uninstall script (optional)",
+  "com_nav_services": "Services",
+  "com_services_title": "Service Registry",
+  "com_services_hint": "One binding = one map (map service) or one datasource (data service). Saving probes availability; end users only see bindings visible to their groups.",
+  "com_services_add_button": "Bind service",
+  "com_services_empty": "No services bound yet.",
+  "com_services_add_title": "Bind service",
+  "com_services_edit_title": "Edit binding",
+  "com_services_field_type": "Service type",
+  "com_services_type_map": "Map service",
+  "com_services_type_all": "All",
+  "com_services_type_data": "Data service",
+  "com_services_type_hint": "Map services bind per map; data services bind per datasource (all its datasets included). M1 supports iServer REST.",
+  "com_services_field_name": "Display name",
+  "com_services_field_base_url": "iServer base URL",
+  "com_services_field_service_path": "Service path",
+  "com_services_path_hint_map": "Map path after iserver/services/, e.g. dom/rest/maps/dom",
+  "com_services_path_hint_data": "Data service root after iserver/services/, e.g. data-BeiJing/rest/data",
+  "com_services_field_datasource": "Datasource",
+  "com_services_datasource_hint": "Required for data services; the datasource name inside the workspace (e.g. BeiJing).",
+  "com_services_field_allowed_groups": "Visible groups",
+  "com_services_groups_hint": "The binding is visible to members of the selected groups; All means every signed-in user.",
+  "com_services_group_custom_placeholder": "Custom group name",
+  "com_services_group_add": "Add",
+  "com_services_field_enabled": "Enabled",
+  "com_services_disabled": "Disabled",
+  "com_services_probe": "Re-probe",
+  "com_services_status_available": "Available",
+  "com_services_status_unavailable": "Unavailable",
+  "com_services_status_unprobed": "Unprobed",
+  "com_services_delete_title": "Delete binding",
+  "com_services_delete_desc": "Deleting \"{name}\" hides it from end users immediately; past runs are unaffected.",
+  "com_services_err_required": "Display name, base URL and service path are required",
+  "com_services_err_datasource": "Data service bindings need a datasource",
+  "com_services_err_groups": "Select at least one visible group",
+  "com_dash_tools_desc": "Manage the tool catalog, groups and visibility.",
+  "com_dash_usage_desc": "Tool usage statistics and run history.",
+  "com_dash_services_desc": "Bind map/data services and manage visibility.",
+  "com_tools_field_display_group": "Display group",
+  "com_tools_display_group_hint": "Pick the tool's group; the group's allowed-groups setting decides who can see this tool (managed on the Groups tab).",
+  "com_tools_display_group_none": "No group",
+  "com_tools_field_help_url": "Help URL",
+  "com_tools_field_usage_stats": "Usage stats",
+  "com_tools_group_allowed_groups": "Allowed user groups for this group's tools",
+  "com_tools_group_allowed_hint": "None selected = no restriction (visible to everyone). Only tools assigned to this group are affected.",
+  "com_services_basemap": "Basemap",
+  "com_services_basemap_set": "Set as basemap",
+  "com_services_basemap_clear": "Unset basemap",
+  "com_services_field_map_name": "Map name (optional)",
+  "com_services_map_name_hint": "e.g. dom",
+  "com_services_map_name_hint2": "Empty = service-level binding (maps listed when adding layers); required to set as basemap.",
+  "com_services_discover": "Discover",
+  "com_services_discover_title": "Discover services from an iServer base URL",
+  "com_services_discover_base": "iServer base URL",
+  "com_services_discover_base_hint": "e.g. http://192.168.5.28:8090 (with or without /iserver)",
+  "com_services_discover_run": "Discover",
+  "com_services_discover_bind": "Bind selected",
+  "com_services_discover_running": "Discovering…",
+  "com_services_discover_maps_n": "{n} maps",
+  "com_services_discover_ds_n": "{n} datasources",
+  "com_services_discover_unavailable": "unavailable",
+  "com_services_discover_empty": "No bindable REST services at this base URL",
+  "com_services_field_service_url": "Service URL",
+  "com_services_service_url_hint": "Full URL, e.g. http://192.168.5.28:8090/iserver/services/data-BeiJing/rest/data",
+  "com_services_basemap_section": "Basemap settings",
+  "com_services_basemap_list_maps": "List maps",
+  "com_services_basemap_save": "Save as basemap group",
+  "com_services_basemap_current": "Current basemap group",
+  "com_services_basemap_none": "No basemap configured",
+  "com_services_list_datasources": "List datasources",
+  "com_services_basemap_saved": "Basemap group saved",
+  "com_services_tab_bindings": "Bindings",
+  "com_services_tab_basemaps": "Basemaps",
+  "com_basemaps_hint": "The basemap group renders at the bottom of the map in order (first = bottom; stack imagery and annotation layers). Refresh the map browser after changes.",
+  "com_basemaps_current": "Current basemap group",
+  "com_basemaps_order_hint": "(bottom to top)",
+  "com_basemaps_pick": "Pick maps from bound map services",
+  "com_basemaps_pick_service": "Pick a service",
+  "com_basemaps_pick_layer": "Pick maps",
+  "com_basemaps_pick_layer_of": "Maps of {{service}}",
+  "com_basemaps_search": "Search",
+  "com_param_add": "Add parameter",
+  "com_param_add_string": "String",
+  "com_param_add_number": "Number",
+  "com_param_add_integer": "Integer",
+  "com_param_add_boolean": "Boolean",
+  "com_param_add_array_multiselect": "Multi-select array",
+  "com_param_type_string": "String",
+  "com_param_type_number": "Number",
+  "com_param_type_integer": "Integer",
+  "com_param_type_boolean": "Boolean",
+  "com_param_type_array": "Array",
+  "com_param_field_accept": "accept extensions",
+  "com_param_add_textarea": "Multiline text",
+  "com_param_add_date": "Date",
+  "com_param_add_datetime": "Date & time",
+  "com_param_add_file": "File",
+  "com_param_add_directory": "Directory",
+  "com_param_add_upload": "Cloud file",
+  "com_param_add_hidden": "Hidden value",
+  "com_param_field_name": "Name",
+  "com_param_field_label": "Label",
+  "com_param_field_help": "Help",
+  "com_param_field_placeholder": "Placeholder",
+  "com_param_field_default": "Default",
+  "com_param_field_widget": "Widget",
+  "com_param_widget_auto": "Auto (text)",
+  "com_param_widget_textarea": "Multiline",
+  "com_param_widget_date": "Date",
+  "com_param_widget_datetime": "Date & time",
+  "com_param_widget_file": "File",
+  "com_param_widget_directory": "Directory",
+  "com_param_widget_upload": "Cloud file",
+  "com_param_widget_hidden": "Hidden",
+  "com_param_required": "Required",
+  "com_param_enum": "Enum options (dropdown)",
+  "com_param_enum_add": "+ option",
+  "com_param_choices": "Static options",
+  "com_param_choices_static": "Static list",
+  "com_param_choices_from": "Dynamic source (choices_from)",
+  "com_param_choices_from_hint": "e.g. spatial.registry_layers",
+  "com_param_mode_visual": "Visual editor",
+  "com_param_mode_json": "JSON",
+  "com_param_json_error": "Invalid JSON — fix it to use the visual editor",
+  "com_param_name_invalid": "Name may only contain letters, digits, underscore, dot, hyphen and must be unique",
+  "com_param_empty": "No parameters yet — use “Add parameter” above",
+  "com_param_type": "Type"
 }
diff --git a/src/locales/i18n.ts b/src/locales/i18n.ts
index 4b261ee0..37254c0d 100644
--- a/src/locales/i18n.ts
+++ b/src/locales/i18n.ts
@@ -1,27 +1,76 @@
 import i18n from 'i18next';
 import { initReactI18next } from 'react-i18next';
-import LanguageDetector from 'i18next-browser-languagedetector';
 import translationEn from './en/translation.json';
+import translationZhHans from './zh-Hans/translation.json';
 
 export const defaultNS = 'translation';
 
+export const supportedLocales = ['en', 'zh-Hans'] as const;
+export type SupportedLocale = (typeof supportedLocales)[number];
+
 export const resources = {
   en: { translation: translationEn },
+  'zh-Hans': { translation: translationZhHans },
 } as const;
 
-i18n
-  .use(LanguageDetector)
-  .use(initReactI18next)
-  .init({
-    fallbackLng: {
-      default: ['en'],
-    },
-    fallbackNS: 'translation',
-    ns: ['translation'],
-    debug: false,
-    defaultNS,
-    resources,
-    interpolation: { escapeValue: false },
-  });
+const supportedByLowercase: Record<string, SupportedLocale> = Object.fromEntries(
+  supportedLocales.map((locale) => [locale.toLowerCase(), locale]),
+);
+
+// Mirrors LibreChat's client locale normalization: exact supported match first,
+// then alias table, then the base-language entry.
+const localeAliases: Record<string, SupportedLocale> = {
+  zh: 'zh-Hans',
+  'zh-cn': 'zh-Hans',
+  'zh-sg': 'zh-Hans',
+};
+
+export function normalizeLocale(locale?: string | null): SupportedLocale {
+  if (!locale) {
+    return 'en';
+  }
+  const normalized = locale.replace(/_/g, '-').toLowerCase();
+  const exact = supportedByLowercase[normalized];
+  if (exact) {
+    return exact;
+  }
+  return localeAliases[normalized] ?? localeAliases[normalized.split('-')[0]] ?? 'en';
+}
+
+// A stored choice (i18nextLng, written by the settings language selector) wins;
+// otherwise fall back to the browser language. SSR has no reliable locale
+// signal (Bun defines `navigator` but leaves `language` empty), so it always
+// renders the default locale and the browser takes over on hydration.
+export function detectInitialLanguage(): SupportedLocale {
+  if (typeof window === 'undefined') {
+    return 'en';
+  }
+  const stored = localStorage.getItem('i18nextLng');
+  if (stored) {
+    return normalizeLocale(stored);
+  }
+  return normalizeLocale(navigator.language || navigator.languages?.[0]);
+}
+
+const initialLanguage = detectInitialLanguage();
+
+i18n.use(initReactI18next).init({
+  lng: initialLanguage,
+  supportedLngs: [...supportedLocales],
+  fallbackLng: {
+    zh: ['zh-Hans'],
+    default: ['en'],
+  },
+  fallbackNS: 'translation',
+  ns: ['translation'],
+  debug: false,
+  defaultNS,
+  resources,
+  interpolation: { escapeValue: false },
+});
+
+if (typeof document !== 'undefined') {
+  document.documentElement.lang = initialLanguage;
+}
 
 export default i18n;
diff --git a/src/locales/locales.test.ts b/src/locales/locales.test.ts
new file mode 100644
index 00000000..94dda990
--- /dev/null
+++ b/src/locales/locales.test.ts
@@ -0,0 +1,65 @@
+/**
+ * Guards locale parity between en and zh-Hans: identical key sets,
+ * matching interpolation placeholders, and a working language switch.
+ */
+import { describe, it, expect } from 'vitest';
+import i18n, { normalizeLocale, detectInitialLanguage } from './i18n';
+import en from './en/translation.json';
+import zhHans from './zh-Hans/translation.json';
+
+const enKeys = Object.keys(en).sort();
+const zhKeys = Object.keys(zhHans).sort();
+
+describe('locale parity (en / zh-Hans)', () => {
+  it('zh-Hans defines the same key set as en', () => {
+    expect(zhKeys).toEqual(enKeys);
+  });
+
+  it('interpolation placeholders match en for every key', () => {
+    const re = /\{\{[^}]+\}\}/g;
+    const mismatches = enKeys.filter(
+      (key) =>
+        (String(en[key as keyof typeof en]).match(re) ?? []).sort().join() !==
+        (String(zhHans[key as keyof typeof zhHans]).match(re) ?? []).sort().join(),
+    );
+    expect(mismatches).toHaveLength(0);
+  });
+
+  it('switches to zh-Hans and back', async () => {
+    await i18n.changeLanguage('zh-Hans');
+    expect(i18n.t('com_ui_save')).toBe(zhHans['com_ui_save']);
+    await i18n.changeLanguage('en');
+    expect(i18n.t('com_ui_save')).toBe(en['com_ui_save']);
+  });
+
+  it('resolves browser-style zh codes to zh-Hans', async () => {
+    await i18n.changeLanguage('zh-CN');
+    expect(i18n.t('com_ui_save')).toBe(zhHans['com_ui_save']);
+    await i18n.changeLanguage('zh');
+    expect(i18n.t('com_ui_save')).toBe(zhHans['com_ui_save']);
+    await i18n.changeLanguage('en');
+    expect(i18n.t('com_ui_save')).toBe(en['com_ui_save']);
+  });
+});
+
+describe('locale normalization (LibreChat-style)', () => {
+  it('maps exact, alias, and base-language codes to supported locales', () => {
+    expect(normalizeLocale(null)).toBe('en');
+    expect(normalizeLocale('en')).toBe('en');
+    expect(normalizeLocale('en-US')).toBe('en');
+    expect(normalizeLocale('zh-CN')).toBe('zh-Hans');
+    expect(normalizeLocale('zh')).toBe('zh-Hans');
+    expect(normalizeLocale('zh-Hans')).toBe('zh-Hans');
+    expect(normalizeLocale('zh_TW')).toBe('zh-Hans');
+    expect(normalizeLocale('zh-TW')).toBe('zh-Hans');
+    expect(normalizeLocale('fr')).toBe('en');
+  });
+
+  it('prefers a stored choice over the browser language', () => {
+    localStorage.setItem('i18nextLng', 'zh-Hans');
+    expect(detectInitialLanguage()).toBe('zh-Hans');
+    localStorage.setItem('i18nextLng', 'en');
+    expect(detectInitialLanguage()).toBe('en');
+    localStorage.removeItem('i18nextLng');
+  });
+});
diff --git a/src/locales/zh-Hans/translation.json b/src/locales/zh-Hans/translation.json
new file mode 100644
index 00000000..7640a9f0
--- /dev/null
+++ b/src/locales/zh-Hans/translation.json
@@ -0,0 +1,1567 @@
+{
+  "com_ui_read_more": "查看更多",
+  "com_ui_add_item": "添加{{item}}",
+  "com_ui_delete": "删除",
+  "com_ui_clear": "清除",
+  "com_a11y_clear_dates": "清除日期筛选",
+  "com_a11y_copy_failed": "复制失败。你的浏览器可能阻止了剪贴板访问。",
+  "com_audit_detail_copied": "已复制！",
+  "com_ui_remove_item": "移除{{name}}",
+  "com_ui_save": "保存",
+  "com_ui_add": "添加",
+  "com_ui_cancel": "取消",
+  "com_ui_create": "创建",
+  "com_ui_retry": "重试",
+  "com_ui_done": "完成",
+  "com_ui_back": "返回",
+  "com_ui_close": "关闭",
+  "com_ui_enabled": "已启用",
+  "com_ui_disabled": "已禁用",
+  "com_ui_no_items": "未配置任何{{item}}",
+  "com_ui_search": "搜索",
+  "com_ui_loading": "加载中...",
+  "com_ui_select": "选择...",
+  "com_ui_enter_value": "输入值...",
+  "com_ui_enter_number": "输入数字...",
+  "com_ui_enter_text": "输入文本...",
+  "com_ui_enter_url": "https://...",
+  "com_ui_key": "键",
+  "com_ui_value": "值",
+  "com_ui_entry": "条目",
+  "com_ui_item": "条目",
+  "com_ui_sign_out": "退出登录",
+  "com_ui_signing_out": "正在退出登录...",
+  "com_ui_items_count": "{{count}} 项",
+  "com_ui_properties_count": "{{count}} 个属性",
+  "com_ui_invalid_json": "无效的 JSON",
+  "com_ui_invalid_yaml": "无效的 YAML",
+  "com_ui_dismiss": "关闭",
+  "com_ui_edit_json": "以 JSON 编辑...",
+  "com_ui_edit_yaml": "以 YAML 编辑...",
+  "com_ui_true": "是",
+  "com_ui_false": "否",
+  "com_ui_reset": "重置",
+  "com_nav_user_menu": "用户菜单",
+  "com_nav_users": "用户",
+  "com_nav_groups": "群组",
+  "com_nav_access": "访问管理",
+  "com_nav_configuration": "配置",
+  "com_nav_all_configuration": "全部配置",
+  "com_nav_help": "帮助",
+  "com_nav_go_home": "回到首页",
+  "com_config_title": "配置",
+  "com_config_subtitle": "查看和管理实例配置设置",
+  "com_config_loading": "正在加载配置...",
+  "com_config_select_section": "选择一个区块查看配置",
+  "com_config_no_results": "未找到配置",
+  "com_config_local_changes": "示例横幅：管理面板即将上线！",
+  "com_config_discard": "放弃更改",
+  "com_config_save": "保存",
+  "com_config_unsaved_changes": "未保存的更改",
+  "com_config_unsaved_leave": "有未保存的更改。仍要离开吗？",
+  "com_config_confirm_save_title": "将更改保存到基础配置？",
+  "com_config_field_change_count": "{{count}} 个字段将被更新",
+  "com_config_field_change_count_plural": "{{count}} 个字段将被更新",
+  "com_config_field_path": "字段",
+  "com_config_field_before": "变更前",
+  "com_config_field_after": "变更后",
+  "com_config_field_added": "已添加",
+  "com_config_field_removed": "已移除",
+  "com_config_field_not_set": "未设置",
+  "com_config_complex_array": "复杂数组编辑即将上线",
+  "com_config_no_fields": "此区块没有字段",
+  "com_config_no_entries": "未配置任何条目",
+  "com_config_customize": "自定义",
+  "com_config_add_field": "添加字段",
+  "com_config_select_field": "选择字段...",
+  "com_config_more_settings": "更多设置",
+  "com_config_create_endpoint": "创建端点",
+  "com_config_no_custom_endpoints": "未配置自定义端点",
+  "com_config_no_mcp_servers": "未配置 MCP 服务器",
+  "com_config_endpoint_name_required": "端点名称为必填项",
+  "com_config_create_mcp_server": "创建MCP服务器",
+  "com_config_server_name": "服务器名称",
+  "com_config_server_name_required": "服务器名称为必填项",
+  "com_config_server_name_exists": "已存在同名服务器",
+  "com_config_server_name_no_dots": "服务器名称不能包含点号",
+  "com_config_server_name_invalid": "服务器名称不被允许",
+  "com_config_server_missing_required": "缺少必填字段：{{field}}",
+  "com_config_mcp_invalid_after_edit": "无法保存：MCP 服务器“{{entry}}”缺少其传输类型所需的字段“{{field}}”。",
+  "com_config_group_connection": "连接",
+  "com_config_group_authentication": "认证",
+  "com_config_group_api_key": "API 密钥",
+  "com_config_group_oauth": "OAuth 配置",
+  "com_config_group_server_options": "服务器选项",
+  "com_config_group_models": "模型",
+  "com_config_group_title_generation": "标题生成",
+  "com_config_group_summarization": "摘要",
+  "com_config_group_advanced": "高级",
+  "com_config_on_this_page": "本页内容",
+  "com_config_expand_all": "全部展开",
+  "com_config_collapse_all": "全部折叠",
+  "com_config_show_toolbar": "显示工具栏",
+  "com_config_minimize": "最小化",
+  "com_config_configured": "已配置",
+  "com_config_default": "默认",
+  "com_config_reset_default": "重置为默认值",
+  "com_config_reset_confirm": "将“{{field}}”重置为默认值？这将移除数据库中的覆盖值。",
+  "com_config_reset_base": "重置为默认值",
+  "com_config_reset_base_title": "重置基础配置",
+  "com_config_reset_base_confirm": "默认情况下，基础配置以本实例的 librechat.yaml 文件（未配置该文件时为内置默认值）为起点，并被你在管理面板中所做的更改覆盖。此操作会将基础配置重置回该起点，且无法撤销。",
+  "com_config_reset_base_action": "重置为默认值",
+  "com_config_reset_base_resetting": "正在重置...",
+  "com_config_reset_base_success": "基础配置已重置为 librechat.yaml",
+  "com_config_reset_base_dirty": "重置前请先保存或放弃更改",
+  "com_config_section_configured_count": "已配置 {{count}}/{{total}} 项",
+  "com_config_default_hint": "（默认：{{value}}）",
+  "com_config_entry_n": "条目 {{n}}",
+  "com_config_mode_simple": "简单",
+  "com_config_mode_advanced": "高级",
+  "com_config_mode_i18n": "按语言",
+  "com_config_mode_multi": "多行",
+  "com_config_simplify_disabled": "切换到简单模式前，请先移除多余的语言条目",
+  "com_config_show_configured_only": "仅显示已配置项",
+  "com_config_saving": "保存中...",
+  "com_config_saved": "更改已保存",
+  "com_config_save_error": "保存失败",
+  "com_toast_group_created": "群组“{{name}}”已创建",
+  "com_toast_group_updated": "群组“{{name}}”已更新",
+  "com_toast_group_deleted": "群组“{{name}}”已删除",
+  "com_toast_role_created": "角色“{{name}}”已创建",
+  "com_toast_role_updated": "角色“{{name}}”已更新",
+  "com_toast_role_deleted": "角色“{{name}}”已删除",
+  "com_toast_user_invited": "用户“{{name}}”已邀请",
+  "com_toast_user_deleted": "用户“{{name}}”已删除",
+  "com_toast_role_assigned": "已添加到角色“{{name}}”",
+  "com_toast_role_unassigned": "已从角色“{{name}}”移除",
+  "com_toast_group_assigned": "已添加到群组“{{name}}”",
+  "com_toast_group_unassigned": "已从群组“{{name}}”移除",
+  "com_toast_user_profile_created": "已为“{{name}}”创建用户配置档案",
+  "com_toast_user_profile_deleted": "用户配置档案已删除",
+  "com_toast_capabilities_saved": "“{{name}}”的能力已保存",
+  "com_toast_profile_value_saved": "配置档案值已保存",
+  "com_toast_profile_value_removed": "配置档案值已移除",
+  "com_toast_tool_created": "工具已创建",
+  "com_toast_tool_updated": "工具已更新",
+  "com_config_import_yaml": "导入 YAML",
+  "com_config_import_yaml_title": "导入配置",
+  "com_config_import_yaml_desc": "上传或粘贴 librechat.yaml 文件，以填充界面中的配置值。",
+  "com_config_import_upload": "上传文件",
+  "com_config_import_paste": "粘贴 YAML",
+  "com_config_import_choose_file": "选择 .yaml 或 .yml 文件",
+  "com_config_import_paste_placeholder": "在此粘贴你的 YAML 配置...",
+  "com_config_import_validate": "校验并导入",
+  "com_config_import_success": "配置导入成功。",
+  "com_config_import_error": "导入失败",
+  "com_config_import_target": "导入目标",
+  "com_config_import_apply": "应用",
+  "com_config_import_back": "后退",
+  "com_config_import_as_base": "基础配置",
+  "com_config_import_as_base_desc": "更新 librechat.yaml 中的默认设置",
+  "com_config_import_as_profile": "配置档案",
+  "com_config_import_as_profile_desc": "将导入的值应用为特定作用域的配置档案设置",
+  "com_config_import_create_scope": "新建",
+  "com_config_import_scope_name": "名称",
+  "com_config_import_scope_name_placeholder": "例如：QA 团队",
+  "com_config_import_scope_type": "类型",
+  "com_config_import_scope_priority": "优先级",
+  "com_config_import_profile_success": "已为 {{name}} 导入 {{count}} 项配置档案值",
+  "com_config_import_creating": "正在创建作用域...",
+  "com_config_import_saving": "正在保存配置档案值...",
+  "com_config_tab_files": "文件与存储",
+  "com_config_tab_endpoints": "端点",
+  "com_config_tab_custom_endpoints": "自定义端点",
+  "com_config_tab_ai_providers": "AI 提供商",
+  "com_config_tab_model_specs": "模型规格",
+  "com_config_tab_mcp": "MCP",
+  "com_config_tab_features": "功能",
+  "com_config_tab_system": "系统设置",
+  "com_config_tab_other": "其他",
+  "com_config_section_interface": "界面",
+  "com_config_section_interface_desc": "外观与行为",
+  "com_config_interface_permissions_info": "功能访问权限（提示词、智能体、市场等）请在“访问管理 > 角色”中按角色配置。",
+  "com_config_section_registration": "注册",
+  "com_config_section_registration_desc": "用户注册选项",
+  "com_config_section_speech": "语音",
+  "com_config_section_speech_desc": "TTS 与 STT 设置",
+  "com_config_section_model_specs": "模型规格",
+  "com_config_section_model_specs_desc": "AI 模型配置",
+  "com_config_section_mcp_servers": "MCP 服务器",
+  "com_config_section_mcp_servers_desc": "服务器配置",
+  "com_config_section_rate_limits": "速率限制",
+  "com_config_section_rate_limits_desc": "API 限流规则",
+  "com_config_section_balance": "余额",
+  "com_config_section_balance_desc": "Token 与积分限额",
+  "com_config_section_file_config": "文件配置",
+  "com_config_section_file_config_desc": "上传与存储设置",
+  "com_config_section_actions": "操作",
+  "com_config_section_actions_desc": "智能体操作处理器",
+  "com_config_section_web_search": "网络搜索",
+  "com_config_section_web_search_desc": "搜索提供商设置",
+  "com_config_section_ocr": "OCR",
+  "com_config_section_ocr_desc": "文字识别",
+  "com_config_section_turnstile": "Turnstile",
+  "com_config_section_turnstile_desc": "验证码设置",
+  "com_config_section_cache": "缓存",
+  "com_config_section_cache_desc": "性能缓存",
+  "com_config_section_version": "版本",
+  "com_config_section_version_desc": "配置版本",
+  "com_config_section_file_strategy": "文件策略",
+  "com_config_section_file_strategy_desc": "存储策略",
+  "com_config_section_endpoints": "端点",
+  "com_config_section_endpoints_desc": "自定义端点",
+  "com_config_section_ai_providers": "AI 提供商",
+  "com_config_section_ai_providers_desc": "内置 AI 提供商连接",
+  "com_config_section_memory": "记忆",
+  "com_config_section_memory_desc": "个性化设置",
+  "com_config_section_mcp_settings": "MCP 设置",
+  "com_config_section_mcp_settings_desc": "安全与域名",
+  "com_config_section_transactions": "交易记录",
+  "com_config_section_transactions_desc": "日志设置",
+  "com_config_field_optional": "可选",
+  "com_config_field_version": "版本",
+  "com_config_field_cache": "缓存",
+  "com_config_field_pinned": "已固定",
+  "com_config_field_promptCacheTtl": "提示词缓存 TTL",
+  "com_config_field_ocr": "OCR",
+  "com_config_field_webSearch": "网络搜索",
+  "com_config_field_memory": "记忆",
+  "com_config_field_secureImageLinks": "安全图片链接",
+  "com_config_field_imageOutputType": "图片输出类型",
+  "com_config_field_includedTools": "包含的工具",
+  "com_config_field_filteredTools": "排除的工具",
+  "com_config_field_defaultPinnedTools": "默认固定工具",
+  "com_config_field_snapshotFiles": "快照文件",
+  "com_config_field_mcpServers": "MCP 服务器",
+  "com_config_field_mcpSettings": "MCP 设置",
+  "com_config_field_interface": "界面",
+  "com_config_field_turnstile": "Turnstile",
+  "com_config_field_fileStrategy": "文件策略",
+  "com_config_field_fileStrategies": "文件策略",
+  "com_config_field_actions": "操作",
+  "com_config_field_registration": "注册",
+  "com_config_field_balance": "余额",
+  "com_config_field_transactions": "交易记录",
+  "com_config_field_speech": "语音",
+  "com_config_field_rateLimits": "速率限制",
+  "com_config_field_fileConfig": "文件配置",
+  "com_config_field_modelSpecs": "模型规格",
+  "com_config_field_endpoints": "端点",
+  "com_config_field_apiKey": "API 密钥",
+  "com_config_field_baseURL": "基础 URL",
+  "com_config_field_url": "URL",
+  "com_config_field_enabled": "已启用",
+  "com_config_field_disabled": "已禁用",
+  "com_config_field_model": "模型",
+  "com_config_field_models": "模型",
+  "com_config_field_name": "名称",
+  "com_config_field_label": "标签",
+  "com_config_field_description": "描述",
+  "com_config_field_timeout": "超时",
+  "com_config_field_headers": "请求头",
+  "com_config_field_language": "语言",
+  "com_config_field_languages": "语言",
+  "com_config_field_region": "区域",
+  "com_config_field_country": "国家/地区",
+  "com_config_field_strategy": "策略",
+  "com_config_field_options": "选项",
+  "com_config_field_default": "默认",
+  "com_config_field_type": "类型",
+  "com_config_field_title": "标题",
+  "com_config_field_id": "ID",
+  "com_config_field_provider": "提供商",
+  "com_config_field_prompt": "提示词",
+  "com_config_field_placeholder": "占位符",
+  "com_config_field_quality": "质量",
+  "com_config_field_mistralModel": "Mistral 模型",
+  "com_config_field_serperApiKey": "Serper API 密钥",
+  "com_config_field_searxngInstanceUrl": "SearXNG 实例 URL",
+  "com_config_field_searxngApiKey": "SearXNG API 密钥",
+  "com_config_field_firecrawlApiKey": "Firecrawl API 密钥",
+  "com_config_field_firecrawlApiUrl": "Firecrawl API URL",
+  "com_config_field_firecrawlVersion": "Firecrawl 版本",
+  "com_config_field_jinaApiKey": "Jina API 密钥",
+  "com_config_field_jinaApiUrl": "Jina API URL",
+  "com_config_field_tavilyApiKey": "Tavily API 密钥",
+  "com_config_field_tavilySearchUrl": "Tavily 搜索 URL",
+  "com_config_field_cohereApiKey": "Cohere API 密钥",
+  "com_config_field_searchProvider": "搜索提供商",
+  "com_config_field_scraperProvider": "抓取器提供商",
+  "com_config_field_rerankerType": "重排序器类型",
+  "com_config_field_scraperTimeout": "抓取超时",
+  "com_config_field_safeSearch": "安全搜索",
+  "com_config_field_firecrawlOptions": "Firecrawl 选项",
+  "com_config_field_includeTags": "包含标签",
+  "com_config_field_excludeTags": "排除标签",
+  "com_config_field_waitFor": "等待目标",
+  "com_config_field_maxAge": "最大时效",
+  "com_config_field_mobile": "移动端",
+  "com_config_field_skipTlsVerification": "跳过 TLS 验证",
+  "com_config_field_blockAds": "拦截广告",
+  "com_config_field_removeBase64Images": "移除 Base64 图片",
+  "com_config_field_parsePDF": "解析 PDF",
+  "com_config_field_storeInCache": "存入缓存",
+  "com_config_field_zeroDataRetention": "零数据保留",
+  "com_config_field_location": "位置",
+  "com_config_field_onlyMainContent": "仅正文内容",
+  "com_config_field_changeTrackingOptions": "变更跟踪选项",
+  "com_config_field_formats": "格式",
+  "com_config_field_modes": "模式",
+  "com_config_field_schema": "Schema",
+  "com_config_field_tag": "标签",
+  "com_config_field_validKeys": "有效键",
+  "com_config_field_tokenLimit": "Token 限制",
+  "com_config_field_charLimit": "字符限制",
+  "com_config_field_personalize": "个性化",
+  "com_config_field_messageWindowSize": "消息窗口大小",
+  "com_config_field_agent": "智能体",
+  "com_config_field_instructions": "指令",
+  "com_config_field_model_parameters": "模型参数",
+  "com_config_field_privacyPolicy": "隐私政策",
+  "com_config_field_termsOfService": "服务条款",
+  "com_config_field_customWelcome": "自定义欢迎语",
+  "com_config_field_endpointsMenu": "端点菜单",
+  "com_config_field_modelSelect": "模型选择",
+  "com_config_field_parameters": "参数",
+  "com_config_field_sidePanel": "侧边栏",
+  "com_config_field_multiConvo": "多会话",
+  "com_config_field_bookmarks": "书签",
+  "com_config_field_memories": "记忆",
+  "com_config_field_presets": "预设",
+  "com_config_field_prompts": "提示词",
+  "com_config_field_agents": "智能体",
+  "com_config_field_temporaryChat": "临时对话",
+  "com_config_field_temporaryChatRetention": "临时对话保留时长",
+  "com_config_field_runCode": "运行代码",
+  "com_config_field_fileSearch": "文件搜索",
+  "com_config_field_fileCitations": "文件引用",
+  "com_config_field_peoplePicker": "人员选择器",
+  "com_config_field_marketplace": "市场",
+  "com_config_field_externalUrl": "外部 URL",
+  "com_config_field_openNewTab": "在新标签页打开",
+  "com_config_field_modalAcceptance": "弹窗确认",
+  "com_config_field_modalTitle": "弹窗标题",
+  "com_config_field_modalContent": "弹窗内容",
+  "com_config_field_use": "使用",
+  "com_config_field_create": "创建",
+  "com_config_field_share": "共享",
+  "com_config_field_trustCheckbox": "信任复选框",
+  "com_config_field_subLabel": "子标签",
+  "com_config_field_users": "用户",
+  "com_config_field_groups": "群组",
+  "com_config_field_roles": "角色",
+  "com_config_field_siteKey": "站点密钥",
+  "com_config_field_size": "大小",
+  "com_config_field_avatar": "头像",
+  "com_config_field_image": "图片",
+  "com_config_field_document": "文档",
+  "com_config_field_socialLogins": "社交登录",
+  "com_config_field_allowedDomains": "允许的域名",
+  "com_config_field_startBalance": "初始余额",
+  "com_config_field_autoRefillEnabled": "自动补充已启用",
+  "com_config_field_refillIntervalValue": "补充间隔值",
+  "com_config_field_refillIntervalUnit": "补充间隔单位",
+  "com_config_field_refillAmount": "补充额度",
+  "com_config_field_tts": "文字转语音",
+  "com_config_field_stt": "语音转文字",
+  "com_config_field_speechTab": "语音标签页",
+  "com_config_field_openai": "OpenAI",
+  "com_config_field_azureOpenAI": "Azure OpenAI",
+  "com_config_field_elevenlabs": "ElevenLabs",
+  "com_config_field_localai": "LocalAI",
+  "com_config_field_voices": "音色",
+  "com_config_field_instanceName": "实例名称",
+  "com_config_field_deploymentName": "部署名称",
+  "com_config_field_apiVersion": "API 版本",
+  "com_config_field_websocketUrl": "WebSocket URL",
+  "com_config_field_voice_settings": "音色设置",
+  "com_config_field_similarity_boost": "相似度提升",
+  "com_config_field_stability": "稳定性",
+  "com_config_field_use_speaker_boost": "使用说话人增强",
+  "com_config_field_pronunciation_dictionary_locators": "发音词典定位器",
+  "com_config_field_backend": "后端",
+  "com_config_field_conversationMode": "对话模式",
+  "com_config_field_advancedMode": "高级模式",
+  "com_config_field_speechToText": "语音转文字",
+  "com_config_field_textToSpeech": "文字转语音",
+  "com_config_field_engineSTT": "语音识别引擎",
+  "com_config_field_languageSTT": "语音识别语言",
+  "com_config_field_autoTranscribeAudio": "自动转录音频",
+  "com_config_field_decibelValue": "分贝值",
+  "com_config_field_autoSendText": "自动发送文本",
+  "com_config_field_engineTTS": "语音合成引擎",
+  "com_config_field_voice": "音色",
+  "com_config_field_languageTTS": "语音合成语言",
+  "com_config_field_automaticPlayback": "自动播放",
+  "com_config_field_playbackRate": "播放速率",
+  "com_config_field_cacheTTS": "缓存语音合成",
+  "com_config_field_fileUploads": "文件上传",
+  "com_config_field_conversationsImport": "会话导入",
+  "com_config_field_ipMax": "IP 上限",
+  "com_config_field_ipWindowInMinutes": "IP 时间窗口（分钟）",
+  "com_config_field_userMax": "用户上限",
+  "com_config_field_userWindowInMinutes": "用户时间窗口（分钟）",
+  "com_config_field_serverFileSizeLimit": "服务器文件大小限制",
+  "com_config_field_avatarSizeLimit": "头像大小限制",
+  "com_config_field_fileTokenLimit": "文件 Token 限制",
+  "com_config_field_imageGeneration": "图片生成",
+  "com_config_field_clientImageResize": "客户端图片缩放",
+  "com_config_field_supportedMimeTypes": "支持的 MIME 类型",
+  "com_config_field_maxWidth": "最大宽度",
+  "com_config_field_maxHeight": "最大高度",
+  "com_config_field_percentage": "百分比",
+  "com_config_field_fileLimit": "文件数量限制",
+  "com_config_field_fileSizeLimit": "文件大小限制",
+  "com_config_field_totalSizeLimit": "总大小限制",
+  "com_config_field_px": "像素",
+  "com_config_field_text": "文本",
+  "com_config_field_enforce": "强制执行",
+  "com_config_field_prioritize": "优先",
+  "com_config_field_addedEndpoints": "已添加端点",
+  "com_config_field_preset": "预设",
+  "com_config_field_order": "顺序",
+  "com_config_field_group": "群组",
+  "com_config_field_groupIcon": "分组图标",
+  "com_config_field_showIconInMenu": "在菜单中显示图标",
+  "com_config_field_showIconInHeader": "在顶栏显示图标",
+  "com_config_field_iconURL": "图标 URL",
+  "com_config_field_authType": "认证类型",
+  "com_config_field_executeCode": "执行代码",
+  "com_config_field_all": "全部",
+  "com_config_field_openAI": "OpenAI",
+  "com_config_field_google": "Google",
+  "com_config_field_anthropic": "Anthropic",
+  "com_config_field_azureAssistants": "Azure 助手",
+  "com_config_field_assistants": "助手",
+  "com_config_field_custom": "自定义",
+  "com_config_field_gptPlugins": "插件",
+  "com_config_field_bedrock": "Bedrock",
+  "com_config_field_streamRate": "流式速率",
+  "com_config_field_titlePrompt": "标题提示词",
+  "com_config_field_titleModel": "标题模型",
+  "com_config_field_titleConvo": "对话标题生成",
+  "com_config_field_titleMethod": "标题生成方式",
+  "com_config_field_titleEndpoint": "标题生成端点",
+  "com_config_field_titlePromptTemplate": "标题提示词模板",
+  "com_config_field_vertex": "Vertex",
+  "com_config_field_projectId": "项目 ID",
+  "com_config_field_serviceKeyFile": "服务密钥文件",
+  "com_config_field_disableBuilder": "禁用构建器",
+  "com_config_field_pollIntervalMs": "轮询间隔（毫秒）",
+  "com_config_field_timeoutMs": "超时（毫秒）",
+  "com_config_field_supportedIds": "支持的 ID",
+  "com_config_field_excludedIds": "排除的 ID",
+  "com_config_field_privateAssistants": "私有助手",
+  "com_config_field_retrievalModels": "检索模型",
+  "com_config_field_capabilities": "功能",
+  "com_config_field_fetch": "获取",
+  "com_config_field_userIdQuery": "用户 ID 查询",
+  "com_config_field_recursionLimit": "递归限制",
+  "com_config_field_maxRecursionLimit": "最大递归限制",
+  "com_config_field_maxCitations": "最大引用数",
+  "com_config_field_maxCitationsPerFile": "每文件最大引用数",
+  "com_config_field_minRelevanceScore": "最小相关度评分",
+  "com_config_field_allowedProviders": "允许的提供商",
+  "com_config_field_summarize": "摘要",
+  "com_config_field_summaryModel": "摘要模型",
+  "com_config_field_forcePrompt": "强制提示词",
+  "com_config_field_modelDisplayLabel": "模型显示标签",
+  "com_config_field_addParams": "附加参数",
+  "com_config_field_dropParams": "移除参数",
+  "com_config_field_customParams": "自定义参数",
+  "com_config_field_customOrder": "自定义顺序",
+  "com_config_field_directEndpoint": "直连端点",
+  "com_config_field_titleMessageRole": "标题消息角色",
+  "com_config_field_defaultParamsEndpoint": "默认参数端点",
+  "com_config_field_paramDefinitions": "参数定义",
+  "com_config_field_serverless": "无服务器",
+  "com_config_field_additionalHeaders": "附加请求头",
+  "com_config_field_startup": "启动",
+  "com_config_field_iconPath": "图标路径",
+  "com_config_field_initTimeout": "初始化超时",
+  "com_config_field_chatMenu": "聊天菜单",
+  "com_config_field_serverInstructions": "服务器指令",
+  "com_config_field_requiresOAuth": "需要 OAuth",
+  "com_config_field_command": "命令",
+  "com_config_field_args": "参数",
+  "com_config_field_env": "环境变量",
+  "com_config_field_availableRegions": "可用区域",
+  "com_config_field_maxToolResultChars": "工具结果最大字符数",
+  "com_config_field_key": "键",
+  "com_config_field_source": "来源",
+  "com_config_field_customUserVars": "自定义用户变量",
+  "com_config_field_sseReadTimeout": "SSE 读取超时",
+  "com_config_field_custom_header": "自定义请求头",
+  "com_config_field_authorization_type": "授权类型",
+  "com_config_field_authorization_url": "授权 URL",
+  "com_config_field_token_url": "令牌 URL",
+  "com_config_field_client_id": "客户端 ID",
+  "com_config_field_client_secret": "客户端密钥",
+  "com_config_field_scope": "权限范围",
+  "com_config_field_redirect_uri": "重定向 URI",
+  "com_config_field_token_exchange_method": "令牌交换方法",
+  "com_config_field_grant_types_supported": "支持的授权类型",
+  "com_config_field_token_endpoint_auth_methods_supported": "令牌端点认证方法",
+  "com_config_field_response_types_supported": "支持的响应类型",
+  "com_config_field_code_challenge_methods_supported": "代码质询方法",
+  "com_config_field_skip_code_challenge_check": "跳过代码质询检查",
+  "com_config_field_revocation_endpoint": "吊销端点",
+  "com_config_field_revocation_endpoint_auth_methods_supported": "吊销端点认证方法",
+  "com_config_field_oauth_headers": "OAuth 请求头",
+  "com_config_field_reserveRatio": "预留比例",
+  "com_config_field_maxSummaryTokens": "最大摘要 Token 数",
+  "com_config_field_updatePrompt": "更新提示词",
+  "com_config_field_trigger": "触发条件",
+  "com_config_field_value": "值",
+  "com_config_field_contextPruning": "上下文裁剪",
+  "com_config_field_keepLastAssistants": "保留最近的助手消息",
+  "com_config_field_softTrimRatio": "软裁剪比例",
+  "com_config_field_hardClearRatio": "硬清除比例",
+  "com_config_field_minPrunableToolChars": "可裁剪工具消息最小字符数",
+  "com_config_field_list": "列表",
+  "com_config_field_endpoint": "端点",
+  "com_config_field_endpointType": "端点类型",
+  "com_config_field_isArchived": "已归档",
+  "com_config_field_user": "用户",
+  "com_config_field_messages": "消息",
+  "com_config_field_tools": "工具",
+  "com_config_field_modelLabel": "模型标签",
+  "com_config_field_userLabel": "用户标签",
+  "com_config_field_promptPrefix": "提示词前缀",
+  "com_config_field_temperature": "温度",
+  "com_config_field_topP": "Top P",
+  "com_config_field_topK": "Top K",
+  "com_config_field_top_p": "Top P",
+  "com_config_field_frequency_penalty": "频率惩罚",
+  "com_config_field_presence_penalty": "存在惩罚",
+  "com_config_field_parentMessageId": "父消息 ID",
+  "com_config_field_maxOutputTokens": "最大输出 Token 数",
+  "com_config_field_maxContextTokens": "最大上下文 Token 数",
+  "com_config_field_max_tokens": "最大 Token 数",
+  "com_config_field_promptCache": "提示词缓存",
+  "com_config_field_system": "系统设置",
+  "com_config_field_thinking": "深度思考",
+  "com_config_field_thinkingBudget": "思考预算",
+  "com_config_field_stream": "流式输出",
+  "com_config_field_artifacts": "Artifacts",
+  "com_config_field_context": "上下文",
+  "com_config_field_examples": "示例",
+  "com_config_field_input": "输入",
+  "com_config_field_content": "内容",
+  "com_config_field_output": "输出",
+  "com_config_field_tags": "标签",
+  "com_config_field_resendFiles": "重发文件",
+  "com_config_field_file_ids": "文件 ID",
+  "com_config_field_imageDetail": "图片细节",
+  "com_config_field_reasoning_effort": "推理投入",
+  "com_config_field_reasoning_summary": "推理摘要",
+  "com_config_field_verbosity": "详细程度",
+  "com_config_field_useResponsesApi": "使用 Responses API",
+  "com_config_field_web_search": "网络搜索",
+  "com_config_field_url_context": "URL 上下文",
+  "com_config_field_disableStreaming": "禁用流式输出",
+  "com_config_field_assistant_id": "助手 ID",
+  "com_config_field_agent_id": "智能体 ID",
+  "com_config_field_maxTokens": "最大 Token 数",
+  "com_config_field_additionalModelRequestFields": "附加模型请求字段",
+  "com_config_field_additional_instructions": "附加指令",
+  "com_config_field_append_current_datetime": "附加当前日期时间",
+  "com_config_field_presetOverride": "预设覆盖",
+  "com_config_field_stop": "停止序列",
+  "com_config_field_greeting": "问候语",
+  "com_config_field_spec": "规格",
+  "com_config_field_expiredAt": "过期时间",
+  "com_config_field_resendImages": "重发图片",
+  "com_config_field_chatGptLabel": "ChatGPT 标签",
+  "com_config_field_conversationId": "会话 ID",
+  "com_config_field_presetId": "预设 ID",
+  "com_config_field_defaultPreset": "默认预设",
+  "com_config_field_style": "风格",
+  "com_config_field_public": "公开",
+  "com_config_field_remoteAgents": "远程智能体",
+  "com_config_field_effort": "投入",
+  "com_config_field_inferenceProfiles": "推理配置",
+  "com_config_field_messages_item": "消息",
+  "com_config_field_tags_item": "标签",
+  "com_config_field_file_ids_item": "文件 ID",
+  "com_config_field_stop_item": "停止序列",
+  "com_config_field_pronunciation_dictionary_locators_item": "定位器",
+  "com_config_field_includedTools_item": "工具",
+  "com_config_field_filteredTools_item": "工具",
+  "com_config_field_defaultPinnedTools_item": "工具",
+  "com_config_field_validKeys_item": "键",
+  "com_config_field_allowedDomains_item": "域名",
+  "com_config_field_socialLogins_item": "登录方式",
+  "com_config_field_voices_item": "音色",
+  "com_config_field_formats_item": "格式",
+  "com_config_field_includeTags_item": "标签",
+  "com_config_field_excludeTags_item": "标签",
+  "com_config_field_languages_item": "语言",
+  "com_config_field_modes_item": "模式",
+  "com_config_field_summarization": "摘要",
+  "com_config_field_oauth": "OAuth",
+  "com_config_field_stderr": "标准错误",
+  "com_config_field_thinkingLevel": "思考等级",
+  "com_config_field_showLabel": "显示标签",
+  "com_config_field_showDefault": "显示默认值",
+  "com_config_field_range": "取值范围",
+  "com_config_field_min": "最小值",
+  "com_config_field_max": "最大值",
+  "com_config_field_step": "步长",
+  "com_config_field_enumMappings": "枚举映射",
+  "com_config_field_component": "组件",
+  "com_config_field_optionType": "选项类型",
+  "com_config_field_columnSpan": "跨列数",
+  "com_config_field_columns": "列",
+  "com_config_field_labelCode": "标签代码",
+  "com_config_field_placeholderCode": "占位符代码",
+  "com_config_field_descriptionCode": "描述代码",
+  "com_config_field_minText": "最小值文本",
+  "com_config_field_maxText": "最大值文本",
+  "com_config_field_minTags": "最少标签数",
+  "com_config_field_maxTags": "最多标签数",
+  "com_config_field_includeInput": "包含输入",
+  "com_config_field_descriptionSide": "描述位置",
+  "com_config_field_searchPlaceholder": "搜索占位符",
+  "com_config_field_selectPlaceholder": "选择占位符",
+  "com_config_field_searchPlaceholderCode": "搜索占位符代码",
+  "com_config_field_selectPlaceholderCode": "选择占位符代码",
+  "com_config_field_grant_types_supported_item": "授权类型",
+  "com_config_field_token_endpoint_auth_methods_supported_item": "方法",
+  "com_config_field_response_types_supported_item": "响应类型",
+  "com_config_field_code_challenge_methods_supported_item": "方法",
+  "com_config_field_revocation_endpoint_auth_methods_supported_item": "方法",
+  "com_config_field_list_item": "条目",
+  "com_config_field_examples_item": "示例",
+  "com_config_field_groups_item": "群组",
+  "com_config_field_custom_item": "条目",
+  "com_config_field_paramDefinitions_item": "参数定义",
+  "com_config_field_options_item": "选项",
+  "com_config_field_dropParams_item": "参数",
+  "com_config_field_supportedIds_item": "ID",
+  "com_config_field_excludedIds_item": "ID",
+  "com_config_field_retrievalModels_item": "模型",
+  "com_config_field_models_item": "模型",
+  "com_config_field_allowedProviders_item": "提供商",
+  "com_config_field_addedEndpoints_item": "端点",
+  "com_config_field_supportedMimeTypes_item": "MIME 类型",
+  "com_config_field_args_item": "参数",
+  "com_config_field_availableRegions_item": "区域",
+  "com_config_field_mcpServers_item": "服务器",
+  "com_config_field_default_item": "条目",
+  "com_config_field_capabilities_item": "能力",
+  "com_config_field_tavilyExtractUrl": "Tavily 提取 URL",
+  "com_config_field_tavilySearchOptions": "Tavily 搜索选项",
+  "com_config_field_tavilyScraperOptions": "Tavily 抓取选项",
+  "com_config_field_searchDepth": "搜索深度",
+  "com_config_field_extractDepth": "提取深度",
+  "com_config_field_maxResults": "最大结果数",
+  "com_config_field_includeImages": "包含图片",
+  "com_config_field_includeImageDescriptions": "包含图片描述",
+  "com_config_field_includeFavicon": "包含网站图标",
+  "com_config_field_includeAnswer": "包含回答",
+  "com_config_field_includeRawContent": "包含原始内容",
+  "com_config_field_includeDomains": "包含域名",
+  "com_config_field_excludeDomains": "排除域名",
+  "com_config_field_topic": "主题",
+  "com_config_field_timeRange": "时间范围",
+  "com_config_field_chunksPerSource": "每来源分块数",
+  "com_config_field_format": "格式",
+  "com_config_field_allowedAddresses": "允许的地址",
+  "com_config_field_autoSubmitFromUrl": "从 URL 自动提交",
+  "com_config_field_skills": "技能",
+  "com_config_field_defaultActiveOnShare": "共享时默认启用",
+  "com_config_field_thinkingDisplay": "思考过程显示",
+  "com_config_field_cloudfront": "CloudFront",
+  "com_config_field_domain": "域名",
+  "com_config_field_distributionId": "分发 ID",
+  "com_config_field_invalidateOnDelete": "删除时失效缓存",
+  "com_config_field_imageSigning": "图片签名",
+  "com_config_field_urlExpiry": "URL 过期时间",
+  "com_config_field_cookieExpiry": "Cookie 过期时间",
+  "com_config_field_cookieDomain": "Cookie 域名",
+  "com_config_field_storageRegion": "存储区域",
+  "com_config_field_includeRegionInPath": "路径中包含区域",
+  "com_config_field_requireSignedAccess": "需要签名访问",
+  "com_config_field_remoteApi": "远程 API",
+  "com_config_field_auth": "认证",
+  "com_config_field_oidc": "OIDC",
+  "com_config_field_issuer": "签发者",
+  "com_config_field_audience": "受众",
+  "com_config_field_jwksUri": "JWKS URI",
+  "com_config_field_forward_audience_on_refresh": "刷新时转发受众",
+  "com_config_field_proxy": "代理",
+  "com_config_field_retentionMode": "保留模式",
+  "com_config_field_buildInfo": "构建信息",
+  "com_config_field_isTemporary": "是否临时",
+  "com_config_field_hideBadgeRow": "隐藏徽章行",
+  "com_config_field_guardrailConfig": "护栏",
+  "com_config_field_guardrailIdentifier": "护栏标识符",
+  "com_config_field_guardrailVersion": "护栏版本",
+  "com_config_field_trace": "追踪",
+  "com_config_field_streamProcessingMode": "流处理模式",
+  "com_config_field_allowedAddresses_item": "地址",
+  "com_config_field_includeDomains_item": "域名",
+  "com_config_field_excludeDomains_item": "域名",
+  "com_config_field_agent_ids": "智能体 ID",
+  "com_config_field_agent_ids_item": "智能体 ID",
+  "com_config_field_allowSelf": "允许自身",
+  "com_config_field_cacheRead": "缓存读取",
+  "com_config_field_cacheWrite": "缓存写入",
+  "com_config_field_code": "代码",
+  "com_config_field_completion": "补全",
+  "com_config_field_configureObo": "配置代表访问（OBO）",
+  "com_config_field_contextCost": "上下文成本",
+  "com_config_field_contextUsage": "上下文用量",
+  "com_config_field_conversation_starters": "对话开场白",
+  "com_config_field_conversation_starters_item": "开场白",
+  "com_config_field_currency": "货币",
+  "com_config_field_customPatterns": "自定义匹配模式",
+  "com_config_field_customPatterns_item": "匹配模式",
+  "com_config_field_github": "GitHub",
+  "com_config_field_intervalMinutes": "间隔（分钟）",
+  "com_config_field_maxCatalogSkills": "目录技能上限",
+  "com_config_field_maxInputTokens": "最大输入 Token 数",
+  "com_config_field_messageFilter": "消息过滤",
+  "com_config_field_obo": "代表访问（OBO）",
+  "com_config_field_pii": "个人身份信息",
+  "com_config_field_rate": "费率",
+  "com_config_field_reasoningFormat": "推理格式",
+  "com_config_field_reasoningKey": "推理键",
+  "com_config_field_includeReasoningContent": "包含推理内容",
+  "com_config_field_includeReasoningHistory": "包含推理历史",
+  "com_config_field_regex": "正则表达式",
+  "com_config_field_retainAgentFiles": "保留智能体文件",
+  "com_config_field_runOnStartup": "启动时运行",
+  "com_config_field_sensitive": "敏感",
+  "com_config_field_sharedLinks": "共享链接",
+  "com_config_field_showOnLanding": "在首页显示",
+  "com_config_field_skillSync": "技能同步",
+  "com_config_field_softDefault": "软默认",
+  "com_config_field_sources": "来源",
+  "com_config_field_sources_item": "来源",
+  "com_config_field_starterPatterns": "开场白匹配模式",
+  "com_config_field_starterPatterns_item": "匹配模式",
+  "com_config_field_subagents": "子智能体",
+  "com_config_field_titleTiming": "标题生成时机",
+  "com_config_field_tokenConfig": "Token 配置",
+  "com_config_section_fileStrategies": "文件策略",
+  "com_config_section_fileStrategies_desc": "为每个端点配置文件处理策略",
+  "com_config_section_cloudfront": "CloudFront",
+  "com_config_section_cloudfront_desc": "通过 Amazon CloudFront 分发提供文件",
+  "com_config_section_filteredTools": "排除的工具",
+  "com_config_section_filteredTools_desc": "被排除在可用范围之外的工具",
+  "com_config_section_imageOutputType": "图片输出类型",
+  "com_config_section_imageOutputType_desc": "生成图片的输出格式",
+  "com_config_section_includedTools": "包含的工具",
+  "com_config_section_includedTools_desc": "显式纳入可用范围的工具",
+  "com_config_section_messageFilter": "消息过滤",
+  "com_config_section_messageFilter_desc": "过滤或拦截用户消息中的匹配模式",
+  "com_config_section_langfuse": "Langfuse",
+  "com_config_section_langfuse_desc": "将此租户连接到 Langfuse 项目以导出追踪数据和反馈评分",
+  "com_config_langfuse_enabled": "Langfuse 连接",
+  "com_config_langfuse_description": "导出本组织内所有智能体的追踪数据和反馈评分。",
+  "com_config_langfuse_beta": "测试版",
+  "com_config_langfuse_destination": "目标",
+  "com_config_langfuse_select_destination": "选择目标",
+  "com_config_langfuse_public_key": "公钥",
+  "com_config_langfuse_secret_key": "密钥",
+  "com_config_langfuse_checking": "正在与 Langfuse 验证...",
+  "com_config_langfuse_save_and_enable": "保存并启用",
+  "com_config_langfuse_enable": "启用",
+  "com_config_langfuse_disable": "禁用",
+  "com_config_langfuse_verified": "已通过 Langfuse 验证",
+  "com_config_langfuse_not_configured": "未配置",
+  "com_config_langfuse_not_verified": "未验证",
+  "com_config_langfuse_test_fail": "无法连接到 Langfuse",
+  "com_config_langfuse_saved": "Langfuse 连接已保存",
+  "com_config_langfuse_tenant_wide": "Langfuse 连接为租户级设置，只能在基础配置中管理。",
+  "com_config_section_secureImageLinks": "安全图片链接",
+  "com_config_section_secureImageLinks_desc": "启用安全、需认证的图片 URL 分发",
+  "com_config_section_skillSync": "技能同步",
+  "com_config_section_skillSync_desc": "定期从外部来源拉取技能定义",
+  "com_config_section_summarization": "摘要",
+  "com_config_section_summarization_desc": "配置会话摘要行为",
+  "com_endpoint_prompt_cache": "提示词缓存",
+  "com_endpoint_anthropic_prompt_cache": "在 API 端缓存稳定的提示词上下文（系统消息、工具、长输入），以减少 Anthropic 模型每次请求的输入 Token 数",
+  "com_auth_title": "管理面板",
+  "com_auth_email_label": "邮箱",
+  "com_auth_email_placeholder": "admin@example.com",
+  "com_auth_password_label": "密码",
+  "com_auth_password_placeholder": "输入你的密码",
+  "com_auth_sign_in": "登录",
+  "com_auth_signing_in": "登录中...",
+  "com_auth_email_required": "邮箱为必填项",
+  "com_auth_email_invalid": "必须填写有效的邮箱地址",
+  "com_auth_password_required": "密码为必填项",
+  "com_auth_login_failed": "登录失败",
+  "com_auth_2fa_required": "需要进行双重认证",
+  "com_auth_2fa_title": "双重认证",
+  "com_auth_2fa_prompt": "请输入验证器应用中的 6 位验证码。",
+  "com_auth_2fa_code_label": "验证码",
+  "com_auth_2fa_code_placeholder": "000000",
+  "com_auth_2fa_verify": "验证",
+  "com_auth_2fa_verifying": "验证中...",
+  "com_auth_2fa_invalid_code": "验证码无效，请重试。",
+  "com_auth_2fa_expired": "会话已过期，请重新登录。",
+  "com_auth_2fa_back": "返回登录",
+  "com_auth_unable_connect": "无法连接，请重试。",
+  "com_auth_show_password": "显示密码",
+  "com_auth_hide_password": "隐藏密码",
+  "com_auth_sso_sign_in": "使用 SSO 登录",
+  "com_auth_sso_redirecting": "正在跳转...",
+  "com_auth_sso_completing": "正在完成登录...",
+  "com_auth_sso_error_title": "认证失败",
+  "com_auth_sso_no_code": "未收到授权码，请重试。",
+  "com_auth_sso_exchange_failed": "认证失败。授权码可能已过期。",
+  "com_auth_sso_back_to_login": "返回登录",
+  "com_auth_sso_redirecting_auto": "正在跳转到你的身份提供商...",
+  "com_auth_sso_redirect_failed": "SSO 跳转失败。你可以在下方手动登录。",
+  "com_error_page_title": "出了点问题",
+  "com_error_page_desc": "发生了意外错误。请重试或返回首页。",
+  "com_error_not_found_title": "页面未找到",
+  "com_error_not_found_desc": "你访问的页面不存在或已被移动。",
+  "com_scope_base_config": "基础配置",
+  "com_scope_base_config_desc": "来自 librechat.yaml 的默认设置",
+  "com_scope_search": "搜索角色和群组...",
+  "com_scope_no_results": "未找到作用域。",
+  "com_scope_priority": "优先级 {{priority}}",
+  "com_scope_profile_values": "{{count}} 项配置档案值",
+  "com_scope_one_profile_value": "1 项配置档案值",
+  "com_scope_no_profile_values": "无配置档案值",
+  "com_scope_members": "{{count}} 名成员",
+  "com_scope_select": "选择作用域",
+  "com_scope_roles": "角色",
+  "com_scope_groups": "群组",
+  "com_scope_users": "用户",
+  "com_scope_default": "默认",
+  "com_scope_active": "生效中",
+  "com_scope_inactive": "未激活",
+  "com_scope_editing_base": "正在编辑基础配置",
+  "com_scope_previewing": "正在显示 {{type}} 的配置档案值：{{name}}",
+  "com_scope_editing": "正在编辑 {{type}}：{{name}}",
+  "com_scope_back_to_base": "返回基础配置",
+  "com_scope_keyboard_navigate": "导航",
+  "com_scope_keyboard_select": "选择",
+  "com_scope_keyboard_close": "关闭",
+  "com_scope_add_profile_value": "添加配置档案值",
+  "com_scope_edit_profile_value": "编辑配置档案值",
+  "com_scope_remove_profile_value": "移除配置档案值",
+  "com_scope_cascade_title": "配置档案",
+  "com_scope_inherited": "继承",
+  "com_scope_profile_source": "{{type}} 配置档案",
+  "com_scope_field_profiles": "字段配置档案",
+  "com_scope_no_field_profiles": "此字段暂无配置档案",
+  "com_scope_add_for_scope": "为此作用域添加配置档案值",
+  "com_scope_changed_to": "作用域已切换为 {{name}}",
+  "com_scope_show_changed_only": "仅显示已修改的值",
+  "com_scope_confirm_remove": "移除此配置档案值？",
+  "com_scope_confirm_yes": "移除",
+  "com_scope_edit_value_title": "编辑配置档案值",
+  "com_scope_set_value_title": "设置配置档案值",
+  "com_scope_no_changed_in_tab": "此标签页没有已修改的字段",
+  "com_scope_create": "创建",
+  "com_scope_create_new": "创建配置",
+  "com_scope_creating": "创建中...",
+  "com_scope_create_error": "配置创建失败",
+  "com_scope_no_available_roles": "所有角色都已有配置",
+  "com_scope_no_available_groups": "所有群组都已有配置",
+  "com_scope_preview": "预览配置",
+  "com_scope_delete": "删除配置",
+  "com_scope_delete_confirm": "确定删除“{{name}}”的配置？这将移除所有配置档案覆盖值。",
+  "com_scope_deleting": "删除中...",
+  "com_nav_theme": "主题",
+  "com_nav_theme_system": "跟随系统",
+  "com_nav_theme_dark": "暗色",
+  "com_nav_theme_light": "亮色",
+  "com_ui_toggle_theme": "切换主题",
+  "com_ui_dark_theme_enabled": "已启用暗色主题",
+  "com_ui_light_theme_enabled": "已启用亮色主题",
+  "com_ui_system_theme_enabled": "已启用系统主题",
+  "com_ui_settings": "设置",
+  "com_settings_theme_desc": "选择你偏好的配色方案",
+  "com_cmdk_label": "命令菜单",
+  "com_cmdk_placeholder": "搜索命令、设置、导航...",
+  "com_cmdk_no_results": "未找到结果。",
+  "com_cmdk_group_navigation": "导航",
+  "com_cmdk_group_actions": "操作",
+  "com_cmdk_group_sections": "配置区块",
+  "com_cmdk_group_tabs": "标签页",
+  "com_cmdk_set_theme": "设置主题：{{theme}}",
+  "com_ui_all": "全部",
+  "com_ui_select_all": "全选",
+  "com_ui_actions": "操作",
+  "com_ui_of": "/",
+  "com_ui_edit": "编辑",
+  "com_ui_active": "活跃",
+  "com_ui_paused": "已暂停",
+  "com_users_title": "用户管理",
+  "com_users_subtitle": "管理 LibreChat 的用户、角色和权限",
+  "com_users_add": "添加用户",
+  "com_users_total": "用户总数",
+  "com_users_admins": "管理员",
+  "com_users_recent": "最近注册",
+  "com_users_list": "用户列表",
+  "com_users_search": "搜索用户...",
+  "com_users_role_filter": "按角色筛选",
+  "com_users_col_user": "用户",
+  "com_users_col_role": "角色",
+  "com_users_col_provider": "提供商",
+  "com_users_col_status": "状态",
+  "com_users_col_joined": "加入时间",
+  "com_users_verified": "已验证",
+  "com_users_pending": "待验证",
+  "com_users_empty": "未找到用户",
+  "com_users_showing": "显示",
+  "com_users_name_placeholder": "姓名",
+  "com_users_email_required": "邮箱为必填项",
+  "com_users_email_placeholder": "邮箱",
+  "com_users_role_label": "角色",
+  "com_users_delete_title": "删除用户",
+  "com_users_delete_desc": "确定要删除 {{name}} 吗？此操作无法撤销。",
+  "com_users_no_assignments": "未分配角色或群组",
+  "com_users_assign_role": "添加到角色...",
+  "com_users_assign_group": "添加到群组...",
+  "com_users_remove_role_title": "从角色移除",
+  "com_users_remove_role_desc": "确定将 {{user}} 从“{{name}}”角色中移除吗？",
+  "com_users_remove_group_title": "从群组移除",
+  "com_users_remove_group_desc": "确定将 {{user}} 从“{{name}}”群组中移除吗？",
+  "com_users_detail_title": "用户详情",
+  "com_users_roles_label": "角色",
+  "com_users_groups_label": "群组",
+  "com_users_no_roles": "未分配角色",
+  "com_users_no_groups": "未分配群组",
+  "com_users_all_roles_assigned": "所有角色均已分配",
+  "com_users_all_groups_assigned": "所有群组均已分配",
+  "com_users_profile_already_created": "用户配置档案已存在",
+  "com_users_view_details": "查看详情",
+  "com_users_add_profiles": "添加配置档案",
+  "com_users_add_profiles_title": "添加配置档案",
+  "com_users_user_profile": "{{name}} 的配置档案",
+  "com_users_create_user_profile": "为 {{name}} 创建配置档案",
+  "com_users_no_profiles": "未分配配置档案",
+  "com_users_delete_profile_title": "删除用户配置档案",
+  "com_users_delete_profile_desc": "确定删除 {{name}} 的配置档案吗？此操作无法撤销。",
+  "com_groups_title": "群组",
+  "com_groups_subtitle": "管理用于配置档案和访问控制的用户群组",
+  "com_groups_create": "创建群组",
+  "com_groups_total": "群组总数",
+  "com_groups_members": "成员",
+  "com_groups_profiles": "配置档案",
+  "com_groups_list": "群组列表",
+  "com_groups_search": "搜索群组...",
+  "com_groups_priority": "优先级",
+  "com_groups_empty": "未找到群组",
+  "com_access_title": "访问管理",
+  "com_access_subtitle": "管理群组、角色和成员权限",
+  "com_access_tab_groups": "群组",
+  "com_access_tab_roles": "角色",
+  "com_access_search_groups": "搜索群组...",
+  "com_access_search_roles": "搜索角色...",
+  "com_access_create_group": "创建群组",
+  "com_access_create_role": "创建角色",
+  "com_access_groups_empty": "未找到群组",
+  "com_access_roles_empty": "未找到角色",
+  "com_access_roles_error": "角色加载失败",
+  "com_access_permissions_load_error": "无法加载该角色的权限。",
+  "com_access_no_results": "没有匹配的结果",
+  "com_access_manage_members": "管理成员",
+  "com_access_delete_group_title": "删除群组",
+  "com_access_delete_group_desc": "确定要删除“{{name}}”吗？所有成员将被移除，配置档案将丢失。",
+  "com_access_delete_role_title": "删除角色",
+  "com_access_delete_role_desc": "确定要删除“{{name}}”吗？所有成员将被移除，配置档案将丢失。",
+  "com_access_save_order_title": "保存优先级顺序",
+  "com_access_save_order_desc": "此操作将更新所有条目的优先级顺序。确定吗？",
+  "com_access_reorder_hint": "拖动条目调整优先级。靠上的条目优先级更高。",
+  "com_access_reorder_discard": "放弃",
+  "com_access_reorder_save": "保存顺序",
+  "com_access_unsaved_changes": "未保存的更改",
+  "com_access_reorder_item": "第 {{position}} 位的条目",
+  "com_access_reorder_lifted": "已从第 {{position}} 位拿起条目",
+  "com_access_reorder_moved": "已移动到第 {{position}} 位（{{direction}}）",
+  "com_access_reorder_dropped": "已从第 {{from}} 位拖放到第 {{to}} 位",
+  "com_access_reorder_canceled": "已取消拖动，条目回到第 {{position}} 位",
+  "com_access_system_role": "系统",
+  "com_access_members_of": "{{name}} 的成员",
+  "com_access_remove_member_title": "移除成员",
+  "com_access_remove_member_desc": "确定要将 {{user}} 从“{{name}}”中移除吗？",
+  "com_access_remove_member": "移除",
+  "com_access_add_members_placeholder": "搜索要添加的用户...",
+  "com_access_no_users_found": "未找到用户",
+  "com_access_no_members": "暂无成员",
+  "com_access_member_count": "{{count}} 名成员",
+  "com_access_pending_additions": "正在添加 {{count}} 名成员",
+  "com_access_pending_removals": "正在移除 {{count}} 名成员",
+  "com_access_details_saved": "详情已保存",
+  "com_access_permissions_saved": "权限已保存",
+  "com_access_member_ops_failed_one": "{{count}} 项成员操作失败",
+  "com_access_member_ops_failed_other": "{{count}} 项成员操作失败",
+  "com_access_details_saved_permissions_failed": "详情已保存，但权限保存失败：{{error}}",
+  "com_access_name_required": "姓名为必填项",
+  "com_access_group_unavailable": "群组已不可用",
+  "com_access_role_unavailable": "角色已不可用",
+  "com_access_col_name": "名称",
+  "com_access_group_name_placeholder": "例如：工程部",
+  "com_access_group_desc_placeholder": "可选描述...",
+  "com_access_role_name_placeholder": "例如：内容审核员",
+  "com_access_role_desc_placeholder": "可选描述...",
+  "com_access_active": "活跃",
+  "com_access_paused": "已暂停",
+  "com_access_edit_group": "编辑群组",
+  "com_access_edit_role": "编辑角色",
+  "com_access_tab_details": "详情",
+  "com_access_tab_permissions": "权限",
+  "com_access_tab_members": "成员",
+  "com_access_save_role": "保存角色",
+  "com_perm_title": "权限",
+  "com_perm_features": "允许的功能",
+  "com_perm_desc_PROMPTS": "创建、共享和使用提示词模板",
+  "com_perm_desc_AGENTS": "创建、共享和使用自定义智能体",
+  "com_perm_desc_MEMORIES": "管理跨会话的持久记忆",
+  "com_perm_desc_MCP_SERVERS": "连接和管理 MCP 工具服务器",
+  "com_perm_desc_REMOTE_AGENTS": "连接和管理远程智能体端点",
+  "com_perm_desc_SKILLS": "创建、共享和使用智能体技能",
+  "com_perm_desc_SHARED_LINKS": "创建和分享会话共享链接",
+  "com_perm_desc_PEOPLE_PICKER": "控制用户、群组和角色的可见性",
+  "com_perm_type_BOOKMARKS": "书签",
+  "com_perm_type_PROMPTS": "提示词",
+  "com_perm_type_AGENTS": "智能体",
+  "com_perm_type_MEMORIES": "记忆",
+  "com_perm_type_MULTI_CONVO": "多会话",
+  "com_perm_type_TEMPORARY_CHAT": "临时对话",
+  "com_perm_type_RUN_CODE": "运行代码",
+  "com_perm_type_WEB_SEARCH": "网络搜索",
+  "com_perm_type_PEOPLE_PICKER": "人员选择器",
+  "com_perm_type_MARKETPLACE": "市场",
+  "com_perm_type_FILE_SEARCH": "文件搜索",
+  "com_perm_type_FILE_CITATIONS": "文件引用",
+  "com_perm_type_MCP_SERVERS": "MCP 服务器",
+  "com_perm_type_REMOTE_AGENTS": "远程智能体",
+  "com_perm_type_SKILLS": "技能",
+  "com_perm_type_SHARED_LINKS": "共享链接",
+  "com_perm_USE": "使用",
+  "com_perm_CREATE": "创建",
+  "com_perm_UPDATE": "更新",
+  "com_perm_READ": "读取",
+  "com_perm_READ_AUTHOR": "读取作者",
+  "com_perm_SHARE": "共享",
+  "com_perm_OPT_OUT": "选择退出",
+  "com_perm_VIEW_USERS": "查看用户",
+  "com_perm_VIEW_GROUPS": "查看群组",
+  "com_perm_VIEW_ROLES": "查看角色",
+  "com_perm_SHARE_PUBLIC": "公开共享",
+  "com_perm_CONFIGURE_OBO": "配置代表访问（OBO）",
+  "com_help_title": "帮助",
+  "com_help_subtitle": "文档、指南和支持资源",
+  "com_help_resources": "资源",
+  "com_help_docs_title": "文档",
+  "com_help_docs_desc": "配置和运行 LibreChat 的完整指南",
+  "com_help_api_title": "配置参考",
+  "com_help_api_desc": "librechat.yaml 和环境变量设置的详细参考",
+  "com_help_community_title": "社区",
+  "com_help_community_desc": "加入 GitHub 社区参与讨论和贡献",
+  "com_help_discord_title": "Discord",
+  "com_help_discord_desc": "在 Discord 上与社区交流并获取支持",
+  "com_help_support": "支持",
+  "com_help_support_text": "需要帮助？请联系你的系统管理员，或查阅 LibreChat 文档中的故障排除指南。",
+  "com_a11y_results_found": "找到{{count}}个结果",
+  "com_a11y_filter_changed": "筛选已更新，共 {{count}} 个结果",
+  "com_a11y_value_hidden": "{{key}} 的值已隐藏",
+  "com_a11y_value_revealed": "{{key}} 的值已显示",
+  "com_a11y_remove_role": "移除角色 {{name}}",
+  "com_a11y_remove_group": "移除群组 {{name}}",
+  "com_a11y_remove_user_profile": "移除用户配置档案",
+  "com_a11y_assigned_profiles": "已分配的配置档案",
+  "com_a11y_available_roles": "可分配角色",
+  "com_a11y_available_groups": "可分配群组",
+  "com_a11y_admin_panel": "管理面板",
+  "com_a11y_pagination": "分页",
+  "com_a11y_previous_page": "上一页",
+  "com_a11y_next_page": "下一页",
+  "com_a11y_page_n": "第 {{page}} 页",
+  "com_a11y_rename_entry": "重命名 {{name}}",
+  "com_a11y_remove_override": "移除 {{name}} 的覆盖值",
+  "com_a11y_reset_to_default": "将 {{name}} 重置为默认值",
+  "com_a11y_add_item": "添加 {{name}}",
+  "com_access_tab_capabilities": "能力",
+  "com_cap_title": "系统能力",
+  "com_cap_subtitle": "管理哪些主体持有系统级能力",
+  "com_cap_count": "{{count}} / {{total}}",
+  "com_cap_edit_title": "编辑 {{name}} 的能力",
+  "com_cap_implied_by": "由 {{cap}} 隐含",
+  "com_cap_grant_success": "能力已授予",
+  "com_cap_revoke_success": "能力已撤销",
+  "com_cap_empty": "未找到持有能力的主体",
+  "com_cap_type_filter": "主体类型筛选",
+  "com_cap_col_type": "类型",
+  "com_cap_col_name": "名称",
+  "com_cap_col_capabilities": "能力",
+  "com_cap_col_status": "状态",
+  "com_cap_cat_users": "用户",
+  "com_cap_cat_groups": "群组",
+  "com_cap_cat_roles": "角色",
+  "com_cap_cat_config": "配置",
+  "com_cap_cat_content": "内容",
+  "com_cap_cat_system": "系统",
+  "com_cap_access_admin": "管理面板访问",
+  "com_cap_read_users": "读取用户",
+  "com_cap_manage_users": "管理用户",
+  "com_cap_read_groups": "读取群组",
+  "com_cap_manage_groups": "管理群组",
+  "com_cap_read_roles": "读取角色",
+  "com_cap_manage_roles": "管理角色",
+  "com_cap_read_configs": "读取配置",
+  "com_cap_manage_configs": "管理配置",
+  "com_cap_assign_configs": "分配配置",
+  "com_cap_read_usage": "读取用量",
+  "com_cap_read_agents": "读取智能体",
+  "com_cap_manage_agents": "管理智能体",
+  "com_cap_manage_mcpservers": "管理 MCP 服务器",
+  "com_cap_read_prompts": "读取提示词",
+  "com_cap_manage_prompts": "管理提示词",
+  "com_cap_read_skills": "读取技能",
+  "com_cap_manage_skills": "管理技能",
+  "com_cap_read_sharedlinks": "读取共享链接",
+  "com_cap_manage_sharedlinks": "管理共享链接",
+  "com_cap_read_assistants": "读取助手",
+  "com_cap_manage_assistants": "管理助手",
+  "com_cap_read_audit_log": "读取审计日志",
+  "com_cap_desc_access_admin": "管理面板完整访问",
+  "com_cap_desc_read_users": "查看用户列表和配置档案",
+  "com_cap_desc_manage_users": "创建、编辑和删除用户",
+  "com_cap_desc_read_groups": "查看群组列表和成员",
+  "com_cap_desc_manage_groups": "创建、编辑和删除群组",
+  "com_cap_desc_read_roles": "查看角色列表和权限",
+  "com_cap_desc_manage_roles": "创建、编辑和删除角色",
+  "com_cap_desc_read_configs": "查看配置设置",
+  "com_cap_desc_manage_configs": "编辑配置设置",
+  "com_cap_desc_assign_configs": "分配配置档案",
+  "com_cap_desc_read_usage": "查看用量指标与分析",
+  "com_cap_desc_read_agents": "查看智能体配置",
+  "com_cap_desc_manage_agents": "创建、编辑和删除智能体",
+  "com_cap_desc_manage_mcpservers": "管理 MCP 服务器连接",
+  "com_cap_desc_read_prompts": "查看提示词库",
+  "com_cap_desc_manage_prompts": "创建、编辑和删除提示词",
+  "com_cap_desc_read_skills": "查看技能配置",
+  "com_cap_desc_manage_skills": "创建、编辑和删除技能",
+  "com_cap_desc_read_sharedlinks": "查看会话共享链接",
+  "com_cap_desc_manage_sharedlinks": "管理会话共享链接",
+  "com_cap_desc_read_assistants": "查看助手配置",
+  "com_cap_desc_manage_assistants": "创建、编辑和删除助手",
+  "com_cap_desc_read_audit_log": "查看和导出授权变更审计日志",
+  "com_access_denied_title": "拒绝访问",
+  "com_access_denied_description": "你没有查看此页面的权限。请联系管理员。",
+  "com_cap_no_permission": "你需要 {{cap}} 权限才能执行此操作",
+  "com_cap_principal_unavailable": "主体已不可用",
+  "com_a11y_cap_filter_changed": "显示 {{count}} 个主体",
+  "com_nav_audit_log": "审计日志",
+  "com_audit_title": "审计日志",
+  "com_audit_subtitle": "跟踪所有系统能力变更",
+  "com_audit_col_timestamp": "时间戳",
+  "com_audit_col_actor": "操作者",
+  "com_audit_col_action": "操作",
+  "com_audit_col_target": "目标",
+  "com_audit_col_capability": "能力",
+  "com_audit_action_assigned": "已授予",
+  "com_audit_action_removed": "已撤销",
+  "com_audit_empty": "未找到审计日志条目",
+  "com_audit_entry_count_zero": "暂无条目",
+  "com_audit_entry_count_one": "{{count}} 条记录",
+  "com_audit_entry_count_other": "{{count}} 条记录",
+  "com_audit_date_from": "起始日期",
+  "com_audit_date_to": "结束日期",
+  "com_audit_filter_action_label": "按操作筛选",
+  "com_audit_search_label": "搜索审计日志",
+  "com_audit_filter_actor_id": "操作者",
+  "com_audit_filter_target_id": "目标",
+  "com_audit_filter_target_type": "目标类型",
+  "com_audit_filter_capability": "能力",
+  "com_audit_export_server": "导出全部匹配项",
+  "com_a11y_audit_row_open": "打开审计日志条目",
+  "com_audit_error": "审计日志加载失败",
+  "com_audit_detail_title": "审计日志条目",
+  "com_audit_detail_summary_assigned": "{{actor}} 向 {{target}} 授予了 {{capability}}",
+  "com_audit_detail_summary_removed": "{{actor}} 从 {{target}} 撤销了 {{capability}}",
+  "com_audit_detail_actor": "操作者",
+  "com_audit_detail_target": "目标",
+  "com_audit_detail_capability": "能力",
+  "com_audit_detail_timestamp": "时间",
+  "com_audit_detail_entry_id": "条目 ID",
+  "com_audit_detail_before": "变更前",
+  "com_audit_detail_after": "变更后",
+  "com_audit_detail_no_changes": "未记录详细变更",
+  "com_audit_detail_copy_permalink": "复制链接",
+  "com_audit_detail_not_found": "未找到审计日志条目。它可能已被清除，或链接不正确。",
+  "com_audit_detail_load_error": "无法加载该审计日志条目。请求失败——请稍后重试。",
+  "com_audit_detail_close": "关闭",
+  "com_a11y_filters": "筛选",
+  "com_a11y_audit_filter_changed": "{{count}} 条审计日志记录匹配当前筛选条件",
+  "com_a11y_audit_export_failed": "审计日志导出失败",
+  "com_nav_grants": "授权",
+  "com_nav_expand_sidebar": "展开侧边栏",
+  "com_nav_collapse_sidebar": "折叠侧边栏",
+  "com_nav_dashboard": "仪表盘",
+  "com_dash_title": "欢迎！",
+  "com_dash_subtitle": "这里是管理 LibreChat 实例所需的一切。",
+  "com_dash_quick_links": "快速链接",
+  "com_dash_config_desc": "查看和管理实例配置设置。",
+  "com_dash_access_desc": "创建和管理群组、分配角色，并精细调整组织内成员的权限。",
+  "com_dash_grants_desc": "控制每个角色可访问的能力，从读取配置到管理用户。",
+  "com_dash_help_desc": "文档、社区资源和支持渠道链接，帮助你充分利用 LibreChat。",
+  "com_dash_nav_tips": "导航技巧",
+  "com_dash_tip_sidebar": "侧边栏可以到达每个页面：配置、访问管理、授权和帮助。展开可查看标签，折叠则仅显示图标。",
+  "com_dash_tip_cmdk": "命令菜单可以搜索并跳转到任意页面、配置区块或配置标签页，还可以在菜单中切换亮色、暗色和系统主题。",
+  "com_grants_title": "系统授权",
+  "com_grants_subtitle": "按角色管理系统级能力",
+  "com_grants_tab_management": "管理",
+  "com_grants_tab_audit_log": "审计日志",
+  "com_grants_no_capabilities": "无能力",
+  "com_grants_capability_count": "{{count}} 项能力",
+  "com_grants_assign_btn": "添加用户授权",
+  "com_grants_assign_title": "向用户授予能力",
+  "com_grants_assign_placeholder": "搜索用户...",
+  "com_grants_assign_hint": "角色和群组可直接在上表中编辑。",
+  "com_grants_assign_no_users": "未找到符合条件的用户",
+  "com_error_load_groups": "群组加载失败，请重试。",
+  "com_error_load_members": "成员加载失败，请重试。",
+  "com_perm_unavailable_title": "无法验证权限",
+  "com_perm_unavailable_desc": "权限服务暂时不可用。请重新加载页面重试。",
+  "com_ui_reload": "重新加载",
+  "com_config_pending_reset": "待重置",
+  "com_config_secret_replace": "替换",
+  "com_a11y_secret_configured": "{{name}} 已配置；值已隐藏",
+  "com_a11y_secret_replace": "替换 {{name}}",
+  "com_a11y_secret_cancel_replace": "取消替换 {{name}}",
+  "com_config_validation_more": "...还有 {{count}} 项",
+  "com_scope_delete_error": "配置删除失败",
+  "com_kv_type_string": "abc",
+  "com_kv_type_number": "123",
+  "com_kv_type_boolean": "T/F",
+  "com_kv_type_json": "{ }",
+  "com_a11y_logo_alt": "LibreChat 徽标",
+  "com_ui_language": "语言",
+  "com_ui_language_english": "English",
+  "com_ui_language_zh_hans": "中文（简体）",
+  "com_audit_target_user": "用户",
+  "com_audit_target_group": "群组",
+  "com_audit_target_role": "角色",
+  "com_users_role_admin": "管理员",
+  "com_users_role_user": "用户",
+  "com_nav_tools": "工具管理",
+  "com_tools_title": "工具管理",
+  "com_tools_subtitle": "TerraVox 工具网关全量清单（含已停用工具）",
+  "com_tools_search": "搜索工具",
+  "com_tools_count": "共 {{count}} 个工具",
+  "com_tools_col_tool": "工具",
+  "com_tools_col_version": "版本",
+  "com_tools_col_expose": "暴露面",
+  "com_tools_col_groups": "允许组",
+  "com_tools_col_renderer": "渲染器",
+  "com_tools_col_status": "状态",
+  "com_tools_enabled": "已启用",
+  "com_tools_disabled": "已停用",
+  "com_tools_dangerous": "危险",
+  "com_tools_all_groups": "所有组",
+  "com_tools_empty": "暂无工具",
+  "com_tools_empty_hint": "工具网关返回了空清单，请先在网关侧注入工具 manifest。",
+  "com_tools_no_match": "没有匹配搜索条件的工具。",
+  "com_tools_load_error": "工具清单加载失败",
+  "com_tools_retry_later": "出现问题，请稍后重试。",
+  "com_tools_tab_catalog": "工具清单",
+  "com_tools_tab_groups": "工具分组",
+  "com_tools_group_ungrouped": "未分组",
+  "com_usage_refresh": "刷新",
+  "com_tools_tab_usage": "使用统计",
+  "com_tools_col_group": "分组",
+  "com_tools_add_button": "添加工具",
+  "com_tools_import_button": "导入",
+  "com_tools_copy_id": "复制工具 ID",
+  "com_tools_delete_title": "删除工具",
+  "com_tools_delete_desc": "确定永久删除 {{name}}？工具将从目录移除，网关重启后也不会被重新种入；审计记录予以保留。",
+  "com_tools_add_title": "添加工具",
+  "com_tools_edit_title": "编辑工具",
+  "com_tools_save": "保存",
+  "com_tools_create": "创建",
+  "com_tools_tab_basic": "基本信息",
+  "com_tools_tab_params": "参数与表单",
+  "com_tools_tab_exec": "执行与结果",
+  "com_tools_custom_group": "自定义…",
+  "com_tools_field_tool_id": "工具 ID",
+  "com_tools_field_group": "分组",
+  "com_tools_field_tool_suffix": "工具名（后缀）",
+  "com_tools_field_version": "版本",
+  "com_tools_field_display_name": "显示名称",
+  "com_tools_field_description": "描述",
+  "com_tools_field_expose": "暴露给",
+  "com_tools_field_flags": "开关",
+  "com_tools_field_enabled": "启用",
+  "com_tools_field_dangerous": "危险（执行需二次确认）",
+  "com_tools_field_parameters": "参数（JSON Schema）",
+  "com_tools_parameters_hint": "必须是 type:object 的 JSON Schema，工具表单与 MCP inputSchema 由此推导。",
+  "com_tools_field_form": "表单提示（JSON）",
+  "com_tools_form_hint": "可选的 UI 提示：字段顺序、标签、控件。",
+  "com_tools_field_exec_kind": "执行方式",
+  "com_tools_field_handler": "处理器",
+  "com_tools_field_dist_owner": "Gitea 用户 / 组织",
+  "com_tools_field_dist_repo": "Gitea 仓库",
+  "com_tools_field_dist_extra": "补充字段（仓库 tool.json 缺失时手填）",
+  "com_tools_field_dist_version": "版本",
+  "com_tools_field_dist_sha256": "包 SHA-256",
+  "com_tools_field_dist_launcher": "启动入口",
+  "com_tools_field_dist_runtime": "运行时",
+  "com_tools_dist_hint": "工具包从该仓库的 Release 分发：描述/版本/哈希等以仓库 tool.json 为准，缺失时用补充字段兜底。",
+  "com_tools_field_timeout": "超时（秒）",
+  "com_tools_field_renderer": "结果渲染器",
+  "com_tools_field_redact": "脱敏参数",
+  "com_tools_redact_hint": "逗号分隔的参数名，审计摘要中将对其脱敏。",
+  "com_tools_field_result_config": "渲染器配置（JSON）",
+  "com_tools_result_config_hint": "渲染器私有配置，例如 table 的列定义。",
+  "com_tools_err_tool_id": "请填写工具 ID。",
+  "com_tools_err_display_name": "请填写显示名称。",
+  "com_tools_err_parameters_json": "参数必须是合法 JSON。",
+  "com_tools_err_form_json": "表单提示必须是合法 JSON。",
+  "com_tools_err_result_config_json": "渲染器配置必须是合法 JSON。",
+  "com_tools_err_handler": "请选择处理器。",
+  "com_tools_err_owner_repo": "桌面工具需填写 Gitea 用户与仓库。",
+  "com_tools_err_sha256": "SHA-256 必须是 64 位十六进制字符。",
+  "com_tools_err_renderer": "请填写结果渲染器。",
+  "com_tools_gitea_import_title": "从 Gitea 导入工具",
+  "com_tools_gitea_url": "Gitea 地址",
+  "com_tools_gitea_url_hint": "留空使用网关默认地址；修改后按 Enter 或移出输入框即重新拉取列表。",
+  "com_tools_gitea_loading": "正在拉取可见的用户与仓库…",
+  "com_tools_gitea_owner": "用户 / 组织",
+  "com_tools_gitea_repo": "仓库",
+  "com_tools_gitea_select_owner": "选择用户 / 组织",
+  "com_tools_gitea_select_repo": "选择仓库",
+  "com_tools_gitea_check": "检查并导入",
+  "com_tools_gitea_manual_create": "手动创建",
+  "com_tools_gitea_release": "Release",
+  "com_tools_gitea_installable": "可直接安装",
+  "com_tools_gitea_not_installable": "需补充字段后才能安装",
+  "com_tools_gitea_check_failed": "检查未通过：存在硬性问题（红色项），请先修复仓库。",
+  "com_tools_gitea_back": "返回重选",
+  "com_tools_gitea_continue": "继续编辑",
+  "com_tools_gitea_prefill_hint": "以上信息将填入编辑面板，请继续检查并补充后保存。",
+  "com_tools_import_title": "导入工具",
+  "com_tools_import_hint": "导入工具清单（JSON）——来自网关种子目录或其他环境的导出。",
+  "com_tools_import_upload": "上传文件",
+  "com_tools_import_paste": "粘贴 JSON",
+  "com_tools_import_pick": "选择 .json 文件",
+  "com_tools_import_pick_hint": "每个文件一份清单，可多选",
+  "com_tools_import_no_files": "未选择任何清单文件。",
+  "com_tools_import_no_paste": "请粘贴至少一份清单。",
+  "com_tools_import_bad_json": "不是合法的 JSON",
+  "com_tools_import_count": "{{count}} 份清单",
+  "com_tools_import_preview": "预览导入",
+  "com_tools_import_preview_desc": "试运行结果——尚未写入任何数据。已存在的工具默认跳过，勾选覆盖后才会更新。",
+  "com_tools_import_overwrite": "覆盖已存在的工具",
+  "com_tools_import_apply": "确认导入",
+  "com_tools_import_apply_skip": "确认导入（跳过已存在）",
+  "com_tools_import_done": "导入完成。",
+  "com_tools_import_action": "操作",
+  "com_tools_import_detail": "说明",
+  "com_tools_import_created": "新增",
+  "com_tools_import_updated": "更新",
+  "com_tools_import_skipped": "跳过",
+  "com_tools_import_failed": "失败",
+  "com_tools_groups_hint": "工具分组（display_group）：既是工具编排方式，也是可见性域——注册分组后可配置该组工具对哪些用户组可见（语义同服务绑定）。排序值控制工具箱侧栏顺序。",
+  "com_tools_group_add_button": "添加分组",
+  "com_tools_groups_empty": "暂无分组。",
+  "com_tools_group_implicit": "隐式",
+  "com_tools_drag_handle": "拖拽调整顺序",
+  "com_tools_group_detail_manage": "管理分组工具",
+  "com_tools_group_detail_left": "未加入的工具",
+  "com_tools_group_detail_right": "组内工具",
+  "com_tools_group_detail_add_ph": "搜索并添加工具到本分组…",
+  "com_tools_group_detail_remove": "从分组移除",
+  "com_tools_group_detail_empty": "该分组暂无工具",
+  "com_tools_group_detail_add": "添加",
+  "com_tools_group_order_saving": "排序保存中…",
+  "com_tools_group_tool_count": "{{count}} 个工具",
+  "com_tools_group_sort": "排序 {{order}}",
+  "com_tools_group_add_title": "添加分组",
+  "com_tools_group_edit_title": "编辑分组",
+  "com_tools_group_field_name": "命名空间",
+  "com_tools_group_name_hint": "1–64 个字符，不含空格与 |；可用中文。创建后不可改。",
+  "com_tools_group_field_display_name": "显示名称",
+  "com_tools_group_field_description": "描述",
+  "com_tools_group_field_sort_order": "排序值",
+  "com_tools_group_sort_hint": "越小越靠前；隐式分组默认 1000。",
+  "com_tools_group_err_name": "命名空间只能包含小写字母、数字、- 和 _。",
+  "com_tools_group_delete_title": "删除分组",
+  "com_tools_group_delete_desc": "确定删除分组 {{name}}？仅删除分组元数据，工具 ID 不受影响。",
+  "com_tools_group_delete_not_empty": "该分组下仍有 {{count}} 个工具，请先移动或删除它们。",
+  "com_tools_pending_title": "待确认更新",
+  "com_tools_pending_hint": "仓库中领先于已批准版本的 Release 在此确认前不会下发给前端用户。",
+  "com_tools_pending_versions": "{{current}} → {{latest}}",
+  "com_tools_pending_checking": "正在获取仓库详情…",
+  "com_tools_pending_confirm": "查看并确认",
+  "com_tools_pending_check_failed": "仓库检查未通过，未打开确认：{{detail}}",
+  "com_tools_pending_check_warns": "检查警告：{{detail}}",
+  "com_nav_usage": "使用统计",
+  "com_usage_title": "使用统计",
+  "com_usage_filter_tool": "工具",
+  "com_usage_filter_user": "用户 ID",
+  "com_usage_col_time": "时间",
+  "com_usage_col_user": "用户",
+  "com_usage_col_user_sub": "用户 ID",
+  "com_usage_col_tool": "工具",
+  "com_usage_col_version": "版本",
+  "com_usage_col_status": "状态",
+  "com_usage_col_duration": "耗时",
+  "com_usage_source_mcp": "AI 调用（MCP）",
+  "com_usage_source_server": "手动执行",
+  "com_usage_source_toolbox": "浏览器直跑",
+  "com_usage_col_arguments": "参数键名",
+  "com_usage_col_source": "来源",
+  "com_usage_col_id": "记录 ID",
+  "com_usage_status_succeeded": "成功",
+  "com_usage_status_failed": "失败",
+  "com_usage_status_stopped": "已停止",
+  "com_usage_status_timeout": "已超时",
+  "com_usage_empty": "暂无工具运行记录。",
+  "com_usage_error": "加载使用统计失败。",
+  "com_usage_export": "导出 CSV",
+  "com_usage_export_failed": "导出失败。",
+  "com_usage_export_truncated": "导出已限制为前 {{count}} 条记录。",
+  "com_usage_count": "共 {{count}} 次运行",
+  "com_tools_gitea_import_kind": "工具类型",
+  "com_tools_gitea_kind_desktop": "桌面自动化",
+  "com_tools_gitea_kind_plugin": "扩展插件",
+  "com_tools_gitea_kind_web": "网页工具",
+  "com_tools_field_web_url": "工具地址",
+  "com_tools_gitea_web_url_hint": "运行网页工具时将在新标签页打开该地址。",
+  "com_tools_gitea_url_hint_web": "可选——选择仓库仅用于预填名称/描述；上方地址才是工具本体。",
+  "com_tools_err_web_url": "工具地址必须以 http(s):// 开头",
+  "com_tools_err_host_launcher": "插件必须登记宿主可执行文件（相对宿主根目录）",
+  "com_tools_field_dist_host_launcher": "宿主可执行文件（相对宿主根目录）",
+  "com_tools_field_dist_host_hints": "宿主根目录候选（每行一个）",
+  "com_tools_field_dist_install_script": "安装脚本（可选）",
+  "com_tools_field_dist_uninstall_script": "卸载脚本（可选）",
+  "com_nav_services": "服务管理",
+  "com_services_title": "服务管理",
+  "com_services_hint": "一个绑定 = 一幅地图（地图服务）或一个数据源（数据服务）。保存时自动探测可用性；用户端按可见组过滤。",
+  "com_services_add_button": "绑定服务",
+  "com_services_empty": "还没有绑定任何服务。",
+  "com_services_add_title": "绑定服务",
+  "com_services_edit_title": "编辑绑定",
+  "com_services_field_type": "服务类型",
+  "com_services_type_map": "地图服务",
+  "com_services_type_all": "全部",
+  "com_services_type_data": "数据服务",
+  "com_services_type_hint": "地图服务按地图绑定；数据服务按数据源绑定（含其全部数据集）。M1 支持 iServer REST。",
+  "com_services_field_name": "展示名",
+  "com_services_field_base_url": "iServer 根地址",
+  "com_services_field_service_path": "服务路径",
+  "com_services_path_hint_map": "iserver/services/ 之后的地图路径，如 dom/rest/maps/dom",
+  "com_services_path_hint_data": "iserver/services/ 之后的数据服务根，如 data-BeiJing/rest/data",
+  "com_services_field_datasource": "数据源",
+  "com_services_datasource_hint": "数据服务必填；填写工作空间中的数据源名（如 BeiJing）。",
+  "com_services_field_allowed_groups": "可见用户组",
+  "com_services_groups_hint": "绑定对所选组的成员可见；«全部» 表示所有已登录用户。",
+  "com_services_group_custom_placeholder": "自定义组名",
+  "com_services_group_add": "添加",
+  "com_services_field_enabled": "启用",
+  "com_services_disabled": "已停用",
+  "com_services_probe": "重新探测",
+  "com_services_status_available": "可用",
+  "com_services_status_unavailable": "不可用",
+  "com_services_status_unprobed": "未探测",
+  "com_services_delete_title": "删除绑定",
+  "com_services_delete_desc": "删除「{name}」后前端立即不可见，历史运行不受影响。",
+  "com_services_err_required": "展示名、根地址、服务路径为必填项",
+  "com_services_err_datasource": "数据服务必须指定数据源",
+  "com_services_err_groups": "至少选择一个可见用户组",
+  "com_dash_tools_desc": "管理工具清单、分组与可见性。",
+  "com_dash_usage_desc": "查看工具使用统计与运行记录。",
+  "com_dash_services_desc": "绑定地图/数据服务并管理可见性。",
+  "com_tools_field_display_group": "展示分组",
+  "com_tools_display_group_hint": "选择工具分组；分组配置的可见组决定该工具对哪些用户可见（分组页可管理）。",
+  "com_tools_display_group_none": "未分组",
+  "com_tools_field_help_url": "帮助文档地址",
+  "com_tools_field_usage_stats": "使用统计",
+  "com_tools_group_allowed_groups": "该组工具的可见组",
+  "com_tools_group_allowed_hint": "不选 = 不限（全员可见）。仅归入本分组的工具受其约束。",
+  "com_services_basemap": "底图",
+  "com_services_basemap_set": "设为底图",
+  "com_services_basemap_clear": "取消底图",
+  "com_services_field_map_name": "地图名（可选）",
+  "com_services_map_name_hint": "如 dom",
+  "com_services_map_name_hint2": "留空 = 服务级绑定（添加图层时列出服务内全部地图）；设为底图需指定地图。",
+  "com_services_discover": "自动探测",
+  "com_services_discover_title": "从 iServer 基地址探测服务",
+  "com_services_discover_base": "iServer 基地址",
+  "com_services_discover_base_hint": "如 http://192.168.5.28:8090（可带 /iserver）",
+  "com_services_discover_run": "探测",
+  "com_services_discover_bind": "绑定所选",
+  "com_services_discover_running": "探测中…",
+  "com_services_discover_maps_n": "{n} 幅地图",
+  "com_services_discover_ds_n": "{n} 个数据源",
+  "com_services_discover_unavailable": "不可用",
+  "com_services_discover_empty": "该基地址下没有可绑定的 REST 服务",
+  "com_services_field_service_url": "服务地址",
+  "com_services_service_url_hint": "完整地址，如 http://192.168.5.28:8090/iserver/services/data-BeiJing/rest/data",
+  "com_services_basemap_section": "底图设置",
+  "com_services_basemap_list_maps": "列出地图",
+  "com_services_basemap_save": "保存为底图组",
+  "com_services_basemap_current": "当前底图组",
+  "com_services_basemap_none": "未设置底图",
+  "com_services_list_datasources": "列出数据源",
+  "com_services_basemap_saved": "底图组已保存",
+  "com_services_tab_bindings": "服务绑定",
+  "com_services_tab_basemaps": "底图管理",
+  "com_basemaps_hint": "底图组按叠放顺序渲染在地图最底层（前者在下，可叠加影像与注记等多幅）。修改后刷新地图浏览器生效。",
+  "com_basemaps_current": "当前底图组",
+  "com_basemaps_order_hint": "（自下而上）",
+  "com_basemaps_pick": "从已绑定的地图服务选择地图",
+  "com_basemaps_pick_service": "选择服务",
+  "com_basemaps_pick_layer": "选择地图",
+  "com_basemaps_pick_layer_of": "{{service}} 的地图",
+  "com_basemaps_search": "搜索",
+  "com_param_add": "添加参数",
+  "com_param_add_string": "字符串",
+  "com_param_add_number": "数字",
+  "com_param_add_integer": "整数",
+  "com_param_add_boolean": "布尔",
+  "com_param_add_array_multiselect": "多选数组",
+  "com_param_type_string": "字符串",
+  "com_param_type_number": "数字",
+  "com_param_type_integer": "整数",
+  "com_param_type_boolean": "布尔",
+  "com_param_type_array": "数组",
+  "com_param_field_accept": "accept 扩展名",
+  "com_param_add_textarea": "多行文本",
+  "com_param_add_date": "日期",
+  "com_param_add_datetime": "日期时间",
+  "com_param_add_file": "文件",
+  "com_param_add_directory": "目录",
+  "com_param_add_upload": "云盘文件",
+  "com_param_add_hidden": "隐藏值",
+  "com_param_field_name": "参数名",
+  "com_param_field_label": "标题",
+  "com_param_field_help": "描述",
+  "com_param_field_placeholder": "占位符",
+  "com_param_field_default": "默认值",
+  "com_param_field_widget": "控件",
+  "com_param_widget_auto": "自动（文本）",
+  "com_param_widget_textarea": "多行文本",
+  "com_param_widget_date": "日期",
+  "com_param_widget_datetime": "日期时间",
+  "com_param_widget_file": "文件",
+  "com_param_widget_directory": "目录",
+  "com_param_widget_upload": "云盘文件",
+  "com_param_widget_hidden": "隐藏",
+  "com_param_required": "必填",
+  "com_param_enum": "枚举选项（下拉）",
+  "com_param_enum_add": "+ 选项",
+  "com_param_choices": "静态选项",
+  "com_param_choices_static": "静态列表",
+  "com_param_choices_from": "动态来源 choices_from",
+  "com_param_choices_from_hint": "如 spatial.registry_layers",
+  "com_param_mode_visual": "可视化编辑",
+  "com_param_mode_json": "JSON",
+  "com_param_json_error": "JSON 语法错误，修正后才能使用可视化编辑",
+  "com_param_name_invalid": "参数名只能包含字母、数字、下划线、点、连字符，且不可重复",
+  "com_param_empty": "尚无参数——点右上「添加参数」",
+  "com_param_type": "类型"
+}
diff --git a/src/routeTree.gen.ts b/src/routeTree.gen.ts
index 5a003893..50a0cc17 100644
--- a/src/routeTree.gen.ts
+++ b/src/routeTree.gen.ts
@@ -13,6 +13,9 @@ import { Route as LoginRouteImport } from './routes/login'
 import { Route as AppRouteImport } from './routes/_app'
 import { Route as AppIndexRouteImport } from './routes/_app/index'
 import { Route as AppUsersRouteImport } from './routes/_app/users'
+import { Route as AppUsageRouteImport } from './routes/_app/usage'
+import { Route as AppToolsRouteImport } from './routes/_app/tools'
+import { Route as AppServicesRouteImport } from './routes/_app/services'
 import { Route as AppHelpRouteImport } from './routes/_app/help'
 import { Route as AppGrantsRouteImport } from './routes/_app/grants'
 import { Route as AppAccessRouteImport } from './routes/_app/access'
@@ -38,6 +41,21 @@ const AppUsersRoute = AppUsersRouteImport.update({
   path: '/users',
   getParentRoute: () => AppRoute,
 } as any)
+const AppUsageRoute = AppUsageRouteImport.update({
+  id: '/usage',
+  path: '/usage',
+  getParentRoute: () => AppRoute,
+} as any)
+const AppToolsRoute = AppToolsRouteImport.update({
+  id: '/tools',
+  path: '/tools',
+  getParentRoute: () => AppRoute,
+} as any)
+const AppServicesRoute = AppServicesRouteImport.update({
+  id: '/services',
+  path: '/services',
+  getParentRoute: () => AppRoute,
+} as any)
 const AppHelpRoute = AppHelpRouteImport.update({
   id: '/help',
   path: '/help',
@@ -70,6 +88,9 @@ export interface FileRoutesByFullPath {
   '/access': typeof AppAccessRoute
   '/grants': typeof AppGrantsRoute
   '/help': typeof AppHelpRoute
+  '/services': typeof AppServicesRoute
+  '/tools': typeof AppToolsRoute
+  '/usage': typeof AppUsageRoute
   '/users': typeof AppUsersRoute
   '/auth/openid/callback': typeof AuthOpenidCallbackRoute
   '/configuration/': typeof AppConfigurationIndexRoute
@@ -79,6 +100,9 @@ export interface FileRoutesByTo {
   '/access': typeof AppAccessRoute
   '/grants': typeof AppGrantsRoute
   '/help': typeof AppHelpRoute
+  '/services': typeof AppServicesRoute
+  '/tools': typeof AppToolsRoute
+  '/usage': typeof AppUsageRoute
   '/users': typeof AppUsersRoute
   '/': typeof AppIndexRoute
   '/auth/openid/callback': typeof AuthOpenidCallbackRoute
@@ -91,6 +115,9 @@ export interface FileRoutesById {
   '/_app/access': typeof AppAccessRoute
   '/_app/grants': typeof AppGrantsRoute
   '/_app/help': typeof AppHelpRoute
+  '/_app/services': typeof AppServicesRoute
+  '/_app/tools': typeof AppToolsRoute
+  '/_app/usage': typeof AppUsageRoute
   '/_app/users': typeof AppUsersRoute
   '/_app/': typeof AppIndexRoute
   '/auth/openid/callback': typeof AuthOpenidCallbackRoute
@@ -104,6 +131,9 @@ export interface FileRouteTypes {
     | '/access'
     | '/grants'
     | '/help'
+    | '/services'
+    | '/tools'
+    | '/usage'
     | '/users'
     | '/auth/openid/callback'
     | '/configuration/'
@@ -113,6 +143,9 @@ export interface FileRouteTypes {
     | '/access'
     | '/grants'
     | '/help'
+    | '/services'
+    | '/tools'
+    | '/usage'
     | '/users'
     | '/'
     | '/auth/openid/callback'
@@ -124,6 +157,9 @@ export interface FileRouteTypes {
     | '/_app/access'
     | '/_app/grants'
     | '/_app/help'
+    | '/_app/services'
+    | '/_app/tools'
+    | '/_app/usage'
     | '/_app/users'
     | '/_app/'
     | '/auth/openid/callback'
@@ -166,6 +202,27 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AppUsersRouteImport
       parentRoute: typeof AppRoute
     }
+    '/_app/usage': {
+      id: '/_app/usage'
+      path: '/usage'
+      fullPath: '/usage'
+      preLoaderRoute: typeof AppUsageRouteImport
+      parentRoute: typeof AppRoute
+    }
+    '/_app/tools': {
+      id: '/_app/tools'
+      path: '/tools'
+      fullPath: '/tools'
+      preLoaderRoute: typeof AppToolsRouteImport
+      parentRoute: typeof AppRoute
+    }
+    '/_app/services': {
+      id: '/_app/services'
+      path: '/services'
+      fullPath: '/services'
+      preLoaderRoute: typeof AppServicesRouteImport
+      parentRoute: typeof AppRoute
+    }
     '/_app/help': {
       id: '/_app/help'
       path: '/help'
@@ -208,6 +265,9 @@ interface AppRouteChildren {
   AppAccessRoute: typeof AppAccessRoute
   AppGrantsRoute: typeof AppGrantsRoute
   AppHelpRoute: typeof AppHelpRoute
+  AppServicesRoute: typeof AppServicesRoute
+  AppToolsRoute: typeof AppToolsRoute
+  AppUsageRoute: typeof AppUsageRoute
   AppUsersRoute: typeof AppUsersRoute
   AppIndexRoute: typeof AppIndexRoute
   AppConfigurationIndexRoute: typeof AppConfigurationIndexRoute
@@ -217,6 +277,9 @@ const AppRouteChildren: AppRouteChildren = {
   AppAccessRoute: AppAccessRoute,
   AppGrantsRoute: AppGrantsRoute,
   AppHelpRoute: AppHelpRoute,
+  AppServicesRoute: AppServicesRoute,
+  AppToolsRoute: AppToolsRoute,
+  AppUsageRoute: AppUsageRoute,
   AppUsersRoute: AppUsersRoute,
   AppIndexRoute: AppIndexRoute,
   AppConfigurationIndexRoute: AppConfigurationIndexRoute,
diff --git a/src/routes/__root.tsx b/src/routes/__root.tsx
index 18d99af2..c44fc078 100644
--- a/src/routes/__root.tsx
+++ b/src/routes/__root.tsx
@@ -80,7 +80,9 @@ function RootPending() {
   const localize = useLocalize();
   return (
     <div className="flex min-h-screen items-center justify-center bg-(--cui-color-background-default)">
-      <div className="animate-pulse text-lg text-(--cui-color-text-muted)">
+      {/* SSR renders the default locale; the browser may resolve another one on
+          hydration, so suppress the expected text mismatch (same as <html lang>). */}
+      <div className="animate-pulse text-lg text-(--cui-color-text-muted)" suppressHydrationWarning>
         {localize('com_ui_loading')}
       </div>
     </div>
diff --git a/src/routes/_app.tsx b/src/routes/_app.tsx
index 4eeb0421..eb3269d6 100644
--- a/src/routes/_app.tsx
+++ b/src/routes/_app.tsx
@@ -16,10 +16,12 @@ const ROUTE_TITLE_KEYS: Record<string, string> = {
   '/users': 'com_users_title',
   '/access': 'com_access_title',
   '/grants': 'com_grants_title',
+  '/tools': 'com_tools_title',
+  '/usage': 'com_usage_title',
+  '/services': 'com_services_title',
   '/help': 'com_help_title',
 };
 
-
 export const Route = createFileRoute('/_app')({
   beforeLoad: async ({ location }) => {
     const result = await verifyAdminTokenFn();
diff --git a/src/routes/_app/services.tsx b/src/routes/_app/services.tsx
new file mode 100644
index 00000000..fcefdd4d
--- /dev/null
+++ b/src/routes/_app/services.tsx
@@ -0,0 +1,10 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { ServicesPage } from '@/components/services';
+
+export const Route = createFileRoute('/_app/services')({
+  component: ServicesRoute,
+});
+
+function ServicesRoute() {
+  return <ServicesPage />;
+}
diff --git a/src/routes/_app/tools.tsx b/src/routes/_app/tools.tsx
new file mode 100644
index 00000000..5ae7d48f
--- /dev/null
+++ b/src/routes/_app/tools.tsx
@@ -0,0 +1,29 @@
+import { createFileRoute, useNavigate } from '@tanstack/react-router';
+import { ToolsPage } from '@/components/tools';
+
+type Tab = 'catalog' | 'groups' | 'usage';
+
+function isValidTab(value?: string): value is Tab {
+  return value === 'catalog' || value === 'groups' || value === 'usage';
+}
+
+export const Route = createFileRoute('/_app/tools')({
+  validateSearch: (search: Record<string, unknown>): { tab?: string } => ({
+    tab: typeof search.tab === 'string' ? search.tab : undefined,
+  }),
+  component: ToolsRoute,
+});
+
+function ToolsRoute() {
+  const { tab } = Route.useSearch();
+  const navigate = useNavigate({ from: '/tools' });
+  const activeTab: Tab = isValidTab(tab) ? tab : 'catalog';
+
+  const handleTabChange = (value: string) => {
+    if (isValidTab(value)) {
+      navigate({ search: (prev: Record<string, unknown>) => ({ ...prev, tab: value }) });
+    }
+  };
+
+  return <ToolsPage activeTab={activeTab} onTabChange={handleTabChange} />;
+}
diff --git a/src/routes/_app/usage.tsx b/src/routes/_app/usage.tsx
new file mode 100644
index 00000000..ef7a51e4
--- /dev/null
+++ b/src/routes/_app/usage.tsx
@@ -0,0 +1,8 @@
+import { createFileRoute, redirect } from '@tanstack/react-router';
+
+/** 使用统计并入工具管理页（2.16.0）：旧链接与书签直接落到 /tools?tab=usage。 */
+export const Route = createFileRoute('/_app/usage')({
+  beforeLoad: () => {
+    throw redirect({ to: '/tools', search: { tab: 'usage' } });
+  },
+});
diff --git a/src/server/index.ts b/src/server/index.ts
index ad8cf1d7..fc6a9586 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -5,4 +5,5 @@ export * from './groups';
 export * from './langfuse';
 export * from './roles';
 export * from './scopes';
+export * from './terravox';
 export * from './users';
diff --git a/src/server/terravox.runReports.test.ts b/src/server/terravox.runReports.test.ts
new file mode 100644
index 00000000..f06025a0
--- /dev/null
+++ b/src/server/terravox.runReports.test.ts
@@ -0,0 +1,176 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+/**
+ * Run-report server fns (usage statistics): query serialization, page fetch,
+ * and the export loop's paging/truncation — `createServerFn` mocked to pass
+ * handlers through, `apiFetch` serving queued pages.
+ */
+
+type QueuedPage = {
+  ok?: boolean;
+  status?: number;
+  body: unknown;
+};
+
+let queued: QueuedPage[] = [];
+
+const apiFetchMock = vi.fn(async (..._args: unknown[]) => {
+  const page = queued.shift();
+  if (!page) {
+    throw new Error('unexpected apiFetch call');
+  }
+  return {
+    ok: page.ok ?? true,
+    status: page.status ?? 200,
+    json: async () => page.body,
+  };
+});
+
+vi.mock('./utils/api', () => ({
+  apiFetch: (...args: unknown[]) => apiFetchMock(...args),
+}));
+
+vi.mock('@tanstack/react-start', () => ({
+  createServerFn: () => ({
+    handler: (fn: (...args: unknown[]) => unknown) => fn,
+    inputValidator: () => ({
+      handler: (fn: (...args: unknown[]) => unknown) => fn,
+    }),
+  }),
+}));
+
+vi.mock('@tanstack/react-query', () => ({
+  queryOptions: (opts: unknown) => opts,
+}));
+
+import {
+  RUN_REPORTS_EXPORT_CAP,
+  buildRunReportsQuery,
+  exportRunReportsFn,
+  getRunReportsFn,
+} from './terravox';
+
+function report(id: string, over: Record<string, unknown> = {}) {
+  return {
+    id,
+    user_sub: 'user-wang',
+    username: 'wangjianbo',
+    tool_id: 'wangjianbo.toolsdemo',
+    version: '1.0.0',
+    status: 'succeeded',
+    duration_ms: 8500,
+    argument_keys: ['text'],
+    source: 'toolbox',
+    created_at: '2026-09-28T10:00:00Z',
+    ...over,
+  };
+}
+
+describe('buildRunReportsQuery', () => {
+  it('always carries paging and drops empty filter values', () => {
+    expect(
+      buildRunReportsQuery(
+        { tool_id: 'wangjianbo.toolsdemo', user_sub: '', since: undefined },
+        50,
+        100,
+      ),
+    ).toBe('?limit=50&offset=100&tool_id=wangjianbo.toolsdemo');
+  });
+
+  it('with no filters only paging remains', () => {
+    expect(buildRunReportsQuery({}, 200, 0)).toBe('?limit=200&offset=0');
+  });
+});
+
+describe('getRunReportsFn', () => {
+  beforeEach(() => {
+    queued = [];
+    apiFetchMock.mockClear();
+  });
+
+  it('hits the proxied admin route with default paging and parses rows', async () => {
+    queued.push({ body: { reports: [report('r1', { status: 'failed' })], total: 1 } });
+    const result = await getRunReportsFn({ data: { tool_id: 'wangjianbo.toolsdemo' } });
+    expect(apiFetchMock).toHaveBeenCalledWith(
+      '/api/terravox/admin/runs/reports?limit=50&offset=0&tool_id=wangjianbo.toolsdemo',
+    );
+    expect(result.total).toBe(1);
+    expect(result.reports[0]).toMatchObject({ id: 'r1', status: 'failed', username: 'wangjianbo' });
+  });
+
+  it('applies defaults for optional/missing fields', async () => {
+    queued.push({
+      body: {
+        reports: [{ id: 'r2', user_sub: 'u', tool_id: 't', status: 'timeout', created_at: 't0' }],
+        total: 1,
+      },
+    });
+    const result = await getRunReportsFn({ data: {} });
+    expect(result.reports[0]).toMatchObject({
+      username: '',
+      version: null,
+      duration_ms: null,
+      argument_keys: [],
+      source: '',
+    });
+  });
+
+  it('surfaces gateway error details', async () => {
+    queued.push({ ok: false, status: 500, body: { detail: 'boom' } });
+    await expect(getRunReportsFn({ data: {} })).rejects.toThrow('boom');
+  });
+});
+
+describe('exportRunReportsFn', () => {
+  beforeEach(() => {
+    queued = [];
+    apiFetchMock.mockClear();
+  });
+
+  it('pages with the 200-row max until a short page, untruncated', async () => {
+    const first = Array.from({ length: 200 }, (_, i) => report(`a${i}`));
+    const second = Array.from({ length: 150 }, (_, i) => report(`b${i}`));
+    queued.push({ body: { reports: first, total: 350 } });
+    queued.push({ body: { reports: second, total: 350 } });
+
+    const result = await exportRunReportsFn({ data: { tool_id: 'wangjianbo.toolsdemo' } });
+
+    expect(apiFetchMock).toHaveBeenCalledTimes(2);
+    expect(apiFetchMock).toHaveBeenNthCalledWith(
+      1,
+      '/api/terravox/admin/runs/reports?limit=200&offset=0&tool_id=wangjianbo.toolsdemo',
+    );
+    expect(apiFetchMock).toHaveBeenNthCalledWith(
+      2,
+      '/api/terravox/admin/runs/reports?limit=200&offset=200&tool_id=wangjianbo.toolsdemo',
+    );
+    expect(result.reports).toHaveLength(350);
+    expect(result.truncated).toBe(false);
+  });
+
+  it('stops exactly at the 10k cap and flags truncation', async () => {
+    /** 50 full pages → 10 000 rows collected, 50 more exist beyond the cap. */
+    for (let page = 0; page < 50; page++) {
+      queued.push({
+        body: {
+          reports: Array.from({ length: 200 }, (_, i) => report(`p${page}-${i}`)),
+          total: RUN_REPORTS_EXPORT_CAP + 50,
+        },
+      });
+    }
+
+    const result = await exportRunReportsFn({ data: {} });
+
+    expect(apiFetchMock).toHaveBeenCalledTimes(50);
+    expect(result.reports).toHaveLength(RUN_REPORTS_EXPORT_CAP);
+    expect(result.truncated).toBe(true);
+  });
+
+  it('single short page returns immediately without a second round-trip', async () => {
+    queued.push({ body: { reports: [report('only')], total: 1 } });
+    const result = await exportRunReportsFn({ data: {} });
+    expect(apiFetchMock).toHaveBeenCalledTimes(1);
+    expect(result.reports).toHaveLength(1);
+    expect(result.truncated).toBe(false);
+  });
+});
diff --git a/src/server/terravox.ts b/src/server/terravox.ts
new file mode 100644
index 00000000..05d2d0ec
--- /dev/null
+++ b/src/server/terravox.ts
@@ -0,0 +1,798 @@
+/**
+ * Server functions for TerraVox tool management.
+ *
+ * All calls go through the LibreChat proxy (/api/terravox/*), which forwards to
+ * the Tool Gateway with the shared service token and this admin's acting
+ * identity (the proxy enforces ACCESS_ADMIN before forwarding).
+ */
+
+import { z } from 'zod';
+import { queryOptions } from '@tanstack/react-query';
+import { createServerFn } from '@tanstack/react-start';
+import { apiFetch } from './utils/api';
+import type {
+  TerraVoxTool,
+  TerraVoxGroup,
+  TerraVoxGroupMeta,
+  GiteaReposResult,
+  GiteaCheckResult,
+  PendingToolUpdate,
+  RunReport,
+  RunReportFilters,
+  TerraVoxService,
+  BasemapItem,
+  DiscoveredService
+} from '@/types/terravox';
+
+// ── Types ──────────────────────────────────────────────────────────
+// 定义在 src/types/terravox.ts（CLAUDE.md：本地接口一律入 src/types/）；
+// 此处 type-only 再导出，既有 `from '@/server'` 导入方零改动。
+export type {
+  JsonValue,
+  TerraVoxTool,
+  TerraVoxGroup,
+  TerraVoxGroupMeta,
+  ImportResult,
+  GiteaRepoSummary,
+  GiteaOwner,
+  GiteaReposResult,
+  GiteaReleaseInfo,
+  GiteaCheckItem,
+  GiteaCheckResult,
+  PendingPackageMeta,
+  PendingToolUpdate,
+  RunReport,
+  RunReportFilters,
+  TerraVoxService,
+  TerraVoxServiceInput,
+  BasemapItem,
+  DiscoveredService
+} from '@/types/terravox';
+
+// ── Types ────────────────────────────────────────────────────────────
+
+
+// ── Gitea 分发（「从 Gitea 导入」）───────────────────────────────────
+
+
+// ── 待确认更新（2.8.0 治理决策）─────────────────────────────────────
+
+
+// ── Runtime guards (shape only — the gateway validates semantics) ────
+
+const toolManifestSchema = z
+  .object({
+    tool_id: z.string(),
+    version: z.string(),
+    display_name: z.string(),
+    description: z.string(),
+  })
+  .passthrough();
+
+const toolGroupSchema = z.object({
+  name: z.string(),
+  display_name: z.string().optional().default(''),
+  description: z.string().optional().default(''),
+  sort_order: z.number().optional().default(0),
+  allowed_groups: z.array(z.string()).optional().default([]),
+  tool_count: z.number().optional().default(0),
+  explicit: z.boolean().optional().default(false),
+});
+
+const toolGroupMetaSchema = z.object({
+  name: z.string(),
+  display_name: z.string().optional().default(''),
+  sort_order: z.number().optional().default(0),
+});
+
+const giteaCheckItemSchema = z.object({
+  key: z.string(),
+  level: z.enum(['ok', 'warn', 'error']),
+  message: z.string(),
+});
+
+const pendingToolUpdateSchema = z.object({
+  tool_id: z.string(),
+  display_name: z.string(),
+  owner: z.string().optional(),
+  repo: z.string().optional(),
+  current_version: z.string(),
+  package: z.object({
+    version: z.string(),
+    size: z.number(),
+    updated_at: z.string(),
+  }),
+});
+
+// ── Error plumbing ───────────────────────────────────────────────────
+
+/** Gateway error detail ({code, message, errors?}) flattened for the UI. */
+export async function gatewayError(response: Response): Promise<never> {
+  let message = `Request failed: ${String(response.status)}`;
+  let code: string | undefined;
+  let errors: { path?: string; message: string }[] | undefined;
+  try {
+    const body = (await response.json()) as {
+      detail?: unknown;
+      message?: unknown;
+    };
+    const detail = body?.detail ?? body;
+    if (typeof detail === 'string') {
+      message = detail;
+    } else if (detail && typeof detail === 'object') {
+      const d = detail as {
+        message?: unknown;
+        code?: unknown;
+        errors?: unknown;
+      };
+      if (typeof d.message === 'string') {
+        message = d.message;
+      }
+      if (typeof d.code === 'string') {
+        code = d.code;
+      }
+      if (Array.isArray(d.errors)) {
+        errors = d.errors
+          .map((e) => {
+            const item = e as { path?: unknown; message?: unknown };
+            return {
+              path: typeof item.path === 'string' ? item.path : undefined,
+              message: typeof item.message === 'string' ? item.message : String(item),
+            };
+          })
+          .filter((e) => e.message);
+      }
+    }
+  } catch {
+    /* non-JSON body — keep the status message */
+  }
+  const error = new Error(message) as Error & {
+    status?: number;
+    code?: string;
+    errors?: { path?: string; message: string }[];
+  };
+  error.status = response.status;
+  error.code = code;
+  error.errors = errors;
+  throw error;
+}
+
+// ── Catalog ──────────────────────────────────────────────────────────
+
+export const getToolsFn = createServerFn({ method: 'GET' }).handler(
+  async (): Promise<{ tools: TerraVoxTool[]; groups: TerraVoxGroupMeta[] }> => {
+    const response = await apiFetch('/api/terravox/tools/all');
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    const json = (await response.json()) as {
+      tools?: unknown[];
+      groups?: unknown[];
+    };
+    const parsed = z.array(toolManifestSchema).safeParse(json.tools ?? []);
+    if (!parsed.success) {
+      throw new Error('Failed to parse tool catalog');
+    }
+    const groups = z.array(toolGroupMetaSchema).safeParse(json.groups ?? []);
+    return {
+      tools: parsed.data as TerraVoxTool[],
+      groups: groups.success ? (groups.data as TerraVoxGroupMeta[]) : [],
+    };
+  },
+);
+
+export const toolsQueryOptions = queryOptions({
+  queryKey: ['terravox', 'tools', 'all'],
+  queryFn: () => getToolsFn(),
+  staleTime: 30_000,
+});
+
+// ── Groups ───────────────────────────────────────────────────────────
+
+export const getToolGroupsFn = createServerFn({ method: 'GET' }).handler(
+  async (): Promise<{ groups: TerraVoxGroup[] }> => {
+    const response = await apiFetch('/api/terravox/admin/groups');
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    const parsed = z.object({ groups: z.array(toolGroupSchema) }).safeParse(await response.json());
+    if (!parsed.success) {
+      throw new Error('Failed to parse tool groups');
+    }
+    return { groups: parsed.data.groups as TerraVoxGroup[] };
+  },
+);
+
+export const toolGroupsQueryOptions = queryOptions({
+  queryKey: ['terravox', 'groups'],
+  queryFn: () => getToolGroupsFn().then((r) => r.groups),
+  staleTime: 30_000,
+});
+
+const groupInputSchema = z.object({
+  name: z.string().optional(),
+  display_name: z.string().optional(),
+  description: z.string().optional(),
+  sort_order: z.number().optional(),
+  allowed_groups: z.array(z.string()).optional(),
+});
+
+export const createToolGroupFn = createServerFn({ method: 'POST' })
+  .inputValidator(groupInputSchema)
+  .handler(async ({ data }) => {
+    const response = await apiFetch('/api/terravox/admin/groups', {
+      method: 'POST',
+      body: JSON.stringify(data),
+    });
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    return response.json();
+  });
+
+export const updateToolGroupFn = createServerFn({ method: 'POST' })
+  .inputValidator(
+    groupInputSchema.extend({
+      name: z.string(),
+    }),
+  )
+  .handler(async ({ data }) => {
+    const { name, ...patch } = data;
+    const response = await apiFetch(`/api/terravox/admin/groups/${encodeURIComponent(name)}`, {
+      method: 'PATCH',
+      body: JSON.stringify(patch),
+    });
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    return response.json();
+  });
+
+export const deleteToolGroupFn = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ name: z.string() }))
+  .handler(async ({ data }) => {
+    const response = await apiFetch(`/api/terravox/admin/groups/${encodeURIComponent(data.name)}`, {
+      method: 'DELETE',
+    });
+    if (!response.ok && response.status !== 404) {
+      await gatewayError(response);
+    }
+    return { deleted: data.name };
+  });
+
+// ── Handlers ─────────────────────────────────────────────────────────
+
+export const getHandlersFn = createServerFn({ method: 'GET' }).handler(async () => {
+  const response = await apiFetch('/api/terravox/admin/handlers');
+  if (!response.ok) {
+    await gatewayError(response);
+  }
+  const parsed = z.object({ handlers: z.array(z.string()) }).safeParse(await response.json());
+  if (!parsed.success) {
+    throw new Error('Failed to parse handlers');
+  }
+  return parsed.data;
+});
+
+export const handlersQueryOptions = queryOptions({
+  queryKey: ['terravox', 'handlers'],
+  queryFn: () => getHandlersFn().then((r) => r.handlers),
+  staleTime: 5 * 60_000,
+});
+
+// ── Tool CRUD ────────────────────────────────────────────────────────
+
+export const createToolFn = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ manifest: z.record(z.string(), z.any()) }))
+  .handler(async ({ data }) => {
+    const response = await apiFetch('/api/terravox/admin/tools', {
+      method: 'POST',
+      body: JSON.stringify(data.manifest),
+    });
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    return response.json();
+  });
+
+export const updateToolFn = createServerFn({ method: 'POST' })
+  .inputValidator(
+    z.object({
+      toolId: z.string(),
+      manifest: z.record(z.string(), z.any()),
+    }),
+  )
+  .handler(async ({ data }) => {
+    const response = await apiFetch(
+      `/api/terravox/admin/tools/${encodeURIComponent(data.toolId)}`,
+      {
+        method: 'PUT',
+        body: JSON.stringify(data.manifest),
+      },
+    );
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    return response.json();
+  });
+
+export const toggleToolFn = createServerFn({ method: 'POST' })
+  .inputValidator(
+    z.object({
+      toolId: z.string(),
+      enabled: z.boolean(),
+    }),
+  )
+  .handler(async ({ data }) => {
+    const response = await apiFetch(
+      `/api/terravox/admin/tools/${encodeURIComponent(data.toolId)}`,
+      {
+        method: 'PATCH',
+        body: JSON.stringify({ enabled: data.enabled }),
+      },
+    );
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    return response.json();
+  });
+
+export const deleteToolFn = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ toolId: z.string() }))
+  .handler(async ({ data }) => {
+    const response = await apiFetch(
+      `/api/terravox/admin/tools/${encodeURIComponent(data.toolId)}`,
+      { method: 'DELETE' },
+    );
+    if (!response.ok && response.status !== 404) {
+      await gatewayError(response);
+    }
+    return { deleted: data.toolId };
+  });
+
+// ── Import ───────────────────────────────────────────────────────────
+
+export const importToolsFn = createServerFn({ method: 'POST' })
+  .inputValidator(
+    z.object({
+      tools: z.array(z.record(z.string(), z.any())).min(1),
+      overwrite: z.boolean().default(false),
+      dryRun: z.boolean().default(false),
+    }),
+  )
+  .handler(async ({ data }) => {
+    const response = await apiFetch('/api/terravox/admin/tools/import', {
+      method: 'POST',
+      body: JSON.stringify({
+        tools: data.tools,
+        overwrite: data.overwrite,
+        dry_run: data.dryRun,
+      }),
+    });
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    const parsed = z
+      .object({
+        results: z.array(
+          z.object({
+            tool_id: z.string(),
+            action: z.enum(['created', 'updated', 'skipped', 'failed']),
+            error: z.string().optional(),
+          }),
+        ),
+        dry_run: z.boolean().optional(),
+      })
+      .safeParse(await response.json());
+    if (!parsed.success) {
+      throw new Error('Failed to parse import results');
+    }
+    return parsed.data;
+  });
+
+// ── Gitea 分发（「从 Gitea 导入」）───────────────────────────────────
+
+export const giteaReposFn = createServerFn({ method: 'GET' })
+  .inputValidator(z.object({ baseUrl: z.string().optional() }))
+  .handler(async ({ data }): Promise<GiteaReposResult> => {
+    const qs = data.baseUrl ? `?base_url=${encodeURIComponent(data.baseUrl)}` : '';
+    const response = await apiFetch(`/api/terravox/admin/gitea/repos${qs}`);
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    const parsed = z
+      .object({
+        base_url: z.string(),
+        owners: z.array(
+          z.object({
+            login: z.string(),
+            repos: z.array(
+              z.object({
+                name: z.string(),
+                description: z.string().optional(),
+                updated_at: z.string().optional(),
+              }),
+            ),
+          }),
+        ),
+      })
+      .safeParse(await response.json());
+    if (!parsed.success) {
+      throw new Error('Failed to parse Gitea repository listing');
+    }
+    return parsed.data as GiteaReposResult;
+  });
+
+/** Gitea 地址 → owner 分组仓库列表（随地址变化重新拉取）。空串 = 网关默认地址。 */
+export const giteaReposQueryOptions = (baseUrl: string) =>
+  queryOptions({
+    queryKey: ['terravox', 'gitea', 'repos', baseUrl],
+    queryFn: () => giteaReposFn({ data: { baseUrl: baseUrl || undefined } }),
+    staleTime: 60_000,
+  });
+
+export const giteaCheckRepoFn = createServerFn({ method: 'POST' })
+  .inputValidator(
+    z.object({
+      owner: z.string().min(1),
+      repo: z.string().min(1),
+      baseUrl: z.string().optional(),
+    }),
+  )
+  .handler(async ({ data }): Promise<GiteaCheckResult> => {
+    const response = await apiFetch('/api/terravox/admin/gitea/repos/check', {
+      method: 'POST',
+      body: JSON.stringify({
+        owner: data.owner,
+        repo: data.repo,
+        ...(data.baseUrl ? { base_url: data.baseUrl } : {}),
+      }),
+    });
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    const parsed = z
+      .object({
+        owner: z.string(),
+        repo: z.string(),
+        repo_description: z.string().optional(),
+        release: z
+          .object({
+            tag: z.string(),
+            published_at: z.string().optional(),
+            zip_asset: z.string().optional(),
+            zip_size: z.number().optional(),
+          })
+          .optional(),
+        tool_json: z.record(z.string(), z.any()).optional(),
+        checks: z.array(giteaCheckItemSchema),
+        installable: z.boolean(),
+      })
+      .safeParse(await response.json());
+    if (!parsed.success) {
+      throw new Error('Failed to parse Gitea repo check result');
+    }
+    return parsed.data as GiteaCheckResult;
+  });
+
+// ── 待确认更新 ───────────────────────────────────────────────────────
+
+export const getPendingUpdatesFn = createServerFn({ method: 'GET' }).handler(
+  async (): Promise<{ updates: PendingToolUpdate[] }> => {
+    const response = await apiFetch('/api/terravox/admin/tools/pending-updates');
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    const parsed = z
+      .object({ updates: z.array(pendingToolUpdateSchema) })
+      .safeParse(await response.json());
+    if (!parsed.success) {
+      throw new Error('Failed to parse pending tool updates');
+    }
+    return parsed.data as { updates: PendingToolUpdate[] };
+  },
+);
+
+/** 每分钟的刷新对齐网关 60s 的 Gitea 解析缓存；确认落库后 invalidate 即时清空。 */
+export const pendingUpdatesQueryOptions = queryOptions({
+  queryKey: ['terravox', 'pending-updates'],
+  queryFn: () => getPendingUpdatesFn().then((r) => r.updates),
+  staleTime: 60_000,
+  refetchInterval: 60_000,
+});
+
+// ── 使用统计（run_reports，local-tool-plan §11 步骤 3）───────────────
+
+
+export const RUN_REPORTS_PAGE_SIZE = 50;
+/** Gateway caps a page at 200 — the export loop uses that maximum. */
+const RUN_REPORTS_FETCH_LIMIT = 200;
+/** Hard export ceiling: a runaway filter must not loop the gateway forever. */
+export const RUN_REPORTS_EXPORT_CAP = 10_000;
+
+const runReportSchema = z.object({
+  id: z.string(),
+  user_sub: z.string(),
+  tool_name: z.string().nullable().optional().default(''),
+  username: z.string().nullable().optional().default(''),
+  user_name: z.string().nullable().optional().default(''),
+  tool_id: z.string(),
+  version: z.string().nullable().optional().default(null),
+  status: z.enum(['succeeded', 'failed', 'stopped', 'timeout']),
+  duration_ms: z.number().nullable().optional().default(null),
+  argument_keys: z.array(z.string()).optional().default([]),
+  source: z.string().optional().default(''),
+  created_at: z.string(),
+});
+
+const runReportFiltersSchema = z.object({
+  tool_id: z.string().optional(),
+  user_sub: z.string().optional(),
+  since: z.string().optional(),
+  until: z.string().optional(),
+});
+
+/** Serialize filters + paging into the gateway query string (empty values dropped). */
+export function buildRunReportsQuery(
+  filters: RunReportFilters,
+  limit: number,
+  offset: number,
+): string {
+  const params = new URLSearchParams({
+    limit: String(limit),
+    offset: String(offset),
+  });
+  for (const [key, value] of Object.entries(filters)) {
+    if (value !== undefined && value !== null && value !== '') {
+      params.set(key, value);
+    }
+  }
+  const qs = params.toString();
+  return qs ? `?${qs}` : '';
+}
+
+async function fetchRunReportsPage(
+  filters: RunReportFilters,
+  limit: number,
+  offset: number,
+): Promise<{ reports: RunReport[]; total: number }> {
+  const response = await apiFetch(
+    `/api/terravox/admin/runs/reports${buildRunReportsQuery(filters, limit, offset)}`,
+  );
+  if (!response.ok) {
+    await gatewayError(response);
+  }
+  const parsed = z
+    .object({ reports: z.array(runReportSchema), total: z.number() })
+    .safeParse(await response.json());
+  if (!parsed.success) {
+    throw new Error('Failed to parse run reports');
+  }
+  return parsed.data;
+}
+
+export const getRunReportsFn = createServerFn({ method: 'GET' })
+  .inputValidator(
+    runReportFiltersSchema.extend({
+      limit: z.number().int().min(1).max(RUN_REPORTS_FETCH_LIMIT).optional(),
+      offset: z.number().int().min(0).optional(),
+    }),
+  )
+  .handler(
+    async ({ data }): Promise<{ reports: RunReport[]; total: number }> =>
+      fetchRunReportsPage(data, data.limit ?? RUN_REPORTS_PAGE_SIZE, data.offset ?? 0),
+  );
+
+/** Paged table query — the Usage screen's main data source. */
+export const runReportsQueryOptions = (page: number, filters: RunReportFilters = {}) =>
+  queryOptions({
+    queryKey: ['terravox', 'runReports', page, filters] as const,
+    queryFn: () =>
+      getRunReportsFn({
+        data: {
+          ...filters,
+          limit: RUN_REPORTS_PAGE_SIZE,
+          offset: (Math.max(1, page) - 1) * RUN_REPORTS_PAGE_SIZE,
+        },
+      }),
+    staleTime: 60_000,
+  });
+
+/** Export path: page through the whole filter result (up to the cap) and hand
+ * the rows to the client, which builds the BOM'd UTF-8 CSV. */
+export const exportRunReportsFn = createServerFn({ method: 'POST' })
+  .inputValidator(runReportFiltersSchema)
+  .handler(async ({ data }): Promise<{ reports: RunReport[]; truncated: boolean }> => {
+    const reports: RunReport[] = [];
+    let offset = 0;
+    let total = Infinity;
+    for (;;) {
+      const page = await fetchRunReportsPage(data, RUN_REPORTS_FETCH_LIMIT, offset);
+      total = page.total;
+      reports.push(...page.reports);
+      if (reports.length >= RUN_REPORTS_EXPORT_CAP) {
+        reports.length = RUN_REPORTS_EXPORT_CAP;
+        return { reports, truncated: total > RUN_REPORTS_EXPORT_CAP };
+      }
+      if (reports.length >= total || page.reports.length < RUN_REPORTS_FETCH_LIMIT) {
+        return { reports, truncated: false };
+      }
+      offset += page.reports.length;
+    }
+  });
+
+// ── Service registry (contracts 2.16.0) ─────────────────────────────
+
+
+const serviceSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: z.string(),
+  base_url: z.string(),
+  service_path: z.string(),
+  datasource: z.string(),
+  allowed_groups: z.array(z.string()),
+  enabled: z.boolean(),
+  status: z.string(),
+  probe_detail: z.string(),
+  probed_at: z.string().nullable().optional().default(null),
+});
+
+export const getServicesFn = createServerFn({ method: 'GET' }).handler(
+  async (): Promise<{ services: TerraVoxService[]; total: number }> => {
+    const response = await apiFetch('/api/terravox/admin/services');
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    const json = (await response.json()) as { services?: unknown[]; total?: number };
+    const parsed = z.array(serviceSchema).safeParse(json.services ?? []);
+    if (!parsed.success) {
+      throw new Error('Failed to parse service registry');
+    }
+    return { services: parsed.data as TerraVoxService[], total: json.total ?? parsed.data.length };
+  },
+);
+
+export const servicesQueryOptions = queryOptions({
+  queryKey: ['terravox', 'admin', 'services'],
+  queryFn: () => getServicesFn(),
+  staleTime: 15_000,
+});
+
+export const createServiceFn = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ service: z.record(z.string(), z.any()) }))
+  .handler(async ({ data }) => {
+    const response = await apiFetch('/api/terravox/admin/services', {
+      method: 'POST',
+      body: JSON.stringify(data.service),
+    });
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    return response.json();
+  });
+
+export const updateServiceFn = createServerFn({ method: 'POST' })
+  .inputValidator(
+    z.object({
+      serviceId: z.string(),
+      service: z.record(z.string(), z.any()),
+    }),
+  )
+  .handler(async ({ data }) => {
+    const response = await apiFetch(
+      `/api/terravox/admin/services/${encodeURIComponent(data.serviceId)}`,
+      {
+        method: 'PATCH',
+        body: JSON.stringify(data.service),
+      },
+    );
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    return response.json();
+  });
+
+export const deleteServiceFn = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ serviceId: z.string() }))
+  .handler(async ({ data }) => {
+    const response = await apiFetch(
+      `/api/terravox/admin/services/${encodeURIComponent(data.serviceId)}`,
+      { method: 'DELETE' },
+    );
+    if (!response.ok && response.status !== 204) {
+      await gatewayError(response);
+    }
+    return { ok: true };
+  });
+
+
+export const getBasemapsFn = createServerFn({ method: 'GET' }).handler(async () => {
+  const response = await apiFetch('/api/terravox/admin/basemaps');
+  if (!response.ok) {
+    await gatewayError(response);
+  }
+  return (await response.json()) as { basemaps: BasemapItem[] };
+});
+
+export const replaceBasemapsFn = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ basemaps: z.array(z.object({
+    base_url: z.string(),
+    service_path: z.string(),
+    map_name: z.string().min(1),
+  })).max(10) }))
+  .handler(async ({ data }) => {
+    const response = await apiFetch('/api/terravox/admin/basemaps', {
+      method: 'PUT',
+      body: JSON.stringify({ basemaps: data.basemaps }),
+    });
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    return response.json();
+  });
+
+/** 列出地图服务绑定内的全部地图（管理端底图设置/编辑用）。 */
+export const listServiceMapsFn = createServerFn({ method: 'GET' })
+  .inputValidator(z.object({ serviceId: z.string() }))
+  .handler(async ({ data }) => {
+    const response = await apiFetch(
+      `/api/terravox/admin/services/${encodeURIComponent(data.serviceId)}/maps`,
+    );
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    return (await response.json()) as {
+      id: string;
+      name: string;
+      maps: { name: string; path: string }[];
+      total: number;
+    };
+  });
+
+
+export const discoverServicesFn = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ baseUrl: z.string().min(1).max(512) }))
+  .handler(async ({ data }) => {
+    const response = await apiFetch('/api/terravox/admin/services/discover', {
+      method: 'POST',
+      body: JSON.stringify({ base_url: data.baseUrl.trim() }),
+    });
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    const json = (await response.json()) as {
+      base: string;
+      services: DiscoveredService[];
+      total: number;
+    };
+    return json;
+  });
+
+export const probeServiceFn = createServerFn({ method: 'POST' })
+  .inputValidator(z.object({ serviceId: z.string() }))
+  .handler(async ({ data }) => {
+    const response = await apiFetch(
+      `/api/terravox/admin/services/${encodeURIComponent(data.serviceId)}/probe`,
+      { method: 'POST' },
+    );
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    return response.json();
+  });
+
+export const getServiceDatasourcesFn = createServerFn({ method: 'GET' })
+  .inputValidator(z.object({ serviceId: z.string() }))
+  .handler(async ({ data }) => {
+    const response = await apiFetch(
+      `/api/terravox/admin/services/${encodeURIComponent(data.serviceId)}/datasources`,
+    );
+    if (!response.ok) {
+      await gatewayError(response);
+    }
+    return (await response.json()) as {
+      datasources: string[];
+      dataset_counts: Record<string, number>;
+    };
+  });
diff --git a/src/styles.css b/src/styles.css
index 91e8d01f..fcf8c04c 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -910,3 +910,24 @@ body > div:has(+ .modal-frost) {
   background-color: var(--cui-color-feedback-user-bg);
   color: var(--cui-color-feedback-user-fg);
 }
+
+/* click-ui Select 弹层列表高度限制：长列表（如参数类型预设）在弹窗内不越界 */
+[data-radix-popper-content-wrapper] [role="listbox"] {
+  max-height: 45vh;
+  overflow-y: auto;
+}
+
+/* 参数构建器的添加菜单项 hover（菜单 portal 在 body，主题变量不可达） */
+.param-add-menu [role="menuitem"] {
+  background-color: transparent;
+  transition: background-color 120ms;
+}
+.param-add-menu [role="menuitem"]:hover {
+  background-color: rgba(128, 128, 128, 0.25);
+}
+
+/* 参数构建器添加菜单：菜单 portal 在 body、位于弹窗焦点陷阱之外，
+ * Radix 的 data-highlighted 不生效——补显式 hover 高亮（值同 gmi-background-hover） */
+.param-add-menu [role="menuitem"]:hover {
+  background-color: #3b3b3b;
+}
diff --git a/src/types/index.ts b/src/types/index.ts
index 33559d05..b764b392 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -9,6 +9,8 @@ export type * from './layout';
 export type * from './role';
 export type * from './scope';
 export type * from './server';
+export type * from './terravox';
 export type * from './shared';
 export type * from './theme';
+export type * from './tools';
 export type * from './user';
diff --git a/src/types/terravox.ts b/src/types/terravox.ts
new file mode 100644
index 00000000..57aa9d3c
--- /dev/null
+++ b/src/types/terravox.ts
@@ -0,0 +1,200 @@
+/**
+ * TerraVox 领域类型（manifest/服务绑定/用量/Gitea 检查等）。
+ *
+ * 从 src/server/terravox.ts 迁入（CLAUDE.md：本地接口一律入 src/types/）。
+ * 刻意用显式 interface 而非 zod 推断——值需跨 server-fn 序列化边界保持
+ * 可赋值；gateway 是校验权威（提交时按 vendored contracts schema 重校验）。
+ */
+
+/** JSON value tree — used for manifest blocks the gateway re-validates. */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/**
+ * Editing view of a Tool Manifest (contracts manifest/v1). `parameters`,
+ * `form`, `execution`, `result` and `audit` stay loose: the gateway is the
+ * validation authority — it re-checks every submit against the vendored
+ * contracts schema. Explicit interfaces (not zod inference) so the values
+ * stay assignable across the server-fn serialization boundary.
+ */
+export interface TerraVoxTool {
+  schema_version?: number;
+  tool_id: string;
+  version: string;
+  enabled?: boolean;
+  display_name: string;
+  description: string;
+  expose?: string[];
+  allowed_groups?: string[];
+  dangerous?: boolean;
+  display_group?: string;
+  /** 2.22.0 分组内显示顺序：升序，缺省沉底（再按 tool_id）。 */
+  display_order?: number;
+  help_url?: string;
+  usage_stats?: boolean;
+  parameters?: { [key: string]: JsonValue };
+  form?: { [key: string]: JsonValue };
+  execution?: { [key: string]: JsonValue };
+  result?: { [key: string]: JsonValue };
+  timeout_seconds?: number;
+  audit?: { [key: string]: JsonValue };
+}
+
+export interface TerraVoxGroup {
+  name: string;
+  display_name: string;
+  description: string;
+  sort_order: number;
+  /** 该组工具的可见组（2.17.0）；空 = 不限（全员可见）。 */
+  allowed_groups: string[];
+  tool_count: number;
+  /** false = implicit namespace derived from existing tools (no DB row). */
+  explicit: boolean;
+}
+
+export interface TerraVoxGroupMeta {
+  name: string;
+  display_name: string;
+  sort_order: number;
+}
+
+export interface ImportResult {
+  tool_id: string;
+  action: 'created' | 'updated' | 'skipped' | 'failed';
+  error?: string;
+}
+
+export interface GiteaRepoSummary {
+  name: string;
+  description?: string;
+  updated_at?: string;
+}
+
+export interface GiteaOwner {
+  login: string;
+  type?: 'user' | 'org';
+  repos: GiteaRepoSummary[];
+}
+
+export interface GiteaReposResult {
+  base_url: string;
+  owners: GiteaOwner[];
+}
+
+export interface GiteaReleaseInfo {
+  tag: string;
+  published_at?: string;
+  zip_asset?: string;
+  zip_size?: number;
+}
+
+export interface GiteaCheckItem {
+  key: string;
+  level: 'ok' | 'warn' | 'error';
+  message: string;
+}
+
+export interface GiteaCheckResult {
+  owner: string;
+  repo: string;
+  repo_description?: string;
+  release?: GiteaReleaseInfo;
+  /** repo 根 tool.json 解析结果（缺失时 undefined） */
+  tool_json?: { [key: string]: JsonValue };
+  checks: GiteaCheckItem[];
+  installable: boolean;
+}
+
+export interface PendingPackageMeta {
+  version: string;
+  size: number;
+  updated_at: string;
+}
+
+/** 仓库最新稳定 Release 领先于 manifest 已批准版本的 desktop 工具。 */
+export interface PendingToolUpdate {
+  tool_id: string;
+  display_name: string;
+  owner?: string;
+  repo?: string;
+  current_version: string;
+  package: PendingPackageMeta;
+}
+
+/** One direct-run usage row recorded by the toolbox (gateway `run_reports`). */
+export interface RunReport {
+  id: string;
+  user_sub: string;
+  /** 工具显示名（2.19.0）；空 = 未记录，展示回退 tool_id。 */
+  tool_name?: string | null;
+  username: string | null;
+  /** 用户显示名（OIDC name claim，如中文名）；空 = 未提供，展示回退 username。 */
+  user_name?: string | null;
+  tool_id: string;
+  version: string | null;
+  status: 'succeeded' | 'failed' | 'stopped' | 'timeout';
+  duration_ms: number | null;
+  /** Argument key names only — values are never recorded (privacy by contract). */
+  argument_keys: string[];
+  source: string;
+  created_at: string;
+}
+
+export interface RunReportFilters {
+  tool_id?: string;
+  user_sub?: string;
+  /** Inclusive ISO bounds built from local-day pickers. */
+  since?: string;
+  until?: string;
+}
+
+/** 一个绑定 = 一幅地图（iserver_map）或一个数据源（iserver_data）。 */
+export interface TerraVoxService {
+  id: string;
+  name: string;
+  type: 'iserver_map' | 'iserver_data';
+  base_url: string;
+  service_path: string;
+  datasource: string;
+  allowed_groups: string[];
+  map_name: string;
+  enabled: boolean;
+  status: 'available' | 'unavailable' | 'unprobed';
+  probe_detail: string;
+  probed_at: string | null;
+}
+
+export interface TerraVoxServiceInput {
+  name: string;
+  type: string;
+  base_url: string;
+  service_path: string;
+  datasource: string;
+  allowed_groups: string[];
+  enabled: boolean;
+}
+
+/** 底图组（2.19.0）：按叠放序的多幅底图，整组读写。 */
+export interface BasemapItem {
+  id?: string;
+  base_url: string;
+  service_path: string;
+  map_name: string;
+  url?: string;
+}
+
+/** 自动发现候选服务（2.18.0）：iServer 基地址 → REST 地图/数据服务清单。 */
+export interface DiscoveredService {
+  name: string;
+  type: 'iserver_map' | 'iserver_data' | 'unknown';
+  service_path: string;
+  status: 'available' | 'unavailable';
+  detail: string;
+  maps: string[];
+  datasources: string[];
+}
diff --git a/src/types/tools.ts b/src/types/tools.ts
new file mode 100644
index 00000000..73338470
--- /dev/null
+++ b/src/types/tools.ts
@@ -0,0 +1,53 @@
+import type { TerraVoxGroup, TerraVoxTool } from '@/server/terravox';
+
+export type ToolsTab = 'catalog' | 'groups' | 'usage';
+
+export interface ToolsPageProps {
+  activeTab: ToolsTab;
+  onTabChange: (tab: string) => void;
+}
+
+export interface ToolEditDialogProps {
+  open: boolean;
+  tool: TerraVoxTool | null;
+  /** Gitea 导入预填：以创建模式打开但预填仓库解析出的字段（tool 仍为 null）。 */
+  prefill?: TerraVoxTool | null;
+  groups: TerraVoxGroup[];
+  /** 现有展示分组值聚合（datalist 点选；也可输入新组）。 */
+  displayGroupOptions: string[];
+  handlers: string[];
+  saving: boolean;
+  error?: ToolEditError;
+  onSubmit: (manifest: Record<string, unknown>) => void;
+  onClose: () => void;
+}
+
+export interface ToolEditError {
+  message?: string;
+  errors?: { path?: string; message: string }[];
+}
+
+export interface GiteaImportDialogProps {
+  open: boolean;
+  onClose: () => void;
+  /** 面板内「手动创建」：跳过 Gitea，直接打开空白编辑对话框。 */
+  onManualCreate: () => void;
+  /** 检查通过（无 error 级问题）后携带仓库解析出的预填数据继续编辑。 */
+  onContinue: (prefill: TerraVoxTool) => void;
+}
+
+export interface ToolGroupEditDialogProps {
+  open: boolean;
+  /** null = create; an implicit group carries metadata-only edit semantics. */
+  group: TerraVoxGroup | null;
+  saving: boolean;
+  error?: string;
+  onSubmit: (input: {
+    name?: string;
+    display_name: string;
+    description: string;
+    sort_order: number;
+    allowed_groups: string[];
+  }) => void;
+  onClose: () => void;
+}