@xcanwin/manyoyo 8.6.2 → 8.6.4

package/lib/app-update.js

@@ -11,7 +11,7 @@ const { spawnSync } = require('child_process');
 const { downloadVerified, sha256File } = require('./download-verified');
 
 const REPO = 'xcanwin/manyoyo';
-const API_BASE = 'https://api.github.com';
+const WEB_BASE = 'https://github.com';
 // 不依赖 PATH 查找 tar（macOS 与常见 Linux 都在 /usr/bin）
 const TAR_COMMAND = fs.existsSync('/usr/bin/tar') ? '/usr/bin/tar' : 'tar';
 const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
@@ -103,35 +103,32 @@ async function request(fetchImpl, url, options = {}) {
 }
 
 /**
- * 查询最新 Release（匿名 API）。返回 { version, tag, assets: { name: url } }。
+ * 查询最新 Release。返回 { version, tag, assets: { name: url } }。
+ * 不调 GitHub API：匿名 API 按 IP 每小时 60 次，共享出口（公司网络、代理、CI runner）经常被限流。
+ * 改为跟随 github.com 的 releases/latest 跳转取版本（与 scripts/install.sh 一致），
+ * 升级包与 SHA256SUMS 的命名是固定的，下载地址直接拼在本仓库的 Release 下载路径下。
  */
-async function fetchLatestRelease({ fetchImpl = fetch, apiBase = API_BASE, now = Date.now } = {}) {
-    const response = await request(fetchImpl, `${apiBase}/repos/${REPO}/releases/latest`);
-    if (response.status === 403 || response.status === 429) {
-        const remaining = response.headers.get('x-ratelimit-remaining');
-        if (response.status === 429 || remaining === '0') {
-            const reset = Number(response.headers.get('x-ratelimit-reset'));
-            const when = reset > 0 ? new Date(reset * 1000).toLocaleTimeString('zh-CN', { hour12: false }) : '';
-            throw new UpdateError('RATE_LIMIT', `GitHub 对匿名请求做了频率限制，${when ? `请在 ${when} 之后重试` : '请稍后重试'}。`);
-        }
-    }
-    if (response.status === 404) throw new UpdateError('NO_RELEASE', '仓库还没有发布的 Release，暂时无法升级。');
-    if (!response.ok) throw new UpdateError('HTTP', `查询最新版本失败（HTTP ${response.status}）。`);
-    let release;
-    try {
-        release = await response.json();
-    } catch (error) {
-        throw new UpdateError('HTTP', '查询最新版本失败（返回内容不是有效的 JSON）。');
-    }
-    const version = String(release.tag_name || '').replace(/^v/, '');
-    if (!VERSION_PATTERN.test(version)) throw new UpdateError('HTTP', `最新 Release 的版本号无法识别: ${release.tag_name}`);
-    // 默认 API 下，下载地址必须在本仓库的 Release 下载路径内（测试注入自定义 apiBase 时不限制）
-    const allowedPrefix = apiBase === API_BASE ? `https://github.com/${REPO}/releases/download/` : '';
+async function fetchLatestRelease({ fetchImpl = fetch, webBase = WEB_BASE } = {}) {
+    const response = await request(fetchImpl, `${webBase}/${REPO}/releases/latest`, { redirect: 'manual', headers: { Accept: 'text/html' } });
+    if (response.status === 429) throw new UpdateError('RATE_LIMIT', 'GitHub 对访问做了频率限制，请稍后重试。');
+    const location = response.status >= 300 && response.status < 400 ? String(response.headers.get('location') || '') : '';
+    if (!location && !response.ok && response.status !== 404) throw new UpdateError('HTTP', `查询最新版本失败（HTTP ${response.status}）。`);
+    // 没有任何 Release 时 latest 跳到 Release 列表页（或 404）
+    const match = /\/releases\/tag\/([^/?#]+)$/.exec(location);
+    if (!match) throw new UpdateError('NO_RELEASE', '仓库还没有发布的 Release，暂时无法升级。');
+    const tag = decodeURIComponent(match[1]);
+    const version = tag.replace(/^v/, '');
+    if (!VERSION_PATTERN.test(version)) throw new UpdateError('HTTP', `最新 Release 的版本号无法识别: ${tag}`);
+    const download = `${webBase}/${REPO}/releases/download/${encodeURIComponent(tag)}/`;
     const assets = {};
-    for (const asset of Array.isArray(release.assets) ? release.assets : []) {
-        if (asset && typeof asset.name === 'string' && typeof asset.browser_download_url === 'string' && asset.browser_download_url.startsWith(allowedPrefix)) assets[asset.name] = asset.browser_download_url;
+    for (const targetOs of ['macos', 'linux']) {
+        for (const targetArch of ['arm64', 'x64']) {
+            const names = releaseAssetNames(version, targetArch, targetOs);
+            assets[names.app] = `${download}${names.app}`;
+            assets[names.sums] = `${download}${names.sums}`;
+        }
     }
-    return { version, tag: release.tag_name, assets };
+    return { version, tag, assets };
 }
 
 function parseSha256Sums(text) {
@@ -250,6 +247,11 @@ async function installAppUpdate({ appRoot, release, fetchImpl = fetch, targetArc
         throw new UpdateError('NO_ASSET', `Release ${release.version} 里没有适合这台机器（${targetOs}-${targetArch}）的升级包（需要 ${names.app} 与 ${names.sums}）。`);
     }
 
+    // 下载地址是按固定命名拼出来的：先确认这个 Release 里确实有本机的升级包（404 就是没有）
+    const probe = await request(fetchImpl, appUrl, { method: 'HEAD' });
+    if (probe.status === 404) {
+        throw new UpdateError('NO_ASSET', `Release ${release.version} 里没有适合这台机器（${targetOs}-${targetArch}）的升级包（需要 ${names.app} 与 ${names.sums}）。`);
+    }
     log(`校验清单: ${sumsUrl}`);
     const sums = parseSha256Sums(await fetchText(fetchImpl, sumsUrl));
     const expected = sums[names.app];

package/lib/core/event-store.js

@@ -67,12 +67,34 @@ class FileEventStore {
         }
 
         fs.mkdirSync(this.eventsDir, { recursive: true });
-        fs.appendFileSync(this.getEventFilePath(event.aggregateId), `${JSON.stringify(event)}\n`);
+        const eventFilePath = this.getEventFilePath(event.aggregateId);
+        // 上一次追加被强杀在行中间时，文件末尾是没有换行的残缺行：先截掉它（read 本来也不认它），
+        // 否则新事件会拼在它后面，残缺行变成中间行，之后每次 read 都会抛错
+        this.dropIncompleteTail(eventFilePath);
+        fs.appendFileSync(eventFilePath, `${JSON.stringify(event)}\n`);
         const projection = projectSessionEvents([...events, event]);
         this.saveProjection(event.aggregateId, projection);
         return event;
     }
 
+    dropIncompleteTail(filePath) {
+        if (!fs.existsSync(filePath)) {
+            return;
+        }
+        const content = fs.readFileSync(filePath);
+        if (!content.length || content[content.length - 1] === 0x0a) {
+            return;
+        }
+        const lineStart = content.lastIndexOf(0x0a) + 1;
+        try {
+            JSON.parse(content.subarray(lineStart).toString('utf-8'));
+            // 最后一行是完整事件，只是缺换行：补上换行，保留这条事件
+            fs.appendFileSync(filePath, '\n');
+        } catch (error) {
+            fs.truncateSync(filePath, lineStart);
+        }
+    }
+
     loadProjection(aggregateId) {
         const events = this.read(aggregateId);
         const projection = projectSessionEvents(events);

package/lib/init-config.js

@@ -418,6 +418,8 @@ async function initAgentConfigs(rawAgents, options = {}) {
     // 只在原文上局部写入各 runs.<agent>，保留用户的注释与格式
     const originalRaw = fs.existsSync(manyoyoConfigPath) ? fs.readFileSync(manyoyoConfigPath, 'utf-8') : '';
     let nextRaw = originalRaw;
+    // 记下每次要写的 runs.<agent>：询问期间别处可能改了配置文件，最后在最新内容上重新写，而不是用开始时读到的旧文本覆盖
+    const pendingRunWrites = [];
 
     let hasConfigChanged = false;
     ctx.log(`${CYAN}🧭 正在初始化 MANYOYO 配置: ${agents.join(', ')}${NC}`);
@@ -431,7 +433,11 @@ async function initAgentConfigs(rawAgents, options = {}) {
         if (shouldWriteRun) {
             const buildResult = buildInitRunProfile(agent, spec.yolo, data.volumes, data.keys, data.values);
             runsMap[agent] = buildResult.runProfile;
-            if (originalRaw.trim()) nextRaw = upsertValueByPath(nextRaw, ['runs', agent], JSON.stringify(buildResult.runProfile, null, 4));
+            if (originalRaw.trim()) {
+                const profileText = JSON.stringify(buildResult.runProfile, null, 4);
+                nextRaw = upsertValueByPath(nextRaw, ['runs', agent], profileText);
+                pendingRunWrites.push({ agent, profileText });
+            }
             writeResult = { missingKeys: buildResult.missingKeys, unsafeKeys: buildResult.unsafeKeys };
             hasConfigChanged = true;
         }
@@ -456,7 +462,15 @@ async function initAgentConfigs(rawAgents, options = {}) {
 
     if (hasConfigChanged || !fs.existsSync(manyoyoConfigPath)) {
         if (originalRaw.trim()) {
-            writeConfigFileSecure(manyoyoConfigPath, nextRaw);
+            let finalRaw = nextRaw;
+            const latestRaw = fs.existsSync(manyoyoConfigPath) ? fs.readFileSync(manyoyoConfigPath, 'utf-8') : '';
+            if (latestRaw !== originalRaw && latestRaw.trim()) {
+                finalRaw = latestRaw;
+                for (const write of pendingRunWrites) {
+                    finalRaw = upsertValueByPath(finalRaw, ['runs', write.agent], write.profileText);
+                }
+            }
+            writeConfigFileSecure(manyoyoConfigPath, finalRaw);
         } else {
             // 新文件没有可保留的注释，写标准 JSON
             writeConfigFileSecure(manyoyoConfigPath, `${JSON.stringify({ ...manyoyoConfig, runs: runsMap }, null, 4)}\n`);

package/lib/web/AGENTS.md

@@ -15,9 +15,14 @@
   - `trace`：**不保证带结构化 `traceEvent`**。stderr 行（`emitStderrTraceLine`）和解析不出 JSON 的 stdout 行只有 `text` + `stream`，前端靠 `toTraceEvent()` 兜底成 `kind="output"` 的事件展示。新增只认 `traceEvent` 的分支等于把自定义 CLI、CLI 报错的输出全吞掉。
   - `ping`：保活心跳，前端忽略。`DEFAULT_AGENT_STREAM_HEARTBEAT_MS` 必须明显小于反向代理的空闲读超时（nginx `proxy_read_timeout` 默认 60s），否则 agent 静默期间流会被 RST，浏览器侧表现为输入框上方冒出 `network error`。
   - token 级增量**不写**事件日志、历史落盘按 `AGENT_STREAM_PARTIAL_PERSIST_INTERVAL_MS` 节流；新增逐事件的落盘/日志动作前先想清楚它会不会被每个 token 触发一次。
-- `GET /api/sessions` 是**同步 IO 大户**：逐容器 `readFileSync` + `JSON.parse` 整份历史。前端每标签页 6s 轮询一次，它阻塞多久事件循环就卡多久，正在跑的 `/agent/stream` 只能在空隙里把输出攒着分批推。往这条路径上加同步操作前务必实测耗时；`buildSessionSummary()` 已支持传入调用方加载好的 history，不要再重复读。（`docker ps -a` + 批量 `inspect` 实测仅约 90ms，不是瓶颈，别被旧注释误导）
+- **历史读写在 `lib/web/history-store.js`**：进程内缓存 + 原子写（`writeConfigFileSecure`，0600）+ 合并写盘。读靠 `stat` 的 `ino + mtimeMs + size` 判断缓存是否还有效（别的进程原子替换也能识别）；`loadWebSessionHistory` 返回的是**缓存里的同一个对象**，改了必须 `saveWebSessionHistory`，只读路由不要改它（`getWebAgentSession(..., { create: true })` 会在缓存里留一个未保存的空 agent，只在马上要写的路径里用）。流式过程中的 trace patch 和控制事件走 `{ defer: true }`（只改内存，最迟 `AGENT_STREAM_PARTIAL_PERSIST_INTERVAL_MS` 后落盘）；`process.exit` / serve 关闭会 flush；`result` / `error` 类事件（`WEB_STREAM_FLUSH_EVENT_TYPES`）和所有非 defer 写入立即写盘并带上攒着的内容。`kill -9` 最多丢约 1 秒的 trace。文件解析失败会留一份 `.corrupt-<时间>` 备份再按空历史处理，不要绕过它。磁盘格式只有 `agents.<id>.messages`（不再有顶层 `messages`，紧凑 JSON），老版本（含 `update --rollback`）读取时优先用 `agents`，能读新文件。
+- `GET /api/sessions` 以前是同步 IO 大户（逐容器读 + 解析整份历史），现在命中缓存基本是 0 次解析，但新增的同步操作仍要先实测；`buildSessionSummary()` 支持传入调用方加载好的 history，不要重复读。（`docker ps -a` + 批量 `inspect` 实测仅约 90ms，不是瓶颈）
+- **`/messages` 是分页 + 增量**（`lib/web/messages-view.js`）：`?limit=`（1～200，默认 60，起点往前对齐到 user 消息）/ `?after=<id>&epoch=<e>`（tail，锚点之后的消息；epoch 不符、锚点不存在或超过 120 条时返回最近一页并标 `mode: "reset"`）/ `?before=<id>`（更早一页）；`GET /messages/<id>/trace` 取完整执行过程。查询参数全部白名单校验，非法返回 400。**稳定前缀约定**：第一条 pending 消息之前的消息不再被修改——违反约定的写操作（删除非 pending 消息、克隆）必须给该 agent 换新的 `epoch`（`removeWebSessionMessage` 与 clone 已处理；新增修改历史消息的写操作要自己判断）。500 条上限从头裁掉**不换** epoch（tail 响应带 `firstId`，前端据此裁掉本地被丢弃的开头）。列表里的 trace 消息会被精简（长字符串截成 200 字符，带 `traceTruncated`），`/audit` 与 trace 接口输出完整内容。
+- **控制事件的 seq 以事件日志为准，不是历史快照**：事件日志（`FileEventStore`）每条事件立即追加，历史快照里的 `events` 是合并写盘的，进程被强杀后快照会落后；`appendWebSessionControlEvent` 靠进程内的 `controlEventSeqCache`（首次用从日志读一次，对不上就丢缓存重算）续 seq，从快照取 seq 会在强杀重启后让每一轮对话都抛 `seq 必须连续递增`、serve 直接退出。`FileEventStore.append` 追加前会截掉被强杀留下的残缺末行（否则它变成中间行，之后每次读都抛错）。
+- **`clientMessageId` 幂等**：`/agent/stream`、`/agent`、`/run` 收到的 `clientMessageId`（`^[A-Za-z0-9_-]{8,64}$`）会存进 user 消息；同一个 id 已出现在该 agent 的消息里（或同一条请求还在检查与落盘之间，`claimClientMessage`）就不再执行，返回 409 `{ error, duplicate: true }`（`rejectDuplicateClientMessage`）。前端在网络中断后重发放回的内容时沿用原 id，靠它兜住“服务端其实已经收到”的情况；有 `duplicate` 的 409 与“容器忙”的 409 要区分。
+- **ETag / 压缩**（`sendJson` / `sendHtml` → `sendBody`）：`/messages` 的 ETag 是 `bootId + 进程内历史版本号 + 查询摘要`（不用 mtime：同一毫秒内两次写入大小相同会误回 304 显示旧内容）；`/sessions`、`detail` 用响应体 sha1；index.html 按文件 stat 缓存并带 ETag。这些响应 `Cache-Control: no-cache`，其余仍是 `no-store`。>1KB 的 JSON/HTML 异步 gzip；**NDJSON 流和 WebSocket 不压缩**（压缩会被缓冲，破坏实时性），`X-Accel-Buffering: no` 必须保留。
 - 请求处理链路上注册在**全局认证网关之前**的代码（如 `res.on('finish')` 之类的钩子）必须自带 try/catch：那里抛异常会冒泡成 `uncaughtException`，而 `bin/manyoyo.js` 的处理器直接 `process.exit(1)`——等于未认证请求可打挂 serve。回归用例见 `test/web-server-auth.test.js` 的 `Web Server Robustness`。
-- **终端 WebSocket**：`/api/sessions/:name/terminal/ws`，在 `server.on('upgrade')` 里做 Origin 校验 + 认证 + 容器名校验，再交给 `bindTerminalWebSocket()`。上行 `input` / `ping` / `close`，下行 `output` / `status`（`ready` / `closed`）/ `error` / `pong`；实现是 `docker exec` 里用 `script` 或 python `pty` 引导出的伪 TTY，**不支持动态 resize**（`resize` 消息是预留的空实现，行列只在建连时由 query 参数定死）。并发上限 `WEB_TERMINAL_MAX_SESSIONS = 20`，每条连接对应一个 `ptyProcess`，`ws` 关闭即 `SIGTERM`——所以前端任何「卸载终端组件」的改动都等于杀掉用户正在跑的 shell。
+- **终端 WebSocket**：`/api/sessions/:name/terminal/ws`，在 `server.on('upgrade')` 里做 Origin 校验 + 认证 + 容器名校验，再交给 `bindTerminalWebSocket()`。上行 `input` / `resize` / `ping` / `close`，下行 `output` / `status`（`ready` / `closed`）/ `error` / `pong`；实现是 `docker exec` 里用 `script` 或 python `pty` 引导出的伪 TTY。**动态 resize**：bootstrap 的 rc 把 `tty` 输出写进容器里 `/tmp/manyoyo-term-<随机id>.tty`；收到 `resize` 后（整数、10～500 列、4～200 行，否则整条忽略；下限比建连初值 40×12 低，因为手机竖屏不到 40 列；节流，同一时刻只有一个 exec）用固定脚本 `TERMINAL_RESIZE_SCRIPT` 在容器里读该文件，内容必须整行匹配 `/dev/pts/<数字>` 才执行 `stty -F`。**这个 tty 文件容器里的进程可写，只能当不可信输入**（脚本只认普通文件、不跟符号链接、最多读 64 字节），用例见 `test/web-terminal-resize.test.js`。降级成非 TTY 时 resize 自然无效。并发上限 `WEB_TERMINAL_MAX_SESSIONS = 20`，每条连接对应一个 `ptyProcess`，`ws` 关闭即 `SIGTERM`——所以前端任何「卸载终端组件」的改动都等于杀掉用户正在跑的 shell。
 - 空闲保活是 `/agent/stream` 那条心跳规则的同类问题，**两个入口都要守**：终端侧服务端每 `WEB_TERMINAL_PING_INTERVAL_MS`（30s）发 WebSocket ping 帧，连续 `WEB_TERMINAL_MAX_MISSED_PONGS`（3 次，约 90s）无 pong 才判死；前端另发应用层 `ping`（浏览器 JS 发不出 ping 帧，上行需要自己造流量）。判死阈值不要收紧到一个周期：手机切后台会让连接短暂挂起，误杀等于用户的 shell 没了。升级后的 socket 还要 `setTimeout(0)` + `setKeepAlive`，解除 HTTP 侧空闲超时。
 - 新增接口/页面必须走全局认证网关，禁止在业务路由里零散补认证；匿名白名单见根 `AGENTS.md` 的安全约束。
 
@@ -25,10 +30,16 @@
 
 `lib/web/container-manage.js`（路由工厂，由 `handleWebApi` 追加进路由表）：`/api/containers/:name/{env,autostart,autostart/run,autostart/log,network,network/allow,network/denied,expose}` 与 `/api/containers/orphans`。旧容器（无 `manyoyo.id`）GET 返回 `{legacy:true}`、写返回 409。`PUT env` 用 `If-Match`（etag）防止覆盖容器内的修改；放开类改动（切到 `custom`、新增很宽的允许规则、非 loopback 暴露）服务端也要求 `confirmRisk:true`；`network` 是 v2 规则表（`outbound` / `inbound`，旧 v1 读取时自动转换，`@container:<名称>` 保存时换成 id）。serve 运行时就绪后 `startContainerServices` 订阅 `<runtime> events`（start / die）补下发规则、拉起 `autostartOnServe` 容器、恢复端口暴露；事件流断开重连（运行时重启）后 `reconcileContainerServices` 再对账一次；过滤代理是 sidecar 容器（`lib/egress-sidecar.js`），由网络管理器 `ensure()` 保证在运行，不在 serve 进程里。`GET network` 带 `denied`（最近被拦截，已放行的不列）、`derived`（别的容器入站放行本容器产生的出站派生行）与 `peers[].ip`；`network/allow` 在出站用户规则最前插入允许域名行；`/agent/stream` 进行中 `createWebDeniedNotifier` 每 2 秒读一次拦截记录，有新域名就推一条 `trace`（只有 `text`，同一域名同一轮一次）。所有 exec 经 `spawnContainerExec`（env 临时文件在子进程 close 时删）。
 
+## 保存不覆盖别人的修改（If-Match）
+
+`PUT /api/config` 和 `PUT /api/sessions/:name/fs/write` **必须**带 `If-Match`，缺少返回 428（报错统一用 `STALE_PAGE_MESSAGE`“页面已更新，请刷新页面后再保存”：现在的前端总会带上 If-Match，走到这里的只有升级前就打开、还没刷新的旧页面，提示要让用户知道怎么办），版本不一致返回 409 `{ conflict: true }`（与容器环境变量 `PUT env` 同一套约定）。`GET /api/config` 的 `etag` 是**磁盘原文**的 sha256（不是脱敏后的 `raw`：只改了密钥时脱敏文本不变，用它算版本就识别不出来），响应里只有哈希；409 的响应体带最新的 `buildSafeWebConfigSnapshot`（含新 `etag`）。配置文件的“读文件 → 比对版本 → 写文件”必须在同一个同步段里完成（中间不能有 `await`，并发请求测试 `test/web-config-etag.test.js` 守着）。`fs/read` 返回内容的 sha256 `etag`（只给 2MB 以内的可编辑文件算），`fs/write` 在容器内的脚本里写入前重新算当前内容的哈希，不一致就返回 `conflict`、服务端转成 409；容器内“比对”和“写入”之间仍有一个极短的窗口（同一个脚本里的两条语句），可以接受。其余写配置文件的接口（`/api/setup/*`、`quick-chat-config`、CLI 的 `build`/`init`/`setup`）都是“读当前磁盘内容 → 局部修改 → 写回”，不会盖掉别人的修改，不需要版本号。**新增写配置文件的接口时，要么走局部修改，要么也带 If-Match。**
+
 ## lib/web/index.html
 
-前端构建产物（`npm run build:web`，已 `.gitignore`），由 `loadIndexHtml()` 在每次请求时读取，`/` 与登录页 `/auth/login` 共用。服务端不托管其它前端静态资源，别往 `lib/web/` 里放散装 js/css。
+前端构建产物（`npm run build:web`，已 `.gitignore`），由 `loadIndexHtml()` 按文件 stat 缓存读取（文件变了才重读），`/` 与登录页 `/auth/login` 共用。服务端不托管其它前端静态资源，别往 `lib/web/` 里放散装 js/css。
 
 ## 测试
 
+- 浏览器 E2E：本机有 `http_proxy` 时，连本地 CDP / serve 要 `env -u http_proxy` 或 `--noproxy '*'`；Playwright `connectOverCDP` 的页面始终显示为有焦点、可见，焦点和可见性要靠覆写 `document.hasFocus` / `visibilityState` 并派发事件来模拟；假 Agent 的开关用唯一令牌，因为服务端会把最近的对话注入 prompt。
+
 Web 相关改动优先补 `test/web-server-auth.test.js`；涉及认证时至少验证未登录 `401`、登录成功可访问、登出后失效。

package/lib/web/container-manage.js

@@ -14,6 +14,8 @@ const { isBrowserBackground } = require('../browser-background');
 // 容器管理接口：环境变量、自启动、网络（含端口暴露）、孤儿状态目录。
 // 全部挂在全局认证网关之后；非只读请求由 handleWebApi 统一校验 X-Requested-With。
 const LEGACY_MESSAGE = '该容器创建于旧版本，重建后可用';
+// 写接口缺 If-Match 只会发生在升级前就打开、还没刷新的旧页面上：告诉用户怎么办，不出现 If-Match / etag 这类术语
+const STALE_PAGE_MESSAGE = '页面已更新，请刷新页面后再保存';
 
 // 本机可用于访问端口暴露的 IPv4 地址（绑定 0.0.0.0 时前端据此列出全部访问链接）；
 // 回环排第一，容器 / 虚拟网桥的地址对访问者没用，过滤掉
@@ -389,7 +391,7 @@ function createContainerManageRoutes({ ctx, state, req, res, deps }) {
                 }
                 const ifMatch = req.headers['if-match'];
                 if (ifMatch === undefined) {
-                    sendJson(res, 428, { error: '需要 If-Match（先 GET 取得 etag），避免覆盖容器内的修改' });
+                    sendJson(res, 428, { error: STALE_PAGE_MESSAGE });
                     return;
                 }
                 try {
@@ -557,4 +559,4 @@ function createContainerManageRoutes({ ctx, state, req, res, deps }) {
     ];
 }
 
-module.exports = { createContainerManageRoutes, pendingRisks, isLoopbackBind };
+module.exports = { createContainerManageRoutes, pendingRisks, isLoopbackBind, STALE_PAGE_MESSAGE };

package/lib/web/history-store.js

@@ -0,0 +1,221 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { writeConfigFileSecure } = require('../secure-file');
+
+// 历史文件的进程内缓存 + 原子写 + 合并写盘。
+// - 读：stat 的 ino + mtimeMs + size 没变就直接返回缓存对象（原子写每次都会换 inode，别的进程改了也能认出来）。
+// - 版本号：进程内单调计数，加启动时随机的 bootId，供 ETag 使用；不能只用 mtime（同一毫秒内的两次写入会撞）。
+// - 写：默认立即原子写；defer 写只改内存并最迟 DEFER_FLUSH_MS 后落盘，serve 关闭时 flushAll。
+
+const CACHE_MAX_BYTES = 64 * 1024 * 1024;
+const DEFER_FLUSH_MS = 1000;
+
+const bootId = crypto.randomBytes(3).toString('hex');
+const cache = new Map();
+// 版本号单独记：缓存条目被淘汰后 ETag 的版本号也不能丢（否则内容变了版本还是 0）
+const versions = new Map();
+const backedUp = new Set();
+let versionSeq = 0;
+let flushTimer = null;
+
+function nextVersion(filePath) {
+    versionSeq += 1;
+    versions.set(filePath, versionSeq);
+    return versionSeq;
+}
+
+function statKey(stat) {
+    return `${stat.ino}:${stat.mtimeMs}:${stat.size}`;
+}
+
+function evictIfNeeded(keep) {
+    let total = 0;
+    cache.forEach(entry => { total += entry.bytes; });
+    if (total <= CACHE_MAX_BYTES) {
+        return;
+    }
+    const candidates = [...cache.entries()]
+        .filter(([key, entry]) => !entry.dirty && key !== keep)
+        .sort((a, b) => a[1].lastUsed - b[1].lastUsed);
+    for (const [key, entry] of candidates) {
+        if (total <= CACHE_MAX_BYTES) {
+            break;
+        }
+        cache.delete(key);
+        total -= entry.bytes;
+    }
+}
+
+function touch(entry) {
+    entry.lastUsed = Date.now();
+}
+
+/**
+ * @param {string} filePath
+ * @param {(raw: any) => any} normalize 把解析出的 JSON 归一化为内存对象
+ * @returns {{ value: any, version: number }|null} 文件不存在返回 null
+ */
+function read(filePath, normalize) {
+    let stat = null;
+    try {
+        stat = fs.statSync(filePath);
+    } catch (e) {
+        stat = null;
+    }
+    const entry = cache.get(filePath);
+    if (entry && entry.dirty) {
+        // 内存里有尚未落盘的更新，比磁盘新
+        touch(entry);
+        return { value: entry.value, version: entry.version };
+    }
+    if (!stat) {
+        cache.delete(filePath);
+        return null;
+    }
+    if (entry && entry.key === statKey(stat)) {
+        touch(entry);
+        return { value: entry.value, version: entry.version };
+    }
+    const text = fs.readFileSync(filePath, 'utf-8');
+    let parsed = null;
+    try {
+        parsed = JSON.parse(text);
+    } catch (e) {
+        // 解析失败：留一份备份，免得下一次保存把空历史写回去后原文彻底丢失（同一份损坏内容只备份一次）
+        const corruptKey = `${filePath}|${statKey(stat)}`;
+        if (!backedUp.has(corruptKey)) {
+            backedUp.add(corruptKey);
+            try {
+                fs.copyFileSync(filePath, `${filePath}.corrupt-${Date.now()}`);
+            } catch (copyError) { /* 尽力 */ }
+        }
+        cache.delete(filePath);
+        return null;
+    }
+    const value = normalize(parsed);
+    const next = {
+        value,
+        version: nextVersion(filePath),
+        key: statKey(stat),
+        bytes: stat.size,
+        dirty: false,
+        lastUsed: Date.now(),
+        serialize: null
+    };
+    cache.set(filePath, next);
+    evictIfNeeded(filePath);
+    return { value, version: next.version };
+}
+
+function writeEntry(filePath, entry) {
+    const text = entry.serialize(entry.value);
+    writeConfigFileSecure(filePath, text);
+    const stat = fs.statSync(filePath);
+    entry.key = statKey(stat);
+    entry.bytes = stat.size;
+    entry.dirty = false;
+}
+
+function scheduleFlush() {
+    if (flushTimer) {
+        return;
+    }
+    flushTimer = setTimeout(() => {
+        flushTimer = null;
+        flushAll();
+    }, DEFER_FLUSH_MS);
+    if (typeof flushTimer.unref === 'function') {
+        flushTimer.unref();
+    }
+}
+
+/**
+ * @param {string} filePath
+ * @param {any} value 已归一化的内存对象（成为新的缓存值）
+ * @param {(value: any) => string} serialize
+ * @param {{ defer?: boolean }} [options]
+ * @returns {number} 新版本号
+ */
+function write(filePath, value, serialize, options = {}) {
+    const entry = {
+        value,
+        version: nextVersion(filePath),
+        key: '',
+        bytes: 0,
+        dirty: true,
+        lastUsed: Date.now(),
+        serialize
+    };
+    const previous = cache.get(filePath);
+    if (previous) {
+        entry.bytes = previous.bytes;
+    }
+    cache.set(filePath, entry);
+    if (options.defer === true) {
+        scheduleFlush();
+        return entry.version;
+    }
+    try {
+        writeEntry(filePath, entry);
+    } catch (error) {
+        cache.delete(filePath);
+        throw error;
+    }
+    evictIfNeeded(filePath);
+    return entry.version;
+}
+
+/** 立即写出所有待写内容；目录已不存在（如测试清理后）则放弃，不重新建目录 */
+function flushAll() {
+    let failed = false;
+    cache.forEach((entry, filePath) => {
+        if (!entry.dirty) {
+            return;
+        }
+        if (!fs.existsSync(path.dirname(filePath))) {
+            cache.delete(filePath);
+            return;
+        }
+        try {
+            writeEntry(filePath, entry);
+        } catch (error) {
+            failed = true;
+        }
+    });
+    if (failed) {
+        // 写失败（磁盘满、权限）：稍后再试，不要等到下一次写入
+        scheduleFlush();
+    }
+}
+
+function flushFile(filePath) {
+    const entry = cache.get(filePath);
+    if (entry && entry.dirty) {
+        writeEntry(filePath, entry);
+    }
+}
+
+function remove(filePath) {
+    cache.delete(filePath);
+    versions.delete(filePath);
+}
+
+function getVersion(filePath) {
+    return versions.get(filePath) || 0;
+}
+
+// 进程退出（含信号处理里的 process.exit）前写出待写内容
+process.on('exit', flushAll);
+
+module.exports = {
+    bootId,
+    read,
+    write,
+    flushAll,
+    flushFile,
+    remove,
+    getVersion
+};