一个面向个人本地知识库构建的 RAG 基座项目，重点解决“把分散在本地目录、飞书文档、飞书云文档、远程知识源中的资料，沉淀成可检索、可解释、可被 Agent / 大模型持续调用的知识底座”。

它既可以作为独立的本地知识库工具使用，也可以作为 OpenClaw、Agent、MCP 工具体系中的知识检索底座，打通“知识接入 -> 多层索引构建 -> 渐进式检索 -> Skill 编排 -> 大模型消费”的完整链路。

当前实现提供：

• CLI：本地构建、搜索、解释、状态查看
• MCP Server：把检索能力暴露给 AI 助手
• Core Engine：数据源扫描、文档解析、索引构建、FTS/向量检索
• Skill：可选的语义编排层，用于 query rewrite、检索参数规划和多轮探索建议

• 个人知识库：把本地 Markdown、PDF、TXT、项目文档沉淀为可持续检索的个人知识底座
• 团队知识接入：统一接入飞书知识空间、飞书云文档、个人等远程知识源
• AI 助手检索底座：通过 MCP 暴露给 Cursor、Agent、Chatbot 或其他支持工具调用的系统
• OpenClaw / 开放搜索链路：作为 OpenClaw 一类开放搜索、RAG、Agent 工作流中的知识库基座
• 长文档问答与知识探索：支持“先找结构，再找证据，再由大模型组织答案”的渐进式检索链路

• 多数据源接入：同时支持本地与远程知识源，适合个人知识库长期积累
• 多层构建结构：把原始文档拆成文档、章节、证据块三层结构，兼顾结构理解与精确召回
• 渐进式检索：支持 map / lookup / read / explore，适合从“找入口”到“找原文证据”的不同问题类型
• 混合检索能力：可结合 FTS、结构检索、向量召回做融合排序，在召回率和解释性之间取得平衡
• Skill + 大模型策略增强：把 query rewrite、意图识别、scope 收窄、多轮探索留给 Skill / 大模型层，提升复杂问答场景下的召回稳定性
• 面向 OpenClaw / RAG 工作流：设计上吸收了 OpenClaw 一类开放检索和工具编排的理念，适合作为外部知识层接入完整 Agent 链路
• 高可观测性：支持状态查看、构建日志、检索 trace、评测脚本，便于持续迭代召回质量

• 应用场景
• 架构设计优势
• 召回评测报告
• 架构概览
• 包结构说明
• 核心能力
• 安装
• 知识库目录
• 环境变量
• 快速开始
• CLI 使用指南
• 接入方式
• 数据源支持
• 检索模型
• 开发
• 回归评估
• 许可证

当前主链路是 CLI / MCP -> @knowledge/core -> SQLite/FTS/Vector，@knowledge/skill 是独立的可选编排层，而不是 CLI/MCP 的必经层。

User / AI Assistant
        │
        ▼
CLI / MCP Server
        │
        ▼
@knowledge/core
  ├─ source      数据源扫描
  ├─ parser      文档解析
  ├─ compiler    分块与索引构建
  ├─ storage     SQLite + FTS5 + sqlite-vec
  ├─ retrieval   检索规划与执行
  ├─ status      索引状态
  └─ logging     日志与 manifest

Optional:
@knowledge/skill
  └─ query rewrite / plan hints / 多轮探索建议

位于 packages/core/，负责系统的核心能力。

位于 packages/cli/，提供命令行入口：

• kb build
• kb search
• kb explain
• kb status

项目根目录还提供了快捷脚本：

pnpm kb

等价于：

node ./packages/cli/dist/index.js

位于 packages/mcp/，通过 stdio 暴露 MCP 工具：

• knowledge_status
• knowledge_search
• knowledge_build
• knowledge_explain

位于 packages/skill/，提供可选的语义编排能力：

• 判断是否属于知识问答场景
• 对 query 做 rewrite 和 alias 提取
• 生成 planHints
• 建议 mode / strategy / entryLayer / budget
• 根据首轮结果决定是否继续二轮探索

• 支持本地目录、本地单文件、飞书知识空间、飞书云文档、个人知识库
• 支持 Markdown、Text、PDF 解析
• 自动切分章节与证据块
• 路径自动派生标签，支持后续 scope.tags
• 构建时优先在临时库完成，成功后再原子替换主库

• 检索策略：structure_first、evidence_first
• 执行模式：map、lookup、read、explore
• 入口层：L0、L1、L3
• 结构化输入：scope / execution / budget / plan_hints
• 返回 explain 计划与 trace，便于调试检索过程

• 构建时可选生成 embedding
• 支持本地模型和远程 embedding API
• 检索时如果存在 embedding 数据且 sqlite-vec 可用，会自动启用 FTS + 结构 + 向量 融合
• 如果没有向量索引或向量不可用，会自动降级到非向量检索

• .knowledge/logs/runtime.log
• .knowledge/logs/build-<runId>.log
• .knowledge/manifest.json
• status 可查看最近一次构建、退化状态、embedding 状态等

• Node.js >= 18
• pnpm >= 8
• 可选：sqlite-vec，仅在需要向量索引时使用

pnpm install

pnpm build

CLI 和 MCP 默认都以当前工作区根目录作为知识库根目录，索引产物落在：

.knowledge/
├── db.sqlite
├── manifest.json
└── logs/
    ├── runtime.log
    └── build-<runId>.log

说明：

• db.sqlite：知识库索引数据库
• manifest.json：最近一次构建和搜索的摘要快照
• logs/：运行日志和按构建 run 分拆的日志文件

当前实现没有 --db 参数；数据库位置固定为当前工作目录下的 .knowledge/db.sqlite。

CLI 会从当前工作目录读取 .env，但不会覆盖已存在的环境变量。MCP 启动后也会按工作区根目录读取 .env。

如需使用远程数据源或远程 embedding，可先复制：

cp .env.example .env

常用环境变量如下：

pnpm kb build --source ./fixtures/files

排除部分文件：

pnpm kb build --source ./fixtures/files --exclude "**/测试集使用说明.md"

pnpm kb search 如何配置环境变量 --top-k 5

输出 JSON：

pnpm kb search 如何配置环境变量 --json

pnpm kb explain 如何配置环境变量

pnpm kb status

用途：全量构建或刷新知识库。

pnpm kb build [options]

主要参数：

• --source <path>：本地源目录或文件；source-type=local 时必填
• --source-type <type>：local | honghu | feishu | feishu_drive
• --include <glob>：本地源包含规则，可重复
• --exclude <glob>：本地源排除规则，可重复
• --knowledge-base <id>：个人知识库 ID
• --api-base-url <url>：个人 API base URL
• --auth-token <token>：个人鉴权 token
• --space-id <id>：飞书知识空间 ID
• --start-node-token <token>：飞书知识空间起始节点
• --folder-token <token>：飞书云文档文件夹 token
• --app-id <id>：飞书 App ID
• --app-secret <secret>：飞书 App Secret
• --embedding：启用 embedding 生成
• --embedding-provider <type>：local | remote
• --embedding-model <name>：覆盖模型名
• --embedding-dimension <n>：覆盖向量维度

示例：

# 本地目录
pnpm kb build --source ./fixtures/files

# 本地目录 + include/exclude
pnpm kb build --source ./fixtures/files --include "**/*.md" --exclude "**/draft/**"

# 飞书知识空间
pnpm kb build --source-type feishu --space-id "<space-id>"

# 飞书云文档
pnpm kb build --source-type feishu_drive --folder-token "<folder-token>"

# 个人知识库
pnpm kb build --source-type honghu --knowledge-base "<knowledge-base>"

# 启用本地向量
pnpm kb build --source ./fixtures/files --embedding

# 启用远程向量
pnpm kb build --source ./fixtures/files --embedding --embedding-provider remote

行为说明：

• 本地构建支持单文件和目录两种模式
• 本地扫描支持 .md、.markdown、.txt、.text、.pdf
• 隐藏路径会被跳过
• 构建成功后会输出文档数、章节数、证据块数和耗时
• 若解析失败或 embedding 失败，构建结果会标记为 degraded

用途：对已构建知识库执行检索。

pnpm kb search <query...> [options]

参数：

• --json：输出 JSON
• --top-k <n>：候选和证据条数上限，默认 10
• --strategy <name>：structure_first | evidence_first
• --mode <name>：map | lookup | read | explore
• --entry-layer <name>：L0 | L1 | L3
• --rewrite <query>：把实际检索使用的 query 写入 planHints.rewrittenQuery

示例：

pnpm kb search 这个系统有哪些模块 --mode map

pnpm kb search 某个规则写在哪 --mode lookup --entry-layer L3

pnpm kb search 原始问题 --rewrite "改写后的检索词" --json

说明：

• 未指定 strategy 时会按 query 自动规划
• mode 会影响默认的 strategy 和 entryLayer
• 如果索引中存在向量数据，检索会自动尝试融合向量召回

用途：返回检索计划、执行 trace 和结果，适合调试。

pnpm kb explain <query...> [options]

参数与 search 基本一致，支持：

• --json
• --top-k
• --strategy
• --mode
• --entry-layer
• --rewrite

用途：查看知识库状态。

pnpm kb status [--json]

重点字段：

• lastBuildStatus
• lastBuildAt
• degraded
• documentCount
• sectionCount
• evidenceCount
• embeddingEnabled
• vectorIndexAvailable
• embeddedChunkCount

本项目既可以独立运行，也可以作为 MCP knowledge server、Skill runtime、OpenClaw knowledge base 接入更大的 Agent / RAG 工作流。

MCP 服务默认使用工作区根目录下的 .knowledge/db.sqlite。如需明确指定工作区，可传 KNOWLEDGE_WORKSPACE_ROOT。

示例配置：

{
  "mcpServers": {
    "knowledge": {
      "command": "node",
      "args": ["/path/to/seek-knowledge/packages/mcp/dist/server.js"],
      "env": {
        "KNOWLEDGE_WORKSPACE_ROOT": "/path/to/your/workspace"
      }
    }
  }
}

可用工具：

• knowledge_status
• knowledge_search
• knowledge_build
• knowledge_explain

适合场景：

• 给 IDE Agent、对话助手、自动化工作流提供外部知识检索能力
• 让大模型先通过工具检索，再组织最终回答
• 作为 OpenClaw 或其他支持 MCP 的系统的知识检索层

说明：

• knowledge_search / knowledge_explain 支持 scope、execution、budget、plan_hints
• knowledge_build 当前主要负责选择数据源并构建索引，不提供 CLI 里的 embedding 参数
• 如需构建带向量的索引，优先使用 CLI 执行 kb build --embedding

@knowledge/skill 适合作为“大模型策略层”接在检索前后，用来提升复杂知识问答场景下的召回率和可解释性。

Skill 主要负责：

• 判断当前问题是否属于知识问答 / 文档检索场景
• 对 query 做 rewrite、alias 提取、意图分类
• 生成 planHints
• 为 knowledge_search 选择更合适的 mode / strategy / entryLayer / budget
• 在首轮结果不足时建议二轮探索

典型链路：

用户问题
  -> Skill 判断与改写
  -> knowledge_search / knowledge_explain
  -> Core Planner 执行检索
  -> 大模型基于候选与证据组织答案

这也是当前仓库中“无向量构建 + Skill 多轮增强检索”能显著提升召回表现的核心原因之一。

如果你的 OpenClaw 运行环境支持 MCP 或外部工具注册，可以把本项目作为知识库基座接入，让 OpenClaw 负责调度、大模型规划与最终回答，本项目负责知识接入、索引构建和检索执行。

推荐链路：

本地文档 / 飞书 / 远程知识源
  -> seek-knowledge build
  -> seek-knowledge MCP
  -> OpenClaw
  -> Skill / LLM 规划
  -> knowledge_search / knowledge_explain
  -> 最终回答

一个常见的接入方式是先构建知识库：

pnpm build
pnpm kb build --source ./your-docs --embedding --embedding-provider remote

然后把 MCP 服务暴露给上层系统：

{
  "mcpServers": {
    "seek-knowledge": {
      "command": "node",
      "args": ["/path/to/seek-knowledge/packages/mcp/dist/server.js"],
      "env": {
        "KNOWLEDGE_WORKSPACE_ROOT": "/path/to/your/workspace"
      }
    }
  }
}

对于 OpenClaw 这类开放搜索 / Agent 系统，可以把这个 MCP server 视为“外部知识层”：

• OpenClaw 负责对用户问题做任务规划、工具路由和答案生成
• seek-knowledge 负责多数据源接入、多层索引构建、渐进式检索和 explain
• Skill + 大模型 负责 query rewrite、策略选择、多轮探索

这样可以形成一条更完整的个人知识库链路：

知识采集
  -> 知识构建
  -> 知识检索
  -> Agent 编排
  -> 大模型回答

仓库中已经包含 OpenClaw 场景下的评测样例与脚本：

• fixtures/tests-feishu-openclaw/
• scripts/run_retrieval_test_feishu_openclaw.py

适合用于验证“seek-knowledge + OpenClaw + 大模型”这条链路的实际表现。

• 支持单文件和目录递归扫描
• 支持 include / exclude glob
• 支持 .md、.markdown、.txt、.text、.pdf
• 隐藏路径会跳过

• source-type=feishu
• 需要 spaceId
• 可选 startNodeToken
• appId / appSecret 可通过参数或环境变量提供
• 通过飞书 raw content API 拉取内容，按 Markdown 文本处理

• source-type=feishu_drive
• folderToken 可选；不填时从根目录扫描
• 会递归遍历文件夹并抓取 doc / docx
• 内容按 Markdown 文本处理

• source-type=honghu
• 需要 knowledgeBase
• authToken 可通过参数或 HONGHU_AUTH_TOKEN 提供
• 当前远程源以文本内容构建为主

说明：远程数据源当前走文本拉取链路，不支持把远程二进制 PDF 下载后再解析。

当前推荐使用结构化检索输入，而不是只传字符串 query。

{
  "query": "这个模块负责什么",
  "scope": {
    "paths": ["packages/core/"],
    "tags": ["core"],
    "docTypes": ["markdown"]
  },
  "execution": {
    "mode": "map",
    "strategy": "structure_first",
    "entryLayer": "L0"
  },
  "budget": {
    "maxCandidates": 8,
    "maxEvidenceChunks": 12
  },
  "plan_hints": {
    "rewrittenQuery": "core 模块职责",
    "queryAliases": ["core", "模块职责"]
  }
}

• paths：按已索引文档路径前缀过滤，推荐使用工作区相对路径，如 docs/、packages/core/
• tags：按路径派生标签过滤，例如 docs/design/foo.md 会派生出类似 docs、design、foo
• docTypes：markdown | text | pdf

• mode
  • map：找结构、找模块、找入口
  • lookup：找精确信息或片段
  • read：阅读方案和说明
  • explore：更开放的探索式检索
• strategy
  • structure_first：先偏结构，再下钻证据
  • evidence_first：先偏证据，适合事实型问答
• entryLayer
  • L0：从文档级入口开始
  • L1：从章节级入口开始
  • L3：从证据块级入口开始

plan_hints 用于给 Core Planner 提供语义提示，常见字段包括：

• rewrittenQuery
• queryAliases
• intent.questionType
• domain.decision
• execution
• scope
• budget
• filters
• hints
• meta

常用返回字段：

• meta.entryLayer：最终入口层
• meta.scopeApplied：是否实际应用了 scope
• meta.degraded：结果是否处于退化状态
• candidates[].source / evidence[].source：命中来源，可能是 fts、structure、vector 或它们的组合

seek-knowledge/
├── packages/
│   ├── cli/
│   ├── core/
│   ├── mcp/
│   └── skill/
├── fixtures/
├── scripts/
├── docs/
├── package.json
└── pnpm-workspace.yaml

pnpm build
pnpm test
pnpm test:coverage
pnpm eval:regression
pnpm clean

在 packages/core/src/source/ 中新增扫描器，并扩展 SourceSpec 分发逻辑。

在 packages/core/src/parser/ 中新增解析器，并接入 parseDocument()。

项目提供回归评估脚本：

pnpm eval:regression

它会基于测试集重建索引，并调用 kb search --json 生成评估报告。

MIT