@ganziliang/kb 0.1.7 → 0.3.0

package/README.md

@@ -1,10 +1,14 @@
 # @ganziliang/kb
 
-本地知识库命令行工具。它会把本地 Markdown、文本、JSON、CSV 或 Excel 文件导入 SQLite 知识库，然后通过关键词检索相关内容，并调用已配置的模型回答问题。同时支持导入图片：入库时自动生成中文描述参与检索，提问命中后把原图发给模型。
+本地知识库命令行工具。它会把本地 Markdown、文本、JSON、CSV 或 Excel 文件导入 SQLite 知识库，也可以直接录入输入框中的文字，然后通过关键词检索相关内容，并调用已配置的模型回答问题。同时支持导入图片：入库时自动生成中文描述参与检索，提问命中后把原图发给模型。
+
+界面基于 [`@earendil-works/pi-tui`](https://www.npmjs.com/package/@earendil-works/pi-tui) 构建，采用差分渲染：Markdown 回答排版、带边框的编辑器、加载动画与命令浮层。
+
+> **0.2.0 提示**：这是界面重写版本，Node.js 要求提升到 `>=22.19.0`。存储格式与 `~/.kb` 数据目录未变，旧知识库可直接使用。详见[常见问题](#从-01x-升级到-020-后无法启动)。
 
 ## 环境要求
 
-- Node.js `>=22.5.0`
+- Node.js `>=22.19.0`（当前 UI 依赖的终端渲染库要求，低于此版本无法启动）
 - 如果使用模型问答，需要可用的模型 API Key
 - 首次启动需要配置模型
 
@@ -105,7 +109,51 @@ kb
 
 ## 交互操作
 
-启动 `kb` 后，在底部的 `> ` 提示符后输入内容并按 Enter。
+启动后界面分为三部分：顶部的启动屏（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+→`。
 
 ### 导入文件
 
@@ -144,6 +192,55 @@ import D:\docs\api.txt
 
 导入后会复制一份原始文件，并建立版本记录。对同一个文件再次导入时，会创建新版本，不会直接覆盖旧版本。
 
+### 直接录入文本
+
+不需要先把内容存成文件，也不需要记命令——用自然语言告诉 kb 就行：
+
+```text
+记住：我的工位在 A 区 12 号，门禁卡号 8823
+记一下，下周三下午两点和产品对需求
+帮我存个配置：接口超时时间 30 秒，失败重试 3 次
+这段你帮我记着：报销单必须贴发票原件
+```
+
+kb 每一轮输入都会先判断你的意图：
+
+- **提问** → 检索知识库并回答（附来源与版本）
+- **录入** → 调用 `save_knowledge` 工具存入知识库
+
+判断由模型根据语义完成，**不依赖固定关键词**。识别为录入后，模型会：
+
+1. **生成标题**：用一句话概括内容，作为知识条目标题。
+2. **整理内容**：转成规范 Markdown，完整保留你给的信息。
+3. **落盘建索引**：写入 `<知识库>/originals/`，并入关键词检索，随后提问就能命中。
+
+多行内容按 **Shift+Enter**（或 `Ctrl+J`）换行，全部输入完再按 `Enter` 提交：
+
+```text
+帮我记下值班规范：
+
+- 线上告警先看 Grafana 面板 pay-dashboard
+- P0 故障 15 分钟内必须响应
+- 值班电话 8001，仅限 P0 使用
+```
+
+录入的内容同样遵循版本规则：内容完全相同时再次录入，会生成新版本而不是重复来源。
+
+#### 显式命令（兜底）
+
+模型判断有误、或模型暂时不可用时，可以用 `/add` 强制录入；
+以 `/` 开头的形式不会与自然语言混淆：
+
+```text
+/add 支付网关的退款接口是 /api/pay/refund，请求方式 POST
+/note 团队周会是每周三下午三点
+```
+
+显式命令不调用模型，标题由程序从内容推导（优先取 Markdown 标题，否则取首个非空行）。
+
+> 区别：`导入 <路径>` 是把**已有的文件**收录进来，`/add <内容>` 是把**输入框里的文字**收录进来，
+> 而直接说「记住 …」则由模型自己判断。
+
 ### 图片知识
 
 图片本身无法参与关键词检索，因此 `kb` 对图片使用双通道处理：
@@ -184,6 +281,7 @@ import D:\docs\api.txt
 | `/help` | 查看命令列表 |
 | `/clear` | 清空当前对话上下文 |
 | `/sources` | 查看当前知识库中的来源文件、路径和版本 |
+| `/add <内容>` | 显式录入文本（正常直接说「记住…」即可） |
 | `/models` 或 `/model` | 查看已配置模型 |
 | `/model <编号>` | 切换模型，例如 `/model 1` |
 | `/kb list` | 查看所有知识库 |
@@ -257,6 +355,22 @@ npm test
 
 ## 常见问题
 
+### 从 0.1.x 升级到 0.2.0 后无法启动
+
+0.2.0 换用了新的终端渲染库，Node.js 要求从 `>=22.5.0` 提升到 `>=22.19.0`。
+
+```bash
+node -v          # 低于 v22.19.0 会启动失败
+```
+
+升级 Node 后重装即可：
+
+```bash
+npm i -g @ganziliang/kb@latest
+```
+
+0.2.0 是界面重写，存储格式和 `~/.kb` 数据目录没有变化，原有知识库和模型配置可以直接沿用。
+
 ### 运行 `kb` 找不到命令
 
 确认 npm 全局 bin 目录已经加入 PATH，或者使用源码方式运行：

package/dist/cli.d.ts

@@ -1,2 +1,41 @@
 #!/usr/bin/env node
+import { ensureModelConfig } from "./config.js";
+import { type KnowledgeBase } from "./storage.js";
+type ModelConfig = Awaited<ReturnType<typeof ensureModelConfig>>[number];
+export declare class KbApp {
+    private readonly root;
+    private readonly tui;
+    private readonly stream;
+    private readonly editor;
+    private store;
+    private base;
+    private models;
+    private modelIndex;
+    private messages;
+    private turns;
+    private busy;
+    private loader;
+    private overlay;
+    private closed;
+    constructor(root: string, base: KnowledgeBase, models: ModelConfig[]);
+    start(): void;
+    private get model();
+    private add;
+    private setBusy;
+    private showOverlay;
+    private closeOverlay;
+    private shutdown;
+    private submit;
+    private run;
+    private addNote;
+    private ingest;
+    private ask;
+    private command;
+    private showSources;
+    private showModelPicker;
+    private switchModel;
+    private kbCommand;
+    private cleanup;
+}
 export declare function main(): Promise<void>;
+export {};