feat(kb): 知识库开放 API — 对外暴露检索/溯源/图谱能力

[ncw1992120]

背景

MateClaw 的知识库目前没有直接对外的入口。外部系统想用知识库，只能套一层 Agent 对话（WebChat 渠道），无法程序化检索。本 ISSUE 规划一套 OpenAPI 风格的知识库开放 API，支持两类消费者：

1. 其他应用程序（客服系统、搜索前端、内部业务系统）—— REST API 程序化检索
2. 外部 AI Agent（Claude Desktop、Cursor 等）—— 后续 MCP Server 零代码接入

核心设计判断

经过多轮讨论，确定了以下关键判断（详见设计文档）：

• Wiki 页面在逻辑上就是实体（pageType 第一种取值叫 entity，页面带 canonicalName/metadataJson/knowledgeLayer）。因此统一为一套接口，slug 即实体标识，不分"页面中心化/实体中心化"两套 API。
• traverse（实体关系遍历）是唯一需要实体关系表的接口，其余全是页面的不同投影。
• 不做 channel 类型——channel 是消息入口（inbound），知识库开放 API 是数据出口（outbound），数据流方向相反，架构错配。

设计方案概要

认证与鉴权

• API Key：mck_ 前缀，SHA-256 hash 存储（复用 PAT 范式，不复用 WebChat 明文存储）
• 一个 Key 绑定多个知识库 + scope 细粒度（kb:search/read/list/meta）
• 集中授权：@RequireKbScope 注解 + interceptor（不逐端点手写，避免重蹈 安全｜WikiRelationController 全部接口缺失工作区鉴权（IDOR） #438/fix(wiki): 关闭 WikiRelationController & WikiEntityController 的 IDOR 漏洞 #439 IDOR）
• P0 限流：search 每次消耗 embedding token，公网可达必须限流（复用 TriggerRateLimiter）
• 空绑定 = 零访问（对外 key 不复用"无绑定=全量"语义）

9 个端点（P0，不含 research）

方法	路径	能力
GET	/kb/{kbId}/pages/{slug}	查主体画像（mode=summary/full/section 下钻）
POST	/kb/{kbId}/search	混合检索（granularity=entity/chunk）
POST	/kb/{kbId}/search/chunks	chunk 级细粒度检索
POST	/kb/{kbId}/pages/{slug}/traverse	实体关系遍历（depth≤2，务实版）
GET	/kb/{kbId}/pages/{slug}/trace	溯源（page→chunk→raw）
GET	/kb/{kbId}/taxonomy	实体/关系/页面类型枚举地图
GET	/kb/{kbId}/whats-new	时效查询（变更 + stale 页面）
GET	/kb/{kbId}/stats	知识库元信息
GET	/kb/{kbId}/pages	列页面

前端管理 UI

• /settings/open-api（Settings ▸ Advanced，仿 AcpEndpoints.vue）
• Key 跨 KB（1 Key → N KB），需平台级统一管理

分阶段实施

阶段	内容	子任务
P0-A	认证体系 + 数据模型 + 管理端 + 限流 + 集中授权	→ #子任务1
P0-B	9 个开放 API 端点（一次上线）	→ #子任务2
P1.5	Deep Research 开放（独立设计：异步/SSE/限流/计费）	→ #子任务3
P1	运营能力（计费/审计/UI/WebChat迁移/token内核共享）	后续细化
P2	MCP Server（低优先级）	暂不排期

关键决策（已确认）

• API Key 不跨工作区
• 检索结果不按 pageType 脱敏
• /research 移出 P0（异步/SSE/多步 LLM，与同步只读端点本质不同）
• traverse 务实版（depth≤2 + LIKE + LIMIT，性能优化留后续）
• token 内核和 PAT 共享（先 hash 层）
• WebChat API Key 迁移到 hash 模式：P1 分两步（P0 先验证 TokenHashUtil，P1 单独 PR 迁 WebChat）

零新建业务表

全部建立在现有 wiki 数据模型之上（page/chunk/entity/relation/citation）。仅新增 API Key 两张表（mate_kb_api_key + mate_kb_api_key_binding）。