API 参考：FAQ 与 Wiki
路由注册：internal/router/routes_knowledge.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）
路径里的 :entry_id，以及批量接口里的 by_id、by_tag、exclude_ids、ids、updates 的键，都是整数 seq_id，不是字符串 ID；标签也按标签的 seq_id 引用。导入进度接口 /faq/import/progress/:task_id 不在知识库分组下，只凭任务 ID 调用。
GET /api/v1/knowledge-bases/:id/faq/entries
用途：FAQ 条目列表。
| 查询参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
page / page_size | int | 否 | 分页（默认 1/20） |
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 文件下载：CSV 为 text/csv; charset=utf-8、文件名 faq_export.csv，带 UTF-8 BOM 以便 Excel 打开；JSON 为 application/json、文件名 faq_export.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 / 导入（异步任务）。立即返回 task_id，结果通过 GET /faq/import/progress/:task_id 查询。Handler 方法 UpsertEntries。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
entries | []FAQEntryPayload | 是（binding:"required"） | 批量条目 |
mode | string | 是（binding:"oneof=append replace"） | append 追加；replace 以本次条目为准，库中不在其中的条目会被删除 |
knowledge_id | string | 否 | FAQ 知识实体 ID |
task_id | string | 否 | 自定义任务 ID |
dry_run | bool | 否 | 只执行校验（格式、批内重复、与库内重复、内容安全），不写入；同样通过进度接口查看结果 |
entries 中每项为 FAQEntryPayload（字段见下一个接口），另可带 id 指定 seq_id，用于数据迁移，必须小于自增起始值 100000000。
响应：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，会即时检查标准问与相似问是否和库内已有条目重复（重复返回 400，如 相似问「...」重复）。请求体（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 | 否 | 按标签 seq_id，对该标签下全部条目应用同一更新 |
exclude_ids | []int64 | 否 | by_tag 时排除的条目 |
每个 object 为 FAQEntryFieldsUpdate：is_enabled、is_recommended、tag_id，都可选，只更新传入的字段。by_id 与 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":{FAQImportProgress}}，主要字段：task_id、kb_id、knowledge_id、status（pending/processing/completed/failed）、progress（0-100）、total、processed、success_count、failed_count、partial_failed_count、skipped_count、added_count、merged_count、success_entries、failed_entries_url、message、error、dry_run、created_at/updated_at（Unix 秒）。有失败条目时会生成 CSV，通过 failed_entries_url 下载，内联的 failed_entries 随之清空。dry-run 任务的 success_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
用途：局部更新页面（types.WikiPageUpdateRequest），只改传入的字段：title、content、summary、page_type、status、aliases。可带 version 做乐观并发控制：与当前版本不一致时返回 409，响应带 current_version。旧版本会先整份快照进 wiki_page_revisions，version 递增，last_edit_source 记为 user。
响应：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+ + KBAccess。
| 查询参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
version | int | 否 | 传入时返回该版本全文（用于 diff），无效或 < 1 返回 400，找不到返回 404 |
limit | int | 否 | 默认 50，上限 200；仅列表模式生效 |
offset | int | 否 | 分页偏移 |
不带 version 时返回历史列表（版本号倒序、不含正文）加上页面当前版本号；每条含 edit_source（pipeline / 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+ + KBAccess。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
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"已移除
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"