@ganziliang/kb 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @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 回答排版、带边框的编辑器、加载动画与命令浮层。
 
@@ -144,13 +144,16 @@ kb
 | 按键 | 作用 |
 | --- | --- |
 | `Enter` | 发送 |
+| `Shift+Enter` / `Ctrl+J` | 输入换行（录入多行内容用） |
 | `Esc` | 关闭浮层 |
 | `Ctrl+C` | 退出 |
 | `Ctrl+A` / `Ctrl+E` | 行首 / 行尾 |
 | `Ctrl+U` / `Ctrl+K` | 删除到行首 / 行尾 |
 | `Ctrl+W` | 删除前一个单词 |
+| `Ctrl+-` | 撤销 |
+| `Ctrl+Y` | 粘贴（yank 最近删除的内容） |
 
-输入框支持多行编辑与撤销：`Ctrl+Z` 撤销，`Ctrl+Y` 重做。
+光标可以用方向键或 `Ctrl+B` / `Ctrl+F` 左右移动；按单词移动用 `Alt+←` / `Alt+→`。
 
 ### 导入文件
 
@@ -189,6 +192,55 @@ import D:\docs\api.txt
 
 导入后会复制一份原始文件，并建立版本记录。对同一个文件再次导入时，会创建新版本，不会直接覆盖旧版本。
 
+### 直接录入文本
+
+不需要先把内容存成文件，也不需要记命令——用自然语言告诉 kb 就行：
+
+```text
+记住：我的工位在 A 区 12 号，门禁卡号 8823
+记一下，下周三下午两点和产品对需求
+帮我存个配置：接口超时时间 30 秒，失败重试 3 次
+这段你帮我记着：报销单必须贴发票原件
+```
+
+kb 每一轮输入都会先判断你的意图：
+
+- **提问** → 检索知识库并回答（附来源与版本）
+- **录入** → 调用 `save_knowledge` 工具存入知识库
+
+判断由模型根据语义完成，**不依赖固定关键词**。识别为录入后，模型会：
+
+1. **生成标题**：用一句话概括内容，作为知识条目标题。
+2. **整理内容**：转成规范 Markdown，完整保留你给的信息。
+3. **落盘建索引**：写入 `<知识库>/originals/`，并入关键词检索，随后提问就能命中。
+
+多行内容按 **Shift+Enter**（或 `Ctrl+J`）换行，全部输入完再按 `Enter` 提交：
+
+```text
+帮我记下值班规范：
+
+- 线上告警先看 Grafana 面板 pay-dashboard
+- P0 故障 15 分钟内必须响应
+- 值班电话 8001，仅限 P0 使用
+```
+
+录入的内容同样遵循版本规则：内容完全相同时再次录入，会生成新版本而不是重复来源。
+
+#### 显式命令（兜底）
+
+模型判断有误、或模型暂时不可用时，可以用 `/add` 强制录入；
+以 `/` 开头的形式不会与自然语言混淆：
+
+```text
+/add 支付网关的退款接口是 /api/pay/refund，请求方式 POST
+/note 团队周会是每周三下午三点
+```
+
+显式命令不调用模型，标题由程序从内容推导（优先取 Markdown 标题，否则取首个非空行）。
+
+> 区别：`导入 <路径>` 是把**已有的文件**收录进来，`/add <内容>` 是把**输入框里的文字**收录进来，
+> 而直接说「记住 …」则由模型自己判断。
+
 ### 图片知识
 
 图片本身无法参与关键词检索，因此 `kb` 对图片使用双通道处理：
@@ -229,6 +281,7 @@ import D:\docs\api.txt
 | `/help` | 查看命令列表 |
 | `/clear` | 清空当前对话上下文 |
 | `/sources` | 查看当前知识库中的来源文件、路径和版本 |
+| `/add <内容>` | 显式录入文本（正常直接说「记住…」即可） |
 | `/models` 或 `/model` | 查看已配置模型 |
 | `/model <编号>` | 切换模型，例如 `/model 1` |
 | `/kb list` | 查看所有知识库 |

package/dist/cli.d.ts

@@ -27,6 +27,7 @@ export declare class KbApp {
     private shutdown;
     private submit;
     private run;
+    private addNote;
     private ingest;
     private ask;
     private command;

package/dist/cli.js

@@ -2,15 +2,58 @@
 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 { backupKnowledgeBase, copyOriginal, defaultDataRoot, deleteKnowledgeBase, ensureKnowledgeBase, isImageFile, KnowledgeStore, listKnowledgeBases, readImage, readLocalFile, restoreKnowledgeBase, } from "./storage.js";
+import { SAVE_KNOWLEDGE_TOOL, describeImage, fetchTransport } from "./model.js";
+import { backupKnowledgeBase, copyOriginal, defaultDataRoot, deleteKnowledgeBase, ensureKnowledgeBase, isImageFile, KnowledgeStore, listKnowledgeBases, readImage, readLocalFile, restoreKnowledgeBase, writeNote, } 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));
+/**
+ * 显式录入命令，仅作为模型不可用时的兜底。
+ * 正常情况交给模型按语义判断（见 buildSystemPrompt），
+ * 因此这里只保留 / 开头的命令，不硬匹配「记住」这类自然语言词。
+ */
+const NOTE_PATTERN = /^\/(?:add|note)(?:\s+([\s\S]*))?$/;
+/** 从录入内容里推导一个标题：优先取 Markdown 标题，否则取首个非空行。 */
+function deriveTitle(content) {
+    const firstLine = content.split("\n").map((l) => l.trim()).find(Boolean) ?? "笔记";
+    const heading = firstLine.match(/^#{1,6}\s+(.+)$/);
+    const base = (heading ? heading[1] : firstLine).replace(/[#*`>_]/g, "").trim();
+    return base.slice(0, 40) || "���记";
+}
+/** 多行内容回显时只显示首行，避免刷屏。 */
+function shortPreview(text) {
+    const lines = text.split("\n");
+    return lines.length > 1 ? `${lines[0]} …（共 ${lines.length} 行）` : text;
+}
+/**
+ * 把「回答」和「录入」放进同一轮对话：模型自己决定是回答还是调用工具，
+ * 因此判断意图不会带来额外的一次模型调用。
+ */
+function buildSystemPrompt(context) {
+    return [
+        "你是本地知识库助手。每一轮输入，先判断用户意图：",
+        "",
+        "A) 提问 —— 用户想从知识库获取信息。",
+        "   用「知识库内容」回答，并标注来源文件名与版本。",
+        "   内容不足以回答时明确说明没有找到，不要编造。",
+        "",
+        "B) 录入 —— 用户想把一段内容长期存进知识库。",
+        "   调用 save_knowledge 工具，title 用一句话概括，content 用规范 Markdown 并完整保留用户信息。",
+        "   此时不要回答内容本身，也不要反问确认。",
+        "",
+        "判断依据是用户表达的意图，不要依赖固定关键词。",
+        "",
+        "知识库内容：",
+        "---",
+        context,
+        "---",
+    ].join("\n");
+}
 const HELP_ITEMS = [
     ["/help", "显示本帮助"],
     ["/clear", "清空对话上下文"],
     ["/sources", "列出知识来源与版本"],
+    ["/add <内容>", "显式录入（通常直接说「记住…」即可）"],
     ["/model", "查看 / 切换模型"],
     ["/kb", "多知识库管理"],
     ["/backup", "备份当前知识库"],
@@ -127,6 +170,17 @@ export class KbApp {
             return;
         this.editor.setText("");
         this.tui.requestRender();
+        const note = value.match(NOTE_PATTERN);
+        if (note) {
+            const content = (note[1] ?? "").trim();
+            if (!content) {
+                this.add(new Notice(ROLE.warn, color.warn, "用法：/add <内容>；也可以直接说「记住 ……」，模型会自动识别为录入。"));
+                return;
+            }
+            this.add(new UserMessage(shortPreview(`/add ${content}`)));
+            await this.addNote(content);
+            return;
+        }
         if (value.startsWith("/")) {
             await this.command(value);
             return;
@@ -143,6 +197,23 @@ export class KbApp {
         }
         await this.ask(value);
     }
+    // ---------- 直接录入文本 ----------
+    async addNote(content, explicitTitle = "") {
+        const body = content.trim();
+        if (!body) {
+            this.add(new Notice(ROLE.warn, color.warn, "没有可录入的内容。"));
+            return;
+        }
+        try {
+            const title = explicitTitle.trim() || deriveTitle(body);
+            const file = writeNote(this.store.root, title, body);
+            const result = this.store.addOrUpdateSource(file, title, body);
+            this.add(new Notice(ROLE.ok, color.ok, `已录入「${result.title}」（v${result.version}，${body.length} 字符）`));
+        }
+        catch (error) {
+            this.add(new Notice(ROLE.err, color.err, `录入失败：${errText(error)}`));
+        }
+    }
     // ---------- 导入 ----------
     async ingest(path) {
         try {
@@ -191,30 +262,39 @@ export class KbApp {
             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 = [];
+            const questionBlocks = [{ type: "text", text: question }];
             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 });
+                    questionBlocks.push({ type: "text", text: `[附图] ${item.source} v${item.version}` });
+                    questionBlocks.push({ type: "image", mediaType: image.mediaType, base64: image.base64 });
                     attached.push({ name: item.source, version: item.version });
                 }
                 catch { /* 跳过无法读取的图片 */ }
             }
-            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.setBusy(true, attached.length ? `命中 ${results.length} 条，附图 ${attached.length} 张，正在处理…` : `检索到 ${results.length} 条，正在理解意图…`);
+            const reply = await fetchTransport.complete(config, [
+                { role: "system", content: buildSystemPrompt(context) },
+                ...this.messages,
+                { role: "user", content: questionBlocks.length > 1 ? questionBlocks : question },
+            ], [SAVE_KNOWLEDGE_TOOL]);
+            const save = reply.toolCalls?.find((call) => call.name === SAVE_KNOWLEDGE_TOOL.name);
+            if (save) {
+                this.setBusy(true, "正在录入知识库…");
+                await this.addNote(String(save.arguments.content ?? ""), String(save.arguments.title ?? ""));
+                return;
+            }
+            const answer = (reply.text ?? "").trim();
+            this.messages = [...this.messages, { role: "user", content: question }, { role: "assistant", content: answer }];
             this.store.saveMessage("user", question);
-            this.store.saveMessage("assistant", answer.text);
+            this.store.saveMessage("assistant", answer);
             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));
+            const meta = `检索 ${results.length} 条 · 用时 ${seconds}s` + (attached.length ? ` · 附图 ${attached.length} 张` : "");
+            this.add(new AssistantMessage(answer || "（模型返回空回答）", meta));
         }
         catch (error) {
             this.add(new Notice(ROLE.err, color.err, `模型请求失败：${errText(error)}`));

package/dist/model.d.ts

@@ -1,9 +1,15 @@
 import type { ModelConfig } from "@ganziliang/kb-model-setup";
 import type { SearchResult, KnowledgeStore } from "./storage.js";
-export type ToolCall = {
-    name: "search" | "read" | "write";
+export type NativeToolCall = {
+    id: string;
+    name: string;
     arguments: Record<string, unknown>;
 };
+export type ToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+};
 export type ContentBlock = {
     type: "text";
     text: string;
@@ -19,13 +25,13 @@ export type ModelMessage = {
 };
 export type ModelReply = {
     text?: string;
-    toolCalls?: ToolCall[];
+    toolCalls?: NativeToolCall[];
 };
 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>;
+    complete(config: ModelConfig, messages: ModelMessage[], tools?: ToolDefinition[]): Promise<ModelReply>;
 };
 export declare const fetchTransport: ModelTransport;
 export declare class Agent {
@@ -40,6 +46,11 @@ export declare class Agent {
     private execute;
 }
 export declare function formatResults(results: SearchResult[]): string;
+/**
+ * 让模型在一轮对话里自己决定「回答」还是「录入」，
+ * 避免为了判断意图而多跑一次模型调用。
+ */
+export declare const SAVE_KNOWLEDGE_TOOL: ToolDefinition;
 type VisionTransport = {
     complete: (config: ModelConfig, messages: ModelMessage[]) => Promise<ModelReply>;
 };

package/dist/model.js

@@ -23,7 +23,7 @@ function endpoint(config) {
     return `${config.baseURL.replace(/\/$/, "")}${config.api === "anthropic-messages" ? "/v1/messages" : "/v1/responses"}`;
 }
 export const fetchTransport = {
-    async complete(config, messages) {
+    async complete(config, messages, tools) {
         const headers = { "content-type": "application/json" };
         if (config.api === "anthropic-messages") {
             headers["x-api-key"] = config.apiKey;
@@ -31,19 +31,46 @@ export const fetchTransport = {
         }
         else
             headers.authorization = `Bearer ${config.apiKey}`;
+        const anthropicTools = tools?.length
+            ? { tools: tools.map((tool) => ({ name: tool.name, description: tool.description, input_schema: tool.inputSchema })) }
+            : {};
+        const openaiTools = tools?.length
+            ? { tools: tools.map((tool) => ({ type: "function", name: tool.name, description: tool.description, parameters: tool.inputSchema })) }
+            : {};
         const response = await fetch(endpoint(config), {
             method: "POST",
             headers,
             body: JSON.stringify(config.api === "anthropic-messages"
-                ? { 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) })) }),
+                ? { 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, ...anthropicTools }
+                : { model: config.model, input: messages.map((m) => ({ role: m.role, content: toOpenAIContent(m.content) })), ...openaiTools }),
         });
         if (!response.ok)
             throw new Error(`Model request failed (${response.status}): ${await response.text()}`);
         const data = await response.json();
-        if (config.api === "anthropic-messages")
-            return { text: data.content?.map((item) => item.text ?? "").join("") };
-        return { text: data.output_text ?? data.output?.map((item) => item.content?.map((part) => part.text ?? "").join("")).join("") ?? "" };
+        if (config.api === "anthropic-messages") {
+            let text = "";
+            const toolCalls = [];
+            for (const item of (data.content ?? [])) {
+                if (item.type === "text")
+                    text += item.text ?? "";
+                else if (item.type === "tool_use")
+                    toolCalls.push({ id: String(item.id ?? ""), name: String(item.name), arguments: (item.input ?? {}) });
+            }
+            return toolCalls.length ? { text, toolCalls } : { text };
+        }
+        const toolCalls = [];
+        for (const item of (data.output ?? [])) {
+            if (item.type !== "function_call")
+                continue;
+            let parsed = {};
+            try {
+                parsed = JSON.parse(item.arguments ?? "{}");
+            }
+            catch { /* 保留空参数 */ }
+            toolCalls.push({ id: String(item.call_id ?? item.id ?? ""), name: String(item.name), arguments: parsed });
+        }
+        const text = data.output_text ?? (data.output ?? []).map((item) => (item.content ?? []).map((part) => part.text ?? "").join("")).join("") ?? "";
+        return toolCalls.length ? { text, toolCalls } : { text };
     },
 };
 export class Agent {
@@ -72,12 +99,34 @@ export class Agent {
             return this.store.search(String(call.arguments.query ?? ""));
         if (call.name === "read")
             return this.store.read(String(call.arguments.id ?? "")) ?? { error: "Knowledge record not found" };
-        return { error: "write requires CLI ingestion flow" };
+        return { error: `Unknown tool: ${call.name}` };
     }
 }
 export function formatResults(results) {
     return results.map((result) => `[${result.id}] ${result.title} (source: ${result.source}, v${result.version})\n${result.content}`).join("\n\n");
 }
+/**
+ * 让模型在一轮对话里自己决定「回答」还是「录入」，
+ * 避免为了判断意图而多跑一次模型调用。
+ */
+export const SAVE_KNOWLEDGE_TOOL = {
+    name: "save_knowledge",
+    description: [
+        "把用户提供的内容保存到本地知识库。",
+        "当用户意图是「记录 / 保存 / 录入 / 收藏 / 备忘 / 以后要用」某段内容时调用，",
+        "例如：记住…、记一下…、记录一下…、把这段存起来、帮我存个配置、以后就按这个来。",
+        "只有用户确实在提供一段希望长期保存的知识时才调用。",
+        "如果用户在询问、查询、确认、闲聊，不要调用，直接回答。",
+    ].join(""),
+    inputSchema: {
+        type: "object",
+        properties: {
+            title: { type: "string", description: "对内容的一句话概括，作为知识条目标题，20 字以内" },
+            content: { type: "string", description: "要保存的完整内容，规范 Markdown。必须完整保留用户给出的全部信息，不要自行增删或改写事实" },
+        },
+        required: ["title", "content"],
+    },
+};
 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, [{

package/dist/storage.d.ts

@@ -54,6 +54,8 @@ type KnowledgeStoreResult = {
 };
 export declare function readLocalFile(filePath: string): LocalFile;
 export declare function copyOriginal(filePath: string, root: string): string;
+/** \u628a\u624b\u52a8\u5f55\u5165\u7684\u6587\u672c\u843d\u76d8\u4e3a originals/ \u4e0b\u7684 Markdown\uff0c\u8fd4\u56de\u8be5\u6587\u4ef6\u8def\u5f84\u3002 */
+export declare function writeNote(root: string, title: string, content: string): string;
 export declare function defaultDataRoot(): string;
 export declare function knowledgeBasePath(root: string, id: string): string;
 export declare function listKnowledgeBases(root: string): KnowledgeBase[];

package/dist/storage.js

@@ -1,4 +1,4 @@
-import { mkdirSync, copyFileSync, existsSync, readFileSync, statSync, cpSync, rmSync, readdirSync } from "node:fs";
+import { mkdirSync, copyFileSync, existsSync, readFileSync, statSync, cpSync, rmSync, readdirSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { join, resolve, extname, basename } from "node:path";
 import { DatabaseSync } from "node:sqlite";
@@ -115,6 +115,15 @@ export function copyOriginal(filePath, root) {
     copyFileSync(filePath, destination);
     return destination;
 }
+/** \u628a\u624b\u52a8\u5f55\u5165\u7684\u6587\u672c\u843d\u76d8\u4e3a originals/ \u4e0b\u7684 Markdown\uff0c\u8fd4\u56de\u8be5\u6587\u4ef6\u8def\u5f84\u3002 */
+export function writeNote(root, title, content) {
+    const dir = join(root, "originals");
+    mkdirSync(dir, { recursive: true });
+    const slug = title.replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "note";
+    const target = join(dir, `${Date.now()}-${slug}.md`);
+    writeFileSync(target, content, "utf8");
+    return target;
+}
 export function defaultDataRoot() {
     const home = process.env.HOME ?? process.env.USERPROFILE ?? process.cwd();
     return process.env.KB_DATA_DIR ?? join(home, ".kb");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganziliang/kb",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local knowledge base agent CLI with a pi-tui interface",
   "type": "module",
   "bin": {