refactor: update terminology and improve clarity in knowledge parsing documentation and UI

This commit refines the language used in the knowledge parsing documentation and user interface. Key changes include:

- Updated the description of the `finalizing` state to clarify that it refers to ongoing optimization tasks rather than just completion.
- Modified the confirmation message for canceling parsing to replace "enhancement" with "optimization" for consistency across multiple languages.
- Enhanced the UI to better reflect the current parsing status, including a new function to display appropriate status messages during in-flight parsing.

These changes aim to improve user understanding and experience when interacting with the knowledge parsing features.
This commit is contained in:
wizardchen
2026-05-28 19:43:14 +08:00
committed by lyingbug
parent 44d6175559
commit e3525f884b
6 changed files with 53 additions and 22 deletions
+2 -2
View File
@@ -31,7 +31,7 @@
> - 路径中的 `:id`(知识库路径下)为**知识库 ID**,`/knowledge/:id` 中的 `:id` 为**知识 ID**。
> - 所有写操作(创建、更新、删除、迁移、重新解析、取消解析)需要当前用户在知识库所属组织内具有 `editor` 或 `admin` 权限;清空知识库内容仅 KB **所有者**(admin 且租户匹配)可操作。
> - 关键状态字段:`parse_status` 取值 `pending` / `processing` / `finalizing` / `completed` / `failed` / `cancelled`;`enable_status` 取值 `enabled` / `disabled`。
> - `processing` 指 DocReader / 分块 / 向量化阶段;`finalizing` 指主解析已完成、但摘要 / 问题生成 / 图谱抽取等异步增强子任务仍在执行;只有当全部子任务到达终态后才进入 `completed`。
> - `processing` 指 DocReader / 分块 / 向量化阶段;`finalizing` 指主解析已完成、仍在执行摘要 / 问题生成 / 图谱抽取等索引优化任务;只有当全部子任务到达终态后才进入 `completed`。
> - `cancelled` 表示解析被用户主动取消,可通过 `reparse` 重新触发。`pending` / `processing` / `finalizing` 这三种状态都可通过 `cancel-parse` 终止。
## POST `/knowledge-bases/:id/knowledge/file` - 上传文件创建知识
@@ -574,7 +574,7 @@ curl --location --request POST 'http://localhost:8080/api/v1/knowledge/4c4e7c1a-
- 将 `parse_status` 置为 `cancelled`,`error_message` 写入「用户已取消解析」,并把 `pending_subtasks_count` 清零。
- 已写入数据库的分块 / 索引保留,可通过 `reparse` 接口在同一记录上重新触发解析。
- 后台异步会 best-effort 从队列中删除该知识对应的下游任务(多模态、问题生成、摘要、图谱抽取、Post-Process 等),并对正在执行的 worker 发出停止信号;worker 在下一个检查点退出。
- **可取消的状态**:`pending` / `processing` / `finalizing`。`finalizing` 表示主解析已完成、但摘要 / 问题生成 / 图谱抽取等增强子任务仍在执行;在该状态取消可以及时止血最昂贵的增强阶段(图谱抽取按 chunk 调 LLM,开销最大)。
- **可取消的状态**:`pending` / `processing` / `finalizing`。`finalizing` 表示主解析已完成、摘要 / 问题生成 / 图谱抽取等索引优化任务仍在执行;在该状态取消可以及时停止后续 LLM 消耗(图谱抽取按 chunk 调用,开销最大)。
- 已经完成 (`completed`) 或失败 (`failed`) 的知识不允许取消;正在删除 (`deleting`) 的知识不允许取消。
- 接口幂等:对已经 `cancelled` 的记录重复调用直接返回当前状态。
+2 -2
View File
@@ -269,7 +269,7 @@ export default {
rebuildFailed: 'Rebuild failed. Please try again later',
rebuildInProgress: 'This document is currently being parsed. Please try again later',
cancelParse: 'Stop parsing',
cancelParseConfirmBody: 'Stop parsing "{title}"? Already-written chunks are kept and can be re-parsed later via "Rebuild"; pending enrichment subtasks (summary / Q&A / knowledge graph) will be dropped immediately.',
cancelParseConfirmBody: 'Stop parsing "{title}"? Already-written chunks are kept and can be re-parsed later via "Rebuild"; pending optimization tasks (summary / Q&A / knowledge graph) will be dropped immediately.',
cancelParseSubmitted: 'Parsing stopped',
cancelParseFailed: 'Failed to stop, please try again later',
draft: 'Draft',
@@ -321,7 +321,7 @@ export default {
batchDeleteFailed: 'Batch delete failed',
statusCompleted: 'Completed',
statusProcessing: 'Processing',
statusFinalizing: 'Finalizing',
statusFinalizing: 'Optimizing',
statusPending: 'Pending',
statusFailed: 'Failed',
statusCancelled: 'Cancelled',
+2 -2
View File
@@ -210,7 +210,7 @@ export default {
rebuildFailed: "재구축 실패, 나중에 다시 시도해주세요",
rebuildInProgress: "현재 문서가 파싱 중입니다. 나중에 다시 시도해주세요",
cancelParse: "파싱 중지",
cancelParseConfirmBody: '"{title}"의 파싱을 중지하시겠습니까? 이미 저장된 청크는 유지되며 "다시 빌드"를 통해 다시 파싱할 수 있습니다. 보강 단계(요약 / Q&A / 지식 그래프)의 대기 중인 하위 작업은 즉시 취소됩니다.',
cancelParseConfirmBody: '"{title}"의 파싱을 중지하시겠습니까? 이미 저장된 청크는 유지되며 "다시 빌드"를 통해 다시 파싱할 수 있습니다. 최적화 단계(요약 / Q&A / 지식 그래프)의 대기 중인 작업은 즉시 취소됩니다.',
cancelParseSubmitted: "파싱이 중지되었습니다",
cancelParseFailed: "중지에 실패했습니다. 나중에 다시 시도해주세요",
characters: "자",
@@ -325,7 +325,7 @@ export default {
batchDeleteFailed: "일괄 삭제 실패",
statusCompleted: "완료",
statusProcessing: "처리 중",
statusFinalizing: "마무리 중",
statusFinalizing: "최적화 중",
statusPending: "대기 중",
statusFailed: "실패",
statusCancelled: "취소됨",
+2 -2
View File
@@ -247,7 +247,7 @@ export default {
batchDeleteFailed: 'Ошибка пакетного удаления',
statusCompleted: 'Завершено',
statusProcessing: 'Обработка',
statusFinalizing: 'Завершение',
statusFinalizing: 'Оптимизация',
statusPending: 'Ожидание',
statusFailed: 'Ошибка',
statusCancelled: 'Отменено',
@@ -360,7 +360,7 @@ export default {
rebuildFailed: 'Ошибка пересборки, попробуйте позже',
rebuildInProgress: 'Документ сейчас анализируется, попробуйте позже',
cancelParse: 'Остановить разбор',
cancelParseConfirmBody: 'Остановить разбор «{title}»? Уже записанные фрагменты сохранятся, и их можно будет разобрать заново через «Пересобрать». Ожидающие подзадачи обогащения (резюме / вопросы и ответы / граф знаний) будут немедленно отменены.',
cancelParseConfirmBody: 'Остановить разбор «{title}»? Уже записанные фрагменты сохранятся, и их можно будет разобрать заново через «Пересобрать». Ожидающие задачи оптимизации (резюме / вопросы и ответы / граф знаний) будут немедленно отменены.',
cancelParseSubmitted: 'Разбор остановлен',
cancelParseFailed: 'Не удалось остановить, попробуйте позже'
},
+2 -2
View File
@@ -270,7 +270,7 @@ export default {
rebuildFailed: "重建失败,请稍后再试",
rebuildInProgress: "当前文档正在解析中,请稍后重试",
cancelParse: "停止解析",
cancelParseConfirmBody: '确认停止解析"{title}"?已写入的分块会保留,可稍后通过"重建"重新触发;增强阶段(摘要 / 问答 / 知识图谱)的待执行子任务会被立即丢弃。',
cancelParseConfirmBody: '确认停止解析"{title}"?已写入的分块会保留,可稍后通过"重建"重新触发;优化阶段(摘要 / 问答 / 知识图谱)的待执行任务会被立即丢弃。',
cancelParseSubmitted: "已停止解析",
cancelParseFailed: "停止失败,请稍后再试",
draft: "草稿",
@@ -322,7 +322,7 @@ export default {
batchDeleteFailed: "批量删除失败",
statusCompleted: "已完成",
statusProcessing: "解析中",
statusFinalizing: "增强中",
statusFinalizing: "优化中",
statusPending: "等待中",
statusFailed: "失败",
statusCancelled: "已取消",
+43 -12
View File
@@ -313,6 +313,17 @@ function isParseInFlight(status?: string): boolean {
return status === 'pending' || status === 'processing' || status === 'finalizing';
}
// Status line shown on the card body while parse is still in flight.
function inFlightCardStatusText(item: KnowledgeCard): string {
if (item.parse_status === 'finalizing') {
if (item.summary_status === 'pending' || item.summary_status === 'processing') {
return t('knowledgeBase.generatingSummary');
}
return t('knowledgeBase.statusFinalizing');
}
return t('knowledgeBase.parsingInProgress');
}
function isTraceMenuVisible(item: KnowledgeCard): boolean {
if (!item?.id) return false;
if (isParseInFlight(item.parse_status)) {
@@ -2470,20 +2481,29 @@ async function createNewSession(value: string): Promise<void> {
</template>
</t-popup>
</div>
<div v-if="item.parse_status === 'processing' || item.parse_status === 'pending'"
class="card-analyze">
<div
v-if="isParseInFlight(item.parse_status)"
class="card-analyze card-analyze-trace"
role="button"
tabindex="0"
:title="t('knowledgeStages.viewTrace')"
@click.stop="handleViewTrace(index, item)"
@keydown.enter.stop="handleViewTrace(index, item)"
@keydown.space.prevent.stop="handleViewTrace(index, item)"
>
<t-icon name="loading" class="card-analyze-loading"></t-icon>
<span class="card-analyze-txt">{{ t('knowledgeBase.parsingInProgress') }}</span>
<span class="card-analyze-txt">{{ inFlightCardStatusText(item) }}</span>
</div>
<div v-else-if="item.parse_status === 'finalizing'" class="card-analyze">
<t-icon name="loading" class="card-analyze-loading"></t-icon>
<span class="card-analyze-txt">{{
(item.summary_status === 'pending' || item.summary_status === 'processing')
? t('knowledgeBase.generatingSummary')
: t('knowledgeBase.statusFinalizing')
}}</span>
</div>
<div v-else-if="item.parse_status === 'failed'" class="card-analyze failure">
<div
v-else-if="item.parse_status === 'failed'"
class="card-analyze failure card-analyze-trace"
role="button"
tabindex="0"
:title="t('knowledgeStages.viewTrace')"
@click.stop="handleViewTrace(index, item)"
@keydown.enter.stop="handleViewTrace(index, item)"
@keydown.space.prevent.stop="handleViewTrace(index, item)"
>
<t-icon name="close-circle" class="card-analyze-loading failure"></t-icon>
<span class="card-analyze-txt failure">{{ t('knowledgeBase.parsingFailed') }}</span>
</div>
@@ -4071,6 +4091,7 @@ async function createNewSession(value: string): Promise<void> {
flex-shrink: 0;
height: 52px;
display: flex;
align-items: flex-start;
}
.card-analyze-loading {
@@ -4087,6 +4108,16 @@ async function createNewSession(value: string): Promise<void> {
margin-left: 8px;
}
// In-flight / failed status row opens the trace drawer — no extra
// icon; hover affordance only.
.card-analyze-trace {
cursor: pointer;
&:hover .card-analyze-txt {
text-decoration: underline;
}
}
.failure {
color: var(--td-error-color);
}