@nickyzj2023/ai 1.4.4 → 1.6.0

package/README.md

@@ -1,64 +1,80 @@
-# ai
-
-男生自用Coding Agent，参考了[nanopi教学](https://pi-from-scratch.vercel.app/)
-
-不断学习+开发中，当前项目仍属于比nano还简陋的“bare-pi”，but one day...
-
-![demo](demo.gif)
-
-## 安装
-
-```bash
-# npm
-npm install @nickyzj2023/ai
-
-# yarn
-yarn add @nickyzj2023/ai
-
-# pnpm
-pnpm add @nickyzj2023/ai
-```
-
-## 使用方式
-
-### 在项目里使用
-
-```typescript
-import { defineModel, runAgent, getWeather } from "@nickyzj2023/ai";
-
-const model = defineModel({
-  baseUrl: "https://api.deepseek.com/v1",
-  apiKey: process.env.APIKEY,
-  model: "deepseek-v4-flash",
-});
-
-const tools = [
-  // 内置工具
-  getWeather,
-  getTime,
-  // 自定义工具
-  defineTool("getRandomNumber", "生成随机数字", {min: {type: "number", description: "最小区间"}, max: {type:"number", description:"最大区间"}}, () => 33550336),
-];
-
-const messages = [{ role: "user", content: "随机一个负无穷到正无穷的整数" }];
-
-for await (const e of runAgent(model, messages, tools)) {
-  console.log(e);
-}
-```
-
-### 在终端里使用
-
-```bash
-# 首次使用：交互式配置BASE_URL / APIKEY / MODEL / ...
-ai setup
-
-# 启动对话
-ai
-```
-
-配置保存在 `~/.@nickyzj2023/ai/config.json`，任意目录下执行`ai`都能读取到
-
-## License
-
-ISC
+# ai
+
+男生自用Coding Agent，参考了[nanopi教学](https://pi-from-scratch.vercel.app/)
+
+不断学习+开发中，当前项目仍属于比nano还简陋的“bare-pi”，but one day...
+
+![demo](demo.gif)
+
+## 安装
+
+```bash
+# npm
+npm install @nickyzj2023/ai
+
+# yarn
+yarn add @nickyzj2023/ai
+
+# pnpm
+pnpm add @nickyzj2023/ai
+```
+
+## 使用方式
+
+### 在项目里使用
+
+```typescript
+import { defineModel, runAgent, getWeather } from "@nickyzj2023/ai";
+// MCP体积较大（200kb），有需要时单独引入
+import { loadMCPTools } from "@nickyzj2023/ai/mcp";
+
+const model = defineModel({
+  baseUrl: "https://api.deepseek.com/v1",
+  apiKey: process.env.APIKEY,
+  model: "deepseek-v4-flash",
+});
+
+const tools = [
+  // 内置工具
+  getWeather,
+  getTime,
+  // MCP工具
+  ..(await loadMCPTools({
+    exa: {
+			type: "streamable_http",
+			url: "https://mcp.exa.ai/mcp",
+			headers: {
+				"x-api-key": "xxxxx",
+			},
+		}
+  })),
+  // 自定义工具
+  defineTool("skipReply", "跳过本轮回复", {reason: {type: "string", description: "不回复的理由"}}, () => {
+    const error = new Error(`模型保持沉默，理由：${reason}`);
+		error.name = "skipReply";
+		throw error;
+  }),
+];
+
+const messages = [{ role: "user", content: "随机一个负无穷到正无穷的整数" }];
+
+for await (const e of runAgent(model, messages, tools)) {
+  console.log(e);
+}
+```
+
+### 在终端里使用
+
+```bash
+# 首次使用：交互式配置BASE_URL / APIKEY / MODEL / ...
+ai setup
+
+# 启动对话
+ai
+```
+
+配置保存在 `~/.@nickyzj2023/ai/config.json`，任意目录下执行`ai`都能读取到
+
+## License
+
+ISC

package/dist/cli.mjs

@@ -1,10 +1,13 @@
-import { a as get_time_default, c as runAgent, i as get_weather_default, o as defineModel, r as loadMCPTools } from "./src-CuZ-6Jye.mjs";
+import { i as runAgent, n as get_weather_default, r as get_time_default } from "./src-CKKPKPMG.mjs";
+import { t as defineModel } from "./helper-juLVGxlQ.mjs";
+import { n as loadMCPTools } from "./mcp-DcntQg-a.mjs";
 import { compactStr, extractErrorMessage, isObject } from "@nickyzj2023/utils";
 import readline from "node:readline";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { MarkdownRenderer } from "@wterm/markdown";
+import { execFile } from "node:child_process";
 //#region src/utils/config.ts
 /**
 * 获取全局配置文件路径（Windows/macOS/Linux通用）
@@ -197,10 +200,110 @@ async function runSetup() {
 	}
 }
 //#endregion
+//#region src/utils/clipboard.ts
+/** 剪贴板图片的原始字节上限：超过则拒绝，避免把超大图片塞入请求体 */
+const MAX_CLIPBOARD_IMAGE_BYTES = 5242880;
+/**
+* 执行命令并原样取回stdout（二进制安全）
+* @param maxBuffer 允许的最大输出字节数
+*/
+const run = (command, args, maxBuffer) => {
+	return new Promise((resolve, reject) => {
+		execFile(command, args, {
+			encoding: "buffer",
+			timeout: 5e3,
+			maxBuffer
+		}, (error, stdout) => {
+			if (error) reject(error);
+			else resolve(stdout);
+		});
+	});
+};
+/** 组装成OpenAI接口能接受的data URL */
+const toDataUrl = (buffer, mime = "image/png") => ({
+	url: `data:${mime};base64,${buffer.toString("base64")}`,
+	bytes: buffer.length
+});
+/** Windows：用PowerShell把剪贴板里的图片转成base64后读出 */
+const readWindows = async () => {
+	const script = [
+		"Add-Type -AssemblyName System.Windows.Forms",
+		"Add-Type -AssemblyName System.Drawing",
+		"$img = [System.Windows.Forms.Clipboard]::GetImage()",
+		"if ($img) {",
+		"$ms = New-Object System.IO.MemoryStream",
+		"$img.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png)",
+		"[Convert]::ToBase64String($ms.ToArray())",
+		"}"
+	].join("; ");
+	const base64 = (await run("powershell.exe", [
+		"-NoProfile",
+		"-Command",
+		script
+	], 67108864)).toString("utf8").trim();
+	return base64 ? toDataUrl(Buffer.from(base64, "base64")) : null;
+};
+/** Linux：Wayland优先，其次X11，最后用python3的tkinter兜底；命令未安装或剪贴板里不是图片时跳过 */
+const readLinux = async () => {
+	for (const candidate of [{
+		command: "wl-paste",
+		args: [
+			"--no-newline",
+			"--type",
+			"image/png"
+		]
+	}, {
+		command: "xclip",
+		args: [
+			"-selection",
+			"clipboard",
+			"-t",
+			"image/png",
+			"-o"
+		]
+	}]) try {
+		const stdout = await run(candidate.command, candidate.args, MAX_CLIPBOARD_IMAGE_BYTES * 2);
+		if (stdout.length === 0) continue;
+		return candidate.base64 ? toDataUrl(Buffer.from(stdout.toString("ascii").trim(), "base64")) : toDataUrl(stdout);
+	} catch {}
+	return null;
+};
+/**
+* 读取系统剪贴板里的图片
+* @returns 剪贴板里没有图片、或当前环境拿不到时返回null
+*/
+const readClipboardImage = async () => {
+	try {
+		switch (process.platform) {
+			case "win32": return await readWindows();
+			default: return await readLinux();
+		}
+	} catch {
+		return null;
+	}
+};
+//#endregion
+//#region src/utils/internalHelper.ts
+const formatter = new Intl.NumberFormat("en-US", {
+	notation: "compact",
+	maximumFractionDigits: 1
+});
+/** 把数字转换成千分位 */
+const humanizeNumber = (number) => {
+	return formatter.format(number);
+};
+//#endregion
 //#region src/interfaces/tui.ts
 var TUI = class {
 	rl = null;
 	onPrompt = null;
+	/**
+	* 已粘贴、等待随下次请求一起发出的图片
+	* TODO: 改为pendingMedias
+	*/
+	pendingImages = [];
+	/** 剪贴板读取是异步的，回车时要先等它结束，避免漏掉刚粘贴的图片 */
+	clipboardTask = Promise.resolve();
 	/** content专用的markdown渲染器 */
 	md = null;
 	/** 是否允许输入 */
@@ -222,27 +325,57 @@ var TUI = class {
 			input: process.stdin,
 			output: process.stdout
 		});
+		process.stdin.on("keypress", this.onKeypress);
 		this.prompting();
 		this.rl.on("close", () => {
+			process.stdin.off("keypress", this.onKeypress);
 			this.rl?.close();
 			this.rl = null;
 		});
 	}
+	/** 监听用户的特定按键 */
+	onKeypress = (_str, key) => {
+		if (this.isBusy) return;
+		if (key?.ctrl && key?.name === "v") this.clipboardTask = this.clipboardTask.then(() => this.attachImage());
+	};
 	/** 监听用户输入 */
 	prompting() {
 		if (this.isBusy) return;
 		this.rl?.question("> ", async (answer) => {
-			const input = answer.trim();
-			if (!input) {
+			await this.clipboardTask;
+			const text = answer.trim();
+			const images = this.pendingImages;
+			this.pendingImages = [];
+			if (!text && images.length === 0) {
 				this.prompting();
 				return;
 			}
 			this.isBusy = true;
-			await this.onPrompt?.(input);
+			await this.onPrompt?.({
+				text,
+				images
+			});
 			this.isBusy = false;
 			this.prompting();
 		});
 	}
+	/** 读取剪贴板图片，推入待发送列表 */
+	async attachImage() {
+		const image = await readClipboardImage();
+		if (!image) {
+			this.printNotice("[剪贴板中没有图片]");
+			return;
+		}
+		if (image.bytes > 5242880) {
+			this.printNotice(`[图片过大（${humanizeNumber(image.bytes)}B），已忽略]`);
+			return;
+		}
+		this.pendingImages.push({
+			type: "image_url",
+			image_url: { url: image.url }
+		});
+		this.printNotice(`[已粘贴图片：共${this.pendingImages.length}张]`);
+	}
 	/**
 	* 所有print方法调用前：
 	* 状态切换时打印换行，并记录当前状态
@@ -294,27 +427,33 @@ var TUI = class {
 		this.preparePrint("tool_result");
 		process.stdout.write(this.colorize(`[工具结果：${name}] ${_result}\n`, "90"));
 	}
-	formatter = new Intl.NumberFormat("en-US", {
-		notation: "compact",
-		maximumFractionDigits: 1
-	});
-	format(number) {
-		return this.formatter.format(number);
-	}
 	/** 打印轮次结束原因、token消耗 */
 	printFinish(finishReason, usage) {
 		this.preparePrint("done");
-		process.stdout.write(this.colorize(`[本轮结束：${finishReason}] ${usage ? `输入${this.format(usage.prompt_tokens)}token，输出${this.format(usage.completion_tokens)}token，总共${this.format(usage.total_tokens)}token` : ""}${finishReason === "stop" ? "\n\n" : "\n"}`, "90"));
+		process.stdout.write(this.colorize(`[本轮结束：${finishReason}] ${usage ? `输入${humanizeNumber(usage.prompt_tokens)}，输出${humanizeNumber(usage.completion_tokens)}，总共${humanizeNumber(usage.total_tokens)}` : ""}${usage?.speed ? `，速度${usage.speed}/秒` : ""}${finishReason === "stop" ? "\n\n" : "\n"}`, "90"));
 	}
-	/**
-	* 打印一行黄色状态提示（如“等待MCP工具加载完成…”）
-	*/
-	printStatus(message) {
-		process.stdout.write(this.colorize(message, "93"));
+	/** 打印一行黄字提示，并重绘当前输入行 */
+	printNotice(message) {
+		process.stdout.write(`${this.colorize(message, "93")}\n`);
+		this.rl?.prompt(true);
 	}
 };
 //#endregion
 //#region src/cli.ts
+/**
+* 组装用户消息的content
+* @remarks 有图片时必须用ContentPart[]（OpenAI多模态协议），纯文本则保持字符串
+*/
+const buildUserContent = (text, images) => {
+	if (images.length === 0) return text;
+	const content = [];
+	if (text) content.push({
+		type: "text",
+		text
+	});
+	content.push(...images);
+	return content;
+};
 /** 启动交互对话：配置来自全局配置文件，环境变量可临时覆盖 */
 const startChat = async () => {
 	const config = loadConfig();
@@ -328,14 +467,17 @@ const startChat = async () => {
 		mcpReady = true;
 		return tools;
 	});
-	const messages = [];
+	const messages = [{
+		role: "system",
+		content: `你是${model.model}，当前时间${(/* @__PURE__ */ new Date()).toLocaleString()}`
+	}];
 	let tools = null;
-	const tui = new TUI(async (input) => {
+	const tui = new TUI(async ({ text, images }) => {
 		messages.push({
 			role: "user",
-			content: input
+			content: buildUserContent(text, images)
 		});
-		if (!mcpReady) tui.printStatus("等待MCP工具加载完成…");
+		if (!mcpReady) tui.printNotice("MCP工具还未加载完成，请稍候……");
 		tools ??= [
 			get_weather_default,
 			get_time_default,

package/dist/helper-juLVGxlQ.mjs

@@ -0,0 +1,65 @@
+//#region src/utils/helper.ts
+/**
+* 辅助定义一个POST /chat/completions支持的model参数
+* @remarks 只有baseUrl字段是必须的
+*/
+const defineModel = (config) => ({
+	modalities: ["text"],
+	context: 131072,
+	...config
+});
+/**
+* 辅助定义一个POST /chat/completions支持的tool对象
+* @param execute 实际执行工具的函数
+*/
+const defineTool = (name, description, properties, execute) => {
+	const _required = [];
+	return {
+		type: "function",
+		function: {
+			name,
+			description,
+			parameters: {
+				type: "object",
+				properties: Object.entries(properties).reduce((result, [key, property]) => {
+					if ("required" in property) {
+						_required.push(key);
+						delete property.required;
+					}
+					result[key] = property;
+					return result;
+				}, {}),
+				required: _required
+			}
+		},
+		execute
+	};
+};
+const segmenter = new Intl.Segmenter([], { granularity: "word" });
+const estimateTextTokens = (text) => {
+	let words = 0;
+	let others = 0;
+	for (const seg of segmenter.segment(text)) if (seg.isWordLike) words++;
+	else others++;
+	return Math.ceil(words * 1.5 + others / 4);
+};
+/**
+* 根据上下文里的中/英文/多模态消息，估算出可能消耗的token
+* - 单词 ≈ 1.5token
+* - 标点/空白等非词字符每4个 ≈ 1token
+* - 图片/音频/视频/文件 ≈ 4096token（不好估算，取个较大的值）
+*/
+const estimateTokens = (messages) => {
+	if (!messages?.length) return 0;
+	return messages.reduce((acc, message) => {
+		const { content, tool_calls, ...metadata } = message;
+		if (typeof content === "string") acc += estimateTextTokens(content);
+		else for (const part of content) if (part.type === "text") acc += estimateTextTokens(part.text);
+		else acc += 4096;
+		if (tool_calls) acc += estimateTextTokens(JSON.stringify(tool_calls));
+		acc += estimateTextTokens(JSON.stringify(metadata));
+		return acc;
+	}, 0);
+};
+//#endregion
+export { estimateTokens as i, defineTool as n, estimateTextTokens as r, defineModel as t };