docs(swagger): document the real request and response types (#4304)

* docs(swagger): add shared response envelope types

* docs(swagger): type knowledge base responses

* docs(swagger): add concrete response body types

* docs(swagger): type chunk list responses

* docs(swagger): type knowledge mutation responses

* docs(swagger): type wiki search and autofix responses

* docs(swagger): type FAQ responses

* docs(swagger): type tag responses

* docs(swagger): type message responses and SSE schemas

* docs(swagger): type agent responses

* docs(swagger): type remaining handler responses

* docs(swagger): regenerate OpenAPI spec

* docs(swagger): type knowledge, activity and wiki maintenance endpoints

Covers the endpoints left out of the earlier passes: knowledge base
detail, document list/detail/spans/reparse/cancel/delete, knowledge
base activity and the Wiki stats, issues, lint and rebuild-links
endpoints. The spans handler now writes the documented structs instead
of gin.H, so the schema cannot drift from the body; the JSON is
unchanged. List filters gain their real enums and bounds, including
the finalizing, cancelled and deleting parse states.

* docs(swagger): document JSON-valued fields as JSON, not byte arrays

types.JSON and json.RawMessage are byte slices, so swag rendered every
metadata, details and config field as an array of integers. A swag
overrides file documents them as objects; the four fields that hold
arrays (relation chunk ids, allowed origins, image refs) say so with a
swaggertype tag.

* chore(lint): exempt swag annotation lines from the line-length limit

swag reads each @Param, @Success and @Failure as a single line, so an
enum list or a composed response type cannot be wrapped to fit.

* chore(lint): exempt struct tags carrying swag attributes from the line limit

Struct tags cannot wrap either; a field documented with swaggertype or
extensions keeps its tags on the declaration line.
main
lyingbug 2026-10-15 01:41:42 +08:00 committed by GitHub
parent a77d83fe0e
commit 234aa948db
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
54 changed files with 22195 additions and 1949 deletions

View File

@ -12,6 +12,12 @@ linters:
paths:
# swag embeds OpenAPI as single-line JSON strings; line-length is not meaningful.
- docs/docs\.go$
rules:
# swag annotations and struct tags cannot wrap, so a parameter with its
# enum list, a composed response type or a field's swag tags have to
# stay on one line.
- linters: [lll]
source: '^\s*// @(Param|Success|Failure|x-)|(swaggertype|extensions):"'
formatters:
enable:
- gofmt

View File

@ -257,7 +257,7 @@ migrate-goto:
docs:
@echo "生成 Swagger API 文档..."
swag init -g $(MAIN_PATH)/main.go -o ./docs --parseDependency --parseInternal \
--exclude ./internal/localsandbox
--exclude ./internal/localsandbox --overridesFile ./docs/swag.overrides
@echo "文档已生成到 ./docs 目录"
@echo "启动服务后访问 http://localhost:8080/swagger/index.html 查看文档"

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,4 @@
// JSON wrappers are byte slices in Go; document them as JSON objects. Fields
// holding arrays override this with a swaggertype tag.
replace github.com/Tencent/WeKnora/internal/types.JSON object
replace encoding/json.RawMessage object

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@ -29,9 +29,10 @@ func NewAuditLogHandler(auditService interfaces.AuditLogService) *AuditLogHandle
// auditLogListResponse is the response envelope for ListTenantAuditLog. The
// cursor is the integer id of the last entry, or 0 if no more rows remain.
type auditLogListResponse struct {
Success bool `json:"success"`
Data []*types.AuditLog `json:"data"`
NextCursor uint64 `json:"next_cursor"`
Success bool `json:"success"`
Data []*types.AuditLog `json:"data"`
// NextCursor is the id of the last entry on this page, 0 when it is empty.
NextCursor uint64 `json:"next_cursor"`
}
// ListTenantAuditLog godoc
@ -112,16 +113,18 @@ func (h *AuditLogHandler) ListTenantAuditLog(c *gin.Context) {
// workspace actors or configuration history.
// @Summary 获取知识库活动记录
// @Description 返回知识库的重要变更与后台任务入口。仅知识库创建者或所属空间管理员可读,共享空间不可读。
// @Description 按 id 倒序;把 next_cursor 作为 after_id 取下一页,返回空列表表示没有更多。
// @Tags 知识库
// @Produce json
// @Param id path string true "知识库ID"
// @Param after_id query int false "游标:返回 id 小于此值的记录"
// @Param limit query int false "页大小,1-100,默认 50"
// @Param action query string false "按 action 精确过滤"
// @Param outcome query string false "按 outcome 精确过滤"
// @Param limit query int false "页大小" minimum(1) maximum(100) default(50)
// @Param action query string false "按 action 精确过滤,如 knowledge.deleted"
// @Param outcome query string false "结果过滤" Enums(success,accepted,partial,failed,denied,canceled)
// @Param actor query string false "按 actor_user_id 精确过滤"
// @Success 200 {object} auditLogListResponse
// @Failure 403 {object} errors.AppError
// @Failure 403 {object} errors.AppError "非创建者或管理员,或知识库来自其他空间"
// @Failure 404 {object} errors.AppError "知识库不存在"
// @Security Bearer
// @Router /knowledge-bases/{id}/activity [get]
func (h *AuditLogHandler) ListKnowledgeBaseActivity(c *gin.Context) {

View File

@ -514,7 +514,7 @@ func urlQueryEscape(value string) string {
// @Tags 认证
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "登出成功"
// @Success 200 {object} handler.MessageResponse "登出成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Router /auth/logout [post]
@ -567,7 +567,7 @@ func (h *AuthHandler) Logout(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body object{refreshToken=string} true "刷新令牌"
// @Success 200 {object} map[string]interface{} "新令牌"
// @Success 200 {object} handler.RefreshTokenResponse "新令牌"
// @Failure 401 {object} errors.AppError "令牌无效"
// @Router /auth/refresh [post]
func (h *AuthHandler) RefreshToken(c *gin.Context) {
@ -610,7 +610,7 @@ func (h *AuthHandler) RefreshToken(c *gin.Context) {
// @Tags 认证
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "用户信息"
// @Success 200 {object} handler.DataResponse{data=handler.CurrentUserData} "用户信息"
// @Failure 401 {object} errors.AppError "未授权"
// @Security Bearer
// @Router /auth/me [get]
@ -696,7 +696,7 @@ type updateMyPreferencesRequest struct {
// @Accept json
// @Produce json
// @Param request body updateMyPreferencesRequest true "Preferences patch"
// @Success 200 {object} map[string]interface{} "更新后的偏好"
// @Success 200 {object} handler.DataResponse{data=types.UserPreferences} "更新后的偏好"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 401 {object} errors.AppError "未授权"
// @Security Bearer
@ -743,7 +743,7 @@ func (h *AuthHandler) UpdateMyPreferences(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body object{old_password=string,new_password=string} true "密码修改请求"
// @Success 200 {object} map[string]interface{} "修改成功"
// @Success 200 {object} handler.MessageResponse "修改成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Router /auth/change-password [post]
@ -815,7 +815,7 @@ func (h *AuthHandler) ChangePassword(c *gin.Context) {
// @Tags 认证
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "认证配置"
// @Success 200 {object} handler.GetAuthConfigResponse "认证配置"
// @Router /auth/config [get]
//
// GetAuthConfig is intentionally a no-auth endpoint: the frontend reads
@ -987,7 +987,7 @@ func tenantNameOrEmpty(t *types.Tenant) string {
// @Tags 认证
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "令牌有效"
// @Success 200 {object} handler.ValidateTokenResponse "令牌有效"
// @Failure 401 {object} errors.AppError "令牌无效"
// @Security Bearer
// @Router /auth/validate [get]

View File

@ -44,7 +44,7 @@ func NewChunkHandler(service interfaces.ChunkService, kgService interfaces.Knowl
// @Accept json
// @Produce json
// @Param id path string true "分块ID"
// @Success 200 {object} map[string]interface{} "分块详情"
// @Success 200 {object} handler.DataResponse{data=types.Chunk} "分块详情"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "分块不存在"
// @Security Bearer
@ -84,14 +84,17 @@ func (h *ChunkHandler) GetChunkByIDOnly(c *gin.Context) {
// ListKnowledgeChunks godoc
// @Summary 获取知识分块列表
// @Description 获取指定知识下的所有分块列表,支持分页
// @Description 获取指定知识下的所有分块列表,支持分页。chunk_type 可重复,缺省 text
// @Description 取值 text, parent_text, image_ocr, image_caption, image_vector, summary, entity,
// @Description relationship, faq, web_search, table_summary, table_column, wiki_page
// @Tags 分块管理
// @Accept json
// @Produce json
// @Param knowledge_id path string true "知识ID"
// @Param page query int false "页码" default(1)
// @Param page_size query int false "每页数量" default(10)
// @Success 200 {object} map[string]interface{} "分块列表"
// @Param page query int false "页码" default(1) minimum(1)
// @Param page_size query int false "每页数量" default(10) minimum(1) maximum(100)
// @Param chunk_type query []string false "分块类型,可重复,缺省 text" collectionFormat(multi)
// @Success 200 {object} handler.PageResponse{data=[]types.Chunk} "分块列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -202,7 +205,7 @@ func (h *ChunkHandler) fetchChunkAndVerifyOwnership(c *gin.Context) (*types.Chun
// @Param knowledge_id path string true "知识ID"
// @Param id path string true "分块ID"
// @Param request body UpdateChunkRequest true "更新请求"
// @Success 200 {object} map[string]interface{} "更新后的分块"
// @Success 200 {object} handler.UpdateChunkResponse "更新后的分块"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "分块不存在"
// @Security Bearer
@ -360,7 +363,7 @@ func (h *ChunkHandler) RegenerateGeneratedQuestions(c *gin.Context) {
// @Produce json
// @Param knowledge_id path string true "知识ID"
// @Param id path string true "分块ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.MessageResponse "删除成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "分块不存在"
// @Security Bearer
@ -395,7 +398,7 @@ func (h *ChunkHandler) DeleteChunk(c *gin.Context) {
// @Accept json
// @Produce json
// @Param knowledge_id path string true "知识ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.MessageResponse "删除成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -431,7 +434,7 @@ func (h *ChunkHandler) DeleteChunksByKnowledgeID(c *gin.Context) {
// @Produce json
// @Param id path string true "分块ID"
// @Param request body object{question_id=string} true "问题ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.MessageResponse "删除成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "分块不存在"
// @Security Bearer

View File

@ -87,7 +87,7 @@ type UpdateAgentRequest struct {
// @Accept json
// @Produce json
// @Param request body CreateAgentRequest true "智能体信息"
// @Success 201 {object} map[string]interface{} "创建的智能体"
// @Success 201 {object} handler.AgentWriteResponse "创建的智能体"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -180,7 +180,7 @@ func (h *CustomAgentHandler) CreateAgent(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "智能体ID"
// @Success 200 {object} map[string]interface{} "智能体详情"
// @Success 200 {object} handler.DataResponse{data=types.CustomAgent} "智能体详情"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "智能体不存在"
// @Security Bearer
@ -230,7 +230,8 @@ func (h *CustomAgentHandler) GetAgent(c *gin.Context) {
// @Tags 智能体
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "智能体列表"
// @Param creator query string false "创建者过滤,仅 mine 与 others 生效" Enums(mine, others)
// @Success 200 {object} handler.ListAgentsResponse "智能体列表"
// @Failure 500 {object} errors.AppError "服务器错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -357,7 +358,7 @@ func enrichAgentCreatorNames(ctx context.Context, userSvc interfaces.UserService
// @Produce json
// @Param id path string true "智能体ID"
// @Param request body UpdateAgentRequest true "更新请求"
// @Success 200 {object} map[string]interface{} "更新后的智能体"
// @Success 200 {object} handler.AgentWriteResponse "更新后的智能体"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "无法修改内置智能体"
// @Security Bearer
@ -484,7 +485,7 @@ func (h *CustomAgentHandler) UpdateAgent(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "智能体ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.MessageResponse "删除成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "无法删除内置智能体"
// @Failure 404 {object} errors.AppError "智能体不存在"
@ -555,7 +556,7 @@ func (h *CustomAgentHandler) DeleteAgent(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "智能体ID"
// @Success 201 {object} map[string]interface{} "复制成功"
// @Success 201 {object} handler.DataResponse{data=types.CustomAgent} "复制成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "智能体不存在"
// @Security Bearer
@ -630,7 +631,7 @@ func (h *CustomAgentHandler) CopyAgent(c *gin.Context) {
// @Tags 智能体
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "占位符定义"
// @Success 200 {object} handler.DataResponse{data=handler.PlaceholderGroups} "占位符定义"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /agents/placeholders [get]
@ -656,7 +657,7 @@ func (h *CustomAgentHandler) GetPlaceholders(c *gin.Context) {
// @Tags 智能体
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "预设列表"
// @Success 200 {object} handler.DataResponse{data=[]types.AgentTypePresetEntry} "预设列表"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /agents/type-presets [get]
@ -675,7 +676,7 @@ func (h *CustomAgentHandler) GetAgentTypePresets(c *gin.Context) {
// @Tags 智能体
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "工具目录"
// @Success 200 {object} handler.DataResponse{data=tools.AgentToolCatalog} "工具目录"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /agents/tools [get]
@ -697,7 +698,7 @@ func (h *CustomAgentHandler) GetAgentTools(c *gin.Context) {
// @Param knowledge_ids query string false "知识ID列表(逗号分隔),限定到具体文档"
// @Param tag_scopes query string false "带知识库归属的标签范围(JSON)"
// @Param limit query int false "返回数量上限(未传时使用智能体配置的开场问题数量,最大30)"
// @Success 200 {object} map[string]interface{} "推荐问题列表"
// @Success 200 {object} handler.DataResponse{data=handler.SuggestedQuestionsData} "推荐问题列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "智能体不存在"
// @Security Bearer

View File

@ -132,7 +132,7 @@ func (h *SystemHandler) BindDeploymentCapabilities(data DeploymentCapabilitiesDa
// @Description 返回当前部署版本及实际注册的后端路由所对应的功能能力;仅 supported=false 表示入口应隐藏
// @Tags 系统
// @Produce json
// @Success 200 {object} map[string]interface{} "标准 code/msg/data 包装,data 为 DeploymentCapabilitiesData"
// @Success 200 {object} handler.GetDeploymentCapabilitiesResponse
// @Router /system/capabilities [get]
func (h *SystemHandler) GetDeploymentCapabilities(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{

View File

@ -36,7 +36,7 @@ type EvaluationRequest struct {
// @Accept json
// @Produce json
// @Param request body EvaluationRequest true "评估请求参数"
// @Success 200 {object} map[string]interface{} "评估任务"
// @Success 200 {object} handler.DataResponse{data=types.EvaluationDetail} "评估任务"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -99,7 +99,7 @@ type GetEvaluationRequest struct {
// @Accept json
// @Produce json
// @Param task_id query string true "评估任务ID"
// @Success 200 {object} map[string]interface{} "评估结果"
// @Success 200 {object} handler.DataResponse{data=types.EvaluationDetail} "评估结果"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth

View File

@ -73,7 +73,7 @@ type updateLastFAQImportResultDisplayStatusRequest struct {
// @Param search_field query string false "搜索字段: standard_question(标准问题), similar_questions(相似问法), answers(答案), 默认搜索全部"
// @Param sort_order query string false "排序方式: asc(按更新时间正序), 默认按更新时间倒序"
// @Param is_enabled query bool false "启用状态筛选;不传时返回全部"
// @Success 200 {object} map[string]interface{} "FAQ列表"
// @Success 200 {object} handler.DataResponse{data=types.PageResult} "FAQ列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -152,7 +152,7 @@ func parseOptionalFAQEnabled(c *gin.Context) (*bool, error) {
// @Produce json
// @Param id path string true "知识库ID"
// @Param request body types.FAQBatchUpsertPayload true "批量操作请求"
// @Success 200 {object} map[string]interface{} "任务ID"
// @Success 200 {object} handler.DataResponse{data=handler.TaskIDData} "任务ID"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -191,7 +191,7 @@ func (h *FAQHandler) UpsertEntries(c *gin.Context) {
// @Produce json
// @Param id path string true "知识库ID"
// @Param request body types.FAQEntryPayload true "FAQ条目"
// @Success 200 {object} map[string]interface{} "创建的FAQ条目"
// @Success 200 {object} handler.DataResponse{data=types.FAQEntry} "创建的FAQ条目"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -229,7 +229,7 @@ func (h *FAQHandler) CreateEntry(c *gin.Context) {
// @Param id path string true "知识库ID"
// @Param entry_id path int true "FAQ条目ID(seq_id)"
// @Param request body types.FAQEntryPayload true "FAQ条目"
// @Success 200 {object} map[string]interface{} "更新成功"
// @Success 200 {object} handler.DataResponse{data=types.FAQEntry} "更新成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -272,7 +272,7 @@ func (h *FAQHandler) UpdateEntry(c *gin.Context) {
// @Produce json
// @Param id path string true "知识库ID"
// @Param request body object true "标签更新请求"
// @Success 200 {object} map[string]interface{} "更新成功"
// @Success 200 {object} handler.SuccessResponse "更新成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -305,7 +305,7 @@ func (h *FAQHandler) UpdateEntryTagBatch(c *gin.Context) {
// @Produce json
// @Param id path string true "知识库ID"
// @Param request body types.FAQEntryFieldsBatchUpdate true "字段更新请求"
// @Success 200 {object} map[string]interface{} "更新成功"
// @Success 200 {object} handler.SuccessResponse "更新成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -338,7 +338,7 @@ func (h *FAQHandler) UpdateEntryFieldsBatch(c *gin.Context) {
// @Produce json
// @Param id path string true "知识库ID"
// @Param request body object{ids=[]int} true "要删除的FAQ ID列表(seq_id)"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.SuccessResponse "删除成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -373,7 +373,7 @@ func (h *FAQHandler) DeleteEntries(c *gin.Context) {
// @Produce json
// @Param id path string true "知识库ID"
// @Param request body types.FAQSearchRequest true "搜索请求"
// @Success 200 {object} map[string]interface{} "搜索结果"
// @Success 200 {object} handler.DataResponse{data=[]types.FAQEntry} "搜索结果"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -463,7 +463,7 @@ func (h *FAQHandler) ExportEntries(c *gin.Context) {
// @Produce json
// @Param id path string true "知识库ID"
// @Param entry_id path int true "FAQ条目ID(seq_id)"
// @Success 200 {object} map[string]interface{} "FAQ条目详情"
// @Success 200 {object} handler.DataResponse{data=types.FAQEntry} "FAQ条目详情"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "条目不存在"
// @Security Bearer
@ -499,7 +499,7 @@ func (h *FAQHandler) GetEntry(c *gin.Context) {
// @Accept json
// @Produce json
// @Param task_id path string true "任务ID"
// @Success 200 {object} map[string]interface{} "导入进度"
// @Success 200 {object} handler.DataResponse{data=types.FAQImportProgress} "导入进度"
// @Failure 404 {object} errors.AppError "任务不存在"
// @Security Bearer
// @Security ApiKeyAuth
@ -533,7 +533,7 @@ func (h *FAQHandler) GetImportProgress(c *gin.Context) {
// @Produce json
// @Param id path string true "知识库ID"
// @Param request body updateLastFAQImportResultDisplayStatusRequest true "状态更新请求"
// @Success 200 {object} map[string]interface{} "更新成功"
// @Success 200 {object} handler.SuccessResponse "更新成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "知识库不存在或无导入记录"
// @Security Bearer
@ -570,7 +570,7 @@ func (h *FAQHandler) UpdateLastImportResultDisplayStatus(c *gin.Context) {
// @Param id path string true "知识库ID"
// @Param entry_id path int true "FAQ条目ID(seq_id)"
// @Param request body addSimilarQuestionsRequest true "相似问列表"
// @Success 200 {object} map[string]interface{} "更新后的FAQ条目"
// @Success 200 {object} handler.DataResponse{data=types.FAQEntry} "更新后的FAQ条目"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "条目不存在"
// @Security Bearer

View File

@ -196,7 +196,7 @@ func (h *IMHandler) ListAllIMChannels(c *gin.Context) {
// @Produce json
// @Param id path string true "渠道 ID"
// @Param request body map[string]interface{} true "更新字段(含 locale)"
// @Success 200 {object} map[string]interface{} "更新后的渠道"
// @Success 200 {object} handler.UpdateIMChannelResponse "更新后的渠道"
// @Failure 400 {object} map[string]interface{} "请求参数错误"
// @Failure 404 {object} map[string]interface{} "渠道不存在"
// @Security Bearer
@ -313,7 +313,7 @@ func normalizeIMLocale(locale string) (string, error) {
// @Tags IM 渠道
// @Produce json
// @Param id path string true "渠道 ID"
// @Success 200 {object} map[string]interface{} "success: true"
// @Success 200 {object} handler.SuccessResponse "success: true"
// @Failure 400 {object} map[string]interface{} "请求参数错误"
// @Failure 404 {object} map[string]interface{} "渠道不存在"
// @Security Bearer
@ -348,7 +348,7 @@ func (h *IMHandler) DeleteIMChannel(c *gin.Context) {
// @Tags IM 渠道
// @Produce json
// @Param id path string true "渠道 ID"
// @Success 200 {object} map[string]interface{} "更新后的渠道"
// @Success 200 {object} handler.UpdateIMChannelResponse "更新后的渠道"
// @Failure 400 {object} map[string]interface{} "请求参数错误"
// @Failure 404 {object} map[string]interface{} "渠道不存在"
// @Security Bearer

View File

@ -231,7 +231,7 @@ type InitializationRequest struct {
// @Produce json
// @Param kbId path string true "知识库ID"
// @Param request body KBModelConfigRequest true "配置请求"
// @Success 200 {object} map[string]interface{} "更新成功"
// @Success 200 {object} handler.MessageResponse "更新成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "知识库不存在"
// @Security Bearer
@ -1279,7 +1279,7 @@ func (h *InitializationHandler) DownloadOllamaModel(c *gin.Context) {
// @Accept json
// @Produce json
// @Param taskId path string true "任务ID"
// @Success 200 {object} map[string]interface{} "下载进度"
// @Success 200 {object} handler.DataResponse{data=handler.DownloadTask} "下载进度"
// @Failure 404 {object} errors.AppError "任务不存在"
// @Security Bearer
// @Security ApiKeyAuth
@ -1313,7 +1313,7 @@ func (h *InitializationHandler) GetDownloadProgress(c *gin.Context) {
// @Tags 初始化
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "任务列表"
// @Success 200 {object} handler.DataResponse{data=[]handler.DownloadTask} "任务列表"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /initialization/ollama/download/tasks [get]
@ -2587,7 +2587,7 @@ type TextRelationExtractionResponse struct {
// @Accept json
// @Produce json
// @Param request body TextRelationExtractionRequest true "提取请求"
// @Success 200 {object} map[string]interface{} "提取结果"
// @Success 200 {object} handler.DataResponse{data=handler.TextRelationExtractionResponse} "提取结果"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -2688,7 +2688,7 @@ type FabriTextResponse struct {
// @Accept json
// @Produce json
// @Param request body FabriTextRequest true "生成请求"
// @Success 200 {object} map[string]interface{} "生成的文本"
// @Success 200 {object} handler.DataResponse{data=handler.FabriTextResponse} "生成的文本"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -2765,7 +2765,7 @@ var tagOptions = []string{
// @Tags 初始化
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "生成的标签"
// @Success 200 {object} handler.DataResponse{data=handler.FabriTagResponse} "生成的标签"
// @Router /initialization/extract/fabri-tag [post]
func (h *InitializationHandler) FabriTag(c *gin.Context) {
tagRandom := RandomSelect(tagOptions, rand.Intn(len(tagOptions)-1)+1)

View File

@ -304,7 +304,7 @@ func (h *KnowledgeHandler) enqueueKnowledgeListReparse(
// @Param enable_multimodel formData bool false "启用多模态处理"
// @Param tag_ids formData string false "分类ID列表,逗号分隔"
// @Param process_config formData string false "处理配置JSON(KnowledgeProcessOverrides)"
// @Success 200 {object} map[string]interface{} "创建的知识"
// @Success 200 {object} handler.DataResponse{data=types.Knowledge} "创建的知识"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 409 {object} map[string]interface{} "文件重复"
// @Security Bearer
@ -468,7 +468,7 @@ func (h *KnowledgeHandler) CreateKnowledgeFromFile(c *gin.Context) {
// @Produce json
// @Param id path string true "知识库ID"
// @Param request body object{url=string,file_name=string,file_type=string,enable_multimodel=bool,title=string,tag_ids=[]string} true "URL请求"
// @Success 201 {object} map[string]interface{} "创建的知识"
// @Success 201 {object} handler.DataResponse{data=types.Knowledge} "创建的知识"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 409 {object} map[string]interface{} "URL重复"
// @Security Bearer
@ -566,7 +566,7 @@ func (h *KnowledgeHandler) CreateKnowledgeFromURL(c *gin.Context) {
// @Produce json
// @Param id path string true "知识库ID"
// @Param request body types.ManualKnowledgePayload true "手工知识内容"
// @Success 200 {object} map[string]interface{} "创建的知识"
// @Success 200 {object} handler.DataResponse{data=types.Knowledge} "创建的知识"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -624,9 +624,10 @@ func (h *KnowledgeHandler) CreateManualKnowledge(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "知识ID"
// @Success 200 {object} map[string]interface{} "知识详情"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "知识不存在"
// @Success 200 {object} handler.DataResponse{data=types.Knowledge} "知识详情"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "无权访问所属知识库"
// @Failure 404 {object} errors.AppError "知识不存在"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge/{id} [get]
@ -671,8 +672,10 @@ func (h *KnowledgeHandler) GetKnowledge(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "知识ID"
// @Param attempt query int false "指定尝试号;省略=最新"
// @Success 200 {object} map[string]interface{}
// @Param attempt query int false "指定尝试号;省略或非正数=最新" minimum(1)
// @Success 200 {object} handler.DataResponse{data=handler.KnowledgeSpansData}
// @Failure 403 {object} errors.AppError "无权访问所属知识库"
// @Failure 404 {object} errors.AppError "知识不存在"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge/{id}/spans [get]
@ -743,40 +746,67 @@ func (h *KnowledgeHandler) GetKnowledgeSpans(c *gin.Context) {
// they're still waiting in the queue.
tree, currentStageName, lastErr := buildSpanTree(knowledge.ID, currentAttempt, rows, knowledge.ParseStatus)
resp := gin.H{
"knowledge_id": knowledge.ID,
"attempt": currentAttempt,
"latest_attempt": latestAttempt,
"parse_status": knowledge.ParseStatus,
"current_attempt": currentAttempt,
"current_stage": currentStageName,
"trace": tree,
resp := KnowledgeSpansData{
KnowledgeID: knowledge.ID,
Attempt: currentAttempt,
LatestAttempt: latestAttempt,
ParseStatus: knowledge.ParseStatus,
CurrentAttempt: currentAttempt,
CurrentStage: currentStageName,
Trace: tree,
}
if isParseInFlight(knowledge.ParseStatus) {
last := spansLastActivity(knowledge.UpdatedAt, rows)
resp["last_activity_at"] = last
resp.LastActivityAt = &last
if time.Since(last) >= stallHintAfter {
if verdict := h.stallVerdicts(ctx, []string{knowledge.ID})[knowledge.ID]; verdict != "" {
resp["stall_state"] = verdict
}
resp.StallState = h.stallVerdicts(ctx, []string{knowledge.ID})[knowledge.ID]
}
}
if lastError := knowledgeSpansLastError(
resp.LastError = knowledgeSpansLastError(
currentAttempt,
latestAttempt,
knowledge.ParseStatus,
knowledge.ErrorMessage,
knowledge.UpdatedAt,
lastErr,
); lastError != nil {
resp["last_error"] = lastError
}
)
c.JSON(http.StatusOK, gin.H{
"success": true,
"data": resp,
})
}
// KnowledgeSpansData is the data object of GET /knowledge/{id}/spans.
type KnowledgeSpansData struct {
KnowledgeID string `json:"knowledge_id"`
// Attempt is the attempt the trace describes; equals CurrentAttempt.
Attempt int `json:"attempt"`
LatestAttempt int `json:"latest_attempt"`
ParseStatus string `json:"parse_status"`
CurrentAttempt int `json:"current_attempt"`
// CurrentStage is the stage running now, or the last one that ran.
CurrentStage string `json:"current_stage"`
Trace *types.SpanTreeNode `json:"trace"`
// LastActivityAt is set while the parse is in flight.
LastActivityAt *time.Time `json:"last_activity_at,omitempty"`
// StallState is types.StallStateQueued or types.StallStateStalled when an
// in-flight parse has gone quiet.
StallState string `json:"stall_state,omitempty"`
LastError *KnowledgeSpanError `json:"last_error,omitempty"`
}
// KnowledgeSpanError is the failure of a parse attempt. Name, ErrorCode and
// ErrorMessage repeat Stage, Code and Message for older clients.
type KnowledgeSpanError struct {
Stage string `json:"stage"`
Code string `json:"code"`
Message string `json:"message"`
Name string `json:"name"`
ErrorCode string `json:"error_code"`
ErrorMessage string `json:"error_message"`
FinishedAt *time.Time `json:"finished_at"`
}
// knowledgeSpansLastError builds the last_error payload for GetKnowledgeSpans.
// Span failures win when present; otherwise a failed knowledge row without a
// matching span error (recovery / dead-letter paths) surfaces ErrorMessage.
@ -785,16 +815,16 @@ func knowledgeSpansLastError(
parseStatus, knowledgeErrorMessage string,
knowledgeUpdatedAt time.Time,
spanFailure *types.KnowledgeProcessingSpan,
) gin.H {
) *KnowledgeSpanError {
if spanFailure != nil {
return gin.H{
"stage": spanFailure.Name,
"code": spanFailure.ErrorCode,
"message": spanFailure.ErrorMessage,
"name": spanFailure.Name,
"error_code": spanFailure.ErrorCode,
"error_message": spanFailure.ErrorMessage,
"finished_at": spanFailure.FinishedAt,
return &KnowledgeSpanError{
Stage: spanFailure.Name,
Code: spanFailure.ErrorCode,
Message: spanFailure.ErrorMessage,
Name: spanFailure.Name,
ErrorCode: spanFailure.ErrorCode,
ErrorMessage: spanFailure.ErrorMessage,
FinishedAt: spanFailure.FinishedAt,
}
}
if currentAttempt != latestAttempt || parseStatus != types.ParseStatusFailed || knowledgeErrorMessage == "" {
@ -805,14 +835,14 @@ func knowledgeSpansLastError(
"Task interrupted due to application restart") {
errorCode = "SERVER_RESTART"
}
return gin.H{
"stage": "knowledge_processing",
"code": errorCode,
"message": knowledgeErrorMessage,
"name": "knowledge_processing",
"error_code": errorCode,
"error_message": knowledgeErrorMessage,
"finished_at": knowledgeUpdatedAt,
return &KnowledgeSpanError{
Stage: "knowledge_processing",
Code: errorCode,
Message: knowledgeErrorMessage,
Name: "knowledge_processing",
ErrorCode: errorCode,
ErrorMessage: knowledgeErrorMessage,
FinishedAt: &knowledgeUpdatedAt,
}
}
@ -1004,22 +1034,24 @@ func buildSpanTree(knowledgeID string, attempt int, rows []types.KnowledgeProces
// @Tags 知识管理
// @Accept json
// @Produce json
// @Description 不传 parse_status 时不返回删除中(deleting)的文档。
// @Param id path string true "知识库ID"
// @Param page query int false "页码"
// @Param page_size query int false "每页数量"
// @Param page query int false "页码" minimum(1) default(1)
// @Param page_size query int false "每页数量" minimum(1) maximum(1000) default(20)
// @Param tag_ids query string false "标签ID筛选,逗号分隔(OR语义)"
// @Param keyword query string false "关键词搜索"
// @Param file_type query string false "文件类型筛选"
// @Param parse_status query string false "解析状态筛选 (pending/processing/completed/failed)"
// @Param parse_status query string false "状态" Enums(pending,processing,finalizing,completed,failed,cancelled,deleting)
// @Param source query string false "来源/渠道筛选 (web/api/feishu/notion/yuque/wechat/...,或 manual/url 按 type 过滤)"
// @Param start_time query string false "更新时间起点,RFC3339 格式"
// @Param end_time query string false "更新时间终点,RFC3339 格式"
// @Param folder_path query string false "文件夹路径筛选,空字符串表示知识库根目录;不传该参数则不按文件夹过滤"
// @Param folder_recursive query bool false "为 true 时同时返回子文件夹内的文档"
// @Param sort_by query string false "排序字段: updated_at/created_at/file_name,默认 created_at"
// @Param sort_order query string false "排序方向: asc/desc,默认 desc"
// @Success 200 {object} map[string]interface{} "知识列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Param sort_by query string false "排序字段" Enums(created_at,updated_at,file_name) default(created_at)
// @Param sort_order query string false "排序方向" Enums(asc, desc) default(desc)
// @Success 200 {object} handler.PageResponse{data=[]types.Knowledge} "知识列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "无权访问知识库"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-bases/{id}/knowledge [get]
@ -1157,7 +1189,7 @@ func (h *KnowledgeHandler) ListKnowledge(c *gin.Context) {
// @Param knowledge_ids query string false "来源文档 ID 列表(逗号分隔,最多 50 个),仅返回这些文档的图片"
// @Param attr_filters query string false "属性筛选 JSON,同一属性多值 OR、属性间 AND"
// @Param attr_rules query string false "属性逐值裁决 JSON(off 隐藏 / on 强制显示,on 优先)"
// @Success 200 {object} map[string]interface{} "图片资产分页列表"
// @Success 200 {object} handler.PageResponse{data=[]types.ImageAsset} "图片资产分页列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -1334,7 +1366,7 @@ type imageListRequestBody struct {
// @Produce json
// @Param id path string true "知识库 ID"
// @Param body body imageListRequestBody false "筛选参数(与 GET /images 同名参数同义)"
// @Success 200 {object} map[string]interface{} "图片资产分页列表"
// @Success 200 {object} handler.PageResponse{data=[]types.ImageAsset} "图片资产分页列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -1495,7 +1527,7 @@ func (h *KnowledgeHandler) GetGalleryConfig(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "知识库ID"
// @Success 200 {object} map[string]interface{} "目录树"
// @Success 200 {object} handler.DataResponse{data=types.KnowledgeFolderTree} "目录树"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -1544,7 +1576,7 @@ type MoveKnowledgeToFolderRequest struct {
// @Accept json
// @Produce json
// @Param request body MoveKnowledgeToFolderRequest true "移动请求"
// @Success 200 {object} map[string]interface{} "移动成功"
// @Success 200 {object} handler.DataResponse{data=handler.FolderMoveData} "移动成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "权限不足"
// @Security Bearer
@ -1619,7 +1651,7 @@ type RenameKnowledgeFolderRequest struct {
// @Produce json
// @Param id path string true "知识库ID"
// @Param request body RenameKnowledgeFolderRequest true "重命名请求"
// @Success 200 {object} map[string]interface{} "重命名成功"
// @Success 200 {object} handler.DataResponse{data=handler.FolderMoveData} "重命名成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "权限不足"
// @Security Bearer
@ -1741,8 +1773,10 @@ func (h *KnowledgeHandler) requireKnowledgeInKB(
// @Accept json
// @Produce json
// @Param id path string true "知识ID"
// @Success 200 {object} map[string]interface{} "任务已提交,返回 task_id"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Success 200 {object} handler.DataMessageResponse{data=handler.TaskIDData} "任务已提交"
// @Failure 400 {object} errors.AppError "请求参数错误或知识正在移动"
// @Failure 403 {object} errors.AppError "需要编辑权限"
// @Failure 404 {object} errors.AppError "知识不存在"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge/{id} [delete]
@ -1810,7 +1844,7 @@ type BatchDeleteKnowledgeRequest struct {
// @Accept json
// @Produce json
// @Param request body BatchDeleteKnowledgeRequest true "批量删除请求"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.SubmittedTaskResponse "删除成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "权限不足"
// @Security Bearer
@ -1904,7 +1938,7 @@ func (h *KnowledgeHandler) BatchDeleteKnowledge(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "知识库ID"
// @Success 200 {object} map[string]interface{} "清空任务已提交"
// @Success 200 {object} handler.SubmittedTaskResponse "清空任务已提交"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "权限不足"
// @Security Bearer
@ -2079,7 +2113,7 @@ type GetKnowledgeBatchRequest struct {
// @Param ids query []string true "知识ID列表"
// @Param kb_id query string false "可选,知识库ID(用于共享知识库时指定范围)"
// @Param agent_id query string false "可选,共享智能体ID(用于按智能体空间批量拉取文件详情)"
// @Success 200 {object} map[string]interface{} "知识列表"
// @Success 200 {object} handler.DataResponse{data=[]types.Knowledge} "知识列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -2298,7 +2332,7 @@ type UpdateKnowledgeRequest struct {
// @Produce json
// @Param id path string true "知识ID"
// @Param request body UpdateKnowledgeRequest true "更新字段(均可选)"
// @Success 200 {object} map[string]interface{} "更新成功"
// @Success 200 {object} handler.UpdateKnowledgeResponse "更新成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -2410,7 +2444,7 @@ func (h *KnowledgeHandler) RegenerateKnowledgeSummary(c *gin.Context) {
// @Produce json
// @Param id path string true "知识ID"
// @Param request body types.ManualKnowledgePayload true "手工知识内容"
// @Success 200 {object} map[string]interface{} "更新后的知识"
// @Success 200 {object} handler.DataResponse{data=types.Knowledge} "更新后的知识"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -2459,17 +2493,24 @@ func (h *KnowledgeHandler) UpdateManualKnowledge(c *gin.Context) {
})
}
// ReparseKnowledgeRequest is the optional body of POST /knowledge/{id}/reparse.
type ReparseKnowledgeRequest struct {
// ProcessConfig overrides the processing options stored at upload time.
ProcessConfig *types.KnowledgeProcessOverrides `json:"process_config"`
}
// ReparseKnowledge godoc
// @Summary 重新解析知识
// @Description 删除知识中现有的文档内容并重新解析,使用异步任务方式处理
// @Tags 知识管理
// @Accept json
// @Produce json
// @Param id path string true "知识ID"
// @Param body body object false "可选的处理配置覆盖:{\"process_config\": KnowledgeProcessOverrides}"
// @Success 200 {object} map[string]interface{} "重新解析任务已提交"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "权限不足"
// @Param id path string true "知识ID"
// @Param body body ReparseKnowledgeRequest false "可选;不传则沿用上传时的处理配置"
// @Success 200 {object} handler.DataMessageResponse{data=types.Knowledge} "重新解析任务已提交"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "权限不足"
// @Failure 404 {object} errors.AppError "知识不存在"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge/{id}/reparse [post]
@ -2495,9 +2536,7 @@ func (h *KnowledgeHandler) ReparseKnowledge(c *gin.Context) {
// overrides stored at upload time.
var processOverrides *types.KnowledgeProcessOverrides
if c.Request.ContentLength != 0 {
var req struct {
ProcessConfig *types.KnowledgeProcessOverrides `json:"process_config"`
}
var req ReparseKnowledgeRequest
if err := c.ShouldBindJSON(&req); err != nil {
logger.Error(ctx, "Failed to parse reparse request body", err)
c.Error(errors.NewBadRequestError("Invalid reparse request body").WithDetails(err.Error()))
@ -2535,7 +2574,7 @@ func (h *KnowledgeHandler) ReparseKnowledge(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "知识ID"
// @Success 200 {object} map[string]interface{} "取消已提交"
// @Success 200 {object} handler.DataMessageResponse{data=types.Knowledge} "取消已提交"
// @Failure 400 {object} errors.AppError "状态不支持取消"
// @Failure 403 {object} errors.AppError "权限不足"
// @Failure 404 {object} errors.AppError "知识不存在"
@ -2593,7 +2632,7 @@ type knowledgeTagBatchRequest struct {
// @Accept json
// @Produce json
// @Param request body object true "标签更新请求(updates 必填,kb_id 可选)"
// @Success 200 {object} map[string]interface{} "更新成功"
// @Success 200 {object} handler.SuccessResponse "更新成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -2670,7 +2709,7 @@ func (h *KnowledgeHandler) UpdateKnowledgeTagBatch(c *gin.Context) {
// @Param id path string true "知识ID"
// @Param chunk_id path string true "分块ID"
// @Param request body object{image_info=string} true "图像信息"
// @Success 200 {object} map[string]interface{} "更新成功"
// @Success 200 {object} handler.MessageResponse "更新成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -2740,7 +2779,7 @@ func (h *KnowledgeHandler) UpdateImageInfo(c *gin.Context) {
// @Param file_types query string false "Comma-separated file extensions to filter (e.g., csv,xlsx)"
// @Param agent_id query string false "Shared agent ID (search within agent's KB scope)"
// @Param recent query bool false "Return recent files when keyword is empty"
// @Success 200 {object} map[string]interface{} "Search results"
// @Success 200 {object} handler.KnowledgeSearchKnowledgeResponse "Search results"
// @Failure 400 {object} errors.AppError "Invalid request"
// @Security Bearer
// @Security ApiKeyAuth
@ -3191,7 +3230,7 @@ type batchReparseKnowledgeRequest struct {
// @Accept json
// @Produce json
// @Param request body batchReparseKnowledgeRequest true "批量重解析请求"
// @Success 200 {object} map[string]interface{} "任务已提交"
// @Success 200 {object} handler.SubmittedTaskResponse "任务已提交"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "权限不足"
// @Security Bearer

View File

@ -134,9 +134,9 @@ func TestKnowledgeSpansLastError_PrefersSpanFailure(t *testing.T) {
got := knowledgeSpansLastError(2, 2, types.ParseStatusFailed, "recovery blew up", now, spanFail)
a := assert.New(t)
a.Equal(types.StageDocReader, got["name"])
a.Equal("DOCREADER_TIMEOUT", got["error_code"])
a.Equal("slow", got["error_message"])
a.Equal(types.StageDocReader, got.Name)
a.Equal("DOCREADER_TIMEOUT", got.ErrorCode)
a.Equal("slow", got.ErrorMessage)
}
func TestKnowledgeSpansLastError_RecoveryFallbackUsesKnowledgeMessage(t *testing.T) {
@ -144,10 +144,10 @@ func TestKnowledgeSpansLastError_RecoveryFallbackUsesKnowledgeMessage(t *testing
got := knowledgeSpansLastError(2, 2, types.ParseStatusFailed, "wiki ingest timed out", now, nil)
a := assert.New(t)
a.NotNil(got)
a.Equal("knowledge_processing", got["name"])
a.Equal("UNKNOWN", got["error_code"])
a.Equal("wiki ingest timed out", got["error_message"])
a.Equal(now, got["finished_at"])
a.Equal("knowledge_processing", got.Name)
a.Equal("UNKNOWN", got.ErrorCode)
a.Equal("wiki ingest timed out", got.ErrorMessage)
a.Equal(&now, got.FinishedAt)
}
func TestKnowledgeSpansLastError_ClassifiesServerRestart(t *testing.T) {
@ -156,8 +156,8 @@ func TestKnowledgeSpansLastError_ClassifiesServerRestart(t *testing.T) {
"Task interrupted due to application restart", now, nil)
a := assert.New(t)
a.NotNil(got)
a.Equal("SERVER_RESTART", got["error_code"])
a.Equal("SERVER_RESTART", got["code"])
a.Equal("SERVER_RESTART", got.ErrorCode)
a.Equal("SERVER_RESTART", got.Code)
}
func TestKnowledgeSpansLastError_SkipsRecoveryFallbackForHistoricalAttempt(t *testing.T) {

View File

@ -303,6 +303,52 @@ func (h *KnowledgeBaseHandler) resolveKBStoreView(
return view
}
// KnowledgeBaseJSON is the encoding/json form of a knowledge base: the struct
// fields plus the computed capabilities object added by MarshalJSON.
// Doc-only; handlers still serialize *types.KnowledgeBase directly.
type KnowledgeBaseJSON struct {
types.KnowledgeBase
Capabilities types.KBCapabilities `json:"capabilities"`
}
// KnowledgeBaseView is KnowledgeBaseJSON plus the optional vector-store
// display fields buildKBResponse merges in. Shared responses omit
// vector_store_id; owned responses include it via the embedded struct.
type KnowledgeBaseView struct {
KnowledgeBaseJSON
VectorStoreName string `json:"vector_store_name,omitempty"`
VectorStoreSource string `json:"vector_store_source,omitempty"`
VectorStoreEngineType string `json:"vector_store_engine_type,omitempty"`
VectorStoreStatus string `json:"vector_store_status,omitempty"`
// MyPermission is the caller's role on a knowledge base shared from
// another workspace; GET /knowledge-bases/{id} sets it.
MyPermission string `json:"my_permission,omitempty" enums:"admin,editor,viewer"`
}
// HybridSearchResponse is the hybrid-search body. meta is set only when the
// request enabled rerank.
type HybridSearchResponse struct {
Success bool `json:"success" example:"true"`
Data []*types.SearchResult `json:"data"`
Meta *types.RetrievalMeta `json:"meta,omitempty"`
}
// DuplicateKnowledgeBaseData is the data object of POST /knowledge-bases/{id}/duplicate.
type DuplicateKnowledgeBaseData struct {
SourceID string `json:"source_id"`
TargetID string `json:"target_id"`
Message string `json:"message"`
KnowledgeBase KnowledgeBaseView `json:"knowledge_base"`
}
// ImageAttrSchemaData is the data object of GET /image-attrs/schema.
type ImageAttrSchemaData struct {
Version string `json:"version"`
Prompt string `json:"prompt"`
Attributes []types.AttrSpec `json:"attributes"`
DefaultActions types.ImageActionsConfig `json:"default_actions"`
}
// HybridSearch godoc
// @Summary 混合搜索
// @Description 底层召回:向量+关键词混合检索,默认不 rerank(可用 rerank 字段开启);一般检索请用 /knowledge-search。推荐 POST,GET 带 JSON 体仅兼容旧客户端。
@ -312,8 +358,9 @@ func (h *KnowledgeBaseHandler) resolveKBStoreView(
// @Param id path string true "知识库ID"
// @Param request body types.SearchParams true "搜索参数"
// @Param resource_urls query string false "文件引用形式,public 返回可加载直链" Enums(handle, public) default(handle)
// @Success 200 {object} map[string]interface{} "搜索结果"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Success 200 {object} handler.HybridSearchResponse "搜索结果"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "知识库不存在"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-bases/{id}/hybrid-search [post]
@ -408,8 +455,9 @@ func (h *KnowledgeBaseHandler) HybridSearch(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body types.KnowledgeBase true "知识库信息"
// @Success 201 {object} map[string]interface{} "创建的知识库"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Success 201 {object} handler.DataResponse{data=handler.KnowledgeBaseView} "创建的知识库"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 500 {object} errors.AppError "服务器错误"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-bases [post]
@ -493,9 +541,10 @@ func (h *KnowledgeBaseHandler) validateAndGetKnowledgeBase(
// @Produce json
// @Param id path string true "知识库ID"
// @Param agent_id query string false "共享智能体 ID(用于校验智能体是否有权访问该知识库)"
// @Success 200 {object} map[string]interface{} "知识库详情"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "知识库不存在"
// @Success 200 {object} handler.DataResponse{data=handler.KnowledgeBaseView} "知识库详情"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "无权访问知识库"
// @Failure 404 {object} errors.AppError "知识库不存在"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-bases/{id} [get]
@ -527,8 +576,10 @@ func (h *KnowledgeBaseHandler) GetKnowledgeBase(c *gin.Context) {
// @Accept json
// @Produce json
// @Param agent_id query string false "共享智能体 ID(传入时返回该智能体可用的知识库)"
// @Success 200 {object} map[string]interface{} "知识库列表"
// @Failure 500 {object} errors.AppError "服务器错误"
// @Param creator query string false "按创建者过滤,仅 mine 与 others 生效" Enums(mine, others)
// @Success 200 {object} handler.DataResponse{data=[]handler.KnowledgeBaseView} "知识库列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 500 {object} errors.AppError "服务器错误"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-bases [get]
@ -701,8 +752,10 @@ func pickUserDisplayName(u *types.User) string {
// @Accept json
// @Produce json
// @Param id path string true "知识库ID"
// @Success 200 {object} map[string]interface{} "更新后的知识库"
// @Failure 404 {object} errors.AppError "知识库不存在"
// @Success 200 {object} handler.DataResponse{data=handler.KnowledgeBaseView} "更新后的知识库"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "知识库不存在"
// @Failure 500 {object} errors.AppError "服务器错误"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-bases/{id}/pin [put]
@ -751,8 +804,10 @@ type UpdateKnowledgeBaseRequest struct {
// @Produce json
// @Param id path string true "知识库ID"
// @Param request body UpdateKnowledgeBaseRequest true "更新请求"
// @Success 200 {object} map[string]interface{} "更新后的知识库"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Success 200 {object} handler.DataResponse{data=handler.KnowledgeBaseView} "更新后的知识库"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "无权限"
// @Failure 404 {object} errors.AppError "知识库不存在"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-bases/{id} [put]
@ -834,8 +889,10 @@ func (h *KnowledgeBaseHandler) UpdateKnowledgeBase(c *gin.Context) {
// @Tags 知识库
// @Produce json
// @Param id path string true "知识库ID"
// @Success 200 {object} map[string]interface{} "生成的知识库画像"
// @Failure 400 {object} errors.AppError "知识库类型不支持或未配置模型"
// @Success 200 {object} handler.DataResponse{data=types.KnowledgeBaseProfile} "生成的知识库画像"
// @Failure 400 {object} errors.AppError "知识库类型不支持或未配置模型"
// @Failure 403 {object} errors.AppError "无权限"
// @Failure 404 {object} errors.AppError "知识库不存在"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-bases/{id}/profile/generate [post]
@ -883,8 +940,10 @@ const knowledgeBaseProfileRequestTimeout = 2 * time.Minute
// @Accept json
// @Produce json
// @Param id path string true "知识库ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Success 200 {object} handler.MessageResponse "删除成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "仅所有者可删除"
// @Failure 404 {object} errors.AppError "知识库不存在"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-bases/{id} [delete]
@ -952,8 +1011,10 @@ type DuplicateKnowledgeBaseResponse struct {
// @Accept json
// @Produce json
// @Param request body CopyKnowledgeBaseRequest true "复制请求"
// @Success 200 {object} map[string]interface{} "任务ID"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Success 200 {object} handler.DataResponse{data=handler.CopyKnowledgeBaseResponse} "任务ID"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 401 {object} errors.AppError "未认证"
// @Failure 403 {object} errors.AppError "无权限"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-bases/copy [post]
@ -1104,8 +1165,10 @@ func (h *KnowledgeBaseHandler) CopyKnowledgeBase(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "源知识库 ID"
// @Success 201 {object} map[string]interface{} "创建后的知识库副本"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Success 201 {object} handler.DataResponse{data=handler.DuplicateKnowledgeBaseData} "创建后的知识库副本"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "无权限"
// @Failure 404 {object} errors.AppError "知识库不存在"
// @Security Bearer
// @Router /knowledge-bases/{id}/duplicate [post]
func (h *KnowledgeBaseHandler) DuplicateKnowledgeBase(c *gin.Context) {
@ -1170,8 +1233,9 @@ func (h *KnowledgeBaseHandler) DuplicateKnowledgeBase(c *gin.Context) {
// @Accept json
// @Produce json
// @Param task_id path string true "任务ID"
// @Success 200 {object} map[string]interface{} "进度信息"
// @Failure 404 {object} errors.AppError "任务不存在"
// @Success 200 {object} handler.DataResponse{data=types.KBCloneProgress} "进度信息"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "任务不存在"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-bases/copy/progress/{task_id} [get]
@ -1284,9 +1348,11 @@ func validateKnowledgeBasePromptInstructions(kb *types.KnowledgeBase) error {
// @Tags 知识库
// @Produce json
// @Param id path string true "源知识库 ID"
// @Success 200 {object} map[string]interface{} "可移动目标列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "知识库不存在"
// @Success 200 {object} handler.DataResponse{data=[]types.KnowledgeBase} "可移动目标列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 401 {object} errors.AppError "未认证"
// @Failure 403 {object} errors.AppError "无权限"
// @Failure 404 {object} errors.AppError "知识库不存在"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-bases/{id}/move-targets [get]
@ -1351,13 +1417,15 @@ func (h *KnowledgeBaseHandler) ListMoveTargets(c *gin.Context) {
})
}
// GetImageAttrsSchema returns the canonical image-attribute registry for this
// release. It is the single source of truth that drives the frontend attribute
// panel — both the attributes and their display text (label, description, the
// meaning of each value) — so adding an attribute later is a backend-only
// change (one registry row) and the UI follows automatically. Read-only; the
// registry is global, not per-KB, so it carries no KB id and only the Viewer
// role is required.
// GetImageAttrsSchema godoc
// @Summary 获取图片属性字典
// @Description 返回当前版本的图片属性注册表、提示词版本和默认动作。全局只读,不绑定知识库。
// @Tags 知识库
// @Produce json
// @Success 200 {object} handler.DataResponse{data=handler.ImageAttrSchemaData}
// @Security Bearer
// @Security ApiKeyAuth
// @Router /image-attrs/schema [get]
func (h *KnowledgeBaseHandler) GetImageAttrsSchema(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{
"success": true,

View File

@ -59,7 +59,7 @@ type mcpCredentialsPutRequest struct {
// @Produce json
// @Param id path string true "MCP 服务 ID"
// @Param request body map[string]interface{} true "{api_key?, token?, client_secret?: string}"
// @Success 200 {object} map[string]interface{} "写入后的凭据状态"
// @Success 200 {object} handler.DataResponse{data=dto.CredentialsResponse} "写入后的凭据状态"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "服务不存在"
// @Security Bearer

View File

@ -204,7 +204,7 @@ func (h *MCPEndpointHandler) UpdateMCPEndpoint(c *gin.Context) {
// @Tags MCP端点
// @Produce json
// @Param endpoint_id path string true "端点 ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.SuccessResponse "删除成功"
// @Failure 404 {object} map[string]interface{} "端点不存在"
// @Security Bearer
// @Security ApiKeyAuth

View File

@ -152,7 +152,7 @@ type mcpOAuthAssertionRequest struct {
// @Produce json
// @Param id path string true "MCP 服务 ID"
// @Param request body map[string]interface{} true "{assertion: string}"
// @Success 200 {object} map[string]interface{} "与 oauth/status 相同"
// @Success 200 {object} handler.DataResponse{data=mcp.OAuthAuthorizationStatus} "与 oauth/status 相同"
// @Failure 400 {object} errors.AppError "断言无效或被授权服务器拒绝"
// @Failure 404 {object} errors.AppError
// @Security Bearer
@ -387,7 +387,7 @@ type resolveMCPOAuthBody struct {
// @Produce json
// @Param pending_id path string true "待授权 ID"
// @Param request body map[string]interface{} true "{service_id: string}"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.SuccessResponse
// @Failure 400 {object} errors.AppError
// @Failure 409 {object} errors.AppError "用户尚未完成授权"
// @Security Bearer
@ -496,7 +496,7 @@ func (h *MCPOAuthHandler) ResolveMCPOAuth(c *gin.Context) {
// @Tags MCP服务
// @Produce json
// @Param pending_id path string true "待授权 ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.SuccessResponse
// @Failure 404 {object} errors.AppError
// @Security Bearer
// @Router /agent/mcp-oauth-resolutions/{pending_id}/cancel [post]

View File

@ -87,7 +87,7 @@ func (h *MCPServiceHandler) mcpServiceResponses(
// @Accept json
// @Produce json
// @Param request body types.MCPService true "MCP服务配置"
// @Success 200 {object} map[string]interface{} "创建的MCP服务"
// @Success 200 {object} handler.DataResponse{data=dto.MCPServiceResponse} "创建的MCP服务"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -146,7 +146,7 @@ func (h *MCPServiceHandler) CreateMCPService(c *gin.Context) {
// @Produce json
// @Param agent_id query string false "Agent ID; needs agent_source_tenant_id"
// @Param agent_source_tenant_id query int false "Shared agent source workspace"
// @Success 200 {object} map[string]interface{} "MCP服务列表"
// @Success 200 {object} handler.DataResponse{data=[]dto.MCPServiceResponse} "MCP服务列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "无权使用该共享智能体"
// @Security Bearer
@ -238,7 +238,7 @@ func (h *MCPServiceHandler) listSharedAgentMCPServices(c *gin.Context, agent *ty
// @Accept json
// @Produce json
// @Param id path string true "MCP服务ID"
// @Success 200 {object} map[string]interface{} "MCP服务详情"
// @Success 200 {object} handler.DataResponse{data=dto.MCPServiceResponse} "MCP服务详情"
// @Failure 404 {object} errors.AppError "服务不存在"
// @Security Bearer
// @Security ApiKeyAuth
@ -278,7 +278,7 @@ func (h *MCPServiceHandler) GetMCPService(c *gin.Context) {
// @Produce json
// @Param id path string true "MCP服务ID"
// @Param request body object true "更新字段"
// @Success 200 {object} map[string]interface{} "更新后的MCP服务"
// @Success 200 {object} handler.DataResponse{data=dto.MCPServiceResponse} "更新后的MCP服务"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -494,7 +494,7 @@ func (h *MCPServiceHandler) UpdateMCPService(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "MCP服务ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.MessageResponse "删除成功"
// @Failure 500 {object} errors.AppError "服务器错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -530,7 +530,7 @@ func (h *MCPServiceHandler) DeleteMCPService(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "MCP服务ID"
// @Success 200 {object} map[string]interface{} "测试结果"
// @Success 200 {object} handler.DataResponse{data=types.MCPTestResult} "测试结果"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -575,7 +575,7 @@ func (h *MCPServiceHandler) TestMCPService(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "MCP服务ID"
// @Success 200 {object} map[string]interface{} "工具列表"
// @Success 200 {object} handler.DataResponse{data=[]types.MCPTool} "工具列表"
// @Failure 500 {object} errors.AppError "服务器错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -611,7 +611,7 @@ func (h *MCPServiceHandler) GetMCPServiceTools(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "MCP服务ID"
// @Success 200 {object} map[string]interface{} "资源列表"
// @Success 200 {object} handler.DataResponse{data=[]types.MCPResource} "资源列表"
// @Failure 500 {object} errors.AppError "服务器错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -685,7 +685,7 @@ type setMCPToolApprovalBody struct {
// @Param id path string true "MCP 服务 ID"
// @Param tool_name path string true "工具名"
// @Param request body map[string]interface{} true "{require_approval?: bool, enabled?: bool}"
// @Success 200 {object} map[string]interface{} "更新结果"
// @Success 200 {object} handler.SuccessResponse "更新结果"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "MCP 服务或工具不存在"
// @Security Bearer

View File

@ -69,7 +69,7 @@ func respondEnvVarError(c *gin.Context, err error) {
// @Description List every sandbox config of this workspace with the caller's own config-wide variables and the credentials its skills declared, each reporting whether it is unset, filled in workspace-wide, or filled in by the caller. Values are never returned.
// @Tags Me
// @Produce json
// @Success 200 {object} map[string]interface{} "One group per sandbox config"
// @Success 200 {object} handler.DataResponse{data=[]service.ConfigEnvGroup} "One group per sandbox config"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Security Bearer
// @Router /me/env-vars [get]
@ -89,7 +89,7 @@ func (h *MeEnvVarHandler) List(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body meEnvVarRequest true "Skill, variable name and value"
// @Success 200 {object} map[string]interface{} "Stored"
// @Success 200 {object} handler.SuccessResponse "Stored"
// @Failure 400 {object} apperrors.AppError "Invalid request"
// @Security Bearer
// @Router /me/env-vars/skill [put]
@ -112,7 +112,7 @@ func (h *MeEnvVarHandler) SetSkill(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body meEnvVarRequest true "Skill and variable name"
// @Success 200 {object} map[string]interface{} "Deleted"
// @Success 200 {object} handler.SuccessResponse "Deleted"
// @Failure 404 {object} apperrors.AppError "Not set"
// @Security Bearer
// @Router /me/env-vars/skill [delete]
@ -135,7 +135,7 @@ func (h *MeEnvVarHandler) DeleteSkill(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body meEnvVarRequest true "Sandbox config, variable name and value"
// @Success 200 {object} map[string]interface{} "Stored"
// @Success 200 {object} handler.SuccessResponse "Stored"
// @Failure 400 {object} apperrors.AppError "Invalid request"
// @Security Bearer
// @Router /me/env-vars/sandbox [put]
@ -160,7 +160,7 @@ func (h *MeEnvVarHandler) SetSandbox(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body meEnvVarRequest true "Sandbox config and variable name"
// @Success 200 {object} map[string]interface{} "Deleted"
// @Success 200 {object} handler.SuccessResponse "Deleted"
// @Failure 404 {object} apperrors.AppError "Not set"
// @Security Bearer
// @Router /me/env-vars/sandbox [delete]

View File

@ -33,7 +33,7 @@ func NewMemoryHandler(memoryService interfaces.MemoryService) *MemoryHandler {
// @Description 返回合并后的记忆开关状态(空间级 + 个人级)与记忆条数
// @Tags 长期记忆
// @Produce json
// @Success 200 {object} map[string]interface{} "记忆设置"
// @Success 200 {object} handler.DataResponse{data=types.MemorySettings} "记忆设置"
// @Security Bearer
// @Router /memory/settings [get]
func (h *MemoryHandler) GetSettings(c *gin.Context) {
@ -57,7 +57,7 @@ type updateMemorySettingsRequest struct {
// @Accept json
// @Produce json
// @Param request body object true "设置"
// @Success 200 {object} map[string]interface{} "更新后的设置"
// @Success 200 {object} handler.DataResponse{data=types.MemorySettings} "更新后的设置"
// @Security Bearer
// @Router /memory/settings [put]
func (h *MemoryHandler) UpdateSettings(c *gin.Context) {
@ -91,7 +91,7 @@ func (h *MemoryHandler) UpdateSettings(c *gin.Context) {
// @Param status query string false "状态过滤" Enums(active, superseded, archived, pending)
// @Param limit query int false "每页条数" default(50)
// @Param offset query int false "偏移量"
// @Success 200 {object} map[string]interface{} "记忆列表"
// @Success 200 {object} handler.ListItemsResponse "记忆列表"
// @Security Bearer
// @Router /memory/items [get]
func (h *MemoryHandler) ListItems(c *gin.Context) {
@ -145,7 +145,7 @@ func memoryListPaging(c *gin.Context) (limit, offset int) {
// @Produce json
// @Param limit query int false "每页条数" default(50)
// @Param offset query int false "偏移量"
// @Success 200 {object} map[string]interface{} "主题列表"
// @Success 200 {object} handler.ListTopicsResponse "主题列表"
// @Security Bearer
// @Router /memory/topics [get]
func (h *MemoryHandler) ListTopics(c *gin.Context) {
@ -169,7 +169,7 @@ func (h *MemoryHandler) ListTopics(c *gin.Context) {
// @Tags 长期记忆
// @Produce json
// @Param id path string true "主题 ID"
// @Success 200 {object} map[string]interface{} "新增的记忆"
// @Success 200 {object} handler.DataResponse{data=types.MemoryItem} "新增的记忆"
// @Security Bearer
// @Router /memory/topics/{id}/promote [post]
func (h *MemoryHandler) PromoteTopic(c *gin.Context) {
@ -188,7 +188,7 @@ func (h *MemoryHandler) PromoteTopic(c *gin.Context) {
// @Tags 长期记忆
// @Produce json
// @Param id path string true "主题 ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.SuccessResponse "删除成功"
// @Security Bearer
// @Router /memory/topics/{id} [delete]
func (h *MemoryHandler) DeleteTopic(c *gin.Context) {
@ -207,7 +207,7 @@ func (h *MemoryHandler) DeleteTopic(c *gin.Context) {
// @Produce json
// @Param limit query int false "每页条数" default(50)
// @Param offset query int false "偏移量"
// @Success 200 {object} map[string]interface{} "文档列表"
// @Success 200 {object} handler.ListDocumentsResponse "文档列表"
// @Security Bearer
// @Router /memory/documents [get]
func (h *MemoryHandler) ListDocuments(c *gin.Context) {
@ -231,7 +231,7 @@ func (h *MemoryHandler) ListDocuments(c *gin.Context) {
// @Tags 长期记忆
// @Produce json
// @Param id path string true "亲和度 ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.SuccessResponse "删除成功"
// @Security Bearer
// @Router /memory/documents/{id} [delete]
func (h *MemoryHandler) DeleteDocument(c *gin.Context) {
@ -256,7 +256,7 @@ type createMemoryItemRequest struct {
// @Accept json
// @Produce json
// @Param request body object true "记忆内容"
// @Success 200 {object} map[string]interface{} "新增的记忆"
// @Success 200 {object} handler.DataResponse{data=types.MemoryItem} "新增的记忆"
// @Security Bearer
// @Router /memory/items [post]
func (h *MemoryHandler) CreateItem(c *gin.Context) {
@ -287,7 +287,7 @@ type updateMemoryItemRequest struct {
// @Produce json
// @Param id path string true "记忆ID"
// @Param request body object true "记忆内容"
// @Success 200 {object} map[string]interface{} "更新后的记忆"
// @Success 200 {object} handler.DataResponse{data=types.MemoryItem} "更新后的记忆"
// @Security Bearer
// @Router /memory/items/{id} [put]
func (h *MemoryHandler) UpdateItem(c *gin.Context) {
@ -311,7 +311,7 @@ func (h *MemoryHandler) UpdateItem(c *gin.Context) {
// @Tags 长期记忆
// @Produce json
// @Param id path string true "记忆ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.SuccessResponse "删除成功"
// @Security Bearer
// @Router /memory/items/{id} [delete]
func (h *MemoryHandler) DeleteItem(c *gin.Context) {
@ -329,7 +329,7 @@ func (h *MemoryHandler) DeleteItem(c *gin.Context) {
// @Tags 长期记忆
// @Produce json
// @Param id path string true "记忆 ID"
// @Success 200 {object} map[string]interface{} "确认成功"
// @Success 200 {object} handler.DataResponse{data=types.MemoryItem} "确认成功"
// @Security Bearer
// @Router /memory/items/{id}/confirm [post]
//
@ -351,7 +351,7 @@ func (h *MemoryHandler) ConfirmItem(c *gin.Context) {
// @Tags 长期记忆
// @Produce json
// @Param id path string true "记忆 ID"
// @Success 200 {object} map[string]interface{} "否决成功"
// @Success 200 {object} handler.SuccessResponse "否决成功"
// @Security Bearer
// @Router /memory/items/{id}/reject [post]
func (h *MemoryHandler) RejectItem(c *gin.Context) {
@ -368,7 +368,7 @@ func (h *MemoryHandler) RejectItem(c *gin.Context) {
// @Description 永久删除当前用户的全部记忆
// @Tags 长期记忆
// @Produce json
// @Success 200 {object} map[string]interface{} "清空成功"
// @Success 200 {object} handler.ClearResponse "清空成功"
// @Security Bearer
// @Router /memory/items [delete]
func (h *MemoryHandler) Clear(c *gin.Context) {
@ -386,7 +386,7 @@ func (h *MemoryHandler) Clear(c *gin.Context) {
// @Description 以 JSON 导出当前用户的全部记忆
// @Tags 长期记忆
// @Produce json
// @Success 200 {object} map[string]interface{} "记忆导出"
// @Success 200 {object} handler.ExportResponse "记忆导出"
// @Security Bearer
// @Router /memory/export [get]
func (h *MemoryHandler) Export(c *gin.Context) {
@ -431,7 +431,7 @@ func (h *MemoryHandler) Export(c *gin.Context) {
// @Description 合并意思接近的条目、归档到期事项,不等待每日后台整理
// @Tags 长期记忆
// @Produce json
// @Success 200 {object} map[string]interface{} "整理结果"
// @Success 200 {object} handler.DataResponse{data=types.MemoryConsolidationResult} "整理结果"
// @Security Bearer
// @Router /memory/consolidate [post]
func (h *MemoryHandler) Consolidate(c *gin.Context) {

View File

@ -120,7 +120,7 @@ func (h *MessageHandler) resolveResourceRewriter(c *gin.Context) (*storageurl.Re
// @Param limit query int false "返回数量" default(20)
// @Param before_time query string false "在此时间之前的消息(RFC3339Nano格式)"
// @Param resource_urls query string false "文件引用形式,public 返回可加载直链" Enums(handle, public) default(handle)
// @Success 200 {object} map[string]interface{} "消息列表"
// @Success 200 {object} handler.DataResponse{data=[]types.Message} "消息列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -232,7 +232,7 @@ func (h *MessageHandler) LoadMessages(c *gin.Context) {
// @Produce json
// @Param session_id path string true "会话ID"
// @Param id path string true "消息ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.MessageResponse "删除成功"
// @Failure 500 {object} errors.AppError "服务器错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -286,7 +286,7 @@ func (h *MessageHandler) DeleteMessage(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body SearchMessagesRequest true "搜索请求"
// @Success 200 {object} map[string]interface{} "搜索结果"
// @Success 200 {object} handler.DataResponse{data=types.MessageSearchResult} "搜索结果"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -351,7 +351,7 @@ type SearchMessagesRequest struct {
// @Tags 消息
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "统计信息"
// @Success 200 {object} handler.DataResponse{data=types.ChatHistoryKBStats} "统计信息"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /messages/chat-history-stats [get]

View File

@ -7,6 +7,7 @@ import (
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"
secutils "github.com/Tencent/WeKnora/internal/utils"
"github.com/gin-gonic/gin"
@ -17,6 +18,9 @@ type MessageSuggestionHandler struct {
service interfaces.MessageSuggestionService
}
// Keeps types imported so swag can resolve MessageSuggestionSet in comments.
var _ types.MessageSuggestionSet
func NewMessageSuggestionHandler(service interfaces.MessageSuggestionService) *MessageSuggestionHandler {
return &MessageSuggestionHandler{service: service}
}
@ -40,8 +44,8 @@ type SuggestionEventRequest struct {
// @Param session_id path string true "会话 ID"
// @Param message_id path string true "助手消息 ID"
// @Param request body EnsureMessageSuggestionsRequest false "生成选项"
// @Success 200 {object} map[string]interface{}
// @Success 202 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=types.MessageSuggestionSet}
// @Success 202 {object} handler.DataResponse{data=types.MessageSuggestionSet}
// @Security Bearer
// @Security ApiKeyAuth
// @Router /sessions/{session_id}/messages/{message_id}/suggestions [post]
@ -76,7 +80,7 @@ func (h *MessageSuggestionHandler) Ensure(c *gin.Context) {
// @Produce json
// @Param session_id path string true "会话 ID"
// @Param message_id path string true "助手消息 ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=types.MessageSuggestionSet}
// @Security Bearer
// @Security ApiKeyAuth
// @Router /sessions/{session_id}/messages/{message_id}/suggestions [get]

View File

@ -63,7 +63,7 @@ type CreateModelRequest struct {
// @Accept json
// @Produce json
// @Param request body CreateModelRequest true "模型信息"
// @Success 201 {object} map[string]interface{} "创建的模型"
// @Success 201 {object} handler.DataResponse{data=dto.ModelResponse} "创建的模型"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -146,7 +146,7 @@ type CopyModelRequest struct {
// @Produce json
// @Param id path string true "源模型ID"
// @Param request body CopyModelRequest true "副本展示名"
// @Success 201 {object} map[string]interface{} "复制的模型"
// @Success 201 {object} handler.DataResponse{data=dto.ModelResponse} "复制的模型"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "模型不存在"
// @Security Bearer
@ -208,7 +208,7 @@ func (h *ModelHandler) CopyModel(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "模型ID"
// @Success 200 {object} map[string]interface{} "模型详情"
// @Success 200 {object} handler.DataResponse{data=dto.ModelResponse} "模型详情"
// @Failure 404 {object} errors.AppError "模型不存在"
// @Security Bearer
// @Security ApiKeyAuth
@ -252,7 +252,7 @@ func (h *ModelHandler) GetModel(c *gin.Context) {
// @Tags 模型管理
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "模型列表"
// @Success 200 {object} handler.DataResponse{data=[]dto.ModelResponse} "模型列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -741,7 +741,7 @@ type UpdateModelRequest struct {
// @Produce json
// @Param id path string true "模型ID"
// @Param request body UpdateModelRequest true "更新信息"
// @Success 200 {object} map[string]interface{} "更新后的模型"
// @Success 200 {object} handler.DataResponse{data=dto.ModelResponse} "更新后的模型"
// @Failure 404 {object} errors.AppError "模型不存在"
// @Security Bearer
// @Security ApiKeyAuth
@ -874,7 +874,7 @@ func (h *ModelHandler) UpdateModel(c *gin.Context) {
// @Accept json
// @Produce json
// @Param id path string true "模型ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.MessageResponse "删除成功"
// @Failure 400 {object} errors.AppError "模型仍被知识库、智能体或长期记忆引用"
// @Failure 404 {object} errors.AppError "模型不存在"
// @Security Bearer

View File

@ -190,7 +190,7 @@ func providerDTO(v *modelruntime.Provider, modelType types.ModelType, includeMod
// @Accept json
// @Produce json
// @Param model_type query string false "模型类型 (chat, embedding, rerank, vllm, asr)"
// @Success 200 {object} map[string]interface{} "厂商列表"
// @Success 200 {object} handler.DataResponse{data=[]handler.ModelProviderDTO} "厂商列表"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /models/providers [get]

View File

@ -66,7 +66,7 @@ func NewOrganizationHandler(
// @Accept json
// @Produce json
// @Param request body types.CreateOrganizationRequest true "组织信息"
// @Success 201 {object} map[string]interface{}
// @Success 201 {object} handler.DataResponse{data=types.OrganizationResponse}
// @Failure 400 {object} apperrors.AppError
// @Security Bearer
// @Router /organizations [post]
@ -107,7 +107,7 @@ func (h *OrganizationHandler) CreateOrganization(c *gin.Context) {
// @Tags 组织管理
// @Produce json
// @Param id path string true "组织ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=types.OrganizationResponse}
// @Failure 404 {object} apperrors.AppError
// @Security Bearer
// @Router /organizations/{id} [get]
@ -303,7 +303,7 @@ func (h *OrganizationHandler) buildResourceCountsByOrg(ctx context.Context, orgs
// @Produce json
// @Param id path string true "组织ID"
// @Param request body types.UpdateOrganizationRequest true "更新信息"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=types.OrganizationResponse}
// @Failure 403 {object} apperrors.AppError
// @Security Bearer
// @Router /organizations/{id} [put]
@ -346,7 +346,7 @@ func (h *OrganizationHandler) UpdateOrganization(c *gin.Context) {
// @Description 删除组织(仅组织创建者可操作)
// @Tags 组织管理
// @Param id path string true "组织ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.MessageResponse
// @Failure 403 {object} apperrors.AppError
// @Security Bearer
// @Router /organizations/{id} [delete]
@ -451,7 +451,7 @@ func (h *OrganizationHandler) ListMembers(c *gin.Context) {
// @Param id path string true "组织ID"
// @Param tenant_id path string true "成员空间ID"
// @Param request body types.UpdateMemberRoleRequest true "角色信息"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.MessageResponse
// @Failure 403 {object} apperrors.AppError
// @Security Bearer
// @Router /organizations/{id}/members/{tenant_id} [put]
@ -492,7 +492,7 @@ func (h *OrganizationHandler) UpdateMemberRole(c *gin.Context) {
// @Tags 组织管理
// @Param id path string true "组织ID"
// @Param tenant_id path string true "成员空间ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.MessageResponse
// @Failure 403 {object} apperrors.AppError
// @Security Bearer
// @Router /organizations/{id}/members/{tenant_id} [delete]
@ -618,7 +618,7 @@ func (h *OrganizationHandler) PreviewByInviteCode(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body types.JoinOrganizationRequest true "邀请码"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=types.OrganizationResponse}
// @Failure 404 {object} apperrors.AppError
// @Security Bearer
// @Router /organizations/join [post]
@ -659,7 +659,7 @@ func (h *OrganizationHandler) JoinByInviteCode(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body types.SubmitJoinRequestRequest true "申请信息"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=types.OrganizationJoinRequest}
// @Failure 400 {object} apperrors.AppError
// @Security Bearer
// @Router /organizations/join-request [post]
@ -732,7 +732,7 @@ func (h *OrganizationHandler) SubmitJoinRequest(c *gin.Context) {
// @Produce json
// @Param q query string false "搜索关键词(空间名称或描述)"
// @Param limit query int false "返回数量限制" default(20)
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.SearchOrganizationsResponse
// @Security Bearer
// @Router /organizations/search [get]
func (h *OrganizationHandler) SearchOrganizations(c *gin.Context) {
@ -765,7 +765,7 @@ func (h *OrganizationHandler) SearchOrganizations(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body types.JoinByOrganizationIDRequest true "空间 ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=types.OrganizationResponse}
// @Failure 403 {object} apperrors.AppError
// @Security Bearer
// @Router /organizations/join-by-id [post]
@ -821,7 +821,7 @@ func (h *OrganizationHandler) JoinByOrganizationID(c *gin.Context) {
// @Produce json
// @Param id path string true "组织ID"
// @Param request body types.RequestRoleUpgradeRequest true "申请信息"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=types.OrganizationJoinRequest}
// @Failure 400 {object} apperrors.AppError
// @Security Bearer
// @Router /organizations/{id}/request-upgrade [post]
@ -879,7 +879,7 @@ func (h *OrganizationHandler) RequestRoleUpgrade(c *gin.Context) {
// @Description 退出指定组织
// @Tags 组织管理
// @Param id path string true "组织ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.MessageResponse
// @Failure 403 {object} apperrors.AppError
// @Security Bearer
// @Router /organizations/{id}/leave [post]
@ -925,7 +925,7 @@ func (h *OrganizationHandler) LeaveOrganization(c *gin.Context) {
// @Tags 组织管理
// @Produce json
// @Param id path string true "组织ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=types.ListJoinRequestsResponse}
// @Failure 403 {object} apperrors.AppError
// @Security Bearer
// @Router /organizations/{id}/join-requests [get]
@ -995,7 +995,7 @@ func (h *OrganizationHandler) ListJoinRequests(c *gin.Context) {
// @Param id path string true "组织ID"
// @Param request_id path string true "申请ID"
// @Param request body types.ReviewJoinRequestRequest true "审核结果"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.MessageResponse
// @Failure 403 {object} apperrors.AppError
// @Security Bearer
// @Router /organizations/{id}/join-requests/{request_id}/review [put]
@ -1056,7 +1056,7 @@ func (h *OrganizationHandler) ReviewJoinRequest(c *gin.Context) {
// @Produce json
// @Param id path string true "知识库ID"
// @Param request body types.ShareKnowledgeBaseRequest true "共享信息"
// @Success 201 {object} map[string]interface{}
// @Success 201 {object} handler.DataResponse{data=types.KnowledgeBaseShare}
// @Failure 403 {object} apperrors.AppError
// @Security Bearer
// @Router /knowledge-bases/{id}/shares [post]
@ -1159,7 +1159,7 @@ func (h *OrganizationHandler) ListKBShares(c *gin.Context) {
// @Param id path string true "知识库ID"
// @Param share_id path string true "共享记录ID"
// @Param request body types.UpdateSharePermissionRequest true "权限信息"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.MessageResponse
// @Failure 403 {object} apperrors.AppError
// @Security Bearer
// @Router /knowledge-bases/{id}/shares/{share_id} [put]
@ -1235,7 +1235,7 @@ func (h *OrganizationHandler) agentShareOnPath(c *gin.Context, shareID string) b
// @Tags 知识库共享
// @Param id path string true "知识库ID"
// @Param share_id path string true "共享记录ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.MessageResponse
// @Failure 403 {object} apperrors.AppError
// @Security Bearer
// @Router /knowledge-bases/{id}/shares/{share_id} [delete]
@ -1345,7 +1345,7 @@ func (h *OrganizationHandler) ListOrgShares(c *gin.Context) {
// @Description 获取通过组织共享给当前用户的所有知识库
// @Tags 知识库共享
// @Produce json
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.ListSharedKnowledgeBasesResponse
// @Security Bearer
// @Router /shared-knowledge-bases [get]
func (h *OrganizationHandler) ListSharedKnowledgeBases(c *gin.Context) {
@ -1467,7 +1467,7 @@ func (h *OrganizationHandler) ListAgentShares(c *gin.Context) {
// @Produce json
// @Param id path string true "智能体 ID"
// @Param share_id path string true "共享记录 ID"
// @Success 200 {object} map[string]interface{} "success: true"
// @Success 200 {object} handler.MessageResponse "success: true"
// @Failure 403 {object} apperrors.AppError "无权限"
// @Security Bearer
// @Security ApiKeyAuth
@ -1571,7 +1571,7 @@ func (h *OrganizationHandler) ListOrgAgentShares(c *gin.Context) {
// @Description 返回所有共享给当前用户所在组织的智能体
// @Tags 组织
// @Produce json
// @Success 200 {object} map[string]interface{} "智能体列表 + total"
// @Success 200 {object} handler.ListSharedAgentsResponse "智能体列表 + total"
// @Failure 500 {object} apperrors.AppError "服务器错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -1718,7 +1718,7 @@ func (h *OrganizationHandler) listSpaceKnowledgeBasesInOrganization(ctx context.
// @Tags 组织管理
// @Produce json
// @Param id path string true "组织ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.ListOrganizationSharedKnowledgeBasesResponse
// @Security Bearer
// @Router /organizations/{id}/shared-knowledge-bases [get]
func (h *OrganizationHandler) ListOrganizationSharedKnowledgeBases(c *gin.Context) {
@ -1768,7 +1768,7 @@ func (h *OrganizationHandler) ListOrganizationSharedKnowledgeBases(c *gin.Contex
// @Tags 组织管理
// @Produce json
// @Param id path string true "组织ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.ListOrganizationSharedAgentsResponse
// @Security Bearer
// @Router /organizations/{id}/shared-agents [get]
func (h *OrganizationHandler) ListOrganizationSharedAgents(c *gin.Context) {
@ -1909,7 +1909,7 @@ func (h *OrganizationHandler) toOrgResponse(ctx context.Context, org *types.Orga
// @Produce json
// @Param id path string true "组织ID"
// @Param q query string true "Exact workspace ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=[]types.TenantInviteCandidate}
// @Security Bearer
// @Router /organizations/{id}/search-tenants [get]
func (h *OrganizationHandler) SearchTenantsForInvite(c *gin.Context) {
@ -1983,7 +1983,7 @@ func (h *OrganizationHandler) SearchUsersForInvite(c *gin.Context) {
// @Produce json
// @Param id path string true "组织ID"
// @Param request body types.InviteMemberRequest true "邀请信息"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.MessageResponse
// @Failure 400 {object} apperrors.AppError
// @Failure 403 {object} apperrors.AppError
// @Security Bearer

View File

@ -303,7 +303,7 @@ func (h *SandboxConfigHandler) SetWorkspacePolicy(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body sandboxConfigRequest true "Sandbox backend config"
// @Success 201 {object} map[string]interface{} "Created sandbox config"
// @Success 201 {object} handler.DataResponse{data=handler.sandboxConfigResponse} "Created sandbox config"
// @Failure 400 {object} apperrors.AppError "Invalid request or validation failure"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Security Bearer
@ -337,7 +337,7 @@ func (h *SandboxConfigHandler) Create(c *gin.Context) {
// @Tags SandboxConfig
// @Produce json
// @Param id path string true "Sandbox config ID"
// @Success 200 {object} map[string]interface{} "Sandbox config"
// @Success 200 {object} handler.DataResponse{data=handler.sandboxConfigResponse} "Sandbox config"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} apperrors.AppError "Sandbox config not found"
// @Security Bearer
@ -367,7 +367,7 @@ func (h *SandboxConfigHandler) Get(c *gin.Context) {
// @Produce json
// @Param id path string true "Sandbox config ID"
// @Param request body sandboxConfigRequest true "Updated sandbox config"
// @Success 200 {object} map[string]interface{} "Updated sandbox config"
// @Success 200 {object} handler.DataResponse{data=handler.sandboxConfigResponse} "Updated sandbox config"
// @Failure 400 {object} apperrors.AppError "Invalid request or validation failure"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} apperrors.AppError "Sandbox config not found"
@ -412,7 +412,7 @@ func (h *SandboxConfigHandler) Update(c *gin.Context) {
// @Produce json
// @Param id path string true "Sandbox config ID"
// @Param force query bool false "Force delete when inventory is unverifiable"
// @Success 200 {object} map[string]interface{} "Deletion success"
// @Success 200 {object} handler.SuccessResponse "Deletion success"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 409 {object} map[string]interface{} "Live sandboxes or unverifiable inventory"
// @Security Bearer
@ -439,7 +439,7 @@ func (h *SandboxConfigHandler) Delete(c *gin.Context) {
// @Tags SandboxConfig
// @Produce json
// @Param id path string true "Sandbox config ID"
// @Success 200 {object} map[string]interface{} "Sandbox inventory"
// @Success 200 {object} handler.DataResponse{data=service.SandboxInventory} "Sandbox inventory"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Security Bearer
// @Security ApiKeyAuth

View File

@ -190,7 +190,7 @@ func respondSkillServiceError(c *gin.Context, err error) {
// @Tags SandboxConfig
// @Produce json
// @Param id path string true "Sandbox config ID"
// @Success 200 {object} map[string]interface{} "Installed skills"
// @Success 200 {object} handler.DataResponse{data=[]handler.skillResponse} "Installed skills"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} apperrors.AppError "Sandbox config not found"
// @Security Bearer
@ -216,7 +216,7 @@ func (h *SandboxSkillHandler) List(c *gin.Context) {
// @Produce json
// @Param id path string true "Sandbox config ID"
// @Param skillId path string true "Skill ID"
// @Success 200 {object} map[string]interface{} "Installed skill"
// @Success 200 {object} handler.DataResponse{data=handler.skillResponse} "Installed skill"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} apperrors.AppError "Skill not found"
// @Security Bearer
@ -238,7 +238,7 @@ func (h *SandboxSkillHandler) Get(c *gin.Context) {
// @Produce json
// @Param id path string true "Sandbox config ID"
// @Param skillId path string true "Skill ID"
// @Success 200 {object} map[string]interface{} "Skill files"
// @Success 200 {object} handler.DataResponse{data=[]service.SkillFileEntry} "Skill files"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} apperrors.AppError "Skill or files not found"
// @Security Bearer
@ -263,7 +263,7 @@ func (h *SandboxSkillHandler) ListFiles(c *gin.Context) {
// @Param id path string true "Sandbox config ID"
// @Param skillId path string true "Skill ID"
// @Param path query string true "Skill-root-relative file path"
// @Success 200 {object} map[string]interface{} "Skill file"
// @Success 200 {object} handler.DataResponse{data=service.SkillFileContent} "Skill file"
// @Failure 400 {object} apperrors.AppError "Invalid path"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} apperrors.AppError "Skill or file not found"
@ -429,7 +429,7 @@ func (h *SandboxSkillHandler) Reinstall(c *gin.Context) {
// @Produce json
// @Param id path string true "Sandbox config ID"
// @Param skillId path string true "Skill ID"
// @Success 200 {object} map[string]interface{} "Stopped skill"
// @Success 200 {object} handler.DataResponse{data=handler.skillResponse} "Stopped skill"
// @Failure 400 {object} apperrors.AppError "Skill is not installing"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} apperrors.AppError "Skill not found"
@ -483,7 +483,7 @@ type skillPatchRequest struct {
// @Param id path string true "Sandbox config ID"
// @Param skillId path string true "Skill ID"
// @Param request body skillPatchRequest true "Fields to update"
// @Success 200 {object} map[string]interface{} "Updated skill"
// @Success 200 {object} handler.DataResponse{data=handler.skillResponse} "Updated skill"
// @Failure 400 {object} apperrors.AppError "Invalid request"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} apperrors.AppError "Skill not found"

View File

@ -1005,7 +1005,7 @@ func knowledgeSearchOptions(request *SearchKnowledgeRequest) (*types.KnowledgeSe
// @Param session_id path string true "会话ID"
// @Param request body CreateKnowledgeQARequest true "问答请求"
// @Param resource_urls query string false "文件引用形式,public 返回可加载直链" Enums(handle, public) default(handle)
// @Success 200 {object} map[string]interface{} "问答结果(SSE流)"
// @Success 200 {string} string "SSE 事件流"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -1035,7 +1035,7 @@ func (h *Handler) KnowledgeQA(c *gin.Context) {
// @Param session_id path string true "会话ID"
// @Param request body CreateKnowledgeQARequest true "问答请求"
// @Param resource_urls query string false "文件引用形式,public 返回可加载直链" Enums(handle, public) default(handle)
// @Success 200 {object} map[string]interface{} "问答结果(SSE流)"
// @Success 200 {string} string "SSE 事件流"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth

View File

@ -27,7 +27,7 @@ import (
// @Param session_id path string true "会话ID"
// @Param message_id query string true "消息ID"
// @Param resource_urls query string false "文件引用形式,public 返回可加载直链" Enums(handle, public) default(handle)
// @Success 200 {object} map[string]interface{} "流式响应"
// @Success 200 {string} string "SSE 事件流"
// @Failure 404 {object} errors.AppError "会话或消息不存在"
// @Security Bearer
// @Security ApiKeyAuth

View File

@ -171,7 +171,7 @@ func (h *SkillHandler) InstallCatalog(c *gin.Context) {
// @Description Refused while any sandbox still has an installation of this skill.
// @Tags Skills
// @Param id path string true "Catalog skill ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.SuccessResponse
// @Router /skills/catalog/{id} [delete]
func (h *SkillHandler) DeleteCatalog(c *gin.Context) {
if h.catalog == nil {
@ -193,7 +193,7 @@ func (h *SkillHandler) DeleteCatalog(c *gin.Context) {
// @Tags Skills
// @Produce json
// @Param id path string true "Catalog skill ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=[]service.SkillFileEntry}
// @Router /skills/catalog/{id}/files [get]
func (h *SkillHandler) ListCatalogFiles(c *gin.Context) {
if h.catalog == nil {
@ -216,7 +216,7 @@ func (h *SkillHandler) ListCatalogFiles(c *gin.Context) {
// @Produce json
// @Param id path string true "Catalog skill ID"
// @Param path query string true "Skill-root-relative file path"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=service.SkillFileContent}
// @Router /skills/catalog/{id}/files/content [get]
func (h *SkillHandler) GetCatalogFile(c *gin.Context) {
if h.catalog == nil {

View File

@ -70,7 +70,7 @@ type SkillInfoResponse struct {
// @Param sandbox_config_id query string false "Sandbox config ID; ignored for a shared agent"
// @Param agent_id query string false "Agent ID; needs agent_source_tenant_id"
// @Param agent_source_tenant_id query int false "Shared agent source workspace"
// @Success 200 {object} map[string]interface{} "Skills列表"
// @Success 200 {object} handler.ListSkillsResponse "Skills列表"
// @Failure 403 {object} errors.AppError "无权使用该共享智能体"
// @Security Bearer
// @Security ApiKeyAuth

View File

@ -46,7 +46,7 @@ func storageTenantID(c *gin.Context) uint64 { return c.GetUint64(types.TenantIDC
// @Description List all storage backend instances for the current workspace, with credentials masked. The workspace default backend id is returned alongside the list.
// @Tags StorageBackend
// @Produce json
// @Success 200 {object} map[string]interface{} "List of storage backends and default_storage_backend_id"
// @Success 200 {object} handler.ListResponse "List of storage backends and default_storage_backend_id"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Security Bearer
// @Security ApiKeyAuth
@ -76,7 +76,7 @@ func (h *StorageBackendHandler) List(c *gin.Context) {
// @Tags StorageBackend
// @Produce json
// @Param id path string true "Storage backend ID"
// @Success 200 {object} map[string]interface{} "Storage backend details"
// @Success 200 {object} handler.DataResponse{data=types.StorageBackend} "Storage backend details"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} apperrors.AppError "Storage backend not found"
// @Security Bearer
@ -102,7 +102,7 @@ func (h *StorageBackendHandler) Get(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body storageBackendRequest true "Storage backend configuration"
// @Success 201 {object} map[string]interface{} "Created storage backend"
// @Success 201 {object} handler.DataResponse{data=types.StorageBackend} "Created storage backend"
// @Failure 400 {object} apperrors.AppError "Invalid request, validation, or connectivity test failure"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 409 {object} apperrors.AppError "A storage backend with this name already exists"
@ -131,7 +131,7 @@ func (h *StorageBackendHandler) Create(c *gin.Context) {
// @Produce json
// @Param id path string true "Storage backend ID"
// @Param request body storageBackendRequest true "Updated storage backend fields"
// @Success 200 {object} map[string]interface{} "Updated storage backend"
// @Success 200 {object} handler.DataResponse{data=types.StorageBackend} "Updated storage backend"
// @Failure 400 {object} apperrors.AppError "Immutable field change, read-only backend, validation, or connectivity failure"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} apperrors.AppError "Storage backend not found"
@ -163,7 +163,7 @@ func (h *StorageBackendHandler) Update(c *gin.Context) {
// @Tags StorageBackend
// @Produce json
// @Param id path string true "Storage backend ID"
// @Success 200 {object} map[string]interface{} "Deletion success"
// @Success 200 {object} handler.SuccessResponse "Deletion success"
// @Failure 400 {object} apperrors.AppError "Backend is default, bound, read-only, or legacy alias"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} apperrors.AppError "Storage backend not found"
@ -184,7 +184,7 @@ func (h *StorageBackendHandler) Delete(c *gin.Context) {
// @Tags StorageBackend
// @Produce json
// @Param id path string true "Storage backend ID"
// @Success 200 {object} map[string]interface{} "Default set successfully"
// @Success 200 {object} handler.SuccessResponse "Default set successfully"
// @Failure 400 {object} apperrors.AppError "Backend is not active"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} apperrors.AppError "Storage backend not found"
@ -206,7 +206,7 @@ func (h *StorageBackendHandler) SetDefault(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body storageBackendRequest true "Storage backend configuration to test"
// @Success 200 {object} map[string]interface{} "Connectivity test result (success, error)"
// @Success 200 {object} handler.SuccessErrorResponse "Connectivity test result (success, error)"
// @Failure 400 {object} apperrors.AppError "Invalid request or validation error"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Security Bearer
@ -236,7 +236,7 @@ func (h *StorageBackendHandler) TestRaw(c *gin.Context) {
// @Tags StorageBackend
// @Produce json
// @Param id path string true "Storage backend ID"
// @Success 200 {object} map[string]interface{} "Connectivity test result (success, error)"
// @Success 200 {object} handler.SuccessErrorResponse "Connectivity test result (success, error)"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} apperrors.AppError "Storage backend not found"
// @Security Bearer
@ -264,7 +264,7 @@ func (h *StorageBackendHandler) TestByID(c *gin.Context) {
// @Description Return the storage provider types allowed by STORAGE_ALLOW_LIST for UI form generation (e.g. local, minio, cos, tos, s3, oss, ks3, obs).
// @Tags StorageBackend
// @Produce json
// @Success 200 {object} map[string]interface{} "List of allowed storage provider types"
// @Success 200 {object} handler.DataResponse{data=[]string} "List of allowed storage provider types"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /storage-backends/types [get]

View File

@ -0,0 +1,314 @@
package handler
// Concrete response bodies for Swagger. Handlers still write these
// shapes with gin.H; the structs exist so the documented JSON matches.
import (
"github.com/Tencent/WeKnora/internal/handler/dto"
"github.com/Tencent/WeKnora/internal/im"
"github.com/Tencent/WeKnora/internal/types"
)
// RefreshTokenResponse is the JSON body written by this handler.
type RefreshTokenResponse struct {
Success bool `json:"success" example:"true"`
Message string `json:"message"`
AccessToken string `json:"access_token"`
RefreshToken string `json:"refresh_token"`
}
// GetAuthConfigResponse is the JSON body written by this handler.
type GetAuthConfigResponse struct {
Success bool `json:"success" example:"true"`
RegistrationMode string `json:"registration_mode"`
ComplexPasswordEnabled bool `json:"complex_password_enabled"`
}
// ValidateTokenResponse is the JSON body written by this handler.
type ValidateTokenResponse struct {
Success bool `json:"success" example:"true"`
Message string `json:"message"`
User types.UserInfo `json:"user"`
}
// UpdateChunkResponse is the JSON body written by this handler.
type UpdateChunkResponse struct {
Success bool `json:"success" example:"true"`
Data types.Chunk `json:"data"`
SummaryStatus string `json:"summary_status"`
Description string `json:"description"`
}
// ListAgentsResponse is the JSON body written by this handler.
type ListAgentsResponse struct {
Data []types.CustomAgent `json:"data"`
DisabledOwnAgentIDs []string `json:"disabled_own_agent_ids"`
Success bool `json:"success" example:"true"`
}
// GetDeploymentCapabilitiesResponse is the JSON body written by this handler.
type GetDeploymentCapabilitiesResponse struct {
Code int `json:"code"`
Msg string `json:"msg"`
Data DeploymentCapabilitiesData `json:"data"`
}
// SuccessResponse is the JSON body written by this handler.
type SuccessResponse struct {
Success bool `json:"success" example:"true"`
}
// UpdateIMChannelResponse is the JSON body written by this handler.
type UpdateIMChannelResponse struct {
Data im.IMChannel `json:"data"`
}
// UpdateKnowledgeResponse is the JSON body written by this handler.
type UpdateKnowledgeResponse struct {
Message string `json:"message"`
Data types.Knowledge `json:"data"`
Success bool `json:"success" example:"true"`
}
// KnowledgeSearchKnowledgeResponse is the JSON body written by this handler.
type KnowledgeSearchKnowledgeResponse struct {
Total int `json:"total"`
Success bool `json:"success" example:"true"`
Data []types.Knowledge `json:"data"`
HasMore bool `json:"has_more"`
}
// ListItemsResponse is the JSON body written by this handler.
type ListItemsResponse struct {
Total int `json:"total"`
Success bool `json:"success" example:"true"`
Data []types.MemoryItem `json:"data"`
}
// ListTopicsResponse is the JSON body written by this handler.
type ListTopicsResponse struct {
Success bool `json:"success" example:"true"`
Data []types.MemoryTopicView `json:"data"`
Total int `json:"total"`
}
// ListDocumentsResponse is the JSON body written by this handler.
type ListDocumentsResponse struct {
Total int `json:"total"`
Success bool `json:"success" example:"true"`
Data []types.MemoryDocView `json:"data"`
}
// ClearResponse is the JSON body written by this handler.
type ClearResponse struct {
Success bool `json:"success" example:"true"`
Removed int `json:"removed"`
}
// ExportResponse is the JSON body written by this handler.
type ExportResponse struct {
Data []types.MemoryItem `json:"data"`
Success bool `json:"success" example:"true"`
Total int `json:"total"`
Truncated bool `json:"truncated"`
}
// SearchOrganizationsResponse is the JSON body written by this handler.
type SearchOrganizationsResponse struct {
Success bool `json:"success" example:"true"`
Data []types.SearchableOrganizationItem `json:"data"`
Total int `json:"total"`
}
// ListSharedKnowledgeBasesResponse is the JSON body written by this handler.
type ListSharedKnowledgeBasesResponse struct {
Total int `json:"total"`
Success bool `json:"success" example:"true"`
Data []map[string]any `json:"data"`
}
// ListSharedAgentsResponse is the JSON body written by this handler.
type ListSharedAgentsResponse struct {
Success bool `json:"success" example:"true"`
Data []types.SharedAgentInfo `json:"data"`
Total int `json:"total"`
}
// ListOrganizationSharedKnowledgeBasesResponse is the JSON body written by this handler.
type ListOrganizationSharedKnowledgeBasesResponse struct {
Success bool `json:"success" example:"true"`
Data []map[string]any `json:"data"`
Total int `json:"total"`
}
// ListOrganizationSharedAgentsResponse is the JSON body written by this handler.
type ListOrganizationSharedAgentsResponse struct {
Success bool `json:"success" example:"true"`
Data []types.OrganizationSharedAgentItem `json:"data"`
Total int `json:"total"`
}
// ListSkillsResponse is the JSON body written by this handler.
type ListSkillsResponse struct {
Success bool `json:"success" example:"true"`
Data []SkillInfoResponse `json:"data"`
SkillsAvailable bool `json:"skills_available"`
}
// ListResponse is the JSON body written by this handler.
type ListResponse struct {
Success bool `json:"success" example:"true"`
Data []types.StorageBackend `json:"data"`
DefaultStorageBackendID string `json:"default_storage_backend_id"`
}
// SuccessErrorResponse is the JSON body written by this handler.
type SuccessErrorResponse struct {
Success bool `json:"success" example:"true"`
Error string `json:"error,omitempty"`
}
// ListParserEnginesResponse is the JSON body written by this handler.
type ListParserEnginesResponse struct {
DocreaderTransport string `json:"docreader_transport"`
Connected bool `json:"connected"`
Code int `json:"code"`
Msg string `json:"msg"`
Data []types.ParserEngineInfo `json:"data"`
DocreaderAddr string `json:"docreader_addr"`
}
// SetUserStatusResponse is the JSON body written by this handler.
type SetUserStatusResponse struct {
User types.UserInfo `json:"user"`
IsActive bool `json:"is_active"`
Message string `json:"message"`
}
// ResetUserPasswordResponse is the JSON body written by this handler.
type ResetUserPasswordResponse struct {
Message string `json:"message"`
}
// PurgeArchivedRuntimeTasksResponse is the JSON body written by this handler.
type PurgeArchivedRuntimeTasksResponse struct {
Success bool `json:"success" example:"true"`
Deleted int `json:"deleted"`
}
// ApplyDefaultStorageQuotaToAllTenantsResponse is the JSON body written by this handler.
type ApplyDefaultStorageQuotaToAllTenantsResponse struct {
Affected int `json:"affected"`
QuotaBytes int `json:"quota_bytes"`
QuotaGb int `json:"quota_gb"`
}
// TestStoreByIDResponse is the JSON body written by this handler.
type TestStoreByIDResponse struct {
Error string `json:"error,omitempty"`
Version string `json:"version"`
Success bool `json:"success" example:"true"`
}
// TestStoreRawResponse is the JSON body written by this handler.
type TestStoreRawResponse struct {
Success bool `json:"success" example:"true"`
Error string `json:"error,omitempty"`
Version string `json:"version"`
}
// AutoFixResponse is the JSON body written by this handler.
type AutoFixResponse struct {
Fixed int `json:"fixed"`
Message string `json:"message"`
}
// FolderMoveData is the data object of a knowledge-folder move or rename.
type FolderMoveData struct {
MovedCount int `json:"moved_count"`
FolderPath string `json:"folder_path"`
}
// SubmittedTaskData is the data object of an async knowledge batch task.
// task_id is omitted when the knowledge base was already empty.
type SubmittedTaskData struct {
TaskID string `json:"task_id,omitempty"`
DeletedCount int `json:"deleted_count,omitempty"`
ReparseCount int `json:"reparse_count,omitempty"`
}
// SubmittedTaskResponse is success, message, and SubmittedTaskData.
type SubmittedTaskResponse struct {
Success bool `json:"success" example:"true"`
Message string `json:"message"`
Data SubmittedTaskData `json:"data"`
}
// TaskIDData is a task id payload.
type TaskIDData struct {
TaskID string `json:"task_id"`
}
// AllowedToolsWarningsDoc mirrors allowedToolsWarnings for Swagger.
type AllowedToolsWarningsDoc struct {
KeptUnknown []string `json:"kept_unknown,omitempty"`
Dropped []string `json:"dropped,omitempty"`
}
// AgentWriteResponse is the create/update agent body.
// allowed_tools_warnings is present only when saving rewrote the tool list.
type AgentWriteResponse struct {
Success bool `json:"success" example:"true"`
Data types.CustomAgent `json:"data"`
AllowedToolsWarnings *AllowedToolsWarningsDoc `json:"allowed_tools_warnings,omitempty"`
}
// PlaceholderGroups is the data object of GET /agents/placeholders.
type PlaceholderGroups struct {
All []types.PromptPlaceholder `json:"all"`
SystemPrompt []types.PromptPlaceholder `json:"system_prompt"`
AgentSystemPrompt []types.PromptPlaceholder `json:"agent_system_prompt"`
ContextTemplate []types.PromptPlaceholder `json:"context_template"`
RewriteSystemPrompt []types.PromptPlaceholder `json:"rewrite_system_prompt"`
RewritePrompt []types.PromptPlaceholder `json:"rewrite_prompt"`
FallbackPrompt []types.PromptPlaceholder `json:"fallback_prompt"`
}
// SuggestedQuestionsData is the data object of suggested questions.
type SuggestedQuestionsData struct {
Questions []types.SuggestedQuestion `json:"questions"`
}
// PreferenceDefaults is the preference_defaults object on GET /auth/me.
type PreferenceDefaults struct {
BrowserSearchInstructions string `json:"browser_search_instructions"`
}
// CurrentUserCapabilities is the capabilities object on GET /auth/me.
type CurrentUserCapabilities struct {
CanCreateTenant bool `json:"can_create_tenant"`
AutoAcceptInvitation bool `json:"auto_accept_invitation"`
}
// CurrentUserData is the data object of GET /auth/me.
type CurrentUserData struct {
User types.UserInfo `json:"user"`
PreferenceDefaults PreferenceDefaults `json:"preference_defaults"`
Tenant *dto.TenantResponse `json:"tenant"`
Memberships []types.Membership `json:"memberships"`
TenantRequired bool `json:"tenant_required"`
Capabilities CurrentUserCapabilities `json:"capabilities"`
}
// TenantListData is the data object of tenant list endpoints.
type TenantListData struct {
Items []*dto.TenantResponse `json:"items"`
}
// TenantSearchData is the data object of GET /tenants/search.
type TenantSearchData struct {
Items []*dto.TenantResponse `json:"items"`
Total int64 `json:"total"`
Page int `json:"page"`
PageSize int `json:"page_size"`
}

View File

@ -0,0 +1,36 @@
package handler
// Response envelopes for Swagger annotations. Handlers write these shapes
// with gin.H; the types only exist so the documented body matches. Compose
// the payload in the annotation, e.g.
//
// @Success 200 {object} handler.DataResponse{data=types.Knowledge}
// @Success 200 {object} handler.PageResponse{data=[]types.Knowledge}
// DataResponse is the {"success": true, "data": ...} body.
type DataResponse struct {
Success bool `json:"success" example:"true"`
Data any `json:"data"`
}
// PageResponse is a page of a list with the total match count.
type PageResponse struct {
Success bool `json:"success" example:"true"`
Data any `json:"data"`
Total int64 `json:"total"`
Page int `json:"page"`
PageSize int `json:"page_size"`
}
// DataMessageResponse is DataResponse with a human-readable message.
type DataMessageResponse struct {
Success bool `json:"success" example:"true"`
Message string `json:"message"`
Data any `json:"data"`
}
// MessageResponse is the {"success": true, "message": ...} body.
type MessageResponse struct {
Success bool `json:"success" example:"true"`
Message string `json:"message"`
}

View File

@ -112,7 +112,7 @@ type platformAPIKeyCreateRequest struct {
// @Description Lists non-workspace API keys. Full tokens are always masked. Human SystemAdmin only.
// @Tags System Admin
// @Produce json
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=[]handler.tenantAPIKeyResponse}
// @Security Bearer
// @Router /system/admin/api-keys [get]
func (h *SystemHandler) ListPlatformAPIKeys(c *gin.Context) {
@ -137,7 +137,7 @@ func (h *SystemHandler) ListPlatformAPIKeys(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body platformAPIKeyCreateRequest true "Platform API key"
// @Success 201 {object} map[string]interface{}
// @Success 201 {object} handler.DataResponse{data=handler.tenantAPIKeyCreateResponse}
// @Security Bearer
// @Router /system/admin/api-keys [post]
func (h *SystemHandler) CreatePlatformAPIKey(c *gin.Context) {
@ -189,7 +189,7 @@ func (h *SystemHandler) CreatePlatformAPIKey(c *gin.Context) {
// @Tags System Admin
// @Produce json
// @Param key_id path int true "API key ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.SuccessResponse
// @Security Bearer
// @Router /system/admin/api-keys/{key_id} [delete]
func (h *SystemHandler) DeletePlatformAPIKey(c *gin.Context) {
@ -398,7 +398,7 @@ func (h *SystemHandler) getDocReaderConnInfo() (addr, transport string) {
// @Summary 列出可用的文档解析引擎
// @Tags 系统
// @Produce json
// @Success 200 {object} map[string]interface{} "解析引擎列表"
// @Success 200 {object} handler.ListParserEnginesResponse "解析引擎列表"
// @Router /system/parser-engines [get]
func (h *SystemHandler) ListParserEngines(c *gin.Context) {
var overrides map[string]string
@ -1598,7 +1598,7 @@ type SetUserStatusRequest struct {
// @Accept json
// @Produce json
// @Param request body SetUserStatusRequest true "Account status request"
// @Success 200 {object} map[string]interface{} "Status updated"
// @Success 200 {object} handler.SetUserStatusResponse "Status updated"
// @Failure 400 {object} map[string]interface{} "Self-disable / last-admin guard"
// @Failure 404 {object} map[string]interface{} "User not found"
// @Router /system/admin/users/status [post]
@ -1651,7 +1651,7 @@ type ResetUserPasswordRequest struct {
// @Accept json
// @Produce json
// @Param request body ResetUserPasswordRequest true "Password reset request"
// @Success 200 {object} map[string]interface{} "Password reset successfully"
// @Success 200 {object} handler.ResetUserPasswordResponse "Password reset successfully"
// @Failure 400 {object} map[string]interface{} "Invalid request, weak password, or self reset"
// @Failure 403 {object} map[string]interface{} "Forbidden: not a system admin"
// @Failure 404 {object} map[string]interface{} "User not found"
@ -2241,7 +2241,7 @@ func (h *SystemHandler) MutateRuntimeTask(c *gin.Context) {
// @Tags System Admin
// @Produce json
// @Param queue path string true "Queue name"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.PurgeArchivedRuntimeTasksResponse
// @Router /system/admin/runtime/queues/{queue}/archived [delete]
func (h *SystemHandler) PurgeArchivedRuntimeTasks(c *gin.Context) {
queue := c.Param("queue")
@ -2425,7 +2425,7 @@ func (h *SystemHandler) UpdateSystemSetting(c *gin.Context) {
// @Description Idempotent — running twice with the same setting is a no-op.
// @Tags System Admin
// @Produce json
// @Success 200 {object} map[string]interface{} "{ affected: int64, quota_bytes: int64 }"
// @Success 200 {object} handler.ApplyDefaultStorageQuotaToAllTenantsResponse "{ affected: int64, quota_bytes: int64 }"
// @Failure 500 {object} map[string]interface{} "DB write failed"
// @Router /system/admin/tenants/apply-default-storage-quota [post]
func (h *SystemHandler) ApplyDefaultStorageQuotaToAllTenants(c *gin.Context) {
@ -2488,7 +2488,7 @@ func (h *SystemHandler) ApplyDefaultStorageQuotaToAllTenants(c *gin.Context) {
// @Description that was never persisted returns 200.
// @Tags System Admin
// @Param key path string true "Setting key"
// @Success 200 {object} map[string]interface{} "Reset acknowledged"
// @Success 200 {object} handler.SuccessResponse "Reset acknowledged"
// @Failure 400 {object} map[string]interface{} "Unknown key"
// @Failure 500 {object} map[string]interface{} "DB write failed"
// @Router /system/admin/settings/{key} [delete]

View File

@ -79,7 +79,7 @@ func (h *TagHandler) getChunksBySeqIDs(ctx context.Context, tenantID uint64, seq
// @Param page query int false "页码"
// @Param page_size query int false "每页数量"
// @Param keyword query string false "关键词搜索"
// @Success 200 {object} map[string]interface{} "标签列表"
// @Success 200 {object} handler.DataResponse{data=types.PageResult} "标签列表"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -124,7 +124,7 @@ type createTagRequest struct {
// @Produce json
// @Param id path string true "知识库ID"
// @Param request body object{name=string,color=string,sort_order=int} true "标签信息"
// @Success 200 {object} map[string]interface{} "创建的标签"
// @Success 200 {object} handler.DataResponse{data=types.KnowledgeTag} "创建的标签"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -171,7 +171,7 @@ type updateTagRequest struct {
// @Param id path string true "知识库ID"
// @Param tag_id path string true "标签ID (UUID或seq_id)"
// @Param request body object true "标签更新信息"
// @Success 200 {object} map[string]interface{} "更新后的标签"
// @Success 200 {object} handler.DataResponse{data=types.KnowledgeTag} "更新后的标签"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -218,7 +218,7 @@ func (h *TagHandler) UpdateTag(c *gin.Context) {
// @Param force query bool false "强制删除"
// @Param content_only query bool false "仅删除内容,保留标签"
// @Param body body DeleteTagRequest false "删除选项"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.SuccessResponse "删除成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth

View File

@ -532,7 +532,7 @@ func (h *TenantHandler) autoCreateTenantAPIKey(ctx context.Context) bool {
// @Accept json
// @Produce json
// @Param id path int true "空间ID"
// @Success 200 {object} map[string]interface{} "空间详情"
// @Success 200 {object} handler.DataResponse{data=dto.TenantResponse} "空间详情"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 404 {object} errors.AppError "空间不存在"
// @Security Bearer
@ -574,7 +574,7 @@ func (h *TenantHandler) GetTenant(c *gin.Context) {
// @Produce json
// @Param id path int true "空间ID"
// @Param request body types.Tenant true "空间信息"
// @Success 200 {object} map[string]interface{} "更新后的空间"
// @Success 200 {object} handler.DataResponse{data=dto.TenantResponse} "更新后的空间"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Router /tenants/{id} [put]
@ -890,7 +890,7 @@ func apiPrincipalConfigForResponse(cfg *types.APIPrincipalConfig) apiPrincipalCo
// @Accept json
// @Produce json
// @Param id path int true "空间ID"
// @Success 200 {object} map[string]interface{} "API principal 配置"
// @Success 200 {object} handler.DataResponse{data=handler.apiPrincipalConfigResponse} "API principal 配置"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "权限不足"
// @Security Bearer
@ -925,7 +925,7 @@ func (h *TenantHandler) GetAPIPrincipalConfig(c *gin.Context) {
// @Produce json
// @Param id path int true "空间ID"
// @Param request body handler.apiPrincipalConfigRequest true "API principal 配置"
// @Success 200 {object} map[string]interface{} "更新后的配置"
// @Success 200 {object} handler.DataResponse{data=handler.apiPrincipalConfigResponse} "更新后的配置"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "权限不足"
// @Security Bearer
@ -1013,7 +1013,7 @@ func (h *TenantHandler) UpdateAPIPrincipalConfig(c *gin.Context) {
// @Produce json
// @Param id path int true "空间ID"
// @Param request body handler.apiPrincipalTestTokenRequest true "测试 Token 参数"
// @Success 200 {object} map[string]interface{} "短期 JWT"
// @Success 200 {object} handler.DataResponse{data=handler.apiPrincipalTestTokenResponse} "短期 JWT"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Failure 403 {object} errors.AppError "权限不足"
// @Security Bearer
@ -1116,7 +1116,7 @@ func validateAPIPrincipalExternalUserID(id string) error {
// @Accept json
// @Produce json
// @Param id path int true "空间ID"
// @Success 200 {object} map[string]interface{} "删除成功"
// @Success 200 {object} handler.MessageResponse "删除成功"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Router /tenants/{id} [delete]
@ -1158,7 +1158,7 @@ func (h *TenantHandler) DeleteTenant(c *gin.Context) {
// @Tags 空间管理
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "空间列表"
// @Success 200 {object} handler.DataResponse{data=handler.TenantListData} "空间列表"
// @Failure 500 {object} errors.AppError "服务器错误"
// @Security Bearer
// @Router /tenants [get]
@ -1185,7 +1185,7 @@ func (h *TenantHandler) ListTenants(c *gin.Context) {
// @Tags 空间管理
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "所有空间列表"
// @Success 200 {object} handler.DataResponse{data=handler.TenantListData} "所有空间列表"
// @Failure 403 {object} errors.AppError "权限不足"
// @Security Bearer
// @Router /tenants/all [get]
@ -1225,8 +1225,8 @@ func (h *TenantHandler) ListAllTenants(c *gin.Context) {
// @Param keyword query string false "搜索关键词"
// @Param tenant_id query int false "空间ID筛选"
// @Param page query int false "页码" default(1)
// @Param page_size query int false "每页数量" default(20)
// @Success 200 {object} map[string]interface{} "搜索结果"
// @Param page_size query int false "每页数量" default(20) minimum(1) maximum(100)
// @Success 200 {object} handler.DataResponse{data=handler.TenantSearchData} "搜索结果"
// @Failure 403 {object} errors.AppError "权限不足"
// @Security Bearer
// @Security ApiKeyAuth
@ -1445,7 +1445,7 @@ func (h *TenantHandler) updateTenantWebSearchConfigInternal(c *gin.Context) {
// @Tags 空间管理
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "网络搜索配置"
// @Success 200 {object} handler.DataResponse{data=types.WebSearchConfig} "网络搜索配置"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -1597,7 +1597,7 @@ func (h *TenantHandler) updateTenantStorageEngineConfigInternal(c *gin.Context)
// @Tags 空间管理
// @Accept json
// @Produce json
// @Success 200 {object} map[string]interface{} "提示词模板配置"
// @Success 200 {object} handler.DataResponse{data=config.PromptTemplatesConfig} "提示词模板配置"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth

View File

@ -259,7 +259,7 @@ func (h *TenantInvitationHandler) ListTenantInvitations(c *gin.Context) {
// @Produce json
// @Param id path string true "空间 ID"
// @Param request body createInvitationRequest true "邀请请求"
// @Success 201 {object} map[string]interface{}
// @Success 201 {object} handler.DataResponse{data=types.TenantInvitationResponse}
// @Security Bearer
// @Router /tenants/{id}/invitations [post]
func (h *TenantInvitationHandler) CreateInvitation(c *gin.Context) {
@ -390,7 +390,7 @@ func (h *TenantInvitationHandler) autoAcceptInvitationAndRespond(
// @Produce json
// @Param id path string true "空间 ID"
// @Param inv_id path string true "邀请 ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.SuccessResponse
// @Security Bearer
// @Router /tenants/{id}/invitations/{inv_id} [delete]
func (h *TenantInvitationHandler) RevokeInvitation(c *gin.Context) {
@ -667,7 +667,7 @@ func (h *TenantInvitationHandler) AcceptMyInvitationByToken(c *gin.Context) {
// @Tags 我的邀请
// @Produce json
// @Param inv_id path string true "邀请 ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.SuccessResponse
// @Security Bearer
// @Router /me/invitations/{inv_id}/decline [post]
func (h *TenantInvitationHandler) DeclineMyInvitation(c *gin.Context) {

View File

@ -63,7 +63,7 @@ type createInviteLinkRequest struct {
// @Produce json
// @Param id path string true "空间 ID"
// @Param request body createInviteLinkRequest true "共享链接配置"
// @Success 201 {object} map[string]interface{}
// @Success 201 {object} handler.DataResponse{data=types.TenantInvitationResponse}
// @Security Bearer
// @Router /tenants/{id}/invite-links [post]
func (h *TenantInvitationHandler) CreateInviteLink(c *gin.Context) {

View File

@ -314,7 +314,7 @@ func addMemberAndRespond(
// @Param id path string true "空间 ID"
// @Param user_id path string true "用户 ID"
// @Param request body updateMemberRoleRequest true "目标角色"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.SuccessResponse
// @Security Bearer
// @Router /tenants/{id}/members/{user_id} [put]
func (h *TenantMemberHandler) UpdateMemberRole(c *gin.Context) {
@ -367,7 +367,7 @@ func (h *TenantMemberHandler) UpdateMemberRole(c *gin.Context) {
// @Produce json
// @Param id path string true "空间 ID"
// @Param user_id path string true "用户 ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.SuccessResponse
// @Security Bearer
// @Router /tenants/{id}/members/{user_id} [delete]
func (h *TenantMemberHandler) RemoveMember(c *gin.Context) {
@ -409,7 +409,7 @@ func (h *TenantMemberHandler) RemoveMember(c *gin.Context) {
// @Tags 空间成员
// @Produce json
// @Param id path string true "空间 ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.SuccessResponse
// @Security Bearer
// @Router /tenants/{id}/leave [post]
func (h *TenantMemberHandler) LeaveTenant(c *gin.Context) {

View File

@ -55,7 +55,7 @@ func favoriteContext(c *gin.Context) (string, uint64, bool) {
// @Description Lists this user's starred resources in the current workspace for a given type
// @Tags User
// @Param type query string true "Resource type (kb | agent)"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=[]types.UserResourceFavorite}
// @Router /user/favorites [get]
func (h *UserResourceFavoriteHandler) ListFavorites(c *gin.Context) {
ctx := c.Request.Context()
@ -90,7 +90,7 @@ type AddFavoriteRequest struct {
// @Summary Star a resource
// @Tags User
// @Param body body AddFavoriteRequest true "Type + id"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.SuccessResponse
// @Router /user/favorites [post]
func (h *UserResourceFavoriteHandler) AddFavorite(c *gin.Context) {
ctx := c.Request.Context()
@ -120,7 +120,7 @@ func (h *UserResourceFavoriteHandler) AddFavorite(c *gin.Context) {
// @Tags User
// @Param type path string true "Resource type"
// @Param id path string true "Resource id"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.SuccessResponse
// @Router /user/favorites/{type}/{id} [delete]
func (h *UserResourceFavoriteHandler) RemoveFavorite(c *gin.Context) {
ctx := c.Request.Context()

View File

@ -84,7 +84,7 @@ func envStoreReadonlyError() gin.H {
// @Accept json
// @Produce json
// @Param request body CreateStoreRequest true "Vector store configuration"
// @Success 201 {object} map[string]interface{} "Created vector store"
// @Success 201 {object} handler.DataResponse{data=types.VectorStoreResponse} "Created vector store"
// @Failure 400 {object} errors.AppError "Invalid request or validation error"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 409 {object} errors.AppError "Duplicate endpoint and index"
@ -132,7 +132,7 @@ func (h *VectorStoreHandler) CreateStore(c *gin.Context) {
// @Description List all vector stores for the current workspace, including environment-configured and user-created stores
// @Tags VectorStore
// @Produce json
// @Success 200 {object} map[string]interface{} "List of vector stores (env + DB)"
// @Success 200 {object} handler.DataResponse{data=[]types.VectorStoreResponse} "List of vector stores (env + DB)"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Security Bearer
// @Security ApiKeyAuth
@ -178,7 +178,7 @@ func (h *VectorStoreHandler) ListStores(c *gin.Context) {
// @Tags VectorStore
// @Produce json
// @Param id path string true "Vector store ID"
// @Success 200 {object} map[string]interface{} "Vector store details"
// @Success 200 {object} handler.DataResponse{data=types.VectorStoreResponse} "Vector store details"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} map[string]interface{} "Vector store not found"
// @Security Bearer
@ -299,7 +299,7 @@ func (h *VectorStoreHandler) UpdateStore(c *gin.Context) {
// @Tags VectorStore
// @Produce json
// @Param id path string true "Vector store ID"
// @Success 200 {object} map[string]interface{} "Deletion success"
// @Success 200 {object} handler.SuccessResponse "Deletion success"
// @Failure 400 {object} map[string]interface{} "Env store cannot be deleted"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} map[string]interface{} "Vector store not found"
@ -343,7 +343,7 @@ func (h *VectorStoreHandler) DeleteStore(c *gin.Context) {
// @Description Return supported engine types with connection and index field schemas for UI form generation
// @Tags VectorStore
// @Produce json
// @Success 200 {object} map[string]interface{} "List of engine types with config schemas"
// @Success 200 {object} handler.DataResponse{data=[]types.VectorStoreTypeInfo}
// @Router /vector-stores/types [get]
func (h *VectorStoreHandler) ListStoreTypes(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{
@ -358,7 +358,7 @@ func (h *VectorStoreHandler) ListStoreTypes(c *gin.Context) {
// @Tags VectorStore
// @Produce json
// @Param id path string true "Vector store ID"
// @Success 200 {object} map[string]interface{} "Connection test result (success, version)"
// @Success 200 {object} handler.TestStoreByIDResponse "Connection test result (success, version)"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Failure 404 {object} map[string]interface{} "Vector store not found"
// @Security Bearer
@ -423,7 +423,7 @@ func (h *VectorStoreHandler) TestStoreByID(c *gin.Context) {
// @Accept json
// @Produce json
// @Param request body TestStoreRequest true "Engine type and connection config"
// @Success 200 {object} map[string]interface{} "Connection test result (success, version)"
// @Success 200 {object} handler.TestStoreRawResponse "Connection test result (success, version)"
// @Failure 400 {object} errors.AppError "Invalid request"
// @Failure 401 {object} map[string]interface{} "Unauthorized"
// @Security Bearer

View File

@ -22,7 +22,7 @@ func NewWebSearchHandler() *WebSearchHandler {
// @Description 返回所有已注册的网络搜索 provider(含元数据)
// @Tags 网络搜索
// @Produce json
// @Success 200 {object} map[string]interface{} "provider 列表"
// @Success 200 {object} handler.DataResponse{data=[]types.WebSearchProviderTypeInfo} "provider 列表"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /web-search/providers [get]

View File

@ -277,7 +277,7 @@ func (h *WebSearchProviderHandler) UpdateProvider(c *gin.Context) {
// @Tags 网络搜索
// @Produce json
// @Param id path string true "Provider ID"
// @Success 200 {object} map[string]interface{} "success: true"
// @Success 200 {object} handler.SuccessResponse "success: true"
// @Failure 404 {object} map[string]interface{} "Provider 不存在"
// @Security Bearer
// @Security ApiKeyAuth
@ -315,7 +315,7 @@ func (h *WebSearchProviderHandler) DeleteProvider(c *gin.Context) {
// @Description 返回 UI 表单需要的 provider 类型及参数定义
// @Tags 网络搜索
// @Produce json
// @Success 200 {object} map[string]interface{} "provider 类型列表"
// @Success 200 {object} handler.DataResponse{data=[]types.WebSearchProviderTypeInfo} "provider 类型列表"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /web-search-providers/types [get]
@ -334,7 +334,7 @@ func (h *WebSearchProviderHandler) ListProviderTypes(c *gin.Context) {
// @Tags 网络搜索
// @Produce json
// @Param id path string true "Provider ID"
// @Success 200 {object} map[string]interface{} "测试结果"
// @Success 200 {object} handler.SuccessErrorResponse "测试结果"
// @Failure 404 {object} map[string]interface{} "Provider 不存在"
// @Security Bearer
// @Security ApiKeyAuth
@ -379,7 +379,7 @@ type TestProviderRequest struct {
// @Accept json
// @Produce json
// @Param request body handler.TestProviderRequest true "{provider, parameters}"
// @Success 200 {object} map[string]interface{} "测试结果"
// @Success 200 {object} handler.SuccessErrorResponse "测试结果"
// @Failure 400 {object} map[string]interface{} "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth

View File

@ -3,10 +3,14 @@ package handler
import (
"net/http"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
"github.com/gin-gonic/gin"
)
// Keeps types imported so swag can resolve WeKnoraCloudStatusResult.
var _ types.WeKnoraCloudStatusResult
// WeKnoraCloudHandler 处理 WeKnoraCloud 凭证管理
type WeKnoraCloudHandler struct {
svc interfaces.WeKnoraCloudService
@ -32,7 +36,7 @@ type weKnoraCloudCredentialsRequest struct {
// @Accept json
// @Produce json
// @Param request body map[string]interface{} true "{app_id, app_secret}"
// @Success 200 {object} map[string]interface{} "success: true"
// @Success 200 {object} handler.MessageResponse "success: true"
// @Failure 400 {object} map[string]interface{} "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
@ -60,7 +64,7 @@ func (h *WeKnoraCloudHandler) SaveCredentials(c *gin.Context) {
// @Description 检查当前空间的 WeKnoraCloud 凭证是否完好;needs_reinit=true 表示需要重新保存
// @Tags WeKnoraCloud
// @Produce json
// @Success 200 {object} map[string]interface{} "凭证状态"
// @Success 200 {object} types.WeKnoraCloudStatusResult "凭证状态"
// @Failure 500 {object} map[string]interface{} "服务器错误"
// @Security Bearer
// @Security ApiKeyAuth

View File

@ -895,6 +895,17 @@ func (h *WikiPageHandler) GetGraph(c *gin.Context) {
c.JSON(http.StatusOK, graph)
}
// WikiMessageResponse is the {"message": ...} body Wiki maintenance endpoints
// write on success.
type WikiMessageResponse struct {
Message string `json:"message"`
}
// WikiErrorResponse is the {"error": ...} body Wiki endpoints write on failure.
type WikiErrorResponse struct {
Error string `json:"error"`
}
// GetStats godoc
// @Summary Get wiki statistics
// @Description Returns aggregate statistics about the wiki
@ -902,6 +913,8 @@ func (h *WikiPageHandler) GetGraph(c *gin.Context) {
// @Produce json
// @Param kb_id path string true "Knowledge base ID"
// @Success 200 {object} types.WikiStats
// @Failure 400 {object} handler.WikiErrorResponse "Not a Wiki knowledge base, or no access"
// @Failure 500 {object} handler.WikiErrorResponse
// @Security Bearer
// @Router /knowledgebase/{kb_id}/wiki/stats [get]
func (h *WikiPageHandler) GetStats(c *gin.Context) {
@ -927,8 +940,10 @@ func (h *WikiPageHandler) GetStats(c *gin.Context) {
// @Produce json
// @Param kb_id path string true "Knowledge base ID"
// @Param slug query string false "Filter by page slug"
// @Param status query string false "Filter by status (pending, ignored, resolved)"
// @Success 200 {array} types.WikiPageIssue
// @Param status query string false "Filter by status" Enums(pending, ignored, resolved)
// @Success 200 {array} types.WikiPageIssue
// @Failure 400 {object} handler.WikiErrorResponse "Not a Wiki knowledge base, or no access"
// @Failure 500 {object} handler.WikiErrorResponse
// @Security Bearer
// @Router /knowledgebase/{kb_id}/wiki/issues [get]
func (h *WikiPageHandler) ListIssues(c *gin.Context) {
@ -1065,7 +1080,7 @@ type WikiSearchHit struct {
// @Accept json
// @Produce json
// @Param request body SearchWikiRequest true "Wiki search request"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.DataResponse{data=[]handler.WikiSearchHit}
// @Failure 400 {object} errors.AppError
// @Security Bearer
// @Security ApiKeyAuth
@ -1153,8 +1168,11 @@ func mergeWikiSearchKBIDs(ids []string, single string) []string {
// @Summary Rebuild wiki links
// @Description Re-parse all pages and rebuild bidirectional link references
// @Tags Wiki
// @Produce json
// @Param kb_id path string true "Knowledge base ID"
// @Success 200 {object} map[string]string
// @Success 200 {object} handler.WikiMessageResponse
// @Failure 400 {object} handler.WikiErrorResponse "Not a Wiki knowledge base, or no access"
// @Failure 500 {object} handler.WikiErrorResponse
// @Security Bearer
// @Router /knowledgebase/{kb_id}/wiki/rebuild-links [post]
func (h *WikiPageHandler) RebuildLinks(c *gin.Context) {
@ -1179,6 +1197,8 @@ func (h *WikiPageHandler) RebuildLinks(c *gin.Context) {
// @Produce json
// @Param kb_id path string true "Knowledge base ID"
// @Success 200 {object} service.WikiLintReport
// @Failure 400 {object} handler.WikiErrorResponse "Not a Wiki knowledge base, or no access"
// @Failure 500 {object} handler.WikiErrorResponse
// @Security Bearer
// @Router /knowledgebase/{kb_id}/wiki/lint [get]
func (h *WikiPageHandler) Lint(c *gin.Context) {
@ -1203,7 +1223,7 @@ func (h *WikiPageHandler) Lint(c *gin.Context) {
// @Tags Wiki
// @Produce json
// @Param kb_id path string true "Knowledge base ID"
// @Success 200 {object} map[string]interface{}
// @Success 200 {object} handler.AutoFixResponse
// @Security Bearer
// @Router /knowledgebase/{kb_id}/wiki/auto-fix [post]
func (h *WikiPageHandler) AutoFix(c *gin.Context) {

View File

@ -176,9 +176,9 @@ type Chunk struct {
// 父 Chunk ID,用于关联图片 Chunk 和原始文本 Chunk
ParentChunkID string `json:"parent_chunk_id" gorm:"type:varchar(36);index"`
// 关系 Chunk ID,用于关联关系 Chunk 和原始文本 Chunk
RelationChunks JSON `json:"relation_chunks" gorm:"type:json"`
RelationChunks JSON `json:"relation_chunks" gorm:"type:json" swaggertype:"array,string"`
// 间接关系 Chunk ID,用于关联间接关系 Chunk 和原始文本 Chunk
IndirectRelationChunks JSON `json:"indirect_relation_chunks" gorm:"type:json"`
IndirectRelationChunks JSON `json:"indirect_relation_chunks" gorm:"type:json" swaggertype:"array,string"`
// Metadata 存储 chunk 级别的扩展信息,例如 FAQ 元数据
Metadata JSON `json:"metadata" gorm:"type:json"`
// ContentHash 存储内容的 hash 值,用于快速匹配(主要用于 FAQ)

View File

@ -17,7 +17,7 @@ type EmbedChannel struct {
Name string `json:"name" gorm:"type:varchar(255);not null;default:''"`
Enabled bool `json:"enabled" gorm:"not null;default:true"`
PublishToken string `json:"-" gorm:"type:varchar(64);not null;default:''"`
AllowedOrigins JSON `json:"allowed_origins" gorm:"type:jsonb;not null;default:'[]'"`
AllowedOrigins JSON `json:"allowed_origins" gorm:"type:jsonb;not null;default:'[]'" swaggertype:"array,string"`
WelcomeMessage string `json:"welcome_message" gorm:"type:text;not null;default:''"`
RateLimitPerMinute int `json:"rate_limit_per_minute" gorm:"not null;default:30"`
RateLimitPerDay int `json:"rate_limit_per_day" gorm:"not null;default:10000"`

View File

@ -37,7 +37,7 @@ type TemporaryDocument struct {
Status string `json:"status" gorm:"type:varchar(16);not null;index"`
Content string `json:"-" gorm:"type:text"`
Chunks JSON `json:"-" gorm:"type:jsonb;not null;default:'[]'"`
ImageRefs JSON `json:"image_refs,omitempty" gorm:"type:jsonb;not null;default:'[]'"`
ImageRefs JSON `json:"image_refs,omitempty" gorm:"type:jsonb;not null;default:'[]'" swaggertype:"array,object"`
Metadata JSON `json:"metadata,omitempty" gorm:"type:jsonb;not null;default:'{}'"`
ProcessingOptions JSON `json:"-" gorm:"type:jsonb;not null;default:'{}'"`
TokenCount int `json:"token_count" gorm:"not null;default:0"`

View File

@ -137,7 +137,7 @@ make package-mac-app # 打 macOS .app(scripts/package-mac-app.sh)
| `fmt` | `go fmt ./...` |
| `lint` | `golangci-lint run` |
| `deps` | `go mod download` |
| `docs` | `swag init -g ./cmd/server/main.go -o ./docs --parseDependency --parseInternal` 生成 Swagger 文档 |
| `docs` | `swag init`(参数见 Makefile,含 `--overridesFile ./docs/swag.overrides`)生成 Swagger 文档 |
| `install-swagger` | 安装 `swag` CLI |
### Docker 镜像与服务管理 {#_3-2-docker-镜像与服务管理}