@ganziliang/kb

v0.4.0

Published

11 days ago

Local knowledge base agent CLI with a pi-tui interface

0High
0Medium
0Low

@ganziliang/kb

本地知识库命令行工具。它会把本地 Markdown、文本、JSON、CSV 或 Excel 文件导入 SQLite 知识库，也可以直接录入输入框中的文字，然后通过关键词检索相关内容，并调用已配置的模型回答问题。同时支持导入图片：入库时自动生成中文描述参与检索，提问命中后把原图发给模型。

界面基于 @earendil-works/pi-tui 构建，采用差分渲染：Markdown 回答排版、带边框的编辑器、加载动画与命令浮层。

0.2.0 提示：这是界面重写版本，Node.js 要求提升到 >=22.19.0。存储格式与 ~/.kb 数据目录未变，旧知识库可直接使用。详见常见问题。

环境要求

Node.js >=22.19.0（当前 UI 依赖的终端渲染库要求，低于此版本无法启动）
如果使用模型问答，需要可用的模型 API Key
首次启动需要配置模型

安装

从 npm 安装

npm install -g @ganziliang/kb

安装后使用 kb 命令：

kb

@ganziliang/kb 已经声明依赖 @ganziliang/kb-model-setup。通过 npm 安装 @ganziliang/kb 时，npm 会自动安装该依赖，正常情况下不需要单独安装。

如果你需要单独安装或更新模型配置模块，可以执行：

npm install -g @ganziliang/kb-model-setup

注意：kb-model-setup 是模型配置模块，不是启动 kb 的主命令。日常使用只需要运行：

kb

首次启动和模型配置

直接运行：

kb

首次启动时，程序会询问：

api-stats 页面地址或 apiId
API Key

kb 使用依赖包 @ganziliang/kb-model-setup 完成模型配置。该模块会查询智真 LLM Gateway 中当前账号可用的模型，并保存所选模型配置。

当前默认使用智真 LLM Gateway：

https://llm-gateway.zhizhengroup.com

api-stats 地址示例：

https://llm-gateway.zhizhengroup.com/admin-next/api-stats?apiId=<你的apiId>

模型配置保存位置：

~/.config/kb/config.json

Windows 通常对应：

C:\Users\<用户名>\.config\kb\config.json

也可以通过环境变量跳过首次交互配置：

KB_PROVIDER=company-gpt \
KB_API=openai-responses \
KB_MODEL=gpt-5.6-luna \
KB_BASE_URL=https://llm-gateway.zhizhengroup.com/openai \
KB_API_KEY=<你的APIKey> \
kb

PowerShell 写法：

$env:KB_PROVIDER = "company-gpt"
$env:KB_API = "openai-responses"
$env:KB_MODEL = "gpt-5.6-luna"
$env:KB_BASE_URL = "https://llm-gateway.zhizhengroup.com/openai"
$env:KB_API_KEY = "你的APIKey"
kb

支持的 KB_API 值：

openai-responses
anthropic-messages

交互操作

启动后界面分为三部分：顶部的启动屏（logo 与环境信息）、中间的对话流、底部的输入框。

   ██╗  ██╗ ██████╗
   ██║ ██╔╝ ██╔══██╗
   █████╔╝  ██████╔╝
   ██╔═██╗  ██╔══██╗
   ██║  ██╗ ██████╔╝
   ╚═╝  ╚═╝ ╚═════╝

   知识库 · Knowledge Base

   知识库  default
   模型    deepseek-flash
   来源    1

   输入问题开始，或键入 /help 查看命令

对话流中不同类型的消息有各自的标记：

| 标记 | 含义 | | --- | --- | | ❯ | 你的提问 | | ⏺ | 模型回答（Markdown 排版，附检索统计与耗时） | | ✔ | 成功（导入完成、命令结果） | | ★ | 本次提问附带的原图 | | ✖ | 错误 | | ! | 用法提示 |

快捷键：

| 按键 | 作用 | | --- | --- | | Enter | 发送 | | Shift+Enter / Ctrl+J | 输入换行（录入多行内容用） | | Esc | 关闭浮层 | | Ctrl+C | 退出 | | Ctrl+A / Ctrl+E | 行首 / 行尾 | | Ctrl+U / Ctrl+K | 删除到行首 / 行尾 | | Ctrl+W | 删除前一个单词 | | Ctrl+- | 撤销 | | Ctrl+Y | 粘贴（yank 最近删除的内容） |

光标可以用方向键或 Ctrl+B / Ctrl+F 左右移动；按单词移动用 Alt+← / Alt+→。

导入文件

支持的文件格式：

Markdown：.md
文本：.txt
JSON：.json
CSV：.csv
Excel：.xlsx、.xls
图片：.png、.jpg、.jpeg、.gif、.webp、.bmp（需要模型支持视觉）

导入命令格式：

导入 <文件路径>

也支持以下关键词：

录入 <文件路径>
整理 <文件路径>
ingest <文件路径>
import <文件路径>

示例：

导入 ./docs/payment.md
import D:\docs\api.txt
导入 "D:\资料\产品说明.xlsx"
导入 "D:\截图\支付报错.png"

路径写法很宽容，下面这几种都能识别（只要文件真实存在）：

录入 D:\资料\支付渠道配置.md到知识库     # 路径后粘了中文
导入D:\资料\支付渠道配置.md              # 关键词后没空格
"D:\资料\文件名字带空格.md"              # 带空格的路径用引号包起来
D:\资料\支付渠道配置.md                 # 直接拖文件进来，不带任何关键词

路径识别走的是本地检查（statSync），不消耗模型调用。

导入后会复制一份原始文件，并建立版本记录。对同一个文件再次导入时，会创建新版本，不会直接覆盖旧版本。

如果路径不存在或是目录，会直接给提示而不去问模型；目录暂不支持导入，请指定具体文件。

让 kb 读写本地文件

除了导入，kb 也把文件读写作为工具交给了模型，所以可以直接用自然语言：

帮我看看 D:\资料\支付渠道配置.md 写了什么？     → 读取文件后回答
把这段内容导出到 D:\out\纪要.md                 → 写入文件
把 D:\资料\渠道.md 收录到知识库                  → 导入知识库

对应的工具：

| 工具 | 作用 | | --- | --- | | save_knowledge | 把对话里的文本存进知识库 | | save_from_file | 把磁盘文件导入知识库（只传路径，正文由程序读取） | | read_file | 读取文件内容（不写进知识库） | | write_file | 把内容写入指定文件 |

模型可能多轮调用这些工具（例如先 read_file 再回答，或直接 save_from_file 完成导入），每轮最多 5 次工具调用。

注意：read_file / write_file 让模型可以访问你本机的文件。kb 是本地工具，在你自己的机器上运行，但请不要在输入里让它处理你不想被读取的敏感路径。

直接录入文本

不需要先把内容存成文件，也不需要记命令——用自然语言告诉 kb 就行：

记住：我的工位在 A 区 12 号，门禁卡号 8823
记一下，下周三下午两点和产品对需求
帮我存个配置：接口超时时间 30 秒，失败重试 3 次
这段你帮我记着：报销单必须贴发票原件

kb 每一轮输入都会先判断你的意图：

提问 → 检索知识库并回答（附来源与版本）
录入 → 调用 save_knowledge 工具存入知识库

判断由模型根据语义完成，不依赖固定关键词。识别为录入后，模型会：

生成标题：用一句话概括内容，作为知识条目标题。
整理内容：转成规范 Markdown，完整保留你给的信息。
落盘建索引：写入 <知识库>/originals/，并入关键词检索，随后提问就能命中。

多行内容按 Shift+Enter（或 Ctrl+J）换行，全部输入完再按 Enter 提交：

帮我记下值班规范：

- 线上告警先看 Grafana 面板 pay-dashboard
- P0 故障 15 分钟内必须响应
- 值班电话 8001，仅限 P0 使用

录入的内容同样遵循版本规则：内容完全相同时再次录入，会生成新版本而不是重复来源。

显式命令（兜底）

模型判断有误、或模型暂时不可用时，可以用 /add 强制录入；以 / 开头的形式不会与自然语言混淆：

/add 支付网关的退款接口是 /api/pay/refund，请求方式 POST
/note 团队周会是每周三下午三点

显式命令不调用模型，标题由程序从内容推导（优先取 Markdown 标题，否则取首个非空行）。

区别：导入 <路径> 是把已有的文件收录进来，/add <内容> 是把输入框里的文字收录进来，而直接说「记住 …」则由模型自己判断。

图片知识

图片本身无法参与关键词检索，因此 kb 对图片使用双通道处理：

入库时生成描述：导入图片时会调用当前模型看图，生成一段中文描述（含图中所有文字、数字、表格与界面细节），写入知识库参与全文检索。
提问时附原图：当问题检索命中图片记录时，kb 会把原始图片一并发送给模型，因此模型看到的是真实图像，而不只是描述。

也就是说，导入一次图片后，既可以按内容关键词搜到它，也可以直接针对图片细节提问：

导入 "D:\截图\支付报错.png"

支付报错的截图里，订单号和错误码分别是什么？

注意：

图片描述依赖当前模型具备视觉能力；模型不支持视觉时，图片仍会入库，但只能按文件名检索，并在导入结果中提示失败原因。
单次提问最多附带 4 张命中图片。
历史对话中不会重复携带图片数据，每轮提问都会按检索结果重新附图。

查询知识

直接输入问题即可：

支付服务的数据库配置是什么？
如何申请退款？
总结产品说明中的核心功能

程序会先在当前知识库中检索，再把匹配到的内容交给模型回答。回答仅允许使用本地知识；如果没有匹配内容，应提示没有找到相关知识。

内置命令

| 命令 | 作用 | | --- | --- | | /help | 查看命令列表 | | /clear | 清空当前对话上下文 | | /sources | 查看当前知识库中的来源文件、路径和版本 | | /add <内容> | 显式录入文本（正常直接说「记住…」即可） | | /models 或 /model | 查看已配置模型 | | /model <编号> | 切换模型，例如 /model 1 | | /kb list | 查看所有知识库 | | /kb current | 查看当前知识库 | | /kb create <名称> | 创建知识库 | | /kb use <id> | 切换知识库 | | /kb delete <id> confirm | 删除非 default 知识库 | | /backup | 创建当前知识库备份 | | /backup <目录> | 备份到指定目录 | | /restore <备份目录> | 从备份恢复 | | /cleanup | 查看历史版本 | | /cleanup <版本ID> confirm | 删除指定历史版本 | | /quit 或 /exit | 退出程序 |

知识库示例：

/kb create payment
/kb list
/kb use payment
/kb current

/kb use 支持使用知识库 ID；知识库名称包含空格时，建议使用生成的 ID。

数据位置

默认数据目录：

~/.kb

Windows 通常对应：

C:\Users\<用户名>\.kb

可通过 KB_DATA_DIR 修改：

$env:KB_DATA_DIR = "D:\kb-data"
kb

数据目录结构大致如下：

.kb/
└── knowledge-bases/
    └── default/
        ├── knowledge.db   # SQLite 数据库
        ├── originals/      # 导入时复制的原始文件
        └── backups/        # 备份文件

不要把 API Key 提交到 Git。模型配置文件中包含明文 API Key，请妥善保护该文件。

开发和测试

在本目录执行：

npm run typecheck
npm run build
npm test

修改源码时编辑 src/，不要直接编辑 dist/。构建后，dist/ 会生成可执行代码。

常见问题

从 0.1.x 升级到 0.2.0 后无法启动

0.2.0 换用了新的终端渲染库，Node.js 要求从 >=22.5.0 提升到 >=22.19.0。

node -v          # 低于 v22.19.0 会启动失败

升级 Node 后重装即可：

npm i -g @ganziliang/kb@latest

0.2.0 是界面重写，存储格式和 ~/.kb 数据目录没有变化，原有知识库和模型配置可以直接沿用。

运行 `kb` 找不到命令

确认 npm 全局 bin 目录已经加入 PATH，或者使用源码方式运行：

node dist/entry.js

PDF 无法导入

当前版本不支持直接解析 PDF。请先将 PDF 转换成 Markdown 或纯文本，再导入转换后的文件。

修改文件后再次导入没有覆盖旧内容

这是预期行为。程序采用版本化存储：新内容会成为当前版本，旧版本可以通过 /cleanup 查看和清理。

恢复备份后查询异常

恢复操作完成后需要退出并重新启动 kb，让程序重新打开 SQLite 数据库。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@ganziliang/kb

环境要求

安装

从 npm 安装

首次启动和模型配置

交互操作

导入文件

让 kb 读写本地文件

直接录入文本

显式命令（兜底）

图片知识

查询知识

内置命令

数据位置

开发和测试

常见问题

从 0.1.x 升级到 0.2.0 后无法启动

运行 kb 找不到命令

PDF 无法导入

修改文件后再次导入没有覆盖旧内容

恢复备份后查询异常

运行 `kb` 找不到命令