@ganziliang/kb 0.2.0 → 0.4.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+→`。
 
 ### 导入文件
 
@@ -187,8 +190,95 @@ import D:\docs\api.txt
 导入 "D:\截图\支付报错.png"
 ```
 
+**路径写法很宽容**，下面这几种都能识别（只要文件真实存在）：
+
+```text
+录入 D:\资料\支付渠道配置.md到知识库     # 路径后粘了中文
+导入D:\资料\支付渠道配置.md              # 关键词后没空格
+"D:\资料\文件名字带空格.md"              # 带空格的路径用引号包起来
+D:\资料\支付渠道配置.md                 # 直接拖文件进来，不带任何关键词
+```
+
+路径识别走的是本地检查（`statSync`），**不消耗模型调用**。
+
 导入后会复制一份原始文件，并建立版本记录。对同一个文件再次导入时，会创建新版本，不会直接覆盖旧版本。
 
+如果路径不存在或是目录，会直接给提示而不去问模型；目录暂不支持导入，请指定具体文件。
+
+### 让 kb 读写本地文件
+
+除了导入，kb 也把文件读写作为工具交给了模型，所以可以直接用自然语言：
+
+```text
+帮我看看 D:\资料\支付渠道配置.md 写了什么？     → 读取文件后回答
+把这段内容导出到 D:\out\纪要.md                 → 写入文件
+把 D:\资料\渠道.md 收录到知识库                  → 导入知识库
+```
+
+对应的工具：
+
+| 工具 | 作用 |
+| --- | --- |
+| `save_knowledge` | 把对话里的文本存进知识库 |
+| `save_from_file` | 把磁盘文件导入知识库（只传路径，正文由程序读取） |
+| `read_file` | 读取文件内容（不写进知识库） |
+| `write_file` | 把内容写入指定文件 |
+
+模型可能多轮调用这些工具（例如先 `read_file` 再回答，或直接 `save_from_file` 完成导入），
+每轮最多 5 次工具调用。
+
+> 注意：`read_file` / `write_file` 让模型可以访问你本机的文件。kb 是本地工具，
+> 在你自己的机器上运行，但请不要在输入里让它处理你不想被读取的敏感路径。
+
+### 直接录入文本
+
+不需要先把内容存成文件，也不需要记命令——用自然语言告诉 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 +319,7 @@ import D:\docs\api.txt
 | `/help` | 查看命令列表 |
 | `/clear` | 清空当前对话上下文 |
 | `/sources` | 查看当前知识库中的来源文件、路径和版本 |
+| `/add <内容>` | 显式录入文本（正常直接说「记住…」即可） |
 | `/models` 或 `/model` | 查看已配置模型 |
 | `/model <编号>` | 切换模型，例如 `/model 1` |
 | `/kb list` | 查看所有知识库 |

package/dist/cli.d.ts

@@ -27,8 +27,11 @@ export declare class KbApp {
     private shutdown;
     private submit;
     private run;
+    private addNote;
     private ingest;
     private ask;
+    /** 执行一次工具调用；done 为 true 表示任务已完成，无需再回模型。 */
+    private runTool;
     private command;
     private showSources;
     private showModelPicker;

package/dist/cli.js

@@ -1,16 +1,115 @@
 #!/usr/bin/env node
-import { mkdirSync } from "node:fs";
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 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 { READ_FILE_TOOL, SAVE_FROM_FILE_TOOL, SAVE_KNOWLEDGE_TOOL, WRITE_FILE_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) || "���记";
+}
+/** 工具回传给模型的最大字符数，避免单次工具结果爆掉上下文。 */
+const MAX_TOOL_CHARS = 8000;
+/** 只接受真实存在的「文件」，目录不算（否则会把目录当成待导入文件）。 */
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 从输入里找出一个真实存在的文件路径。
+ * 容忍「录入 D:\a.md」与「录入D:\a.md到知识库」两种写法：
+ * 后者路径尾部粘了中文，靠逐步截断 + 文件存在性检查回退。
+ */
+function extractExistingPath(text) {
+    for (const match of text.matchAll(/["'`]([^"'`]+)["'`]/g)) {
+        const candidate = match[1].trim();
+        if (isFile(candidate))
+            return candidate;
+    }
+    const candidates = text.match(/[A-Za-z]:[\\/][^\s"'`|<>*?]+|\/[^\s"'`|<>*?]+|\.{1,2}[\\/][^\s"'`|<>*?]+/g) ?? [];
+    for (const candidate of candidates) {
+        if (isFile(candidate))
+            return candidate;
+        const limit = Math.min(candidate.length - 1, 40);
+        for (let cut = 1; cut <= limit; cut += 1) {
+            const probe = candidate.slice(0, candidate.length - cut);
+            if (isFile(probe))
+                return probe;
+        }
+    }
+    return undefined;
+}
+/** 输入里出现这些词、且能找到真实路径时，直接本地导入（不消耗模型）。 */
+const IMPORT_WORDS = /(?:录入|导入|收录|整理|加到|加入|添加|入库|ingest|import)/i;
+/** 多行内容回显时只显示首行，避免刷屏。 */
+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)，title 用一句话概括，content 用规范 Markdown 完整保留用户信息。",
+        "   此时不要回答内容本身，也不要反问确认。",
+        "",
+        "C) 录入文件 —— 用户给了一个文件路径，想归档到知识库。",
+        "   调用 save_from_file(path, title)。",
+        "   重要：只传路径，不要先 read_file 再把内容抄进 save_knowledge，也不要说你无法访问本地文件。",
+        "",
+        "D) 查看文件 —— 用户想知道某个文件里写了什么。",
+        "   调用 read_file(path)，然后根据读到的内容回答。",
+        "",
+        "E) 导出文件 —— 用户要求把内容写成文件、导出到某个路径。",
+        "   调用 write_file(path, content)。",
+        "",
+        "判断依据是用户表达的意图，不要依赖固定关键词。",
+        "",
+        "知识库内容：",
+        "---",
+        context,
+        "---",
+    ].join("\n");
+}
 const HELP_ITEMS = [
     ["/help", "显示本帮助"],
     ["/clear", "清空对话上下文"],
     ["/sources", "列出知识来源与版本"],
+    ["/add <内容>", "显式录入（通常直接说「记住…」即可）"],
     ["/model", "查看 / 切换模型"],
     ["/kb", "多知识库管理"],
     ["/backup", "备份当前知识库"],
@@ -127,6 +226,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;
@@ -136,15 +246,55 @@ export class KbApp {
         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, ""));
+        const trimmed = value.trim();
+        const looksLikePath = /[A-Za-z]:[\\/]|(?:^|[\s"'])~?[.\/]/.test(trimmed) || isDirectory(trimmed);
+        // 既有导入意图、又能定位到真实文件：直接本地导入，不消耗模型。
+        if (IMPORT_WORDS.test(value)) {
+            const path = extractExistingPath(value);
+            if (path) {
+                await this.ingest(path);
+                return;
+            }
+            if (isDirectory(trimmed)) {
+                this.add(new Notice(ROLE.warn, color.warn, `${trimmed} 是一个目录，请指定具体文件（目录暂不支持导入）。`));
+                return;
+            }
+            if (looksLikePath) {
+                this.add(new Notice(ROLE.err, color.err, "没有找到这个文件，请确认路径是否正确。"));
+                return;
+            }
+        }
+        // 整条输入就是一个存在的文件路径（例如直接把文件拖进来）。
+        const direct = extractExistingPath(trimmed);
+        if (direct && direct === trimmed) {
+            await this.ingest(direct);
+            return;
+        }
+        if (isDirectory(trimmed)) {
+            this.add(new Notice(ROLE.warn, color.warn, `${trimmed} 是一个目录，请指定具体文件（目录暂不支持导入）。`));
             return;
         }
         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) {
+    async ingest(path, explicitTitle = "") {
         try {
             this.setBusy(true, "读取文件…");
             const source = readLocalFile(path);
@@ -167,8 +317,9 @@ export class KbApp {
                     note = "，图片描述生成失败（仅按文件名检索）";
                 }
             }
+            const title = explicitTitle.trim() || source.title;
             const copied = copyOriginal(source.originalPath, this.store.root);
-            const result = this.store.addOrUpdateSource(copied, source.title, content);
+            const result = this.store.addOrUpdateSource(copied, title, content);
             this.add(new Notice(ROLE.ok, color.ok, `${result.isNew ? "已导入" : "已创建新版本"} ${result.title}（v${result.version}）${note}`));
         }
         catch (error) {
@@ -191,30 +342,56 @@ 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.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));
+            const tools = [SAVE_KNOWLEDGE_TOOL, SAVE_FROM_FILE_TOOL, READ_FILE_TOOL, WRITE_FILE_TOOL];
+            const messages = [
+                { role: "system", content: buildSystemPrompt(context) },
+                ...this.messages,
+                { role: "user", content: questionBlocks.length > 1 ? questionBlocks : question },
+            ];
+            // 工具循环：模型可能先 read_file 再回答，或者直接调 save_* 完成录入。
+            for (let round = 0; round < 5; round += 1) {
+                this.setBusy(true, round === 0
+                    ? (attached.length ? `检索到 ${results.length} 条，附图 ${attached.length} 张，正在理解意图…` : `检索到 ${results.length} 条，正在理解意图…`)
+                    : "正在继续处理…");
+                const reply = await fetchTransport.complete(config, messages, tools);
+                if (!reply.toolCalls?.length) {
+                    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);
+                    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} 条 · 用时 ${seconds}s` + (attached.length ? ` · 附图 ${attached.length} 张` : "");
+                    this.add(new AssistantMessage(answer || "（模型返回空回答）", meta));
+                    return;
+                }
+                messages.push({ role: "assistant", content: reply.text ?? "", toolCalls: reply.toolCalls });
+                let finished = false;
+                for (const call of reply.toolCalls) {
+                    const outcome = await this.runTool(call);
+                    if (outcome.done) {
+                        finished = true;
+                        break;
+                    }
+                    messages.push({ role: "tool", toolCallId: call.id, content: outcome.text });
+                }
+                if (finished)
+                    return;
+            }
+            this.add(new Notice(ROLE.warn, color.warn, "工具调用轮次过多，已停止。"));
         }
         catch (error) {
             this.add(new Notice(ROLE.err, color.err, `模型请求失败：${errText(error)}`));
@@ -223,6 +400,49 @@ export class KbApp {
             this.setBusy(false);
         }
     }
+    /** 执行一次工具调用；done 为 true 表示任务已完成，无需再回模型。 */
+    async runTool(call) {
+        const arg = (key) => String(call.arguments[key] ?? "").trim();
+        if (call.name === SAVE_KNOWLEDGE_TOOL.name) {
+            this.setBusy(true, "正在录入知识库…");
+            await this.addNote(arg("content"), arg("title"));
+            return { done: true, text: "已录入知识库" };
+        }
+        if (call.name === SAVE_FROM_FILE_TOOL.name) {
+            this.setBusy(true, "正在读取文件…");
+            await this.ingest(arg("path"), arg("title"));
+            return { done: true, text: "已从文件导入知识库" };
+        }
+        if (call.name === READ_FILE_TOOL.name) {
+            const path = arg("path");
+            this.setBusy(true, `正在读取 ${path.split(/[\\/]/).pop() ?? "文件"}…`);
+            try {
+                const source = readLocalFile(path);
+                const clipped = source.content.length > MAX_TOOL_CHARS
+                    ? `${source.content.slice(0, MAX_TOOL_CHARS)}\n…（已截断，全文共 ${source.content.length} 字符）`
+                    : source.content;
+                this.add(new Notice(ROLE.ok, color.ok, `已读取 ${source.title}（${source.content.length} 字符）`));
+                return { done: false, text: `文件 ${source.title} 的内容如下：\n\n${clipped}` };
+            }
+            catch (error) {
+                return { done: false, text: `读取失败：${errText(error)}` };
+            }
+        }
+        if (call.name === WRITE_FILE_TOOL.name) {
+            const path = arg("path");
+            const content = String(call.arguments.content ?? "");
+            try {
+                mkdirSync(dirname(path), { recursive: true });
+                writeFileSync(path, content, "utf8");
+                this.add(new Notice(ROLE.ok, color.ok, `已写入 ${path}（${content.length} 字符）`));
+                return { done: false, text: `已写入 ${path}` };
+            }
+            catch (error) {
+                return { done: false, text: `写入失败：${errText(error)}` };
+            }
+        }
+        return { done: false, text: `未知工具：${call.name}` };
+    }
     // ---------- 命令 ----------
     async command(value) {
         const [cmd, ...rest] = value.split(/\s+/);

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;
@@ -15,17 +21,24 @@ export type ContentBlock = {
 export type ModelMessage = {
     role: "system" | "user" | "assistant" | "tool";
     content: string | ContentBlock[];
+    /** assistant 消息回传时携带的工具调用（tool_use / function_call）。 */
+    toolCalls?: NativeToolCall[];
+    /** role 为 tool 时，关联的 tool_use id。 */
     toolCallId?: string;
 };
 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;
+/** 把内部消息数组转成 Anthropic Messages API 的 messages（tool_result 必须放进 user 消息）。 */
+export declare function toAnthropicMessages(messages: ModelMessage[]): unknown[];
+/** 把内部消息数组转成 OpenAI Responses API 的 input。 */
+export declare function toOpenAIInput(messages: ModelMessage[]): unknown[];
 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 +53,21 @@ export declare class Agent {
     private execute;
 }
 export declare function formatResults(results: SearchResult[]): string;
+/**
+ * 让模型在一轮对话里自己决定「回答」还是「录入」，
+ * 避免为了判断意图而多跑一次模型调用。
+ */
+export declare const SAVE_KNOWLEDGE_TOOL: ToolDefinition;
+/**
+ * 从本地文件导入知识。
+ * 单独做成一个工具，是为了避免让模型把整份文件内容搬进参数里
+ * （大文件会直接爆掉输出 token）：模型只给路径，正文由本地读取。
+ */
+export declare const SAVE_FROM_FILE_TOOL: ToolDefinition;
+/** 读取本地文件内容（用于回答关于文件的问题，不会写进知识库）。 */
+export declare const READ_FILE_TOOL: ToolDefinition;
+/** 写入本地文件。 */
+export declare const WRITE_FILE_TOOL: ToolDefinition;
 type VisionTransport = {
     complete: (config: ModelConfig, messages: ModelMessage[]) => Promise<ModelReply>;
 };

package/dist/model.js

@@ -15,6 +15,63 @@ export function toOpenAIContent(content) {
 export function contentToText(content) {
     return typeof content === "string" ? content : content.map((block) => block.type === "text" ? block.text : `[image:${block.mediaType}]`).join("\n");
 }
+/** 把内部消息数组转成 Anthropic Messages API 的 messages（tool_result 必须放进 user 消息）。 */
+export function toAnthropicMessages(messages) {
+    const out = [];
+    for (const message of messages) {
+        if (message.role === "system")
+            continue;
+        if (message.role === "tool") {
+            const block = {
+                type: "tool_result",
+                tool_use_id: message.toolCallId ?? "",
+                content: typeof message.content === "string" ? message.content : contentToText(message.content),
+            };
+            const last = out[out.length - 1];
+            if (last && last.role === "user" && Array.isArray(last.content))
+                last.content.push(block);
+            else
+                out.push({ role: "user", content: [block] });
+            continue;
+        }
+        if (message.role === "assistant" && message.toolCalls?.length) {
+            const blocks = [];
+            const text = typeof message.content === "string" ? message.content : contentToText(message.content);
+            if (text)
+                blocks.push({ type: "text", text });
+            for (const call of message.toolCalls)
+                blocks.push({ type: "tool_use", id: call.id, name: call.name, input: call.arguments });
+            out.push({ role: "assistant", content: blocks });
+            continue;
+        }
+        out.push({ role: message.role, content: toAnthropicContent(message.content) });
+    }
+    return out;
+}
+/** 把内部消息数组转成 OpenAI Responses API 的 input。 */
+export function toOpenAIInput(messages) {
+    const out = [];
+    for (const message of messages) {
+        if (message.role === "tool") {
+            out.push({
+                type: "function_call_output",
+                call_id: message.toolCallId ?? "",
+                output: typeof message.content === "string" ? message.content : contentToText(message.content),
+            });
+            continue;
+        }
+        if (message.role === "assistant" && message.toolCalls?.length) {
+            const text = typeof message.content === "string" ? message.content : contentToText(message.content);
+            if (text)
+                out.push({ role: "assistant", content: toOpenAIContent(text) });
+            for (const call of message.toolCalls)
+                out.push({ type: "function_call", call_id: call.id, name: call.name, arguments: JSON.stringify(call.arguments) });
+            continue;
+        }
+        out.push({ role: message.role, content: toOpenAIContent(message.content) });
+    }
+    return out;
+}
 // 历史消息里的图片 base64 不重复携带：每轮都会重新检索并附图，避免上下文膨胀。
 function compactHistory(messages) {
     return messages.map((message) => typeof message.content === "string" ? message : { ...message, content: contentToText(message.content) });
@@ -23,7 +80,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 +88,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: toAnthropicMessages(messages), system: messages.find((m) => m.role === "system")?.content, ...anthropicTools }
+                : { model: config.model, input: toOpenAIInput(messages), ...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 {
@@ -62,7 +146,7 @@ export class Agent {
             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 });
+            messages.push({ role: "tool", content: JSON.stringify(result), toolCallId: call.id });
         }
         const final = await this.transport.complete(this.config, messages);
         return { text: final.text ?? "", messages: [...compactHistory(messages), { role: "assistant", content: final.text ?? "" }] };
@@ -72,12 +156,90 @@ 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"],
+    },
+};
+/**
+ * 从本地文件导入知识。
+ * 单独做成一个工具，是为了避免让模型把整份文件内容搬进参数里
+ * （大文件会直接爆掉输出 token）：模型只给路径，正文由本地读取。
+ */
+export const SAVE_FROM_FILE_TOOL = {
+    name: "save_from_file",
+    description: [
+        "把本地磁盘上的一个文件导入知识库。",
+        "当用户提到一个文件路径并要求录入、导入、收录到知识库时使用，",
+        "例如：录入 D:/docs/a.md、把这个文件加到知识库、import ./notes.txt。",
+        "只需要提供路径，正文由程序自己读取，不要把文件内容写进参数。",
+    ].join(""),
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "文件的绝对路径，例如 D:/docs/支付渠道配置.md" },
+            title: { type: "string", description: "可选。知识条目标题，不填则用文件名" },
+        },
+        required: ["path"],
+    },
+};
+/** 读取本地文件内容（用于回答关于文件的问题，不会写进知识库）。 */
+export const READ_FILE_TOOL = {
+    name: "read_file",
+    description: [
+        "读取本地文件的内容。",
+        "当用户想知道某个文件里写了什么、需要你根据文件内容回答、",
+        "或者需要先查看文件再决定如何处理时使用。",
+        "如果用户只是要把文件录入知识库，应该用 save_from_file 而不是这个工具。",
+    ].join(""),
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "要读取的文件绝对路径" },
+        },
+        required: ["path"],
+    },
+};
+/** 写入本地文件。 */
+export const WRITE_FILE_TOOL = {
+    name: "write_file",
+    description: [
+        "把文本内容写入本地文件。",
+        "仅在用户明确要求导出、另存为、写到某个文件路径时使用。",
+        "不要用它来记录知识（那应该用 save_knowledge）。",
+    ].join(""),
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "目标文件绝对路径" },
+            content: { type: "string", description: "要写入的完整文本内容" },
+        },
+        required: ["path", "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.4.0",
   "description": "Local knowledge base agent CLI with a pi-tui interface",
   "type": "module",
   "bin": {