yawan
f7fc992f57
16 KiB
API 参考：FAQ 与 Wiki
路由注册：internal/router/router.go 的 RegisterFAQRoutes 与 RegisterWikiPageRoutes。Handler：internal/handler/faq.go、internal/handler/wiki_page.go。
两组均为 KB 内容子资源：读为 Viewer+ 且 KB read（API key retrieve/full）；写为“KB 创建者 OR Admin+”且 KB write（API key ingest/full），并受 KB 白名单约束。
FAQ（/api/v1/knowledge-bases/:id/faq）
GET /api/v1/knowledge-bases/:id/faq/entries
用途：FAQ 条目列表。
| 查询参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
page / page_size |
int | 否 | 分页 |
tag_id |
int | 否 | 旧版单标签 seq_id |
tag_ids |
string | 否 | 逗号分隔标签 UUID |
keyword |
string | 否 | 关键字 |
search_field |
string | 否 | standard_question/similar_questions/answers（默认全字段） |
sort_order |
string | 否 | asc（默认按更新时间倒序） |
响应：200 {"success":true,"data":{分页 FAQEntry 列表}}
curl "$BASE/api/v1/knowledge-bases/kb-1/faq/entries?page=1" -H "Authorization: Bearer $TOKEN"
GET /api/v1/knowledge-bases/:id/faq/entries/export
用途：导出 FAQ。查询参数：format（csv 默认 / json）。
响应：200 文件下载（text/csv 或 application/json）。
curl -OJ "$BASE/api/v1/knowledge-bases/kb-1/faq/entries/export?format=csv" -H "Authorization: Bearer $TOKEN"
GET /api/v1/knowledge-bases/:id/faq/entries/:entry_id
用途：FAQ 条目详情（entry_id 为整数 seq_id）。
响应：200 {"success":true,"data":{FAQEntry}}
curl $BASE/api/v1/knowledge-bases/kb-1/faq/entries/12 -H "Authorization: Bearer $TOKEN"
POST /api/v1/knowledge-bases/:id/faq/entries
用途：批量 upsert / 导入（异步任务）。Handler 方法 UpsertEntries。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
entries |
[]FAQEntryPayload | 是（binding:"required"） |
批量条目 |
mode |
string | 是（binding:"oneof=append replace"） |
追加或替换 |
knowledge_id |
string | 否 | FAQ 知识实体 ID |
task_id |
string | 否 | 自定义任务 ID |
dry_run |
bool | 否 | 仅校验不落库 |
响应：200 {"success":true,"data":{"task_id"}}
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/faq/entries -H "X-API-Key: $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"mode":"append","entries":[{"standard_question":"如何退款?","answers":["联系客服"]}]}'
POST /api/v1/knowledge-bases/:id/faq/entry
用途：创建单条 FAQ。请求体（types.FAQEntryPayload）：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
standard_question |
string | 是（binding:"required"） |
标准问 |
similar_questions |
[]string | 否 | 相似问 |
negative_questions |
[]string | 否 | 负样例问 |
answers |
[]string | 否 | 答案列表 |
answer_strategy |
string | 否 | all / random |
tag_id |
int64 | 否 | 标签 seq_id |
tag_name |
string | 否 | 标签名 |
is_enabled / is_recommended |
*bool | 否 | 启用/推荐 |
响应：200 {"success":true,"data":{FAQEntry}}
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/faq/entry -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"standard_question":"如何退款?","answers":["7 天内可退"]}'
PUT /api/v1/knowledge-bases/:id/faq/entries/:entry_id
用途：更新单条 FAQ（请求体同创建）。
响应：200 {"success":true,"data":{FAQEntry}}
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/faq/entries/12 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"standard_question":"如何退款?","answers":["30 天内可退"]}'
POST /api/v1/knowledge-bases/:id/faq/entries/:entry_id/similar-questions
用途：追加相似问。请求体：{"similar_questions":["..."]}（binding:"required,min=1"）。
响应：200 {"success":true,"data":{FAQEntry}}
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/faq/entries/12/similar-questions \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"similar_questions":["退款怎么操作"]}'
PUT /api/v1/knowledge-bases/:id/faq/entries/fields
用途：批量更新条目字段（is_enabled/is_recommended/tag_id）。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
by_id |
map[int64]object | 否 | 按条目 seq_id 更新 |
by_tag |
map[int64]object | 否 | 按标签批量更新 |
exclude_ids |
[]int64 | 否 | by_tag 时排除的条目 |
响应：200 {"success":true}
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/faq/entries/fields -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"by_id":{"12":{"is_enabled":false}}}'
PUT /api/v1/knowledge-bases/:id/faq/entries/tags
用途：批量改条目标签。请求体：{"updates":{"<entry_id>":<tag_id|null>}}（binding:"required,min=1"；null 移除标签）。
响应：200 {"success":true}
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/faq/entries/tags -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"updates":{"12":3}}'
DELETE /api/v1/knowledge-bases/:id/faq/entries
用途：批量删除条目。请求体：{"ids":[int64]}（binding:"required,min=1"）。
响应：200 {"success":true}
curl -X DELETE $BASE/api/v1/knowledge-bases/kb-1/faq/entries -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"ids":[12,13]}'
POST /api/v1/knowledge-bases/:id/faq/search
用途：FAQ 检索（只读语义，scoped key 用 retrieve 亦可调用）。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
query_text |
string | 是（binding:"required"） |
查询 |
vector_threshold |
float64 | 否 | 向量阈值 |
match_count |
int | 否 | 默认 10，上限 200 |
first_priority_tag_ids / second_priority_tag_ids |
[]int64 | 否 | 标签优先级过滤 |
only_recommended |
bool | 否 | 仅推荐条目 |
响应：200 {"success":true,"data":[FAQEntry(含 match_type/score)]}
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/faq/search -H "X-API-Key: $API_KEY" \
-H 'Content-Type: application/json' -d '{"query_text":"退款"}'
PUT /api/v1/knowledge-bases/:id/faq/import/last-result/display
用途：设置最近一次导入结果面板的显示状态。请求体：{"display_status":"open|close"}（binding:"required,oneof=open close"）。
响应：200 {"success":true}
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/faq/import/last-result/display \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"display_status":"close"}'
GET /api/v1/faq/import/progress/:task_id
用途：查询 FAQ 导入/dry-run 进度（任务按空间隔离）。权限：Viewer+；API key retrieve/ingest/full。
响应：200 {"success":true,"data":{status,progress,failed_entries,...}}
curl $BASE/api/v1/faq/import/progress/task-1 -H "X-API-Key: $API_KEY"
Wiki（/api/v1/knowledgebase/:kb_id/wiki）
注意此组前缀为 /knowledgebase/:kb_id/wiki（单数，无连字符）。Handler: internal/handler/wiki_page.go。本组响应多为原始对象（不带 success 包装）。
GET /api/v1/knowledgebase/:kb_id/wiki/pages
用途：Wiki 页面列表。
| 查询参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
page_type |
string | 否 | 逗号分隔类型 |
status |
string | 否 | 页面状态 |
query |
string | 否 | 全文搜索 |
category_path |
string | 否 | / 分隔路径过滤 |
folder_id |
string | 否 | 精确目录过滤（空串=根） |
category_depth |
int | 否 | 目录深度 |
page / page_size |
int | 否 | 分页（默认 1/20） |
sort_by / sort_order |
string | 否 | 排序（默认 updated_at desc） |
响应：200 WikiPageListResponse
curl "$BASE/api/v1/knowledgebase/kb-1/wiki/pages?page=1" -H "Authorization: Bearer $TOKEN"
POST /api/v1/knowledgebase/:kb_id/wiki/pages
用途：创建页面。请求体（types.WikiPage）：slug、title、content、folder_id、page_type 等（均可选，slug 缺省自动生成）。
响应：201 WikiPage
curl -X POST $BASE/api/v1/knowledgebase/kb-1/wiki/pages -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"title":"架构概览","content":"# 概览"}'
PUT /api/v1/knowledgebase/:kb_id/wiki/move-page
用途：移动页面到目录。请求体：{"slug":"<页面slug>","folder_id":"<目录ID|空=根>"}（slug 必填）。
响应：200 WikiPage
curl -X PUT $BASE/api/v1/knowledgebase/kb-1/wiki/move-page -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"slug":"overview","folder_id":"f-1"}'
GET /api/v1/knowledgebase/:kb_id/wiki/pages/*slug
用途：获取页面（*slug 为通配路径）。
响应：200 WikiPage
curl $BASE/api/v1/knowledgebase/kb-1/wiki/pages/overview -H "Authorization: Bearer $TOKEN"
PUT /api/v1/knowledgebase/:kb_id/wiki/pages/*slug
用途：更新页面（请求体同创建）。旧版本会先整份快照进 wiki_page_revisions，version 递增，last_edit_source 记为 user（Agent 工具写入时为 agent）。
响应：200 WikiPage
curl -X PUT $BASE/api/v1/knowledgebase/kb-1/wiki/pages/overview -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"content":"# 更新后的概览"}'
GET /api/v1/knowledgebase/:kb_id/wiki/revisions/*slug
用途：页面版本历史（migration 000075）。权限：Viewer+ + KBAccessRead。
| 查询参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
version |
int | 否 | 传入时返回该版本全文（用于 diff），无效或 < 1 返回 400，找不到返回 404 |
limit |
int | 否 | 默认 50，上限 200；仅列表模式生效 |
offset |
int | 否 | 分页偏移 |
不带 version 时返回历史列表（版本号倒序、不含正文）加上页面当前版本号；每条含 edit_source（pipeline / agent / user / revert）、editor_id、edited_at。
历史保留是两级上限：软上限 50 版只裁剪 pipeline 与空来源的快照，硬上限 200 版对所有来源生效，因此人工编辑不会被管道刷掉。
# 历史列表
curl $BASE/api/v1/knowledgebase/kb-1/wiki/revisions/entity/acme-corp -H "Authorization: Bearer $TOKEN"
# 取第 3 版全文
curl "$BASE/api/v1/knowledgebase/kb-1/wiki/revisions/entity/acme-corp?version=3" -H "Authorization: Bearer $TOKEN"
POST /api/v1/knowledgebase/:kb_id/wiki/revert
用途：把页面回滚到某个历史版本。权限：KB owner 或 Admin+ + KBAccessWrite。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
slug |
string | 是 | 目标页面 |
version |
int | 是 | 目标版本号（≥ 1） |
回滚不会把版本号退回去：目标版本的内容会作为一个新版本写入，last_edit_source 记为 revert，所以回滚也能被回滚。回滚到当前版本返回 400（一般是前端历史列表过期）。
响应：200 WikiPage
curl -X POST $BASE/api/v1/knowledgebase/kb-1/wiki/revert -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"slug":"entity/acme-corp","version":3}'
DELETE /api/v1/knowledgebase/:kb_id/wiki/pages/*slug
用途：删除页面。
响应：204 No Content
curl -X DELETE $BASE/api/v1/knowledgebase/kb-1/wiki/pages/overview -H "Authorization: Bearer $TOKEN"
GET /api/v1/knowledgebase/:kb_id/wiki/folders
用途：目录列表。查询参数：parent_id（空=根）、page_types（逗号分隔）。
响应：200 WikiFolderListResponse
curl $BASE/api/v1/knowledgebase/kb-1/wiki/folders -H "Authorization: Bearer $TOKEN"
POST /api/v1/knowledgebase/:kb_id/wiki/folders
用途：创建目录。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name |
string | 是 | 目录名 |
parent_id |
string | 否 | 父目录 |
响应：201 WikiFolder
curl -X POST $BASE/api/v1/knowledgebase/kb-1/wiki/folders -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"设计文档"}'
PUT /api/v1/knowledgebase/:kb_id/wiki/folders/:folder_id
用途：重命名/移动目录。请求体：name、parent_id、move_parent（bool），均可选。
响应：200 WikiFolder
curl -X PUT $BASE/api/v1/knowledgebase/kb-1/wiki/folders/f-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"架构设计"}'
DELETE /api/v1/knowledgebase/:kb_id/wiki/folders/:folder_id
用途：删除目录。
响应：204 No Content
curl -X DELETE $BASE/api/v1/knowledgebase/kb-1/wiki/folders/f-1 -H "Authorization: Bearer $TOKEN"
GET /api/v1/knowledgebase/:kb_id/wiki/index
用途：Wiki 索引页（按类型分组窗口）。查询参数：types（逗号分隔）、limit（1-200，默认 50）、cursor（游标）。
响应：200 WikiIndexResponse
curl $BASE/api/v1/knowledgebase/kb-1/wiki/index -H "Authorization: Bearer $TOKEN"
::: warning 已移除
GET /api/v1/knowledgebase/:kb_id/wiki/log（Wiki 变更日志）已随 migration 000077_remove_wiki_log 一并下线，wiki_log_entries 表被删除。Wiki 变更现在统一投影到知识库活动流，改用 GET /api/v1/knowledge-bases/:id/activity。
:::
GET /api/v1/knowledgebase/:kb_id/wiki/graph
用途：页面关系图。
| 查询参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
mode |
string | 否 | overview（默认）/ ego |
center |
string | 否 | ego 模式中心 slug（ego 时必填） |
depth |
int | 否 | 1-3，默认 1 |
types |
string | 否 | page_type 过滤 |
limit |
int | 否 | 默认 500，上限 2000 |
响应：200 WikiGraphData
curl "$BASE/api/v1/knowledgebase/kb-1/wiki/graph?mode=overview" -H "Authorization: Bearer $TOKEN"
GET /api/v1/knowledgebase/:kb_id/wiki/stats
用途：Wiki 统计。
响应：200 WikiStats
curl $BASE/api/v1/knowledgebase/kb-1/wiki/stats -H "Authorization: Bearer $TOKEN"
GET /api/v1/knowledgebase/:kb_id/wiki/search
用途：页面搜索。查询参数：q（必填）、limit（默认 10）。
响应：200 {"pages":[WikiPage]}
curl "$BASE/api/v1/knowledgebase/kb-1/wiki/search?q=部署" -H "Authorization: Bearer $TOKEN"
POST /api/v1/knowledgebase/:kb_id/wiki/rebuild-links
用途：重建页面互链。写权限。无请求体。
响应：200 {"message":"Links rebuilt successfully"}
curl -X POST $BASE/api/v1/knowledgebase/kb-1/wiki/rebuild-links -H "Authorization: Bearer $TOKEN"
GET /api/v1/knowledgebase/:kb_id/wiki/lint
用途：Wiki 一致性检查报告。
响应：200 WikiLintReport
curl $BASE/api/v1/knowledgebase/kb-1/wiki/lint -H "Authorization: Bearer $TOKEN"
POST /api/v1/knowledgebase/:kb_id/wiki/auto-fix
用途：自动修复 lint 问题。写权限。无请求体。
响应：200 {"fixed":N,"message":"Auto-fixed N issues"}
curl -X POST $BASE/api/v1/knowledgebase/kb-1/wiki/auto-fix -H "Authorization: Bearer $TOKEN"
GET /api/v1/knowledgebase/:kb_id/wiki/issues
用途：问题列表。查询参数：slug（按页面过滤）、status（pending/ignored/resolved）。
响应：200 [WikiPageIssue]
curl $BASE/api/v1/knowledgebase/kb-1/wiki/issues -H "Authorization: Bearer $TOKEN"
PUT /api/v1/knowledgebase/:kb_id/wiki/issues/:issue_id/status
用途：更新问题状态。写权限。请求体：{"status":"pending|ignored|resolved"}（binding:"required"）。
响应：200 {"message":"Issue status updated successfully"}
curl -X PUT $BASE/api/v1/knowledgebase/kb-1/wiki/issues/i-1/status -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"status":"resolved"}'