diff --git a/ui/src/api/API_README.md b/ui/src/api/API_README.md
index 5cf1da13489..89463c42df9 100644
--- a/ui/src/api/API_README.md
+++ b/ui/src/api/API_README.md
@@ -672,7 +672,8 @@ Workspace、System 资源管理及 System 共享资源的 `knowledge.ts` 提供
 
 `workspace/knowledge/tags.ts` 维护标签查询、创建、编辑和删除，前缀为
 `/workspace/<workspaceId>/knowledge/<knowledgeId>/tags`，工作空间由 `getWorkspaceId()` 读取。
-`getKnowledgeTags(knowledgeId)` 返回非分页 `KnowledgeTagGroup[]`；
+`getKnowledgeTags(knowledgeId, query?)` 返回非分页 `KnowledgeTagGroup[]`；
+可选 `query.name` 用于标签管理列表搜索，不传时仍查询全部标签供下拉候选使用。
 标签值中的可选 `doc_count` 表示关联文档数量。`postKnowledgeTags` 直接提交
 `KnowledgeTagPayload[]`（`key`、`value`），用于创建标签和新增标签值；
 `putKnowledgeTag` 向 `/<tagId>` 提交完整 `KnowledgeTagUpdatePayload`（`id`、`key`、`value`），
@@ -689,7 +690,7 @@ Workspace、System 资源管理及 System 共享资源的 `knowledge.ts` 提供
 不声明多行编辑接口，也不组合旧接口模拟多行保存。
 
 文档与标签的关联由 `workspace/knowledge/document.ts` 维护，不使用标签删除接口代替取消关联。
-`getDocumentTags` 查询 `document/<documentId>/tags`，返回分组标签；
+`getDocumentTags(knowledgeId, documentId, query?)` 查询 `document/<documentId>/tags`，返回分组标签，支持 `query.name` 搜索；
 `postAddDocumentTags` POST 到 `document/batch_add_tag`，提交 `{ document_ids, tag_ids }`；
 `putDeleteDocumentTags` PUT 到 `document/<documentId>/tags/batch_delete`，直接提交标签 ID 数组。
 `putUnlinkTagDocuments` PUT 到知识库下的 `tag/<tagId>/docs_delete`，提交 `{ id_list: documentIds }`，
diff --git a/ui/src/api/admin/workspace/knowledge/document.ts b/ui/src/api/admin/workspace/knowledge/document.ts
index a54d4178b8a..92b26d53ff9 100644
--- a/ui/src/api/admin/workspace/knowledge/document.ts
+++ b/ui/src/api/admin/workspace/knowledge/document.ts
@@ -166,7 +166,8 @@ const postReplaceDocumentSource = (knowledgeId: string, documentId: string, file
 }
 
 /** 查询文档当前标签。 */
-const getDocumentTags = (knowledgeId: string, documentId: string) => get<KnowledgeTagGroup[]>(`${getPrefix(knowledgeId)}/${documentId}/tags`)
+const getDocumentTags = (knowledgeId: string, documentId: string, query?: Dict<unknown>) =>
+  get<KnowledgeTagGroup[]>(`${getPrefix(knowledgeId)}/${documentId}/tags`, query)
 
 /** 给指定文档批量添加已有标签。 */
 const postAddDocumentTags = (knowledgeId: string, documentIds: string[], tagIds: string[]) =>
diff --git a/ui/src/api/admin/workspace/knowledge/tags.ts b/ui/src/api/admin/workspace/knowledge/tags.ts
index 23a0694cf61..6a19ed29c24 100644
--- a/ui/src/api/admin/workspace/knowledge/tags.ts
+++ b/ui/src/api/admin/workspace/knowledge/tags.ts
@@ -1,11 +1,11 @@
 import { del, get, getExportFile, post, put } from '../../core/request'
-import type { KnowledgeTagGroup, KnowledgeTagPayload, KnowledgeTagUpdatePayload } from '@/api/types'
+import type { Dict, KnowledgeTagGroup, KnowledgeTagPayload, KnowledgeTagUpdatePayload } from '@/api/types'
 import { getWorkspaceId } from '@/utils/resource-context'
 
 const getPrefix = (knowledgeId: string) => `/workspace/${getWorkspaceId()}/knowledge/${knowledgeId}/tags`
 
 /** 获取知识库按标签名称分组的标签选项。 */
-const getKnowledgeTags = (knowledgeId: string) => get<KnowledgeTagGroup[]>(getPrefix(knowledgeId))
+const getKnowledgeTags = (knowledgeId: string, query?: Dict<unknown>) => get<KnowledgeTagGroup[]>(getPrefix(knowledgeId), query)
 
 /** 创建知识库标签或为已有标签新增值。 */
 const postKnowledgeTags = (knowledgeId: string, tags: KnowledgeTagPayload[]) => post<KnowledgeTagPayload[], void>(getPrefix(knowledgeId), tags)
diff --git a/ui/src/views/VIEW_README.md b/ui/src/views/VIEW_README.md
index ace2e3e3ae7..76cc61794d4 100644
--- a/ui/src/views/VIEW_README.md
+++ b/ui/src/views/VIEW_README.md
@@ -799,7 +799,7 @@ Web 来源地址与选择器仅在单项设置中编辑，批量设置不展示
 文档任务是否排队或执行中通过其中的 `isDocumentTaskRunning(document, taskType)` 判断，
 页面及 Action 不重复解析状态字符串；文档或任务状态缺失时返回 `false`。
 `EmbeddingDocumentAction` 负责单项向量化与取消向量化，`BatchEmbeddingAction` 负责批量向量化按钮，`GenerateQuestionsAction` 负责单项生成问题与取消生成，`BatchGenerateQuestionsAction` 负责批量生成问题，`SettingDocumentAction` 负责召回及来源设置，
-`MigrateDocumentAction` 选择目标知识库；`setting-tags/DocumentTagsAction.vue` 暂仅提供“标签设置”入口按钮。
+`MigrateDocumentAction` 选择目标知识库；`setting-tags/DocumentTagsAction.vue` 内部管理标签设置抽屉的挂载、打开和关闭。
 生成问题复用公共配置弹窗，其余 Action 按下文维护各自专属弹窗。组件接收完整 Document API、知识库 ID、文档 ID 或文档数组及禁用状态，
 点击时快照本次操作对象，内部管理弹窗和请求，成功后通过 `refresh` 通知页面刷新，失败保留输入。
 迁移操作集中在 `document/action-dropdown/migrate/`，`MigrateDocumentAction.vue` 负责入口与弹窗按需挂载，
@@ -827,7 +827,28 @@ Action 仍通过上层 `action-dropdown/index.ts` 导出，弹窗仅在目录内
 弹窗通过 `batch` 参数区分批量模式，批量入口显式传入；文档地址和选择器仅在 `!batch` 且为 Web 知识库时显示。
 单项保留文档原有 `meta`，批量使用默认配置并将 `allow_download`
 放在顶层。请求与成功关闭由 Action 负责，成功通知页面刷新，失败保留表单。
-标签组件通过 `manageTags` 区分标签管理与批量添加。
+标签操作集中在 `document/action-dropdown/setting-tags/`。`DocumentTagsDrawer.vue` 管理单篇文档的标签关联，
+由 `DocumentTagsAction` 按需挂载、关闭后卸载；仅提供添加、搜索、单值删除及批量删除，不提供编辑和分页。
+抽屉每次打开都查询最新关联；增删后立即刷新自身列表，Action 记录成功变更，关闭后再通过 `refresh` 通知文档页刷新。
+查询使用 `DocumentApi.getDocumentTags`，搜索使用单一 `MkSearchInput`，通过 `change` 将关键词作为 `name` 请求接口，清空时省略该参数；
+查询前清除勾选，直接展示接口返回的分组，不再本地过滤。选择列和标签名单元格合并；
+通过 `MkTable selection-group-key="key"` 联动组内标签值，已选数量按标签值行数统计；标签值列复用 `border-l!` 展示与合并标签列之间的分隔线。
+删除调用 `putDeleteDocumentTags`，仅移除当前文档关联，不调用知识库标签删除接口。
+`AddTagDialog.vue` 为标签列、抽屉与批量操作栏共用的下拉式添加弹窗，接收完整 Document API 和知识库 ID。
+三个入口分别由 `DocumentTags`、`DocumentTagsDrawer`、`BatchDocumentTagsAction` 管理弹窗实例，不通过页面 Ref 打开。
+候选项使用 `tagsApi.getKnowledgeTags`，按返回顺序截取前 100 个标签组，然后由 `el-select filterable` 本地搜索；
+右侧显示所选组的全部标签值，切换标签名清空本行标签值，不增加远程搜索或自动扩展候选范围。
+单篇与批量均允许选择已关联标签值和重复选择，不为禁选查询文档已有标签，也不区分 `batch` 模式。
+表单复用 `MkFormList`，至少一行，保留必填与标签值归属校验；通过 `postAddDocumentTags` 提交所选 ID，由后台去重并追加关联。
+下拉 footer 复用模型选择器的创建入口，先收起下拉，再打开输入式 `tags/components/CreateTagDialog.vue`；
+标签名入口调用 `open()`；标签值下拉始终可展开，未选标签时点击“创建标签值”也调用 `open()` 创建标签，
+已选标签时调用 `open(key)` 新增标签值，不合并两类弹窗的模式。
+弹窗每次打开都查询候选；内部创建成功后重载前 100 组候选，保留当前选择，不自动选中新数据。
+`BatchDocumentTagsAction.vue` 使用普通按钮外放在底部批量操作栏，内部按需挂载 `AddTagDialog`，打开时固定知识库和文档 ID，
+即使只勾选一篇，也按批量添加处理。添加成功关闭动画结束后通知刷新，再卸载弹窗。
+三个外层标签入口只通过 `refresh` 通知页面刷新，沿用文档列表原有轮询，不为标签浮层单独暂停。
+页面不持有标签浮层 Ref 或控制其挂载。标签入口与打开方法只限制 Workspace 共享只读范围，
+Workspace 普通资源、System 资源管理和 System 共享资源允许打开；System library 的文档与标签 API 仍待按范围接入，不能将入口可用视为接口已支持。
 分词索引集中在 `document/action-dropdown/tokenize/`：`TokenizeDocumentAction` 接收单个 `document`，
 按运行状态调用单项分词或取消接口；`BatchTokenizeAction` 接收 `documentIds`，仅调用批量分词接口。
 两个 Action 均处理全部分段状态，通过 `v-model:loading` 共用页面操作状态，成功后通知页面刷新。
@@ -856,11 +877,11 @@ Action 仍通过上层 `action-dropdown/index.ts` 导出，弹窗仅在目录内
 启停开关直接使用页面内的 `el-switch`，由页面 `handleChangeActive` 管理请求，
 接口成功后刷新列表回显，不在请求前切换状态，不单独封装 Action。
 页面保留列表、多选、任务状态展示判断与刷新方法，不维护各 Action 的请求流程。
-`DocumentStatus`、`DocumentTags` 等纯展示组件继续留在 `document/components/`。
-页面不再维护这些弹窗 Ref 和打开方法。行内更多菜单使用 `MkTableMoreDropdown`；批量操作栏使用
+`DocumentStatus` 和标签列组件 `DocumentTags` 继续留在 `document/components/`，后者同时管理本入口的添加弹窗。
+弹窗 Ref 和打开方法由对应 Action 或标签列入口组件维护，页面只传参、处理刷新。行内更多菜单使用 `MkTableMoreDropdown`；批量操作栏使用
 `MkDropdown` 搭配非 text 的 More 图标按钮和 `MkDropdownMenu`，点击展开。
 批量 More 开启 `hide-when-empty`，按标准菜单插槽判断空内容，不强制开启 `persistent`；不检查业务 Action 内部的条件渲染。
-不新增前端权限判断；共享文档不展示选择列及操作入口。
+不新增前端权限判断；Workspace 共享文档不展示选择列、操作列及批量操作，标签列保留禁用的添加按钮。
 文档分页接口维护在 `workspace/knowledge/document.ts`，页面管理 loading。文件状态表头使用
 `MkDropdown` 单选筛选全部、成功、失败、索引中、分词索引中、排队中和生成中；查询组合
 `status` 与可选的 `task_type`，切换选项清除旧任务类型并回到第一页，保留名称和创建者条件。
@@ -931,8 +952,9 @@ library 的接口调整已撤回，文档和标签沿用原有调用方式，Sys
 
 `knowledge-detail/library/tags/index.vue` 复用详情布局的 `customHeader` 与 Teleport，
 维护搜索、导入入口、创建入口和标签表格，不嵌套页面布局或修改路由。
-通过 `workspace/knowledge/knowledge.ts` 查询全量分组，前端按标签名或值搜索并保留完整命中分组；
-先按标签组分页，再展开各组标签值，分页总数为标签组数。
+通过 `workspace/knowledge/knowledge.ts` 查询分组，使用单一 `MkSearchInput`，通过 `change` 将关键词作为 `name` 请求接口；
+清空时省略该参数，搜索后回到第一页并清除勾选，不在前端过滤匹配结果。
+对接口返回结果先按标签组分页，再展开各组标签值，分页总数为返回的标签组数。
 `MkTable` 合并选择列和标签名，通过 `selection-group-key="key"` 联动当前页同组标签值；
 批量底栏按实际选中标签值行数／当前页标签值总行数统计，不按标签组计数。
 删除提交全部选中标签值 ID，确认框同时说明标签值数量、标签组数量及整组删除的影响。
@@ -969,7 +991,7 @@ library 的接口调整已撤回，文档和标签沿用原有调用方式，Sys
 文档图标和时间格式沿用文档列表，状态使用 `MkStatusLabel`；批量操作放在顶部，不再显示页面批量底栏。
 搜索、分页和页签切换清空选择，关联变更后重新查询并通知标签页刷新数量，末页为空时回退。
 抽屉在 `closed` 重置标签、筛选、分页和选择，不新增权限判断或共享范围接口。
-文档页原有标签查询继续使用 Knowledge API，共享标签查询保持原接口，不启用尚未接入的文档标签入口。
+文档页标签候选查询继续使用 Knowledge API，共享标签查询保持原接口；普通文档标签入口使用上述独立添加弹窗与抽屉。
 
 `KnowledgeWorkflowView` 复用 `ButtonDefaultModelSetting`，从知识库详情读取默认模型配置，
 随工作流保存提交并将配置传入画布；支持应用到所有节点，保存失败回滚至已保存配置。
@@ -1263,16 +1285,17 @@ Web 地址按行去空白、去重并校验 HTTP/HTTPS；空选择器提交 `bod
 `MkTableFilter mode="single"`，标签使用 `mode="cascader"`。文件状态按 v2 提供成功、失败、
 索引中、分词索引中、排队中、生成中，同时映射 `status` 与可选 `task_type`；切换到非任务状态
 或全部时清除任务类型。启用状态保留布尔 `false`，召回处理复用 `DOCUMENT_HIT_HANDLING_LABELS`。
-标签首次打开时按普通／共享范围查询知识库标签，成功后通过非空选项复用缓存（始终包含“无标签”），
-不额外维护 loaded 标记；普通布尔请求锁防止重复请求，失败释放后下次打开可重试。
+表头标签筛选每次展开时按普通／共享范围重新查询知识库标签，不因已有选项而跳过请求；
+普通布尔请求锁防止重复请求，失败释放后下次打开可重试。
 标签级联沿用 MkTableFilter 默认的父子独立选择和隐藏复选框外观；组件内部保留原始勾选，
 对外将父组转换为叶子值并去重。页面直接将回写的叶子标签 ID 数组用于查询，
 “无标签”使用 `NO_TAG`；页面不维护父组展开或去重逻辑。
 任一筛选确认或重置后回到第一页查询，保留其他筛选和名称／创建者搜索条件。
-标签列使用页面专属 `components/DocumentTags.vue`，接收 `document`，展示标签数量，
+标签列使用页面专属 `components/DocumentTags.vue`，接收 `document`、知识库 ID 和完整 Document API，展示标签数量，
 悬浮时显示标签名与值，长文本省略并保留 title。数量优先读取 `tag_count`，缺省时使用标签数组长度，
-无标签时仅显示添加入口。添加按钮阻止点击冒泡，通过 `add(documentId)` 通知调用方；
-当前文档页尚未接入添加弹窗与保存接口，不新增权限判断。
+添加按钮始终显示，通过 `disabled` 接收页面的 Workspace 共享只读状态，通过 `v-model:loading` 共用操作状态，不隐藏加号和“标签”文案；已有标签的悬浮查看不受影响。
+添加按钮阻止点击冒泡，组件内部按需挂载并打开 `AddTagDialog`；打开方法同时检查只读、操作中和重复打开状态。
+添加成功关闭弹窗后通过 `refresh` 通知页面刷新文档列表与数量；不新增权限判断。
 
 文件状态的解析、聚合与展示统一放在文档页的 `components/DocumentStatus.vue`。组件接收 `status`、`statusMeta`，按从右起的任务位置解析向量化、生成问题、
 同步、分词索引；聚合优先级为取消中、执行中、排队中、失败、取消完成、成功，
diff --git a/ui/src/views/knowledge-detail/library/document/action-dropdown/embedding/BatchEmbeddingAction.vue b/ui/src/views/knowledge-detail/library/document/action-dropdown/embedding/BatchEmbeddingAction.vue
index 5f6e5693017..361dd448c4c 100644
--- a/ui/src/views/knowledge-detail/library/document/action-dropdown/embedding/BatchEmbeddingAction.vue
+++ b/ui/src/views/knowledge-detail/library/document/action-dropdown/embedding/BatchEmbeddingAction.vue
@@ -38,6 +38,6 @@ function handleSubmit(stateList: DocumentTaskState[]) {
 
 <template>
   <!-- 批量向量化 -->
-  <el-button plain :disabled="loading" @click="handleOpen">向量化</el-button>
+  <el-button plain type="primary" :disabled="loading" @click="handleOpen">向量化</el-button>
   <DocumentEmbeddingDialog v-model="visible" :loading="loading" @submit="handleSubmit" />
 </template>
diff --git a/ui/src/views/knowledge-detail/library/document/action-dropdown/generate-questions/BatchGenerateQuestionsAction.vue b/ui/src/views/knowledge-detail/library/document/action-dropdown/generate-questions/BatchGenerateQuestionsAction.vue
index 3f1c29bb842..4b3c1378f32 100644
--- a/ui/src/views/knowledge-detail/library/document/action-dropdown/generate-questions/BatchGenerateQuestionsAction.vue
+++ b/ui/src/views/knowledge-detail/library/document/action-dropdown/generate-questions/BatchGenerateQuestionsAction.vue
@@ -59,6 +59,6 @@ function handleClosed() {
 
 <template>
   <!-- 批量生成问题 -->
-  <el-button plain :disabled="disabled || loading" @click="handleOpenDialog">生成问题</el-button>
+  <el-button plain type="primary" :disabled="disabled || loading" @click="handleOpenDialog">生成问题</el-button>
   <GenerateQuestionsDialog v-if="dialogMounted" ref="dialogRef" :loading="loading" @submit="handleSubmit" @closed="handleClosed" />
 </template>
diff --git a/ui/src/views/knowledge-detail/library/document/action-dropdown/index.ts b/ui/src/views/knowledge-detail/library/document/action-dropdown/index.ts
index 49e2ab1e31d..20cfbd5eccf 100644
--- a/ui/src/views/knowledge-detail/library/document/action-dropdown/index.ts
+++ b/ui/src/views/knowledge-detail/library/document/action-dropdown/index.ts
@@ -2,6 +2,7 @@ export { default as BatchEmbeddingAction } from './embedding/BatchEmbeddingActio
 export { default as BatchCancelTaskAction } from './BatchCancelTaskAction.vue'
 export { default as DeleteDocumentAction } from './DeleteDocumentAction.vue'
 export { default as DocumentTagsAction } from './setting-tags/DocumentTagsAction.vue'
+export { default as BatchDocumentTagsAction } from './setting-tags/BatchDocumentTagsAction.vue'
 export { default as EmbeddingDocumentAction } from './embedding/EmbeddingDocumentAction.vue'
 export { default as GenerateQuestionsAction } from './generate-questions/GenerateQuestionsAction.vue'
 export { default as BatchGenerateQuestionsAction } from './generate-questions/BatchGenerateQuestionsAction.vue'
diff --git a/ui/src/views/knowledge-detail/library/document/action-dropdown/setting-tags/AddTagDialog.vue b/ui/src/views/knowledge-detail/library/document/action-dropdown/setting-tags/AddTagDialog.vue
new file mode 100644
index 00000000000..0e90c437698
--- /dev/null
+++ b/ui/src/views/knowledge-detail/library/document/action-dropdown/setting-tags/AddTagDialog.vue
@@ -0,0 +1,209 @@
+<script setup lang="ts">
+import { computed, nextTick, reactive, ref, type ComponentPublicInstance } from 'vue'
+import type { FormInstance, FormItemRule, SelectInstance } from 'element-plus'
+import type DocumentApi from '@/api/admin/workspace/knowledge/document'
+import tagsApi from '@/api/admin/workspace/knowledge/tags'
+import type { KnowledgeTagGroup } from '@/api/types'
+import { MsgSuccess } from '@/utils/message'
+import CreateTagDialog from '../../../tags/components/CreateTagDialog.vue'
+
+defineOptions({ name: 'AddTagDialog' })
+const props = defineProps<{
+  knowledgeId: string
+  api: typeof DocumentApi
+}>()
+const loading = defineModel<boolean>('loading', { default: false })
+const emit = defineEmits<{ refresh: []; closed: [] }>()
+
+interface TagSelection {
+  key: string
+  tagId: string
+}
+
+const visible = ref(false)
+const queryLoading = ref(false)
+const optionsReady = ref(false)
+const targetKnowledgeId = ref('')
+const targetDocumentIds = ref<string[]>([])
+const tagGroups = ref<KnowledgeTagGroup[]>([])
+const tagForm = reactive<{ tags: TagSelection[] }>({ tags: [{ key: '', tagId: '' }] })
+const formRef = ref<FormInstance>()
+const keySelectRefs: Record<number, SelectInstance | null> = {}
+const valueSelectRefs: Record<number, SelectInstance | null> = {}
+const createTagRef = ref<InstanceType<typeof CreateTagDialog>>()
+const createTagMounted = ref(false)
+const busy = computed(() => loading.value || queryLoading.value || createTagMounted.value)
+let added = false
+
+// 候选项只保留接口返回的前 100 个标签组，搜索交给 el-select 的 filterable。
+function loadTagOptions() {
+  return tagsApi.getKnowledgeTags(targetKnowledgeId.value).then((groups) => {
+    tagGroups.value = groups.slice(0, 100)
+  })
+}
+
+function open(documentIds: string[]) {
+  if (visible.value || busy.value || !documentIds.length) return
+  targetKnowledgeId.value = props.knowledgeId
+  targetDocumentIds.value = [...documentIds]
+  visible.value = true
+  queryLoading.value = true
+  return loadTagOptions()
+    .then(() => {
+      optionsReady.value = true
+    })
+    .finally(() => {
+      queryLoading.value = false
+    })
+}
+
+function getTagValues(key: string) {
+  return tagGroups.value.find((group) => group.key === key)?.values ?? []
+}
+
+function handleTagKeyChange(index: number) {
+  tagForm.tags[index]!.tagId = ''
+  formRef.value?.clearValidate([`tags.${index}.key`, `tags.${index}.tagId`])
+}
+
+function handleRowsChange() {
+  formRef.value?.clearValidate()
+}
+
+function getTagValueRules(index: number): FormItemRule[] {
+  return [
+    { required: true, message: '请选择标签值', trigger: 'change' },
+    {
+      validator: (_rule, value: string, callback) => {
+        const tag = tagForm.tags[index]
+        if (value && (!tag || !getTagValues(tag.key).some(({ id }) => id === value))) {
+          return callback(new Error('请重新选择标签值'))
+        }
+        callback()
+      },
+      trigger: 'change',
+    },
+  ]
+}
+
+function handleOpenCreateTag(index: number, field: 'key' | 'value') {
+  if (busy.value || !optionsReady.value) return
+  const key = tagForm.tags[index]?.key
+  const selectRefs = field === 'key' ? keySelectRefs : valueSelectRefs
+  selectRefs[index]?.blur()
+  createTagMounted.value = true
+  return nextTick(() => createTagRef.value?.open(field === 'value' && key ? key : undefined))
+}
+
+function handleTagsCreated() {
+  // 创建成功后刷新当前弹窗的候选项。
+  queryLoading.value = true
+  optionsReady.value = false
+  return loadTagOptions()
+    .then(() => {
+      optionsReady.value = true
+    })
+    .finally(() => {
+      queryLoading.value = false
+    })
+}
+
+function handleSubmit() {
+  if (busy.value || !optionsReady.value) return
+  return formRef.value?.validate((valid) => {
+    if (!valid || busy.value || !tagForm.tags.length) return
+    const tagIds = tagForm.tags.map(({ tagId }) => tagId)
+    loading.value = true
+    return props.api
+      .postAddDocumentTags(targetKnowledgeId.value, targetDocumentIds.value, tagIds)
+      .then(() => {
+        MsgSuccess('添加成功')
+        added = true
+        visible.value = false
+      })
+      .finally(() => {
+        loading.value = false
+      })
+  })
+}
+
+function handleBeforeClose(done: () => void) {
+  if (!busy.value) done()
+}
+
+function handleClosed() {
+  // 等关闭动画结束再刷新，避免批量勾选清空时提前卸载弹窗。
+  if (added) emit('refresh')
+  emit('closed')
+}
+
+defineExpose({ open })
+</script>
+
+<template>
+  <MkDialog v-model="visible" title="添加标签" :before-close="handleBeforeClose" @closed="handleClosed">
+    <el-form ref="formRef" v-loading="queryLoading || loading" :model="tagForm" label-position="top" @submit.prevent>
+      <MkFormList v-model="tagForm.tags" :default-item="{ key: '', tagId: '' }" @update:model-value="handleRowsChange">
+        <template #default="{ index, item: tag }">
+          <el-form-item
+            class="min-w-0 flex-1"
+            :label="index === 0 ? '标签' : ''"
+            :prop="`tags.${index}.key`"
+            :rules="{ required: true, message: '请选择标签', trigger: 'change' }"
+          >
+            <el-select
+              :ref="(select: Element | ComponentPublicInstance | null) => (keySelectRefs[index] = select as SelectInstance | null)"
+              v-model="tag.key"
+              filterable
+              clearable
+              placeholder="请选择标签"
+              @change="handleTagKeyChange(index)"
+            >
+              <el-option v-for="group in tagGroups" :key="group.key" :label="group.key" :value="group.key" />
+              <template #footer>
+                <!-- 创建新标签 -->
+                <el-button type="primary" link :disabled="busy || !optionsReady" @click.stop="handleOpenCreateTag(index, 'key')">
+                  <MkIcon name="icon_add_outlined" />
+                  <span>创建标签</span>
+                </el-button>
+              </template>
+            </el-select>
+          </el-form-item>
+          <el-form-item class="min-w-0 flex-1" :label="index === 0 ? '标签值' : ''" :prop="`tags.${index}.tagId`" :rules="getTagValueRules(index)">
+            <el-select
+              :ref="(select: Element | ComponentPublicInstance | null) => (valueSelectRefs[index] = select as SelectInstance | null)"
+              v-model="tag.tagId"
+              filterable
+              clearable
+              placeholder="请选择标签值"
+            >
+              <el-option v-for="value in getTagValues(tag.key)" :key="value.id" :label="value.value" :value="value.id" />
+              <template #footer>
+                <!-- 已选标签时新增值，未选标签时创建标签 -->
+                <el-button type="primary" link :disabled="busy || !optionsReady" @click.stop="handleOpenCreateTag(index, 'value')">
+                  <MkIcon name="icon_add_outlined" />
+                  <span>创建标签值</span>
+                </el-button>
+              </template>
+            </el-select>
+          </el-form-item>
+        </template>
+      </MkFormList>
+    </el-form>
+    <template #footer>
+      <!-- 取消添加 -->
+      <el-button plain :disabled="busy" @click="visible = false">取消</el-button>
+      <!-- 添加所选标签到目标文档 -->
+      <el-button type="primary" :loading="loading" :disabled="queryLoading || createTagMounted || !optionsReady" @click="handleSubmit">
+        添加
+      </el-button>
+    </template>
+  </MkDialog>
+  <CreateTagDialog
+    v-if="createTagMounted"
+    ref="createTagRef"
+    :knowledge-id="targetKnowledgeId"
+    @refresh="handleTagsCreated"
+    @closed="createTagMounted = false"
+  />
+</template>
diff --git a/ui/src/views/knowledge-detail/library/document/action-dropdown/setting-tags/BatchDocumentTagsAction.vue b/ui/src/views/knowledge-detail/library/document/action-dropdown/setting-tags/BatchDocumentTagsAction.vue
new file mode 100644
index 00000000000..dfa7e929945
--- /dev/null
+++ b/ui/src/views/knowledge-detail/library/document/action-dropdown/setting-tags/BatchDocumentTagsAction.vue
@@ -0,0 +1,46 @@
+<script setup lang="ts">
+import { nextTick, ref, useTemplateRef } from 'vue'
+import type DocumentApi from '@/api/admin/workspace/knowledge/document'
+import AddTagDialog from './AddTagDialog.vue'
+
+defineOptions({ name: 'BatchDocumentTagsAction' })
+const props = defineProps<{
+  api: typeof DocumentApi
+  knowledgeId: string
+  documentIds: string[]
+  label: string
+  disabled?: boolean
+}>()
+const loading = defineModel<boolean>('loading', { default: false })
+const emit = defineEmits<{ refresh: [] }>()
+
+const dialogMounted = ref(false)
+const addTagRef = useTemplateRef<InstanceType<typeof AddTagDialog>>('addTagRef')
+const targetKnowledgeId = ref('')
+
+function handleOpenDialog() {
+  if (props.disabled || loading.value || dialogMounted.value || !props.documentIds.length) return
+  targetKnowledgeId.value = props.knowledgeId
+  const documentIds = [...props.documentIds]
+  dialogMounted.value = true
+  return nextTick(() => addTagRef.value?.open(documentIds))
+}
+
+function handleDialogClosed() {
+  dialogMounted.value = false
+}
+</script>
+
+<template>
+  <!-- 为选中文档批量添加标签 -->
+  <el-button plain type="primary" :disabled="disabled || loading" @click="handleOpenDialog">{{ label }}</el-button>
+  <AddTagDialog
+    v-if="dialogMounted"
+    ref="addTagRef"
+    v-model:loading="loading"
+    :api="api"
+    :knowledge-id="targetKnowledgeId"
+    @refresh="emit('refresh')"
+    @closed="handleDialogClosed"
+  />
+</template>
diff --git a/ui/src/views/knowledge-detail/library/document/action-dropdown/setting-tags/DocumentTagsAction.vue b/ui/src/views/knowledge-detail/library/document/action-dropdown/setting-tags/DocumentTagsAction.vue
index 7b14cb061a6..5448f1752db 100644
--- a/ui/src/views/knowledge-detail/library/document/action-dropdown/setting-tags/DocumentTagsAction.vue
+++ b/ui/src/views/knowledge-detail/library/document/action-dropdown/setting-tags/DocumentTagsAction.vue
@@ -1,9 +1,58 @@
 <script setup lang="ts">
+import { nextTick, ref, useTemplateRef } from 'vue'
+import type DocumentApi from '@/api/admin/workspace/knowledge/document'
+import type { DocumentItem } from '@/api/types'
+import DocumentTagsDrawer from './DocumentTagsDrawer.vue'
+
 defineOptions({ name: 'DocumentTagsAction' })
-defineProps<{ label: string; icon?: string; disabled?: boolean }>()
+const props = defineProps<{
+  api: typeof DocumentApi
+  knowledgeId: string
+  document: DocumentItem
+  label: string
+  icon?: string
+  disabled?: boolean
+}>()
+const loading = defineModel<boolean>('loading', { default: false })
+const emit = defineEmits<{ refresh: [] }>()
+
+const drawerMounted = ref(false)
+const documentTagsRef = useTemplateRef<InstanceType<typeof DocumentTagsDrawer>>('documentTagsRef')
+const targetKnowledgeId = ref('')
+let tagsChanged = false
+
+function handleOpenDrawer() {
+  if (props.disabled || loading.value || drawerMounted.value) return
+  targetKnowledgeId.value = props.knowledgeId
+  const documentId = props.document.id
+  drawerMounted.value = true
+  return nextTick(() => documentTagsRef.value?.open(documentId))
+}
+
+function handleTagsChanged() {
+  // 抽屉内立即刷新，关闭后再统一刷新文档列表。
+  tagsChanged = true
+}
+
+function handleDrawerClosed() {
+  drawerMounted.value = false
+  if (tagsChanged) {
+    tagsChanged = false
+    emit('refresh')
+  }
+}
 </script>
 
 <template>
   <!-- 文档标签设置入口 -->
-  <MkAction :label="label" :icon="icon" :disabled="disabled" />
+  <MkAction :label="label" :icon="icon" :disabled="disabled || loading" @click="handleOpenDrawer" />
+  <DocumentTagsDrawer
+    v-if="drawerMounted"
+    ref="documentTagsRef"
+    v-model:loading="loading"
+    :api="api"
+    :knowledge-id="targetKnowledgeId"
+    @refresh="handleTagsChanged"
+    @closed="handleDrawerClosed"
+  />
 </template>
diff --git a/ui/src/views/knowledge-detail/library/document/action-dropdown/setting-tags/DocumentTagsDrawer.vue b/ui/src/views/knowledge-detail/library/document/action-dropdown/setting-tags/DocumentTagsDrawer.vue
new file mode 100644
index 00000000000..80997c7372f
--- /dev/null
+++ b/ui/src/views/knowledge-detail/library/document/action-dropdown/setting-tags/DocumentTagsDrawer.vue
@@ -0,0 +1,169 @@
+<script setup lang="ts">
+import { computed, nextTick, ref } from 'vue'
+import type { TableColumnCtx } from 'element-plus'
+import type DocumentApi from '@/api/admin/workspace/knowledge/document'
+import type { KnowledgeTagGroup } from '@/api/types'
+import { MsgConfirm, MsgSuccess } from '@/utils/message'
+import AddTagDialog from './AddTagDialog.vue'
+
+defineOptions({ name: 'DocumentTagsDrawer' })
+const props = defineProps<{
+  knowledgeId: string
+  api: typeof DocumentApi
+}>()
+const operationLoading = defineModel<boolean>('loading', { default: false })
+const emit = defineEmits<{ refresh: []; closed: [] }>()
+
+interface DocumentTagRow {
+  id: string
+  key: string
+  value: string
+  rowspan: number
+}
+
+const visible = ref(false)
+const loading = ref(false)
+const targetKnowledgeId = ref('')
+const targetDocumentId = ref('')
+const tagGroups = ref<KnowledgeTagGroup[]>([])
+const searchText = ref('')
+const selectedTags = ref<DocumentTagRow[]>([])
+const tagTableRef = ref<{ clearSelection: () => void }>()
+const addTagRef = ref<InstanceType<typeof AddTagDialog>>()
+const addTagMounted = ref(false)
+const confirming = ref(false)
+
+// 按接口返回的分组展开，勾选与删除始终按标签值 ID 处理。
+const tagRows = computed<DocumentTagRow[]>(() =>
+  tagGroups.value.flatMap((group) => group.values.map((tag, index) => ({ ...tag, key: group.key, rowspan: index === 0 ? group.values.length : 0 }))),
+)
+
+function clearSelection() {
+  tagTableRef.value?.clearSelection()
+  selectedTags.value = []
+}
+
+function loadTags() {
+  clearSelection()
+  loading.value = true
+  return props.api
+    .getDocumentTags(targetKnowledgeId.value, targetDocumentId.value, { name: searchText.value.trim() || undefined })
+    .then((groups) => {
+      tagGroups.value = groups
+    })
+    .catch(() => {
+      // 查询失败时清除旧数据，避免继续操作已失效的关联。
+      tagGroups.value = []
+    })
+    .finally(() => {
+      loading.value = false
+    })
+}
+
+function open(documentId: string) {
+  if (visible.value || operationLoading.value) return
+  targetKnowledgeId.value = props.knowledgeId
+  targetDocumentId.value = documentId
+  visible.value = true
+  return loadTags()
+}
+
+function handleSelectionChange(selection: unknown[]) {
+  selectedTags.value = selection as DocumentTagRow[]
+}
+
+function spanMethod({ column, row }: { column: TableColumnCtx<DocumentTagRow>; row: DocumentTagRow }) {
+  if (column.type === 'selection' || column.property === 'key') return row.rowspan ? [row.rowspan, 1] : [0, 0]
+}
+
+function handleOpenAddTag() {
+  if (loading.value || operationLoading.value || addTagMounted.value) return
+  addTagMounted.value = true
+  return nextTick(() => addTagRef.value?.open([targetDocumentId.value]))
+}
+
+function handleTagsChanged() {
+  emit('refresh')
+  return loadTags()
+}
+
+function handleDeleteTags(tags: DocumentTagRow[]) {
+  if (loading.value || operationLoading.value || confirming.value || !tags.length) return
+  const tagIds = tags.map(({ id }) => id)
+  const title = tags.length === 1 ? `是否移除标签：${tags[0]!.key}—${tags[0]!.value}？` : `是否移除选中的 ${tagIds.length} 个标签值？`
+  confirming.value = true
+  return MsgConfirm(title, '仅移除当前文档与所选标签值的关联，不删除知识库标签，也不影响其他文档。')
+    .then(
+      () => {
+        operationLoading.value = true
+        return props.api
+          .putDeleteDocumentTags(targetKnowledgeId.value, targetDocumentId.value, tagIds)
+          .then(() => {
+            MsgSuccess('移除成功')
+            return handleTagsChanged()
+          })
+          .finally(() => {
+            operationLoading.value = false
+          })
+      },
+      () => {},
+    )
+    .finally(() => {
+      confirming.value = false
+    })
+}
+
+function handleBeforeClose(done: () => void) {
+  if (!loading.value && !operationLoading.value && !addTagMounted.value && !confirming.value) done()
+}
+
+defineExpose({ open })
+</script>
+
+<template>
+  <MkDrawer v-model="visible" title="标签设置" content-class="h-full flex-column gap-4" :before-close="handleBeforeClose" @closed="emit('closed')">
+    <div class="flex-between gap-4">
+      <!-- 为当前文档添加标签 -->
+      <el-button type="primary" :disabled="loading || operationLoading" @click="handleOpenAddTag">
+        <MkIcon name="icon_add_outlined" />
+        <span>添加标签</span>
+      </el-button>
+      <MkSearchInput v-model="searchText" class="w-60!" @change="loadTags" />
+    </div>
+    <MkTable
+      ref="tagTableRef"
+      v-loading="loading || operationLoading"
+      :data="tagRows"
+      selection-group-key="key"
+      :span-method="spanMethod"
+      @selection-change="handleSelectionChange"
+    >
+      <el-table-column type="selection" width="40" />
+      <el-table-column prop="key" label="标签" min-width="160" show-overflow-tooltip />
+      <el-table-column prop="value" label="标签值" min-width="160" class-name="border-l!" show-overflow-tooltip />
+      <el-table-column label="操作" width="64">
+        <template #default="{ row }: { row: DocumentTagRow }">
+          <!-- 移除当前文档的标签关联 -->
+          <MkTooltip content="删除" placement="top">
+            <el-button type="primary" text :disabled="loading || operationLoading" @click="handleDeleteTags([row])">
+              <MkIcon name="icon_delete-trash_outlined" />
+            </el-button>
+          </MkTooltip>
+        </template>
+      </el-table-column>
+      <template #footer-batch-actions>
+        <!-- 批量移除当前文档的标签关联 -->
+        <el-button plain type="danger" :disabled="loading || operationLoading" @click="handleDeleteTags(selectedTags)">删除</el-button>
+      </template>
+    </MkTable>
+  </MkDrawer>
+  <AddTagDialog
+    v-if="addTagMounted"
+    ref="addTagRef"
+    v-model:loading="operationLoading"
+    :api="api"
+    :knowledge-id="targetKnowledgeId"
+    @refresh="handleTagsChanged"
+    @closed="addTagMounted = false"
+  />
+</template>
diff --git a/ui/src/views/knowledge-detail/library/document/action-dropdown/setting/BatchSettingDocumentAction.vue b/ui/src/views/knowledge-detail/library/document/action-dropdown/setting/BatchSettingDocumentAction.vue
index 72ea2ab2bec..4e8dd45bcba 100644
--- a/ui/src/views/knowledge-detail/library/document/action-dropdown/setting/BatchSettingDocumentAction.vue
+++ b/ui/src/views/knowledge-detail/library/document/action-dropdown/setting/BatchSettingDocumentAction.vue
@@ -50,6 +50,6 @@ function handleDialogClosed() {
 
 <template>
   <!-- 批量文档设置 -->
-  <el-button plain :disabled="disabled || loading" @click="handleOpenDialog">{{ label }}</el-button>
+  <el-button plain type="primary" :disabled="disabled || loading" @click="handleOpenDialog">{{ label }}</el-button>
   <DocumentSettingDialog v-if="dialogMounted" ref="settingDialogRef" batch :loading="loading" @submit="handleSubmit" @closed="handleDialogClosed" />
 </template>
diff --git a/ui/src/views/knowledge-detail/library/document/action-dropdown/tokenize/BatchTokenizeAction.vue b/ui/src/views/knowledge-detail/library/document/action-dropdown/tokenize/BatchTokenizeAction.vue
index a0101107cd4..d1cd940b6d4 100644
--- a/ui/src/views/knowledge-detail/library/document/action-dropdown/tokenize/BatchTokenizeAction.vue
+++ b/ui/src/views/knowledge-detail/library/document/action-dropdown/tokenize/BatchTokenizeAction.vue
@@ -26,5 +26,5 @@ function handleTokenize() {
 
 <template>
   <!-- 批量分词索引 -->
-  <el-button plain :disabled="loading" @click="handleTokenize">分词索引</el-button>
+  <el-button plain type="primary" :disabled="loading" @click="handleTokenize">分词索引</el-button>
 </template>
diff --git a/ui/src/views/knowledge-detail/library/document/components/DocumentTags.vue b/ui/src/views/knowledge-detail/library/document/components/DocumentTags.vue
index 14d0565e73e..738b83fbc0d 100644
--- a/ui/src/views/knowledge-detail/library/document/components/DocumentTags.vue
+++ b/ui/src/views/knowledge-detail/library/document/components/DocumentTags.vue
@@ -1,14 +1,33 @@
 <script setup lang="ts">
 import { TOOLTIP_SHOW_DELAY } from '@/components/global/mk-tooltip/constants'
-import { computed } from 'vue'
+import { computed, nextTick, ref, useTemplateRef } from 'vue'
+import type DocumentApi from '@/api/admin/workspace/knowledge/document'
 import type { DocumentItem } from '@/api/types'
+import AddTagDialog from '../action-dropdown/setting-tags/AddTagDialog.vue'
 
 defineOptions({ name: 'DocumentTags' })
-const props = defineProps<{ document: DocumentItem }>()
-const emit = defineEmits<{ add: [documentId: string] }>()
+const props = defineProps<{ api: typeof DocumentApi; knowledgeId: string; document: DocumentItem; disabled?: boolean }>()
+const loading = defineModel<boolean>('loading', { default: false })
+const emit = defineEmits<{ refresh: [] }>()
 
 // 优先使用接口数量，兼容只返回标签明细的数据。
 const tagCount = computed(() => props.document.tag_count ?? props.document.tags?.length ?? 0)
+
+const dialogMounted = ref(false)
+const addTagRef = useTemplateRef<InstanceType<typeof AddTagDialog>>('addTagRef')
+const targetKnowledgeId = ref('')
+
+function handleOpenDialog() {
+  if (props.disabled || loading.value || dialogMounted.value) return
+  targetKnowledgeId.value = props.knowledgeId
+  const documentId = props.document.id
+  dialogMounted.value = true
+  return nextTick(() => addTagRef.value?.open([documentId]))
+}
+
+function handleDialogClosed() {
+  dialogMounted.value = false
+}
 </script>
 
 <template>
@@ -32,9 +51,18 @@ const tagCount = computed(() => props.document.tag_count ?? props.document.tags?
       </div>
     </el-popover>
     <!-- 添加文档标签 -->
-    <el-button class="mk-add-tag-button" plain @click.stop="emit('add', document.id)">
+    <el-button class="mk-add-tag-button" plain :disabled="disabled || loading" @click.stop="handleOpenDialog">
       <MkIcon name="icon_add_outlined" size="14" />
       <span>标签</span>
     </el-button>
   </div>
+  <AddTagDialog
+    v-if="dialogMounted"
+    ref="addTagRef"
+    v-model:loading="loading"
+    :api="api"
+    :knowledge-id="targetKnowledgeId"
+    @refresh="emit('refresh')"
+    @closed="handleDialogClosed"
+  />
 </template>
diff --git a/ui/src/views/knowledge-detail/library/document/index.vue b/ui/src/views/knowledge-detail/library/document/index.vue
index e8b7edb9f0b..a12e5ff56d7 100644
--- a/ui/src/views/knowledge-detail/library/document/index.vue
+++ b/ui/src/views/knowledge-detail/library/document/index.vue
@@ -33,6 +33,7 @@ import {
   BatchCancelTaskAction,
   DeleteDocumentAction,
   DocumentTagsAction,
+  BatchDocumentTagsAction,
   EmbeddingDocumentAction,
   GenerateQuestionsAction,
   BatchGenerateQuestionsAction,
@@ -151,8 +152,7 @@ const documentTagOptions = ref<CascaderOption[]>([])
 const documentTagLoading = ref(false)
 
 function loadDocumentTagOptions() {
-  // 加载成功后至少有“无标签”选项，无需额外维护 loaded 状态。
-  if (documentTagLoading.value || documentTagOptions.value.length) return
+  if (documentTagLoading.value) return
   documentTagLoading.value = true
   const requestApi = isWorkspaceSharedResource() ? SharedTagsApi : TagsApi
   return requestApi
@@ -419,7 +419,14 @@ onBeforeUnmount(() => {
         />
       </template>
       <template #default="{ row }: { row: DocumentItem }">
-        <DocumentTags :document="row" />
+        <DocumentTags
+          :api="DocumentApi"
+          :knowledge-id="knowledgeId"
+          :document="row"
+          :disabled="isWorkspaceSharedResource()"
+          v-model:loading="operationLoading"
+          @refresh="refreshAfterOperation"
+        />
       </template>
     </el-table-column>
 
@@ -487,8 +494,16 @@ onBeforeUnmount(() => {
                 :document="row"
                 @refresh="refreshAfterOperation"
               />
-              <!-- TODO: 设置文档标签 -->
-              <DocumentTagsAction label="标签设置" icon="icon_tag" :disabled="operationLoading" />
+              <!-- 设置当前文档的标签 -->
+              <DocumentTagsAction
+                label="标签设置"
+                icon="icon_tag"
+                :api="DocumentApi"
+                :knowledge-id="knowledgeId"
+                :document="row"
+                v-model:loading="operationLoading"
+                @refresh="refreshAfterOperation"
+              />
               <!-- 同步 -->
               <SyncDocumentAction
                 v-if="
@@ -590,9 +605,15 @@ onBeforeUnmount(() => {
         v-model:loading="operationLoading"
         @refresh="refreshAfterOperation"
       />
-
-      <!-- // TODO 批量添加标签 -->
-      <el-button>添加标签</el-button>
+      <!-- 为选中文档批量添加标签 -->
+      <BatchDocumentTagsAction
+        label="标签设置"
+        :api="DocumentApi"
+        :knowledge-id="knowledgeId"
+        :document-ids="selectedDocumentIds"
+        v-model:loading="operationLoading"
+        @refresh="refreshAfterOperation"
+      />
 
       <!-- 更多批量操作 -->
       <MkDropdown class="ml-3" trigger="click" placement="bottom-end" hide-when-empty persistent>
diff --git a/ui/src/views/knowledge-detail/library/tags/components/CreateTagDialog.vue b/ui/src/views/knowledge-detail/library/tags/components/CreateTagDialog.vue
index 29d523ad10b..a27202100d8 100644
--- a/ui/src/views/knowledge-detail/library/tags/components/CreateTagDialog.vue
+++ b/ui/src/views/knowledge-detail/library/tags/components/CreateTagDialog.vue
@@ -1,13 +1,15 @@
 <script setup lang="ts">
 import { computed, reactive, ref } from 'vue'
 import type { FormInstance, FormItemRule } from 'element-plus'
-import type TagsApi from '@/api/admin/workspace/knowledge/tags'
+import TagsApi from '@/api/admin/workspace/knowledge/tags'
 import type { KnowledgeTagPayload } from '@/api/types'
 import { MsgSuccess } from '@/utils/message'
 
 defineOptions({ name: 'CreateTagDialog' })
 
-const props = defineProps<{ knowledgeId: string; api: typeof TagsApi }>()
+const props = withDefaults(defineProps<{ knowledgeId: string; api?: typeof TagsApi }>(), {
+  api: () => TagsApi,
+})
 const emit = defineEmits<{ refresh: [] }>()
 
 const visible = ref(false)
diff --git a/ui/src/views/knowledge-detail/library/tags/index.vue b/ui/src/views/knowledge-detail/library/tags/index.vue
index 7a5558721bf..9220bb62143 100644
--- a/ui/src/views/knowledge-detail/library/tags/index.vue
+++ b/ui/src/views/knowledge-detail/library/tags/index.vue
@@ -5,7 +5,7 @@ import type { TableColumnCtx } from 'element-plus'
 import type { ResourceDetailPageProps } from '@/layout/ResourceDetailLayout.vue'
 import TagsApi from '@/api/admin/workspace/knowledge/tags'
 import DocumentApi from '@/api/admin/workspace/knowledge/document'
-import type { Dict, KnowledgeTagGroup, KnowledgeTagUpdatePayload } from '@/api/types'
+import type { KnowledgeTagGroup, KnowledgeTagUpdatePayload } from '@/api/types'
 import { MsgConfirm, MsgSuccess } from '@/utils/message'
 import CreateTagDialog from './components/CreateTagDialog.vue'
 import EditTagDialog from './components/EditTagDialog.vue'
@@ -32,23 +32,15 @@ const tagTableRef = ref<{ clearSelection: () => void }>()
 const selectedTags = ref<TagTableRow[]>([])
 const hoveredTagKey = ref<string | null>(null)
 
-/* 保留完整分组进行搜索和分页，避免同一标签跨页拆开。 */
-const filteredTagGroups = computed(() => {
-  const keyword = searchText.value.trim().toLocaleLowerCase()
-  return tagGroups.value.filter(
-    (group) =>
-      !keyword || group.key.toLocaleLowerCase().includes(keyword) || group.values.some(({ value }) => value.toLocaleLowerCase().includes(keyword)),
-  )
-})
 const paginationConfig = computed({
-  get: () => ({ ...tagPage.value, total: filteredTagGroups.value.length }),
+  get: () => ({ ...tagPage.value, total: tagGroups.value.length }),
   set: ({ currentPage, pageSize }) => {
     tagPage.value = { currentPage, pageSize }
   },
 })
 const tagRows = computed<TagTableRow[]>(() => {
   const start = (tagPage.value.currentPage - 1) * tagPage.value.pageSize
-  return filteredTagGroups.value
+  return tagGroups.value
     .slice(start, start + tagPage.value.pageSize)
     .flatMap((group) => group.values.map((tag, index) => ({ ...tag, key: group.key, rowspan: index === 0 ? group.values.length : 0 })))
 })
@@ -62,10 +54,10 @@ function clearSelection() {
 function loadTags() {
   clearSelection()
   loading.value = true
-  return TagsApi.getKnowledgeTags(knowledgeId.value)
+  return TagsApi.getKnowledgeTags(knowledgeId.value, { name: searchText.value.trim() || undefined })
     .then((groups) => {
       tagGroups.value = groups
-      const lastPage = Math.max(1, Math.ceil(filteredTagGroups.value.length / tagPage.value.pageSize))
+      const lastPage = Math.max(1, Math.ceil(groups.length / tagPage.value.pageSize))
       tagPage.value.currentPage = Math.min(tagPage.value.currentPage, lastPage)
     })
     .finally(() => {
@@ -73,10 +65,9 @@ function loadTags() {
     })
 }
 
-function handleSearchChange(query?: Dict<unknown>) {
-  searchText.value = typeof query?.name === 'string' ? query.name : ''
+function handleSearchChange() {
   tagPage.value.currentPage = 1
-  clearSelection()
+  return loadTags()
 }
 
 function handleSelectionChange(selection: unknown[]) {
@@ -178,7 +169,7 @@ onMounted(() => {
     <div class="flex-between gap-4">
       <h4>{{ title }}</h4>
       <div class="flex-align-center">
-        <MkComplexSearch :fields="[{ label: '名称', value: 'name' }]" class="mr-3" @change="handleSearchChange" />
+        <MkSearchInput v-model="searchText" class="mr-3 w-60!" @change="handleSearchChange" />
         <!-- 导入标签，成功后刷新列表 -->
         <ButtonImportTags :api="TagsApi" :knowledge-id="knowledgeId" :disabled="loading || operationLoading" @refresh="loadTags" />
         <!-- 创建标签 -->