oh-my-agent-web 0.2.0 → 0.4.0

package/dist/server/snapshot/sender.js

@@ -0,0 +1,62 @@
+export const DEFAULT_WINDOW_MS = 60;
+export function createSender(options) {
+    const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+    const stats = {
+        sentSnapshots: 0,
+        coalescedSnapshots: 0,
+        skippedSnapshots: 0,
+        sentEvents: 0,
+        sentReplies: 0,
+    };
+    let pending = null;
+    let lastSentAt = Number.NEGATIVE_INFINITY;
+    let busy = false;
+    const sendNow = () => {
+        if (!pending)
+            return false;
+        options.send({ kind: "snapshot", snapshot: pending });
+        pending = null;
+        stats.sentSnapshots += 1;
+        return true;
+    };
+    return {
+        pushSnapshot(snapshot) {
+            if (pending)
+                stats.coalescedSnapshots += 1;
+            pending = snapshot;
+        },
+        pushEvent(event) {
+            options.send({ kind: "event", event });
+            stats.sentEvents += 1;
+        },
+        pushReply(reply) {
+            options.send({ kind: "reply", reply });
+            stats.sentReplies += 1;
+        },
+        tick(now) {
+            if (!pending)
+                return;
+            if (busy) {
+                stats.skippedSnapshots += 1;
+                return;
+            }
+            if (now - lastSentAt < windowMs)
+                return;
+            if (sendNow())
+                lastSentAt = now;
+        },
+        setBusy(next) {
+            busy = next;
+        },
+        flush(now) {
+            if (sendNow())
+                lastSentAt = now;
+        },
+        stats() {
+            return { ...stats };
+        },
+        hasPendingSnapshot() {
+            return pending !== null;
+        },
+    };
+}

package/dist/server/snapshot/state.js

@@ -0,0 +1,193 @@
+/**
+ * 服务端状态与快照构造（ADR-0012）。
+ *
+ * 服务端持有唯一事实源；`buildSnapshot` 是纯函数：同一份 state 永远得到同一份快照，
+ * 且**丢任意中间帧后，下一帧仍然正确** —— 这正是「快照可丢」能成立的原因。
+ */
+import { SNAPSHOT_MESSAGE_LIMIT, PROTOCOL_VERSION, } from "../protocol.js";
+import { isOutdated } from "../util/upstream-version.js";
+export function emptyRunning() {
+    return { status: "idle", conversationId: null, turnStartedAt: null, streamingText: "", activeTool: null };
+}
+export function createServerState(workspace, engine = "pi") {
+    return {
+        workspace,
+        engine,
+        engines: [],
+        model: null,
+        // ADR-0034：默认全部放行（提示仍然会出现在快照/悬浮牌上，用户可以随时切回「询问」）
+        approvalMode: "allow",
+        engineCapabilities: { approvals: true, tools: true, modelSwitch: true, thinkingLevel: true, resume: true },
+        providers: [],
+        thinkingLevel: null,
+        thinkingLevels: [],
+        sessionStats: null,
+        models: [],
+        piProjects: [],
+        piProjectsVersion: 0,
+        settings: {
+            quickPhrases: [],
+            quickPhrasesEnabled: true,
+            templates: [],
+            projectPrefs: { order: [], pinned: [], aliases: {} },
+            sessionPrefs: { pinned: [], archived: [] },
+            defaultModels: {},
+            thinkCount: 5,
+            thinkTimeoutSec: 20,
+        },
+        actions: [],
+        conversations: [],
+        activeId: null,
+        messages: {},
+        running: emptyRunning(),
+        queued: [],
+        enabledModels: [],
+        statsByConversation: {},
+        modelByConversation: {},
+        thinkingByConversation: {},
+        filesRootByConversation: {},
+        runningByConversation: {},
+        pendingApproval: null,
+        versions: { web: "unknown", engine: null, latest: null },
+        notices: [],
+        terminal: null,
+        files: null,
+    };
+}
+/** 换一份 pi 会话清单：顺手把版本号 +1（快照靠它决定「这一帧要不要带清单」） */
+export function setPiProjects(state, projects) {
+    state.piProjects = projects;
+    state.piProjectsVersion += 1;
+}
+/** 会话元数据刷新（内存态）：updatedAt / messageCount 跟着消息走 */
+export function touchConversationIn(state, conversationId, now, patch = {}) {
+    state.conversations = state.conversations.map((conversation) => conversation.id === conversationId
+        ? {
+            ...conversation,
+            ...patch,
+            updatedAt: now,
+            messageCount: state.messages[conversationId]?.length ?? conversation.messageCount,
+        }
+        : conversation);
+}
+export function createConversation(input) {
+    return {
+        id: input.id,
+        title: input.title,
+        createdAt: input.now,
+        updatedAt: input.now,
+        workspace: input.workspace,
+        messageCount: 0,
+    };
+}
+/** 只取最近 limit 条（ADR-0012：N=100），更早的靠 hasMoreBefore 提示按需拉 */
+/**
+ * @param activeIdOverride 该客户端自己选中的会话（ADR-0033）：
+ *   多标签 / 多设备各自看各自的会话，不再跟着服务端那个全局 activeId 跑。
+ */
+/**
+ * 这个客户端看到的「运行状态」。
+ *
+ * - 没传 activeIdOverride（老路径）：直接用全局 running；
+ * - 传了且正好是全局那个会话：也用全局（它带着流式正文与工具信息）；
+ * - 传了但是别的会话：从 runningByConversation 里取它自己的状态，
+ *   流式正文/工具不属于这条会话，留空。
+ */
+function runningForClient(state, activeId, override) {
+    if (override === undefined || override === state.running.conversationId) {
+        return { ...state.running, activeTool: state.running.activeTool ? { ...state.running.activeTool } : null };
+    }
+    const own = activeId ? state.runningByConversation[activeId] : undefined;
+    return {
+        status: own?.status ?? "idle",
+        conversationId: activeId,
+        turnStartedAt: own?.turnStartedAt ?? null,
+        streamingText: "",
+        activeTool: null,
+    };
+}
+/** 会话级缓存里取该会话的值；没有记录就回落到全局那份 */
+function pickPerConversation(cache, activeId, fallback) {
+    if (!activeId)
+        return fallback;
+    return Object.hasOwn(cache, activeId) ? cache[activeId] : fallback;
+}
+export function buildSnapshot(state, limit = SNAPSHOT_MESSAGE_LIMIT, activeIdOverride, options = {}) {
+    const activeId = activeIdOverride === undefined ? state.activeId : activeIdOverride;
+    const all = activeId ? (state.messages[activeId] ?? []) : [];
+    const messages = all.length > limit ? all.slice(all.length - limit) : all;
+    return {
+        protocolVersion: PROTOCOL_VERSION,
+        engine: state.engine,
+        engines: state.engines.map((option) => ({ ...option, capabilities: { ...option.capabilities } })),
+        model: pickPerConversation(state.modelByConversation, activeId, state.model),
+        approvalMode: state.approvalMode,
+        engineCapabilities: { ...state.engineCapabilities },
+        providers: state.providers.map((provider) => ({
+            ...provider,
+            models: provider.models.map((model) => ({ ...model })),
+        })),
+        thinkingLevel: pickPerConversation(state.thinkingByConversation, activeId, state.thinkingLevel),
+        thinkingLevels: [...state.thinkingLevels],
+        sessionStats: state.sessionStats ? { ...state.sessionStats } : null,
+        models: state.models.map((model) => ({ ...model })),
+        actions: state.actions.map((action) => ({ ...action })),
+        settings: {
+            quickPhrases: [...state.settings.quickPhrases],
+            quickPhrasesEnabled: state.settings.quickPhrasesEnabled,
+            templates: state.settings.templates.map((template) => ({ ...template })),
+            projectPrefs: {
+                order: [...state.settings.projectPrefs.order],
+                pinned: [...state.settings.projectPrefs.pinned],
+                aliases: { ...state.settings.projectPrefs.aliases },
+            },
+            defaultModels: { ...state.settings.defaultModels },
+            sessionPrefs: {
+                pinned: [...state.settings.sessionPrefs.pinned],
+                archived: [...state.settings.sessionPrefs.archived],
+            },
+            thinkCount: state.settings.thinkCount,
+            thinkTimeoutSec: state.settings.thinkTimeoutSec,
+        },
+        ...(options.includeProjects === false
+            ? {}
+            : {
+                piProjects: state.piProjects.map((project) => ({
+                    ...project,
+                    sessions: project.sessions.map((session) => ({ ...session })),
+                })),
+            }),
+        conversations: state.conversations.map((conversation) => ({ ...conversation })),
+        active: {
+            conversationId: activeId,
+            messages: messages.map((message) => ({ ...message, blocks: message.blocks.map((block) => ({ ...block })) })),
+            hasMoreBefore: all.length > messages.length,
+        },
+        // running 也要按客户端的会话算：否则别人在跑时，你在看的会话既不出「引导/排队」，
+        // 也看不到 agent 在工作（但状态栏又显示「工作中」）—— A 方案落地后的连带问题
+        running: runningForClient(state, activeId, activeIdOverride),
+        queued: state.queued.map((item) => ({ ...item })),
+        enabledModels: [...state.enabledModels],
+        runningByConversation: { ...state.runningByConversation },
+        pendingApproval: state.pendingApproval ? { ...state.pendingApproval } : null,
+        // 标不标红在这里算：快照是纯函数，界面拿到的就是一个结论，不用自己比版本号
+        versions: {
+            web: state.versions.web,
+            engine: state.versions.engine,
+            latest: state.versions.latest,
+            outdated: isOutdated(state.versions.latest, state.versions.web),
+        },
+        terminal: state.terminal ? { ...state.terminal } : null,
+        files: (() => {
+            const root = activeId ? state.filesRootByConversation[activeId] : undefined;
+            if (!root)
+                return state.files ? { ...state.files } : null;
+            return { root, treeVersion: state.files?.treeVersion ?? 0 };
+        })(),
+        notices: state.notices.map((notice) => ({ ...notice })),
+    };
+}
+/** 快照体积（字节）—— ADR-0012 的体积护栏用它判断是否需要减小 N */
+export function snapshotBytes(snapshot) {
+    return Buffer.byteLength(JSON.stringify(snapshot), "utf8");
+}

package/dist/server/terminal/terminal-routes.js

@@ -0,0 +1,176 @@
+/**
+ * 终端的 HTTP + SSE 通道（ADR-0027）。
+ *
+ * 为什么不用 WS：WS 是「协议单源」（ADR-0004），加 4 条终端消息要动 protocol / 白名单 / 分发，
+ * 收益不如成本。终端本质是「一条向前读的字节流 + 几条控制请求」，SSE 正好：
+ *   POST /api/terminal/start   起 PTY（cwd = 当前会话工作区）
+ *   GET  /api/terminal/stream  SSE：输出流（text/event-stream）
+ *   POST /api/terminal/input   键盘输入
+ *   POST /api/terminal/resize  窗口尺寸
+ *   POST /api/terminal/stop    关掉 PTY
+ *
+ * 同时只允许 1 个 PTY（ADR-0027 §2）。
+ */
+import { spawn } from "node:child_process";
+import { realpathSync, statSync } from "node:fs";
+import { startTerminal } from "./terminal-session.js";
+export function registerTerminalRoutes(app, options) {
+    /**
+     * 多终端注册表（ADR-0027 增补）：每个终端一个 id，互不影响。
+     * 之前是「全局单例」，所以开第二个终端会把第一个杀掉（用户反馈的"切换终端就退出"）。
+     */
+    const terminals = new Map();
+    /** 被重启/关闭过的 id：迟到的 onExit 一律忽略（否则会污染新终端） */
+    const discarded = new Set();
+    const broadcastFor = (id, chunk) => {
+        const entry = terminals.get(id);
+        if (!entry)
+            return;
+        for (const listener of entry.listeners)
+            listener(chunk);
+    };
+    app.post("/api/terminal/start", async (request, response) => {
+        const workspace = options.workspaceOf();
+        if (!workspace) {
+            response
+                .status(409)
+                .json({ error: { code: "terminal.no_workspace", message: "还没有打开会话（不知道在哪个目录起终端）" } });
+            return;
+        }
+        const body = request.body;
+        const id = typeof body?.id === "string" && body.id !== "" ? body.id : `term-${Date.now().toString(36)}`;
+        // 同一个 id 重复 start = 重启（例如刷新页面），先收掉旧的
+        terminals.get(id)?.session.kill();
+        terminals.delete(id);
+        // 旧 PTY 的 onExit 是异步的：它可能在新终端注册之后才到达。
+        // 用「已废弃的 id 集合」把这类迟到的退出事件丢掉，否则新终端里会冒出「进程已退出」。
+        discarded.add(id);
+        // 指定了 cwd（从项目菜单「在终端中打开」进来）：必须存在且是目录，且以它自身为根
+        let root = workspace;
+        let cwd = workspace;
+        if (typeof body?.cwd === "string" && body.cwd.startsWith("/")) {
+            try {
+                const real = realpathSync(body.cwd);
+                if (statSync(real).isDirectory()) {
+                    root = real;
+                    cwd = real;
+                }
+            }
+            catch {
+                // 路径不可用 → 回落到当前工作区
+            }
+        }
+        const result = await startTerminal({
+            workspaceRoot: root,
+            cwd,
+            cols: body?.cols,
+            rows: body?.rows,
+            handlers: {
+                onData: (chunk) => broadcastFor(id, chunk),
+                onExit: (exitCode) => {
+                    if (discarded.delete(id))
+                        return; // 这条退出属于被替换掉的旧会话
+                    broadcastFor(id, `\r\n[进程已退出，code=${exitCode}]\r\n`);
+                    terminals.delete(id);
+                },
+            },
+        });
+        if (!result.ok) {
+            response.status(503).json({ error: { code: "terminal.start_failed", message: result.error } });
+            return;
+        }
+        terminals.set(id, { session: result.terminal, listeners: new Set() });
+        response.json({ ok: true, id, cols: result.terminal.cols(), rows: result.terminal.rows() });
+    });
+    app.get("/api/terminal/stream", (request, response) => {
+        response.writeHead(200, {
+            "content-type": "text/event-stream",
+            "cache-control": "no-cache",
+            connection: "keep-alive",
+        });
+        response.write(": connected\n\n");
+        const id = typeof request.query.id === "string" ? request.query.id : ([...terminals.keys()].at(-1) ?? "");
+        const entry = terminals.get(id);
+        if (!entry) {
+            response
+                .writeHead(404, { "content-type": "application/json" })
+                .end(JSON.stringify({ error: { code: "terminal.not_found", message: "没有这个终端" } }));
+            return;
+        }
+        const listener = (chunk) => {
+            // SSE 帧里的换行必须转义，否则浏览器会把一帧拆成两条
+            response.write(`data: ${JSON.stringify(chunk)}\n\n`);
+        };
+        entry.listeners.add(listener);
+        request.on("close", () => entry.listeners.delete(listener));
+    });
+    app.post("/api/terminal/input", (request, response) => {
+        const body = request.body;
+        const entry = terminals.get(typeof body?.id === "string" ? body.id : "");
+        if (typeof body?.data === "string" && entry)
+            entry.session.write(body.data);
+        response.json({ ok: true });
+    });
+    app.post("/api/terminal/resize", (request, response) => {
+        const body = request.body;
+        const entry = terminals.get(typeof body?.id === "string" ? body.id : "");
+        if (entry && typeof body?.cols === "number" && typeof body?.rows === "number")
+            entry.session.resize(body.cols, body.rows);
+        response.json({ ok: true });
+    });
+    app.post("/api/terminal/stop", (request, response) => {
+        const body = request.body;
+        const id = typeof body?.id === "string" ? body.id : "";
+        if (id !== "") {
+            terminals.get(id)?.session.kill();
+            terminals.delete(id);
+            discarded.add(id);
+        }
+        response.json({ ok: true });
+    });
+    // 进程退出时统一收拾（不留孤儿 shell）
+    process.on("exit", () => {
+        for (const entry of terminals.values())
+            entry.session.kill();
+    });
+}
+/**
+ * 「在文件中打开」/「在终端中打开」的支撑（ADR-0027 增补）。
+ *
+ * 安全边界（刻意保守）：
+ *   - **只接受绝对路径**，且 realpath 后必须存在、必须是目录；
+ *   - 「在文件中打开」用 `open -R`（**只定位、不执行**）：直接 `open <path>` 遇到 .app/.command
+ *     会**执行**它，这是必须避开的坑；
+ *   - 不读目录内容、不返回任何文件信息，只回 ok。
+ */
+export function registerProjectActions(app, _options) {
+    app.post("/api/projects/reveal", async (request, response) => {
+        const cwd = typeof request.body?.cwd === "string"
+            ? String(request.body.cwd)
+            : "";
+        const safe = await safeDirectory(cwd);
+        if (!safe) {
+            response.status(400).json({ error: { code: "project.bad_path", message: "不是可用的目录路径" } });
+            return;
+        }
+        if (process.platform !== "darwin") {
+            response.status(501).json({ error: { code: "project.unsupported", message: "当前平台暂不支持" } });
+            return;
+        }
+        // -R = 在 Finder 里定位，不执行
+        spawn("open", ["-R", safe], { detached: true, stdio: "ignore" }).unref();
+        response.json({ ok: true });
+    });
+}
+/** 纯函数式的校验：绝对路径 + 存在 + 是目录 */
+async function safeDirectory(cwd) {
+    if (!cwd.startsWith("/"))
+        return null;
+    try {
+        const real = realpathSync(cwd);
+        return statSync(real).isDirectory() ? real : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server/terminal/terminal-session.js

@@ -0,0 +1,140 @@
+/**
+ * 终端会话（ADR-0027）：一个 PTY + 输出节流。
+ *
+ * 为什么必须是 PTY（node-pty）而不是 child_process.spawn：
+ *   vim / top / Ctrl-C / 颜色 / 行编辑，全都依赖"对面是个终端"。用管道跑出来的东西
+ *   在真实使用里几乎不可用（vim 会直接报错），所以这条依赖是必要的。
+ *
+ * 安全与稳定的三条硬约束：
+ *   1. cwd 由调用方给定，**只允许在工作区内**（由调用方用 resolveInsideRoot 保证）；
+ *   2. 环境变量最小化，不把 AGENT_WEB_* 之类内部变量透传给 shell；
+ *   3. 输出**节流合并**（30ms 一批、单批 ≤64KB），否则 `yes` 一条命令就能把进程打爆。
+ */
+import { resolveInsideRoot } from "../util/paths.js";
+import { realpathSync } from "node:fs";
+export const OUTPUT_FLUSH_MS = 30;
+export const MAX_CHUNK_BYTES = 64 * 1024;
+export const MIN_COLS = 20;
+export const MAX_COLS = 400;
+export const MIN_ROWS = 5;
+export const MAX_ROWS = 200;
+/** 纯函数：把前端报上来的尺寸夹到合法区间（防止 0 列导致 PTY 崩） */
+export function clampSize(cols, rows) {
+    const safeCols = Number.isFinite(cols) ? Math.floor(cols) : 80;
+    const safeRows = Number.isFinite(rows) ? Math.floor(rows) : 24;
+    return {
+        cols: Math.min(Math.max(safeCols, MIN_COLS), MAX_COLS),
+        rows: Math.min(Math.max(safeRows, MIN_ROWS), MAX_ROWS),
+    };
+}
+/** 纯函数：给 shell 的最小环境（不透传内部变量，不继承可能的密钥） */
+export function shellEnv(base = process.env) {
+    const keep = ["HOME", "PATH", "SHELL", "USER", "LOGNAME", "TMPDIR", "LANG", "LC_ALL"]; // TERM 必须在下面强制
+    const env = { TERM: "xterm-256color" };
+    for (const key of keep) {
+        const value = base[key];
+        if (typeof value === "string" && value !== "")
+            env[key] = value;
+    }
+    return env;
+}
+/**
+ * 起一个 PTY。`workspaceRoot` 用来兜底 cwd：即使在别处被误用，也不会在任意目录开 shell。
+ */
+export async function startTerminal(options) {
+    const safe = resolveInsideRoot(options.workspaceRoot, options.cwd, realpathSync);
+    if (!safe.ok)
+        return { ok: false, error: safe.reason };
+    let spawn = options.spawnImpl;
+    if (!spawn) {
+        try {
+            // 动态 import：node-pty 是原生模块，装不上时整个服务不该崩（ADR-0027 §影响）
+            spawn = (await import("node-pty")).spawn;
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: `终端不可用（node-pty 未安装或编译失败）：${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    const size = clampSize(options.cols ?? 80, options.rows ?? 24);
+    const shell = process.env.SHELL ?? "/bin/zsh";
+    let pty;
+    try {
+        pty = spawn(shell, ["-l"], {
+            name: "xterm-256color",
+            cwd: safe.path,
+            env: shellEnv(),
+            cols: size.cols,
+            rows: size.rows,
+        });
+    }
+    catch (error) {
+        return { ok: false, error: `起 shell 失败：${error instanceof Error ? error.message : String(error)}` };
+    }
+    // 输出节流：攒到 30ms 再一起推，单批超 64KB 截断（宁可丢显示，不能拖垮进程）
+    let buffer = "";
+    let timer = null;
+    let killed = false;
+    const flush = () => {
+        timer = null;
+        if (buffer === "")
+            return;
+        const chunk = buffer.length > MAX_CHUNK_BYTES ? `${buffer.slice(0, MAX_CHUNK_BYTES)}\r\n[输出过快，已截断]\r\n` : buffer;
+        buffer = "";
+        options.handlers.onData(chunk);
+    };
+    pty.onData((data) => {
+        if (killed)
+            return;
+        buffer += data;
+        if (buffer.length > MAX_CHUNK_BYTES * 4) {
+            // 前端根本不读时别无限攒内存：直接丢到上限
+            buffer = buffer.slice(-MAX_CHUNK_BYTES);
+        }
+        if (timer === null)
+            timer = setTimeout(flush, OUTPUT_FLUSH_MS);
+    });
+    pty.onExit(({ exitCode }) => {
+        killed = true;
+        if (timer !== null)
+            clearTimeout(timer);
+        timer = null;
+        flush();
+        options.handlers.onExit(exitCode);
+    });
+    return {
+        ok: true,
+        terminal: {
+            write: (data) => {
+                if (!killed)
+                    pty.write(data);
+            },
+            resize: (cols, rows) => {
+                if (killed)
+                    return;
+                const next = clampSize(cols, rows);
+                try {
+                    pty.resize(next.cols, next.rows);
+                }
+                catch {
+                    // 已经退出的 PTY resize 会抛，忽略即可
+                }
+            },
+            kill: () => {
+                if (killed)
+                    return;
+                killed = true;
+                try {
+                    pty.kill();
+                }
+                catch {
+                    // 幂等
+                }
+            },
+            cols: () => size.cols,
+            rows: () => size.rows,
+        },
+    };
+}

package/dist/server/uploads/upload-routes.js

@@ -0,0 +1,64 @@
+/**
+ * 附件上传的 HTTP 路由（ADR-0020 §P3）——从 index.ts 抽出（400 行护栏）。
+ *
+ * 两条路由：
+ *   `POST /api/uploads`  原始字节（文件名走 `x-file-name` 头）→ 返回 AttachmentRef
+ *   `GET  /api/uploads/:id`  回显（界面内联显示图片；也是消息里 markdown 引用的落点）
+ *
+ * 刻意用 `express.raw` 而不是 multipart：少一个依赖，而且我们只需要「一堆字节 + 一个文件名」。
+ */
+import express, {} from "express";
+import { isImageMime, MAX_UPLOAD_BYTES } from "./upload-store.js";
+/**
+ * 纯函数：解出上传文件名。
+ *
+ * 两种客户端都要伺候（真实踩过：中文名变成 `æªå¾.png`）：
+ *   - 百分号编码（我们的前端）→ decodeURIComponent；
+ *   - 原样 UTF-8（curl / 其它工具）→ Node 按 **latin1** 解了请求头，得转回 UTF-8。
+ */
+export function decodeFileName(header) {
+    const trimmed = header.trim();
+    if (trimmed === "")
+        return "粘贴的图片";
+    if (/%[0-9a-f]{2}/i.test(trimmed)) {
+        try {
+            return decodeURIComponent(trimmed);
+        }
+        catch {
+            // 落回下面的 latin1 → UTF-8 转换
+        }
+    }
+    const recovered = Buffer.from(trimmed, "latin1").toString("utf8");
+    return recovered.includes("\uFFFD") ? trimmed : recovered;
+}
+export function registerUploadRoutes(app, options) {
+    app.post("/api/uploads", express.raw({ type: () => true, limit: MAX_UPLOAD_BYTES }), async (request, response) => {
+        try {
+            const bytes = request.body instanceof Uint8Array ? request.body : new Uint8Array();
+            const header = request.headers["x-file-name"];
+            const name = decodeFileName(typeof header === "string" ? header : "");
+            const saved = await options.uploadStore.save({ bytes, declaredMime: request.headers["content-type"], name });
+            options.logger.info("收到上传", { id: saved.id, mime: saved.mime, bytes: saved.bytes });
+            response.json({
+                id: saved.id,
+                kind: isImageMime(saved.mime) ? "image" : "file",
+                name: saved.name,
+                mime: saved.mime,
+                bytes: saved.bytes,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            options.logger.warn("上传被拒", { message });
+            response.status(400).json({ error: { code: "upload.rejected", message } });
+        }
+    });
+    app.get("/api/uploads/:id", async (request, response) => {
+        const found = await options.uploadStore.read(request.params.id);
+        if (!found) {
+            response.status(404).json({ error: { code: "upload.not_found", message: "附件不存在或已过期" } });
+            return;
+        }
+        response.type(found.mime).send(found.bytes);
+    });
+}