feat(wiki): add page hierarchy/category metadata and retrieval APIs

Persist category and hierarchy metadata on wiki pages (new migration), expose
category-path retrieval and related repository/service/handler/router APIs, and
update wiki ingestion (batch, cite, taxonomy) plus agent wiki prompts to build
and consume the taxonomy. Regenerate swagger docs for the new endpoints.
This commit is contained in:
wizardchen
2026-06-16 16:35:06 +08:00
committed by lyingbug
parent ec66a3dac7
commit fe33db9493
20 changed files with 1893 additions and 25 deletions
+153 -1
View File
@@ -6350,6 +6350,71 @@ const docTemplate = `{
}
}
},
"/knowledgebase/{kb_id}/wiki/categories": {
"get": {
"security": [
{
"Bearer": []
}
],
"description": "Retrieve direct child directories for a wiki page type and optional parent_path",
"produces": [
"application/json"
],
"tags": [
"Wiki"
],
"summary": "List wiki category paths",
"parameters": [
{
"type": "string",
"description": "Knowledge base ID",
"name": "kb_id",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Wiki page type; comma-separated for multiple (e.g. entity,concept)",
"name": "page_type",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Parent category path, slash-separated",
"name": "parent_path",
"in": "query"
},
{
"type": "integer",
"description": "Page number (1-based)",
"name": "page",
"in": "query"
},
{
"type": "integer",
"description": "Page size",
"name": "page_size",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiCategoryPathListResponse"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
}
},
"/knowledgebase/{kb_id}/wiki/graph": {
"get": {
"security": [
@@ -6682,7 +6747,7 @@ const docTemplate = `{
},
{
"type": "string",
"description": "Filter by page type",
"description": "Filter by page type; comma-separated for multiple (e.g. entity,concept)",
"name": "page_type",
"in": "query"
},
@@ -13730,6 +13795,9 @@ const docTemplate = `{
"dimension": {
"type": "integer"
},
"supports_dimension_override": {
"type": "boolean"
},
"truncate_prompt_tokens": {
"type": "integer"
}
@@ -17095,6 +17163,43 @@ const docTemplate = `{
"WebSearchProviderTypeSearxng"
]
},
"github_com_Tencent_WeKnora_internal_types.WikiCategoryPath": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"path": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"github_com_Tencent_WeKnora_internal_types.WikiCategoryPathListResponse": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"page_size": {
"type": "integer"
},
"paths": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiCategoryPath"
}
},
"total": {
"type": "integer"
},
"total_pages": {
"type": "integer"
}
}
},
"github_com_Tencent_WeKnora_internal_types.WikiConfig": {
"type": "object",
"properties": {
@@ -17223,14 +17328,32 @@ const docTemplate = `{
"github_com_Tencent_WeKnora_internal_types.WikiIndexEntry": {
"type": "object",
"properties": {
"category_path": {
"type": "array",
"items": {
"type": "string"
}
},
"depth": {
"type": "integer"
},
"parent_slug": {
"type": "string"
},
"slug": {
"type": "string"
},
"sort_order": {
"type": "integer"
},
"summary": {
"type": "string"
},
"title": {
"type": "string"
},
"wiki_path": {
"type": "string"
}
}
},
@@ -17350,6 +17473,13 @@ const docTemplate = `{
"type": "string"
}
},
"category_path": {
"description": "CategoryPath is the directory breadcrumb that groups this page in the\nwiki browser, e.g. [\"AI\", \"LLM 应用\", \"RAG\"]. It is intentionally\nlabel-based so intermediate directory nodes do not need to be real pages.",
"type": "array",
"items": {
"type": "string"
}
},
"chunk_refs": {
"description": "ChunkRefs records the specific source-document chunks this page was\nbuilt from — one UUID per cited chunk. Populated during ingest from\nthe chunk-citation pass; refreshed wholesale whenever the page is\nre-materialized. Empty for summary pages (they are document-level\nsynopses and don't carry chunk-level citations). Use this when you\nneed to surface the underlying evidence for a wiki page, or to\nretract citations when a source document is deleted.",
"type": "array",
@@ -17373,6 +17503,10 @@ const docTemplate = `{
}
]
},
"depth": {
"description": "Depth is len(CategoryPath), cached for filtering / display.",
"type": "integer"
},
"id": {
"description": "Unique identifier (UUID)",
"type": "string"
@@ -17406,10 +17540,18 @@ const docTemplate = `{
"description": "Page type: summary, entity, concept, index, log, synthesis, comparison",
"type": "string"
},
"parent_slug": {
"description": "ParentSlug optionally points at the wiki page that should act as this\npage's semantic parent in the directory tree. The parent may be empty\nwhen the page is grouped only by CategoryPath.",
"type": "string"
},
"slug": {
"description": "URL-friendly slug for addressing, e.g. \"entity/acme-corp\", \"concept/rag\"\nUnique within a knowledge base",
"type": "string"
},
"sort_order": {
"description": "SortOrder allows generated or manually edited pages to control sibling\nordering before falling back to title.",
"type": "integer"
},
"source_refs": {
"description": "References to source knowledge IDs that contributed to this page.\nFormat matches the legacy \"\u003cknowledge_id\u003e|\u003cdoc_title\u003e\" convention used\nacross the ingest pipeline, so retract / display code can split on ` + "`" + `|` + "`" + `\nto recover the title. Document-level granularity.",
"type": "array",
@@ -17440,6 +17582,10 @@ const docTemplate = `{
"version": {
"description": "Version number. Incremented only when a user-visible content field\n(title, content, summary, page_type, status) actually changes; pure\nbookkeeping writes (link maintenance, same-content re-ingest, status\nsync from background jobs) leave it untouched so it can be used as a\nreal \"the page was edited\" signal.",
"type": "integer"
},
"wiki_path": {
"description": "WikiPath is a normalized, sortable path derived from page_type,\ncategory_path, and title. It keeps large directory listings cheap to sort.",
"type": "string"
}
}
},
@@ -18203,6 +18349,9 @@ const docTemplate = `{
"source": {
"description": "为空时按需默认为 \"remote\"",
"type": "string"
},
"supportsDimensionOverride": {
"type": "boolean"
}
}
},
@@ -18437,6 +18586,9 @@ const docTemplate = `{
"source": {
"description": "为空时按需默认为 \"remote\"",
"type": "string"
},
"supportsDimensionOverride": {
"type": "boolean"
}
}
},
+153 -1
View File
@@ -6343,6 +6343,71 @@
}
}
},
"/knowledgebase/{kb_id}/wiki/categories": {
"get": {
"security": [
{
"Bearer": []
}
],
"description": "Retrieve direct child directories for a wiki page type and optional parent_path",
"produces": [
"application/json"
],
"tags": [
"Wiki"
],
"summary": "List wiki category paths",
"parameters": [
{
"type": "string",
"description": "Knowledge base ID",
"name": "kb_id",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Wiki page type; comma-separated for multiple (e.g. entity,concept)",
"name": "page_type",
"in": "query",
"required": true
},
{
"type": "string",
"description": "Parent category path, slash-separated",
"name": "parent_path",
"in": "query"
},
{
"type": "integer",
"description": "Page number (1-based)",
"name": "page",
"in": "query"
},
{
"type": "integer",
"description": "Page size",
"name": "page_size",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiCategoryPathListResponse"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
}
}
}
}
},
"/knowledgebase/{kb_id}/wiki/graph": {
"get": {
"security": [
@@ -6675,7 +6740,7 @@
},
{
"type": "string",
"description": "Filter by page type",
"description": "Filter by page type; comma-separated for multiple (e.g. entity,concept)",
"name": "page_type",
"in": "query"
},
@@ -13723,6 +13788,9 @@
"dimension": {
"type": "integer"
},
"supports_dimension_override": {
"type": "boolean"
},
"truncate_prompt_tokens": {
"type": "integer"
}
@@ -17088,6 +17156,43 @@
"WebSearchProviderTypeSearxng"
]
},
"github_com_Tencent_WeKnora_internal_types.WikiCategoryPath": {
"type": "object",
"properties": {
"count": {
"type": "integer"
},
"path": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"github_com_Tencent_WeKnora_internal_types.WikiCategoryPathListResponse": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"page_size": {
"type": "integer"
},
"paths": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.WikiCategoryPath"
}
},
"total": {
"type": "integer"
},
"total_pages": {
"type": "integer"
}
}
},
"github_com_Tencent_WeKnora_internal_types.WikiConfig": {
"type": "object",
"properties": {
@@ -17216,14 +17321,32 @@
"github_com_Tencent_WeKnora_internal_types.WikiIndexEntry": {
"type": "object",
"properties": {
"category_path": {
"type": "array",
"items": {
"type": "string"
}
},
"depth": {
"type": "integer"
},
"parent_slug": {
"type": "string"
},
"slug": {
"type": "string"
},
"sort_order": {
"type": "integer"
},
"summary": {
"type": "string"
},
"title": {
"type": "string"
},
"wiki_path": {
"type": "string"
}
}
},
@@ -17343,6 +17466,13 @@
"type": "string"
}
},
"category_path": {
"description": "CategoryPath is the directory breadcrumb that groups this page in the\nwiki browser, e.g. [\"AI\", \"LLM 应用\", \"RAG\"]. It is intentionally\nlabel-based so intermediate directory nodes do not need to be real pages.",
"type": "array",
"items": {
"type": "string"
}
},
"chunk_refs": {
"description": "ChunkRefs records the specific source-document chunks this page was\nbuilt from — one UUID per cited chunk. Populated during ingest from\nthe chunk-citation pass; refreshed wholesale whenever the page is\nre-materialized. Empty for summary pages (they are document-level\nsynopses and don't carry chunk-level citations). Use this when you\nneed to surface the underlying evidence for a wiki page, or to\nretract citations when a source document is deleted.",
"type": "array",
@@ -17366,6 +17496,10 @@
}
]
},
"depth": {
"description": "Depth is len(CategoryPath), cached for filtering / display.",
"type": "integer"
},
"id": {
"description": "Unique identifier (UUID)",
"type": "string"
@@ -17399,10 +17533,18 @@
"description": "Page type: summary, entity, concept, index, log, synthesis, comparison",
"type": "string"
},
"parent_slug": {
"description": "ParentSlug optionally points at the wiki page that should act as this\npage's semantic parent in the directory tree. The parent may be empty\nwhen the page is grouped only by CategoryPath.",
"type": "string"
},
"slug": {
"description": "URL-friendly slug for addressing, e.g. \"entity/acme-corp\", \"concept/rag\"\nUnique within a knowledge base",
"type": "string"
},
"sort_order": {
"description": "SortOrder allows generated or manually edited pages to control sibling\nordering before falling back to title.",
"type": "integer"
},
"source_refs": {
"description": "References to source knowledge IDs that contributed to this page.\nFormat matches the legacy \"\u003cknowledge_id\u003e|\u003cdoc_title\u003e\" convention used\nacross the ingest pipeline, so retract / display code can split on `|`\nto recover the title. Document-level granularity.",
"type": "array",
@@ -17433,6 +17575,10 @@
"version": {
"description": "Version number. Incremented only when a user-visible content field\n(title, content, summary, page_type, status) actually changes; pure\nbookkeeping writes (link maintenance, same-content re-ingest, status\nsync from background jobs) leave it untouched so it can be used as a\nreal \"the page was edited\" signal.",
"type": "integer"
},
"wiki_path": {
"description": "WikiPath is a normalized, sortable path derived from page_type,\ncategory_path, and title. It keeps large directory listings cheap to sort.",
"type": "string"
}
}
},
@@ -18196,6 +18342,9 @@
"source": {
"description": "为空时按需默认为 \"remote\"",
"type": "string"
},
"supportsDimensionOverride": {
"type": "boolean"
}
}
},
@@ -18430,6 +18579,9 @@
"source": {
"description": "为空时按需默认为 \"remote\"",
"type": "string"
},
"supportsDimensionOverride": {
"type": "boolean"
}
}
},
+113 -1
View File
@@ -850,6 +850,8 @@ definitions:
properties:
dimension:
type: integer
supports_dimension_override:
type: boolean
truncate_prompt_tokens:
type: integer
type: object
@@ -3345,6 +3347,30 @@ definitions:
- WebSearchProviderTypeOllama
- WebSearchProviderTypeBaidu
- WebSearchProviderTypeSearxng
github_com_Tencent_WeKnora_internal_types.WikiCategoryPath:
properties:
count:
type: integer
path:
items:
type: string
type: array
type: object
github_com_Tencent_WeKnora_internal_types.WikiCategoryPathListResponse:
properties:
page:
type: integer
page_size:
type: integer
paths:
items:
$ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.WikiCategoryPath'
type: array
total:
type: integer
total_pages:
type: integer
type: object
github_com_Tencent_WeKnora_internal_types.WikiConfig:
properties:
extraction_granularity:
@@ -3450,12 +3476,24 @@ definitions:
type: object
github_com_Tencent_WeKnora_internal_types.WikiIndexEntry:
properties:
category_path:
items:
type: string
type: array
depth:
type: integer
parent_slug:
type: string
slug:
type: string
sort_order:
type: integer
summary:
type: string
title:
type: string
wiki_path:
type: string
type: object
github_com_Tencent_WeKnora_internal_types.WikiIndexGroup:
properties:
@@ -3549,6 +3587,14 @@ definitions:
items:
type: string
type: array
category_path:
description: |-
CategoryPath is the directory breadcrumb that groups this page in the
wiki browser, e.g. ["AI", "LLM 应用", "RAG"]. It is intentionally
label-based so intermediate directory nodes do not need to be real pages.
items:
type: string
type: array
chunk_refs:
description: |-
ChunkRefs records the specific source-document chunks this page was
@@ -3571,6 +3617,9 @@ definitions:
allOf:
- $ref: '#/definitions/gorm.DeletedAt'
description: Soft delete
depth:
description: Depth is len(CategoryPath), cached for filtering / display.
type: integer
id:
description: Unique identifier (UUID)
type: string
@@ -3596,11 +3645,22 @@ definitions:
description: 'Page type: summary, entity, concept, index, log, synthesis,
comparison'
type: string
parent_slug:
description: |-
ParentSlug optionally points at the wiki page that should act as this
page's semantic parent in the directory tree. The parent may be empty
when the page is grouped only by CategoryPath.
type: string
slug:
description: |-
URL-friendly slug for addressing, e.g. "entity/acme-corp", "concept/rag"
Unique within a knowledge base
type: string
sort_order:
description: |-
SortOrder allows generated or manually edited pages to control sibling
ordering before falling back to title.
type: integer
source_refs:
description: |-
References to source knowledge IDs that contributed to this page.
@@ -3633,6 +3693,11 @@ definitions:
sync from background jobs) leave it untouched so it can be used as a
real "the page was edited" signal.
type: integer
wiki_path:
description: |-
WikiPath is a normalized, sortable path derived from page_type,
category_path, and title. It keeps large directory listings cheap to sort.
type: string
type: object
github_com_Tencent_WeKnora_internal_types.WikiPageIssue:
properties:
@@ -4159,6 +4224,8 @@ definitions:
source:
description: 为空时按需默认为 "remote"
type: string
supportsDimensionOverride:
type: boolean
required:
- modelName
type: object
@@ -4325,6 +4392,8 @@ definitions:
source:
description: 为空时按需默认为 "remote"
type: string
supportsDimensionOverride:
type: boolean
required:
- modelName
type: object
@@ -8834,6 +8903,49 @@ paths:
summary: Auto-fix wiki issues
tags:
- Wiki
/knowledgebase/{kb_id}/wiki/categories:
get:
description: Retrieve direct child directories for a wiki page type and optional
parent_path
parameters:
- description: Knowledge base ID
in: path
name: kb_id
required: true
type: string
- description: Wiki page type; comma-separated for multiple (e.g. entity,concept)
in: query
name: page_type
required: true
type: string
- description: Parent category path, slash-separated
in: query
name: parent_path
type: string
- description: Page number (1-based)
in: query
name: page
type: integer
- description: Page size
in: query
name: page_size
type: integer
produces:
- application/json
responses:
"200":
description: OK
schema:
$ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.WikiCategoryPathListResponse'
"400":
description: Bad Request
schema:
$ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
security:
- Bearer: []
summary: List wiki category paths
tags:
- Wiki
/knowledgebase/{kb_id}/wiki/graph:
get:
description: |-
@@ -9050,7 +9162,7 @@ paths:
name: kb_id
required: true
type: string
- description: Filter by page type
- description: Filter by page type; comma-separated for multiple (e.g. entity,concept)
in: query
name: page_type
type: string