codexmate 0.1.10 → 0.1.13

package/README.md

@@ -49,7 +49,7 @@
 
 Have you ever felt overwhelmed by managing multiple local AI agents? Each has its own config format, session storage, and skills directory.
 
-**Codex Mate** offers a unified control plane to bring order to the chaos. It's a local-first CLI + Web UI designed to manage [Codex](https://github.com/openai/codex), [Claude Code](https://github.com/anthropic-ai/claude-code), [OpenCode](https://opencode.ai/), KiloCode, and [OpenClaw](https://github.com/moeru-ai/openclaw) seamlessly.
+**Codex Mate** offers a unified control plane to bring order to the chaos. It's a local-first CLI + Web UI designed to manage [Codex](https://github.com/openai/codex), [Claude Code](https://github.com/anthropic-ai/claude-code), [OpenCode](https://opencode.ai/), KiloCode, [OpenClaw](https://github.com/moeru-ai/openclaw), and Pi seamlessly.
 
 ### What's So Special?
 
@@ -59,6 +59,7 @@ Unlike simple wrappers, Codex Mate acts as a **Local Agent Bridge**:
 - **Claude Provider Bridge**: Connect Claude Code to OpenAI Chat Completions-compatible providers and Ollama through the built-in local Claude-compatible proxy.
 - **OpenCode Provider Control**: Manage OpenCode provider/model selection with a CodexMate-owned provider store under `~/.codexmate`, projecting only the active provider into native OpenCode config to avoid polluting or deleting user-owned settings.
 - **KiloCode Config Bridge**: Configure KiloCode providers from the CLI or Web UI, writing to `~/.config/kilo/kilo.jsonc` while preserving stored API keys.
+- **Pi Provider Config**: Manage Pi providers from the Web UI with lossless round-trip writes to `~/.pi/agent/models.json`, auto-fetched remote model lists, and one-click default provider/model switching via `~/.pi/agent/settings.json`.
 - **Provider Health Cleanup**: Probe local Codex and Claude provider routes, surface failed configs in one modal, and bulk-clean selected broken providers without touching healthy or protected entries.
 - **Skills Marketplace**: A local-first market to share and import skills between different agent apps.
 - **Prompt File Editor**: Unified editor for global and project-level `CLAUDE.md` and `AGENTS.md` with auto-detection of project paths, plus a shared preset pool for reusable prompts.
@@ -70,7 +71,7 @@ Unlike simple wrappers, Codex Mate acts as a **Local Agent Bridge**:
 
 | Feature | Status | Description |
 | --- | --- | --- |
-| **Provider Management** | ✅ | Switch providers/models for Codex, Claude, OpenCode, KiloCode, and OpenClaw |
+| **Provider Management** | ✅ | Switch providers/models for Codex, Claude, OpenCode, KiloCode, OpenClaw, and Pi |
 | **Live Agent Sync** | ✅ | Real-time monitoring of Codex/Claude config & status |
 | **Session Browser** | ✅ | Search, preview, filter, and export sessions across Codex, Claude Code, Gemini CLI, CodeBuddy Code, and Pi |
 | **Usage Analytics** | ✅ | Visualize message trends and top projects |
@@ -80,6 +81,7 @@ Unlike simple wrappers, Codex Mate acts as a **Local Agent Bridge**:
 | **Claude Provider Bridge** | ✅ | Connect Claude Code to OpenAI Chat Completions-compatible providers and Ollama via the built-in Claude-compatible proxy |
 | **OpenCode Provider Store** | ✅ | Keep multiple OpenCode providers in `~/.codexmate` while projecting only the selected provider to native OpenCode config |
 | **KiloCode Config Bridge** | ✅ | Configure KiloCode through `codexmate kilo config` or the Web UI, writing provider URL/model/API key data to `~/.config/kilo/kilo.jsonc` |
+| **Pi Provider Config** | ✅ | Manage Pi providers in the Web UI writing to `~/.pi/agent/models.json` (unknown fields preserved) and switch the default provider/model in `~/.pi/agent/settings.json` |
 | **Provider Health Check** | ✅ | Probe local Codex/Claude provider routes, highlight failed configs, and bulk-remove selected broken providers safely |
 | **Prompt Templates** | ✅ | Reusable prompt plugins with variables |
 | **Prompt File Editor** | ✅ | Edit global and project-level CLAUDE.md / AGENTS.md with auto-detect, path switching, and a shared preset pool. Applying a preset only updates the editor; save manually to write the file. |
@@ -133,7 +135,7 @@ curl -fsSL https://raw.githubusercontent.com/SakuraByteCore/codexmate/main/scrip
 - **KiloCode**: `npm install -g @kilocode/cli` (`kilo` / `kilocode`)
 - **OpenCode**: install from the [official OpenCode docs](https://opencode.ai/)
 - **OpenClaw**: see the [OpenClaw repository](https://github.com/moeru-ai/openclaw)
-- **Pi**: sessions are discovered from `~/.pi/agent/sessions`
+- **Pi**: sessions are discovered from `~/.pi/agent/sessions`; provider config lives in `~/.pi/agent/models.json` and the default provider/model in `~/.pi/agent/settings.json`
 
 ---
 
@@ -184,10 +186,6 @@ Special thanks to all contributors for their contributions to Codex Mate ❤️
   <img src="https://contrib.rocks/image?repo=SakuraByteCore/codexmate" />
 </a>
 
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=SakuraByteCore/codexmate&type=Date)](https://star-history.com/#SakuraByteCore/codexmate&Date)
-
 ## License
 
 Apache-2.0

package/README.vi.md

@@ -41,7 +41,7 @@
 
 Bạn có bao giờ cảm thấy rối khi phải quản lý nhiều AI agent cục bộ? Mỗi tool lại có định dạng cấu hình, nơi lưu phiên và thư mục skill riêng.
 
-**Codex Mate** cung cấp một trung tâm điều khiển thống nhất để giải quyết sự hỗn loạn đó. Đây là CLI + Web UI ưu tiên cục bộ, được thiết kế để quản lý [Codex](https://github.com/openai/codex), [Claude Code](https://github.com/anthropic-ai/claude-code), [OpenCode](https://opencode.ai/), KiloCode và [OpenClaw](https://github.com/moeru-ai/openclaw) một cách liền mạch.
+**Codex Mate** cung cấp một trung tâm điều khiển thống nhất để giải quyết sự hỗn loạn đó. Đây là CLI + Web UI ưu tiên cục bộ, được thiết kế để quản lý [Codex](https://github.com/openai/codex), [Claude Code](https://github.com/anthropic-ai/claude-code), [OpenCode](https://opencode.ai/), KiloCode, [OpenClaw](https://github.com/moeru-ai/openclaw) và Pi một cách liền mạch.
 
 ### Điểm nổi bật
 
@@ -58,7 +58,8 @@ Khác với các wrapper đơn giản, Codex Mate hoạt động như một **Ag
 
 | Tính năng | Trạng thái | Mô tả |
 | --- | --- | --- |
-| **Quản lý Provider** | ✅ | Chuyển đổi provider/model cho Codex, Claude, OpenCode, KiloCode và OpenClaw |
+| **Quản lý Provider** | ✅ | Chuyển đổi provider/model cho Codex, Claude, OpenCode, KiloCode, OpenClaw và Pi |
+| **Cấu hình Provider Pi** | ✅ | Quản lý provider Pi trong Web UI, ghi vào `~/.pi/agent/models.json` (giữ nguyên các trường không nhận dạng được) và chuyển đổi provider/model mặc định trong `~/.pi/agent/settings.json` |
 | **Đồng bộ Agent trực tiếp** | ✅ | Giám sát cấu hình & trạng thái Codex/Claude theo thời gian thực |
 | **Trình duyệt phiên** | ✅ | Liệt kê, xem trước, lọc và xuất phiên (Codex/Claude/Gemini/CodeBuddy/Pi) |
 | **Phân tích sử dụng** | ✅ | Trực quan hóa xu hướng tin nhắn và dự án nổi bật |
@@ -118,7 +119,7 @@ curl -fsSL https://raw.githubusercontent.com/SakuraByteCore/codexmate/main/scrip
 - **KiloCode**: `npm install -g @kilocode/cli` (`kilo` / `kilocode`)
 - **OpenCode**: xem [tài liệu chính thức OpenCode](https://opencode.ai/)
 - **OpenClaw**: xem [kho lưu trữ OpenClaw](https://github.com/moeru-ai/openclaw)
-- **Pi**: phiên làm việc được phát hiện từ `~/.pi/agent/sessions`
+- **Pi**: phiên làm việc được phát hiện từ `~/.pi/agent/sessions`; cấu hình provider nằm ở `~/.pi/agent/models.json`, provider/model mặc định nằm ở `~/.pi/agent/settings.json`
 
 ---
 
@@ -167,10 +168,6 @@ Cảm ơn tất cả những người đóng góp cho Codex Mate ❤️
   <img src="https://contrib.rocks/image?repo=SakuraByteCore/codexmate" alt="Contributors" />
 </a>
 
-## Lịch sử Star
-
-[![Star History Chart](https://api.star-history.com/svg?repos=SakuraByteCore/codexmate&type=Date)](https://star-history.com/#SakuraByteCore/codexmate&Date)
-
 ## Giấy phép
 
 Apache-2.0

package/README.zh.md

@@ -48,7 +48,7 @@
 
 你是否曾因管理多个本地 AI 智能体而感到疲惫？每个工具都有自己的配置格式、会话存储和 Skills 目录。
 
-**Codex Mate** 提供了一个统一的控制平面，让混乱重归有序。这是一个本地优先的 CLI + Web UI，旨在无缝管理 [Codex](https://github.com/openai/codex)、[Claude Code](https://github.com/anthropic-ai/claude-code)、[OpenCode](https://opencode.ai/)、KiloCode 和 [OpenClaw](https://github.com/moeru-ai/openclaw)。
+**Codex Mate** 提供了一个统一的控制平面，让混乱重归有序。这是一个本地优先的 CLI + Web UI，旨在无缝管理 [Codex](https://github.com/openai/codex)、[Claude Code](https://github.com/anthropic-ai/claude-code)、[OpenCode](https://opencode.ai/)、KiloCode、[OpenClaw](https://github.com/moeru-ai/openclaw) 与 Pi。
 
 ### 有什么独特之处？
 
@@ -57,6 +57,7 @@
 - **OpenAI 兼容桥接**：通过归一化 Responses API，让 Codex 能够与任何支持 OpenAI 格式的 UI 配合使用；内建 Codex 转换会补齐并规范化 `User-Agent`、`Version`、`OpenAI-Beta`、`Originator` 等 Codex 指纹，对上游伪装为官方 Codex CLI 请求。
 - **Claude Provider 桥接**：通过内建本地 Claude 兼容代理，让 Claude Code 接入 OpenAI Chat Completions 兼容 provider 与 Ollama。
 - **OpenCode Provider 控制**：在 `~/.codexmate` 下维护 CodexMate 自有的 OpenCode 多 provider 存储，只将当前选中的 provider 投影到 OpenCode 原生配置，避免污染或误删用户已有配置。
+- **Pi Provider 配置**：在 Web UI 中管理 Pi 供应商，写入 `~/.pi/agent/models.json` 时无损保留未知字段，支持自动拉取远端模型列表，并可一键切换 `~/.pi/agent/settings.json` 中的默认供应商/模型。
 - **Provider 健康清理**：探测本地 Codex 与 Claude provider 路由，在同一个弹窗里集中展示失败配置，并批量清理已选坏配置，不影响正常或受保护项。
 - **Skills 市场**：本地优先的市场，支持在不同的智能体应用之间共享和导入 Skills。
 - **提示词文件编辑器**：统一编辑全局和项目级 `CLAUDE.md` 与 `AGENTS.md`，支持项目路径自动检测，并提供通用预设池复用 prompt。
@@ -68,7 +69,7 @@
 
 | 特性 | 状态 | 描述 |
 | --- | --- | --- |
-| **Provider 管理** | ✅ | 切换 Codex、Claude、OpenCode、KiloCode 和 OpenClaw 的 provider/model |
+| **Provider 管理** | ✅ | 切换 Codex、Claude、OpenCode、KiloCode、OpenClaw 与 Pi 的 provider/model |
 | **状态实时同步** | ✅ | 实时感知 Codex/Claude 的配置与运行状态变更 |
 | **会话浏览器** | ✅ | 跨 Codex、Claude Code、Gemini CLI、CodeBuddy Code 与 Pi 的本地会话进行检索、预览、筛选与导出 |
 | **Usage 统计** | ✅ | 可视化消息趋势与热门项目统计 |
@@ -77,6 +78,7 @@
 | **OpenAI 桥接** | ✅ | 将 Codex Responses API 转换为标准 OpenAI 格式，并在内建转换中附加/规范化 Codex 指纹 |
 | **Claude Provider 桥接** | ✅ | 通过内建 Claude 兼容代理，让 Claude Code 接入 OpenAI Chat Completions 兼容 provider 与 Ollama |
 | **OpenCode Provider 存储** | ✅ | 在 `~/.codexmate` 中保留多个 OpenCode provider，只将当前选中的 provider 投影到 OpenCode 原生配置 |
+| **Pi Provider 配置** | ✅ | 在 Web UI 中管理 Pi 供应商，写入 `~/.pi/agent/models.json`（未知字段无损保留），并切换 `~/.pi/agent/settings.json` 中的默认供应商/模型 |
 | **Provider 健康检查** | ✅ | 探测本地 Codex/Claude provider 路由，标记失败配置，并安全批量移除已选坏配置 |
 | **提示词模板** | ✅ | 支持变量的可复用提示词插件 |
 | **提示词文件编辑器** | ✅ | 编辑全局和项目级 CLAUDE.md / AGENTS.md，支持自动检测、路径切换与通用预设池。应用预设只更新编辑器，需手动保存才会写入文件。 |
@@ -130,7 +132,7 @@ curl -fsSL https://raw.githubusercontent.com/SakuraByteCore/codexmate/main/scrip
 - **KiloCode**: `npm install -g @kilocode/cli`（`kilo` / `kilocode`）
 - **OpenCode**: 参照 [OpenCode 官方文档](https://opencode.ai/) 安装
 - **OpenClaw**: 参见 [OpenClaw 仓库](https://github.com/moeru-ai/openclaw)
-- **Pi**: 会话从 `~/.pi/agent/sessions` 自动发现
+- **Pi**: 会话从 `~/.pi/agent/sessions` 自动发现；供应商配置位于 `~/.pi/agent/models.json`，默认供应商/模型位于 `~/.pi/agent/settings.json`
 
 ---
 
@@ -181,10 +183,6 @@ flowchart TD
   <img src="https://contrib.rocks/image?repo=SakuraByteCore/codexmate" />
 </a>
 
-## Star 历史
-
-[![Star History Chart](https://api.star-history.com/svg?repos=SakuraByteCore/codexmate&type=Date)](https://star-history.com/#SakuraByteCore/codexmate&Date)
-
 ## 开源协议
 
 Apache-2.0

package/cli/agents-files.js

@@ -14,7 +14,8 @@ function createAgentsFileController(deps = {}) {
         CLAUDE_DIR,
         CLAUDE_MD_FILE_NAME,
         readOpenclawAgentsFile,
-        readOpenclawWorkspaceFile
+        readOpenclawWorkspaceFile,
+        backupPromptBeforeWrite
     } = deps;
 
     if (!fs) throw new Error('createAgentsFileController 缺少 fs');
@@ -32,6 +33,7 @@ function createAgentsFileController(deps = {}) {
     if (typeof CLAUDE_MD_FILE_NAME !== 'string' || !CLAUDE_MD_FILE_NAME) throw new Error('createAgentsFileController 缺少 CLAUDE_MD_FILE_NAME');
     if (typeof readOpenclawAgentsFile !== 'function') throw new Error('createAgentsFileController 缺少 readOpenclawAgentsFile');
     if (typeof readOpenclawWorkspaceFile !== 'function') throw new Error('createAgentsFileController 缺少 readOpenclawWorkspaceFile');
+    if (typeof backupPromptBeforeWrite !== 'function' && typeof backupPromptBeforeWrite !== 'undefined') throw new Error('createAgentsFileController 备份回调无效');
 
     function resolveAgentsFilePath(params = {}) {
         const baseDir = typeof params.baseDir === 'string' && params.baseDir.trim()
@@ -40,6 +42,12 @@ function createAgentsFileController(deps = {}) {
         return path.join(baseDir, AGENTS_FILE_NAME);
     }
 
+    function sanitizeHistoryId(raw) {
+        const safe = typeof raw === 'string' ? raw.trim() : '';
+        if (!safe) return 'global';
+        return safe.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 64) || 'global';
+    }
+
     function validateAgentsBaseDir(filePath) {
         const dirPath = path.dirname(filePath);
         try {
@@ -152,6 +160,13 @@ function createAgentsFileController(deps = {}) {
         if (content.length > 2 * 1024 * 1024) {
             return { error: 'content too large (max 2MB)' };
         }
+        if (typeof backupPromptBeforeWrite === 'function') {
+            var bucket = resolved.isProject
+                ? 'claude-project_' + sanitizeHistoryId(resolved.projectPath)
+                : 'claude-global';
+            backupPromptBeforeWrite(bucket, filePath);
+            resolved.historyBucket = bucket;
+        }
         var lineEnding = params.lineEnding === '\r\n' ? '\r\n' : '\n';
         var normalized = normalizeLineEnding(content, lineEnding);
         var finalContent = ensureUtf8Bom(normalized);
@@ -159,6 +174,7 @@ function createAgentsFileController(deps = {}) {
             ensureDir(path.dirname(filePath));
             fs.writeFileSync(filePath, finalContent, 'utf-8');
             var result = { success: true, path: filePath };
+            if (resolved.historyBucket) result.historyBucket = resolved.historyBucket;
             if (resolved.isProject) {
                 result.projectPath = resolved.projectPath;
                 result.detectionSource = resolved.detectionSource;
@@ -218,13 +234,21 @@ function createAgentsFileController(deps = {}) {
         if (content.length > 2 * 1024 * 1024) {
             return { error: '内容过大（最大 2MB）' };
         }
+        let agentsHistoryBucket = '';
+        if (typeof backupPromptBeforeWrite === 'function') {
+            const bucket = 'codex_' + sanitizeHistoryId(String(params.baseDir || '').trim() || 'global');
+            backupPromptBeforeWrite(bucket, filePath);
+            agentsHistoryBucket = bucket;
+        }
         const lineEnding = params.lineEnding === '\r\n' ? '\r\n' : '\n';
-        const normalized = normalizeLineEnding(content, lineEnding);
+        var normalized = normalizeLineEnding(content, lineEnding);
         const finalContent = ensureUtf8Bom(normalized);
 
         try {
             fs.writeFileSync(filePath, finalContent, 'utf-8');
-            return { success: true, path: filePath };
+            const agentsResult = { success: true, path: filePath };
+            if (agentsHistoryBucket) agentsResult.historyBucket = agentsHistoryBucket;
+            return agentsResult;
         } catch (e) {
             return { error: `写入 AGENTS.md 失败: ${e.message}` };
         }

package/cli/prompt-history.js

@@ -0,0 +1,171 @@
+'use strict';
+
+function createPromptHistoryController(deps = {}) {
+    const {
+        fs,
+        path,
+        CONFIG_DIR,
+        MAX_HISTORY = 20
+    } = deps;
+
+    if (!fs) throw new Error('createPromptHistoryController 缺少 fs');
+    if (!path) throw new Error('createPromptHistoryController 缺少 path');
+    if (typeof CONFIG_DIR !== 'string' || !CONFIG_DIR) throw new Error('createPromptHistoryController 缺少 CONFIG_DIR');
+
+    const HISTORY_ROOT = path.join(CONFIG_DIR, 'codexmate-prompt-history');
+    const STAMP_RE = /^(\d{8})-(\d{6})-(\d{3})\.bak$/;
+
+    function sanitizeBucket(bucket) {
+        const raw = typeof bucket === 'string' ? bucket.trim() : '';
+        if (!raw) throw new Error('prompt history bucket 不能为空');
+        const safe = raw.replace(/[^A-Za-z0-9_.-]/g, '_');
+        if (!safe) throw new Error('prompt history bucket 无效: ' + bucket);
+        return safe;
+    }
+
+    function resolveBucketDir(bucket) {
+        const safe = sanitizeBucket(bucket);
+        return path.join(HISTORY_ROOT, safe);
+    }
+
+    function buildTimestamp(d = new Date()) {
+        const pad2 = (n) => String(n).padStart(2, '0');
+        const pad3 = (n) => String(n).padStart(3, '0');
+        return `${d.getFullYear()}${pad2(d.getMonth() + 1)}${pad2(d.getDate())}`
+            + `-${pad2(d.getHours())}${pad2(d.getMinutes())}${pad2(d.getSeconds())}`
+            + `-${pad3(d.getMilliseconds())}`;
+    }
+
+    function parseStamp(name) {
+        return STAMP_RE.test(name) ? name.slice(0, name.length - 4) : null;
+    }
+
+    function ensureDirSync(dir) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+
+    function rmtreeSync(dir) {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+        } catch (_) {}
+    }
+
+    function backupPromptBeforeWrite(bucket, currentFilePath) {
+        const dir = resolveBucketDir(bucket);
+        const exists = fs.existsSync(currentFilePath);
+        if (!exists) return { backedUp: false, entries: listPromptHistory(bucket) };
+        let raw;
+        try {
+            raw = fs.readFileSync(currentFilePath, 'utf-8');
+        } catch (e) {
+            return { backedUp: false, error: '读取当前文件失败: ' + e.message };
+        }
+        ensureDirSync(dir);
+        const stamp = buildTimestamp();
+        const dest = path.join(dir, stamp + '.bak');
+        try {
+            fs.writeFileSync(dest, raw, 'utf-8');
+        } catch (e) {
+            return { backedUp: false, error: '写入备份失败: ' + e.message };
+        }
+        trimHistory(dir);
+        return { backedUp: true, entries: listPromptHistory(bucket) };
+    }
+
+    function listPromptHistory(bucket) {
+        const dir = resolveBucketDir(bucket);
+        if (!fs.existsSync(dir)) return [];
+        let names;
+        try {
+            names = fs.readdirSync(dir);
+        } catch (_) {
+            return [];
+        }
+        const items = [];
+        for (const name of names) {
+            const stamp = parseStamp(name);
+            if (!stamp) continue;
+            let stat;
+            try {
+                stat = fs.statSync(path.join(dir, name));
+            } catch (_) {
+                continue;
+            }
+            items.push({
+                id: stamp,
+                bucket: sanitizeBucket(bucket),
+                size: Number(stat.size) || 0,
+                mtimeMs: Number(stat.mtimeMs) || 0
+            });
+        }
+        items.sort((a, b) => b.mtimeMs - a.mtimeMs);
+        return items;
+    }
+
+    function readPromptHistory(bucket, id) {
+        const dir = resolveBucketDir(bucket);
+        const stamp = typeof id === 'string' ? id.trim() : '';
+        const fullName = stamp + '.bak';
+        if (!stamp || !STAMP_RE.test(fullName)) {
+            return { error: 'history id invalid' };
+        }
+        const file = path.join(dir, fullName);
+        if (!fs.existsSync(file)) return { error: 'history entry 不存在' };
+        try {
+            const content = fs.readFileSync(file, 'utf-8');
+            return { id: stamp, content, bucket: sanitizeBucket(bucket) };
+        } catch (e) {
+            return { error: '读取 history 失败: ' + e.message };
+        }
+    }
+
+    function trimHistory(dir) {
+        let names;
+        try {
+            names = fs.readdirSync(dir);
+        } catch (_) {
+            return;
+        }
+        const stamped = [];
+        for (const name of names) {
+            const stamp = parseStamp(name);
+            if (!stamp) continue;
+            let stat;
+            try {
+                stat = fs.statSync(path.join(dir, name));
+            } catch (_) {
+                continue;
+            }
+            stamped.push({ name, mtimeMs: Number(stat.mtimeMs) || 0 });
+        }
+        stamped.sort((a, b) => b.mtimeMs - a.mtimeMs);
+        if (stamped.length <= MAX_HISTORY) return;
+        for (let i = MAX_HISTORY; i < stamped.length; i++) {
+            try {
+                fs.unlinkSync(path.join(dir, stamped[i].name));
+            } catch (_) {}
+        }
+    }
+
+    function clearPromptHistory(bucket) {
+        if (!bucket) {
+            rmtreeSync(HISTORY_ROOT);
+            return { cleared: true };
+        }
+        const dir = resolveBucketDir(bucket);
+        rmtreeSync(dir);
+        return { cleared: true };
+    }
+
+    return {
+        sanitizeBucket,
+        backupPromptBeforeWrite,
+        listPromptHistory,
+        readPromptHistory,
+        clearPromptHistory
+    };
+}
+
+module.exports = {
+    createPromptHistoryController
+};

package/cli/system-prompt-files.js

@@ -8,7 +8,8 @@ function createSystemPromptFileController(deps = {}) {
         crypto,
         buildLineDiff,
         CONFIG_DIR,
-        PI_AGENT_DIR
+        PI_AGENT_DIR,
+        backupPromptBeforeWrite
     } = deps;
 
     if (!fs) throw new Error('createSystemPromptFileController 缺少 fs');
@@ -18,6 +19,7 @@ function createSystemPromptFileController(deps = {}) {
     if (typeof buildLineDiff !== 'function') throw new Error('createSystemPromptFileController 缺少 buildLineDiff');
     if (typeof CONFIG_DIR !== 'string' || !CONFIG_DIR) throw new Error('createSystemPromptFileController 缺少 CONFIG_DIR');
     if (typeof PI_AGENT_DIR !== 'string' || !PI_AGENT_DIR) throw new Error('createSystemPromptFileController 缺少 PI_AGENT_DIR');
+    if (typeof backupPromptBeforeWrite !== 'function' && typeof backupPromptBeforeWrite !== 'undefined') throw new Error('createSystemPromptFileController 备份回调无效');
 
     const MODES = {
         system: 'SYSTEM.md',
@@ -34,6 +36,12 @@ function createSystemPromptFileController(deps = {}) {
         return key;
     }
 
+    function sanitizeSystemHistoryId(raw) {
+        const safe = typeof raw === 'string' ? raw.trim() : '';
+        if (!safe) return 'global';
+        return safe.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 64) || 'global';
+    }
+
     function normalizeScope(scope) {
         const key = typeof scope === 'string' ? scope.trim() : '';
         if (!SCOPES.includes(key)) {
@@ -104,16 +112,26 @@ function createSystemPromptFileController(deps = {}) {
         if (baseHash && baseHash !== current.hash) {
             return { error: '文件已被外部修改，请重新加载后再保存' };
         }
+        let sysHistoryBucket = '';
         try {
             const dir = path.dirname(target.path);
             fs.mkdirSync(dir, { recursive: true });
+            if (typeof backupPromptBeforeWrite === 'function') {
+                const bucket = 'system_' + target.scope + '_' + (target.scope === 'project'
+                    ? sanitizeSystemHistoryId(path.dirname(target.path))
+                    : 'global');
+                backupPromptBeforeWrite(bucket, target.path);
+                sysHistoryBucket = bucket;
+            }
             const finalContent = content.endsWith('\n') ? content : content + '\n';
             fs.writeFileSync(target.path, finalContent, { encoding: 'utf8', mode: 0o600 });
             try { fs.chmodSync(target.path, 0o600); } catch (_) {}
         } catch (e) {
             return { error: '写入 system prompt 失败: ' + e.message };
         }
-        return readSystemPromptFilePath(target);
+        const saved = readSystemPromptFilePath(target);
+        if (sysHistoryBucket) saved.historyBucket = sysHistoryBucket;
+        return saved;
     }
 
     function readSystemPromptFilePath(resolved) {