dsh-workbuddy-files 0.1.5 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 dsh-workbuddy-files contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 喵芯科技（Miaoxin Technology）
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,218 +1,218 @@
-# dsh-workbuddy-files
-
-WorkBuddy 风格的 DeepSeek Harness (DSH) Web 插件：**拖拽 / 粘贴文件与文件夹 → 全屏接收遮罩 → 输入框原生引用气泡（File Pill）→ 发送后对话区文件卡片**，Agent 通过 `read_document` 工具或任意读取工具直接消费引用。
-
-> 本插件同时存在两个形态：
-> - **本目录**：可发布/可安装的正式插件包（TypeScript，Cordis，Host + Client 双半侧）；
-> - **动态演示版**：会话内动态 Cordis 插件（pluginId `wbdrop-1`），当前版本 pkg-5，与正式包行为一致，拖拽/粘贴/`@`/卡片立即可体验。
-
----
-
-## 功能对照（与 WorkBuddy 对齐）
-
-| 需求 | 实现 |
-| --- | --- |
-| 拖拽任意文件到输入框（PDF/Word/Excel/图片/代码…） | ✅ 统一接管：**所有**文件拖入都显示本插件全屏「松开以接收文件」遮罩并走气泡管线 |
-| 截图/文件粘贴（Ctrl+V） | ✅ 统一接管：图片与文件粘贴都走气泡管线（拖入即缓存 + 引用绝对路径） |
-| `@` 弹出菜单搜索并引用文件/文件夹 | ✅ 工作区文件由 DSH 官方 `@` 源提供；本插件追加「文件缓存」分组 |
-| 光标位置原生引用气泡 | ✅ 输入机 `insertReference` 铸造原生 occurrence 气泡（文件名 + 类型图标） |
-| 气泡整体 Backspace/Delete 一次删除 | ✅ 原生 occurrence 语义（整段删除、撤销/重做一体） |
-| 发送后对话区文件卡片 | ✅ `conversation.chat.turnTail` 链式槽按轮次渲染「📎 消息引用的文件」卡片，点击经 `openFile` 打开 |
-| 引用附带绝对路径 | ✅ **拖入瞬间**按预分配路径（`~/.dsh-drops/<批次>/<相对路径>`）在光标处插入气泡，文件**后台异步缓存**，引用即 `@"C:\...\file.pdf"` |
-| 文件夹拖拽保留目录树 | ✅ `webkitGetAsEntry` 递归遍历；顶层文件夹一个 `📁` 气泡，内部树结构原样落盘 |
-| Agent 可读性 | ✅ Host 注册 `read_document` 工具：文本返回内容、目录返回树、图片/二进制/大文件返回元数据与建议 |
-
-> 设计取舍：v1 曾实现 Chromium「FS Access API 零上传直引」（拖入时零字节、发送时才落地）。实测中发送时物化偶发「直引落地失败」会阻断发送，且浏览器安全模型拿不到拖入文件的绝对路径。为保证**拖入必可用、发送必成功**，现统一为「拖入即缓存 + 真实绝对路径」——localhost 场景下缓存即本地拷贝，无网络开销；零上传直引作为后续可选增强（见「后续方向」）。
-
-## 架构
-
-```
-浏览器（Client 半侧）                          DSH Host（Node 进程）
-┌──────────────────────────────┐        ┌──────────────────────────────┐
-│ window 拖拽/粘贴监听（capture）│        │ 私有 RPC / webServer 路由      │
-│   任何文件拖拽 → stopPropagation│        │   save  → 二进制落盘          │
-│   （原生图片遮罩不再激活）      │ ─────► │   list/stat/home               │
-│   全屏遮罩「松开以接收文件」    │        │                               │
-│                              │        │ ~/.dsh-drops/<批次>/<相对路径>│
-│ 目录树解析（webkitGetAsEntry） │        │ （目录树结构保留，绝对路径）     │
-│   → 立即上传（拖入即缓存）      │        │                               │
-│                              │        │ read_document 工具             │
-│ 气泡注入管线                    │        │   解析引用 → 内容/树/元数据     │
-│   conversation.input.shell(id)│        └──────────────────────────────┘
-│   shell.state.getSnapshot()   │
-│   shell.insertReference(      │
-│     {source:'workbuddy',      │
-│      ref, label, appearance}, │
-│     {start,end,draftRev})  ←  │ 草稿修订号 CAS + 重试（8 次）
-│                              │
-│ @ 触发源「workbuddy」          │
-│   candidates: drops.list →    │
-│   onPick → insert             │
-│   codec.serialize: 恒等        │
-│   （拖入时已落地，发送必成功）  │
-│                              │
-│ conversationEvents 定义        │
-│   workbuddy-file-refs         │
-│   （按轮次聚合用户消息引用）     │
-│                              │
-│ Slot 注册                      │
-│   shell.overlay（遮罩+toast）  │
-│   conversation.input.left     │
-│     （📎 选择文件/文件夹）      │
-│   conversation.chat.turnTail  │
-│     （文件卡片，select 精确匹配）│
-└──────────────────────────────┘
-```
-
-### 为什么气泡是「原生」的
-
-DSH 的输入状态机（`dsh-client-ui-input-trigger` + `InputMachine`）内置**引用气泡（occurrence）**机制：官方 `@` 文件引用、`/` 命令都以气泡呈现，气泡在草稿中占用原子区间 —— Backspace 一次删除、撤销/重做、提交时序列化都走同一套机器。插件通过 `conversation.input.shell(sessionId).insertReference(reference, span)` 铸造气泡（id 寻址服务面，不经过 scoped context），`span` 携带 `draftRev` 做 CAS：插入期间用户继续输入导致修订号变化时自动重读状态重试；非 plain 阶段（提交中）被拒则 toast 提示。
-
-### 与原生图片轨道的互斥共存
-
-DSH 原生的图片拖放轨道在 document 上监听 dragenter 并无条件显示全屏遮罩。本插件在 **window capture 阶段（传播第一站）** 从 dragenter 起 `stopPropagation()`，原生轨道感知不到被接管的拖拽，其遮罩不会激活，也不会因收不到收尾事件而卡住页面；本插件的遮罩自身在 dragleave/dragend/drop 时必然归零，页面随时可恢复。
-
-### 可靠性设计
-
-- **拖入即插气泡**：最终缓存路径在拖入时即可确定（`<dropsRoot>/<批次>/<文件名或目录树>`），气泡**立即**插入光标处，不等上传；文件落盘在后台异步进行（本地写盘，用户无感），完成/失败以 toast 告知；
-- 发送时 `codec.serialize` 恒等，**发送消息不可能因文件未落地而失败**；极端情况下（超大文件拖入后立即发送）Agent 读取时文件可能仍在写入，`read_document` 对不存在路径返回明确错误，稍候重试即可；
-- 气泡插入失败（输入区忙/无会话）自动降级：直接写草稿文本（`setDraft`）/ 聚焦 textarea 时 `execCommand`，保证输入框有内容；
-- Host 写盘加固：fs 服务写 base64 临时文本 + PowerShell 从文件解码写盘（不依赖 stdin 管道），目录自动创建、临时文件自动清理；
-- 单文件上限（动态版 ~31MB / 正式包 256MB 可配）超出时跳过并提示，其余文件正常接收。
-
-## 项目结构
-
-```
-dsh-workbuddy-files/
-├── package.json            # dsh.client 声明 + dsh.bundle.patch 声明
-├── cordis.patch.yml        # bundle patch：把 host 半侧挂进配置树
-├── tsconfig.json
-├── tsdown.config.ts        # 构建 lib/index.js（host）+ lib/client.js（client）
-├── README.md
-└── src/
-    ├── host/
-    │   └── index.ts        # /workbuddy-drops 路由 + read_document 工具
-    └── client/
-        ├── index.ts        # 副作用外壳：__ModuleLoader__.load
-        ├── app.ts          # factory：require('react') + 组装插件
-        ├── at-source.ts    # @ 触发源（文件缓存分组）
-        ├── definitions.ts  # 会话事件定义 + turnTail selector
-        ├── css.ts
-        ├── types.ts
-        ├── components/
-        │   ├── overlay.tsx      # 全屏拖拽遮罩 + toast
-        │   ├── pick-button.tsx  # 📎 选择文件/文件夹
-        │   └── file-cards.tsx   # 对话区文件卡片
-        └── lib/
-            ├── bus.ts       # 拖拽/提示总线
-            ├── insert.ts    # 气泡注入管线（核心）
-            ├── drop.ts      # 拖拽/粘贴处理
-            ├── transfer.ts  # 目录树遍历 + 上传 + 引用格式
-            └── icons.ts     # 类型图标
-```
-
-## 安装
-
-前置：Node 18+、pnpm（`dsh plugin` 内部转发给 pnpm）。
-
-### 方式一：本地项目安装（开发/验证，推荐先走这条）
-
-```powershell
-cd F:\dsh工作空间\dsh-workbuddy-files
-npm install          # 安装 tsdown（0.22+）/ typescript 等构建依赖
-npm run bundle       # 产出 lib/index.js 与 lib/client.js
-npm run typecheck    # 可选：类型检查（已通过）
-
-# link 安装：符号链接（改完代码重新 bundle + 重启 dsh 即生效）
-dsh plugin --profile web add link:..\dsh-workbuddy-files
-# 或拷贝安装（发布前验证打包产物用）：
-dsh plugin --profile web add file:..\dsh-workbuddy-files
-
-dsh web              # 重启 web 界面
-```
-
-`dsh plugin add` 会：在 `$DSH_HOME/profiles/web` 里 `pnpm add` 该包，并因为本包声明了 `dsh.bundle.patch`，自动把 `dsh-workbuddy-files` 追加进 profile 的 `dsh.profile.bundles` 层栈（可在 `~/.dsh/profiles/web/package.json` 中核对）。卸载：`dsh plugin --profile web remove dsh-workbuddy-files`。
-
-### 方式二：npm registry 安装（在其他设备上安装，推荐）
-
-前置：目标设备已安装 DSH 与 pnpm。
-
-```powershell
-npm i -g pnpm               # 若尚未安装
-# DSH 未安装时：npm i -g @deepseek-ai/dsh
-
-dsh plugin --profile web add dsh-workbuddy-files
-dsh web                     # 重启 web 界面，刷新页面即生效
-```
-
-### 方式三：GitHub 直装（npm registry 不可达时）
-
-仓库自带 `lib/` 构建产物（clone 即可用，无需构建）：
-
-```powershell
-dsh plugin --profile web add "github:miaoxintechnology/dsh-workbuddy-files"
-dsh web
-```
-
-### 方式四：离线拷贝
-
-把整个项目目录拷到目标设备，然后：
-
-```powershell
-dsh plugin --profile web add file:<项目目录绝对路径>
-dsh web
-```
-
-### 更新与卸载
-
-```powershell
-# 更新到指定版本（显式版本号可绕过 pnpm 的「新版本最小发布年龄」供应链门禁）
-dsh plugin --profile web add dsh-workbuddy-files@0.1.5
-
-# 卸载
-dsh plugin --profile web remove dsh-workbuddy-files
-```
-
-### 配置（可选）
-
-`cordis.patch.yml` 中 host 半侧的 `config`（浏览器半侧目前收不到配置，走代码默认值）：
-
-```yaml
-config:
-  dropsDir: '~/.dsh-drops'   # 缓存根目录
-  maxFileBytes: 268435456    # 单文件上限（默认 256MB）
-```
-
-### 依赖说明
-
-- Host 半侧硬依赖 `webServer` 服务（`inject: ['webServer']`），写文件用 `node:fs`（真实插件非沙箱环境，与 dsh-pet 同款写法）；
-- Client 半侧在运行时探测 `sessions` / `conversation` / `inputTriggers` / `conversationEvents` / `slots` 服务，缺失时优雅降级（例如无 `conversation` 时气泡退化为纯文本插入）。
-
-### 沙箱模式说明
-
-- **正式插件包**：Host 半侧用 `node:fs` 直写，不经过 DSH 的沙箱化 shell/fs 服务（沙箱只约束模型工具的执行，不约束插件自身的 Node 代码）——因此 `read-only` / `workspace-write` / `danger-full-access` 任何会话模式下，拖入即缓存都能正常工作；
-- **动态演示版**：动态插件环境没有 Node 文件系统，二进制写盘需借用沙箱化 shell 服务；当部署的沙箱 runner 不可用（如 Windows ACL runner 配置异常）或缓存目录位于会话 workspace 之外时，写盘命令需要 `danger-full-access` 策略（演示版已显式携带，与当前会话文件策略一致）；
-- **折中方案**：将 `dropsDir` 配置到 workspace 内（如 `<workspace>/.dsh-drops`），workspace-write 沙箱即可放行；或让插件先继承会话模式、被沙箱拒绝时再升级重试并提示。
-
-## 测试步骤（逐条验收）
-
-1. **拖拽文件**：从资源管理器把 `report.pdf` 拖入页面 → 全屏虚线遮罩「松开以接收文件」（不是原生的图片遮罩）→ 松手 → 输入框光标处出现 `📕 report.pdf` 气泡；`~/.dsh-drops/drop-*` 下文件已落地。
-2. **拖拽图片**：拖入一张 PNG → 同一个遮罩 → `🖼️` 气泡（引用 `~/.dsh-drops` 下的真实路径）；Agent 可用 `read_image` 查看。
-3. **光标位置**：输入「请分析 」后把光标停在句号前拖入文件 → 气泡插在光标处，而非末尾。
-4. **气泡整体删除**：气泡前/后按 Backspace / Delete → 整个气泡一次删除；Ctrl+Z 完整还原。
-5. **粘贴**：资源管理器复制一个 `.py` 文件 → 输入框 Ctrl+V → `💻` 代码气泡；微信/QQ 截图 Ctrl+V → `🖼️` 图片气泡（统一体验）。
-6. **文件夹**：拖入一个含子目录的文件夹 → 一个 `📁` 文件夹气泡；`~/.dsh-drops/<批次>/<文件夹>/` 树结构完整。
-7. **取消拖拽**：拖入后把文件拖出窗口 / 按 Esc → 遮罩消失，页面完全恢复，无残留覆盖。
-8. **@ 菜单**：输入 `@` → 官方「文件与文件夹」组可搜工作区文件；「文件缓存 · ~/.dsh-drops」组列出拖入过的文件，可搜索、可选中插入。
-9. **文件卡片**：发送带引用的消息，等本轮结束 → 轮次尾部出现「📎 消息引用的文件」卡片（图标+名称+大小），点击卡片打开文件。
-10. **read_document**：对 Agent 说「用 read_document 读取我刚引用的文件并总结」→ Agent 调用 `read_document` 拿到文本内容（或目录树/元数据/建议）。
-11. **超大文件**：拖入一个 >31MB（动态版）的文件 → toast 明确提示「超过 31MB 上限」，其余文件正常接收。
-12. **卸载清理**：`dsh plugin --profile web remove dsh-workbuddy-files` 后重启，遮罩/按钮/卡片全部消失；`~/.dsh-drops` 按需手动清理。
-
-## 已知限制与后续方向
-
-- 动态演示版上传走 `host.call` + base64（单文件 ≤ ~31MB），正式包走 fetch 二进制流（≤ 256MB 可配）；
-- turnTail 为链式槽（先匹配者胜出）：当同一轮次既有用户引用又有 Agent 产出文件时，与官方「产出文件」行按注册顺序互斥 —— 扩展：合并渲染或注册到更早优先级；
-- 二进制/超大文件的内容读取依赖宿主侧转换（read_document 返回元数据与建议）；
-- 未做多语言字典注册（当前界面文案为中文），扩展点：`locale.register('workbuddy', { zh, en })`；
-- 零上传直引（FS Access API 句柄 + 发送时物化 + 持久化句柄到 IndexedDB）可作为可选增强回补：默认仍走「拖入即缓存」的可靠路径，直引仅用于超大目录/远程部署场景。
+# dsh-workbuddy-files
+
+WorkBuddy 风格的 DeepSeek Harness (DSH) Web 插件：**拖拽 / 粘贴文件与文件夹 → 全屏接收遮罩 → 输入框原生引用气泡（File Pill）→ 发送后对话区文件卡片**，Agent 通过 `read_document` 工具或任意读取工具直接消费引用。
+
+> 本插件同时存在两个形态：
+> - **本目录**：可发布/可安装的正式插件包（TypeScript，Cordis，Host + Client 双半侧）；
+> - **动态演示版**：会话内动态 Cordis 插件（pluginId `wbdrop-1`），当前版本 pkg-5，与正式包行为一致，拖拽/粘贴/`@`/卡片立即可体验。
+
+---
+
+## 功能对照（与 WorkBuddy 对齐）
+
+| 需求 | 实现 |
+| --- | --- |
+| 拖拽任意文件到输入框（PDF/Word/Excel/图片/代码…） | ✅ 统一接管：**所有**文件拖入都显示本插件全屏「松开以接收文件」遮罩并走气泡管线 |
+| 截图/文件粘贴（Ctrl+V） | ✅ 统一接管：图片与文件粘贴都走气泡管线（拖入即缓存 + 引用绝对路径） |
+| `@` 弹出菜单搜索并引用文件/文件夹 | ✅ 工作区文件由 DSH 官方 `@` 源提供；本插件追加「文件缓存」分组 |
+| 光标位置原生引用气泡 | ✅ 输入机 `insertReference` 铸造原生 occurrence 气泡（文件名 + 类型图标） |
+| 气泡整体 Backspace/Delete 一次删除 | ✅ 原生 occurrence 语义（整段删除、撤销/重做一体） |
+| 发送后对话区文件卡片 | ✅ `conversation.chat.turnTail` 链式槽按轮次渲染「📎 消息引用的文件」卡片，点击经 `openFile` 打开 |
+| 引用附带绝对路径 | ✅ **拖入瞬间**按预分配路径（`~/.dsh-drops/<批次>/<相对路径>`）在光标处插入气泡，文件**后台异步缓存**，引用即 `@"C:\...\file.pdf"` |
+| 文件夹拖拽保留目录树 | ✅ `webkitGetAsEntry` 递归遍历；顶层文件夹一个 `📁` 气泡，内部树结构原样落盘 |
+| Agent 可读性 | ✅ Host 注册 `read_document` 工具：文本返回内容、目录返回树、图片/二进制/大文件返回元数据与建议 |
+
+> 设计取舍：v1 曾实现 Chromium「FS Access API 零上传直引」（拖入时零字节、发送时才落地）。实测中发送时物化偶发「直引落地失败」会阻断发送，且浏览器安全模型拿不到拖入文件的绝对路径。为保证**拖入必可用、发送必成功**，现统一为「拖入即缓存 + 真实绝对路径」——localhost 场景下缓存即本地拷贝，无网络开销；零上传直引作为后续可选增强（见「后续方向」）。
+
+## 架构
+
+```
+浏览器（Client 半侧）                          DSH Host（Node 进程）
+┌──────────────────────────────┐        ┌──────────────────────────────┐
+│ window 拖拽/粘贴监听（capture）│        │ 私有 RPC / webServer 路由      │
+│   任何文件拖拽 → stopPropagation│        │   save  → 二进制落盘          │
+│   （原生图片遮罩不再激活）      │ ─────► │   list/stat/home               │
+│   全屏遮罩「松开以接收文件」    │        │                               │
+│                              │        │ ~/.dsh-drops/<批次>/<相对路径>│
+│ 目录树解析（webkitGetAsEntry） │        │ （目录树结构保留，绝对路径）     │
+│   → 立即上传（拖入即缓存）      │        │                               │
+│                              │        │ read_document 工具             │
+│ 气泡注入管线                    │        │   解析引用 → 内容/树/元数据     │
+│   conversation.input.shell(id)│        └──────────────────────────────┘
+│   shell.state.getSnapshot()   │
+│   shell.insertReference(      │
+│     {source:'workbuddy',      │
+│      ref, label, appearance}, │
+│     {start,end,draftRev})  ←  │ 草稿修订号 CAS + 重试（8 次）
+│                              │
+│ @ 触发源「workbuddy」          │
+│   candidates: drops.list →    │
+│   onPick → insert             │
+│   codec.serialize: 恒等        │
+│   （拖入时已落地，发送必成功）  │
+│                              │
+│ conversationEvents 定义        │
+│   workbuddy-file-refs         │
+│   （按轮次聚合用户消息引用）     │
+│                              │
+│ Slot 注册                      │
+│   shell.overlay（遮罩+toast）  │
+│   conversation.input.left     │
+│     （📎 选择文件/文件夹）      │
+│   conversation.chat.turnTail  │
+│     （文件卡片，select 精确匹配）│
+└──────────────────────────────┘
+```
+
+### 为什么气泡是「原生」的
+
+DSH 的输入状态机（`dsh-client-ui-input-trigger` + `InputMachine`）内置**引用气泡（occurrence）**机制：官方 `@` 文件引用、`/` 命令都以气泡呈现，气泡在草稿中占用原子区间 —— Backspace 一次删除、撤销/重做、提交时序列化都走同一套机器。插件通过 `conversation.input.shell(sessionId).insertReference(reference, span)` 铸造气泡（id 寻址服务面，不经过 scoped context），`span` 携带 `draftRev` 做 CAS：插入期间用户继续输入导致修订号变化时自动重读状态重试；非 plain 阶段（提交中）被拒则 toast 提示。
+
+### 与原生图片轨道的互斥共存
+
+DSH 原生的图片拖放轨道在 document 上监听 dragenter 并无条件显示全屏遮罩。本插件在 **window capture 阶段（传播第一站）** 从 dragenter 起 `stopPropagation()`，原生轨道感知不到被接管的拖拽，其遮罩不会激活，也不会因收不到收尾事件而卡住页面；本插件的遮罩自身在 dragleave/dragend/drop 时必然归零，页面随时可恢复。
+
+### 可靠性设计
+
+- **拖入即插气泡**：最终缓存路径在拖入时即可确定（`<dropsRoot>/<批次>/<文件名或目录树>`），气泡**立即**插入光标处，不等上传；文件落盘在后台异步进行（本地写盘，用户无感），完成/失败以 toast 告知；
+- 发送时 `codec.serialize` 恒等，**发送消息不可能因文件未落地而失败**；极端情况下（超大文件拖入后立即发送）Agent 读取时文件可能仍在写入，`read_document` 对不存在路径返回明确错误，稍候重试即可；
+- 气泡插入失败（输入区忙/无会话）自动降级：直接写草稿文本（`setDraft`）/ 聚焦 textarea 时 `execCommand`，保证输入框有内容；
+- Host 写盘加固：fs 服务写 base64 临时文本 + PowerShell 从文件解码写盘（不依赖 stdin 管道），目录自动创建、临时文件自动清理；
+- 单文件上限（动态版 ~31MB / 正式包 256MB 可配）超出时跳过并提示，其余文件正常接收。
+
+## 项目结构
+
+```
+dsh-workbuddy-files/
+├── package.json            # dsh.client 声明 + dsh.bundle.patch 声明
+├── cordis.patch.yml        # bundle patch：把 host 半侧挂进配置树
+├── tsconfig.json
+├── tsdown.config.ts        # 构建 lib/index.js（host）+ lib/client.js（client）
+├── README.md
+└── src/
+    ├── host/
+    │   └── index.ts        # /workbuddy-drops 路由 + read_document 工具
+    └── client/
+        ├── index.ts        # 副作用外壳：__ModuleLoader__.load
+        ├── app.ts          # factory：require('react') + 组装插件
+        ├── at-source.ts    # @ 触发源（文件缓存分组）
+        ├── definitions.ts  # 会话事件定义 + turnTail selector
+        ├── css.ts
+        ├── types.ts
+        ├── components/
+        │   ├── overlay.tsx      # 全屏拖拽遮罩 + toast
+        │   ├── pick-button.tsx  # 📎 选择文件/文件夹
+        │   └── file-cards.tsx   # 对话区文件卡片
+        └── lib/
+            ├── bus.ts       # 拖拽/提示总线
+            ├── insert.ts    # 气泡注入管线（核心）
+            ├── drop.ts      # 拖拽/粘贴处理
+            ├── transfer.ts  # 目录树遍历 + 上传 + 引用格式
+            └── icons.ts     # 类型图标
+```
+
+## 安装
+
+前置：Node 18+、pnpm（`dsh plugin` 内部转发给 pnpm）。
+
+### 方式一：本地项目安装（开发/验证，推荐先走这条）
+
+```powershell
+cd F:\dsh工作空间\dsh-workbuddy-files
+npm install          # 安装 tsdown（0.22+）/ typescript 等构建依赖
+npm run bundle       # 产出 lib/index.js 与 lib/client.js
+npm run typecheck    # 可选：类型检查（已通过）
+
+# link 安装：符号链接（改完代码重新 bundle + 重启 dsh 即生效）
+dsh plugin --profile web add link:..\dsh-workbuddy-files
+# 或拷贝安装（发布前验证打包产物用）：
+dsh plugin --profile web add file:..\dsh-workbuddy-files
+
+dsh web              # 重启 web 界面
+```
+
+`dsh plugin add` 会：在 `$DSH_HOME/profiles/web` 里 `pnpm add` 该包，并因为本包声明了 `dsh.bundle.patch`，自动把 `dsh-workbuddy-files` 追加进 profile 的 `dsh.profile.bundles` 层栈（可在 `~/.dsh/profiles/web/package.json` 中核对）。卸载：`dsh plugin --profile web remove dsh-workbuddy-files`。
+
+### 方式二：npm registry 安装（在其他设备上安装，推荐）
+
+前置：目标设备已安装 DSH 与 pnpm。
+
+```powershell
+npm i -g pnpm               # 若尚未安装
+# DSH 未安装时：npm i -g @deepseek-ai/dsh
+
+dsh plugin --profile web add dsh-workbuddy-files
+dsh web                     # 重启 web 界面，刷新页面即生效
+```
+
+### 方式三：GitHub 直装（npm registry 不可达时）
+
+仓库自带 `lib/` 构建产物（clone 即可用，无需构建）：
+
+```powershell
+dsh plugin --profile web add "github:miaoxintechnology/dsh-workbuddy-files"
+dsh web
+```
+
+### 方式四：离线拷贝
+
+把整个项目目录拷到目标设备，然后：
+
+```powershell
+dsh plugin --profile web add file:<项目目录绝对路径>
+dsh web
+```
+
+### 更新与卸载
+
+```powershell
+# 更新到指定版本（显式版本号可绕过 pnpm 的「新版本最小发布年龄」供应链门禁）
+dsh plugin --profile web add dsh-workbuddy-files@0.1.5
+
+# 卸载
+dsh plugin --profile web remove dsh-workbuddy-files
+```
+
+### 配置（可选）
+
+`cordis.patch.yml` 中 host 半侧的 `config`（浏览器半侧目前收不到配置，走代码默认值）：
+
+```yaml
+config:
+  dropsDir: '~/.dsh-drops'   # 缓存根目录
+  maxFileBytes: 268435456    # 单文件上限（默认 256MB）
+```
+
+### 依赖说明
+
+- Host 半侧硬依赖 `webServer` 服务（`inject: ['webServer']`），写文件用 `node:fs`（真实插件非沙箱环境，与 dsh-pet 同款写法）；
+- Client 半侧在运行时探测 `sessions` / `conversation` / `inputTriggers` / `conversationEvents` / `slots` 服务，缺失时优雅降级（例如无 `conversation` 时气泡退化为纯文本插入）。
+
+### 沙箱模式说明
+
+- **正式插件包**：Host 半侧用 `node:fs` 直写，不经过 DSH 的沙箱化 shell/fs 服务（沙箱只约束模型工具的执行，不约束插件自身的 Node 代码）——因此 `read-only` / `workspace-write` / `danger-full-access` 任何会话模式下，拖入即缓存都能正常工作；
+- **动态演示版**：动态插件环境没有 Node 文件系统，二进制写盘需借用沙箱化 shell 服务；当部署的沙箱 runner 不可用（如 Windows ACL runner 配置异常）或缓存目录位于会话 workspace 之外时，写盘命令需要 `danger-full-access` 策略（演示版已显式携带，与当前会话文件策略一致）；
+- **折中方案**：将 `dropsDir` 配置到 workspace 内（如 `<workspace>/.dsh-drops`），workspace-write 沙箱即可放行；或让插件先继承会话模式、被沙箱拒绝时再升级重试并提示。
+
+## 测试步骤（逐条验收）
+
+1. **拖拽文件**：从资源管理器把 `report.pdf` 拖入页面 → 全屏虚线遮罩「松开以接收文件」（不是原生的图片遮罩）→ 松手 → 输入框光标处出现 `📕 report.pdf` 气泡；`~/.dsh-drops/drop-*` 下文件已落地。
+2. **拖拽图片**：拖入一张 PNG → 同一个遮罩 → `🖼️` 气泡（引用 `~/.dsh-drops` 下的真实路径）；Agent 可用 `read_image` 查看。
+3. **光标位置**：输入「请分析 」后把光标停在句号前拖入文件 → 气泡插在光标处，而非末尾。
+4. **气泡整体删除**：气泡前/后按 Backspace / Delete → 整个气泡一次删除；Ctrl+Z 完整还原。
+5. **粘贴**：资源管理器复制一个 `.py` 文件 → 输入框 Ctrl+V → `💻` 代码气泡；微信/QQ 截图 Ctrl+V → `🖼️` 图片气泡（统一体验）。
+6. **文件夹**：拖入一个含子目录的文件夹 → 一个 `📁` 文件夹气泡；`~/.dsh-drops/<批次>/<文件夹>/` 树结构完整。
+7. **取消拖拽**：拖入后把文件拖出窗口 / 按 Esc → 遮罩消失，页面完全恢复，无残留覆盖。
+8. **@ 菜单**：输入 `@` → 官方「文件与文件夹」组可搜工作区文件；「文件缓存 · ~/.dsh-drops」组列出拖入过的文件，可搜索、可选中插入。
+9. **文件卡片**：发送带引用的消息，等本轮结束 → 轮次尾部出现「📎 消息引用的文件」卡片（图标+名称+大小），点击卡片打开文件。
+10. **read_document**：对 Agent 说「用 read_document 读取我刚引用的文件并总结」→ Agent 调用 `read_document` 拿到文本内容（或目录树/元数据/建议）。
+11. **超大文件**：拖入一个 >31MB（动态版）的文件 → toast 明确提示「超过 31MB 上限」，其余文件正常接收。
+12. **卸载清理**：`dsh plugin --profile web remove dsh-workbuddy-files` 后重启，遮罩/按钮/卡片全部消失；`~/.dsh-drops` 按需手动清理。
+
+## 已知限制与后续方向
+
+- 动态演示版上传走 `host.call` + base64（单文件 ≤ ~31MB），正式包走 fetch 二进制流（≤ 256MB 可配）；
+- turnTail 为链式槽（先匹配者胜出）：当同一轮次既有用户引用又有 Agent 产出文件时，与官方「产出文件」行按注册顺序互斥 —— 扩展：合并渲染或注册到更早优先级；
+- 二进制/超大文件的内容读取依赖宿主侧转换（read_document 返回元数据与建议）；
+- 未做多语言字典注册（当前界面文案为中文），扩展点：`locale.register('workbuddy', { zh, en })`；
+- 零上传直引（FS Access API 句柄 + 发送时物化 + 持久化句柄到 IndexedDB）可作为可选增强回补：默认仍走「拖入即缓存」的可靠路径，直引仅用于超大目录/远程部署场景。

package/lib/client.js

@@ -247,10 +247,11 @@
 	//#endregion
 	//#region src/client/components/file-cards.tsx
 	/**
-	* 对话区文件卡片（挂在 conversation.chat.turnTail 链式槽）：
-	* 用户消息发送后，该轮次消息中引用的文件以「类型图标 + 文件名 + 大小/文件夹」卡片
-	* 渲染在轮次尾部；点击卡片经 owner 的 openFile 打开文件。
-	* selector 只匹配含文件引用的轮次（见 definitions.ts），不抢占其他链条目。
+	* 对话区文件卡片（挂在 conversation.chat.turnTail —— 0.2.0 起是 **list 槽**）：
+	* 每个完成的轮次都会渲染本条目，从 ownerProps.turn 的轮次位置数据里读
+	* `workbuddy-file-refs`（由 definitions.ts 注册的会话定义聚合自用户消息），
+	* 有引用时渲染「类型图标 + 文件名 + 大小/文件夹」卡片，无引用返回 null。
+	* 点击卡片经 owner 的 openFile 打开文件。
 	*/
 	function createFileCardsComponent(React) {
 		function FileCard(props) {
@@ -287,9 +288,11 @@
 			}, React.createElement("span", { className: "wbd-card-icon" }, icon), React.createElement("span", { className: "wbd-card-name" }, name), React.createElement("span", { className: "wbd-card-sub" }, sub));
 		}
 		return function FileCards(props) {
-			const matched = props.matched;
-			if (matched === null || matched === void 0 || !Array.isArray(matched.refs) || matched.refs.length === 0) return null;
-			return React.createElement("div", { className: "wbd-cards" }, React.createElement("span", { className: "wbd-cards-label" }, "📎 消息引用的文件"), matched.refs.map((path, i) => React.createElement(FileCard, {
+			const turn = props.turn;
+			const data = turn !== void 0 && turn !== null && turn.data !== void 0 && typeof turn.data.get === "function" ? turn.data.get("workbuddy-file-refs") : void 0;
+			const refs = data !== void 0 && data !== null && Array.isArray(data.refs) ? data.refs : [];
+			if (refs.length === 0) return null;
+			return React.createElement("div", { className: "wbd-cards" }, React.createElement("span", { className: "wbd-cards-label" }, "📎 消息引用的文件"), refs.map((path, i) => React.createElement(FileCard, {
 				key: String(path) + ":" + i,
 				path,
 				openFile: props.openFile
@@ -316,11 +319,17 @@
 	* 📎 引用按钮（挂在 conversation.input.left 列表槽）：
 	* 统一走 <input type=file>（多选 / webkitdirectory）→ 立即插入气泡 →
 	* 后台缓存（所有浏览器行为一致）。
+	*
+	* 该槽位是 session 作用域，标准属性里的 `sessionId` 是 0.2.0 获取当前会话的
+	* 官方途径（sessions 服务已不再暴露列表快照），在此上报给插件共享状态。
 	*/
-	function createPickButtonComponent(React, bus, handlers) {
-		return function PickButton() {
+	function createPickButtonComponent(React, bus, handlers, onSession) {
+		return function PickButton(props) {
 			const [open, setOpen] = React.useState(false);
 			const newBatch = () => "drop-" + Date.now().toString(36);
+			React.useEffect(() => {
+				onSession(props.sessionId);
+			}, [props.sessionId]);
 			const pickFolder = async () => {
 				setOpen(false);
 				const input = document.createElement("input");
@@ -474,14 +483,6 @@
 			};
 		}
 	};
-	/** turnTail chain selector：仅当该轮次存在文件引用时返回 matched，避免抢占其他链条目 */
-	function selectTurnFileRefs(owner) {
-		const t = owner !== null && owner !== void 0 ? owner.turn : void 0;
-		if (t === void 0 || t.data === void 0 || typeof t.data.get !== "function") return null;
-		const data = t.data.get("workbuddy-file-refs");
-		if (data === void 0 || data === null || !Array.isArray(data.refs) || data.refs.length === 0) return null;
-		return { refs: data.refs };
-	}
 	//#endregion
 	//#region src/client/lib/bus.ts
 	function createDropBus() {
@@ -820,7 +821,7 @@
 	}
 	function createInsertPipeline(deps) {
 		return async function insertItems(items) {
-			const sessionId = deps.sessions.list.getSnapshot().current;
+			const sessionId = deps.currentSessionId();
 			if (sessionId === void 0) {
 				deps.toast("请先打开或新建一个会话，再拖入文件", "error");
 				return 0;
@@ -903,8 +904,9 @@
 				name: "workbuddy-files",
 				inject: [
 					"slots",
-					"sessions",
-					"conversation"
+					"conversation",
+					"uiConversation",
+					"inputTriggers"
 				],
 				apply(ctx) {
 					try {
@@ -919,13 +921,17 @@
 	function applyClient(ctx, React) {
 		console.log("[workbuddy-files] client apply 开始");
 		const get = (name) => ctx.get(name);
-		const sessions = get("sessions");
 		const slots = get("slots");
 		const conversation = get("conversation");
 		const inputTriggers = get("inputTriggers");
-		const conversationEvents = get("conversationEvents");
+		const uiConversation = get("uiConversation");
 		const styles = get("styles");
 		if (slots === void 0) return;
+		let currentSessionId;
+		const setSessionId = (id) => {
+			currentSessionId = id;
+		};
+		const getSessionId = () => currentSessionId;
 		const injectCssViaHead = (css) => {
 			if (typeof document === "undefined") return;
 			const tagId = "dsh-workbuddy-files/styles";
@@ -943,7 +949,7 @@
 		};
 		const effect = ctx.effect.bind(ctx);
 		effect(insertStyles, "workbuddy: styles");
-		console.log("[workbuddy-files] client apply 开始：services slots=" + (slots !== void 0) + " conversation=" + (conversation !== void 0) + " inputTriggers=" + (inputTriggers !== void 0) + " conversationEvents=" + (conversationEvents !== void 0) + " styles=" + (styles !== void 0));
+		console.log("[workbuddy-files] client apply 开始：services slots=" + (slots !== void 0) + " conversation=" + (conversation !== void 0) + " inputTriggers=" + (inputTriggers !== void 0) + " uiConversation=" + (uiConversation !== void 0) + " styles=" + (styles !== void 0));
 		const bus = createDropBus();
 		let rootCache = null;
 		dropsHome().then((r) => {
@@ -966,8 +972,8 @@
 		const handlers = createDropHandlers({
 			bus,
 			insert: createInsertPipeline({
-				sessions,
 				conversation,
+				currentSessionId: getSessionId,
 				toast: bus.toast
 			}),
 			ensureRoot,
@@ -982,9 +988,10 @@
 			const source = createAtSource();
 			effect(() => inputTriggers.registerSource(source), "workbuddy: @ source");
 		}
-		if (conversationEvents !== void 0) effect(() => {
-			const d1 = conversationEvents.register(boundaryDef);
-			const d2 = conversationEvents.register(fileRefsDef);
+		const events = uiConversation !== void 0 ? uiConversation.events : void 0;
+		if (events !== void 0) effect(() => {
+			const d1 = events.register(boundaryDef);
+			const d2 = events.register(fileRefsDef);
 			return () => {
 				if (typeof d1 === "function") d1();
 				if (typeof d2 === "function") d2();
@@ -1001,10 +1008,12 @@
 			id: "workbuddy-pick",
 			order: 0,
 			label: "引用文件/文件夹"
-		}, createPickButtonComponent(React, bus, handlers)));
+		}, createPickButtonComponent(React, bus, handlers, setSessionId)));
 		slots.inject("conversation.chat.turnTail", () => slots.register({
 			name: "conversation.chat.turnTail",
-			select: selectTurnFileRefs
+			id: "dsh-workbuddy-files",
+			order: 20,
+			label: "文件引用卡片"
 		}, createFileCardsComponent(React)));
 		console.log("[workbuddy-files] client 就绪：拖入即插气泡 + 后台缓存 / 统一遮罩 / 文件卡片");
 	}

package/package.json

@@ -1,88 +1,84 @@
-{
-  "name": "dsh-workbuddy-files",
-  "version": "0.1.5",
-  "description": "WorkBuddy 风格的 DeepSeek Harness Web 插件：拖拽/粘贴文件与文件夹生成输入框引用气泡（附绝对路径）、@ 菜单检索缓存文件、对话区文件卡片、read_document 工具。",
-  "keywords": [
-    "dsh",
-    "dsh-plugin",
-    "deepseek-harness",
-    "workbuddy",
-    "drag-drop",
-    "file-reference",
-    "file-pill",
-    "web-ui",
-    "cordis"
-  ],
-  "license": "MIT",
-  "homepage": "https://github.com/miaoxintechnology/dsh-workbuddy-files#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/miaoxintechnology/dsh-workbuddy-files.git"
-  },
-  "bugs": {
-    "url": "https://github.com/miaoxintechnology/dsh-workbuddy-files/issues"
-  },
-  "type": "module",
-  "main": "lib/index.js",
-  "exports": {
-    ".": {
-      "default": "./lib/index.js"
-    },
-    "./client": {
-      "default": "./lib/client.js"
-    },
-    "./src/*": "./src/*",
-    "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "src",
-    "cordis.patch.yml",
-    "README.md"
-  ],
-  "scripts": {
-    "bundle": "tsdown --config tsdown.host.config.ts && tsdown --config tsdown.client.config.ts && node scripts/rename.mjs",
-    "watch": "tsdown --config tsdown.client.config.ts --watch",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run typecheck && npm run bundle"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "_comment": [
-    "main (lib/index.js) 是 Host 半侧入口（Cordis 插件 apply/inject）",
-    "exports['./client'] 是浏览器半侧入口，DSH 模块系统据此提供 /plugins/dsh-workbuddy-files/client.js",
-    "dsh.bundle.patch 声明本包是 bundle：dsh plugin add 后自动加入 profile 的 bundles 层栈并挂载 host 半侧",
-    "dsh.client 声明浏览器半侧的注入依赖与平台（web）",
-    "peerDependencies 是宿主（DSH）提供的模块，本包不打包它们"
-  ],
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "client": {
-      "inject": [
-        "@deepseek-ai/dsh-client-runtime"
-      ],
-      "platform": "web"
-    }
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-client-ui-input-trigger": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-fs": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-shell": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.1-rc.1",
-    "react": "^18.2.0"
-  },
-  "devDependencies": {
-    "@types/node": "^26.2.0",
-    "@types/react": "^18.2.0",
-    "tsdown": "^0.22.14",
-    "typescript": "^5.5.0"
-  }
-}
+{
+  "name": "dsh-workbuddy-files",
+  "version": "0.2.0",
+  "description": "WorkBuddy 风格的 DeepSeek Harness Web 插件：拖拽/粘贴文件与文件夹生成输入框引用气泡（附绝对路径）、@ 菜单检索缓存文件、对话区文件卡片、read_document 工具。",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "workbuddy",
+    "drag-drop",
+    "file-reference",
+    "file-pill",
+    "web-ui",
+    "cordis"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/miaoxintechnology/dsh-workbuddy-files#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/miaoxintechnology/dsh-workbuddy-files.git"
+  },
+  "bugs": {
+    "url": "https://github.com/miaoxintechnology/dsh-workbuddy-files/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "bundle": "tsdown --config tsdown.host.config.ts && tsdown --config tsdown.client.config.ts && node scripts/rename.mjs",
+    "watch": "tsdown --config tsdown.client.config.ts --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run bundle"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "_comment": [
+    "main (lib/index.js) 是 Host 半侧入口（Cordis 插件 apply/inject）",
+    "exports['./client'] 是浏览器半侧入口，DSH 模块系统据此提供 /plugins/dsh-workbuddy-files/client.js",
+    "dsh.bundle.patch 声明本包是 bundle：dsh plugin add 后自动加入 profile 的 bundles 层栈并挂载 host 半侧",
+    "dsh.client 声明浏览器半侧的注入依赖与平台（web）",
+    "peerDependencies 是宿主（DSH）提供的模块，本包不打包它们"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-input-trigger",
+        "@deepseek-ai/dsh-client-ui-renderer"
+      ],
+      "platform": "web"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@types/node": "^26.2.0",
+    "@types/react": "^18.2.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.5.0"
+  }
+}

package/src/client/app.ts

@@ -14,7 +14,7 @@ import { createFileCardsComponent } from './components/file-cards'
 import { createOverlayComponent, ReactLike } from './components/overlay'
 import { createPickButtonComponent } from './components/pick-button'
 import { CSS } from './css'
-import { boundaryDef, fileRefsDef, selectTurnFileRefs } from './definitions'
+import { boundaryDef, fileRefsDef } from './definitions'
 import { createDropBus } from './lib/bus'
 import { createDropHandlers } from './lib/drop'
 import { createInsertPipeline } from './lib/insert'
@@ -35,8 +35,8 @@ export function makeFactory() {
 
     return {
       name: 'workbuddy-files',
-      // slots：UI 注册入口；sessions + conversation：气泡插入管线核心
-      inject: ['slots', 'sessions', 'conversation'],
+      // 0.2.0：slots / conversation / uiConversation（会话定义注册）/ inputTriggers
+      inject: ['slots', 'conversation', 'uiConversation', 'inputTriggers'],
       apply(ctx) {
         try {
           applyClient(ctx, React)
@@ -53,7 +53,6 @@ function applyClient(ctx: Record<string, unknown>, React: ReactLike): void {
   const get = (name: string) => (ctx.get as (n: string) => unknown)(name)
 
         // ---- 能力探测（缺失则优雅退出）----
-        const sessions = get('sessions') as never
         const slots = get('slots') as {
           inject(key: string, callback: () => unknown): () => void
           register(options: Record<string, unknown>, component: unknown): unknown
@@ -62,12 +61,19 @@ function applyClient(ctx: Record<string, unknown>, React: ReactLike): void {
         const inputTriggers = get('inputTriggers') as {
           registerSource(source: unknown): () => void
         } | undefined
-        const conversationEvents = get('conversationEvents') as {
-          register(definition: unknown): (() => void) | undefined
+        // 0.2.0：conversationEvents 服务改名为 uiConversation（定义注册在 .events 上）
+        const uiConversation = get('uiConversation') as {
+          events?: { register(definition: unknown): (() => void) | undefined }
         } | undefined
         const styles = get('styles') as { insert(css: string): () => void } | undefined
         if (slots === undefined) return
 
+        // ---- 当前会话 id ----
+        // 0.2.0 的 sessions 服务不再暴露 list；会话 id 由 session 作用域的插槽标准属性提供
+        let currentSessionId: string | undefined
+        const setSessionId = (id: string | undefined): void => { currentSessionId = id }
+        const getSessionId = (): string | undefined => currentSessionId
+
         // ---- 包内样式 ----
         // 正式插件包没有动态版的 styles 内置服务：回退到 document.head style 注入（dsh-pet 同款）
         const injectCssViaHead = (css: string): void => {
@@ -87,7 +93,7 @@ function applyClient(ctx: Record<string, unknown>, React: ReactLike): void {
         }
         const effect = (ctx.effect as (fn: () => (() => void) | undefined, label?: string) => void).bind(ctx)
         effect(insertStyles, 'workbuddy: styles')
-        console.log('[workbuddy-files] client apply 开始：services slots=' + (slots !== undefined) + ' conversation=' + (conversation !== undefined) + ' inputTriggers=' + (inputTriggers !== undefined) + ' conversationEvents=' + (conversationEvents !== undefined) + ' styles=' + (styles !== undefined))
+        console.log('[workbuddy-files] client apply 开始：services slots=' + (slots !== undefined) + ' conversation=' + (conversation !== undefined) + ' inputTriggers=' + (inputTriggers !== undefined) + ' uiConversation=' + (uiConversation !== undefined) + ' styles=' + (styles !== undefined))
 
         // ---- 共享实例 ----
         const bus = createDropBus()
@@ -116,7 +122,7 @@ function applyClient(ctx: Record<string, unknown>, React: ReactLike): void {
         }
 
         // ---- 气泡注入管线 ----
-        const insert = createInsertPipeline({ sessions, conversation, toast: bus.toast })
+        const insert = createInsertPipeline({ conversation, currentSessionId: getSessionId, toast: bus.toast })
 
         // ---- 拖拽 / 粘贴处理 + 窗口级监听 ----
         const handlers = createDropHandlers({ bus, insert, ensureRoot, enqueueUpload })
@@ -132,11 +138,12 @@ function applyClient(ctx: Record<string, unknown>, React: ReactLike): void {
           effect(() => inputTriggers.registerSource(source), 'workbuddy: @ source')
         }
 
-        // ---- 会话事件定义 ----
-        if (conversationEvents !== undefined) {
+        // ---- 会话事件定义（0.2.0：注册在 uiConversation.events 上）----
+        const events = uiConversation !== undefined ? uiConversation.events : undefined
+        if (events !== undefined) {
           effect(() => {
-            const d1 = conversationEvents.register(boundaryDef)
-            const d2 = conversationEvents.register(fileRefsDef)
+            const d1 = events.register(boundaryDef)
+            const d2 = events.register(fileRefsDef)
             return () => {
               if (typeof d1 === 'function') d1()
               if (typeof d2 === 'function') d2()
@@ -149,12 +156,14 @@ function applyClient(ctx: Record<string, unknown>, React: ReactLike): void {
           { name: 'shell.overlay', id: 'workbuddy-drop', order: 300, label: 'WorkBuddy 拖拽遮罩' },
           createOverlayComponent(React, bus),
         ))
+        // conversation.input.left：session 作用域，标准属性含 sessionId —— 在此捕获当前会话
         slots.inject('conversation.input.left', () => slots.register(
           { name: 'conversation.input.left', id: 'workbuddy-pick', order: 0, label: '引用文件/文件夹' },
-          createPickButtonComponent(React, bus, handlers),
+          createPickButtonComponent(React, bus, handlers, setSessionId),
         ))
+        // 0.2.0：turnTail 从 chain 变为 list —— 用 id 注册，组件直接拿到 { turn, seq, openFile }
         slots.inject('conversation.chat.turnTail', () => slots.register(
-          { name: 'conversation.chat.turnTail', select: selectTurnFileRefs },
+          { name: 'conversation.chat.turnTail', id: 'dsh-workbuddy-files', order: 20, label: '文件引用卡片' },
           createFileCardsComponent(React),
         ))
 

package/src/client/components/file-cards.tsx

@@ -3,10 +3,11 @@ import { dropsStat } from '../lib/transfer'
 import type { ReactLike } from './overlay'
 
 /**
- * 对话区文件卡片（挂在 conversation.chat.turnTail 链式槽）：
- * 用户消息发送后，该轮次消息中引用的文件以「类型图标 + 文件名 + 大小/文件夹」卡片
- * 渲染在轮次尾部；点击卡片经 owner 的 openFile 打开文件。
- * selector 只匹配含文件引用的轮次（见 definitions.ts），不抢占其他链条目。
+ * 对话区文件卡片（挂在 conversation.chat.turnTail —— 0.2.0 起是 **list 槽**）：
+ * 每个完成的轮次都会渲染本条目，从 ownerProps.turn 的轮次位置数据里读
+ * `workbuddy-file-refs`（由 definitions.ts 注册的会话定义聚合自用户消息），
+ * 有引用时渲染「类型图标 + 文件名 + 大小/文件夹」卡片，无引用返回 null。
+ * 点击卡片经 owner 的 openFile 打开文件。
  */
 export function createFileCardsComponent(React: ReactLike) {
   function FileCard(props: { path: string; openFile?: (path: string) => void }) {
@@ -36,12 +37,24 @@ export function createFileCardsComponent(React: ReactLike) {
     )
   }
 
-  return function FileCards(props: { matched: { refs: string[] }; openFile?: (path: string) => void }) {
-    const matched = props.matched
-    if (matched === null || matched === undefined || !Array.isArray(matched.refs) || matched.refs.length === 0) return null
+  interface TurnTailProps {
+    /** 0.2.0 的 turnTail list ownerProps：完成的轮次位置 */
+    turn?: { data: { get(key: string): { refs?: string[] } | undefined } }
+    seq?: number
+    openFile?: (path: string) => void
+  }
+
+  return function FileCards(props: TurnTailProps) {
+    // 0.2.0：turnTail 是 list 条目，ownerProps 直接给出 { turn, seq, openFile }
+    const turn = props.turn
+    const data = turn !== undefined && turn !== null && turn.data !== undefined && typeof turn.data.get === 'function'
+      ? turn.data.get('workbuddy-file-refs')
+      : undefined
+    const refs = data !== undefined && data !== null && Array.isArray(data.refs) ? data.refs : []
+    if (refs.length === 0) return null
     return React.createElement('div', { className: 'wbd-cards' },
       React.createElement('span', { className: 'wbd-cards-label' }, '📎 消息引用的文件'),
-      matched.refs.map((path, i) => React.createElement(FileCard, { key: String(path) + ':' + i, path, openFile: props.openFile })),
+      refs.map((path: string, i: number) => React.createElement(FileCard, { key: String(path) + ':' + i, path, openFile: props.openFile })),
     )
   }
 }

package/src/client/components/pick-button.tsx

@@ -7,12 +7,24 @@ import type { ReactLike } from './overlay'
  * 📎 引用按钮（挂在 conversation.input.left 列表槽）：
  * 统一走 <input type=file>（多选 / webkitdirectory）→ 立即插入气泡 →
  * 后台缓存（所有浏览器行为一致）。
+ *
+ * 该槽位是 session 作用域，标准属性里的 `sessionId` 是 0.2.0 获取当前会话的
+ * 官方途径（sessions 服务已不再暴露列表快照），在此上报给插件共享状态。
  */
-export function createPickButtonComponent(React: ReactLike, bus: DropBus, handlers: Pick<DropHandlers, 'acceptTree'>) {
-  return function PickButton() {
+export function createPickButtonComponent(
+  React: ReactLike,
+  bus: DropBus,
+  handlers: Pick<DropHandlers, 'acceptTree'>,
+  onSession: (sessionId: string | undefined) => void,
+) {
+  return function PickButton(props: { sessionId?: string }) {
     const [open, setOpen] = React.useState(false)
     const newBatch = () => 'drop-' + Date.now().toString(36)
 
+    React.useEffect(() => {
+      onSession(props.sessionId)
+    }, [props.sessionId])
+
     const pickFolder = async () => {
       setOpen(false)
       const input = document.createElement('input')

package/src/client/lib/insert.ts

@@ -13,15 +13,12 @@ import type { InsertItem } from '../types'
  * 兜底 2：无 facade → 聚焦 textarea 时 document.execCommand 纯文本插入。
  */
 export interface InsertDeps {
-  sessions: {
-    list: { getSnapshot(): { current: string | undefined } }
-  }
+  /**
+   * 会话输入 shell 注册表（0.2.0：ctx.conversation.input，服务键与 0.1.x 相同）。
+   */
   conversation: {
     input: {
-      /**
-       * id 寻址服务面（InputHub.shell）—— 直接返回会话输入 shell，
-       * 无需 sessions.scope()（后者返回 cordis Context，动态门面拒绝暴露）。
-       */
+      /** id 寻址服务面 InputHub.shell(sessionId) —— 直接返回会话输入 shell */
       shell(id: string): {
         state: { getSnapshot(): { draft: string; draftRev: number } }
         insertReference(reference: InsertItem['reference'], span: { start: number; end: number; draftRev: number }): boolean
@@ -30,6 +27,11 @@ export interface InsertDeps {
       }
     }
   }
+  /**
+   * 当前会话 id。0.2.0 的 sessions 服务不再暴露列表快照，
+   * 由 conversation.input.left 插槽的 sessionId 标准属性捕获。
+   */
+  currentSessionId(): string | undefined
   toast(text: string, level?: 'info' | 'error'): void
 }
 
@@ -47,7 +49,7 @@ function readCaret(fallbackLen: number): number {
 
 export function createInsertPipeline(deps: InsertDeps): InsertPipeline {
   return async function insertItems(items: InsertItem[]): Promise<number> {
-    const sessionId = deps.sessions.list.getSnapshot().current
+    const sessionId = deps.currentSessionId()
     if (sessionId === undefined) {
       deps.toast('请先打开或新建一个会话，再拖入文件', 'error')
       return 0

package/src/types/dsh-ambient.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 宿主（DSH）运行时模块的最小环境声明。
+ *
+ * 这两个包由 Harness 在运行时提供（宿主模块解析），第三方插件不把它们装成
+ * 依赖 —— 官方 0.2.0 插件同样只 peer 依赖 @deepseek-ai/cordis。这里声明本
+ * 插件实际消费的接口形状，使本地 `npm run typecheck` 不依赖宿主包。
+ */
+
+declare module '@deepseek-ai/dsh-tools' {
+  /** 模型工具定义（本插件只消费 defineTool 的宽松签名） */
+  export interface ToolDefinition {
+    name: string
+    description: string
+    parameters: Record<string, unknown>
+    output: {
+      schema: unknown
+      render: (args: unknown, value: unknown) => Array<{ type: string; text: string }>
+      presentationMeta?: (args: unknown, value: unknown) => unknown
+    }
+    execute: (args: never, exec: unknown) => Promise<unknown>
+    presentCall?: (args: never) => unknown
+    presentResult?: (args: never, result: unknown) => unknown
+  }
+  /** 定义并校验一个模型工具 */
+  export function defineTool<T extends Record<string, unknown>>(definition: T): T
+}
+
+declare module '@deepseek-ai/dsh-client-ui-input-trigger/client' {
+  /** 一条 @ / 菜单候选 */
+  export interface InputTriggerCandidate {
+    name: string
+    description?: string
+    icon?: string
+    hint?: string
+    section?: string
+    value?: string
+  }
+  /** 一次 @ / 菜单触发源的注册面 */
+  export interface InputTriggerSource {
+    trigger: '@' | '/'
+    name: string
+    order?: number
+    showGroupTitle?: boolean
+    candidates(
+      session: { readonly sessionId: string },
+      request: { query: string; quoted?: boolean; signal: AbortSignal },
+    ): Promise<InputTriggerCandidate[]> | InputTriggerCandidate[]
+    onPick(pick: { candidate: InputTriggerCandidate }): { insert?: unknown } | undefined
+    codec?: {
+      clipboardText(ref: string): string
+      serialize(ref: string, signal: AbortSignal): Promise<string>
+    }
+  }
+}