@mmteam/jsllm 0.1.13 → 0.1.14

package/package.json

@@ -1,20 +1,9 @@
 {
   "name": "@mmteam/jsllm",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "MM Team LLM library (providers + chat/session runner)",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "types": "./dist/types.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/types.d.ts",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "sideEffects": false,
+  "main": "./index.cjs",
+  "types": "./types.d.ts",
   "engines": {
     "node": ">=20.0.0"
   }

package/types.d.ts

@@ -0,0 +1,295 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * @packageDocumentation
+ *
+ * `@mmteam/jsllm` 对外仅暴露少量稳定 API（会话引擎 + 单轮生成）与必要类型。
+ *
+ * 说明：
+ * - 本包以 CommonJS 方式导出（`require('@mmteam/jsllm')`）。
+ * - 更详细的参数、类型与中文注释请参考发布包中的 `dist/types.d.ts`。
+ */
+/**
+ * 供应商 API 协议类型。
+ * - `"openai"`：OpenAI 兼容协议（可对接 OpenAI、兼容网关、qwen* 等）
+ * - `"gemini"`：Gemini SDK 协议
+ */
+export type JsLlmProviderApiType = "gemini" | "openai";
+/**
+ * 通用 thinking 配置（公共字段）。
+ *
+ * 注意：是否生效取决于供应商/模型；qwen* 场景下会映射到 OpenAI compatible 的扩展字段。
+ */
+export type JsLlmThinkingOptions = {
+	/**
+	 * thinking 开关。
+	 * - 允许 boolean/number/string 以兼容历史配置与不同服务端接受的类型
+	 */
+	enabled?: boolean | number | string;
+	/**
+	 * thinking 预算（tokens）。
+	 * - 允许 number/string 以兼容不同服务端入参要求
+	 */
+	budgetTokens?: number | string;
+};
+/**
+ * qwen 模型私有字段（仅 qwen* providerName 生效）。
+ *
+ * 优先级：qwen 私有字段 > thinking 公共字段。
+ */
+export type JsLlmQwenOptions = {
+	/**
+	 * Qwen/DashScope OpenAI compatible 扩展字段：`enable_thinking`
+	 */
+	enable_thinking?: boolean | number | string;
+	/**
+	 * Qwen/DashScope OpenAI compatible 扩展字段：`thinking_budget`
+	 */
+	thinking_budget?: number | string;
+};
+/**
+ * 初始化 LLM 配置（下游项目通常由配置文件/环境变量拼装得到）。
+ *
+ * 关键约定：
+ * - `providerName` 用于做部分模型/供应商的策略判断（例如 `qwen*` 前缀）。
+ * - `temperature` 若不合法（非有限数字或不在 [0,2]）将不会下发给供应商，从而使用供应商默认值。
+ */
+export type JsLlmInitOptions = {
+	/**
+	 * 供应商名称（用于标识与部分策略判断）。
+	 * - qwen* 判断规则：以 `qwen` 前缀（不区分大小写）命名时视为 qwen 模式（例如 `qwen1`、`qwen-local`）。
+	 */
+	providerName: string;
+	/**
+	 * 协议类型：`openai` 或 `gemini`。
+	 */
+	apiType: JsLlmProviderApiType;
+	/**
+	 * 供应商 API Key。
+	 */
+	apiKey: string;
+	/**
+	 * 可选：自定义 API baseUrl（常用于反向代理/兼容网关）。
+	 * - OpenAI compatible：例如 `https://your-gateway.example.com/v1`
+	 * - Gemini：默认通常为 `https://generativelanguage.googleapis.com`；仅代理/国内环境需要设置
+	 */
+	baseUrl?: string;
+	/**
+	 * 可选：API 版本（当前主要用于 Gemini）。
+	 * - 预览模型建议显式配置，例如 `v1beta`
+	 */
+	apiVersion?: string;
+	/**
+	 * 模型名称（不同供应商的模型命名规则不同）。
+	 */
+	model: string;
+	/**
+	 * 可选：采样温度。
+	 * - 合法范围：[0,2]
+	 * - 不传/不合法：不下发给供应商（使用供应商默认值）
+	 */
+	temperature?: number;
+	/**
+	 * 通用 thinking 配置（公共字段）。
+	 */
+	thinking?: JsLlmThinkingOptions;
+	/**
+	 * qwen 私有字段（仅 qwen* providerName 生效）。
+	 */
+	qwen?: JsLlmQwenOptions;
+};
+/**
+ * 对话消息角色。
+ */
+export type JsLlmChatMessageRole = "system" | "user" | "assistant" | "tool";
+/**
+ * 工具调用结构（OpenAI compatible 常见）。
+ * - `arguments` 必须是 JSON 字符串（例如 `{"command":"ls -la"}`）
+ */
+export type JsLlmChatToolCall = {
+	id: string;
+	name: string;
+	arguments: string;
+};
+/**
+ * 对话消息结构。
+ */
+export type JsLlmChatMessage = {
+	/**
+	 * 消息角色。
+	 */
+	role: JsLlmChatMessageRole;
+	/**
+	 * 消息正文文本。
+	 */
+	content: string;
+	/**
+	 * tool message 对应的 tool_call_id（OpenAI 兼容协议）。
+	 */
+	toolCallId?: string;
+	/**
+	 * system/tool 消息可选名称（例如 agentLabel / tool 名称）。
+	 */
+	name?: string;
+	/**
+	 * assistant 触发的工具调用列表（OpenAI 兼容协议）。
+	 */
+	toolCalls?: JsLlmChatToolCall[];
+};
+/**
+ * `chatInSession` 实时输出事件（用于应用侧接收流式信息）。
+ *
+ * 关键约定：
+ * - `messageFileName/thinkFileName` 与会话目录落盘文件名一致（例如 `0005-O-AS-140236.txt` / `0005-O-AS-140236.think`）。
+ * - `*_soFar` 字段表示“当前轮已输出的累计内容”（便于增量渲染）。
+ */
+export type JsLlmChatCliOutputEvent = {
+	type: "assistant_start";
+	sessionDir: string;
+	sessionName: string;
+	seq: number;
+	direction: "O";
+	role: "assistant";
+	messageFileName: string;
+	messageFilePath: string;
+	thinkFileName: string;
+	thinkFilePath: string;
+	attempt: number;
+} | {
+	type: "assistant_text";
+	sessionDir: string;
+	sessionName: string;
+	seq: number;
+	direction: "O";
+	role: "assistant";
+	messageFileName: string;
+	messageFilePath: string;
+	chunkText: string;
+	textSoFar: string;
+	attempt: number;
+} | {
+	type: "assistant_think";
+	sessionDir: string;
+	sessionName: string;
+	seq: number;
+	direction: "O";
+	role: "assistant";
+	thinkFileName: string;
+	thinkFilePath: string;
+	chunkThink: string;
+	thinkSoFar: string;
+	attempt: number;
+} | {
+	type: "assistant_tool_call";
+	sessionDir: string;
+	sessionName: string;
+	seq: number;
+	direction: "O";
+	role: "assistant";
+	messageFileName: string;
+	messageFilePath: string;
+	toolCall: JsLlmChatToolCall;
+	toolCallsSoFar: JsLlmChatToolCall[];
+	attempt: number;
+} | {
+	type: "assistant_end";
+	sessionDir: string;
+	sessionName: string;
+	seq: number;
+	direction: "O";
+	role: "assistant";
+	messageFileName: string;
+	messageFilePath: string;
+	thinkFileName: string;
+	thinkFilePath: string;
+	text: string;
+	think: string;
+	toolCalls: JsLlmChatToolCall[];
+	usage?: {
+		promptTokens?: number;
+		completionTokens?: number;
+		totalTokens?: number;
+	};
+	attempt: number;
+};
+/**
+ * `chatInSession` 入参（会话引擎）。
+ */
+export type JsLlmRunChatCliOptions = {
+	/**
+	 * 初始化 LLM 配置。
+	 */
+	init: JsLlmInitOptions;
+	/**
+	 * 可选：用于会话 front matter 的 user 字段。
+	 */
+	user?: string;
+	/**
+	 * 可选：全局 agent 名称或路径（按 `public/agents` 规则解析）。
+	 */
+	globalAgent?: string;
+	/**
+	 * 工作区根目录：
+	 * - 用于解析 `public/agents/*` 的系统提示词与 agent 文件
+	 * - 也是内置 `shell` 工具的执行 cwd
+	 */
+	workspaceRoot: string;
+	/**
+	 * 会话落盘根目录：
+	 * - 会在其下创建 `YYYYMMDD_HHMMSS/` 会话目录与 `latest` 软链
+	 */
+	sessionRootDir: string;
+	/**
+	 * 可选：用户输入消息（优先级最高）。
+	 * - 未提供时，在 stdin 非 TTY 的情况下读取 stdin
+	 */
+	messageArg?: string;
+	/**
+	 * 可选：系统提示词。
+	 * - 内联文本：直接传字符串
+	 * - 引用文件/agent：以 `@` 开头，例如 `@公共智能体` 或 `@./path/to/prompt.txt`
+	 */
+	systemPrompt?: string;
+	/**
+	 * 可选：指定会话目录名（相对于 `sessionRootDir` 的相对子目录）。
+	 */
+	sessionArg?: string;
+	/**
+	 * 是否将输出写入控制台（stdout/stderr）。
+	 * - 默认 true（保持 CLI 行为）
+	 */
+	consoleOutput?: boolean;
+	/**
+	 * 实时输出回调：用于获取流式 text/think/tool_call 等事件，便于应用侧渲染/采集。
+	 */
+	onEvent?: (event: JsLlmChatCliOutputEvent) => void | Promise<void>;
+};
+/**
+ * 会话模式聊天（落盘 + 工具循环 + 流式输出）。
+ *
+ * 多轮会话通过“会话目录落盘 + 下次加载历史”实现；详见 README 与 `dist/types.d.ts` 注释说明。
+ */
+export declare const chatInSession: (options: JsLlmRunChatCliOptions) => Promise<void>;
+/**
+ * 单轮文本生成（不落盘、不启用工具）。
+ *
+ * @example
+ * ```js
+ * const { chatDirectText } = require("@mmteam/jsllm");
+ *
+ * const text = await chatDirectText(
+ *   {
+ *     providerName: "gemini",
+ *     apiType: "gemini",
+ *     apiKey: process.env.GEMINI_API_KEY,
+ *     model: "gemini-1.5-pro",
+ *     apiVersion: "v1beta",
+ *   },
+ *   [{ role: "user", content: "Summarize: ..." }],
+ * );
+ * console.log(text);
+ * ```
+ */
+export declare const chatDirectText: (init: JsLlmInitOptions, messages: JsLlmChatMessage[]) => Promise<string>;
+
+export {};