Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

feat(graph): add standalone JSON graph search API (#4395)

Xinliang Zheng164dafca85a4
diff --git a/docs/docs.go b/docs/docs.go
index 4464d9d2f..826588e67 100644
--- a/docs/docs.go
+++ b/docs/docs.go
@@ -6272,6 +6272,121 @@ const docTemplate = `{
}
}
},
+ "/knowledge-bases/{id}/graph-search": {
+ "post": {
+ "security": [
+ {
+ "Bearer": []
+ },
+ {
+ "ApiKeyAuth": []
+ }
+ ],
+ "description": "对单个授权知识库按实体名进行区分大小写的子串查询,返回实体、定向关系及仍然有效的来源分块。不调用模型,不影响默认检索。0 表示使用默认上限。",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "知识库"
+ ],
+ "summary": "查询知识图谱",
+ "parameters": [
+ {
+ "type": "string",
+ "description": "知识库ID",
+ "name": "id",
+ "in": "path",
+ "required": true
+ },
+ {
+ "type": "string",
+ "description": "共享智能体 ID",
+ "name": "agent_id",
+ "in": "query"
+ },
+ {
+ "type": "integer",
+ "description": "共享智能体来源空间",
+ "name": "agent_source_tenant_id",
+ "in": "query"
+ },
+ {
+ "description": "查询及结果上限",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchRequest"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "schema": {
+ "allOf": [
+ {
+ "$ref": "#/definitions/internal_handler.DataResponse"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "data": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchResult"
+ }
+ }
+ }
+ ]
+ }
+ },
+ "400": {
+ "description": "参数错误",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ },
+ "401": {
+ "description": "未登录",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ },
+ "403": {
+ "description": "无权访问知识库",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ },
+ "404": {
+ "description": "知识库不存在",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ },
+ "409": {
+ "description": "知识图谱未启用",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ },
+ "500": {
+ "description": "来源校验失败",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ },
+ "503": {
+ "description": "图谱服务不可用",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ }
+ }
+ }
+ },
"/knowledge-bases/{id}/hybrid-search": {
"get": {
"security": [
@@ -27334,6 +27449,173 @@ const docTemplate = `{
}
}
},
+ "github_com_Tencent_WeKnora_internal_types.GraphSearchEntity": {
+ "type": "object",
+ "properties": {
+ "attributes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "id": {
+ "type": "string"
+ },
+ "knowledge_id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "source_chunk_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "github_com_Tencent_WeKnora_internal_types.GraphSearchMeta": {
+ "type": "object",
+ "properties": {
+ "max_nodes": {
+ "type": "integer"
+ },
+ "max_relations": {
+ "type": "integer"
+ },
+ "max_source_chunks": {
+ "type": "integer"
+ },
+ "truncated": {
+ "type": "boolean"
+ },
+ "truncation_reasons": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "github_com_Tencent_WeKnora_internal_types.GraphSearchRelation": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "source_chunk_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "source_id": {
+ "type": "string"
+ },
+ "target_id": {
+ "type": "string"
+ },
+ "type": {
+ "type": "string"
+ }
+ }
+ },
+ "github_com_Tencent_WeKnora_internal_types.GraphSearchRequest": {
+ "type": "object",
+ "required": [
+ "query"
+ ],
+ "properties": {
+ "max_nodes": {
+ "type": "integer",
+ "default": 50,
+ "maximum": 100,
+ "minimum": 0
+ },
+ "max_relations": {
+ "type": "integer",
+ "default": 100,
+ "maximum": 200,
+ "minimum": 0
+ },
+ "max_source_chunks": {
+ "type": "integer",
+ "default": 20,
+ "maximum": 50,
+ "minimum": 0
+ },
+ "query": {
+ "type": "string",
+ "maxLength": 512,
+ "minLength": 1
+ }
+ }
+ },
+ "github_com_Tencent_WeKnora_internal_types.GraphSearchResult": {
+ "type": "object",
+ "properties": {
+ "entities": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchEntity"
+ }
+ },
+ "knowledge_base_id": {
+ "type": "string"
+ },
+ "meta": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchMeta"
+ },
+ "query": {
+ "type": "string"
+ },
+ "relationships": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchRelation"
+ }
+ },
+ "source_chunks": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchSourceChunk"
+ }
+ }
+ }
+ },
+ "github_com_Tencent_WeKnora_internal_types.GraphSearchSourceChunk": {
+ "type": "object",
+ "properties": {
+ "chunk_index": {
+ "type": "integer"
+ },
+ "content": {
+ "type": "string"
+ },
+ "content_truncated": {
+ "type": "boolean"
+ },
+ "end_at": {
+ "type": "integer"
+ },
+ "id": {
+ "type": "string"
+ },
+ "knowledge_id": {
+ "type": "string"
+ },
+ "start_at": {
+ "type": "integer"
+ },
+ "title": {
+ "type": "string"
+ },
+ "title_truncated": {
+ "type": "boolean"
+ }
+ }
+ },
"github_com_Tencent_WeKnora_internal_types.History": {
"type": "object",
"properties": {
diff --git a/docs/swagger.json b/docs/swagger.json
index 2b7d1306b..5ae09e897 100644
--- a/docs/swagger.json
+++ b/docs/swagger.json
@@ -6265,6 +6265,121 @@
}
}
},
+ "/knowledge-bases/{id}/graph-search": {
+ "post": {
+ "security": [
+ {
+ "Bearer": []
+ },
+ {
+ "ApiKeyAuth": []
+ }
+ ],
+ "description": "对单个授权知识库按实体名进行区分大小写的子串查询,返回实体、定向关系及仍然有效的来源分块。不调用模型,不影响默认检索。0 表示使用默认上限。",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "知识库"
+ ],
+ "summary": "查询知识图谱",
+ "parameters": [
+ {
+ "type": "string",
+ "description": "知识库ID",
+ "name": "id",
+ "in": "path",
+ "required": true
+ },
+ {
+ "type": "string",
+ "description": "共享智能体 ID",
+ "name": "agent_id",
+ "in": "query"
+ },
+ {
+ "type": "integer",
+ "description": "共享智能体来源空间",
+ "name": "agent_source_tenant_id",
+ "in": "query"
+ },
+ {
+ "description": "查询及结果上限",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchRequest"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "schema": {
+ "allOf": [
+ {
+ "$ref": "#/definitions/internal_handler.DataResponse"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "data": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchResult"
+ }
+ }
+ }
+ ]
+ }
+ },
+ "400": {
+ "description": "参数错误",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ },
+ "401": {
+ "description": "未登录",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ },
+ "403": {
+ "description": "无权访问知识库",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ },
+ "404": {
+ "description": "知识库不存在",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ },
+ "409": {
+ "description": "知识图谱未启用",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ },
+ "500": {
+ "description": "来源校验失败",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ },
+ "503": {
+ "description": "图谱服务不可用",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ }
+ }
+ }
+ },
"/knowledge-bases/{id}/hybrid-search": {
"get": {
"security": [
@@ -27327,6 +27442,173 @@
}
}
},
+ "github_com_Tencent_WeKnora_internal_types.GraphSearchEntity": {
+ "type": "object",
+ "properties": {
+ "attributes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "id": {
+ "type": "string"
+ },
+ "knowledge_id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "source_chunk_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "github_com_Tencent_WeKnora_internal_types.GraphSearchMeta": {
+ "type": "object",
+ "properties": {
+ "max_nodes": {
+ "type": "integer"
+ },
+ "max_relations": {
+ "type": "integer"
+ },
+ "max_source_chunks": {
+ "type": "integer"
+ },
+ "truncated": {
+ "type": "boolean"
+ },
+ "truncation_reasons": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "github_com_Tencent_WeKnora_internal_types.GraphSearchRelation": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "source_chunk_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "source_id": {
+ "type": "string"
+ },
+ "target_id": {
+ "type": "string"
+ },
+ "type": {
+ "type": "string"
+ }
+ }
+ },
+ "github_com_Tencent_WeKnora_internal_types.GraphSearchRequest": {
+ "type": "object",
+ "required": [
+ "query"
+ ],
+ "properties": {
+ "max_nodes": {
+ "type": "integer",
+ "default": 50,
+ "maximum": 100,
+ "minimum": 0
+ },
+ "max_relations": {
+ "type": "integer",
+ "default": 100,
+ "maximum": 200,
+ "minimum": 0
+ },
+ "max_source_chunks": {
+ "type": "integer",
+ "default": 20,
+ "maximum": 50,
+ "minimum": 0
+ },
+ "query": {
+ "type": "string",
+ "maxLength": 512,
+ "minLength": 1
+ }
+ }
+ },
+ "github_com_Tencent_WeKnora_internal_types.GraphSearchResult": {
+ "type": "object",
+ "properties": {
+ "entities": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchEntity"
+ }
+ },
+ "knowledge_base_id": {
+ "type": "string"
+ },
+ "meta": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchMeta"
+ },
+ "query": {
+ "type": "string"
+ },
+ "relationships": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchRelation"
+ }
+ },
+ "source_chunks": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchSourceChunk"
+ }
+ }
+ }
+ },
+ "github_com_Tencent_WeKnora_internal_types.GraphSearchSourceChunk": {
+ "type": "object",
+ "properties": {
+ "chunk_index": {
+ "type": "integer"
+ },
+ "content": {
+ "type": "string"
+ },
+ "content_truncated": {
+ "type": "boolean"
+ },
+ "end_at": {
+ "type": "integer"
+ },
+ "id": {
+ "type": "string"
+ },
+ "knowledge_id": {
+ "type": "string"
+ },
+ "start_at": {
+ "type": "integer"
+ },
+ "title": {
+ "type": "string"
+ },
+ "title_truncated": {
+ "type": "boolean"
+ }
+ }
+ },
"github_com_Tencent_WeKnora_internal_types.History": {
"type": "object",
"properties": {
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index ee9b480ad..ffa670703 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -3546,6 +3546,119 @@ definitions:
type:
type: string
type: object
+ github_com_Tencent_WeKnora_internal_types.GraphSearchEntity:
+ properties:
+ attributes:
+ items:
+ type: string
+ type: array
+ id:
+ type: string
+ knowledge_id:
+ type: string
+ name:
+ type: string
+ source_chunk_ids:
+ items:
+ type: string
+ type: array
+ type: object
+ github_com_Tencent_WeKnora_internal_types.GraphSearchMeta:
+ properties:
+ max_nodes:
+ type: integer
+ max_relations:
+ type: integer
+ max_source_chunks:
+ type: integer
+ truncated:
+ type: boolean
+ truncation_reasons:
+ items:
+ type: string
+ type: array
+ type: object
+ github_com_Tencent_WeKnora_internal_types.GraphSearchRelation:
+ properties:
+ id:
+ type: string
+ source_chunk_ids:
+ items:
+ type: string
+ type: array
+ source_id:
+ type: string
+ target_id:
+ type: string
+ type:
+ type: string
+ type: object
+ github_com_Tencent_WeKnora_internal_types.GraphSearchRequest:
+ properties:
+ max_nodes:
+ default: 50
+ maximum: 100
+ minimum: 0
+ type: integer
+ max_relations:
+ default: 100
+ maximum: 200
+ minimum: 0
+ type: integer
+ max_source_chunks:
+ default: 20
+ maximum: 50
+ minimum: 0
+ type: integer
+ query:
+ maxLength: 512
+ minLength: 1
+ type: string
+ required:
+ - query
+ type: object
+ github_com_Tencent_WeKnora_internal_types.GraphSearchResult:
+ properties:
+ entities:
+ items:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchEntity'
+ type: array
+ knowledge_base_id:
+ type: string
+ meta:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchMeta'
+ query:
+ type: string
+ relationships:
+ items:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchRelation'
+ type: array
+ source_chunks:
+ items:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchSourceChunk'
+ type: array
+ type: object
+ github_com_Tencent_WeKnora_internal_types.GraphSearchSourceChunk:
+ properties:
+ chunk_index:
+ type: integer
+ content:
+ type: string
+ content_truncated:
+ type: boolean
+ end_at:
+ type: integer
+ id:
+ type: string
+ knowledge_id:
+ type: string
+ start_at:
+ type: integer
+ title:
+ type: string
+ title_truncated:
+ type: boolean
+ type: object
github_com_Tencent_WeKnora_internal_types.History:
properties:
answer:
@@ -17748,6 +17861,77 @@ paths:
summary: 搜索FAQ
tags:
- FAQ管理
+ /knowledge-bases/{id}/graph-search:
+ post:
+ consumes:
+ - application/json
+ description: 对单个授权知识库按实体名进行区分大小写的子串查询,返回实体、定向关系及仍然有效的来源分块。不调用模型,不影响默认检索。0 表示使用默认上限。
+ parameters:
+ - description: 知识库ID
+ in: path
+ name: id
+ required: true
+ type: string
+ - description: 共享智能体 ID
+ in: query
+ name: agent_id
+ type: string
+ - description: 共享智能体来源空间
+ in: query
+ name: agent_source_tenant_id
+ type: integer
+ - description: 查询及结果上限
+ in: body
+ name: request
+ required: true
+ schema:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchRequest'
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: OK
+ schema:
+ allOf:
+ - $ref: '#/definitions/internal_handler.DataResponse'
+ - properties:
+ data:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchResult'
+ type: object
+ "400":
+ description: 参数错误
+ schema:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+ "401":
+ description: 未登录
+ schema:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+ "403":
+ description: 无权访问知识库
+ schema:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+ "404":
+ description: 知识库不存在
+ schema:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+ "409":
+ description: 知识图谱未启用
+ schema:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+ "500":
+ description: 来源校验失败
+ schema:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+ "503":
+ description: 图谱服务不可用
+ schema:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+ security:
+ - Bearer: []
+ - ApiKeyAuth: []
+ summary: 查询知识图谱
+ tags:
+ - 知识库
/knowledge-bases/{id}/hybrid-search:
get:
consumes:
diff --git a/docs/swagger_contract_test.go b/docs/swagger_contract_test.go
index 1be752cfa..fcf5816aa 100644
--- a/docs/swagger_contract_test.go
+++ b/docs/swagger_contract_test.go
@@ -113,6 +113,46 @@ func TestReleaseAPIContracts(t *testing.T) {
}
}
+func TestGraphSearchContract(t *testing.T) {
+ for _, tt := range swaggerDocuments() {
+ t.Run(tt.name, func(t *testing.T) {
+ var spec struct {
+ Paths map[string]map[string]any `json:"paths" yaml:"paths"`
+ Definitions map[string]struct {
+ Properties map[string]any `json:"properties" yaml:"properties"`
+ } `json:"definitions" yaml:"definitions"`
+ }
+ if err := tt.parse(tt.loadSpec(t), &spec); err != nil {
+ t.Fatal(err)
+ }
+ methods := spec.Paths["/knowledge-bases/{id}/graph-search"]
+ if methods["post"] == nil || len(methods) != 1 {
+ t.Fatal("graph-search must be documented as a POST-only endpoint")
+ }
+ const prefix = "github_com_Tencent_WeKnora_internal_types."
+ for definition, fields := range map[string][]string{
+ "GraphSearchResult": {"entities", "relationships", "source_chunks", "meta"},
+ "GraphSearchEntity": {"id", "knowledge_id", "source_chunk_ids"},
+ "GraphSearchRelation": {"source_id", "target_id", "source_chunk_ids"},
+ "GraphSearchSourceChunk": {"content_truncated", "title_truncated"},
+ "GraphSearchMeta": {"truncated", "truncation_reasons"},
+ } {
+ properties := spec.Definitions[prefix+definition].Properties
+ for _, field := range fields {
+ if properties[field] == nil {
+ t.Errorf("%s.%s must be documented", definition, field)
+ }
+ }
+ for _, hidden := range []string{"tenant_id", "knowledge_base_id", "element_id"} {
+ if definition != "GraphSearchResult" && properties[hidden] != nil {
+ t.Errorf("%s leaks internal field %s", definition, hidden)
+ }
+ }
+ }
+ })
+ }
+}
+
func TestModelDeleteUsageContract(t *testing.T) {
for _, tt := range swaggerDocuments() {
t.Run(tt.name, func(t *testing.T) {
diff --git a/internal/application/repository/graph_search.go b/internal/application/repository/graph_search.go
new file mode 100644
index 000000000..5b951c9ff
--- /dev/null
+++ b/internal/application/repository/graph_search.go
@@ -0,0 +1,63 @@
+package repository
+
+import (
+ "context"
+ "fmt"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+ "gorm.io/gorm"
+)
+
+type graphSearchEvidenceRepository struct {
+ db *gorm.DB
+}
+
+// NewGraphSearchEvidenceRepository constructs the scoped live-source projection.
+func NewGraphSearchEvidenceRepository(db *gorm.DB) interfaces.GraphSearchEvidenceRepository {
+ return &graphSearchEvidenceRepository{db: db}
+}
+
+func (r *graphSearchEvidenceRepository) GetGraphSourceChunks(
+ ctx context.Context, tenantID uint64, kbID string, ids []string,
+) ([]types.GraphSearchSourceChunk, error) {
+ if tenantID == 0 || kbID == "" || len(ids) > types.GraphSearchMaxEvidence {
+ return nil, fmt.Errorf("invalid graph evidence scope or budget")
+ }
+ rows := []types.GraphSearchSourceChunk{}
+ if len(ids) == 0 {
+ return rows, nil
+ }
+ // Explicit soft-delete predicates are necessary: Table/Joins do not apply
+ // the two models' GORM default scopes. SUBSTR is supported by every SQL
+ // backend; fetching one extra character detects clipping without loading
+ // unbounded content or doing a second, racy metadata-to-content lookup.
+ err := r.db.WithContext(ctx).Table("chunks AS c").
+ Select(`c.id, c.tenant_id, c.knowledge_base_id, c.knowledge_id,
+ c.chunk_index, c.start_at, c.end_at,
+ SUBSTR(c.content, 1, ?) AS content, SUBSTR(k.title, 1, 513) AS title`,
+ types.GraphSearchMaxContentRunes+1).
+ Joins(`JOIN knowledges AS k ON k.id = c.knowledge_id
+ AND k.tenant_id = c.tenant_id AND k.knowledge_base_id = c.knowledge_base_id`).
+ Where("c.tenant_id = ? AND c.knowledge_base_id = ? AND c.id IN ?", tenantID, kbID, ids).
+ Where("c.deleted_at IS NULL AND k.deleted_at IS NULL AND c.is_enabled = ?", true).
+ Where("k.enable_status = ? AND k.parse_status <> ?", "enabled", types.ParseStatusDeleting).
+ Where("(c.index_status = ? OR c.index_status = ?)", "ready", "").
+ Order("c.id").Scan(&rows).Error
+ if err != nil {
+ return nil, err
+ }
+ for i := range rows {
+ rows[i].Content, rows[i].ContentTruncated = graphSearchClip(rows[i].Content, types.GraphSearchMaxContentRunes)
+ rows[i].Title, rows[i].TitleTruncated = graphSearchClip(rows[i].Title, 512)
+ }
+ return rows, nil
+}
+
+func graphSearchClip(text string, limit int) (string, bool) {
+ runes := []rune(text) // SQL has already bounded this allocation.
+ if len(runes) > limit {
+ return string(runes[:limit]), true
+ }
+ return text, false
+}
diff --git a/internal/application/repository/graph_search_test.go b/internal/application/repository/graph_search_test.go
new file mode 100644
index 000000000..02dbfddb3
--- /dev/null
+++ b/internal/application/repository/graph_search_test.go
@@ -0,0 +1,88 @@
+package repository
+
+import (
+ "context"
+ "strings"
+ "testing"
+ "time"
+ "unicode/utf8"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+ "gorm.io/driver/sqlite"
+ "gorm.io/gorm"
+)
+
+func TestGraphSearchLiveEvidenceSQL(t *testing.T) {
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ require.NoError(t, err)
+ sqlDB, err := db.DB()
+ require.NoError(t, err)
+ t.Cleanup(func() { require.NoError(t, sqlDB.Close()) })
+ require.NoError(t, db.AutoMigrate(&types.Knowledge{}, &types.Chunk{}))
+ for _, name := range []string{
+ "live", "chunk-deleted", "doc-deleted", "chunk-disabled", "doc-disabled",
+ "deleting", "wrong-tenant", "wrong-kb", "wrong-parent", "indexing", "long",
+ } {
+ doc := &types.Knowledge{
+ ID: name, TenantID: 7, KnowledgeBaseID: "kb",
+ EnableStatus: "enabled", ParseStatus: types.ParseStatusCompleted, Title: "标题",
+ }
+ chunk := &types.Chunk{
+ ID: name, TenantID: 7, KnowledgeBaseID: "kb", KnowledgeID: name,
+ Content: "内容", IsEnabled: true, IndexStatus: "ready",
+ }
+ switch name {
+ case "chunk-deleted":
+ chunk.DeletedAt = gorm.DeletedAt{Time: time.Now(), Valid: true}
+ case "doc-deleted":
+ doc.DeletedAt = gorm.DeletedAt{Time: time.Now(), Valid: true}
+ case "chunk-disabled":
+ // GORM's default:true would rewrite false at insert; disable below.
+ case "doc-disabled":
+ doc.EnableStatus = "disabled"
+ case "deleting":
+ doc.ParseStatus = types.ParseStatusDeleting
+ case "wrong-tenant":
+ chunk.TenantID, doc.TenantID = 8, 8
+ case "wrong-kb":
+ chunk.KnowledgeBaseID, doc.KnowledgeBaseID = "other", "other"
+ case "wrong-parent":
+ doc.KnowledgeBaseID = "other"
+ case "indexing":
+ chunk.IndexStatus = "processing"
+ case "long":
+ chunk.Content = strings.Repeat("中", 2100)
+ doc.Title = strings.Repeat("题", 600)
+ }
+ require.NoError(t, db.Create(doc).Error)
+ require.NoError(t, db.Create(chunk).Error)
+ }
+ require.NoError(t, db.Model(&types.Chunk{}).Where("id = ?", "chunk-disabled").
+ UpdateColumn("is_enabled", false).Error)
+ repo := NewGraphSearchEvidenceRepository(db)
+ ids := []string{
+ "live", "chunk-deleted", "doc-deleted", "chunk-disabled", "doc-disabled",
+ "deleting", "wrong-tenant", "wrong-kb", "wrong-parent", "indexing", "missing", "long",
+ }
+ rows, err := repo.GetGraphSourceChunks(context.Background(), 7, "kb", ids)
+ require.NoError(t, err)
+ require.Len(t, rows, 2)
+ require.Equal(t, "live", rows[0].ID)
+ require.Equal(t, "内容", rows[0].Content)
+ require.False(t, rows[0].ContentTruncated)
+ require.Equal(t, "long", rows[1].ID)
+ require.Equal(t, 2000, utf8.RuneCountInString(rows[1].Content))
+ require.True(t, utf8.ValidString(rows[1].Content))
+ require.True(t, rows[1].ContentTruncated)
+ require.Equal(t, 512, utf8.RuneCountInString(rows[1].Title))
+ require.True(t, rows[1].TitleTruncated)
+ _, err = repo.GetGraphSourceChunks(context.Background(), 7, "kb", make([]string, 513))
+ require.Error(t, err)
+ _, err = repo.GetGraphSourceChunks(context.Background(), 0, "kb", []string{"live"})
+ require.Error(t, err)
+ require.NoError(t, db.Migrator().DropTable(&types.Chunk{}))
+ rows, err = repo.GetGraphSourceChunks(context.Background(), 7, "kb", []string{"live"})
+ require.Error(t, err)
+ require.Nil(t, rows, "database failure is not an empty successful search")
+}
diff --git a/internal/application/repository/retriever/neo4j/graph_search.go b/internal/application/repository/retriever/neo4j/graph_search.go
new file mode 100644
index 000000000..9d47d530c
--- /dev/null
+++ b/internal/application/repository/retriever/neo4j/graph_search.go
@@ -0,0 +1,192 @@
+// Package neo4j implements the knowledge graph storage and query adapters.
+package neo4j
+
+import (
+ "context"
+ "fmt"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+ "github.com/neo4j/neo4j-go-driver/v6/neo4j"
+)
+
+// NewGraphSearchRepository constructs the bounded public-query adapter.
+func NewGraphSearchRepository(driver neo4j.Driver) interfaces.GraphSearchRepository {
+ return &Neo4jRepository{driver: driver, nodePrefix: "ENTITY"}
+}
+
+// graphSearchProjection bounds fields before they cross Bolt. One extra item
+// (or character) lets the service report clipping instead of a false total.
+func graphSearchProjection(alias string) string {
+ return alias + ` {
+ id: elementId(` + alias + `),
+ name: substring(` + alias + `.name, 0, 513),
+ knowledge_id: substring(` + alias + `.kg, 0, 129),
+ chunks: [c IN ` + alias + `.chunks[..513] | substring(c, 0, 129)],
+ attributes: [a IN ` + alias + `.attributes[..21] | substring(a, 0, 1001)]
+ }`
+}
+
+// graphSearchLabel quotes every identifier. KB IDs are data, never Cypher,
+// including imported/legacy IDs containing punctuation or backticks.
+func (n *Neo4jRepository) graphSearchLabel(namespace types.NameSpace) (string, error) {
+ if namespace.KnowledgeBase == "" || namespace.Knowledge != "" {
+ return "", fmt.Errorf("graph search requires exactly one knowledge base")
+ }
+ labels := n.Labels(namespace)
+ for i, label := range labels {
+ labels[i] = "`" + strings.ReplaceAll(label, "`", "``") + "`"
+ }
+ return strings.Join(labels, ":"), nil
+}
+
+// SearchGraph returns ranked seed entities and a bounded one-hop neighbourhood.
+func (n *Neo4jRepository) SearchGraph(
+ ctx context.Context, namespace types.NameSpace, query string,
+) (*types.GraphSearchCandidates, error) {
+ if n.driver == nil {
+ return nil, nil // Distinguished from an available backend with no matches.
+ }
+ label, err := n.graphSearchLabel(namespace)
+ if err != nil {
+ return nil, err
+ }
+ session := n.driver.NewSession(ctx, neo4j.SessionConfig{AccessMode: neo4j.AccessModeRead})
+ defer func() {
+ if err := session.Close(ctx); err != nil {
+ logger.Warnf(ctx, "Failed to close graph query session: %v", err)
+ }
+ }()
+ value, err := session.ExecuteRead(ctx, func(tx neo4j.ManagedTransaction) (any, error) {
+ out := &types.GraphSearchCandidates{Graph: &types.GraphData{}}
+ seedResult, err := tx.Run(ctx, `
+ MATCH (n:`+label+`)
+ WHERE n.name CONTAINS $query
+ WITH n ORDER BY CASE WHEN n.name = $query THEN 0 ELSE 1 END,
+ size(n.name), n.name, n.kg, elementId(n)
+ LIMIT $probeLimit
+ RETURN `+graphSearchProjection("n")+` AS n`,
+ map[string]any{"query": query, "probeLimit": types.GraphSearchMaxSeeds + 1})
+ if err != nil {
+ return nil, err
+ }
+ seedIDs := []string{}
+ seen := map[string]bool{}
+ for seedResult.Next(ctx) {
+ if len(seedIDs) == types.GraphSearchMaxSeeds {
+ out.TruncationReasons = append(out.TruncationReasons, "candidate_seeds")
+ continue
+ }
+ node, err := decodeGraphSearchProjection(seedResult.Record(), "n")
+ if err != nil {
+ return nil, err
+ }
+ seedIDs = append(seedIDs, node.ID)
+ seen[node.ID] = true
+ out.Graph.Node = append(out.Graph.Node, node)
+ }
+ if err := seedResult.Err(); err != nil {
+ return nil, err
+ }
+ if len(seedIDs) == 0 {
+ return out, nil
+ }
+ // Keep relation-less seeds, and expand each stored edge only from its
+ // earliest seed. Target matches cannot reverse the stored direction or
+ // fill the budget twice. Both endpoints must carry the KB label.
+ rows, err := tx.Run(ctx, `
+ UNWIND range(0, size($seeds) - 1) AS seed_index
+ MATCH (n:`+label+`) WHERE elementId(n) = $seeds[seed_index]
+ MATCH (n)-[r]-(m:`+label+`)
+ WHERE NOT elementId(m) IN $seeds[0..seed_index]
+ WITH n, r, m, seed_index ORDER BY seed_index, elementId(r)
+ LIMIT $probeLimit
+ RETURN `+graphSearchProjection("n")+` AS n, `+graphSearchProjection("m")+` AS m,
+ elementId(r) AS id, elementId(startNode(r)) AS source_id,
+ elementId(endNode(r)) AS target_id, substring(type(r), 0, 129) AS type`,
+ map[string]any{"seeds": seedIDs, "probeLimit": types.GraphSearchMaxRows + 1})
+ if err != nil {
+ return nil, err
+ }
+ count := 0
+ for rows.Next(ctx) {
+ if count == types.GraphSearchMaxRows {
+ out.TruncationReasons = append(out.TruncationReasons, "candidate_relations")
+ continue
+ }
+ count++
+ for _, alias := range []string{"n", "m"} {
+ node, err := decodeGraphSearchProjection(rows.Record(), alias)
+ if err != nil {
+ return nil, err
+ }
+ if !seen[node.ID] {
+ out.Graph.Node = append(out.Graph.Node, node)
+ seen[node.ID] = true
+ }
+ }
+ relation := &types.GraphRelation{}
+ for field, dest := range map[string]*string{
+ "id": &relation.ID, "source_id": &relation.SourceID,
+ "target_id": &relation.TargetID, "type": &relation.Type,
+ } {
+ v, _, err := neo4j.GetRecordValue[string](rows.Record(), field)
+ if err != nil || v == "" {
+ return nil, fmt.Errorf("invalid graph relationship field %s", field)
+ }
+ *dest = v
+ }
+ if !seen[relation.SourceID] || !seen[relation.TargetID] {
+ return nil, fmt.Errorf("graph relationship has an unreturned endpoint")
+ }
+ out.Graph.Relation = append(out.Graph.Relation, relation)
+ }
+ if err := rows.Err(); err != nil {
+ return nil, err
+ }
+ return out, nil
+ }, neo4j.WithTxTimeout(types.GraphSearchTimeout))
+ if err != nil {
+ return nil, err
+ }
+ return value.(*types.GraphSearchCandidates), nil
+}
+
+func decodeGraphSearchProjection(record *neo4j.Record, alias string) (*types.GraphNode, error) {
+ if record == nil {
+ return nil, fmt.Errorf("nil graph search record")
+ }
+ value, ok := record.Get(alias)
+ props, isMap := value.(map[string]any)
+ if !ok || !isMap {
+ return nil, fmt.Errorf("invalid graph node projection")
+ }
+ node := &types.GraphNode{}
+ for key, dest := range map[string]*string{"id": &node.ID, "name": &node.Name, "knowledge_id": &node.KnowledgeID} {
+ value, ok := props[key].(string)
+ if !ok || value == "" {
+ return nil, fmt.Errorf("graph node has no %s", key)
+ }
+ *dest = value
+ }
+ for key, dest := range map[string]*[]string{"chunks": &node.Chunks, "attributes": &node.Attributes} {
+ *dest = []string{}
+ if props[key] == nil {
+ continue
+ }
+ values, ok := props[key].([]any)
+ if !ok {
+ return nil, fmt.Errorf("invalid graph node %s", key)
+ }
+ for _, value := range values {
+ text, ok := value.(string)
+ if !ok {
+ return nil, fmt.Errorf("invalid graph node %s item", key)
+ }
+ *dest = append(*dest, text)
+ }
+ }
+ return node, nil
+}
diff --git a/internal/application/repository/retriever/neo4j/graph_search_test.go b/internal/application/repository/retriever/neo4j/graph_search_test.go
new file mode 100644
index 000000000..2b6d4e1b3
--- /dev/null
+++ b/internal/application/repository/retriever/neo4j/graph_search_test.go
@@ -0,0 +1,169 @@
+package neo4j
+
+import (
+ "context"
+ "fmt"
+ "os"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/neo4j/neo4j-go-driver/v6/neo4j"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestGraphSearchLabelAndDisabledBackend(t *testing.T) {
+ repo := &Neo4jRepository{nodePrefix: "ENTITY"}
+ label, err := repo.graphSearchLabel(types.NameSpace{KnowledgeBase: "kb-`):MATCH (x)"})
+ require.NoError(t, err)
+ require.Equal(t, "`ENTITYkb_``):MATCH (x)`", label)
+ _, err = repo.graphSearchLabel(types.NameSpace{})
+ require.Error(t, err)
+ _, err = repo.graphSearchLabel(types.NameSpace{KnowledgeBase: "kb", Knowledge: "doc"})
+ require.Error(t, err)
+ result, err := repo.SearchGraph(context.Background(), types.NameSpace{KnowledgeBase: "kb"}, "Acme")
+ require.NoError(t, err)
+ require.Nil(t, result)
+}
+
+func TestGraphSearchProjectionValidation(t *testing.T) {
+ valid := map[string]any{
+ "id": "n", "name": "Acme", "knowledge_id": "doc",
+ "chunks": []any{"c1"}, "attributes": []any{"attr"},
+ }
+ record := &neo4j.Record{Keys: []string{"n"}, Values: []any{valid}}
+ node, err := decodeGraphSearchProjection(record, "n")
+ require.NoError(t, err)
+ require.Equal(t, []string{"c1"}, node.Chunks)
+ _, err = decodeGraphSearchProjection(nil, "n")
+ require.Error(t, err)
+ for _, key := range []string{"id", "name", "knowledge_id", "chunks", "attributes"} {
+ props := map[string]any{}
+ for k, v := range valid {
+ props[k] = v
+ }
+ props[key] = 17
+ _, err = decodeGraphSearchProjection(&neo4j.Record{Keys: []string{"n"}, Values: []any{props}}, "n")
+ require.Error(t, err, key)
+ }
+}
+
+func TestGraphSearchIntegration(t *testing.T) {
+ uri := os.Getenv("WEKNORA_NEO4J_TEST_URI")
+ if uri == "" {
+ t.Skip("set WEKNORA_NEO4J_TEST_URI to run the live public graph-query regression")
+ }
+ ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+ defer cancel()
+ driver, err := neo4j.NewDriver(uri, neo4j.NoAuth())
+ require.NoError(t, err)
+ t.Cleanup(func() { assert.NoError(t, driver.Close(context.Background())) })
+ require.NoError(t, driver.VerifyConnectivity(ctx))
+ repo := NewGraphSearchRepository(driver).(*Neo4jRepository)
+ // Exercise escaping against a real engine, not only a string assertion.
+ ns := types.NameSpace{KnowledgeBase: fmt.Sprintf("public_graph_%d_`", time.Now().UnixNano())}
+ label, err := repo.graphSearchLabel(ns)
+ require.NoError(t, err)
+ outsideLabel, err := repo.graphSearchLabel(types.NameSpace{KnowledgeBase: ns.KnowledgeBase + "_outside"})
+ require.NoError(t, err)
+ t.Cleanup(func() {
+ cleanupCtx, stop := context.WithTimeout(context.Background(), 10*time.Second)
+ defer stop()
+ _, err := neo4j.ExecuteQuery(cleanupCtx, driver, "MATCH (n:"+label+") DETACH DELETE n",
+ nil, neo4j.EagerResultTransformer)
+ assert.NoError(t, err)
+ })
+ _, err = neo4j.ExecuteQuery(ctx, driver, `
+ CREATE (a:`+label+` {name:'Acme', kg:'doc1', chunks:['c1'], attributes:['attr1']}),
+ (b:`+label+` {name:'Acme Shanghai', kg:'doc1', chunks:['c1'], attributes:[]}),
+ (a2:`+label+` {name:'Acme', kg:'doc2', chunks:['c2'], attributes:['attr2']}),
+ (b2:`+label+` {name:'Acme Shanghai', kg:'doc2', chunks:['c2'], attributes:[]}),
+ (isolated:`+label+` {name:'Isolated', kg:'doc1', chunks:['c1'], attributes:[]}),
+ (outside:`+outsideLabel+` {name:'Outside', kg:'secret', chunks:['secret']}),
+ (a)-[:HEADQUARTERED_IN]->(b), (b)-[:RELATED_TO]->(a), (a)-[:SELF]->(a),
+ (a2)-[:HAS_BRANCH_IN]->(b2), (a)-[:MUST_NOT_LEAK]->(outside)
+ `, nil, neo4j.EagerResultTransformer)
+ require.NoError(t, err)
+ t.Cleanup(func() {
+ _, err := neo4j.ExecuteQuery(context.Background(), driver,
+ "MATCH (n:"+outsideLabel+") DETACH DELETE n", nil, neo4j.EagerResultTransformer)
+ assert.NoError(t, err)
+ })
+ for _, query := range []string{"Acme", "Shanghai"} {
+ result, err := repo.SearchGraph(ctx, ns, query)
+ require.NoError(t, err)
+ require.Len(t, result.Graph.Node, 4)
+ expectedRelations := 4
+ if query == "Shanghai" {
+ expectedRelations = 3 // Self-loop is outside this one-hop neighbourhood.
+ }
+ require.Len(t, result.Graph.Relation, expectedRelations)
+ names := map[string]string{}
+ for _, node := range result.Graph.Node {
+ names[node.ID] = node.Name
+ }
+ for _, relation := range result.Graph.Relation {
+ require.NotEqual(t, "MUST_NOT_LEAK", relation.Type)
+ if relation.Type == "HEADQUARTERED_IN" {
+ require.Equal(t, "Acme", names[relation.SourceID])
+ require.Equal(t, "Acme Shanghai", names[relation.TargetID])
+ }
+ }
+ require.Empty(t, result.TruncationReasons)
+ }
+ isolated, err := repo.SearchGraph(ctx, ns, "Isolated")
+ require.NoError(t, err)
+ require.Len(t, isolated.Graph.Node, 1)
+ require.Empty(t, isolated.Graph.Relation)
+ empty, err := repo.SearchGraph(ctx, ns, "no match")
+ require.NoError(t, err)
+ require.Empty(t, empty.Graph.Node)
+ // Full query text remains a parameter, including a Cypher-looking payload.
+ empty, err = repo.SearchGraph(ctx, ns, "' RETURN 1 //")
+ require.NoError(t, err)
+ require.Empty(t, empty.Graph.Node)
+
+ t.Run("seed cap and exact-name priority", func(t *testing.T) {
+ _, err := neo4j.ExecuteQuery(ctx, driver, `
+ UNWIND range(0, 104) AS i CREATE (n:`+label+`
+ {name:'Cap '+toString(i), kg:'doc', chunks:['c1'], attributes:[]})
+ WITH count(*) AS created
+ CREATE (exact:`+label+` {name:'Cap', kg:'doc', chunks:['c1'], attributes:[]})`,
+ nil, neo4j.EagerResultTransformer)
+ require.NoError(t, err)
+ result, err := repo.SearchGraph(ctx, ns, "Cap")
+ require.NoError(t, err)
+ require.Len(t, result.Graph.Node, types.GraphSearchMaxSeeds)
+ require.Equal(t, "Cap", result.Graph.Node[0].Name)
+ require.Contains(t, result.TruncationReasons, "candidate_seeds")
+ })
+ t.Run("row cap without duplicate edge expansion", func(t *testing.T) {
+ _, err := neo4j.ExecuteQuery(ctx, driver, `
+ CREATE (hub:`+label+` {name:'Hub', kg:'doc', chunks:['c1'], attributes:[]})
+ WITH hub UNWIND range(0, 512) AS i
+ CREATE (leaf:`+label+` {name:'Leaf '+toString(i), kg:'doc', chunks:['c1'], attributes:[]}),
+ (hub)-[:CONNECTS]->(leaf)`,
+ nil, neo4j.EagerResultTransformer)
+ require.NoError(t, err)
+ result, err := repo.SearchGraph(ctx, ns, "Hub")
+ require.NoError(t, err)
+ require.Len(t, result.Graph.Relation, types.GraphSearchMaxRows)
+ require.Contains(t, result.TruncationReasons, "candidate_relations")
+ })
+ t.Run("field projections are bounded before Bolt", func(t *testing.T) {
+ _, err := neo4j.ExecuteQuery(ctx, driver, `
+ CREATE (n:`+label+` {name:'Large', kg:'doc', chunks:$chunks, attributes:$attributes})`,
+ map[string]any{
+ "chunks": strings.Split(strings.Repeat("c,", 600), ","),
+ "attributes": []string{strings.Repeat("中", 3000)},
+ }, neo4j.EagerResultTransformer)
+ require.NoError(t, err)
+ result, err := repo.SearchGraph(ctx, ns, "Large")
+ require.NoError(t, err)
+ require.Len(t, result.Graph.Node, 1)
+ require.Len(t, result.Graph.Node[0].Chunks, 513)
+ require.Len(t, []rune(result.Graph.Node[0].Attributes[0]), 1001)
+ })
+}
diff --git a/internal/application/service/graph_search.go b/internal/application/service/graph_search.go
new file mode 100644
index 000000000..fbcec51b5
--- /dev/null
+++ b/internal/application/service/graph_search.go
@@ -0,0 +1,242 @@
+package service
+
+import (
+ "context"
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "slices"
+ "unicode/utf8"
+
+ "github.com/Tencent/WeKnora/internal/application/access"
+ apperrors "github.com/Tencent/WeKnora/internal/errors"
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+)
+
+type graphSearchService struct {
+ graph interfaces.GraphSearchRepository
+ evidence interfaces.GraphSearchEvidenceRepository
+}
+
+// NewGraphSearchService constructs the public-query provenance boundary.
+func NewGraphSearchService(graph interfaces.GraphSearchRepository,
+ evidence interfaces.GraphSearchEvidenceRepository,
+) interfaces.GraphSearchService {
+ return &graphSearchService{graph: graph, evidence: evidence}
+}
+
+func (s *graphSearchService) Search(
+ ctx context.Context, kb *types.KnowledgeBase, req types.GraphSearchRequest,
+) (*types.GraphSearchResult, error) {
+ if kb == nil || !access.HasKBGrant(ctx, kb.ID, kb.TenantID, types.OrgRoleViewer) {
+ return nil, apperrors.NewForbiddenError("An explicit read grant for this knowledge base is required")
+ }
+ if scope, ok := types.TenantAPIKeyScopeFromContext(ctx); ok && !scope.FullAccess &&
+ !scope.HasCapability(types.APIKeyCapabilityRetrieve) {
+ return nil, apperrors.NewForbiddenError("The API key requires retrieve capability")
+ }
+ if err := req.Normalize(); err != nil {
+ return nil, apperrors.NewBadRequestError(err.Error())
+ }
+ if !kb.IsGraphEnabled() {
+ return nil, apperrors.NewConflictError("Knowledge graph is not enabled for this knowledge base")
+ }
+ ctx, cancel := context.WithTimeout(ctx, types.GraphSearchTimeout)
+ defer cancel()
+ candidates, err := s.graph.SearchGraph(ctx, types.NameSpace{KnowledgeBase: kb.ID}, req.Query)
+ if err != nil {
+ logger.ErrorWithFields(ctx, err, nil)
+ return nil, apperrors.NewServiceUnavailableError("Knowledge graph query is temporarily unavailable")
+ }
+ if candidates == nil || candidates.Graph == nil {
+ return nil, apperrors.NewServiceUnavailableError("Knowledge graph backend is not configured")
+ }
+ result := &types.GraphSearchResult{
+ KnowledgeBaseID: kb.ID, Query: req.Query,
+ Entities: []types.GraphSearchEntity{}, Relationships: []types.GraphSearchRelation{},
+ SourceChunks: []types.GraphSearchSourceChunk{},
+ Meta: types.GraphSearchMeta{
+ TruncationReasons: []string{}, MaxNodes: req.MaxNodes,
+ MaxRelations: req.MaxRelations, MaxSourceChunks: req.MaxSourceChunks,
+ },
+ }
+ mark := func(reason string) {
+ result.Meta.Truncated = true
+ if !slices.Contains(result.Meta.TruncationReasons, reason) {
+ result.Meta.TruncationReasons = append(result.Meta.TruncationReasons, reason)
+ }
+ }
+ for _, reason := range candidates.TruncationReasons {
+ mark(reason)
+ }
+ ids := []string{}
+ wanted := map[string]bool{}
+ eligible := map[string][]string{}
+ for _, node := range candidates.Graph.Node {
+ if node == nil || node.ID == "" || node.Name == "" || node.KnowledgeID == "" || len(node.Chunks) == 0 {
+ continue
+ }
+ if utf8.RuneCountInString(node.Name) > types.GraphSearchMaxNameRunes ||
+ len(node.KnowledgeID) > 128 || len(node.Chunks) > types.GraphSearchMaxEvidence {
+ mark("entity_fields")
+ continue
+ }
+ chunkIDs := []string{}
+ additional := []string{}
+ valid := true
+ for _, id := range node.Chunks {
+ if id == "" || len(id) > 128 {
+ valid = false
+ mark("entity_fields")
+ break
+ }
+ if !slices.Contains(chunkIDs, id) {
+ chunkIDs = append(chunkIDs, id)
+ if !wanted[id] {
+ additional = append(additional, id)
+ }
+ }
+ }
+ if !valid {
+ continue
+ }
+ if len(ids)+len(additional) > types.GraphSearchMaxEvidence {
+ mark("candidate_source_chunks")
+ continue
+ }
+ for _, id := range additional {
+ wanted[id] = true
+ ids = append(ids, id)
+ }
+ slices.Sort(chunkIDs)
+ eligible[node.ID] = chunkIDs
+ }
+ sources := map[string]types.GraphSearchSourceChunk{}
+ if len(ids) != 0 {
+ rows, err := s.evidence.GetGraphSourceChunks(ctx, kb.TenantID, kb.ID, ids)
+ if err != nil {
+ logger.ErrorWithFields(ctx, err, nil)
+ return nil, apperrors.NewInternalServerError("Failed to validate graph source chunks")
+ }
+ for _, row := range rows {
+ if wanted[row.ID] && row.TenantID == kb.TenantID && row.KnowledgeBaseID == kb.ID {
+ sources[row.ID] = row
+ }
+ }
+ }
+ // Conservative provenance: every cited chunk must still be enabled, live
+ // and in this exact document/KB. Attributes are document-level aggregates;
+ // validating just one surviving chunk could expose disabled-source facts.
+ nodes := map[string]types.GraphSearchEntity{}
+ publicIDs := map[string]bool{}
+ returnedSources := map[string]bool{}
+ for _, node := range candidates.Graph.Node {
+ if node == nil {
+ continue
+ }
+ chunkIDs, ok := eligible[node.ID]
+ if !ok {
+ continue
+ }
+ valid, extra := true, 0
+ for _, id := range chunkIDs {
+ if row, ok := sources[id]; !ok || row.KnowledgeID != node.KnowledgeID {
+ valid = false
+ break
+ }
+ if !returnedSources[id] {
+ extra++
+ }
+ }
+ if !valid {
+ continue
+ }
+ id := graphSearchPublicID("entity", kb.ID, node.KnowledgeID, node.Name)
+ if publicIDs[id] {
+ continue
+ }
+ if len(result.Entities) >= req.MaxNodes {
+ mark("max_nodes")
+ continue
+ }
+ if len(result.SourceChunks)+extra > req.MaxSourceChunks {
+ mark("max_source_chunks")
+ continue
+ }
+ attributes := []string{}
+ for i, attribute := range node.Attributes {
+ if i == types.GraphSearchMaxAttributes {
+ mark("entity_fields")
+ break
+ }
+ text := []rune(attribute)
+ if len(text) > types.GraphSearchMaxAttributeRunes {
+ attribute = string(text[:types.GraphSearchMaxAttributeRunes])
+ mark("entity_fields")
+ }
+ attributes = append(attributes, attribute)
+ }
+ entity := types.GraphSearchEntity{
+ ID: id, Name: node.Name, KnowledgeID: node.KnowledgeID,
+ Attributes: attributes, SourceChunkIDs: chunkIDs,
+ }
+ nodes[node.ID] = entity
+ publicIDs[id] = true
+ result.Entities = append(result.Entities, entity)
+ for _, id := range chunkIDs {
+ if !returnedSources[id] {
+ row := sources[id]
+ result.SourceChunks = append(result.SourceChunks, row)
+ returnedSources[id] = true
+ if row.ContentTruncated || row.TitleTruncated {
+ mark("source_fields")
+ }
+ }
+ }
+ }
+ seenRelations := map[string]bool{}
+ for _, relation := range candidates.Graph.Relation {
+ if relation == nil {
+ continue
+ }
+ source, sourceOK := nodes[relation.SourceID]
+ target, targetOK := nodes[relation.TargetID]
+ if !sourceOK || !targetOK || source.KnowledgeID != target.KnowledgeID || relation.Type == "" {
+ continue
+ }
+ if utf8.RuneCountInString(relation.Type) > 128 {
+ mark("relation_fields")
+ continue
+ }
+ id := graphSearchPublicID("relation", source.ID, target.ID, relation.Type)
+ if seenRelations[id] {
+ continue
+ }
+ seenRelations[id] = true
+ if len(result.Relationships) >= req.MaxRelations {
+ mark("max_relations")
+ continue
+ }
+ chunkIDs := append([]string{}, source.SourceChunkIDs...)
+ for _, id := range target.SourceChunkIDs {
+ if !slices.Contains(chunkIDs, id) {
+ chunkIDs = append(chunkIDs, id)
+ }
+ }
+ slices.Sort(chunkIDs)
+ result.Relationships = append(result.Relationships, types.GraphSearchRelation{
+ ID: id, SourceID: source.ID, TargetID: target.ID, Type: relation.Type, SourceChunkIDs: chunkIDs,
+ })
+ }
+ return result, nil
+}
+
+// JSON tuple encoding avoids delimiter collisions; IDs survive graph reindexing
+// and never expose Neo4j element IDs or conflate same-named document instances.
+func graphSearchPublicID(parts ...string) string {
+ data, _ := json.Marshal(parts)
+ sum := sha256.Sum256(data)
+ return hex.EncodeToString(sum[:])
+}
diff --git a/internal/application/service/graph_search_test.go b/internal/application/service/graph_search_test.go
new file mode 100644
index 000000000..d4e5c85a1
--- /dev/null
+++ b/internal/application/service/graph_search_test.go
@@ -0,0 +1,298 @@
+package service
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "strings"
+ "testing"
+ "unicode/utf8"
+
+ "github.com/Tencent/WeKnora/internal/application/access"
+ apperrors "github.com/Tencent/WeKnora/internal/errors"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+)
+
+type graphSearchStoreStub struct {
+ candidates *types.GraphSearchCandidates
+ err error
+ calls int
+ namespace types.NameSpace
+ query string
+}
+
+func (s *graphSearchStoreStub) SearchGraph(
+ _ context.Context, ns types.NameSpace, query string,
+) (*types.GraphSearchCandidates, error) {
+ s.calls++
+ s.namespace, s.query = ns, query
+ return s.candidates, s.err
+}
+
+type graphSearchEvidenceStub struct {
+ rows []types.GraphSearchSourceChunk
+ err error
+ calls int
+ tenantID uint64
+ kbID string
+ ids []string
+}
+
+func (s *graphSearchEvidenceStub) GetGraphSourceChunks(
+ _ context.Context, tenantID uint64, kbID string, ids []string,
+) ([]types.GraphSearchSourceChunk, error) {
+ s.calls++
+ s.tenantID, s.kbID, s.ids = tenantID, kbID, append([]string{}, ids...)
+ return s.rows, s.err
+}
+
+func graphSearchTestKB() *types.KnowledgeBase {
+ return &types.KnowledgeBase{
+ ID: "kb", TenantID: 7,
+ IndexingStrategy: types.IndexingStrategy{GraphEnabled: true},
+ ExtractConfig: &types.ExtractConfig{Enabled: true},
+ }
+}
+
+func graphSearchTestContext(kb *types.KnowledgeBase) context.Context {
+ grant := &access.KBAccess{
+ KnowledgeBase: kb, EffectiveTenantID: kb.TenantID,
+ Caller: types.Caller{TenantID: 1, UserID: "reader", Role: types.TenantRoleViewer},
+ Permission: types.OrgRoleViewer,
+ }
+ return grant.WithGrant(context.Background())
+}
+
+func graphSearchTestSource(id, doc string) types.GraphSearchSourceChunk {
+ return types.GraphSearchSourceChunk{
+ ID: id, KnowledgeID: doc,
+ TenantID: 7, KnowledgeBaseID: "kb", Title: doc, Content: "source " + id,
+ }
+}
+
+func TestGraphSearchPublicIdentitiesDirectionAndProvenance(t *testing.T) {
+ kb := graphSearchTestKB()
+ graph := &types.GraphData{
+ Node: []*types.GraphNode{
+ {
+ ID: "physical-a1", Name: "Acme", KnowledgeID: "doc1",
+ Chunks: []string{"c1"}, Attributes: []string{"attr1"},
+ },
+ {ID: "physical-b1", Name: "Shanghai", KnowledgeID: "doc1", Chunks: []string{"c1"}},
+ {
+ ID: "physical-a2", Name: "Acme", KnowledgeID: "doc2",
+ Chunks: []string{"c2"}, Attributes: []string{"attr2"},
+ },
+ {ID: "physical-b2", Name: "Shanghai", KnowledgeID: "doc2", Chunks: []string{"c2"}},
+ {ID: "physical-dead", Name: "Acme", KnowledgeID: "deleted", Chunks: []string{"missing"}},
+ },
+ Relation: []*types.GraphRelation{
+ {ID: "r1", SourceID: "physical-a1", TargetID: "physical-b1", Type: "HEADQUARTERED_IN"},
+ {ID: "r1-duplicate", SourceID: "physical-a1", TargetID: "physical-b1", Type: "HEADQUARTERED_IN"},
+ {ID: "r2", SourceID: "physical-b1", TargetID: "physical-a1", Type: "RELATED_TO"},
+ {ID: "r3", SourceID: "physical-a2", TargetID: "physical-b2", Type: "HAS_BRANCH_IN"},
+ {ID: "self", SourceID: "physical-a1", TargetID: "physical-a1", Type: "SELF"},
+ {ID: "dead", SourceID: "physical-dead", TargetID: "physical-b1", Type: "SECRET"},
+ {ID: "cross-document", SourceID: "physical-a1", TargetID: "physical-b2", Type: "INVALID"},
+ {Node1: "Acme", Node2: "Shanghai", Type: "NAMES_ARE_NOT_IDENTITIES"},
+ },
+ }
+ store := &graphSearchStoreStub{candidates: &types.GraphSearchCandidates{Graph: graph}}
+ evidence := &graphSearchEvidenceStub{rows: []types.GraphSearchSourceChunk{
+ graphSearchTestSource("c1", "doc1"), graphSearchTestSource("c2", "doc2"),
+ }}
+ svc := NewGraphSearchService(store, evidence)
+ result, err := svc.Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: " Acme "})
+ require.NoError(t, err)
+ require.Len(t, result.Entities, 4)
+ require.Len(t, result.Relationships, 4)
+ require.Len(t, result.SourceChunks, 2)
+ require.False(t, result.Meta.Truncated)
+ require.NotEqual(t, result.Entities[0].ID, result.Entities[2].ID, "same names in different documents stay distinct")
+ require.Equal(t, "Acme", store.query)
+ require.Equal(t, types.NameSpace{KnowledgeBase: "kb"}, store.namespace)
+ require.Equal(t, uint64(7), evidence.tenantID, "use shared KB owner, never caller/execution tenant")
+ require.Equal(t, "kb", evidence.kbID)
+ require.Equal(t, result.Entities[0].ID, result.Relationships[0].SourceID)
+ require.Equal(t, result.Entities[1].ID, result.Relationships[0].TargetID)
+ require.Equal(t, result.Entities[1].ID, result.Relationships[1].SourceID)
+ data, err := json.Marshal(result)
+ require.NoError(t, err)
+ for _, secret := range []string{"physical-", "SECRET", "INVALID", "NAMES_ARE_NOT_IDENTITIES", "tenant_id"} {
+ require.NotContains(t, string(data), secret)
+ }
+ // Reindexing changes backend IDs but not the public document-instance ID.
+ graph.Node[0].ID = "new-backend-id"
+ result2, err := svc.Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: "Acme"})
+ require.NoError(t, err)
+ require.Equal(t, result.Entities[0].ID, result2.Entities[0].ID)
+ require.NotEqual(t, graphSearchPublicID("a:b", "c"), graphSearchPublicID("a", "b:c"))
+}
+
+func TestGraphSearchRequiresEverySourceInExactDocument(t *testing.T) {
+ kb := graphSearchTestKB()
+ for name, rows := range map[string][]types.GraphSearchSourceChunk{
+ "missing or disabled second source": {graphSearchTestSource("c1", "doc")},
+ "wrong document": {
+ graphSearchTestSource("c1", "doc"), graphSearchTestSource("c2", "another"),
+ },
+ "wrong tenant": {
+ graphSearchTestSource("c1", "doc"),
+ {ID: "c2", KnowledgeID: "doc", TenantID: 8, KnowledgeBaseID: "kb"},
+ },
+ "wrong KB": {
+ graphSearchTestSource("c1", "doc"),
+ {ID: "c2", KnowledgeID: "doc", TenantID: 7, KnowledgeBaseID: "other"},
+ },
+ } {
+ t.Run(name, func(t *testing.T) {
+ store := &graphSearchStoreStub{candidates: &types.GraphSearchCandidates{Graph: &types.GraphData{
+ Node: []*types.GraphNode{
+ {
+ ID: "n", Name: "Secret", KnowledgeID: "doc", Chunks: []string{"c1", "c2"},
+ Attributes: []string{"do not expose"},
+ },
+ },
+ Relation: []*types.GraphRelation{{SourceID: "n", TargetID: "n", Type: "SECRET"}},
+ }}}
+ result, err := NewGraphSearchService(store, &graphSearchEvidenceStub{rows: rows}).
+ Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: "Secret"})
+ require.NoError(t, err)
+ require.Empty(t, result.Entities)
+ require.Empty(t, result.Relationships)
+ require.Empty(t, result.SourceChunks)
+ })
+ }
+}
+
+func TestGraphSearchAdmissionAndFailures(t *testing.T) {
+ kb := graphSearchTestKB()
+ for name, ctx := range map[string]context.Context{
+ "no grant": context.Background(),
+ "wrong resource": graphSearchTestContext(&types.KnowledgeBase{ID: "other", TenantID: 7}),
+ "wrong owner": graphSearchTestContext(&types.KnowledgeBase{ID: "kb", TenantID: 8}),
+ "narrowed key": types.WithTenantAPIKeyScope(graphSearchTestContext(kb),
+ types.TenantAPIKeyScope{KnowledgeBaseIDs: types.StringArray{"other"}}),
+ "chat-only direct caller": types.WithTenantAPIKeyScope(graphSearchTestContext(kb),
+ types.TenantAPIKeyScope{Capabilities: types.StringArray{"chat"}}),
+ "ingest-only direct caller": types.WithTenantAPIKeyScope(graphSearchTestContext(kb),
+ types.TenantAPIKeyScope{Capabilities: types.StringArray{"ingest"}}),
+ } {
+ t.Run(name, func(t *testing.T) {
+ store, evidence := &graphSearchStoreStub{}, &graphSearchEvidenceStub{}
+ result, err := NewGraphSearchService(store, evidence).Search(ctx, kb,
+ types.GraphSearchRequest{Query: "Acme"})
+ require.Nil(t, result)
+ var appErr *apperrors.AppError
+ require.ErrorAs(t, err, &appErr)
+ require.Equal(t, apperrors.ErrForbidden, appErr.Code)
+ require.Zero(t, store.calls+evidence.calls)
+ })
+ }
+ for _, legacyConfigOnly := range []bool{false, true} {
+ disabled := *kb
+ disabled.IndexingStrategy.GraphEnabled = legacyConfigOnly
+ if legacyConfigOnly {
+ disabled.ExtractConfig = &types.ExtractConfig{Enabled: false}
+ }
+ store := &graphSearchStoreStub{}
+ _, err := NewGraphSearchService(store, &graphSearchEvidenceStub{}).
+ Search(graphSearchTestContext(&disabled), &disabled, types.GraphSearchRequest{Query: "Acme"})
+ var appErr *apperrors.AppError
+ require.ErrorAs(t, err, &appErr)
+ require.Equal(t, apperrors.ErrConflict, appErr.Code)
+ require.Zero(t, store.calls)
+ }
+ for _, storeErr := range []error{nil, errors.New("backend password must not be returned")} {
+ store := &graphSearchStoreStub{err: storeErr}
+ _, err := NewGraphSearchService(store, &graphSearchEvidenceStub{}).
+ Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: "Acme"})
+ var appErr *apperrors.AppError
+ require.ErrorAs(t, err, &appErr)
+ require.Equal(t, apperrors.ErrServiceUnavailable, appErr.Code)
+ require.NotContains(t, err.Error(), "password")
+ }
+ store := &graphSearchStoreStub{candidates: &types.GraphSearchCandidates{Graph: &types.GraphData{
+ Node: []*types.GraphNode{{ID: "n", Name: "Acme", KnowledgeID: "doc", Chunks: []string{"c1"}}},
+ }}}
+ result, err := NewGraphSearchService(store, &graphSearchEvidenceStub{err: errors.New("SQL error")}).
+ Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: "Acme"})
+ require.Nil(t, result, "validation failure must not return partial graph data")
+ var appErr *apperrors.AppError
+ require.ErrorAs(t, err, &appErr)
+ require.Equal(t, apperrors.ErrInternalServer, appErr.Code)
+}
+
+func TestGraphSearchBudgetsAndClipping(t *testing.T) {
+ kb := graphSearchTestKB()
+ graph := &types.GraphData{}
+ evidence := &graphSearchEvidenceStub{}
+ for i := range 513 {
+ chunkID, nodeID := fmt.Sprintf("c%d", i), fmt.Sprintf("n%d", i)
+ graph.Node = append(graph.Node, &types.GraphNode{
+ ID: nodeID, Name: nodeID,
+ KnowledgeID: "doc", Chunks: []string{chunkID, chunkID},
+ Attributes: []string{strings.Repeat("中", 1001)},
+ })
+ evidence.rows = append(evidence.rows, graphSearchTestSource(chunkID, "doc"))
+ }
+ for i := range 3 {
+ graph.Relation = append(graph.Relation, &types.GraphRelation{
+ SourceID: "n0", TargetID: "n1", Type: fmt.Sprintf("REL%d", i),
+ })
+ }
+ store := &graphSearchStoreStub{candidates: &types.GraphSearchCandidates{
+ Graph: graph, TruncationReasons: []string{"candidate_seeds", "candidate_relations"},
+ }}
+ result, err := NewGraphSearchService(store, evidence).Search(graphSearchTestContext(kb), kb,
+ types.GraphSearchRequest{Query: "n", MaxNodes: 2, MaxSourceChunks: 2, MaxRelations: 1})
+ require.NoError(t, err)
+ require.Len(t, evidence.ids, types.GraphSearchMaxEvidence)
+ require.Len(t, result.Entities, 2)
+ require.Len(t, result.SourceChunks, 2)
+ require.Len(t, result.Relationships, 1)
+ require.True(t, result.Meta.Truncated)
+ for _, reason := range []string{
+ "candidate_seeds", "candidate_relations", "candidate_source_chunks",
+ "max_nodes", "max_relations", "entity_fields",
+ } {
+ require.Contains(t, result.Meta.TruncationReasons, reason)
+ }
+ require.Equal(t, 1000, utf8.RuneCountInString(result.Entities[0].Attributes[0]))
+ // The chunk limit must never create dangling node/relationship references.
+ result, err = NewGraphSearchService(store, evidence).Search(graphSearchTestContext(kb), kb,
+ types.GraphSearchRequest{Query: "n", MaxSourceChunks: 1})
+ require.NoError(t, err)
+ require.Len(t, result.Entities, 1)
+ require.Len(t, result.SourceChunks, 1)
+ require.Empty(t, result.Relationships)
+ require.Contains(t, result.Meta.TruncationReasons, "max_source_chunks")
+}
+
+func TestGraphSearchEmptyAndIsolatedEntity(t *testing.T) {
+ kb := graphSearchTestKB()
+ store := &graphSearchStoreStub{candidates: &types.GraphSearchCandidates{Graph: &types.GraphData{}}}
+ evidence := &graphSearchEvidenceStub{}
+ svc := NewGraphSearchService(store, evidence)
+ result, err := svc.Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: "none"})
+ require.NoError(t, err)
+ require.Zero(t, evidence.calls)
+ data, err := json.Marshal(result)
+ require.NoError(t, err)
+ for _, field := range []string{`"entities":[]`, `"relationships":[]`, `"source_chunks":[]`} {
+ require.Contains(t, string(data), field)
+ }
+ store.candidates.Graph.Node = []*types.GraphNode{
+ {ID: "isolated", Name: "Isolated", KnowledgeID: "doc", Chunks: []string{"c1"}},
+ }
+ source := graphSearchTestSource("c1", "doc")
+ source.ContentTruncated = true
+ evidence.rows = []types.GraphSearchSourceChunk{source}
+ result, err = svc.Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: "Isolated"})
+ require.NoError(t, err)
+ require.Len(t, result.Entities, 1)
+ require.Empty(t, result.Relationships)
+ require.Contains(t, result.Meta.TruncationReasons, "source_fields")
+}
diff --git a/internal/container/container.go b/internal/container/container.go
index edb2a304f..99b49b7b9 100644
--- a/internal/container/container.go
+++ b/internal/container/container.go
@@ -178,6 +178,8 @@ func BuildContainer(container *dig.Container) *dig.Container {
must(container.Provide(repository.NewSystemSettingRepository))
must(container.Provide(repository.NewModelCatalogRepository))
must(container.Provide(neo4jRepo.NewNeo4jRepository))
+ must(container.Provide(neo4jRepo.NewGraphSearchRepository))
+ must(container.Provide(repository.NewGraphSearchEvidenceRepository))
must(container.Provide(repository.NewMCPServiceRepository))
must(container.Provide(repository.NewMCPToolApprovalRepository))
must(container.Provide(repository.NewAgentPromptRepository))
@@ -240,6 +242,7 @@ func BuildContainer(container *dig.Container) *dig.Container {
must(container.Provide(service.NewAuditLogService))
must(container.Provide(service.NewAuditLogRetentionRunner))
must(container.Provide(service.NewKnowledgeBaseService))
+ must(container.Provide(service.NewGraphSearchService))
must(container.Provide(service.NewOrganizationService))
must(container.Provide(service.NewKBShareService)) // KBShareService must be registered before KnowledgeService and KnowledgeTagService
must(container.Provide(service.NewAgentShareService))
@@ -561,6 +564,7 @@ func BuildContainer(container *dig.Container) *dig.Container {
must(container.Provide(handler.NewTenantInvitationHandler))
must(container.Provide(handler.NewAuditLogHandler))
must(container.Provide(handler.NewKnowledgeBaseHandler))
+ must(container.Provide(handler.NewGraphSearchHandler))
must(container.Provide(handler.NewKnowledgeHandler))
must(container.Provide(handler.NewChunkHandler))
must(container.Provide(handler.NewFAQHandler))
diff --git a/internal/handler/graph_search.go b/internal/handler/graph_search.go
new file mode 100644
index 000000000..7aee3726a
--- /dev/null
+++ b/internal/handler/graph_search.go
@@ -0,0 +1,75 @@
+package handler
+
+import (
+ "encoding/json"
+ "io"
+ "net/http"
+
+ apperrors "github.com/Tencent/WeKnora/internal/errors"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+ "github.com/gin-gonic/gin"
+)
+
+// GraphSearchHandler exposes a read-only JSON view of one authorized KB graph.
+type GraphSearchHandler struct {
+ kbHandler *KnowledgeBaseHandler
+ service interfaces.GraphSearchService
+}
+
+// NewGraphSearchHandler reuses the standard KB access resolver.
+func NewGraphSearchHandler(kbHandler *KnowledgeBaseHandler, service interfaces.GraphSearchService) *GraphSearchHandler {
+ return &GraphSearchHandler{kbHandler: kbHandler, service: service}
+}
+
+// Search godoc
+// @Summary 查询知识图谱
+// @Description 对单个授权知识库按实体名进行区分大小写的子串查询,返回实体、定向关系及仍然有效的来源分块。不调用模型,不影响默认检索。0 表示使用默认上限。
+// @Tags 知识库
+// @Accept json
+// @Produce json
+// @Param id path string true "知识库ID"
+// @Param agent_id query string false "共享智能体 ID"
+// @Param agent_source_tenant_id query integer false "共享智能体来源空间"
+// @Param request body types.GraphSearchRequest true "查询及结果上限"
+// @Success 200 {object} handler.DataResponse{data=types.GraphSearchResult}
+// @Failure 400 {object} apperrors.AppError "参数错误"
+// @Failure 401 {object} apperrors.AppError "未登录"
+// @Failure 403 {object} apperrors.AppError "无权访问知识库"
+// @Failure 404 {object} apperrors.AppError "知识库不存在"
+// @Failure 409 {object} apperrors.AppError "知识图谱未启用"
+// @Failure 500 {object} apperrors.AppError "来源校验失败"
+// @Failure 503 {object} apperrors.AppError "图谱服务不可用"
+// @Security Bearer
+// @Security ApiKeyAuth
+// @Router /knowledge-bases/{id}/graph-search [post]
+func (h *GraphSearchHandler) Search(c *gin.Context) {
+ kb, _, _, _, err := h.kbHandler.validateAndGetKnowledgeBase(c)
+ if err != nil {
+ _ = c.Error(err)
+ return
+ }
+ c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, 8<<10)
+ decoder := json.NewDecoder(c.Request.Body)
+ decoder.DisallowUnknownFields()
+ var req types.GraphSearchRequest
+ if err := decoder.Decode(&req); err != nil {
+ _ = c.Error(apperrors.NewBadRequestError("Invalid graph query request"))
+ return
+ }
+ // Reject trailing JSON rather than silently executing only the first query.
+ if err := decoder.Decode(new(any)); err != io.EOF {
+ _ = c.Error(apperrors.NewBadRequestError("Expected one graph query object"))
+ return
+ }
+ if err := req.Normalize(); err != nil {
+ _ = c.Error(apperrors.NewBadRequestError(err.Error()))
+ return
+ }
+ result, err := h.service.Search(c.Request.Context(), kb, req)
+ if err != nil {
+ _ = c.Error(err)
+ return
+ }
+ c.JSON(http.StatusOK, gin.H{"success": true, "data": result})
+}
diff --git a/internal/handler/graph_search_test.go b/internal/handler/graph_search_test.go
new file mode 100644
index 000000000..e6c38d2d6
--- /dev/null
+++ b/internal/handler/graph_search_test.go
@@ -0,0 +1,198 @@
+package handler
+
+import (
+ "context"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/application/access"
+ "github.com/Tencent/WeKnora/internal/application/repository"
+ apperrors "github.com/Tencent/WeKnora/internal/errors"
+ "github.com/Tencent/WeKnora/internal/middleware"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+ "github.com/gin-gonic/gin"
+ "github.com/stretchr/testify/require"
+)
+
+type graphSearchHandlerServiceStub struct {
+ calls int
+ req types.GraphSearchRequest
+ kb *types.KnowledgeBase
+ grant bool
+ err error
+}
+
+func (s *graphSearchHandlerServiceStub) Search(
+ ctx context.Context, kb *types.KnowledgeBase, req types.GraphSearchRequest,
+) (*types.GraphSearchResult, error) {
+ s.calls++
+ s.req, s.kb = req, kb
+ s.grant = access.HasKBGrant(ctx, kb.ID, kb.TenantID, types.OrgRoleViewer)
+ return &types.GraphSearchResult{
+ KnowledgeBaseID: kb.ID, Query: req.Query,
+ Entities: []types.GraphSearchEntity{}, Relationships: []types.GraphSearchRelation{},
+ SourceChunks: []types.GraphSearchSourceChunk{},
+ }, s.err
+}
+
+func graphSearchHandlerRouter(
+ kbService interfaces.KnowledgeBaseService, shares interfaces.KBShareService,
+ svc interfaces.GraphSearchService, caller uint64, scope *types.TenantAPIKeyScope,
+ agents ...interfaces.AgentShareService,
+) *gin.Engine {
+ gin.SetMode(gin.TestMode)
+ r := gin.New()
+ r.Use(middleware.ErrorHandler(), func(c *gin.Context) {
+ c.Set(types.TenantIDContextKey.String(), caller)
+ c.Set(types.UserIDContextKey.String(), "reader")
+ if scope != nil {
+ c.Request = c.Request.WithContext(types.WithTenantAPIKeyScope(c.Request.Context(), *scope))
+ }
+ c.Next()
+ })
+ kbHandler := &KnowledgeBaseHandler{service: kbService, kbShareService: shares}
+ if len(agents) > 0 {
+ kbHandler.agentShareService = agents[0]
+ }
+ h := NewGraphSearchHandler(kbHandler, svc)
+ r.POST("/knowledge-bases/:id/graph-search", h.Search)
+ return r
+}
+
+func graphSearchHandlerKB(owner uint64) *stubKBOnlyService {
+ return &stubKBOnlyService{getByID: func(_ context.Context, id string) (*types.KnowledgeBase, error) {
+ return &types.KnowledgeBase{ID: id, TenantID: owner}, nil
+ }}
+}
+
+func TestGraphSearchHandlerValidation(t *testing.T) {
+ for name, body := range map[string]string{
+ "empty": "",
+ "missing query": `{}`,
+ "null root": `null`,
+ "query whitespace": `{"query":" "}`,
+ "wrong query type": `{"query":1}`,
+ "unknown field": `{"query":"Acme","tenant_id":7}`,
+ "trailing object": `{"query":"Acme"} {}`,
+ "fractional limit": `{"query":"Acme","max_nodes":1.5}`,
+ "negative limit": `{"query":"Acme","max_source_chunks":-1}`,
+ "excessive limit": `{"query":"Acme","max_relations":201}`,
+ "long query": `{"query":"` + strings.Repeat("中", 513) + `"}`,
+ "large body": `{"query":"Acme"}` + strings.Repeat(" ", 8192),
+ } {
+ t.Run(name, func(t *testing.T) {
+ svc := &graphSearchHandlerServiceStub{}
+ w := httptest.NewRecorder()
+ graphSearchHandlerRouter(graphSearchHandlerKB(1), nil, svc, 1, nil).
+ ServeHTTP(w, httptest.NewRequest(http.MethodPost,
+ "/knowledge-bases/kb/graph-search", strings.NewReader(body)))
+ require.Equal(t, http.StatusBadRequest, w.Code, w.Body.String())
+ require.Zero(t, svc.calls)
+ require.Contains(t, w.Body.String(), `"code":1000`)
+ })
+ }
+}
+
+func TestGraphSearchHandlerSharedAccessAndErrors(t *testing.T) {
+ shares := &handlerKBShareStub{}
+ svc := &graphSearchHandlerServiceStub{}
+ r := graphSearchHandlerRouter(graphSearchHandlerKB(7), shares, svc, 1, nil)
+ w := httptest.NewRecorder()
+ r.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/knowledge-bases/kb/graph-search",
+ strings.NewReader(`{"query":" Acme "}`)))
+ require.Equal(t, http.StatusOK, w.Code, w.Body.String())
+ require.True(t, svc.grant, "the service receives the exact KB read grant")
+ require.Equal(t, uint64(7), svc.kb.TenantID)
+ require.Equal(t, uint64(1), shares.caller)
+ require.Equal(t, "Acme", svc.req.Query)
+ require.Equal(t, 50, svc.req.MaxNodes)
+
+ svc.err = apperrors.NewServiceUnavailableError("graph unavailable")
+ w = httptest.NewRecorder()
+ r.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/knowledge-bases/kb/graph-search",
+ strings.NewReader(`{"query":"Acme"}`)))
+ require.Equal(t, http.StatusServiceUnavailable, w.Code)
+ require.NotContains(t, w.Body.String(), `"entities"`, "errors never expose partial results")
+}
+
+func TestGraphSearchHandlerDeniesBeforeQuery(t *testing.T) {
+ for _, tt := range []struct {
+ name string
+ caller uint64
+ scope *types.TenantAPIKeyScope
+ kbService interfaces.KnowledgeBaseService
+ status int
+ }{
+ {name: "unauthenticated", caller: 0, kbService: graphSearchHandlerKB(1), status: 401},
+ {name: "unshared KB", caller: 1, kbService: graphSearchHandlerKB(7), status: 403},
+ {
+ name: "key outside allow list", caller: 1, kbService: graphSearchHandlerKB(1), status: 403,
+ scope: &types.TenantAPIKeyScope{KnowledgeBaseIDs: types.StringArray{"other"}},
+ },
+ {
+ name: "missing KB", caller: 1, status: 404,
+ kbService: &stubKBOnlyService{getByID: func(context.Context, string) (*types.KnowledgeBase, error) {
+ return nil, repository.ErrKnowledgeBaseNotFound
+ }},
+ },
+ } {
+ t.Run(tt.name, func(t *testing.T) {
+ svc := &graphSearchHandlerServiceStub{}
+ r := graphSearchHandlerRouter(tt.kbService, nil, svc, tt.caller, tt.scope)
+ w := httptest.NewRecorder()
+ r.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/knowledge-bases/kb/graph-search",
+ strings.NewReader(`{"query":"Acme"}`)))
+ require.Equal(t, tt.status, w.Code, w.Body.String())
+ require.Zero(t, svc.calls)
+ })
+ }
+}
+
+type graphSearchAgentStub struct {
+ interfaces.AgentShareService
+ config types.CustomAgentConfig
+ owner uint64
+}
+
+func (s *graphSearchAgentStub) GetSharedAgentForTenant(
+ context.Context, uint64, types.TenantRole, string, ...uint64,
+) (*types.CustomAgent, error) {
+ return &types.CustomAgent{ID: "shared", TenantID: s.owner, Config: s.config}, nil
+}
+
+func TestGraphSearchHandlerSharedAgentScope(t *testing.T) {
+ for _, tt := range []struct {
+ name, mode string
+ kbs []string
+ owner uint64
+ status int
+ }{
+ {"selected KB", "selected", []string{"kb"}, 7, 200},
+ {"none is not all", "none", nil, 7, 403},
+ {"empty selected is not all", "selected", nil, 7, 403},
+ {"another selection", "selected", []string{"other"}, 7, 403},
+ {"all in another owner", "all", nil, 8, 403},
+ } {
+ t.Run(tt.name, func(t *testing.T) {
+ svc := &graphSearchHandlerServiceStub{}
+ agent := &graphSearchAgentStub{
+ owner: tt.owner,
+ config: types.CustomAgentConfig{KBSelectionMode: tt.mode, KnowledgeBases: tt.kbs},
+ }
+ r := graphSearchHandlerRouter(graphSearchHandlerKB(7), nil, svc, 1, nil, agent)
+ w := httptest.NewRecorder()
+ r.ServeHTTP(w, httptest.NewRequest(http.MethodPost,
+ "/knowledge-bases/kb/graph-search?agent_id=shared", strings.NewReader(`{"query":"Acme"}`)))
+ require.Equal(t, tt.status, w.Code, w.Body.String())
+ if tt.status == http.StatusOK {
+ require.Equal(t, 1, svc.calls)
+ require.True(t, svc.grant)
+ } else {
+ require.Zero(t, svc.calls)
+ }
+ })
+ }
+}
diff --git a/internal/router/router.go b/internal/router/router.go
index d2545215d..29f37d3b1 100644
--- a/internal/router/router.go
+++ b/internal/router/router.go
@@ -44,6 +44,7 @@ type RouterParams struct {
KBShareService interfaces.KBShareService
AgentShareService interfaces.AgentShareService
KBHandler *handler.KnowledgeBaseHandler
+ GraphSearchHandler *handler.GraphSearchHandler
KnowledgeHandler *handler.KnowledgeHandler
TenantHandler *handler.TenantHandler
TenantService interfaces.TenantService
@@ -296,6 +297,7 @@ func NewRouter(params RouterParams) *gin.Engine {
)
RegisterKnowledgeTagRoutes(v1, params.TagHandler, rbacGuards)
RegisterKnowledgeRoutes(v1, params.KnowledgeHandler, rbacGuards)
+ RegisterGraphSearchRoutes(v1, params.GraphSearchHandler, rbacGuards)
RegisterFAQRoutes(v1, params.FAQHandler, rbacGuards)
RegisterChunkRoutes(v1, params.ChunkHandler, rbacGuards)
RegisterSessionRoutes(v1, params.SessionHandler, params.MessageSuggestionHandler, rbacGuards)
diff --git a/internal/router/routes_graph.go b/internal/router/routes_graph.go
new file mode 100644
index 000000000..f81729e77
--- /dev/null
+++ b/internal/router/routes_graph.go
@@ -0,0 +1,18 @@
+package router
+
+import (
+ "net/http"
+
+ "github.com/Tencent/WeKnora/internal/handler"
+ "github.com/gin-gonic/gin"
+)
+
+// RegisterGraphSearchRoutes is a read-only KB content route, even though the
+// query is POSTed. Role, API-key capability and exact KB grant are independent.
+func RegisterGraphSearchRoutes(r *gin.RouterGroup, h *handler.GraphSearchHandler, g *rbacGuards) {
+ if h == nil {
+ return
+ }
+ g.apiKeyRoute(r, http.MethodPost, "/knowledge-bases/:id/graph-search",
+ apiKeyRetrieve(apiKeyFullAccess()), g.Viewer(), g.KBAccessRead("id"), h.Search)
+}
diff --git a/internal/router/routes_graph_test.go b/internal/router/routes_graph_test.go
new file mode 100644
index 000000000..e876ebb8a
--- /dev/null
+++ b/internal/router/routes_graph_test.go
@@ -0,0 +1,27 @@
+package router
+
+import (
+ "net/http"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/handler"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/gin-gonic/gin"
+ "github.com/stretchr/testify/require"
+)
+
+func TestGraphSearchRouteCapability(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ g := &rbacGuards{}
+ r := gin.New()
+ RegisterGraphSearchRoutes(r.Group("/api/v1"), &handler.GraphSearchHandler{}, g)
+ g.assertAPIKeyPoliciesMatchRoutes(r)
+ policy := mustLookupAPIKeyPolicy(t, g, http.MethodPost, "/api/v1/knowledge-bases/:id/graph-search")
+ require.True(t, policy.RequireFullAccess)
+ require.True(t, policyHasCapability(policy, types.APIKeyCapabilityRetrieve))
+ require.False(t, policyHasCapability(policy, types.APIKeyCapabilityChat))
+ require.False(t, policyHasCapability(policy, types.APIKeyCapabilityIngest))
+ require.False(t, policyHasCapability(policy, types.APIKeyCapabilityManageKnowledgeBases))
+ require.Len(t, r.Routes(), 1)
+ require.Equal(t, http.MethodPost, r.Routes()[0].Method)
+}
diff --git a/internal/types/graph_search.go b/internal/types/graph_search.go
new file mode 100644
index 000000000..e930e39d5
--- /dev/null
+++ b/internal/types/graph_search.go
@@ -0,0 +1,114 @@
+package types
+
+import (
+ "fmt"
+ "strings"
+ "time"
+ "unicode/utf8"
+)
+
+// Internal candidate budgets are independent of the caller's response limits.
+const (
+ GraphSearchMaxSeeds = 100
+ GraphSearchMaxRows = 512
+ GraphSearchMaxEvidence = 512
+ GraphSearchMaxNameRunes = 512
+ GraphSearchMaxAttributeRunes = 1000
+ GraphSearchMaxAttributes = 20
+ GraphSearchMaxContentRunes = 2000
+ GraphSearchTimeout = 10 * time.Second
+)
+
+// GraphSearchRequest matches a case-sensitive entity-name substring. It does
+// not run a model, generate embeddings or change the regular retrieval pipeline.
+type GraphSearchRequest struct {
+ Query string `json:"query" binding:"required" minLength:"1" maxLength:"512"`
+ MaxNodes int `json:"max_nodes" minimum:"0" maximum:"100" default:"50"`
+ MaxRelations int `json:"max_relations" minimum:"0" maximum:"200" default:"100"`
+ MaxSourceChunks int `json:"max_source_chunks" minimum:"0" maximum:"50" default:"20"`
+}
+
+// Normalize validates both HTTP and direct service callers. Zero means default.
+func (r *GraphSearchRequest) Normalize() error {
+ r.Query = strings.TrimSpace(r.Query)
+ if r.Query == "" || !utf8.ValidString(r.Query) || utf8.RuneCountInString(r.Query) > GraphSearchMaxNameRunes {
+ return fmt.Errorf("query must contain 1 to %d characters", GraphSearchMaxNameRunes)
+ }
+ for _, limit := range []struct {
+ name string
+ value *int
+ defaultValue, maximum int
+ }{
+ {"max_nodes", &r.MaxNodes, 50, 100},
+ {"max_relations", &r.MaxRelations, 100, 200},
+ {"max_source_chunks", &r.MaxSourceChunks, 20, 50},
+ } {
+ if *limit.value < 0 || *limit.value > limit.maximum {
+ return fmt.Errorf("%s must be between 1 and %d, or 0 for the default", limit.name, limit.maximum)
+ }
+ if *limit.value == 0 {
+ *limit.value = limit.defaultValue
+ }
+ }
+ return nil
+}
+
+// GraphSearchCandidates is internal: physical graph identities never cross the
+// public API boundary. Truncation reports candidate caps, not an invented total.
+type GraphSearchCandidates struct {
+ Graph *GraphData
+ TruncationReasons []string
+}
+
+// GraphSearchEntity identifies an entity instance within a live document.
+type GraphSearchEntity struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ KnowledgeID string `json:"knowledge_id"`
+ Attributes []string `json:"attributes"`
+ SourceChunkIDs []string `json:"source_chunk_ids"`
+}
+
+// GraphSearchRelation connects two returned, same-document entities.
+type GraphSearchRelation struct {
+ ID string `json:"id"`
+ SourceID string `json:"source_id"`
+ TargetID string `json:"target_id"`
+ Type string `json:"type"`
+ SourceChunkIDs []string `json:"source_chunk_ids"`
+}
+
+// GraphSearchSourceChunk is a bounded, live SQL projection, not a raw Chunk or
+// Knowledge row. It excludes file paths, metadata, image URLs and owner details.
+type GraphSearchSourceChunk struct {
+ ID string `json:"id"`
+ KnowledgeID string `json:"knowledge_id"`
+ Title string `json:"title"`
+ Content string `json:"content"`
+ ChunkIndex int `json:"chunk_index"`
+ StartAt int `json:"start_at"`
+ EndAt int `json:"end_at"`
+ ContentTruncated bool `json:"content_truncated" gorm:"-"`
+ TitleTruncated bool `json:"title_truncated" gorm:"-"`
+ TenantID uint64 `json:"-"`
+ KnowledgeBaseID string `json:"-"`
+}
+
+// GraphSearchMeta reports effective limits and observed clipping, not totals.
+type GraphSearchMeta struct {
+ Truncated bool `json:"truncated"`
+ TruncationReasons []string `json:"truncation_reasons"`
+ MaxNodes int `json:"max_nodes"`
+ MaxRelations int `json:"max_relations"`
+ MaxSourceChunks int `json:"max_source_chunks"`
+}
+
+// GraphSearchResult is the stable public JSON contract, separate from GraphData.
+type GraphSearchResult struct {
+ KnowledgeBaseID string `json:"knowledge_base_id"`
+ Query string `json:"query"`
+ Entities []GraphSearchEntity `json:"entities"`
+ Relationships []GraphSearchRelation `json:"relationships"`
+ SourceChunks []GraphSearchSourceChunk `json:"source_chunks"`
+ Meta GraphSearchMeta `json:"meta"`
+}
diff --git a/internal/types/graph_search_test.go b/internal/types/graph_search_test.go
new file mode 100644
index 000000000..56b96bf67
--- /dev/null
+++ b/internal/types/graph_search_test.go
@@ -0,0 +1,36 @@
+package types
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestGraphSearchRequestNormalize(t *testing.T) {
+ req := GraphSearchRequest{Query: " 腾讯 "}
+ require.NoError(t, req.Normalize())
+ require.Equal(t, "腾讯", req.Query)
+ require.Equal(t, 50, req.MaxNodes)
+ require.Equal(t, 100, req.MaxRelations)
+ require.Equal(t, 20, req.MaxSourceChunks)
+ for _, req := range []GraphSearchRequest{
+ {Query: ""},
+ {Query: "\n\t"},
+ {Query: strings.Repeat("中", 513)},
+ {Query: string([]byte{0xff})},
+ {Query: "Acme", MaxNodes: -1},
+ {Query: "Acme", MaxNodes: 101},
+ {Query: "Acme", MaxRelations: -1},
+ {Query: "Acme", MaxRelations: 201},
+ {Query: "Acme", MaxSourceChunks: -1},
+ {Query: "Acme", MaxSourceChunks: 51},
+ } {
+ require.Error(t, req.Normalize(), "%+v", req)
+ }
+ req = GraphSearchRequest{
+ Query: strings.Repeat("中", 512),
+ MaxNodes: 100, MaxRelations: 200, MaxSourceChunks: 50,
+ }
+ require.NoError(t, req.Normalize())
+}
diff --git a/internal/types/interfaces/graph_search.go b/internal/types/interfaces/graph_search.go
new file mode 100644
index 000000000..7617f3062
--- /dev/null
+++ b/internal/types/interfaces/graph_search.go
@@ -0,0 +1,25 @@
+package interfaces
+
+import (
+ "context"
+
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// GraphSearchRepository is separate from the agent retrieval contract: the
+// public API needs isolated entities, bounded fields and explicit cap metadata.
+type GraphSearchRepository interface {
+ SearchGraph(context.Context, types.NameSpace, string) (*types.GraphSearchCandidates, error)
+}
+
+// GraphSearchEvidenceRepository reads validated, bounded source content.
+type GraphSearchEvidenceRepository interface {
+ // GetGraphSourceChunks joins live chunks/documents in exactly one owner
+ // tenant and KB, projecting bounded text in the same SQL read as validation.
+ GetGraphSourceChunks(context.Context, uint64, string, []string) ([]types.GraphSearchSourceChunk, error)
+}
+
+// GraphSearchService requires an exact KB grant before any graph/database read.
+type GraphSearchService interface {
+ Search(context.Context, *types.KnowledgeBase, types.GraphSearchRequest) (*types.GraphSearchResult, error)
+}
diff --git a/website-docs/03-features/09-knowledge-graph.md b/website-docs/03-features/09-knowledge-graph.md
index 07f28514b..0c759bf1f 100644
--- a/website-docs/03-features/09-knowledge-graph.md
+++ b/website-docs/03-features/09-knowledge-graph.md
@@ -21,7 +21,7 @@
| `NEO4J_USERNAME` | string | `neo4j` | 用户名 |
| `NEO4J_PASSWORD` | string | `password` | 密码 |
-`initNeo4jClient` 启动时最多重试 30 次(间隔 2s)建立并验证连接;未启用时返回 `nil` driver,此时 `Neo4jRepository` 的所有方法降级为 no-op(日志 `NOT SUPPORT RETRIEVE GRAPH`)。`GET /system` 信息接口通过 `getGraphDatabaseEngine()` 报告 `"Neo4j"` 或 `"Not Enabled"`(`internal/handler/system.go`)。
+`initNeo4jClient` 启动时最多重试 30 次(间隔 2s)建立并验证连接;未启用时返回 `nil` driver,此时原有构建、删除及内部 `SearchNode` 路径降级为 no-op(日志 `NOT SUPPORT RETRIEVE GRAPH`)。独立公共查询接口则明确返回 503,不把未配置后端伪装成“没有匹配”。`GET /system` 信息接口通过 `getGraphDatabaseEngine()` 报告 `"Neo4j"` 或 `"Not Enabled"`(`internal/handler/system.go`)。
docker-compose 的 `neo4j` 服务预装 APOC:`NEO4JLABS_PLUGINS=["apoc"]`(图谱写入依赖 `apoc.merge.node` / `apoc.merge.relationship`,删除依赖 `apoc.periodic.iterate`)。
@@ -131,6 +131,12 @@ SET node.chunks = apoc.coll.union(node.chunks, row.chunks)
Agent 模式则提供 `query_knowledge_graph` 工具(`internal/agent/tools/query_knowledge_graph.go`):校验各知识库是否配置了图谱(`ExtractConfig.Nodes/Relations` 非空),并发对多库执行检索、按 chunk 去重排序,输出中附带各库的图谱配置状态(实体类型 / 关系类型清单);未配置图谱的库回落为普通混合检索结果。该工具的能力要求是 `all_of: [graph]`,并且只有当 Agent 作用域内存在启用图谱的知识库时才会提供给模型——`agent_service.go` 装配工具白名单时会把它从没有图谱库的作用域中移除,避免模型反复调用一个只能返回退化结果的工具。
+## 独立 JSON 查询
+
+外部应用可使用 `POST /api/v1/knowledge-bases/{id}/graph-search`,按区分大小写的实体名子串读取实体、定向关系及有效来源分块。它是单 KB 的只读接口,不调用模型、不修改默认问答/检索管线,亦不是可执行任意 Cypher 的入口。
+
+该接口使用独立的有界读取契约:保留无关系实体,返回结果/候选/字段截断标记,并在输出属性与关系前验证完整来源。删除或禁用任一引用分块会使相关实体与关系被保守省略。权限、请求参数、响应字段和上限见 [graph-search API](../04-api/02-api-knowledge.md#graph-search)。
+
## 流程图
### 构建流程
@@ -168,5 +174,5 @@ flowchart TD
## 可视化
- **Mermaid 图生成**:`internal/application/service/graph.go` 的 `graphBuilder` 是 `types.GraphBuilder` 接口的内存版实现(LLM 抽实体 → 抽关系 → PMI×0.6 + Strength×0.4 计算关系权重并归一到 1-10 → 计算实体度数 → 构建 chunk 关联图),其 `generateKnowledgeGraphDiagram` 用 DFS 找连通分量并输出 Mermaid `graph TD` 子图(高频实体高亮、强度 >7 的关系用粗箭头)。注意:`NewGraphBuilder` 目前没有被容器装配调用(仓库内无其他引用),属于独立/遗留的图构建与可视化实现;生成的 Mermaid 图输出到日志。
-- **对外 API**:知识图谱本身没有专门的可视化 REST 端点;`query_knowledge_graph` 工具的结构化输出(`graph_configs`、结果列表)供 Agent 前端渲染。`GET /wiki/graph`(`wikiHandler.GetGraph`)是 Wiki 功能自己的图接口,与本文的实体关系图谱无关。
+- **对外 API**:`POST /knowledge-bases/{id}/graph-search` 提供独立 JSON 数据,可用于外部可视化,不包含新的内置可视化页面;`query_knowledge_graph` 仍是 Agent 自己的工具输出。`GET /wiki/graph`(`wikiHandler.GetGraph`)是 Wiki 功能自己的图接口,与本文的实体关系图谱无关。
- **prompt 模板**:`config/prompt_templates/graph_extraction.yaml` 提供 `default_extract_entities` 等模板(实体类型枚举 Person/Organization/Location/... 与 JSON 输出协议),经 `internal/config/config.go` 的 `extract_entities_prompt_id` / `extract_relationships_prompt_id` 解析进 `Conversation.ExtractEntitiesPrompt` / `ExtractRelationshipsPrompt`,供上述内存版 `graphBuilder` 使用;生产异步抽取路径使用的是 `config.yaml` 中 `extract.extract_graph` / `extract.extract_entity` 模板(`ExtractManagerConfig`)。
diff --git a/website-docs/04-api/02-api-knowledge.md b/website-docs/04-api/02-api-knowledge.md
index a0fcad45f..236955659 100644
--- a/website-docs/04-api/02-api-knowledge.md
+++ b/website-docs/04-api/02-api-knowledge.md
@@ -37,6 +37,45 @@ curl -X POST $BASE/api/v1/knowledge-bases -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"产品文档","type":"document"}'
```
+### POST /api/v1/knowledge-bases/:id/graph-search {#graph-search}
+
+独立的只读 JSON 图谱查询。按 `query` 对实体名称做**区分大小写的子串匹配**,返回匹配实体、其一跳邻居、定向关系和来源分块;也返回没有关系的匹配实体。无需把 Agent 对话输出重新解析成结构化数据。
+
+权限:Viewer+ 且对该 KB 有 read 权限(自有、组织共享或共享 Agent)。API key 需 `retrieve`/full,并受 KB 白名单约束。共享 Agent 可带 `agent_id` / `agent_source_tenant_id`,授权规则与 KB 详情一致。
+
+本接口不调用 Chat、Embedding 或 Rerank 模型,不修改数据,也不改变 `knowledge-search` / `hybrid-search` 的默认行为。自然语言实体抽取、跨库搜索、多跳遍历不在此接口范围内。
+
+| JSON 字段 | 默认值 | 上限 / 含义 |
+| --- | --- | --- |
+| `query` | 必填 | 去除首尾空白后 1–512 字符;不是 Cypher |
+| `max_nodes` | 50 | 100,包含匹配实体和邻居 |
+| `max_relations` | 100 | 200 |
+| `max_source_chunks` | 20 | 50,来源按 ID 去重 |
+
+上限字段 `0` 使用默认值;负数或超过上限返回 400。请求体最多 8 KiB,仅接收一个 JSON 对象,未知字段会被拒绝。
+
+```bash
+curl -X POST "$BASE/api/v1/knowledge-bases/$KB_ID/graph-search" \
+ -H "X-API-Key: $API_KEY" -H 'Content-Type: application/json' \
+ -d '{"query":"Acme","max_nodes":50,"max_relations":100,"max_source_chunks":20}'
+```
+
+响应:200 `{"success":true,"data":{...}}`。`data` 字段:
+
+- `knowledge_base_id`、`query`:本次作用域和规范化查询。
+- `entities`:`id`、`name`、`knowledge_id`、`attributes`、`source_chunk_ids`。ID 是不透明的文档实体身份,不暴露 Neo4j element ID;同名但不同文档的实体不会合并。名称/所属文档不变时,重建图存储不会改变公共 ID。
+- `relationships`:`id`、`source_id`、`target_id`、`type`、`source_chunk_ids`。方向为存储方向,不随查询命中哪一端而反转;两端必须实际出现在 `entities`。来源列表是两端实体来源的并集,不表示每个分块都直接陈述该关系。
+- `source_chunks`:`id`、`knowledge_id`、`title`、`content`、`chunk_index`、`start_at`、`end_at`、`content_truncated`、`title_truncated`。正文最多 2000 字符,标题最多 512 字符;截断时保留原始位置字段,不伪装成完整正文。无匹配结果时三个列表均为 `[]`。
+- `meta`:`truncated`、`truncation_reasons` 和本次生效的三个上限。它不是全图总量统计,也不提供分页游标;需要更完整的结果时应缩小实体名范围。
+
+为限制模糊查询成本,内部最多检查 100 个名称匹配种子、512 条一跳关系和 512 个来源分块;查询执行最多 10 秒。候选种子按名称完全匹配优先、名称长度、名称、文档身份排序。属性最多 20 项,每项最多 1000 字符。
+
+`truncation_reasons` 的值包括 `candidate_seeds`、`candidate_relations`、`candidate_source_chunks`、`max_nodes`、`max_relations`、`max_source_chunks`、`entity_fields`、`relation_fields`、`source_fields`。只有实际触达的上限才标注,不推测被省略结果的精确数量。
+
+来源校验采用保守规则:实体引用的**所有**分块都必须属于当前授权 KB 的该文档,且文档/分块未删除、未禁用,文档不在删除中、分块当前索引就绪;任一来源失效即省略该实体及相关关系。关系两端还必须属于同一文档。无法校验或因预算未检查的图谱事实不会作为已验证结果返回。这可能降低部分旧图谱的召回率;查询不会自动重建图谱,也不能保证模型抽取的事实本身正确。
+
+状态:400 参数错误;401 未认证;403 无读取权限/超出 key 范围;404 KB 不存在;409 KB 未开启图谱;500 来源数据库校验失败;503 图谱未配置、连接失败或查询超时。错误不附带部分图谱结果。部署配置见[知识图谱](../03-features/09-knowledge-graph.md)。
+
### 自动标签与 AI 描述配置
创建知识库时 `auto_tag_config`、`profile_config` 位于顶层;更新时放在 `config.auto_tag_config`、`config.profile_config`。两者仅 document 知识库支持,默认 enabled=false。