@ganziliang/kb 0.1.6 → 0.2.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,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` 重做。
 
 ### 导入文件
 
@@ -116,6 +161,7 @@ kb
 - JSON：`.json`
 - CSV：`.csv`
 - Excel：`.xlsx`、`.xls`
+- 图片：`.png`、`.jpg`、`.jpeg`、`.gif`、`.webp`、`.bmp`（需要模型支持视觉）
 
 导入命令格式：
 
@@ -138,10 +184,32 @@ import <文件路径>
 导入 ./docs/payment.md
 import D:\docs\api.txt
 导入 "D:\资料\产品说明.xlsx"
+导入 "D:\截图\支付报错.png"
 ```
 
 导入后会复制一份原始文件，并建立版本记录。对同一个文件再次导入时，会创建新版本，不会直接覆盖旧版本。
 
+### 图片知识
+
+图片本身无法参与关键词检索，因此 `kb` 对图片使用双通道处理：
+
+1. **入库时生成描述**：导入图片时会调用当前模型看图，生成一段中文描述（含图中所有文字、数字、表格与界面细节），写入知识库参与全文检索。
+2. **提问时附原图**：当问题检索命中图片记录时，`kb` 会把原始图片一并发送给模型，因此模型看到的是真实图像，而不只是描述。
+
+也就是说，导入一次图片后，既可以按内容关键词搜到它，也可以直接针对图片细节提问：
+
+```text
+导入 "D:\截图\支付报错.png"
+
+支付报错的截图里，订单号和错误码分别是什么？
+```
+
+注意：
+
+- 图片描述依赖当前模型具备视觉能力；模型不支持视觉时，图片仍会入库，但只能按文件名检索，并在导入结果中提示失败原因。
+- 单次提问最多附带 4 张命中图片。
+- 历史对话中不会重复携带图片数据，每轮提问都会按检索结果重新附图。
+
 ### 查询知识
 
 直接输入问题即可：
@@ -234,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,180 +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, fetchTransport } from "./model.js";
-import { copyOriginal, defaultDataRoot, ensureKnowledgeBase, KnowledgeStore, readLocalFile, listKnowledgeBases, deleteKnowledgeBase, backupKnowledgeBase, restoreKnowledgeBase } from "./storage.js";
-const banner = [
-    "  _  __ ____  ",
-    " | |/ // __ ) ",
-    " |   // __  | ",
-    " |   |/ /_/ / ",
-    " |_|\\_\\____/ ",
-    " Welcome to KB Knowledge Base",
+import { Agent, describeImage, fetchTransport } from "./model.js";
+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"]);
+        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"]);
+            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 查看可用命令。`));
+        }
+    }
+    showSources() {
+        const sources = this.store.sources();
+        if (!sources.length) {
+            this.add(new Notice(ROLE.warn, color.warn, "知识库还是空的，用「导入 <文件路径>」录入内容。"));
             return;
         }
-        if (value === "/backup" || value.startsWith("/backup ")) {
-            setLines((old) => [...old, `Backup created at ${backupKnowledgeBase(currentBase, value.slice(7).trim() || undefined)}`]);
+        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.startsWith("/restore ")) {
-            restoreKnowledgeBase(currentBase, value.slice(9).trim());
-            setLines((old) => [...old, "Knowledge base restored. Restart the session to reopen the database."]);
+        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 === "/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."]);
+        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 ? "   ← 当前" : ""}`));
+            }
+            return;
+        }
+        if (sub === "current") {
+            this.add(new Notice(ROLE.ok, color.ok, `${this.base.name}（${this.base.id}）`));
             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}.`]);
+        if (sub === "create") {
+            if (!args.length) {
+                this.add(new Notice(ROLE.warn, color.warn, "用法：/kb create <名称>"));
+                return;
             }
-            else
-                setLines((old) => [...old, "Usage: /cleanup <version-id> confirm"]);
+            const created = ensureKnowledgeBase(this.root, args.join(" "));
+            this.add(new Notice(ROLE.ok, color.ok, `已创建 ${created.name}（${created.id}）`));
             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 === "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;
         }
-        catch (error) {
-            setLines((old) => [...old, `Error: ${error instanceof Error ? error.message : String(error)}`]);
+        if (sub === "delete") {
+            if (!args[0] || args[1] !== "confirm") {
+                this.add(new Notice(ROLE.warn, color.warn, "用法：/kb delete <id> confirm"));
+                return;
+            }
+            try {
+                deleteKnowledgeBase(this.root, args[0]);
+                this.add(new Notice(ROLE.ok, color.ok, `已删除 ${args[0]}，备份已保留。`));
+            }
+            catch (error) {
+                this.add(new Notice(ROLE.err, color.err, errText(error)));
+            }
+            return;
         }
-        finally {
-            setBusy(false);
+        this.add(new Notice(ROLE.warn, color.warn, "用法：/kb list | /kb create <名称> | /kb use <id> | /kb current | /kb delete <id> confirm"));
+    }
+    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;
         }
+        this.store.removeVersions([id]);
+        this.add(new Notice(ROLE.ok, color.ok, `已删除历史版本 ${id}。`));
     }
-    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 };
-        const copied = copyOriginal(source.originalPath, store.root);
-        const result = store.addOrUpdateSource(copied, source.title, source.content);
-        return { text: `${result.isNew ? "Imported" : "New version created for"} ${result.title} (v${result.version})`, messages: previous };
-    }
-    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 agent = new Agent(store, modelConfig, fetchTransport);
-    return agent.answer(`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}`, 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/model.d.ts

@@ -4,15 +4,26 @@ export type ToolCall = {
     name: "search" | "read" | "write";
     arguments: Record<string, unknown>;
 };
+export type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    mediaType: string;
+    base64: string;
+};
 export type ModelMessage = {
     role: "system" | "user" | "assistant" | "tool";
-    content: string;
+    content: string | ContentBlock[];
     toolCallId?: string;
 };
 export type ModelReply = {
     text?: string;
     toolCalls?: ToolCall[];
 };
+export declare function toAnthropicContent(content: string | ContentBlock[]): unknown;
+export declare function toOpenAIContent(content: string | ContentBlock[]): unknown;
+export declare function contentToText(content: string | ContentBlock[]): string;
 export type ModelTransport = {
     complete(config: ModelConfig, messages: ModelMessage[]): Promise<ModelReply>;
 };
@@ -22,10 +33,18 @@ export declare class Agent {
     private readonly config;
     private readonly transport;
     constructor(store: KnowledgeStore, config: ModelConfig, transport?: ModelTransport);
-    answer(question: string, previous?: ModelMessage[]): Promise<{
+    answer(question: string | ContentBlock[], previous?: ModelMessage[]): Promise<{
         text: string;
         messages: ModelMessage[];
     }>;
     private execute;
 }
 export declare function formatResults(results: SearchResult[]): string;
+type VisionTransport = {
+    complete: (config: ModelConfig, messages: ModelMessage[]) => Promise<ModelReply>;
+};
+export declare function describeImage(config: ModelConfig, transport: VisionTransport, image: {
+    mediaType: string;
+    base64: string;
+}): Promise<string>;
+export {};

package/dist/model.js

@@ -1,3 +1,24 @@
+export function toAnthropicContent(content) {
+    if (typeof content === "string")
+        return content;
+    return content.map((block) => block.type === "text"
+        ? { type: "text", text: block.text }
+        : { type: "image", source: { type: "base64", media_type: block.mediaType, data: block.base64 } });
+}
+export function toOpenAIContent(content) {
+    if (typeof content === "string")
+        return content;
+    return content.map((block) => block.type === "text"
+        ? { type: "input_text", text: block.text }
+        : { type: "input_image", image_url: `data:${block.mediaType};base64,${block.base64}` });
+}
+export function contentToText(content) {
+    return typeof content === "string" ? content : content.map((block) => block.type === "text" ? block.text : `[image:${block.mediaType}]`).join("\n");
+}
+// 历史消息里的图片 base64 不重复携带：每轮都会重新检索并附图，避免上下文膨胀。
+function compactHistory(messages) {
+    return messages.map((message) => typeof message.content === "string" ? message : { ...message, content: contentToText(message.content) });
+}
 function endpoint(config) {
     return `${config.baseURL.replace(/\/$/, "")}${config.api === "anthropic-messages" ? "/v1/messages" : "/v1/responses"}`;
 }
@@ -14,8 +35,8 @@ export const fetchTransport = {
             method: "POST",
             headers,
             body: JSON.stringify(config.api === "anthropic-messages"
-                ? { model: config.model, max_tokens: 4096, messages: messages.filter((m) => m.role !== "system"), system: messages.find((m) => m.role === "system")?.content }
-                : { model: config.model, input: messages.map((m) => ({ role: m.role, content: m.content })) }),
+                ? { model: config.model, max_tokens: 4096, messages: messages.filter((m) => m.role !== "system").map((m) => ({ role: m.role, content: toAnthropicContent(m.content) })), system: messages.find((m) => m.role === "system")?.content }
+                : { model: config.model, input: messages.map((m) => ({ role: m.role, content: toOpenAIContent(m.content) })) }),
         });
         if (!response.ok)
             throw new Error(`Model request failed (${response.status}): ${await response.text()}`);
@@ -38,13 +59,13 @@ export class Agent {
         const messages = [...previous, { role: "user", content: question }];
         const first = await this.transport.complete(this.config, messages);
         if (!first.toolCalls?.length)
-            return { text: first.text ?? "", messages: [...messages, { role: "assistant", content: first.text ?? "" }] };
+            return { text: first.text ?? "", messages: [...compactHistory(messages), { role: "assistant", content: first.text ?? "" }] };
         for (const call of first.toolCalls) {
             const result = this.execute(call);
             messages.push({ role: "tool", content: JSON.stringify(result), toolCallId: call.name });
         }
         const final = await this.transport.complete(this.config, messages);
-        return { text: final.text ?? "", messages: [...messages, { role: "assistant", content: final.text ?? "" }] };
+        return { text: final.text ?? "", messages: [...compactHistory(messages), { role: "assistant", content: final.text ?? "" }] };
     }
     execute(call) {
         if (call.name === "search")
@@ -57,3 +78,11 @@ export class Agent {
 export function formatResults(results) {
     return results.map((result) => `[${result.id}] ${result.title} (source: ${result.source}, v${result.version})\n${result.content}`).join("\n\n");
 }
+const IMAGE_QUESTION = "\u8bf7\u7528\u4e2d\u6587\u8be6\u7ec6\u63cf\u8ff0\u8fd9\u5f20\u56fe\u7247\u7684\u5185\u5bb9\uff0c\u5199\u6e05\u6240\u6709\u53ef\u89c1\u7684\u6587\u5b57\u3001\u6570\u5b57\u3001\u8868\u683c\u3001\u754c\u9762\u5143\u7d20\u548c\u5173\u952e\u7ec6\u8282\uff0c\u4ee5\u53ca\u56fe\u7247\u6574\u4f53\u5728\u8bb2\u4ec0\u4e48\u3002\u53ea\u8f93\u51fa\u63cf\u8ff0\u6b63\u6587\uff0c\u4e0d\u8981\u5ba2\u5957\u8bdd\u3002";
+export async function describeImage(config, transport, image) {
+    const reply = await transport.complete(config, [{
+            role: "user",
+            content: [{ type: "text", text: IMAGE_QUESTION }, { type: "image", mediaType: image.mediaType, base64: image.base64 }],
+        }]);
+    return (reply.text ?? "").trim();
+}

package/dist/storage.d.ts

@@ -11,7 +11,22 @@ export type SearchResult = {
     source: string;
     version: number;
     updatedAt: string;
+    originalPath?: string;
 };
+export declare const IMAGE_MEDIA_TYPES: Record<string, string>;
+export type ImageData = {
+    mediaType: string;
+    base64: string;
+};
+export type LocalFile = {
+    title: string;
+    content: string;
+    originalPath: string;
+    hash: string;
+    image?: ImageData;
+};
+export declare function isImageFile(filePath: string): boolean;
+export declare function readImage(filePath: string): ImageData;
 export declare function tokenize(text: string): string;
 export declare class KnowledgeStore {
     readonly root: string;
@@ -37,12 +52,7 @@ type KnowledgeStoreResult = {
     title: string;
     isNew: boolean;
 };
-export declare function readLocalFile(filePath: string): {
-    title: string;
-    content: string;
-    originalPath: string;
-    hash: string;
-};
+export declare function readLocalFile(filePath: string): LocalFile;
 export declare function copyOriginal(filePath: string, root: string): string;
 export declare function defaultDataRoot(): string;
 export declare function knowledgeBasePath(root: string, id: string): string;

package/dist/storage.js

@@ -3,6 +3,24 @@ import { createHash } from "node:crypto";
 import { join, resolve, extname, basename } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import * as XLSX from "xlsx";
+export const IMAGE_MEDIA_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+};
+export function isImageFile(filePath) {
+    return extname(filePath).toLowerCase() in IMAGE_MEDIA_TYPES;
+}
+export function readImage(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    const mediaType = IMAGE_MEDIA_TYPES[ext];
+    if (!mediaType)
+        throw new Error(`Unsupported image format: ${ext || "unknown"}`);
+    return { mediaType, base64: readFileSync(filePath).toString("base64") };
+}
 export function tokenize(text) {
     const segmenter = new Intl.Segmenter("zh", { granularity: "word" });
     const words = [...segmenter.segment(text)]
@@ -48,10 +66,10 @@ export class KnowledgeStore {
         const match = tokenize(query).split(/\s+/).filter(Boolean).map((part) => `"${part.replaceAll('"', '""')}"`).join(" OR ");
         if (!match)
             return [];
-        return this.db.prepare(`SELECT k.id, k.title, k.content, s.name AS source, k.version, k.updated_at AS updatedAt FROM knowledge_fts f JOIN knowledge k ON k.id = f.knowledge_id JOIN sources s ON s.id = k.source_id WHERE f.knowledge_fts MATCH ? AND k.current = 1 ORDER BY rank LIMIT ?`).all(match, limit);
+        return this.db.prepare(`SELECT k.id, k.title, k.content, s.name AS source, k.version, k.updated_at AS updatedAt, s.original_path AS originalPath FROM knowledge_fts f JOIN knowledge k ON k.id = f.knowledge_id JOIN sources s ON s.id = k.source_id WHERE f.knowledge_fts MATCH ? AND k.current = 1 ORDER BY rank LIMIT ?`).all(match, limit);
     }
     read(id) {
-        return this.db.prepare("SELECT k.id,k.title,k.content,s.name AS source,k.version,k.updated_at AS updatedAt FROM knowledge k JOIN sources s ON s.id=k.source_id WHERE k.id=?").get(id);
+        return this.db.prepare("SELECT k.id,k.title,k.content,s.name AS source,k.version,k.updated_at AS updatedAt,s.original_path AS originalPath FROM knowledge k JOIN sources s ON s.id=k.source_id WHERE k.id=?").get(id);
     }
     sources() { return this.db.prepare("SELECT s.name,s.original_path AS path,MAX(k.updated_at) AS updatedAt,MAX(k.version) AS version FROM sources s JOIN knowledge k ON k.source_id=s.id AND k.current=1 GROUP BY s.id ORDER BY updatedAt DESC").all(); }
     oldVersions() { return this.db.prepare("SELECT k.id,k.title,k.version,s.name AS source FROM knowledge k JOIN sources s ON s.id=k.source_id WHERE k.current=0 ORDER BY s.name,k.version").all(); }
@@ -66,6 +84,17 @@ export function readLocalFile(filePath) {
     const originalPath = resolve(filePath);
     const ext = extname(originalPath).toLowerCase();
     let content;
+    if (IMAGE_MEDIA_TYPES[ext]) {
+        const image = readImage(originalPath);
+        const size = statSync(originalPath).size;
+        return {
+            title: basename(originalPath),
+            content: `[\u56fe\u7247] ${basename(originalPath)} (${image.mediaType}, ${size} bytes)`,
+            originalPath,
+            hash: createHash("sha256").update(image.base64).digest("hex"),
+            image,
+        };
+    }
     if ([".md", ".txt", ".json", ".csv"].includes(ext))
         content = readFileSync(originalPath, "utf8");
     else if (ext === ".xlsx" || ext === ".xls") {

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.6",
-  "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"
   }
 }