minimal-agent 0.5.3 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "最小化 Agent 系统 —— 10 工具 + 插件系统 + workflow DSL + 自动压缩 + OpenAI 兼容 + Ink TUI；NodeNext + tsc 原地编译，dev 用 Bun .ts、install 用 Node .js（学习/教学用）",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",

package/src/context/archive.js

@@ -0,0 +1,117 @@
+/**
+ * ============================================================
+ *  src/context/archive.ts —— /new 自动归档历史对话
+ * ------------------------------------------------------------
+ *  做的事：
+ *    `/new` 清空上下文前，先把当前对话历史落盘到 archive 目录，
+ *    供后续 `/list-archive`、`/restore <id>` 查看 / 找回。
+ *
+ *  文件路径：
+ *    <MINIMAL_AGENT_HOME ?? ~>/.minimal-agent/archive/<cwd-hash>/<ISO-timestamp>.json
+ *    - cwd-hash：当前工作目录 sha1 前 12 位（避免不同项目 archive 串台）
+ *    - timestamp：new Date().toISOString().replace(/:/g, '-')（Windows 不允许冒号）
+ *
+ *  存储格式：
+ *    { updatedAt: number; messages: Message[] }
+ *
+ *  抉择：
+ *    - 仅含 system 消息（空对话）跳过写入，返回空字符串
+ *    - 失败由调用方 try/catch 吞掉，本模块不做 stderr（保持纯函数语义）
+ *    - 损坏文件在 listArchives 中静默 skip
+ *    - 通过 MINIMAL_AGENT_HOME 环境变量让测试切到临时目录，避免污染真实 ~/.minimal-agent
+ * ============================================================
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getWorkingDir } from '../bootstrap/workingDir.js';
+/** 解析 archive 根目录，支持 MINIMAL_AGENT_HOME 测试覆盖 */
+function agentHome() {
+    return process.env.MINIMAL_AGENT_HOME ?? homedir();
+}
+function archiveDir(cwd) {
+    const hash = createHash('sha1').update(cwd).digest('hex').slice(0, 12);
+    return join(agentHome(), '.minimal-agent', 'archive', hash);
+}
+/**
+ * 归档当前 messages 到 archive 目录。
+ *
+ * @returns archive id（成功）或空字符串（无内容跳过）
+ *
+ * 行为：
+ *  - messages 为空 / 仅含 system role → 跳过，返回 ''
+ *  - 写入失败抛错（调用方负责吞）
+ */
+export async function archiveCurrent(messages) {
+    const nonSystem = messages.filter((m) => m.role !== 'system');
+    if (nonSystem.length === 0)
+        return '';
+    const dir = archiveDir(getWorkingDir());
+    await mkdir(dir, { recursive: true });
+    const id = new Date().toISOString().replace(/:/g, '-');
+    const path = join(dir, `${id}.json`);
+    await writeFile(path, JSON.stringify({ updatedAt: Date.now(), messages }), 'utf8');
+    return id;
+}
+/**
+ * 列出当前 cwd 下所有归档，最新优先（按文件 mtime 倒序）。
+ *
+ * 损坏 / 无法解析的文件会被静默跳过——不影响其它条目展示。
+ * 目录不存在视作空列表。
+ */
+export async function listArchives() {
+    const dir = archiveDir(getWorkingDir());
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const id = name.slice(0, -'.json'.length);
+        const fpath = join(dir, name);
+        try {
+            const st = await stat(fpath);
+            const raw = await readFile(fpath, 'utf8');
+            const data = JSON.parse(raw);
+            if (!Array.isArray(data.messages))
+                continue;
+            const firstUser = data.messages.find((m) => m.role === 'user');
+            const preview = firstUser && typeof firstUser.content === 'string'
+                ? firstUser.content.replace(/\s+/g, ' ').slice(0, 80)
+                : '';
+            entries.push({
+                id,
+                updatedAt: st.mtimeMs,
+                msgCount: data.messages.length,
+                firstUserPreview: preview,
+            });
+        }
+        catch {
+            // 损坏文件静默 skip
+        }
+    }
+    return entries.sort((a, b) => b.updatedAt - a.updatedAt);
+}
+/**
+ * 按 id 恢复归档。
+ *
+ * @returns messages 数组（成功）；找不到 / 损坏 / messages 非数组 → null
+ */
+export async function restoreArchive(id) {
+    const dir = archiveDir(getWorkingDir());
+    const path = join(dir, `${id}.json`);
+    try {
+        const raw = await readFile(path, 'utf8');
+        const data = JSON.parse(raw);
+        return Array.isArray(data.messages) ? data.messages : null;
+    }
+    catch {
+        return null;
+    }
+}

package/src/context/persistContext.js

@@ -25,6 +25,7 @@
 import { mkdir, readFile, readdir, rmdir, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { getWorkingDir } from '../bootstrap/workingDir.js';
+import { archiveCurrent } from './archive.js';
 import { sessionFileFor } from './sessionPath.js';
 /** 上下文文件路径（按工作目录隔离，可用环境变量覆盖） */
 export function getContextPath() {
@@ -76,6 +77,21 @@ export async function saveContext(messages, file) {
  */
 export async function clearContext(file) {
     const target = file ?? getContextPath();
+    // 归档当前历史（仅含 system 的空对话会跳过）；失败不阻塞 clear
+    // 显式传 file（HTTP 模式 / 测试覆盖路径）或 MINIMAL_AGENT_CONTEXT_FILE 激活时
+    // 跳过 archive：这两种语义下 caller 自管路径，不应污染默认 archive 目录
+    const skipArchive = file !== undefined || !!process.env.MINIMAL_AGENT_CONTEXT_FILE;
+    if (!skipArchive) {
+        try {
+            const current = await loadContext(target);
+            if (current && current.length > 0) {
+                await archiveCurrent(current);
+            }
+        }
+        catch (e) {
+            process.stderr.write(`[minimal-agent] archive 失败（继续 clear）：${e.message}\n`);
+        }
+    }
     try {
         await unlink(target);
     }

package/src/context/sessionPath.js

@@ -6,10 +6,16 @@
  *    把当前工作目录编码为 ~/.minimal-agent/sessions/<encoded>.json
  *    的文件名，让不同项目目录的对话历史互不覆盖。
  *
- *  命名规则：
- *    <sanitized-path>-<6-hex-hash>.json
+ *  命名规则（v2 加 sessionId 后）：
+ *    <sanitized-path>-<6-hex-hash>--<sessionId>.json
  *      sanitized：路径归一化后只保留 [a-z0-9-]，最长 80 字符
  *      hash    ：原始路径 sha1 前 6 位，防 sanitize 后碰撞
+ *      sessionId：v2 多 session 支持；默认 'default'
+ *
+ *    向后兼容：sessionId='default' 时，新文件名 `<sanitized>-<hash>--default.json`
+ *    与旧文件名 `<sanitized>-<hash>.json` 都可能存在。resolveSessionFile()
+ *    优先返新路径，新路径不存在但旧路径存在时回退到旧路径，保证老用户的
+ *    last-context 无缝继承。
  *
  *  迁移：
  *    旧版 ~/.minimal-agent/last-context.json 启动时一次性 rename 到
@@ -20,8 +26,29 @@ import { createHash } from 'node:crypto';
 import { mkdir, rename, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-/** 把 cwd 编码成会话文件绝对路径 */
-export function sessionFileFor(cwd) {
+const DEFAULT_SESSION_ID = 'default';
+/**
+ * 把 cwd + sessionId 编码成会话文件绝对路径。
+ *
+ * @param cwd 工作目录
+ * @param sessionId 多 session 支持的 id；缺省 'default'
+ *
+ * 注意：'default' 调用走新格式 `<base>--default.json`。如果磁盘上只有
+ * 旧格式 `<base>.json`（v1 历史文件），需要用 resolveSessionFile()
+ * 拿到实际存在的路径用于 load。
+ */
+export function sessionFileFor(cwd, sessionId = DEFAULT_SESSION_ID) {
+    const normalized = resolve(cwd).replace(/\\/g, '/').toLowerCase();
+    const sanitized = normalized
+        .replace(/:/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 80);
+    const hash = createHash('sha1').update(normalized).digest('hex').slice(0, 6);
+    return join(homedir(), '.minimal-agent', 'sessions', `${sanitized}-${hash}--${sessionId}.json`);
+}
+/** 旧格式（v1，不带 `--<id>` 后缀）—— 仅 'default' session 可能存在 */
+function legacySessionFileFor(cwd) {
     const normalized = resolve(cwd).replace(/\\/g, '/').toLowerCase();
     const sanitized = normalized
         .replace(/:/g, '')
@@ -31,6 +58,34 @@ export function sessionFileFor(cwd) {
     const hash = createHash('sha1').update(normalized).digest('hex').slice(0, 6);
     return join(homedir(), '.minimal-agent', 'sessions', `${sanitized}-${hash}.json`);
 }
+/**
+ * 解析 cwd + sessionId 对应的实际存在的会话文件路径。
+ *
+ *  - 新格式（带 `--<id>`）存在 → 返回新路径
+ *  - 仅 sessionId='default' 且新路径不存在但旧路径（不带 `--`）存在 → 返回旧路径
+ *  - 都不存在 → 返回新路径（让调用方按新格式 create）
+ */
+export async function resolveSessionFile(cwd, sessionId = DEFAULT_SESSION_ID) {
+    const fresh = sessionFileFor(cwd, sessionId);
+    try {
+        await stat(fresh);
+        return fresh;
+    }
+    catch {
+        // 新路径不存在
+    }
+    if (sessionId === DEFAULT_SESSION_ID) {
+        const legacy = legacySessionFileFor(cwd);
+        try {
+            await stat(legacy);
+            return legacy;
+        }
+        catch {
+            // 旧路径也不存在
+        }
+    }
+    return fresh;
+}
 /**
  * 一次性把旧版 ~/.minimal-agent/last-context.json 迁到当前 cwd 对应的
  * 会话文件。

package/src/context/sessionRegistry.js

@@ -0,0 +1,104 @@
+/**
+ * ============================================================
+ *  src/context/sessionRegistry.ts —— 同 cwd 多 session 注册表
+ * ------------------------------------------------------------
+ *  做的事：
+ *    一个工作目录下可以有多个并行 session（id = 任意字符串），
+ *    每次只激活一个。active 信息存 ~/.minimal-agent/active-sessions.json，
+ *    键是 cwd 的 sha1[:12]，值是当前激活的 session id 字符串。
+ *
+ *  文件路径：
+ *    <MINIMAL_AGENT_HOME ?? ~>/.minimal-agent/active-sessions.json
+ *    <MINIMAL_AGENT_HOME ?? ~>/.minimal-agent/sessions/<cwd-hash>--<id>.json
+ *      （新格式；旧格式 <cwd-hash>.json 视作 id='default' 兼容）
+ *
+ *  抉择：
+ *    - active 文件 atomic write（写 .tmp + rename）—— 防止跨进程并发写时部分写入
+ *    - sessionId 为字符串，'default' 是约定的默认值（无 active 时返回它）
+ *    - listSessions 同时扫新旧格式，保证迁移期不丢
+ * ============================================================
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** 解析根目录，支持 MINIMAL_AGENT_HOME 测试覆盖 */
+function agentHome() {
+    return process.env.MINIMAL_AGENT_HOME ?? homedir();
+}
+function agentDir() {
+    return join(agentHome(), '.minimal-agent');
+}
+function activeFilePath() {
+    return join(agentDir(), 'active-sessions.json');
+}
+function sessionsDirPath() {
+    return join(agentDir(), 'sessions');
+}
+function cwdHash(cwd) {
+    return createHash('sha1').update(cwd).digest('hex').slice(0, 12);
+}
+async function loadActiveMap() {
+    try {
+        const raw = await readFile(activeFilePath(), 'utf8');
+        const data = JSON.parse(raw);
+        if (data && typeof data === 'object' && !Array.isArray(data)) {
+            return data;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * 获取当前 cwd 的激活 session id。
+ * 无记录 → 返回 'default'。
+ */
+export async function getActiveSession(cwd) {
+    const map = await loadActiveMap();
+    return map[cwdHash(cwd)] ?? 'default';
+}
+/**
+ * 设置当前 cwd 的激活 session id。
+ *
+ * 写入策略：先写 <target>.tmp，再原子 rename 到 target；
+ * 即使被中断也只会留临时文件，不破坏 target。
+ */
+export async function setActiveSession(cwd, sessionId) {
+    const map = await loadActiveMap();
+    map[cwdHash(cwd)] = sessionId;
+    await mkdir(agentDir(), { recursive: true });
+    const target = activeFilePath();
+    const tmp = `${target}.tmp`;
+    await writeFile(tmp, JSON.stringify(map), 'utf8');
+    await rename(tmp, target);
+}
+/**
+ * 列出当前 cwd 下所有 session id（含 'default'）。
+ *
+ * 扫描规则：
+ *  - 新格式 `<hash>--<id>.json` → 提取 id
+ *  - 旧格式 `<hash>.json` → 视作 'default'
+ *  - 都没有 → 返回 ['default']（让 UI 默认能 list 出至少一项）
+ */
+export async function listSessions(cwd) {
+    const dir = sessionsDirPath();
+    const hash = cwdHash(cwd);
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return ['default'];
+    }
+    const prefix = `${hash}--`;
+    const ids = names
+        .filter((n) => n.startsWith(prefix) && n.endsWith('.json'))
+        .map((n) => n.slice(prefix.length, -'.json'.length));
+    const legacy = `${hash}.json`;
+    if (names.includes(legacy) && !ids.includes('default')) {
+        ids.unshift('default');
+    }
+    return ids.length > 0 ? ids : ['default'];
+}