@mmteam/jsllm 0.1.7 → 0.1.13

package/README.md

@@ -27,10 +27,10 @@ npm i @mmteam/jsllm
 ### CommonJS（推荐）
 ```js
 const path = require("node:path");
-const { runChatCliSession } = require("@mmteam/jsllm");
+const { chatInSession } = require("@mmteam/jsllm");
 
 async function main() {
-  await runChatCliSession({
+  await chatInSession({
     init: {
       providerName: "openai",
       apiType: "openai",
@@ -59,7 +59,7 @@ main().catch((err) => {
 ```js
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
-const { streamChatText } = require("@mmteam/jsllm");
+const { chatDirectText } = require("@mmteam/jsllm");
 ```
 
 ## API
@@ -68,7 +68,7 @@ const { streamChatText } = require("@mmteam/jsllm");
 详细参数、类型与中文说明：请参考 `node_modules/@mmteam/jsllm/dist/types.d.ts`（本仓库构建产物对应 `projects/jsllm/codex-zf/dist/types.d.ts`）。
 
 ### 如何选择？
-| 能力 | `streamChatText` | `runChatCliSession` |
+| 能力 | `chatDirectText` | `chatInSession` |
 |---|---|---|
 | 目标 | 单轮生成（返回文本） | 会话引擎（落盘 + 工具循环 + 流式输出） |
 | 输入 | 调用方提供 `messages` | `messageArg` 或 stdin；并自动加载会话历史 |
@@ -76,12 +76,12 @@ const { streamChatText } = require("@mmteam/jsllm");
 | 工具 | 不启用、不执行 | 内置 `shell`（模型触发时执行并回填） |
 | 适用场景 | 摘要/改写/分类等一次性生成；你自管存储 | CLI/交互式场景；需要可追溯、可续写会话 |
 
-### `streamChatText(init, messages): Promise<string>`
+### `chatDirectText(init, messages): Promise<string>`
 - 用途：不落盘、不启用工具的“单轮文本生成”，返回最终聚合文本
 - 示例：
 ```js
-const { streamChatText } = require("@mmteam/jsllm");
-const text = await streamChatText(
+const { chatDirectText } = require("@mmteam/jsllm");
+const text = await chatDirectText(
   {
     providerName: "gemini",
     apiType: "gemini",
@@ -95,12 +95,14 @@ const text = await streamChatText(
 console.log(text);
 ```
 
-### `runChatCliSession(options): Promise<void>`
+### `chatInSession(options): Promise<void>`
 - 用途：执行一次“CLI 式会话主循环”（会话落盘 + 流式输出 + 工具循环）
 - 重要参数：
   - `workspaceRoot`：工作区根目录（用于解析 `public/agents`，以及工具执行 cwd）
   - `sessionRootDir`：会话根目录（会在其下创建会话目录与 `latest` 软链）
   - `systemPrompt`：支持内联文本或 `@` 引用文件/agent 名称（见下方说明）
+  - `consoleOutput`：是否写入 stdout/stderr（默认 `true`）
+  - `onEvent`：实时输出回调（区分正常回复 text 与 think，并携带与落盘一致的文件名/路径）
 
 ## 供应商与配置
 
@@ -150,7 +152,7 @@ init: {
 }
 ```
 
-## 会话落盘说明（`runChatCliSession`）
+## 会话落盘说明（`chatInSession`）
 - 会话根目录：由 `sessionRootDir` 指定
 - 会话目录：`YYYYMMDD_HHMMSS/`
 - `latest`：会话根目录下的软链，指向最近一次有效会话目录
@@ -158,7 +160,31 @@ init: {
 - 消息文件：按序号落盘，支持恢复历史继续会话
 - `.think`：当模型输出 reasoning/think 时，会额外落盘同名 `.think` 文件
 
-## systemPrompt / globalAgent（`runChatCliSession`）
+## 实时回调（`chatInSession.onEvent`）
+你可以通过 `onEvent` 在应用侧接收流式输出，并区分正常回复与 think（事件中携带与落盘一致的文件名）：
+```js
+await chatInSession({
+  /* ... */,
+  consoleOutput: false,
+  onEvent(e) {
+    if (e.type === "assistant_text") {
+      // e.textSoFar：当前轮累计的“正常回复”
+    }
+    if (e.type === "assistant_think") {
+      // e.thinkSoFar：当前轮累计的 think/reasoning
+    }
+  },
+});
+```
+
+## 多轮会话（`chatInSession`）
+`chatInSession` 的多轮能力通过“会话目录落盘 + 下次加载历史”实现：每次调用会读取目标会话目录的历史消息并继续追加写入。
+
+- 默认续写上一会话（推荐）：多次调用时保持相同的 `sessionRootDir`，且不传 `sessionArg`，库会自动复用 `latest` 指向的会话目录。
+- 固定到指定会话：传入 `sessionArg: "my-session"`（相对 `sessionRootDir` 的相对子目录），每次调用都使用同一个值，即可稳定续写同一会话。
+- systemPrompt 建议：同一会话通常只在“第一轮”设置 `systemPrompt`；后续轮次不再传（或改用 `sessionArg` 固定会话），避免触发创建新会话导致上下文断裂。
+
+## systemPrompt / globalAgent（`chatInSession`）
 - `systemPrompt` 支持两种形式：
   - 内联文本：直接传字符串
   - 引用文件/agent：以 `@` 开头，例如 `@公共智能体` 或 `@./path/to/prompt.txt`
@@ -169,7 +195,7 @@ init: {
 - `MCHAT_DEBUG`：Gemini provider debug 输出（`true/1` 开启）
 
 ## 安全说明（工具）
-`runChatCliSession` 内置 `shell` 工具：当模型触发工具调用时，会在 `workspaceRoot` 下通过 `bash -lc` 执行命令并回填输出。请仅在可信环境中使用，并确保运行账号权限可控。
+`chatInSession` 内置 `shell` 工具：当模型触发工具调用时，会在 `workspaceRoot` 下通过 `bash -lc` 执行命令并回填输出。请仅在可信环境中使用，并确保运行账号权限可控。
 
 ## 开发
 > 下述为仓库开发者使用；下游项目不需要执行 build。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmteam/jsllm",
-  "version": "0.1.7",
+  "version": "0.1.13",
   "description": "MM Team LLM library (providers + chat/session runner)",
   "type": "module",
   "main": "./dist/index.cjs",