@ganziliang/kb 0.1.4 → 0.1.5

package/README.md

@@ -0,0 +1,254 @@
+# @ganziliang/kb
+
+本地知识库命令行工具。它会把本地 Markdown、文本、JSON、CSV 或 Excel 文件导入 SQLite 知识库，然后通过关键词检索相关内容，并调用已配置的模型回答问题。
+
+## 环境要求
+
+- Node.js `>=22.5.0`
+- 如果使用模型问答，需要可用的模型 API Key
+- 首次启动需要配置模型
+
+## 安装
+
+### 从 npm 安装
+
+```bash
+npm install -g @ganziliang/kb
+```
+
+安装后使用 `kb` 命令：
+
+```bash
+kb
+```
+
+### 在源码目录运行
+
+```bash
+cd D:\IDEAProject\ai_work\zhishiku\kb
+npm install
+npm run build
+node dist/entry.js
+```
+
+如果希望全局的 `kb` 命令使用当前源码构建结果，可以在源码目录执行：
+
+```bash
+npm link
+npm run build
+```
+
+## 首次启动和模型配置
+
+直接运行：
+
+```bash
+kb
+```
+
+首次启动时，程序会询问：
+
+1. `api-stats` 页面地址或 `apiId`
+2. API Key
+
+当前默认使用智真 LLM Gateway：
+
+```text
+https://llm-gateway.zhizhengroup.com
+```
+
+`api-stats` 地址示例：
+
+```text
+https://llm-gateway.zhizhengroup.com/admin-next/api-stats?apiId=<你的apiId>
+```
+
+模型配置保存位置：
+
+```text
+~/.config/kb/config.json
+```
+
+Windows 通常对应：
+
+```text
+C:\Users\<用户名>\.config\kb\config.json
+```
+
+也可以通过环境变量跳过首次交互配置：
+
+```bash
+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 写法：
+
+```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`
+
+## 交互操作
+
+启动 `kb` 后，在底部的 `> ` 提示符后输入内容并按 Enter。
+
+### 导入文件
+
+支持的文件格式：
+
+- Markdown：`.md`
+- 文本：`.txt`
+- JSON：`.json`
+- CSV：`.csv`
+- Excel：`.xlsx`、`.xls`
+
+导入命令格式：
+
+```text
+导入 <文件路径>
+```
+
+也支持以下关键词：
+
+```text
+录入 <文件路径>
+整理 <文件路径>
+ingest <文件路径>
+import <文件路径>
+```
+
+示例：
+
+```text
+导入 ./docs/payment.md
+import D:\docs\api.txt
+导入 "D:\资料\产品说明.xlsx"
+```
+
+导入后会复制一份原始文件，并建立版本记录。对同一个文件再次导入时，会创建新版本，不会直接覆盖旧版本。
+
+### 查询知识
+
+直接输入问题即可：
+
+```text
+支付服务的数据库配置是什么？
+如何申请退款？
+总结产品说明中的核心功能
+```
+
+程序会先在当前知识库中检索，再把匹配到的内容交给模型回答。回答仅允许使用本地知识；如果没有匹配内容，应提示没有找到相关知识。
+
+### 内置命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `/help` | 查看命令列表 |
+| `/clear` | 清空当前对话上下文 |
+| `/sources` | 查看当前知识库中的来源文件、路径和版本 |
+| `/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` | 退出程序 |
+
+知识库示例：
+
+```text
+/kb create payment
+/kb list
+/kb use payment
+/kb current
+```
+
+`/kb use` 支持使用知识库 ID；知识库名称包含空格时，建议使用生成的 ID。
+
+## 数据位置
+
+默认数据目录：
+
+```text
+~/.kb
+```
+
+Windows 通常对应：
+
+```text
+C:\Users\<用户名>\.kb
+```
+
+可通过 `KB_DATA_DIR` 修改：
+
+```powershell
+$env:KB_DATA_DIR = "D:\kb-data"
+kb
+```
+
+数据目录结构大致如下：
+
+```text
+.kb/
+└── knowledge-bases/
+    └── default/
+        ├── knowledge.db   # SQLite 数据库
+        ├── originals/      # 导入时复制的原始文件
+        └── backups/        # 备份文件
+```
+
+不要把 API Key 提交到 Git。模型配置文件中包含明文 API Key，请妥善保护该文件。
+
+## 开发和测试
+
+在本目录执行：
+
+```bash
+npm run typecheck
+npm run build
+npm test
+```
+
+修改源码时编辑 `src/`，不要直接编辑 `dist/`。构建后，`dist/` 会生成可执行代码。
+
+## 常见问题
+
+### 运行 `kb` 找不到命令
+
+确认 npm 全局 bin 目录已经加入 PATH，或者使用源码方式运行：
+
+```bash
+node dist/entry.js
+```
+
+### PDF 无法导入
+
+当前版本不支持直接解析 PDF。请先将 PDF 转换成 Markdown 或纯文本，再导入转换后的文件。
+
+### 修改文件后再次导入没有覆盖旧内容
+
+这是预期行为。程序采用版本化存储：新内容会成为当前版本，旧版本可以通过 `/cleanup` 查看和清理。
+
+### 恢复备份后查询异常
+
+恢复操作完成后需要退出并重新启动 `kb`，让程序重新打开 SQLite 数据库。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganziliang/kb",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Local knowledge base agent CLI",
   "type": "module",
   "bin": {