@xcanwin/manyoyo 8.7.3 → 8.7.4

package/lib/archive/tar.js

@@ -0,0 +1,329 @@
+'use strict';
+
+// 最小 tar 读写器（ustar + pax）。只认普通文件 / 目录 / 符号链接，硬链接和其余类型由读端标出来、交给调用方拒绝。
+// 不引入第三方依赖：宿主机侧解包的安全规则要完全受控。
+
+const BLOCK = 512;
+const MAX_OCTAL_SIZE = 0o77777777777; // ustar size 字段能表示的上限（8GiB - 1），更大的走 pax size
+const MAX_PAX_BYTES = 1024 * 1024;
+
+const TYPES = {
+    '0': 'file',
+    '\0': 'file',
+    '5': 'dir',
+    '2': 'symlink',
+    '1': 'hardlink'
+};
+
+class TarError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TarError';
+    }
+}
+
+function writeString(buf, value, offset, length) {
+    const bytes = Buffer.from(value, 'utf8');
+    bytes.copy(buf, offset, 0, Math.min(bytes.length, length));
+}
+
+function writeOctal(buf, value, offset, length) {
+    const text = Math.max(0, Math.floor(value)).toString(8).padStart(length - 1, '0');
+    buf.write(text.slice(-(length - 1)), offset, length - 1, 'ascii');
+    buf[offset + length - 1] = 0;
+}
+
+function isPlainAscii(text) {
+    return /^[\x20-\x7e]*$/.test(text);
+}
+
+function pad(size) {
+    const rest = size % BLOCK;
+    return rest === 0 ? 0 : BLOCK - rest;
+}
+
+function paxRecord(key, value) {
+    const body = ` ${key}=${value}\n`;
+    let length = Buffer.byteLength(body);
+    // 长度字段本身也算在内
+    let total = length + String(length).length;
+    if (String(total).length !== String(length).length) total += 1;
+    return Buffer.from(`${total}${body}`, 'utf8');
+}
+
+function buildBlock({ name, mode = 0o644, size = 0, mtime = 0, type = '0', linkname = '', uid = 0, gid = 0 }) {
+    const block = Buffer.alloc(BLOCK);
+    writeString(block, name, 0, 100);
+    writeOctal(block, mode & 0o7777, 100, 8);
+    writeOctal(block, uid, 108, 8);
+    writeOctal(block, gid, 116, 8);
+    writeOctal(block, Math.min(size, MAX_OCTAL_SIZE), 124, 12);
+    writeOctal(block, mtime, 136, 12);
+    block.fill(0x20, 148, 156);
+    block.write(type, 156, 1, 'ascii');
+    writeString(block, linkname, 157, 100);
+    block.write('ustar\0', 257, 6, 'latin1');
+    block.write('00', 263, 2, 'ascii');
+    let sum = 0;
+    for (let i = 0; i < BLOCK; i++) sum += block[i];
+    const text = sum.toString(8).padStart(6, '0');
+    block.write(text, 148, 6, 'ascii');
+    block[154] = 0;
+    block[155] = 0x20;
+    return block;
+}
+
+/**
+ * 一个条目的头部（必要时前面带 pax 扩展头）。meta：{ name, type: 'file'|'dir'|'symlink', size, mode, mtime, linkname }
+ * 名字超过 100 字节、含非 ASCII、size 超过 8GiB-1 都走 pax。
+ */
+function encodeEntryHeader(meta) {
+    const type = meta.type === 'dir' ? '5' : meta.type === 'symlink' ? '2' : '0';
+    const name = meta.type === 'dir' && !meta.name.endsWith('/') ? `${meta.name}/` : meta.name;
+    const size = meta.type === 'file' ? Number(meta.size || 0) : 0;
+    const linkname = meta.linkname || '';
+    const records = [];
+    if (Buffer.byteLength(name) > 100 || !isPlainAscii(name)) records.push(paxRecord('path', name));
+    if (Buffer.byteLength(linkname) > 100 || !isPlainAscii(linkname)) records.push(paxRecord('linkpath', linkname));
+    if (size > MAX_OCTAL_SIZE) records.push(paxRecord('size', String(size)));
+    const parts = [];
+    if (records.length) {
+        const body = Buffer.concat(records);
+        parts.push(buildBlock({ name: 'PaxHeader', type: 'x', size: body.length, mode: 0o644 }));
+        parts.push(body, Buffer.alloc(pad(body.length)));
+    }
+    const plainName = Buffer.byteLength(name) > 100 || !isPlainAscii(name) ? 'long-name' : name;
+    const plainLink = Buffer.byteLength(linkname) > 100 || !isPlainAscii(linkname) ? 'long-link' : linkname;
+    parts.push(buildBlock({
+        name: plainName,
+        mode: meta.mode === undefined ? (type === '5' ? 0o755 : 0o644) : meta.mode,
+        size,
+        mtime: Math.floor(meta.mtime || 0),
+        type,
+        linkname: plainLink,
+        uid: meta.uid || 0,
+        gid: meta.gid || 0
+    }));
+    return Buffer.concat(parts);
+}
+
+const END_BLOCKS = Buffer.alloc(BLOCK * 2);
+
+function readString(block, offset, length) {
+    let end = offset;
+    const limit = offset + length;
+    while (end < limit && block[end] !== 0) end++;
+    return block.toString('utf8', offset, end);
+}
+
+function readNumber(block, offset, length) {
+    // base-256（GNU 对超大数的编码）：最高位为 1
+    if (block[offset] & 0x80) {
+        let value = block[offset] & 0x7f;
+        for (let i = 1; i < length; i++) value = value * 256 + block[offset + i];
+        return value;
+    }
+    const text = readString(block, offset, length).trim();
+    if (text === '') return 0;
+    if (!/^[0-7]+$/.test(text)) throw new TarError('tar 头部数字字段非法');
+    return parseInt(text, 8);
+}
+
+function isZeroBlock(block) {
+    for (let i = 0; i < BLOCK; i++) if (block[i] !== 0) return false;
+    return true;
+}
+
+function verifyChecksum(block) {
+    const expected = readNumber(block, 148, 8);
+    let sum = 0;
+    for (let i = 0; i < BLOCK; i++) sum += (i >= 148 && i < 156) ? 0x20 : block[i];
+    if (sum !== expected) throw new TarError('tar 头部校验和不符');
+}
+
+function parsePax(body) {
+    const out = {};
+    let pos = 0;
+    while (pos < body.length) {
+        const space = body.indexOf(0x20, pos);
+        if (space < 0) throw new TarError('pax 记录非法');
+        const length = parseInt(body.toString('ascii', pos, space), 10);
+        if (!Number.isInteger(length) || length <= 0 || pos + length > body.length) throw new TarError('pax 记录长度非法');
+        const record = body.toString('utf8', space + 1, pos + length - 1);
+        const eq = record.indexOf('=');
+        if (eq > 0) out[record.slice(0, eq)] = record.slice(eq + 1);
+        pos += length;
+    }
+    return out;
+}
+
+function metaFromBlock(block, pax) {
+    const prefix = readString(block, 345, 155);
+    let name = readString(block, 0, 100);
+    if (prefix && block.toString('ascii', 257, 262) === 'ustar') name = `${prefix}/${name}`;
+    const typeflag = String.fromCharCode(block[156]);
+    const meta = {
+        name,
+        type: TYPES[typeflag] || 'other',
+        typeflag,
+        size: readNumber(block, 124, 12),
+        mode: readNumber(block, 100, 8),
+        mtime: readNumber(block, 136, 12),
+        linkname: readString(block, 157, 100)
+    };
+    if (pax.path !== undefined) meta.name = pax.path;
+    if (pax.linkpath !== undefined) meta.linkname = pax.linkpath;
+    if (pax.size !== undefined) {
+        const size = Number(pax.size);
+        if (!Number.isSafeInteger(size) || size < 0) throw new TarError('pax size 非法');
+        meta.size = size;
+    }
+    if (meta.type === 'dir' && meta.name.endsWith('/')) meta.name = meta.name.slice(0, -1);
+    return meta;
+}
+
+/**
+ * 只解析内存里的头部（可含 pax 扩展头，不含正文）：用于测试和快速探测。
+ * 返回 { meta, consumed }，meta 为 null 表示读到了结束块。
+ */
+function decodeEntryHeader(buffer) {
+    let pos = 0;
+    let pax = {};
+    for (;;) {
+        if (buffer.length - pos < BLOCK) throw new TarError('tar 头部不完整');
+        const block = buffer.subarray(pos, pos + BLOCK);
+        if (isZeroBlock(block)) return { meta: null, consumed: pos + BLOCK };
+        verifyChecksum(block);
+        const typeflag = String.fromCharCode(block[156]);
+        if (typeflag === 'x' || typeflag === 'g') {
+            const size = readNumber(block, 124, 12);
+            if (size > MAX_PAX_BYTES) throw new TarError('pax 扩展头过大');
+            const bodyEnd = pos + BLOCK + size;
+            if (buffer.length < bodyEnd) throw new TarError('tar 头部不完整');
+            if (typeflag === 'x') pax = { ...pax, ...parsePax(buffer.subarray(pos + BLOCK, bodyEnd)) };
+            pos = bodyEnd + pad(size);
+            continue;
+        }
+        return { meta: metaFromBlock(block, pax), consumed: pos + BLOCK };
+    }
+}
+
+// 按需从异步字节源里取定长数据
+class ByteReader {
+    constructor(source) {
+        this.iterator = source[Symbol.asyncIterator]();
+        this.buffer = Buffer.alloc(0);
+        this.done = false;
+    }
+
+    async fill() {
+        if (this.done) return false;
+        const { value, done } = await this.iterator.next();
+        if (done) {
+            this.done = true;
+            return false;
+        }
+        const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+        this.buffer = this.buffer.length ? Buffer.concat([this.buffer, chunk]) : chunk;
+        return true;
+    }
+
+    // 恰好 n 字节；一个字节都没有就到了流尾返回 null；中途断了抛截断错误
+    async readExact(n) {
+        while (this.buffer.length < n) {
+            if (!(await this.fill())) {
+                if (this.buffer.length === 0) return null;
+                throw new TarError('tar 流被截断');
+            }
+        }
+        const out = this.buffer.subarray(0, n);
+        this.buffer = this.buffer.subarray(n);
+        return out;
+    }
+
+    // 分块取 n 字节（不一次性放进内存）
+    async *chunks(n) {
+        let left = n;
+        while (left > 0) {
+            if (this.buffer.length === 0 && !(await this.fill())) throw new TarError('tar 流被截断');
+            const take = Math.min(left, this.buffer.length);
+            const piece = this.buffer.subarray(0, take);
+            this.buffer = this.buffer.subarray(take);
+            left -= take;
+            yield piece;
+        }
+    }
+
+    // 读掉剩下的所有字节（tar 结束块之后上游可能还有补零；不读掉，上游进程会堵在写管道上不退出）
+    async drain() {
+        try {
+            while (await this.fill()) this.buffer = Buffer.alloc(0);
+        } catch (error) {
+            // 结束块之后的错误不影响已经读到的内容
+        }
+    }
+
+    async skip(n) {
+        for await (const piece of this.chunks(n)) void piece;
+    }
+}
+
+/**
+ * 流式读端（拉取式，天然带背压）：
+ *   for await (const { meta, body } of readTarEntries(stream)) { for await (const chunk of body) ... }
+ * body 是该条目正文的异步迭代器（目录 / 链接为空）；没读完的部分在进入下一个条目前自动跳过。
+ * meta.type 为 'other' / 'hardlink' 由调用方决定怎么处理（导入一律拒绝）。
+ * 流在条目中途结束会抛 TarError('tar 流被截断')；在条目边界干净结束视为正常。
+ */
+async function* readTarEntries(source, options = {}) {
+    const maxEntrySize = options.maxEntrySize || Infinity;
+    const reader = new ByteReader(source);
+    let pax = {};
+    for (;;) {
+        const block = await reader.readExact(BLOCK);
+        if (block === null) return;
+        if (isZeroBlock(block)) {
+            await reader.drain();
+            return;
+        }
+        verifyChecksum(block);
+        const typeflag = String.fromCharCode(block[156]);
+        if (typeflag === 'x' || typeflag === 'g') {
+            const size = readNumber(block, 124, 12);
+            if (size > MAX_PAX_BYTES) throw new TarError('pax 扩展头过大');
+            const parts = [];
+            for await (const piece of reader.chunks(size)) parts.push(piece);
+            await reader.skip(pad(size));
+            if (typeflag === 'x') pax = { ...pax, ...parsePax(Buffer.concat(parts)) };
+            continue;
+        }
+        const meta = metaFromBlock(block, pax);
+        pax = {};
+        if (meta.size > maxEntrySize) throw new TarError(`条目过大: ${meta.name}`);
+        const size = meta.type === 'file' ? meta.size : 0;
+        let consumed = 0;
+        const body = (async function* () {
+            for await (const piece of reader.chunks(size)) {
+                consumed += piece.length;
+                yield piece;
+            }
+        })();
+        yield { meta, body };
+        // 调用方没读完：丢弃剩余正文
+        if (consumed < size) {
+            await reader.skip(size - consumed);
+        }
+        await reader.skip(pad(size));
+    }
+}
+
+module.exports = {
+    BLOCK,
+    MAX_OCTAL_SIZE,
+    END_BLOCKS,
+    TarError,
+    readTarEntries,
+    encodeEntryHeader,
+    decodeEntryHeader,
+    pad
+};

package/lib/model-services.js

@@ -19,7 +19,7 @@ function agentLabelOf(agent) {
 }
 
 const RUN_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,39}$/;
-// 订阅登录用的长期令牌；保存它时要删掉同一个运行配置里会盖过订阅的 API Key 类变量（Claude Code 同时有 Key 时优先用 Key）
+// 订阅登录用的长期令牌；保存它时要删掉同一个运行配置里会盖过订阅的 API Key 类变量（Base URL 不删）（Claude Code 同时有 Key 时优先用 Key）
 const CLAUDE_OAUTH_KEY = 'CLAUDE_CODE_OAUTH_TOKEN';
 const CLAUDE_API_KEYS = ['ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY'];
 
@@ -170,6 +170,12 @@ function buildNewService(config, input, options = {}) {
     if (input.subscription) {
         if (agent !== 'claude') throw new Error('订阅登录令牌目前只支持 Claude Code');
         env[CLAUDE_OAUTH_KEY] = secret;
+        // 只有转发订阅令牌的网关才需要 Base URL；模型同理，都是选填
+        const baseUrl = String(input.baseUrl || '').trim();
+        if (baseUrl && !/^https?:\/\//i.test(baseUrl)) throw new Error('Base URL 必须以 http:// 或 https:// 开头');
+        if (baseUrl) env[spec.baseUrlKey] = baseUrl;
+        const model = String(input.model || '').trim();
+        if (model) env[spec.modelKey] = model;
         baseName = `${agent}-subscription`;
     } else if (input.providerId) {
         const preset = presetFor(agent, String(input.providerId));
@@ -238,7 +244,7 @@ function buildReuseService(config, fromName, targetAgent, options = {}) {
 
 /**
  * 编辑已有服务：key 留空表示不改。返回配置改动列表 ops（set / remove，路径从根开始）。
- * 订阅令牌：换成订阅令牌时删掉同一个运行配置里的 API Key 类变量和 Base URL。
+ * 订阅令牌：换成订阅令牌时删掉同一个运行配置里的 API Key 类变量（Base URL 保留，订阅令牌也能走转发网关）。
  */
 function buildServiceEdit(config, name, patch) {
     const runs = isPlainObject(config && config.runs) ? config.runs : {};
@@ -261,7 +267,7 @@ function buildServiceEdit(config, name, patch) {
         if (patch.subscription) {
             if (agent !== 'claude') throw new Error('订阅登录令牌目前只支持 Claude Code');
             setEnv(CLAUDE_OAUTH_KEY, secret);
-            [...CLAUDE_API_KEYS, spec.baseUrlKey].forEach(key => {
+            CLAUDE_API_KEYS.forEach(key => {
                 if (isPlainObject(run.env) && key in run.env) ops.push({ type: 'remove', path: ['runs', name, 'env', key] });
             });
         } else {

package/lib/setup.js

@@ -93,9 +93,9 @@ function buildAgentRunProfile(agent, envInput, options = {}) {
     const existingEnv = isPlainObject(existing.env) ? existing.env : {};
     const profile = { ...existing };
     profile.env = { ...existingEnv, ...provided };
-    // 换成订阅令牌时，同一个运行配置里的 API Key 类变量和 Base URL 要删掉：Claude Code 同时有 Key 时优先用 Key，订阅就被绕过了
+    // 换成订阅令牌时，同一个运行配置里的 API Key 类变量要删掉：Claude Code 同时有 Key 时优先用 Key，订阅就被绕过了
     if (agent === 'claude' && provided.CLAUDE_CODE_OAUTH_TOKEN && !['ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY'].some(key => provided[key])) {
-        for (const key of ['ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY', 'ANTHROPIC_BASE_URL']) delete profile.env[key];
+        for (const key of ['ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY']) delete profile.env[key];
     }
     if (!hasNonEmptyRequiredKey(spec, profile.env)) {
         throw new Error(`请填写 ${spec.requiredAnyOf.join(' 或 ')}`);

package/lib/web/AGENTS.md

@@ -32,6 +32,7 @@
 - 请求处理链路上注册在**全局认证网关之前**的代码（如 `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` / `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 侧空闲超时。
+- **容器导出 / 导入接口**（`lib/web/transfer-routes.js`，核心在 `lib/archive/`，总说明见根 `AGENTS.md`）：`GET /api/transfer/preview`、`POST /api/exports`（`output: download|server`）、`GET /api/exports/<id>/download`（一次性）、`GET/DELETE /api/exports/files/<文件名>`（白名单 `^manyoyo-export-\d{8}-\d{6}\.tar\.(zst|gz)$`）、`GET /api/jobs[/<id>]`、`POST /api/jobs/<id>/cancel`、`POST /api/imports/inspect`（只读文件开头 ≤4MB 的清单）、`POST /api/imports`（`?plan=` + 原始请求体流，或 JSON `{serverFile, plan}`；响应在全部处理完才回来，进度看会话摘要里的 `job`）。**闸门**：`handleWebApi` 一开头按路径归到容器（`/api/sessions|containers/<名>/…`，名字可能是 `容器~agent`），任务期间 409 `{busy, jobId}`，只放行 `GET messages|detail`；终端 WebSocket 升级处同样拒绝；新增“带容器名的路由”不需要改闸门，但**新增不在 `/api/sessions|containers/<名>/` 下、却会动某个容器的接口要自己判断 `state.jobs.busyFor(名)`**。AGENT 正在执行（`state.agentRuns`）时导出直接 409。导入 / 导出文件名、`plan` 里的名字和路径都要重新校验；导入目的地不能是 `/`、`/home`、`$HOME`、`~/.manyoyo` 里，且必须不存在或为空。
 - 新增接口/页面必须走全局认证网关，禁止在业务路由里零散补认证；匿名白名单见根 `AGENTS.md` 的安全约束。
 - **系统提示词**（`lib/agent-instructions.js` 唯一数据源，`buildWebAgentExecCommand` 的 `options.instructions`）：全局配置（`agentInstructions` + 两个 `agentInstructions{Builtin,Custom}Enabled` 开关，`composeSystemPrompt`）只决定**新建容器时的初始内容**；创建时（请求 `systemPrompt:{enabled,text}`，没给就现算）存进容器状态目录 `system-prompt.json`，之后只能经 `/api/containers/:name/system-prompt` 改，改系统设置不影响已有容器。每次执行时读该容器的文件（`readContainerSystemPrompt`），旧容器没有文件就退回按当前全局配置现算；claude 用 `--append-system-prompt`、codex 用 `-c developer_instructions=<TOML 字符串>`、opencode 把说明写进容器 `/tmp/manyoyo-agent-instructions.md` 再经 `OPENCODE_CONFIG_CONTENT` 合并（1.19.3 实测与用户的 instructions 拼接）；gemini 只有 `GEMINI_SYSTEM_MD` 这种整体替换，不注入。用户模板里已有同名参数 / 变量就不注入；用户追加的文本去控制字符、把 `{prompt}` 拆开（否则会被模板替换成提示词）。CLI 的 `manyoyo run` 是交互终端，不注入。
 - **会话标题**：显示优先级 备注 > `title`（claude 的 `/rename` 写 `custom-title`、交互模式写 `ai-title`，**`-p` 下实测不生成 `ai-title`**）> `autoTitle`（轻量调用生成）> `firstPrompt` > AGENT N，服务端摘要与前端 `sessionDisplayTitle` 要同步改。每轮结束后 `refreshWebAgentTitle` 在后台只读会话 jsonl 尾部 256KB（session id 按 UUID 校验），失败静默不写日志；`firstPrompt` 在第一次追加 Agent 用户消息时记下（历史会被裁剪，不能现算）。**自动标题**（`maybeStartAutoTitle`）：第一条 Agent 消息落盘后与第一轮并行发一次轻量调用（`agent-light-call.js`，claude `--no-session-persistence --tools ""` + `CLAUDE_CODE_EFFORT_LEVEL=low`，codex `exec --ephemeral`；实测各约 2 秒、一两百个输入 token），`autoTitleTried` 在调用**前**就落盘（失败也不重试，避免每次刷新都花钱），有备注 / `title` 时不生成；`ctx.autoTitle === false` 可关（那些按“最后一次 exec 就是 Agent 那一轮”断言的测试要关，否则轻量调用混进去）。这些字段与 `pinned`、`slashCommands`、`effort`、`contextUsage`、`recap`、`forkPending` 都要同时加进 `createEmptyWebAgentSession` 和 `normalizeWebAgentSessionRecord`，否则落盘丢失。

package/lib/web/container-jobs.js

@@ -0,0 +1,276 @@
+'use strict';
+
+// 容器导出 / 导入任务：登记、进度、取消、闸门，以及 serve 重启后的恢复。
+// 任务记录落盘到 ~/.manyoyo/jobs/<id>.json：记下“被本任务暂停的容器”和“本任务新建的容器 / 目录 / 历史文件”，
+// serve 被强杀后启动时据此恢复暂停、撤销没做完的导入。恢复时只动记录在案、且 manyoyo.id 对得上的容器（宁可删不掉）。
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { writeConfigFileSecure } = require('../secure-file');
+
+const JOB_ID_RE = /^[0-9a-f]{16}$/;
+
+class JobCancelled extends Error {
+    constructor() {
+        super('任务已取消');
+        this.name = 'JobCancelled';
+    }
+}
+
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+
+function jobsDir(homeDir) {
+    return path.join(homeDir, '.manyoyo', 'jobs');
+}
+
+function createJobRegistry(options = {}) {
+    const homeDir = options.homeDir || os.homedir();
+    const dir = jobsDir(homeDir);
+    const jobs = new Map();
+    const FINISHED_KEEP = 20;
+
+    function persist(job) {
+        if (job.status !== 'running') {
+            try { fs.unlinkSync(path.join(dir, `${job.id}.json`)); } catch (error) { /* 没落盘过 */ }
+            return;
+        }
+        try {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+            const data = { ...job.record() };
+            writeConfigFileSecure(path.join(dir, `${job.id}.json`), `${JSON.stringify(data)}\n`);
+        } catch (error) {
+            // 落盘失败不影响任务本身，只是崩溃后无法自动恢复
+        }
+    }
+
+    function makeJob({ type, containers, meta = {}, id: fixedId, status = 'running' }) {
+        const id = fixedId || crypto.randomBytes(8).toString('hex');
+        const job = {
+            id,
+            type,
+            containers: [...containers],
+            status,
+            stage: '',
+            container: '',
+            bytes: 0,
+            estimate: Number(meta.estimate) || 0,
+            startedAt: new Date().toISOString(),
+            finishedAt: null,
+            error: '',
+            result: null,
+            paused: [],
+            created: { containers: [], dirs: [], historyFiles: [] },
+            partFile: '',
+            cancelRequested: false,
+            meta,
+            // 给界面看的快照（不含内部路径）
+            view() {
+                return {
+                    id: job.id,
+                    type: job.type,
+                    status: job.status,
+                    containers: job.containers,
+                    stage: job.stage,
+                    container: job.container,
+                    bytes: job.bytes,
+                    estimate: job.estimate,
+                    startedAt: job.startedAt,
+                    finishedAt: job.finishedAt,
+                    error: job.error,
+                    result: job.result,
+                    cancelRequested: job.cancelRequested
+                };
+            },
+            // 落盘的记录：恢复需要的内部信息
+            record() {
+                return {
+                    id: job.id,
+                    type: job.type,
+                    pid: process.pid,
+                    containers: job.containers,
+                    startedAt: job.startedAt,
+                    paused: job.paused,
+                    created: job.created,
+                    partFile: job.partFile
+                };
+            },
+            update(patch) {
+                Object.assign(job, patch);
+                persist(job);
+            },
+            check() {
+                if (job.cancelRequested) throw new JobCancelled();
+            },
+            addBytes(n) {
+                job.bytes += n;
+            },
+            addPaused(name, id2, how = 'pause') {
+                job.paused = job.paused.filter(item => item.name !== name);
+                job.paused.push({ name, id: id2, how });
+                persist(job);
+            },
+            removePaused(name) {
+                job.paused = job.paused.filter(item => item.name !== name);
+                persist(job);
+            },
+            addCreated(kind, value) {
+                job.created[kind].push(value);
+                persist(job);
+            },
+            finish(status, extra = {}) {
+                job.status = status;
+                job.finishedAt = new Date().toISOString();
+                Object.assign(job, extra);
+                persist(job);
+                // 只留最近几个已结束的任务
+                const finished = [...jobs.values()].filter(item => item.status !== 'running');
+                finished.slice(0, Math.max(0, finished.length - FINISHED_KEEP)).forEach(item => jobs.delete(item.id));
+            }
+        };
+        jobs.set(id, job);
+        persist(job);
+        return job;
+    }
+
+    return {
+        dir,
+        create: makeJob,
+        get: id => jobs.get(id) || null,
+        list: () => [...jobs.values()].map(job => job.view()),
+        // 正在跑的、涉及这个容器的任务
+        busyFor(containerName) {
+            for (const job of jobs.values()) {
+                if (job.status === 'running' && job.containers.includes(containerName)) return job;
+            }
+            return null;
+        },
+        running: () => [...jobs.values()].filter(job => job.status === 'running'),
+        hasRunning: () => [...jobs.values()].some(job => job.status === 'running'),
+        cancel(id) {
+            const job = jobs.get(id);
+            if (!job || job.status !== 'running') return false;
+            job.cancelRequested = true;
+            return true;
+        },
+
+        /**
+         * 启动时恢复。actions：
+         *   containerIdOf(name) → 当前容器的 manyoyo.id（不存在返回 ''）
+         *   isPaused(name) → 容器当前是否处于暂停
+         *   unpause(name)
+         *   removeContainer(name)
+         *   removePath(p)       删目录或文件
+         * 返回处理过的任务记录列表（status: 'interrupted'）。
+         */
+        recover(actions) {
+            const handled = [];
+            let names = [];
+            try { names = fs.readdirSync(dir); } catch (error) { return handled; }
+            for (const file of names) {
+                if (!/^[0-9a-f]{16}\.json$/.test(file)) continue;
+                const full = path.join(dir, file);
+                let record;
+                try {
+                    record = JSON.parse(fs.readFileSync(full, 'utf8'));
+                } catch (error) {
+                    try { fs.unlinkSync(full); } catch (e) { /* ignore */ }
+                    continue;
+                }
+                if (!record || record.id !== file.slice(0, -5)) {
+                    try { fs.unlinkSync(full); } catch (error) { /* ignore */ }
+                    continue;
+                }
+                // 同一个 HOME 上另一个还活着的 serve 进程在跑的任务不是“上次崩了留下的”，别动
+                if (Number.isInteger(record.pid) && record.pid !== process.pid && isProcessAlive(record.pid)) continue;
+                const report = { id: record.id, type: record.type, containers: record.containers || [], restored: [], removed: [], skipped: [], failed: [] };
+                for (const item of Array.isArray(record.paused) ? record.paused : []) {
+                    try {
+                        if (item && item.id && item.how === 'stop' && actions.containerIdOf(item.name) === item.id && actions.isStopped && actions.isStopped(item.name)) {
+                            actions.start(item.name);
+                            report.restored.push(item.name);
+                        } else if (item && item.id && item.how !== 'stop' && actions.containerIdOf(item.name) === item.id && actions.isPaused(item.name)) {
+                            actions.unpause(item.name);
+                            report.restored.push(item.name);
+                        } else {
+                            report.skipped.push(item && item.name);
+                        }
+                    } catch (error) {
+                        report.failed.push(item && item.name);
+                    }
+                }
+                const created = record.created || {};
+                for (const item of Array.isArray(created.containers) ? created.containers : []) {
+                    try {
+                        if (item && item.id && actions.containerIdOf(item.name) === item.id) {
+                            actions.removeContainer(item.name);
+                            report.removed.push(item.name);
+                        } else {
+                            report.skipped.push(item && item.name);
+                        }
+                    } catch (error) {
+                        report.failed.push(item && item.name);
+                    }
+                }
+                for (const kind of ['dirs', 'historyFiles']) {
+                    for (const p of Array.isArray(created[kind]) ? created[kind] : []) {
+                        try { actions.removePath(p); report.removed.push(p); } catch (error) { report.failed.push(p); }
+                    }
+                }
+                if (record.partFile) {
+                    try { actions.removePath(record.partFile); } catch (error) { report.failed.push(record.partFile); }
+                }
+                // 有动作没做成（运行时还没起来、删除失败）时保留记录，下次启动再试；全部处理完才删
+                if (report.failed.length) {
+                    handled.push(report);
+                    continue;
+                }
+                try { fs.unlinkSync(full); } catch (error) { /* ignore */ }
+                // 登记成“已中断”，界面能看到
+                const job = makeJob({ type: record.type, containers: report.containers, id: record.id });
+                job.finish('interrupted', { error: 'serve 重启，任务已中断', result: report });
+                handled.push(report);
+            }
+            return handled;
+        }
+    };
+}
+
+// 把请求路径归到某个容器：/api/sessions/<名>/… 与 /api/containers/<名>/…（名字可能是 容器~agent）。
+// 返回 { container, tail }；与容器无关返回 null。
+function containerOfPath(pathname, decode = decodeURIComponent) {
+    const match = /^\/api\/(?:sessions|containers)\/([^/]+)(\/.*)?$/.exec(pathname);
+    if (!match) return null;
+    if (match[1] === 'orphans') return null;
+    let name = match[1];
+    try { name = decode(match[1]); } catch (error) { /* 保持原样 */ }
+    return { container: name.split('~')[0], tail: match[2] || '' };
+}
+
+// 任务期间仍允许的只读请求：读消息、读详情（进度在 /api/jobs 与列表里）
+const READONLY_TAILS = [/^\/messages$/, /^\/detail$/];
+
+/**
+ * 闸门：返回 null 表示放行，否则返回 { status:409, body }。
+ */
+function gateRequest(registry, method, pathname) {
+    const target = containerOfPath(pathname);
+    if (!target) return null;
+    const job = registry.busyFor(target.container);
+    if (!job) return null;
+    if (method === 'GET' && READONLY_TAILS.some(re => re.test(target.tail.split('?')[0]))) return null;
+    return {
+        status: 409,
+        body: { error: job.type === 'export' ? '正在导出，完成后可用' : '正在导入，完成后可用', busy: job.type, jobId: job.id }
+    };
+}
+
+module.exports = { createJobRegistry, JobCancelled, containerOfPath, gateRequest, JOB_ID_RE, jobsDir };