mm_llm 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 qww
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,201 @@
-# Temporary Holding Version
+# mm_llm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+一个适用于**多用户、多智能体、多会话、多工具**的大模型调用模块，方便打造多智能体系统。
+
+- 基于 OpenAI 兼容接口，可对接任意兼容服务（OpenAI、DeepSeek 等）
+- 消息、智能体、工具、用户、选项、配额全部经由可替换的存储层读写
+- 内置内存存储（`Memory`）与 SQLite 存储（`Sqlite`），数据按 `(user_id, agent_id, session_id)` 三元组分区，多用户多智能体互不串台
+- 内置自动工具调用循环、鉴权与配额准入、系统提示固化等能力
+- 关键步骤均为可覆写方法，二次开发者可按需定制任意一环
+
+## 环境要求
+
+- Node.js `>= 22.5.0`（`Sqlite` 依赖内置的 `node:sqlite`）
+- 仅使用 `Memory` 时对 Node 版本无额外要求
+
+## 安装
+
+```bash
+npm install mm_llm
+```
+
+## 快速开始
+
+```js
+const { LLM } = require('mm_llm');
+
+const llm = new LLM({
+  api_key: 'sk-xxx',
+  base_url: 'https://api.deepseek.com/v1',
+  model: 'deepseek-chat'
+});
+
+// 配置智能体与用户
+llm.getStore().setAgent(1, { system_prompt: '你是一个简洁的助手' });
+llm.getStore().setQuota(9, 100); // 默认按配额准入，未设置配额的用户会被拒绝，需先开户
+
+// 一轮对话
+const reply = await llm.main(
+  { user_id: 9 },
+  { agent_id: 1, session_id: 100, content: '你好' }
+);
+console.log(reply.content);
+```
+
+## 核心概念
+
+### LLM
+
+大模型调用类。直接实例化即可使用：默认从内存存储读取会话消息、智能体与用户配置，经 OpenAI 兼容接口完成对话，并把助手回复写回存储。
+
+调用链路：`main` → 鉴权 → 配额准入 → 写入用户输入 → `send` → 装配消息 / 工具 / 选项 → `post` → 写回助手回复。
+
+### 存储（Store）
+
+存储负责六类数据，`Memory` 与 `Sqlite` 实现同一契约、方法一一对应。
+
+| 数据 | 键 | 说明 |
+| --- | --- | --- |
+| 会话消息 | `(user_id, agent_id, session_id)` | 三元组分区，避免串台 |
+| 智能体配置 | `agent_id` | `{ system_prompt, tools, users }` |
+| 工具定义 | `tool_name` | 提交给模型的函数声明，供智能体按名引用 |
+| 用户信息 | `user_id` | `{ name, profile }`，用于组装系统提示词 |
+| 智能体选项 | `(user_id, agent_id)` | 同一用户对不同智能体可各有选项 |
+| 用户配额 | `user_id` | 剩余配额，未设置的用户返回 `undefined`，视为无配额而被拒绝 |
+
+**LLM 依赖的存储契约**（实现以下方法即可自定义存储）：
+
+```js
+getMessages(user_id, agent_id, session_id) -> Array
+setMessages(user_id, agent_id, session_id, messages) -> store
+addMessage(user_id, agent_id, session_id, message) -> store
+delSession(user_id, agent_id, session_id) -> Boolean
+getAgent(agent_id) -> { system_prompt, tools, users }
+getToolSchema(tool_name) -> Object
+setToolSchema(tool_name, schema) -> store
+getUser(user_id) -> { name, profile }
+getOptions(user_id, agent_id) -> Object
+getQuota(user_id) -> Number   // 未设置时返回 undefined，视为无配额
+```
+
+`Memory` / `Sqlite` 在此之上还提供配置写入方法：`addMessage` / `addMessages`、`setMessages`、`setAgent` / `delAgent`、`setToolSchema` / `getToolSchema` / `delToolSchema` / `listToolSchemas` / `clearToolSchemas`、`setUser` / `delUser`、`setOptions` / `delOptions`、`setQuota` / `gainQuota` / `delQuota`、`countMessages` / `hasSession` / `listSessions`、`clear`（`Sqlite` 另有 `close`）。
+
+> `setAgent` / `setUser` / `setOptions` 均按字段合并，重复设置只覆盖传入的字段。
+
+### 使用 SQLite 持久化
+
+```js
+const { LLM, Sqlite } = require('mm_llm');
+
+const llm = new LLM({
+  api_key: 'sk-xxx',
+  store: new Sqlite('llm.db') // 缺省为 ':memory:'，进程退出即丢失
+});
+```
+
+## 配置项
+
+`new LLM(config)` 可传字段如下（`LLM.config` 为默认值）：
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `api_key` | String | `''` | 服务密钥，缺失时调用抛异常 |
+| `base_url` | String | `https://api.openai.com/v1` | 兼容接口地址 |
+| `model` | String | `gpt-4o` | 模型名 |
+| `temperature` | Number | `0.7` | 采样温度 |
+| `max_tokens` | Number | `8192` | 单次最大生成 token |
+| `stream` | Boolean | `false` | 是否流式返回 |
+| `system_prompt` | String | `''` | 兜底系统提示词 |
+| `max_rounds` | Number | `8` | 工具调用最大轮数 |
+| `auth_default` | String | `allow` | 智能体未限定 `users` 时的默认准入策略 |
+| `store` | Object | `null` | 存储实例，缺省使用 `Memory` |
+
+## API
+
+### 实例方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `main(params, ctx, options)` | 执行一次对话。`ctx` 含 `user_id`；`params` 含 `agent_id` / `session_id` / `content`；`options` 为本次调用选项，优先级最高 |
+| `send(user_id, agent_id, session_id)` | 装配上下文后调用模型，`main` 内部使用 |
+| `setStore(store)` / `getStore()` | 设置 / 获取存储实例 |
+| `resetSession(user_id, agent_id, session_id)` | 清空该会话全部消息，下次调用按最新配置重建 system 消息 |
+| `setTool(name, handler)` / `getTool` / `delTool` / `listTools` / `clearTools` | 注册 / 查询 / 删除 / 列举 / 清空工具执行函数 |
+| `checkAuth(user_id, agent_id)` | 鉴权，可覆写 |
+| `checkQuota(user_id, agent_id)` | 配额准入，可覆写 |
+| `getSystemPrompt` / `getBasePrompt` / `getHistory` / `getMessages` / `getOptions` / `getTools` | 数据装配，可覆写或经存储替换 |
+| `useTool(tool_name, params)` / `post(messages, tools, options)` | 工具执行与模型调用，可覆写 |
+
+### 选项优先级
+
+由低到高：实例默认配置 < `(user_id, agent_id)` 级选项 < 本次调用选项。
+
+其中 `(user_id, agent_id)` 级选项的 `system_prompt` 字段存在时，即代替智能体自身的系统提示词。本次调用选项借助 `AsyncLocalStorage` 承载，同一实例并发处理多用户时互不影响。
+
+### 工具调用
+
+工具的执行函数注册在 LLM 实例上（`setTool`），工具定义存于存储（`setToolSchema`），两者按同名关联；智能体通过 `agent.tools`（工具名数组）按名引用，引用的工具名未在存储中定义时抛异常。模型请求工具时由框架自动执行、回填结果并继续对话，直到模型不再请求工具或达到 `max_rounds`。
+
+```js
+llm.setTool('get_weather', (params) => ({ city: params.city, weather: '晴' }));
+llm.getStore().setToolSchema('get_weather', {
+  type: 'function',
+  function: {
+    name: 'get_weather',
+    description: '查询指定城市的天气',
+    parameters: {
+      type: 'object',
+      properties: { city: { type: 'string' } },
+      required: ['city']
+    }
+  }
+});
+llm.getStore().setAgent(2, { system_prompt: '你会按需调用工具', tools: ['get_weather'] });
+```
+
+### 鉴权与配额
+
+调用前先鉴权、再准入，任一不通过即抛异常，既不发送请求也不写入消息。
+
+**鉴权**：按智能体配置中的 `users`（允许调用的用户ID数组）判定：
+
+- `users` 存在：仅列表内用户可调用，空数组表示谁都不能用；
+- `users` 缺省：由 `auth_default` 决定，`'allow'` 放行（默认）、`'deny'` 拒绝。
+
+**配额**：默认可覆写的 `checkQuota` 按用户配额判定，剩余配额大于 0 才放行；未设置配额（返回 `undefined`）视为无配额，同样拒绝。配额扣减等结算动作由二次开发者自行处理。
+
+### 系统提示固化
+
+系统提示（基础提示 + 用户信息段）只在会话首次调用时固化为一条 `system` 消息并置于最前，之后每轮直接从历史读取，使历史前缀保持稳定以命中缓存。需要让新配置生效时调用 `resetSession` 重建会话。
+
+## 扩展方式
+
+1. **注入存储**：`new LLM({ store })`，传入实现上述契约的存储，消息、选项、提示、工具即改由该存储提供；
+2. **覆写方法**：子类覆写 `getHistory` / `getOptions` / `getSystemPrompt` / `getTools` / `useTool` / `post` / `checkAuth` / `checkQuota`，即可自定义任意一步的数据来源与行为；
+3. **替换工具实现**：通过 `setTool` 注册的 `handler` 按名覆盖。
+
+## 示例
+
+`example` 目录提供九个可独立运行的示例（`demo1.js` ~ `demo9.js`），由 `example/demo.js` 依次调用，均请求真实接口：
+
+```bash
+npm run demo
+```
+
+| 文件 | 主题 |
+| --- | --- |
+| [demo1.js](example/demo1.js) | 基础对话 |
+| [demo2.js](example/demo2.js) | 多用户 / 多智能体隔离 |
+| [demo3.js](example/demo3.js) | 系统提示固化与重置会话 |
+| [demo4.js](example/demo4.js) | 工具调用 |
+| [demo5.js](example/demo5.js) | 用户选项与优先级 |
+| [demo6.js](example/demo6.js) | 替换存储 |
+| [demo7.js](example/demo7.js) | 用户配额准入 |
+| [demo8.js](example/demo8.js) | 连续多轮对话 |
+| [demo9.js](example/demo9.js) | 智能体鉴权 |
+
+运行前请在 `example/helpers.js` 中确认 `DEMO_API_KEY` 可用，并按需调整 `DEMO_BASE_URL` 与 `DEMO_MODEL`（默认对接 DeepSeek）。
+
+## License
+
+[ISC](LICENSE)

package/index.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const { LLM } = require('./lib/llm');
+const { Memory } = require('./lib/memory');
+const { Sqlite } = require('./lib/sqlite');
+const Admin = require('mm_corejs').Admin;
+
+let admin = new Admin();
+admin.setClass(LLM);
+
+/**
+ * 获取大模型实例
+ * @param {string} scope 作用域
+ * @param {Object} config 配置参数
+ * @returns {LLM} 大模型实例
+ */
+function llmAdmin(scope, config) {
+  if (!scope) {
+    scope = 'os';
+  }
+  return admin.get(scope, config);
+}
+
+module.exports = {
+  LLM,
+  Memory,
+  Sqlite,
+  admin,
+  llmAdmin
+};