@ganziliang/kb 0.1.5 → 0.1.7

package/README.md

@@ -1,6 +1,6 @@
 # @ganziliang/kb
 
-本地知识库命令行工具。它会把本地 Markdown、文本、JSON、CSV 或 Excel 文件导入 SQLite 知识库，然后通过关键词检索相关内容，并调用已配置的模型回答问题。
+本地知识库命令行工具。它会把本地 Markdown、文本、JSON、CSV 或 Excel 文件导入 SQLite 知识库，然后通过关键词检索相关内容，并调用已配置的模型回答问题。同时支持导入图片：入库时自动生成中文描述参与检索，提问命中后把原图发给模型。
 
 ## 环境要求
 
@@ -22,20 +22,18 @@ npm install -g @ganziliang/kb
 kb
 ```
 
-### 在源码目录运行
+`@ganziliang/kb` 已经声明依赖 `@ganziliang/kb-model-setup`。通过 npm 安装 `@ganziliang/kb` 时，npm 会自动安装该依赖，正常情况下不需要单独安装。
+
+如果你需要单独安装或更新模型配置模块，可以执行：
 
 ```bash
-cd D:\IDEAProject\ai_work\zhishiku\kb
-npm install
-npm run build
-node dist/entry.js
+npm install -g @ganziliang/kb-model-setup
 ```
 
-如果希望全局的 `kb` 命令使用当前源码构建结果，可以在源码目录执行：
+注意：`kb-model-setup` 是模型配置模块，不是启动 `kb` 的主命令。日常使用只需要运行：
 
 ```bash
-npm link
-npm run build
+kb
 ```
 
 ## 首次启动和模型配置
@@ -51,6 +49,8 @@ kb
 1. `api-stats` 页面地址或 `apiId`
 2. API Key
 
+`kb` 使用依赖包 `@ganziliang/kb-model-setup` 完成模型配置。该模块会查询智真 LLM Gateway 中当前账号可用的模型，并保存所选模型配置。
+
 当前默认使用智真 LLM Gateway：
 
 ```text
@@ -75,6 +75,7 @@ Windows 通常对应：
 C:\Users\<用户名>\.config\kb\config.json
 ```
 
+
 也可以通过环境变量跳过首次交互配置：
 
 ```bash
@@ -115,6 +116,7 @@ kb
 - JSON：`.json`
 - CSV：`.csv`
 - Excel：`.xlsx`、`.xls`
+- 图片：`.png`、`.jpg`、`.jpeg`、`.gif`、`.webp`、`.bmp`（需要模型支持视觉）
 
 导入命令格式：
 
@@ -137,10 +139,32 @@ import <文件路径>
 导入 ./docs/payment.md
 import D:\docs\api.txt
 导入 "D:\资料\产品说明.xlsx"
+导入 "D:\截图\支付报错.png"
 ```
 
 导入后会复制一份原始文件，并建立版本记录。对同一个文件再次导入时，会创建新版本，不会直接覆盖旧版本。
 
+### 图片知识
+
+图片本身无法参与关键词检索，因此 `kb` 对图片使用双通道处理：
+
+1. **入库时生成描述**：导入图片时会调用当前模型看图，生成一段中文描述（含图中所有文字、数字、表格与界面细节），写入知识库参与全文检索。
+2. **提问时附原图**：当问题检索命中图片记录时，`kb` 会把原始图片一并发送给模型，因此模型看到的是真实图像，而不只是描述。
+
+也就是说，导入一次图片后，既可以按内容关键词搜到它，也可以直接针对图片细节提问：
+
+```text
+导入 "D:\截图\支付报错.png"
+
+支付报错的截图里，订单号和错误码分别是什么？
+```
+
+注意：
+
+- 图片描述依赖当前模型具备视觉能力；模型不支持视觉时，图片仍会入库，但只能按文件名检索，并在导入结果中提示失败原因。
+- 单次提问最多附带 4 张命中图片。
+- 历史对话中不会重复携带图片数据，每轮提问都会按检索结果重新附图。
+
 ### 查询知识
 
 直接输入问题即可：

package/dist/cli.js

@@ -4,8 +4,8 @@ import { useEffect, useRef, useState } from "react";
 import { Box, Text, render, useApp, useInput } from "ink";
 import { mkdirSync } from "node:fs";
 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";
+import { Agent, describeImage, fetchTransport } from "./model.js";
+import { copyOriginal, defaultDataRoot, ensureKnowledgeBase, isImageFile, KnowledgeStore, readImage, readLocalFile, listKnowledgeBases, deleteKnowledgeBase, backupKnowledgeBase, restoreKnowledgeBase } from "./storage.js";
 const banner = [
     "  _  __ ____  ",
     " | |/ // __ ) ",
@@ -55,7 +55,7 @@ function App({ config, root, knowledgeBase }) {
             return;
         }
         if (value === "/help") {
-            setLines((old) => [...old, "/help /clear /sources /backup /restore /cleanup /model /models /kb /quit"]);
+            setLines((old) => [...old, "/help /clear /sources /backup /restore /cleanup /model /models /kb /quit", "导入：输入「导入 <文件路径>」，支持 .md/.txt/.json/.csv/.xlsx/.xls 及 .png/.jpg/.jpeg/.gif/.webp/.bmp", "图片入库时自动生成中文描述用于检索，提问命中后会把原图一并发给模型"]);
             return;
         }
         if (value === "/sources") {
@@ -161,14 +161,38 @@ async function ingestOrAsk(value, store, modelConfig, previous) {
         const source = readLocalFile(pathMatch[1].trim().replace(/^['"]|['"]$/g, ""));
         if (!source.hash)
             return { text: `${source.title}: unable to parse (${source.content})`, messages: previous };
+        let content = source.content;
+        let note = "";
+        if (source.image) {
+            try {
+                const caption = await describeImage(modelConfig, fetchTransport, source.image);
+                if (caption) {
+                    content = `${source.content}\n\n${caption}`;
+                    note = "，已生成图片描述";
+                }
+            }
+            catch (error) {
+                note = `，图片描述生成失败（仅按文件名检索）: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
         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 result = store.addOrUpdateSource(copied, source.title, content);
+        return { text: `${result.isNew ? "Imported" : "New version created for"} ${result.title} (v${result.version})${note}`, 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 prompt = `Answer only from the local knowledge below. If it is insufficient, say no knowledge was found. Include source filename and version.\n\n${context}\n\nQuestion: ${value}`;
+    const blocks = [{ type: "text", text: prompt }];
+    for (const item of results.filter((hit) => hit.originalPath && isImageFile(hit.originalPath)).slice(0, 4)) {
+        try {
+            const image = readImage(item.originalPath);
+            blocks.push({ type: "text", text: `[附图] ${item.source} v${item.version}` });
+            blocks.push({ type: "image", mediaType: image.mediaType, base64: image.base64 });
+        }
+        catch { /* 忽略无法读取的图片 */ }
+    }
     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);
+    return agent.answer(blocks.length > 1 ? blocks : prompt, previous);
 }
 export async function main() {
     const root = defaultDataRoot();

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganziliang/kb",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Local knowledge base agent CLI",
   "type": "module",
   "bin": {