virlen-remote 0.5.0 → 0.7.0

package/dist/testing/mock-host.js

@@ -23,7 +23,12 @@
 import { BridgeError } from '../protocol/errors.js';
 import { answerActionError, normalizeChoiceAnswer } from '../protocol/answer.js';
 import { COMPRESS_MIN_RATIO, DEFAULT_CONTEXT_WINDOW_TOKENS } from '../protocol/api.js';
+import { COMPRESS_MODE_CAPABILITY, DEFAULT_COMPRESS_MODE, compressModeOf, } from '../protocol/compress.js';
 import { MESSAGE_DELETE_CAPABILITY, MESSAGE_QUOTE_CAPABILITY } from '../protocol/message-actions.js';
+import { MESSAGE_FILE_CAPABILITY, sanitizeFileRefs } from '../protocol/message-files.js';
+import { SESSION_AGENT_CAPABILITY } from '../protocol/agents.js';
+import { summarizeToolArgs, formatToolArgs } from '../protocol/tool-args.js';
+import { FILE_BROWSE_CAPABILITY, FILE_CHUNK_BYTES, FILE_DOWNLOAD_CAPABILITY, FILE_EDIT_CAPABILITY, FILE_EDIT_MAX_BYTES, FILE_LIST_MAX_ENTRIES, FILE_UPLOAD_CAPABILITY, FILE_UPLOAD_MAX_BYTES, base64ToBytes, baseNameOfPath, bytesToBase64, compareFileEntries, duplicateNameCandidate, fileTransferDeniedReason, formatFileSize, isEditableFileName, isSafeEntryName, mimeTypeOf, normalizeRelPath, previewKindOf, } from '../protocol/files.js';
 /** 演示用模型服务（与 `sessions` 里的 provider 字段一致）。 */
 const DEMO_PROVIDERS = [
     { id: 'p-openai', name: 'OpenAI（演示）', models: ['gpt-4o', 'gpt-4o-mini'] },
@@ -31,6 +36,91 @@ const DEMO_PROVIDERS = [
 ];
 /** 演示用工作目录候选集（新建会话只能从这里选）。 */
 const DEMO_WORKSPACES = ['E:/code/virlen-demo', 'E:/code/another-project'];
+/**
+ * 演示文件树的固定修改时刻 —— 不取 `Date.now()`：否则用例只能对着「大于某刻」断言，
+ * 而手机上要显示「3 分钟前修改」时又得再多一层换算。
+ */
+const DEMO_FILE_MTIME = Date.UTC(2026, 9, 1, 12, 0, 0);
+/**
+ * 标准 1×1 透明 PNG（68 字节）。
+ *
+ * 为什么放一个**真的**图片字节而不是随便一段文本叫 `logo.png`：图片预览这条路要验证的是
+ * 「字节 → base64 → Blob → ObjectURL → <img> 真的能显示」，而假图片会让这条路永远发绿灯。
+ */
+const DEMO_PNG_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
+/** 演示文件树的初始内容（文本 / base64 两种写法）。 */
+const DEMO_TREE_SPEC = [
+    {
+        path: 'README.md',
+        text: '# Virlen 演示项目\n\n这是一个用于验证**手机端文件浏览**的演示目录。\n\n- `src/` 下有 TypeScript 源码\n- `assets/logo.png` 是一张小图\n- `build/app.bin` 是未知类型（只能下载）\n',
+    },
+    {
+        path: 'src/index.ts',
+        text: [
+            // ⚠️ 演示内容里**不要**写相对导入说明符（构建脚本会把产物中所有形如相对导入的字符串
+            // 补上 `.js` 后缀，于是这段演示文本会被误报一句告警）。用路径别名即可。
+            "import { createApp } from '@/app'",
+            '',
+            'const app = createApp({ port: 3000 })',
+            'app.start()',
+            '',
+        ].join('\n'),
+    },
+    {
+        path: 'src/store/chat.ts',
+        text: [
+            'export interface ChatState {',
+            '  messages: string[]',
+            '  working: boolean',
+            '}',
+            '',
+            'export const INITIAL: ChatState = { messages: [], working: false }',
+            '',
+        ].join('\n'),
+    },
+    { path: 'src/app.ts', text: 'export function createApp(config: { port: number }) {\n  return { start: () => console.log(config.port) }\n}\n' },
+    {
+        path: 'package.json',
+        text: '{\n  "name": "virlen-demo",\n  "version": "1.0.0",\n  "private": true\n}\n',
+    },
+    { path: 'docs/notes.txt', text: '手机端浏览这个目录时，应该看到 src/ 与 docs/ 两个子目录。\n' },
+    { path: '.gitignore', text: 'node_modules/\ndist/\n' },
+    { path: 'assets/logo.png', base64: DEMO_PNG_BASE64 },
+    // 未知扩展名 → `previewKindOf` 给 binary → 手机端只给「下载」（这条路必须有用例盯着）
+    { path: 'build/app.bin', text: 'not-a-real-binary-but-unknown-extension' },
+];
+/** 建一份演示文件树（相对工作目录的路径 → 文件）。每份工作目录各得一份，互不影响。 */
+function createDemoTree() {
+    const encoder = new TextEncoder();
+    const tree = new Map();
+    for (const item of DEMO_TREE_SPEC) {
+        tree.set(item.path, {
+            bytes: item.base64 ? base64ToBytes(item.base64) : encoder.encode(item.text ?? ''),
+            mtimeMs: DEMO_FILE_MTIME,
+        });
+    }
+    return tree;
+}
+/**
+ * 演示用 Agent 候选集（与上面 `sessions` 里的 `agentId` / `agentName` 一致）。
+ *
+ * 两个 Agent 故意配**不同的默认模型 / 默认目录**：手机端切换 Agent 时能看出联动，
+ * 也能验证「不传模型 / 目录 = 用所选 Agent 的默认值」这条语义。
+ */
+const DEMO_AGENTS = [
+    {
+        id: 'agent-virlen',
+        name: 'Virlen',
+        defaultModel: { providerConfigId: 'p-openai', modelId: 'gpt-4o' },
+        defaultWorkspace: DEMO_WORKSPACES[0],
+    },
+    {
+        id: 'agent-reviewer',
+        name: '代码评审员',
+        defaultModel: { providerConfigId: 'p-anthropic', modelId: 'claude-sonnet-4' },
+        defaultWorkspace: DEMO_WORKSPACES[1],
+    },
+];
 /**
  * 「只引用了消息、没写正文」时电脑侧补的那句话。
  *
@@ -40,6 +130,8 @@ const DEMO_WORKSPACES = ['E:/code/virlen-demo', 'E:/code/another-project'];
  * （真要与 i18n 一致，那是 virlen-app 侧的跨端用例该盯的事）。
  */
 const QUOTE_ONLY_TEXT = '请针对引用的消息回复';
+/** 只带文件、不写正文时的兜底正文（与电脑侧 `buildUserContent` 的「看看这些文件」同义）。 */
+const FILE_ONLY_TEXT = '看看这些文件';
 export function createMockHostDataSource(options = {}) {
     const streamSteps = options.streamSteps ?? 3;
     const streamDelayMs = options.streamDelayMs ?? 40;
@@ -106,6 +198,16 @@ export function createMockHostDataSource(options = {}) {
             text: 'src/index.ts\nsrc/store.ts\nsrc/ui/pages/Chat.tsx',
             createdAt: Date.now() - 105000,
             toolName: 'list_files',
+            /*
+             * 入参摘要与真实电脑侧**同源**（`summarizeToolArgs`）：演示宿主不手写一行
+             * 会与真实格式化规则打架的假数据 —— 那种假数据会让联调时看到的现象失去意义。
+             */
+            toolArgs: summarizeToolArgs('list_files', { path: 'src' }),
+            /*
+             * 展开区的完整入参同样**同源**（`formatToolArgs`）：演示宿主手写一段会在形态上
+             * 与真实电脑侧打架（缩进 / 路径缩不缩短），那会让联调时看到的现象失去意义。
+             */
+            toolArgsFull: formatToolArgs({ path: 'src' }),
         }, {
             id: 'empty-assistant',
             role: 'assistant',
@@ -212,6 +314,22 @@ export function createMockHostDataSource(options = {}) {
             runtime: { working: true, ...(progress ? { toolProgress: progress } : {}) },
         });
     }
+    /** 推一次「正在执行中的工具」（`RuntimeDTO.runningTools`）—— 同上，受订阅门约束。 */
+    function setRunningTools(sessionId, tools) {
+        if (tools === null) {
+            // 跑完了：没有执行中的工具，也不再工作（真机上这一步之后要么空闲、要么出新消息）
+            emitFor(sessionId, 'host.event.session.runtime.changed', {
+                sessionId,
+                runtime: { working: false },
+            });
+            return;
+        }
+        emitFor(sessionId, 'host.event.session.runtime.changed', {
+            sessionId,
+            // 工具在执行 → 一定是 working；空数组即「都执行完了，但本轮还没结束」
+            runtime: { working: true, ...(tools.length > 0 ? { runningTools: tools } : {}) },
+        });
+    }
     function contextOf(sessionId) {
         const tokens = contextTokens.get(sessionId);
         return {
@@ -219,6 +337,80 @@ export function createMockHostDataSource(options = {}) {
             windowTokens: DEFAULT_CONTEXT_WINDOW_TOKENS,
         };
     }
+    /* ───────────────────── §37：演示文件树（手机端文件浏览 / 上传） ───────────────────── */
+    /** 各工作目录一份演示文件树（懒建：没碰过就没有）。 */
+    const trees = new Map();
+    function treeOf(sessionId) {
+        const workspace = sessions.find((s) => s.id === sessionId)?.workspace;
+        if (!workspace)
+            throw new BridgeError('E_NOT_FOUND', `session not found: ${sessionId}`);
+        let tree = trees.get(workspace);
+        if (!tree) {
+            tree = createDemoTree();
+            trees.set(workspace, tree);
+        }
+        return tree;
+    }
+    /**
+     * 单调递增的修改时刻。
+     *
+     * 不用裸 `Date.now()`：同毫秒内的两次保存会拿到**相同**的 mtime，冲突就检不出来 ——
+     * 而「连续存两次」正是这条路径最常见的用法。
+     */
+    let mtimeSeq = 0;
+    function nowMtime() {
+        mtimeSeq = Math.max(Date.now(), mtimeSeq + 1);
+        return mtimeSeq;
+    }
+    /**
+     * 非中继门槛 —— **与真实电脑侧同一句文案**（`fileTransferDeniedReason`），
+     * 差别只在模拟开关：`MockHostOptions.fileLinkKind`。
+     */
+    function assertFileLinkUsable() {
+        const reason = fileTransferDeniedReason(options.fileLinkKind ?? 'direct');
+        if (reason)
+            throw new BridgeError('E_DENIED', reason);
+    }
+    /** 目录是否存在（目录由路径前缀隐式推出；根目录恒存在）。 */
+    function dirExists(tree, relPath) {
+        if (!relPath)
+            return true;
+        const prefix = `${relPath}/`;
+        for (const key of tree.keys())
+            if (key.startsWith(prefix))
+                return true;
+        return false;
+    }
+    /** 把扁平的文件表按当前层拆成条目（目录在前、按名排序，超过上限即截断）。 */
+    function entriesOf(tree, relPath) {
+        const prefix = relPath ? `${relPath}/` : '';
+        const byName = new Map();
+        for (const [path, file] of tree) {
+            if (!path.startsWith(prefix))
+                continue;
+            const rest = path.slice(prefix.length);
+            const slash = rest.indexOf('/');
+            if (slash < 0) {
+                byName.set(rest, { name: rest, isDir: false, size: file.bytes.length, mtimeMs: file.mtimeMs });
+            }
+            else {
+                const dir = rest.slice(0, slash);
+                if (!byName.has(dir))
+                    byName.set(dir, { name: dir, isDir: true, size: 0, mtimeMs: DEMO_FILE_MTIME });
+            }
+        }
+        const all = [...byName.values()].sort(compareFileEntries);
+        return { entries: all.slice(0, FILE_LIST_MAX_ENTRIES), truncated: all.length > FILE_LIST_MAX_ENTRIES };
+    }
+    const uploads = new Map();
+    /** 最后一次真正执行的压缩（见 `MockHostDataSource.lastCompress`）。 */
+    let lastCompress = null;
+    function requireUpload(uploadId) {
+        const upload = uploads.get(uploadId);
+        if (!upload)
+            throw new BridgeError('E_NOT_FOUND', `上传任务不存在或已结束：${uploadId}`);
+        return upload;
+    }
     const host = {
         calls,
         bind(fn) {
@@ -268,10 +460,26 @@ export function createMockHostDataSource(options = {}) {
                     'session.workspace',
                     'session.context',
                     'session.compress',
+                    // 压缩方式（§22）：mock 真的按 `CompressParams.mode` 出不同产物，故如实声明 ——
+                    // 不声明的话手机端只会渲染一个「压缩上下文」按钮，用例就测不到选择器那条路
+                    COMPRESS_MODE_CAPABILITY,
+                    // Agent 选择：mock 确实按候选集校验 agentId（见 createSession），故如实声明 ——
+                    // 不声明的话手机端会隐藏选择器，用例就测不到真实链路
+                    SESSION_AGENT_CAPABILITY,
                     // 消息级操作：mock 确实实现了这两项（引用进内容块 / 截断删除），故如实声明 ——
                     // 不声明的话手机端会隐藏入口，用例就测不到真实链路
                     MESSAGE_QUOTE_CAPABILITY,
                     MESSAGE_DELETE_CAPABILITY,
+                    // 文件引用（`SendParams.files`）：mock 真的做两步 —— 校验归一（`sanitizeFileRefs`，
+                    // 与真电脑侧同一份）与「文件块不进 `text`」的投影规则 —— 故如实声明
+                    MESSAGE_FILE_CAPABILITY,
+                    // §37：文件四档 —— mock 真的按这四档实现了（列 / 读 / 写 / 覆写），故如实声明
+                    FILE_BROWSE_CAPABILITY,
+                    FILE_DOWNLOAD_CAPABILITY,
+                    FILE_UPLOAD_CAPABILITY,
+                    // 覆写已有文件（编辑保存）：mock 真的按「目标必须存在 + mtime/size 校验 + 不改名」
+                    // 实现了，故如实声明 —— 不声明的话手机端只会给只读预览，用例就测不到编辑那条路
+                    FILE_EDIT_CAPABILITY,
                 ],
                 paired: true,
                 deviceName: 'Virlen 电脑（演示）',
@@ -322,14 +530,27 @@ export function createMockHostDataSource(options = {}) {
             if (!list)
                 throw new BridgeError('E_NOT_FOUND', `session not found: ${params.sessionId}`);
             const quotes = params.quotes ?? [];
+            /*
+             * 文件引用（§37 的延伸）：与真电脑侧**同一个校验口径**（`sanitizeFileRefs`）——
+             * 形状非法 / 超上限 → `E_BAD_REQUEST` 拒整条。mock 若比真机宽松（比如照单全收），
+             * 手机端侧的处理分支就永远测不到，真机上才表现为「发了但什么都没发生」。
+             */
+            const sanitized = sanitizeFileRefs(params.files);
+            if (!sanitized.ok) {
+                throw new BridgeError('E_BAD_REQUEST', sanitized.reason);
+            }
+            const files = sanitized.files;
             const userMessage = {
                 id: nextId('u'),
                 role: 'user',
-                // 与真实电脑侧的白名单投影同一条规则：引用**不进 `text`**（而是走 `quotes`），
-                // 否则客户端会把它显示两遍（引用条 + 正文里的 `[引用] …`）
-                text: params.text || (quotes.length > 0 ? QUOTE_ONLY_TEXT : ''),
+                // 与真实电脑侧的白名单投影同一条规则：引用与文件都**不进 `text`**
+                // （引用走 `quotes`、文件走 `files`），否则客户端会各显示两遍
+                // （引用条 / 文件 chip + 正文里的 `[引用] …` / `[文件] …`）
+                text: params.text || (quotes.length > 0 ? QUOTE_ONLY_TEXT : files.length > 0 ? FILE_ONLY_TEXT : ''),
                 createdAt: Date.now(),
                 ...(quotes.length > 0 ? { quotes: quotes.map((q) => ({ ...q })) } : {}),
+                // 无文件则整个字段不带（与 `quotes` 同一条纪律：不为旧手机端凭空多出一个空数组）
+                ...(files.length > 0 ? { files: files.map((f) => ({ ...f })) } : {}),
             };
             list.push(userMessage);
             emitFor(params.sessionId, 'host.event.message.added', { sessionId: params.sessionId, message: userMessage });
@@ -459,15 +680,24 @@ export function createMockHostDataSource(options = {}) {
                 }
                 workspace = match;
             }
-            const model = resolveModel(params.providerConfigId, params.modelId);
+            /**
+             * Agent：**与真实电脑侧同一条防线** —— id 必须来自 `host.agent.list` 的候选集，
+             * 手机不能自造（未知 id 即 `E_BAD_REQUEST`）。不传 = 默认 Agent。
+             */
+            const agent = params.agentId != null ? DEMO_AGENTS.find((a) => a.id === params.agentId) : undefined;
+            if (params.agentId != null && !agent) {
+                throw new BridgeError('E_BAD_REQUEST', `Agent 不存在：${params.agentId}`);
+            }
+            // 模型：手机没给就用**所选 Agent** 的默认模型（与真实电脑侧 createSession 同序）
+            const model = resolveModel(params.providerConfigId ?? agent?.defaultModel?.providerConfigId, params.modelId ?? agent?.defaultModel?.modelId);
             sessions.unshift({
                 id,
                 title: params.title || '手机新建的会话',
                 updatedAt: Date.now(),
                 working: false,
-                agentId: 'agent-virlen',
-                agentName: 'Virlen',
-                workspace: workspace ?? DEMO_WORKSPACES[0],
+                agentId: agent?.id ?? 'agent-virlen',
+                agentName: agent?.name ?? 'Virlen',
+                workspace: workspace ?? agent?.defaultWorkspace ?? DEMO_WORKSPACES[0],
                 ...model,
             });
             messages.set(id, []);
@@ -540,11 +770,18 @@ export function createMockHostDataSource(options = {}) {
             bumpContext(params.sessionId, Math.max(0, (contextTokens.get(params.sessionId) ?? 0) - 1000));
             return { ok: true };
         },
-        // ── §22：模型 / 工作目录 / 上下文 ──
+        // ── §22：模型 / Agent / 工作目录 / 上下文 ──
         async listModels() {
             calls.push('host.model.list');
             return DEMO_PROVIDERS.map((p) => ({ ...p, models: [...p.models] }));
         },
+        async listAgents() {
+            calls.push('host.agent.list');
+            return DEMO_AGENTS.map((a) => ({
+                ...a,
+                ...(a.defaultModel ? { defaultModel: { ...a.defaultModel } } : {}),
+            }));
+        },
         async setModel(params) {
             calls.push('host.session.setModel');
             const session = sessions.find((s) => s.id === params.sessionId);
@@ -570,14 +807,22 @@ export function createMockHostDataSource(options = {}) {
             return contextOf(params.sessionId);
         },
         /**
-         * 压缩上下文：**与真实电脑侧同判据**（confirm + 最小占用比例），
+         * 压缩上下文：**与真实电脑侧同判据**（confirm + 最小占用比例 + 方式可辨认），
          * 然后把消息换成一条 summary，并推 `messages.reset`（手机重拉窗口）。
+         *
+         * `mode` 不同则产物不同（`ai` 是一句摘要口吻、`raw` 是「历史已重排为文本」）——
+         * 两种方式的差别在真机上恰恰就是产物形态，mock 若给同一句文本，两条支路就分不开。
          */
         async compress(params) {
             calls.push('host.session.compress');
             if (params.confirm !== true) {
                 throw new BridgeError('E_CONFIRM_REQUIRED', '压缩上下文需二次确认（confirm:true）');
             }
+            // 没传 = 用缺省（真实电脑侧是「设置里的 contextCompressMode」）；传了但不认识 → 拒
+            const mode = params.mode == null ? DEFAULT_COMPRESS_MODE : compressModeOf(params.mode);
+            if (!mode) {
+                throw new BridgeError('E_BAD_REQUEST', `未知的压缩方式: ${String(params.mode)}`);
+            }
             if (!sessions.some((s) => s.id === params.sessionId)) {
                 throw new BridgeError('E_NOT_FOUND', `session not found: ${params.sessionId}`);
             }
@@ -589,9 +834,12 @@ export function createMockHostDataSource(options = {}) {
             const summary = {
                 id: nextId('sum'),
                 role: 'system',
-                text: '[上下文摘要] 之前的内容已压缩为摘要。',
+                text: mode === 'raw'
+                    ? '[上下文摘要] 正文压缩：整段历史已本地渲染为一段文本（正文一字未删）。'
+                    : '[上下文摘要] 之前的内容已压缩为摘要。',
                 createdAt: Date.now(),
             };
+            lastCompress = { sessionId: params.sessionId, mode };
             messages.set(params.sessionId, [summary]);
             emitFor(params.sessionId, 'host.event.session.messages.reset', { sessionId: params.sessionId });
             emitFor(params.sessionId, 'host.event.message.added', { sessionId: params.sessionId, message: summary });
@@ -601,6 +849,187 @@ export function createMockHostDataSource(options = {}) {
         /** 手动推一次占用变化（harness 按钮 / 测试用）。 */
         bumpContext,
         setToolProgress,
+        setRunningTools,
+        // ── §37：工作目录文件（与真实电脑侧同几条纪律：非中继拒 / 分块 / 临时态不落盘）──
+        async listFiles(params) {
+            calls.push('host.file.list');
+            assertFileLinkUsable();
+            const tree = treeOf(params.sessionId);
+            const relPath = normalizeRelPath(params.path ?? '');
+            if (!dirExists(tree, relPath)) {
+                throw new BridgeError('E_NOT_FOUND', `目录不存在：${relPath || '/'}`);
+            }
+            const { entries, truncated } = entriesOf(tree, relPath);
+            const workspace = sessions.find((s) => s.id === params.sessionId)?.workspace ?? '';
+            return {
+                relPath,
+                absPath: relPath ? `${workspace}/${relPath}` : workspace,
+                entries,
+                ...(truncated ? { truncated: true } : {}),
+            };
+        },
+        async readFile(params) {
+            calls.push('host.file.read');
+            assertFileLinkUsable();
+            const relPath = normalizeRelPath(params.path);
+            const file = treeOf(params.sessionId).get(relPath);
+            if (!file)
+                throw new BridgeError('E_NOT_FOUND', `文件不存在：${relPath}`);
+            const bytes = file.bytes;
+            const offset = Math.max(0, Math.floor(params.offset ?? 0));
+            const want = Math.max(1, Math.floor(params.length ?? FILE_CHUNK_BYTES));
+            const slice = bytes.subarray(offset, offset + Math.min(want, FILE_CHUNK_BYTES));
+            const name = baseNameOfPath(relPath);
+            return {
+                data: bytesToBase64(slice),
+                offset,
+                size: bytes.length,
+                eof: offset + slice.length >= bytes.length,
+                kind: previewKindOf(name),
+                mime: mimeTypeOf(name),
+                // 编辑保存的冲突校验靠它（手机端打开时记下、保存时回传）
+                mtimeMs: file.mtimeMs,
+            };
+        },
+        async beginFileWrite(params) {
+            calls.push('host.file.write.begin');
+            assertFileLinkUsable();
+            const tree = treeOf(params.sessionId);
+            const dir = normalizeRelPath(params.dir ?? '');
+            const target = (n) => (dir ? `${dir}/${n}` : n);
+            if (!isSafeEntryName(params.name)) {
+                throw new BridgeError('E_BAD_REQUEST', `文件名不合法：${params.name}`);
+            }
+            if (!Number.isFinite(params.size) || params.size < 0) {
+                throw new BridgeError('E_BAD_REQUEST', '文件大小非法');
+            }
+            // 超限在**开始前**就拒（而不是传到一半才说）—— 这是 u91cf 级纪律，与真实电脑侧同一条
+            if (params.size > FILE_UPLOAD_MAX_BYTES) {
+                throw new BridgeError('E_BAD_REQUEST', `文件超过上限（${formatFileSize(FILE_UPLOAD_MAX_BYTES)}）`);
+            }
+            if (!dirExists(tree, dir))
+                throw new BridgeError('E_NOT_FOUND', `目录不存在：${dir || '/'}`);
+            /*
+             * ── 覆写（编辑保存）：与上传是**两条不同的路** ──
+             * 这里的每一条都与真实电脑侧逐条对齐（否则手机端用例在 mock 上跑出来的行为不算数）：
+             * 目标必须已存在、只收可编辑的扩展名、按编辑上限夹一次、mtime/size 不符即冲突。
+             */
+            if (params.overwrite) {
+                const existing = tree.get(target(params.name));
+                if (!existing) {
+                    throw new BridgeError('E_NOT_FOUND', `文件不存在：${target(params.name)}`);
+                }
+                if (!isEditableFileName(params.name)) {
+                    throw new BridgeError('E_BAD_REQUEST', `这类文件不支持编辑：${params.name}`);
+                }
+                if (params.size > FILE_EDIT_MAX_BYTES) {
+                    throw new BridgeError('E_BAD_REQUEST', `文件超过编辑上限（${formatFileSize(FILE_EDIT_MAX_BYTES)}）`);
+                }
+                if (params.expectMtimeMs != null && params.expectMtimeMs !== existing.mtimeMs) {
+                    throw new BridgeError('E_CONFLICT', '电脑上的这份文件已经变了，请重新载入');
+                }
+                if (params.expectSize != null && params.expectSize !== existing.bytes.length) {
+                    throw new BridgeError('E_CONFLICT', '电脑上的这份文件已经变了，请重新载入');
+                }
+                const editId = nextId('up');
+                uploads.set(editId, {
+                    sessionId: params.sessionId,
+                    dir,
+                    name: params.name,
+                    relPath: target(params.name),
+                    bytes: new Uint8Array(params.size),
+                    received: 0,
+                    overwrite: true,
+                });
+                return { uploadId: editId, name: params.name, relPath: target(params.name), received: 0 };
+            }
+            let name = params.name;
+            if (tree.has(target(name))) {
+                if ((params.onConflict ?? 'rename') === 'reject') {
+                    throw new BridgeError('E_CONFLICT', `同名文件已存在：${name}`);
+                }
+                let index = 1;
+                for (; index <= 100; index++) {
+                    const candidate = duplicateNameCandidate(params.name, index);
+                    if (!tree.has(target(candidate))) {
+                        name = candidate;
+                        break;
+                    }
+                }
+                if (index > 100)
+                    throw new BridgeError('E_CONFLICT', '同名文件过多，无法自动改名');
+            }
+            const uploadId = nextId('up');
+            uploads.set(uploadId, {
+                sessionId: params.sessionId,
+                dir,
+                name,
+                relPath: target(name),
+                bytes: new Uint8Array(params.size),
+                received: 0,
+            });
+            return { uploadId, name, relPath: target(name), received: 0 };
+        },
+        async writeFileChunk(params) {
+            calls.push('host.file.write.chunk');
+            assertFileLinkUsable();
+            const upload = requireUpload(params.uploadId);
+            // 乱序即拒：拼接错位得到的是一份「看起来成功了」的坏文件，比报错难查得多
+            if (params.offset !== upload.received) {
+                throw new BridgeError('E_CONFLICT', `分块偏移不对：期望 ${upload.received}，收到 ${params.offset}`);
+            }
+            const chunk = base64ToBytes(params.data);
+            if (upload.received + chunk.length > upload.bytes.length) {
+                throw new BridgeError('E_BAD_REQUEST', '写入字节数超过申报的文件大小');
+            }
+            upload.bytes.set(chunk, upload.received);
+            upload.received += chunk.length;
+            return { received: upload.received };
+        },
+        async finishFileWrite(params) {
+            calls.push('host.file.write.finish');
+            assertFileLinkUsable();
+            const upload = requireUpload(params.uploadId);
+            // 字节数不符就不落盘：申报 1MB 只收到 300KB 时，用户在电脑上得到的是一份坏文件
+            if (upload.received !== upload.bytes.length) {
+                throw new BridgeError('E_BAD_REQUEST', `文件未传完：${upload.received}/${upload.bytes.length}`);
+            }
+            uploads.delete(params.uploadId);
+            // 写盘即换 mtime（编辑保存的冲突校验靠它）
+            const mtimeMs = nowMtime();
+            treeOf(upload.sessionId).set(upload.relPath, { bytes: upload.bytes, mtimeMs });
+            // 覆写与上传的收尾差别只有一句注释那么大：**同一个 relPath**，不做冲突改名
+            return { name: upload.name, relPath: upload.relPath, size: upload.bytes.length, mtimeMs };
+        },
+        /**
+         * 放弃上传：**不过非中继门槛**（只删自己的临时态）。
+         *
+         * 为何例外：上传开始后链路可能刚好被换成中继（或断了），而那时用户/手机端恰恰最需要
+         * 把临时文件清掉。在一个只做清理的动作上又加一道链路门，只会把临时文件永久留在用户项目里。
+         */
+        async abortFileWrite(params) {
+            calls.push('host.file.write.abort');
+            uploads.delete(params.uploadId);
+            return { ok: true };
+        },
+        /** 测试 / harness：直接读演示文件树里的一个文件（`null` = 不存在）。 */
+        readMockFile(sessionId, relPath) {
+            const file = treeOf(sessionId).get(normalizeRelPath(relPath));
+            return file ? file.bytes.slice() : null;
+        },
+        /** 测试 / harness：往演示文件树里放一个文件（目录隐式创建）——模拟「电脑上有人改了它」。 */
+        writeMockFile(sessionId, relPath, content) {
+            const data = typeof content === 'string' ? new TextEncoder().encode(content) : content;
+            treeOf(sessionId).set(normalizeRelPath(relPath), { bytes: data, mtimeMs: nowMtime() });
+        },
+        /** 测试 / harness：当前文件树里的全部相对路径（排序后）。 */
+        listMockFiles(sessionId) {
+            return [...treeOf(sessionId).keys()].sort();
+        },
+        /** 测试 / harness：最后一次真正执行的压缩（含**实际生效的方式**）。 */
+        lastCompress() {
+            return lastCompress;
+        },
     };
     return host;
 }