@ganziliang/kb 0.1.7 → 0.2.0

package/README.md

@@ -2,9 +2,13 @@
 
 本地知识库命令行工具。它会把本地 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,48 @@ kb
 
 ## 交互操作
 
-启动 `kb` 后，在底部的 `> ` 提示符后输入内容并按 Enter。
+启动后界面分为三部分：顶部的启动屏（logo 与环境信息）、中间的对话流、底部的输入框。
+
+```
+   ██╗  ██╗ ██████╗
+   ██║ ██╔╝ ██╔══██╗
+   █████╔╝  ██████╔╝
+   ██╔═██╗  ██╔══██╗
+   ██║  ██╗ ██████╔╝
+   ╚═╝  ╚═╝ ╚═════╝
+
+   知识库 · Knowledge Base
+
+   知识库  default
+   模型    deepseek-flash
+   来源    1
+
+   输入问题开始，或键入 /help 查看命令
+```
+
+对话流中不同类型的消息有各自的标记：
+
+| 标记 | 含义 |
+| --- | --- |
+| `❯` | 你的提问 |
+| `⏺` | 模型回答（Markdown 排版，附检索统计与耗时） |
+| `✔` | 成功（导入完成、命令结果） |
+| `★` | 本次提问附带的原图 |
+| `✖` | 错误 |
+| `!` | 用法提示 |
+
+快捷键：
+
+| 按键 | 作用 |
+| --- | --- |
+| `Enter` | 发送 |
+| `Esc` | 关闭浮层 |
+| `Ctrl+C` | 退出 |
+| `Ctrl+A` / `Ctrl+E` | 行首 / 行尾 |
+| `Ctrl+U` / `Ctrl+K` | 删除到行首 / 行尾 |
+| `Ctrl+W` | 删除前一个单词 |
+
+输入框支持多行编辑与撤销：`Ctrl+Z` 撤销，`Ctrl+Y` 重做。
 
 ### 导入文件
 
@@ -257,6 +302,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,40 @@
 #!/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 ingest;
+    private ask;
+    private command;
+    private showSources;
+    private showModelPicker;
+    private switchModel;
+    private kbCommand;
+    private cleanup;
+}
 export declare function main(): Promise<void>;
+export {};

package/dist/cli.js

@@ -1,204 +1,390 @@
 #!/usr/bin/env node
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from "react";
-import { Box, Text, render, useApp, useInput } from "ink";
 import { mkdirSync } from "node:fs";
+import { Container, Editor, Loader, ProcessTerminal, SelectList, Spacer, TuiMainScreen, matchesKey, } from "@earendil-works/pi-tui";
 import { ensureModelConfig, saveModels } from "./config.js";
 import { Agent, describeImage, fetchTransport } from "./model.js";
-import { copyOriginal, defaultDataRoot, ensureKnowledgeBase, isImageFile, KnowledgeStore, readImage, readLocalFile, listKnowledgeBases, deleteKnowledgeBase, backupKnowledgeBase, restoreKnowledgeBase } from "./storage.js";
-const banner = [
-    "  _  __ ____  ",
-    " | |/ // __ ) ",
-    " |   // __  | ",
-    " |   |/ /_/ / ",
-    " |_|\\_\\____/ ",
-    " Welcome to KB Knowledge Base",
+import { backupKnowledgeBase, copyOriginal, defaultDataRoot, deleteKnowledgeBase, ensureKnowledgeBase, isImageFile, KnowledgeStore, listKnowledgeBases, readImage, readLocalFile, restoreKnowledgeBase, } from "./storage.js";
+import { color, editorTheme, selectListTheme } from "./theme.js";
+import { AssistantMessage, HelpPanel, ImageNotice, Notice, Rule, Splash, UserMessage } from "./ui.js";
+const errText = (error) => (error instanceof Error ? error.message : String(error));
+const HELP_ITEMS = [
+    ["/help", "显示本帮助"],
+    ["/clear", "清空对话上下文"],
+    ["/sources", "列出知识来源与版本"],
+    ["/model", "查看 / 切换模型"],
+    ["/kb", "多知识库管理"],
+    ["/backup", "备份当前知识库"],
+    ["/restore", "��备份恢复"],
+    ["/cleanup", "清理历史版本"],
+    ["/quit", "退出"],
+    ["", ""],
+    ["导入 <路径>", "录入 md / txt / json / csv / xlsx / png / jpg"],
 ];
-function App({ config, root, knowledgeBase }) {
-    const { exit } = useApp();
-    const [input, setInput] = useState("");
-    const [lines, setLines] = useState([...banner, `knowledge base: ${knowledgeBase.name}`, "Type a question, or /help."]);
-    const [busy, setBusy] = useState(false);
-    const [messages, setMessages] = useState([]);
-    const [modelIndex, setModelIndex] = useState(0);
-    const [currentBase, setCurrentBase] = useState(knowledgeBase);
-    const storeRef = useRef(new KnowledgeStore(knowledgeBase.path));
-    const store = storeRef.current;
-    useEffect(() => () => storeRef.current.close(), []);
-    useInput((char, key) => {
-        if (key.ctrl && char === "c") {
-            store.close();
-            exit();
-            return;
+const ROLE = { user: "❯", assistant: "⏺", ok: "✔", err: "✖", warn: "!", image: "★" };
+export class KbApp {
+    root;
+    tui;
+    stream = new Container();
+    editor;
+    store;
+    base;
+    models;
+    modelIndex = 0;
+    messages = [];
+    turns = 0;
+    busy = false;
+    loader = null;
+    overlay = null;
+    closed = false;
+    constructor(root, base, models) {
+        this.root = root;
+        this.base = base;
+        this.models = models;
+        this.store = new KnowledgeStore(base.path);
+        this.tui = new TuiMainScreen(new ProcessTerminal());
+        this.editor = new Editor(this.tui, editorTheme, { paddingX: 1 });
+        this.editor.onSubmit = (text) => { void this.submit(text.trim()); };
+    }
+    // ---------- 启动 ----------
+    start() {
+        this.tui.addChild(new Splash({
+            base: this.base.name,
+            model: this.model?.model ?? "-",
+            dataPath: this.root,
+            sources: this.store.sources().length,
+        }));
+        this.tui.addChild(this.stream);
+        this.tui.addChild(new Spacer(1));
+        this.tui.addChild(new Rule());
+        this.tui.addChild(this.editor);
+        this.tui.setFocus(this.editor);
+        this.tui.addInputListener((data) => {
+            if (matchesKey(data, "ctrl+c")) {
+                this.shutdown();
+                return { consume: true };
+            }
+            if (matchesKey(data, "escape") && this.tui.hasOverlay()) {
+                this.closeOverlay();
+                return { consume: true };
+            }
+            return {};
+        });
+        this.tui.start();
+    }
+    get model() { return this.models[this.modelIndex]; }
+    // ---------- 渲染原语 ----------
+    add(component) {
+        this.stream.addChild(component);
+        this.tui.requestRender();
+    }
+    setBusy(on, message = "") {
+        if (on) {
+            this.editor.disableSubmit = true;
+            if (this.loader) {
+                this.loader.setMessage(message);
+            }
+            else {
+                this.loader = new Loader(this.tui, color.accent, color.muted, message);
+                this.stream.addChild(this.loader);
+                this.loader.start();
+            }
         }
-        if (key.return && input.trim() && !busy) {
-            void submit(input.trim());
-            setInput("");
-            return;
+        else {
+            this.editor.disableSubmit = false;
+            if (this.loader) {
+                this.loader.stop();
+                this.stream.removeChild(this.loader);
+                this.loader = null;
+            }
         }
-        if (key.backspace || key.delete) {
-            setInput((value) => value.slice(0, -1));
-            return;
+        this.tui.requestRender();
+    }
+    showOverlay(component, width) {
+        this.closeOverlay();
+        this.overlay = this.tui.showOverlay(component, { width, anchor: "center", margin: 1 });
+    }
+    closeOverlay() {
+        if (this.overlay) {
+            this.overlay.hide();
+            this.overlay = null;
         }
-        if (!key.ctrl && !key.meta && char)
-            setInput((value) => value + char);
-    });
-    async function submit(value) {
-        if (value === "/quit" || value === "/exit") {
-            store.close();
-            exit();
+        this.tui.setFocus(this.editor);
+    }
+    shutdown() {
+        if (this.closed)
             return;
+        this.closed = true;
+        try {
+            this.store.close();
         }
-        if (value === "/clear") {
-            setLines(["Conversation cleared."]);
-            setMessages([]);
+        catch { /* 已关闭 */ }
+        this.tui.stop();
+        process.exit(0);
+    }
+    // ---------- 输入入口 ----------
+    async submit(value) {
+        if (this.busy || !value)
             return;
-        }
-        if (value === "/help") {
-            setLines((old) => [...old, "/help /clear /sources /backup /restore /cleanup /model /models /kb /quit", "导入：输入「导入 <文件路径>」，支持 .md/.txt/.json/.csv/.xlsx/.xls 及 .png/.jpg/.jpeg/.gif/.webp/.bmp", "图片入库时自动生成中文描述用于检索，提问命中后会把原图一并发给模型"]);
+        this.editor.setText("");
+        this.tui.requestRender();
+        if (value.startsWith("/")) {
+            await this.command(value);
             return;
         }
-        if (value === "/sources") {
-            setLines((old) => [...old, ...store.sources().map((s) => `${s.name} | ${s.path} | v${s.version} | ${s.updatedAt}`)]);
+        this.turns += 1;
+        this.add(new UserMessage(value));
+        await this.run(value);
+    }
+    async run(value) {
+        const pathMatch = value.match(/(?:录入|导入|整理|ingest|import)\s+(.+)$/i);
+        if (pathMatch) {
+            await this.ingest(pathMatch[1].trim().replace(/^['"]|['"]$/g, ""));
             return;
         }
-        if (value === "/model" || value === "/models") {
-            setLines((old) => [...old, ...config.map((item, i) => `${i === modelIndex ? "*" : " "} ${i}: ${item.provider}/${item.model} (${item.api})`)]);
+        await this.ask(value);
+    }
+    // ---------- 导入 ----------
+    async ingest(path) {
+        try {
+            this.setBusy(true, "读取文件…");
+            const source = readLocalFile(path);
+            if (!source.hash) {
+                this.add(new Notice(ROLE.err, color.err, `${source.title}：无法解析（${source.content}）`));
+                return;
+            }
+            let content = source.content;
+            let note = "";
+            if (source.image) {
+                this.setBusy(true, "识别图片并生成描述…");
+                try {
+                    const caption = await describeImage(this.model, fetchTransport, source.image);
+                    if (caption) {
+                        content = `${source.content}\n\n${caption}`;
+                        note = "，已生成图片描述";
+                    }
+                }
+                catch {
+                    note = "，图片描述生成失败（仅按文件名检索）";
+                }
+            }
+            const copied = copyOriginal(source.originalPath, this.store.root);
+            const result = this.store.addOrUpdateSource(copied, source.title, content);
+            this.add(new Notice(ROLE.ok, color.ok, `${result.isNew ? "已导入" : "已创建新版本"} ${result.title}（v${result.version}）${note}`));
+        }
+        catch (error) {
+            this.add(new Notice(ROLE.err, color.err, `导入失败：${errText(error)}`));
+        }
+        finally {
+            this.setBusy(false);
+        }
+    }
+    // ---------- 问答 ----------
+    async ask(question) {
+        const config = this.model;
+        if (!config) {
+            this.add(new Notice(ROLE.err, color.err, "没有可用模型，请先配置模型。"));
             return;
         }
-        if (value.startsWith("/model ")) {
-            const index = Number(value.slice(7));
-            if (config[index]) {
-                setModelIndex(index);
-                saveModels([config[index], ...config.filter((_, i) => i !== index)]);
-                setLines((old) => [...old, `Using ${config[index].model}`]);
+        const started = Date.now();
+        try {
+            this.setBusy(true, "检索知识库…");
+            const results = this.store.search(question);
+            const context = results.length
+                ? results.map((item) => `[${item.id}] ${item.title} (source: ${item.source}, v${item.version})\n${item.content}`).join("\n\n")
+                : "No matching knowledge was found.";
+            const prompt = `Answer only from the local knowledge below. If it is insufficient, say no knowledge was found. Include source filename and version.\n\n${context}\n\nQuestion: ${question}`;
+            const blocks = [{ type: "text", text: prompt }];
+            const attached = [];
+            for (const item of results.filter((hit) => hit.originalPath && isImageFile(hit.originalPath)).slice(0, 4)) {
+                try {
+                    const image = readImage(item.originalPath);
+                    blocks.push({ type: "text", text: `[附图] ${item.source} v${item.version}` });
+                    blocks.push({ type: "image", mediaType: image.mediaType, base64: image.base64 });
+                    attached.push({ name: item.source, version: item.version });
+                }
+                catch { /* 跳过无法读取的图片 */ }
             }
-            else
-                setLines((old) => [...old, "Unknown model index."]);
-            return;
+            this.setBusy(true, attached.length ? `命中 ${results.length} 条，附图 ${attached.length} 张，正在生成回答…` : `命中 ${results.length} 条，正在生成回答…`);
+            const agent = new Agent(this.store, config, fetchTransport);
+            const answer = await agent.answer(blocks.length > 1 ? blocks : prompt, this.messages);
+            this.messages = answer.messages;
+            this.store.saveMessage("user", question);
+            this.store.saveMessage("assistant", answer.text);
+            for (const item of attached)
+                this.add(new ImageNotice(item.name, item.version));
+            const seconds = ((Date.now() - started) / 1000).toFixed(1);
+            const meta = `检索 ${results.length} 条 · 命中 ${results.length} 条 · ${seconds}s` + (attached.length ? ` · 附图 ${attached.length} 张` : "");
+            this.add(new AssistantMessage(answer.text || "（模型返回空回答）", meta));
+        }
+        catch (error) {
+            this.add(new Notice(ROLE.err, color.err, `模型请求失败：${errText(error)}`));
+        }
+        finally {
+            this.setBusy(false);
         }
-        if (value.startsWith("/kb ")) {
-            const [command, ...args] = value.slice(4).trim().split(/\s+/);
-            if (command === "list") {
-                setLines((old) => [...old, ...listKnowledgeBases(root).map((item) => `${item.id}${item.id === currentBase.id ? " *" : ""}`)]);
+    }
+    // ---------- 命令 ----------
+    async command(value) {
+        const [cmd, ...rest] = value.split(/\s+/);
+        const arg = rest.join(" ");
+        switch (cmd) {
+            case "/quit":
+            case "/exit":
+                this.shutdown();
                 return;
-            }
-            if (command === "current") {
-                setLines((old) => [...old, `${currentBase.name} (${currentBase.id})`]);
+            case "/help":
+                this.showOverlay(new HelpPanel(HELP_ITEMS), 66);
                 return;
-            }
-            if (command === "create" && args.length) {
-                const created = ensureKnowledgeBase(root, args.join(" "));
-                setLines((old) => [...old, `Created ${created.name} (${created.id})`]);
+            case "/clear":
+                this.stream.clear();
+                this.messages = [];
+                this.turns = 0;
+                this.add(new Notice(ROLE.ok, color.ok, "已清空对话上下文。"));
                 return;
-            }
-            if (command === "use" && args[0]) {
-                const selected = listKnowledgeBases(root).find((item) => item.id === args[0] || item.name === args.join(" "));
-                if (!selected) {
-                    setLines((old) => [...old, "Knowledge base not found."]);
+            case "/sources": return this.showSources();
+            case "/model":
+            case "/models":
+                if (!rest.length) {
+                    this.showModelPicker();
                     return;
                 }
-                store.close();
-                storeRef.current = new KnowledgeStore(selected.path);
-                setCurrentBase(selected);
-                setMessages([]);
-                setLines((old) => [...old, `Using ${selected.name}`]);
+                this.switchModel(Number(rest[0]));
                 return;
-            }
-            if (command === "delete" && args[0] && args[1] === "confirm") {
-                deleteKnowledgeBase(root, args[0]);
-                setLines((old) => [...old, `Deleted ${args[0]}; backups were retained.`]);
+            case "/kb": return this.kbCommand(rest, arg);
+            case "/backup": {
+                const target = backupKnowledgeBase(this.base, arg || undefined);
+                this.add(new Notice(ROLE.ok, color.ok, `已备份到 ${target}`));
                 return;
             }
-            setLines((old) => [...old, "Usage: /kb list | /kb create <name> | /kb use <id> | /kb current | /kb delete <id> confirm"]);
-            return;
+            case "/restore":
+                if (!arg) {
+                    this.add(new Notice(ROLE.warn, color.warn, "用法：/restore <备份目录>"));
+                    return;
+                }
+                restoreKnowledgeBase(this.base, arg);
+                this.add(new Notice(ROLE.ok, color.ok, "已恢复。重启 kb 后重新打开数据库。"));
+                return;
+            case "/cleanup": return this.cleanup(rest);
+            default:
+                this.add(new Notice(ROLE.warn, color.warn, `未知命令 ${cmd}，输入 /help 查看可用命令。`));
         }
-        if (value === "/backup" || value.startsWith("/backup ")) {
-            setLines((old) => [...old, `Backup created at ${backupKnowledgeBase(currentBase, value.slice(7).trim() || undefined)}`]);
+    }
+    showSources() {
+        const sources = this.store.sources();
+        if (!sources.length) {
+            this.add(new Notice(ROLE.warn, color.warn, "知识库还是空的，用「导入 <文件路径>」录入内容。"));
             return;
         }
-        if (value.startsWith("/restore ")) {
-            restoreKnowledgeBase(currentBase, value.slice(9).trim());
-            setLines((old) => [...old, "Knowledge base restored. Restart the session to reopen the database."]);
+        this.add(new Notice(ROLE.ok, color.ok, `共 ${sources.length} 个来源：`));
+        for (const source of sources) {
+            this.add(new Notice(" ", color.muted, `${String(source.name)}  v${String(source.version)}  ${String(source.updatedAt)}`));
+        }
+    }
+    showModelPicker() {
+        if (!this.models.length) {
+            this.add(new Notice(ROLE.err, color.err, "没有已配置的模型。"));
             return;
         }
-        if (value === "/cleanup") {
-            const oldVersions = store.oldVersions();
-            setLines((old) => [...old, oldVersions.length ? `Old versions (delete with /cleanup <id> confirm): ${oldVersions.map((item) => `${item.id} ${item.title} v${item.version}`).join("; ")}` : "No old versions."]);
+        const items = this.models.map((m, index) => ({
+            value: String(index),
+            label: `${m.provider}/${m.model}`,
+            description: `${m.api}${index === this.modelIndex ? "   ← 当前" : ""}`,
+        }));
+        const list = new SelectList(items, Math.min(items.length, 10), selectListTheme);
+        list.onSelect = (item) => { this.switchModel(Number(item.value)); this.closeOverlay(); };
+        list.onCancel = () => { this.closeOverlay(); };
+        this.showOverlay(list, 68);
+    }
+    switchModel(index) {
+        const next = this.models[index];
+        if (!next) {
+            this.add(new Notice(ROLE.err, color.err, `没有编号为 ${index} 的模型。`));
             return;
         }
-        if (value.startsWith("/cleanup ")) {
-            const [id, confirmation] = value.slice(9).trim().split(/\s+/);
-            if (confirmation === "confirm") {
-                store.removeVersions([id]);
-                setLines((old) => [...old, `Deleted old version ${id}.`]);
+        this.modelIndex = index;
+        this.models = [next, ...this.models.filter((_, i) => i !== index)];
+        saveModels(this.models);
+        this.add(new Notice(ROLE.ok, color.ok, `已切换到 ${next.provider}/${next.model}`));
+    }
+    kbCommand(rest, arg) {
+        const [sub, ...args] = rest;
+        if (!sub || sub === "list") {
+            const bases = listKnowledgeBases(this.root);
+            this.add(new Notice(ROLE.ok, color.ok, `共 ${bases.length} 个知识库：`));
+            for (const item of bases) {
+                this.add(new Notice(" ", color.muted, `${item.id}${item.id === this.base.id ? "   ← 当前" : ""}`));
             }
-            else
-                setLines((old) => [...old, "Usage: /cleanup <version-id> confirm"]);
             return;
         }
-        setBusy(true);
-        setLines((old) => [...old, `> ${value}`]);
-        try {
-            const result = await ingestOrAsk(value, store, config[modelIndex], messages);
-            setMessages(result.messages);
-            store.saveMessage("user", value);
-            store.saveMessage("assistant", result.text);
-            setLines((old) => [...old, result.text]);
+        if (sub === "current") {
+            this.add(new Notice(ROLE.ok, color.ok, `${this.base.name}（${this.base.id}）`));
+            return;
         }
-        catch (error) {
-            setLines((old) => [...old, `Error: ${error instanceof Error ? error.message : String(error)}`]);
+        if (sub === "create") {
+            if (!args.length) {
+                this.add(new Notice(ROLE.warn, color.warn, "用法：/kb create <名称>"));
+                return;
+            }
+            const created = ensureKnowledgeBase(this.root, args.join(" "));
+            this.add(new Notice(ROLE.ok, color.ok, `已创建 ${created.name}（${created.id}）`));
+            return;
         }
-        finally {
-            setBusy(false);
+        if (sub === "use") {
+            const selected = listKnowledgeBases(this.root).find((item) => item.id === args[0] || item.name === args.join(" "));
+            if (!selected) {
+                this.add(new Notice(ROLE.err, color.err, `未找到知识库 ${arg}`));
+                return;
+            }
+            this.store.close();
+            this.store = new KnowledgeStore(selected.path);
+            this.base = selected;
+            this.messages = [];
+            this.turns = 0;
+            this.add(new Notice(ROLE.ok, color.ok, `已切换到知识库 ${selected.name}（${this.store.sources().length} 个来源）`));
+            return;
         }
-    }
-    return _jsxs(Box, { flexDirection: "column", padding: 1, children: [lines.slice(-18).map((line, i) => _jsx(Text, { children: line }, `${i}-${line}`)), _jsxs(Text, { color: busy ? "yellow" : "cyan", children: [busy ? "Searching..." : "> ", input] })] });
-}
-async function ingestOrAsk(value, store, modelConfig, previous) {
-    const pathMatch = value.match(/(?:录入|导入|整理|ingest|import)\s+(.+)$/i);
-    if (pathMatch) {
-        const source = readLocalFile(pathMatch[1].trim().replace(/^['"]|['"]$/g, ""));
-        if (!source.hash)
-            return { text: `${source.title}: unable to parse (${source.content})`, messages: previous };
-        let content = source.content;
-        let note = "";
-        if (source.image) {
+        if (sub === "delete") {
+            if (!args[0] || args[1] !== "confirm") {
+                this.add(new Notice(ROLE.warn, color.warn, "用法：/kb delete <id> confirm"));
+                return;
+            }
             try {
-                const caption = await describeImage(modelConfig, fetchTransport, source.image);
-                if (caption) {
-                    content = `${source.content}\n\n${caption}`;
-                    note = "，已生成图片描述";
-                }
+                deleteKnowledgeBase(this.root, args[0]);
+                this.add(new Notice(ROLE.ok, color.ok, `已删除 ${args[0]}，备份已保留。`));
             }
             catch (error) {
-                note = `，图片描述生成失败（仅按文件名检索）: ${error instanceof Error ? error.message : String(error)}`;
+                this.add(new Notice(ROLE.err, color.err, errText(error)));
             }
+            return;
         }
-        const copied = copyOriginal(source.originalPath, store.root);
-        const result = store.addOrUpdateSource(copied, source.title, content);
-        return { text: `${result.isNew ? "Imported" : "New version created for"} ${result.title} (v${result.version})${note}`, messages: previous };
+        this.add(new Notice(ROLE.warn, color.warn, "用法：/kb list | /kb create <名称> | /kb use <id> | /kb current | /kb delete <id> confirm"));
     }
-    const results = store.search(value);
-    const context = results.length ? results.map((item) => `[${item.id}] ${item.title} (source: ${item.source}, v${item.version})\n${item.content}`).join("\n\n") : "No matching knowledge was found.";
-    const prompt = `Answer only from the local knowledge below. If it is insufficient, say no knowledge was found. Include source filename and version.\n\n${context}\n\nQuestion: ${value}`;
-    const blocks = [{ type: "text", text: prompt }];
-    for (const item of results.filter((hit) => hit.originalPath && isImageFile(hit.originalPath)).slice(0, 4)) {
-        try {
-            const image = readImage(item.originalPath);
-            blocks.push({ type: "text", text: `[附图] ${item.source} v${item.version}` });
-            blocks.push({ type: "image", mediaType: image.mediaType, base64: image.base64 });
+    cleanup(rest) {
+        if (!rest.length) {
+            const old = this.store.oldVersions();
+            if (!old.length) {
+                this.add(new Notice(ROLE.ok, color.ok, "没有历史版本。"));
+                return;
+            }
+            this.add(new Notice(ROLE.warn, color.warn, `历史版本 ${old.length} 个，用 /cleanup <版本ID> confirm 删除：`));
+            for (const item of old)
+                this.add(new Notice(" ", color.muted, `${String(item.id)}  ${String(item.title)} v${String(item.version)}`));
+            return;
+        }
+        const [id, confirmation] = rest;
+        if (confirmation !== "confirm") {
+            this.add(new Notice(ROLE.warn, color.warn, "用法：/cleanup <版本ID> confirm"));
+            return;
         }
-        catch { /* 忽略无法读取的图片 */ }
+        this.store.removeVersions([id]);
+        this.add(new Notice(ROLE.ok, color.ok, `已删除历史版本 ${id}。`));
     }
-    const agent = new Agent(store, modelConfig, fetchTransport);
-    return agent.answer(blocks.length > 1 ? blocks : prompt, previous);
 }
 export async function main() {
     const root = defaultDataRoot();
     mkdirSync(root, { recursive: true });
-    const knowledgeRoot = root;
     const base = ensureKnowledgeBase(root, "default");
-    const configs = await ensureModelConfig();
-    render(_jsx(App, { config: configs, root: knowledgeRoot, knowledgeBase: base }));
+    const models = await ensureModelConfig();
+    const app = new KbApp(root, base, models);
+    app.start();
 }

package/dist/theme.d.ts

@@ -0,0 +1,27 @@
+import type { EditorTheme, ImageTheme, MarkdownTheme, SelectListTheme } from "@earendil-works/pi-tui";
+export declare const fg: (r: number, g: number, b: number) => (s: string) => string;
+export declare const bg: (r: number, g: number, b: number) => (s: string) => string;
+export declare const bold: (s: string) => string;
+export declare const dim: (s: string) => string;
+export declare const italic: (s: string) => string;
+export declare const underline: (s: string) => string;
+export declare const strike: (s: string) => string;
+/** 全局配色：slate/sky/teal 冷色调，深浅终端下都有足够对比度。 */
+export declare const color: {
+    accent: (s: string) => string;
+    accent2: (s: string) => string;
+    user: (s: string) => string;
+    text: (s: string) => string;
+    muted: (s: string) => string;
+    dim: (s: string) => string;
+    border: (s: string) => string;
+    ok: (s: string) => string;
+    warn: (s: string) => string;
+    err: (s: string) => string;
+    chip: (s: string) => string;
+    userBg: (s: string) => string;
+};
+export declare const markdownTheme: MarkdownTheme;
+export declare const selectListTheme: SelectListTheme;
+export declare const editorTheme: EditorTheme;
+export declare const imageTheme: ImageTheme;

package/dist/theme.js

@@ -0,0 +1,52 @@
+export const fg = (r, g, b) => (s) => `\x1b[38;2;${r};${g};${b}m${s}\x1b[39m`;
+export const bg = (r, g, b) => (s) => `\x1b[48;2;${r};${g};${b}m${s}\x1b[49m`;
+export const bold = (s) => `\x1b[1m${s}\x1b[22m`;
+export const dim = (s) => `\x1b[2m${s}\x1b[22m`;
+export const italic = (s) => `\x1b[3m${s}\x1b[23m`;
+export const underline = (s) => `\x1b[4m${s}\x1b[24m`;
+export const strike = (s) => `\x1b[9m${s}\x1b[29m`;
+/** 全局配色：slate/sky/teal 冷色调，深浅终端下都有足够对比度。 */
+export const color = {
+    accent: fg(56, 189, 248),
+    accent2: fg(45, 212, 191),
+    user: fg(226, 232, 240),
+    text: fg(203, 213, 225),
+    muted: fg(100, 116, 139),
+    dim: fg(71, 85, 105),
+    border: fg(51, 65, 85),
+    ok: fg(74, 222, 128),
+    warn: fg(251, 191, 36),
+    err: fg(248, 113, 113),
+    chip: bg(30, 41, 59),
+    userBg: bg(15, 23, 42),
+};
+export const markdownTheme = {
+    heading: (t) => bold(color.accent2(t)),
+    link: (t) => color.accent(t),
+    linkUrl: (t) => dim(color.muted(t)),
+    code: (t) => color.warn(t),
+    codeBlock: (t) => color.text(t),
+    codeBlockBorder: (t) => color.border(t),
+    quote: (t) => dim(color.muted(t)),
+    quoteBorder: (t) => color.accent2(t),
+    hr: (t) => color.border(t),
+    listBullet: (t) => color.accent(t),
+    bold: (t) => bold(color.user(t)),
+    italic: (t) => italic(color.text(t)),
+    strikethrough: (t) => strike(color.text(t)),
+    underline: (t) => underline(color.text(t)),
+};
+export const selectListTheme = {
+    selectedPrefix: (t) => color.accent(bold(t)),
+    selectedText: (t) => bold(color.user(t)),
+    description: (t) => color.muted(t),
+    scrollInfo: (t) => dim(color.muted(t)),
+    noMatch: (t) => dim(color.muted(t)),
+};
+export const editorTheme = {
+    borderColor: (t) => color.border(t),
+    selectList: selectListTheme,
+};
+export const imageTheme = {
+    fallbackColor: (t) => color.muted(t),
+};

package/dist/ui.d.ts

@@ -0,0 +1,88 @@
+import { type Component } from "@earendil-works/pi-tui";
+import { dim, selectListTheme } from "./theme.js";
+/** 把文本按可见宽度换行；保证每行都不超过 width。 */
+export declare function wrap(text: string, width: number): string[];
+/** 通用多行文本组件，按渲染宽度截断，保证永不超宽。 */
+export declare class Lines implements Component {
+    private lines;
+    constructor(lines?: string[]);
+    setLines(lines: string[]): void;
+    invalidate(): void;
+    render(width: number): string[];
+}
+/** 启动屏：logo + 环境信息。 */
+export declare class Splash implements Component {
+    private info;
+    constructor(info: {
+        base: string;
+        model: string;
+        dataPath: string;
+        sources: number;
+    });
+    invalidate(): void;
+    render(width: number): string[];
+}
+/** 顶部状态条：带圆角边框的一行摘要。 */ export declare class StatusBar implements Component {
+    private info;
+    constructor(info: {
+        base: string;
+        model: string;
+        sources: number;
+        turns: number;
+    });
+    setInfo(info: {
+        base: string;
+        model: string;
+        sources: number;
+        turns: number;
+    }): void;
+    invalidate(): void;
+    render(width: number): string[];
+}
+/** 用户提问。 */
+export declare class UserMessage implements Component {
+    private text;
+    constructor(text: string);
+    invalidate(): void;
+    render(width: number): string[];
+}
+/** 助手回答：图标 + Markdown 正文 + 元信息脚注。 */
+export declare class AssistantMessage implements Component {
+    private meta;
+    private md;
+    constructor(text: string, meta?: string);
+    setMeta(meta: string): void;
+    invalidate(): void;
+    render(width: number): string[];
+}
+/** 单行提示（成功 / 信息 / 警告 / 错误）。 */
+export declare class Notice implements Component {
+    private icon;
+    private style;
+    private text;
+    constructor(icon: string, style: (s: string) => string, text: string);
+    invalidate(): void;
+    render(width: number): string[];
+}
+/** 检索命中的附图标记。 */
+export declare class ImageNotice implements Component {
+    private name;
+    private version;
+    constructor(name: string, version: number);
+    invalidate(): void;
+    render(width: number): string[];
+}
+/** 水平分隔线。 */
+export declare class Rule implements Component {
+    invalidate(): void;
+    render(width: number): string[];
+}
+/** 帮助面板（作为 overlay 内容）。 */
+export declare class HelpPanel implements Component {
+    private items;
+    constructor(items: Array<[string, string]>);
+    invalidate(): void;
+    render(width: number): string[];
+}
+/** 供 SelectList 复用的主题。 */
+export { selectListTheme, dim };

package/dist/ui.js

@@ -0,0 +1,171 @@
+import { Markdown, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { bold, color, dim, markdownTheme, selectListTheme } from "./theme.js";
+/** 把文本按可见宽度换行；保证每行都不超过 width。 */
+export function wrap(text, width) {
+    if (width <= 0)
+        return [""];
+    const out = [];
+    for (const raw of text.split("\n")) {
+        if (raw === "") {
+            out.push("");
+            continue;
+        }
+        for (const piece of wrapTextWithAnsi(raw, width))
+            out.push(piece);
+    }
+    return out;
+}
+const pad = (s, w) => s + " ".repeat(Math.max(0, w - visibleWidth(s)));
+/** 统一裁剪：保证组件输出永不超过给定宽度（pi-tui 会因超宽报错）。 */
+const clip = (lines, width) => lines.map((l) => truncateToWidth(l, Math.max(0, width)));
+/** 通用多行文本组件，按渲染宽度截断，保证永不超宽。 */
+export class Lines {
+    lines = [];
+    constructor(lines = []) { this.lines = lines; }
+    setLines(lines) { this.lines = lines; }
+    invalidate() { }
+    render(width) {
+        return this.lines.map((l) => truncateToWidth(l, Math.max(0, width)));
+    }
+}
+/** 启动屏：logo + 环境信息。 */
+export class Splash {
+    info;
+    constructor(info) {
+        this.info = info;
+    }
+    invalidate() { }
+    render(width) {
+        const logo = ["██╗  ██╗ ██████╗", "██║ ██╔╝ ██╔══██╗", "█████╔╝  ██████╔╝", "██╔═██╗  ██╔══██╗", "██║  ██╗ ██████╔╝", "╚═╝  ╚═╝ ╚═════╝ "];
+        const field = (k, v, val) => `   ${color.muted(pad(k, 8))}${val(v)}`;
+        const lines = [
+            "",
+            ...logo.map((l) => "   " + color.accent(bold(l))),
+            "",
+            "   " + color.text(bold("知识库")) + color.border(" · ") + color.muted("Knowledge Base"),
+            "",
+            field("知识库", this.info.base, color.user),
+            field("模型", this.info.model, color.user),
+            field("来源", String(this.info.sources), color.user),
+            field("数据", this.info.dataPath, (s) => color.dim(s)),
+            "",
+            "   " + color.dim("输入问题开始，或键入 ") + color.accent("/help") + color.dim(" 查看命令"),
+            "",
+        ];
+        return lines.map((l) => truncateToWidth(l, Math.max(0, width)));
+    }
+}
+/** 顶部状态条：带圆角边框的一行摘要。 */ export class StatusBar {
+    info;
+    constructor(info) {
+        this.info = info;
+    }
+    setInfo(info) { this.info = info; }
+    invalidate() { }
+    render(width) {
+        const w = Math.max(0, width);
+        const inner = Math.max(0, w - 4);
+        const label = " KB ";
+        const top = color.border("╭─") + color.accent(bold(label)) + color.border("─".repeat(Math.max(0, w - 3 - visibleWidth(label))) + "╮");
+        const bot = color.border("╰" + "─".repeat(Math.max(0, w - 2)) + "╯");
+        const stat = (k, v) => `${color.muted(k)} ${color.user(v)}`;
+        const content = "  " + [
+            stat("知识库", this.info.base),
+            stat("模型", this.info.model),
+            stat("来源", String(this.info.sources)),
+            stat("会话", String(this.info.turns)),
+        ].join(color.border("  ·  "));
+        const row = color.border("│") + " " + pad(truncateToWidth(content, inner), inner) + " " + color.border("│");
+        return clip([top, row, bot], w);
+    }
+}
+/** 用户提问。 */
+export class UserMessage {
+    text;
+    constructor(text) {
+        this.text = text;
+    }
+    invalidate() { }
+    render(width) {
+        const prefix = `  ${color.accent2(bold("❯"))} `;
+        const body = wrap(this.text, Math.max(1, width - 4));
+        return body.map((l, i) => (i === 0 ? prefix + color.user(l) : "    " + color.user(l)));
+    }
+}
+/** 助手回答：图标 + Markdown 正文 + 元信息脚注。 */
+export class AssistantMessage {
+    meta;
+    md;
+    constructor(text, meta = "") {
+        this.meta = meta;
+        this.md = new Markdown(text, 0, 0, markdownTheme);
+    }
+    setMeta(meta) { this.meta = meta; }
+    invalidate() { this.md.invalidate(); }
+    render(width) {
+        const indent = "    ";
+        const bodyWidth = Math.max(10, width - indent.length);
+        const lines = [`  ${color.ok(bold("⏺"))}`, ""];
+        for (const l of this.md.render(bodyWidth))
+            lines.push(indent + l.replace(/\s+$/, ""));
+        if (this.meta)
+            lines.push("", `${indent}${color.dim("·")} ${color.muted(this.meta)}`);
+        return lines.map((l) => truncateToWidth(l, Math.max(0, width)));
+    }
+}
+/** 单行提示（成功 / 信息 / 警告 / 错误）。 */
+export class Notice {
+    icon;
+    style;
+    text;
+    constructor(icon, style, text) {
+        this.icon = icon;
+        this.style = style;
+        this.text = text;
+    }
+    invalidate() { }
+    render(width) {
+        const prefix = `  ${this.style(this.icon)} `;
+        return wrap(this.text, Math.max(1, width - 4)).map((l, i) => (i === 0 ? prefix + color.text(l) : "    " + color.text(l)));
+    }
+}
+/** 检索命中的附图标记。 */
+export class ImageNotice {
+    name;
+    version;
+    constructor(name, version) {
+        this.name = name;
+        this.version = version;
+    }
+    invalidate() { }
+    render(width) {
+        const line = `  ${color.accent2("★")} ${color.muted("附图")} ${color.chip(color.text(` ${this.name} `))} ${color.dim("v" + this.version)}`;
+        return [truncateToWidth(line, Math.max(0, width))];
+    }
+}
+/** 水平分隔线。 */
+export class Rule {
+    invalidate() { }
+    render(width) {
+        return [color.dim("─".repeat(Math.max(0, width)))];
+    }
+}
+/** 帮助面板（作为 overlay 内容）。 */
+export class HelpPanel {
+    items;
+    constructor(items) { this.items = items; }
+    invalidate() { }
+    render(width) {
+        const w = Math.min(Math.max(0, width), 72);
+        const inner = Math.max(0, w - 4);
+        const title = " 命令 ";
+        const keyWidth = Math.max(10, ...this.items.map(([k]) => visibleWidth(k))) + 2;
+        const top = color.border("╭─") + color.accent(bold(title)) + color.border("─".repeat(Math.max(0, w - 3 - visibleWidth(title))) + "╮");
+        const bot = color.border("╰" + "─".repeat(Math.max(0, w - 2)) + "╯");
+        const row = (c) => color.border("│") + " " + pad(truncateToWidth(c, inner), inner) + " " + color.border("│");
+        const body = this.items.map(([k, d]) => row(k ? "  " + color.accent(k) + " ".repeat(Math.max(1, keyWidth - visibleWidth(k))) + color.muted(d) : ""));
+        return clip([top, row(""), ...body, row(""), bot], w);
+    }
+}
+/** 供 SelectList 复用的主题。 */
+export { selectListTheme, dim };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ganziliang/kb",
-  "version": "0.1.7",
-  "description": "Local knowledge base agent CLI",
+  "version": "0.2.0",
+  "description": "Local knowledge base agent CLI with a pi-tui interface",
   "type": "module",
   "bin": {
     "kb": "dist/entry.js"
@@ -17,17 +17,15 @@
     "test": "npm run build && node --test"
   },
   "engines": {
-    "node": ">=22.5.0"
+    "node": ">=22.19.0"
   },
   "dependencies": {
+    "@earendil-works/pi-tui": "^0.85.1",
     "@ganziliang/kb-model-setup": "^0.1.2",
-    "ink": "^5.1.0",
-    "react": "^18.3.1",
     "xlsx": "^0.18.5"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
-    "@types/react": "^18.3.12",
     "typescript": "^5.7.2"
   }
 }