ctx.filePreview（wire 命名空间 filePreview）暴露六个生成的 Remote 方法：

• capabilities()——零会话可用性握手，返回 { protocolVersion: 1 }；浏览器半只在握手成功后安装 UI 面。

• list(agent)——对 agent.session.events 的纯折叠：read/write/edit 的 tool/call 贡献展示路径，这些工具的已完结嵌套 PTC tool/ptc-dispatch 同样计入（失败的派发不记录；条目借用根调用的 turn/step）。携带 diffs 元数据的 write/edit tool/result 把每次改动按事件序追加进条目，lastDiff 保留为最后一次。响应携带条目、最后扫描的 seq，以及是否触达 maxFiles。折叠本身不访问文件系统；captureBashWrites 开启时并入采集器验证过的 bash 写入路径。返回前按会话 cwd 解析每条路径并 stat，只保留当前仍存在的常规文件——日志折叠是历史，产物列表只看磁盘现状（某回合写后又清理的临时脚本不再是产物）；存在性每次调用都现查（不随日志折叠缓存）。

• read(agent, path, signal)——以会话 cwd 为基准解析 path，返回 kind: 'text'（超过 maxReadBytes 截断并标记 truncated）；web 宿主上图片返回 kind: 'image' 及浏览器可加载 URL——字节走专门的 /file-preview-image/<sessionId>/<path> 路由，仅当组合了可选的 webServer 与 agents 服务时注册；无 web 宿主返回 binary——否则返回分类提示：binary（二进制扩展名或 NUL 字节；绝不读取）、missing、too-large、error（含消息）。

• reveal(agent, path, signal)——在宿主文件管理器中打开文件所在文件夹并选中它，全程无 shell，走 @deepseek-ai/dsh-native-command：macOS open -R、Windows explorer /select,<path>、WSL 经 wslpath、桌面 Linux 依次尝试 nautilus/dolphin/nemo --select。选中返回 { revealed: true }，否则 false 及 reason: 'missing'（目标不存在）或 'select-failed'（无可用文件管理器——调用方改开父文件夹，手势总能落在可见处）。不写入任何东西。

• openExternal(agent, path, app, signal)——在指定宿主应用中打开文件（「在 IDE 打开」手势）：官方 open-in-app 路由只收目录，文件级打开走这里——macOS open -a <App> <path>，同样无 shell。app 是官方 open-in-app catalog id（客户端经 /open-in-app/apps 探测）；id → .app 名映射在 open-external.ts（镜像官方 catalog 的 darwin 条目）。非 macOS 或未知 id 返回 { opened: false, reason }，客户端据此隐藏手势。不写入任何东西。

• turnFiles(agent)——每个回合的文件变更，回合卡片与 list 同源但不去重：同一文件在两个回合改过，两个分组都有它——每张卡片精确列出该回合改了什么。行数增减由 result diff 求和；折叠按会话缓存、由日志水位线失效，响应携带水位线供客户端自缓存。与 list 一样，返回前按会话 cwd 校验存在性，只保留当前仍存在的文件（被清理的临时脚本不占卡片）。

bash 写入采集器：监听每个会话的 bash tool/call/tool/result 配对，提取高精度写入目标（cat > path heredoc、单 > 重定向、tee 非追加、sed -i），按宿主环境与会话 cwd 展开 $VAR/~/相对路径，只记录 fs.stat 确认为文件的路径（宁缺毋滥）。采集结果存于按会话的内存登记表，session/created 时重放会话自身历史重建——宿主重启后不丢；会话日志本身绝不被改动（官方 Session.append 无法给插件事件标 ignorable——见 docs/upstream-seam-registry.md 的 S2 条目）。bash 采集的文件没有 diff 历史；预览与普通条目一样通过 read 读当前内容。

浏览器半（src/client/）：

• src/client/index.ts —— apply：挂载 filePreview Remote 并执行零会话 capabilities() 握手；成功后由 installFilePreviewSurfaces 注册所有 UI 面并统一卸载；turnTail 的 list 臂同时注册官方 deliverables 条目的遮蔽体
• src/client/definition.tsx —— page-type tab 的注册表定义（guide 入口 + dsh-resource://file/** 可渲染后缀认领）与认领后缀清单
• src/client/FilePreviewTab.tsx —— 右栏「产物」页（列表 + 详情视图）
• src/client/preview.ts —— 适配层：filePreview wire kind → 内核 PreviewRead、字典适配（详情页的头部与预览栈来自共享内核 @khorsheed/dsh-client-ui-content-preview，源码面内联）
• src/client/DiffHistory.tsx —— 逐次 write/edit diff 步进（本插件独有）
• src/client/mentions-wrap.ts —— mention 打开方向统一进右栏的就地包装（缝 S1 尾巴）
• src/client/open-in-app.ts —— 官方 open-in-app 探测（行动作可见性）
• src/client/TurnFileRow.tsx —— 每回合的「N 个产物」卡片

纯增量插件：宿主半是一个 Remote 服务，浏览器半经官方 ctx.remote.$mount 通道自挂载该 Remote，注册一个右栏 tab 类型（ctx.sidebarRightTabs + keyed sidebar.right.pane.tab seat）与一个回合文件行（conversation.chat.turnTail——0.1.6-alpha.2 起该槽为 list 语义，本行另注册一条同官方 deliverables cell id、priority -1 的空体遮蔽官方 present/changes 卡——slot 系统一等遮蔽：同 cell 异优先级共存、最低者渲染，官方条目仍在册故其声明的 deliverables.file.actions 子槽不塌；0.1.5 宿主上该槽仍是 chain 选举，注册按探测回落为旧的 select + priority: -1 抢占形）——原版 dsh 核心零改动即可运行。该命名空间不声明为 inject（自挂载会让加载器死锁）；挂载被 await 后用 ctx.get('remote.filePreview') 读回，并先执行零会话 capabilities()；只有 { protocolVersion: 1 } 成功返回才安装这些 UI 面，宿主缺席时全部缺席。回合卡片经按会话的客户端缓存读同一个宿主 filePreview.turnFiles RPC——卡片与 tab 同一事实源。

0.1.5-rc.1 迁移退役了四处绕行（上游缝 S1 已落地）：conversation.view 的「产物」tab、shell.overlay 预览抽屉、正文 mention 的捕获阶段 DOM 拦截、turnTail 的 priority: -1 抢占——产物行 / 正文 mention / 工具结果行的打开入口官方已统一收敛到 ctx.sidebarRight.openResource()。方案 B（2026-09-24 落地、同日被仓主否决回退）：内容面注册进官方 documentPreviews 面做官方 document tab 默认渲染器 + 二期 headless 嵌入——接缝成本（renderer loading 协议、extension 档接管语义、headless 布局耦合）与 UX 妥协（改动记录塞进渲染器下拉、复制钮浮动压搜索行）不成立，自绘产物页（地址认领形态）双线恢复；turnTail 遮蔽不在否决范围，保留。

信任与状态：受信任的只读能力——能读取 ctx.fs 允许会话访问的一切，组合它即授予对会话文件系统视图的预览权限；它不是安全边界。不产生会话事件；仅有的按会话状态是回合折叠缓存与 bash 采集器的已验证写入登记表。