旺小宝项目知识库

> CRITICAL —— 跑命令前 MUST 先用 Read tool 读取 ../wangxiaobao-shared/SKILL.md（一份共享文档讲清安装 / 登录 / 选项目 / 错误码 / 输出协议等所有 xiaobao-cli 命令通用的前置约定）。

跑 xiaobao-cli kb * 检索 / 浏览当前激活项目的知识库（楼盘资料、政策、户型、物料等）。

执行前必读

• 必须有有效 token：先调 xiaobao-cli auth whoami；未登录就走 auth login --no-wait split-flow（见 wangxiaobao-shared）
• 必须有激活项目：kb search / kb docs 按当前激活项目（estate）隔离知识；kb doc / kb doc-content 按 docId 直取（项目级而非顾问级隔离——任何登录用户按 docId 可读）
• 只读：不写文件、不出报告

快速索引：意图 → 工具

核心约束

1. search 返回 chunk，不是全文

kb search 走语义检索，返回最相关的若干 chunk（片段），用于快速回答"知识库里怎么说 X"。要读某篇文档的完整内容，先 kb docs 找到 docId，再 kb doc-content 翻页读全文。

2. doc-content 用 offset/limit 翻页

正文可能很长，kb doc-content 按 offset/limit 分页（limit 默认 1000、最大 2000）。响应里 hasMore=true 说明还有后续，把 offset 加上已读长度继续翻，直到 hasMore=false。

3. k 默认 5，上限 20

kb search --k 控制返回 chunk 数；默认 5，最大 20。问题宽泛时调大 k，精确查证时用小 k。

4. 响应字段重点

kb search：

{ "code": "0", "data": {
  "query": "学区", "tenantId": "...", "estateId": "...",
  "chunks": [
    { "pageContent": "本项目对口 XX 小学...", "summary": "...", "sourceId": "123", "sourceType": "doc", "metadata": {...} }
  ] } }

kb docs：data.docs[]，每项 { docId, title }。

kb doc：data = { id, title, fileName, description, enabled, parseStatus, createdAt, updatedAt }。

kb doc-content：data = { docId, offset, limit, totalLength, hasMore, content }。

CLI 都再包一层 → 实际读 resp.data.data.*。

使用场景示例

场景 1：知识库里关于学区怎么说

xiaobao-cli kb search "学区 对口小学" --k 5

把命中的 chunks[].pageContent 综合成一段回答，必要时标注来源 sourceId。

场景 2：找户型相关文档并读全文

# step 1: 找文档
xiaobao-cli kb docs --title 户型
# step 2: 假设 docId = 88，逐段读
xiaobao-cli kb doc-content 88 --offset 0 --limit 2000
# 若 hasMore=true，继续
xiaobao-cli kb doc-content 88 --offset 2000 --limit 2000

场景 3：看某文档元信息

xiaobao-cli kb doc 88

常见错误与排查

• error: 'NO_ACTIVE_PROJECT' — 跑 wangxiaobao-switch-project skill（search/docs 需要激活项目）
• 401 / token 过期 — 走 auth login --no-wait --force split-flow 重登
• search 命中为空 / chunks 为空 — 换关键词或调大 --k；该项目知识库可能尚未入库相关内容
• doc-content 读不全 — 看 hasMore，按 offset 继续翻页
• 用户其实想问业务数据（客户/来访/业绩） — 那是 wangxiaobao-quick-qa，不是知识库