dsh-file-fix

DeepSeek Harness（DSH）上传体验优化插件：统一文件导入体系——任何后缀的文件都能
拖入 / 粘贴 / 点击选择，字节上传到附件库（不依赖工作区路径，服务器部署可用），
文件清单随消息注入模型上下文，历史消息下方显示文件气泡（可下载），agent 可读取内容
或导出到工作区。完全不使用 DSH 官方图片导入链路。

背景（DSH Web 原生痛点）

痛点	现状
非图片文件无法上传	DSH Web 只收图片；非图片弹「仅支持 PNG、JPG、WebP、GIF」提示
拖入非图片后 overlay 卡住	drop 后「拖入图片」界面不消失
无法点击选择文件	没有 file input
粘贴只支持文本	Ctrl+V 文件无反应
上传文件 agent 不可见	无文件清单注入，agent 只能猜路径（曾猜 75 步）

方案

• 任何文件 drop / 粘贴 / 📎 选择 → 字节上传（filefix/persistFile）→ host 存入内容寻址附件库
  ~/.dsh/attachments/filefix/（sha256 去重，manifest.jsonl 索引）——与工作区完全解耦
• 发送时（agent/pre-step）注入文件清单消息（role=user + plugin 来源 + notice 表单：
  UI 只显示「📎 附件 N 个文件」一行摘要，模型读到完整清单与 attachment_id）
• 模型侧工具：
  • read_attachment：按 attachment_id 读取内容；支持分段（offset/limit/more，默认段
    48 KB 避开 dsh spill-policy 的 50 KB 内联阈值）；大文件自动镜像完整副本到工作区
    .dsh-uploadux/reads/（官方 read 工具在 spill-policy 中豁免，可读全量）
  • place_attachment：把附件字节导出到会话工作区任意路径（边界校验，防 ../ 逃逸）
• 历史消息：filefix/files 会话事件（ignorable）记录「消息 ↔ 文件」关联，客户端
  注册官方 Conversation Node（conversationEvents Definition + keyed renderer），
  在文字气泡下方渲染文件列表气泡（文件名+大小+下载链接，
  下载走 /plugins/dsh-file-fix/download/<attachmentId>）
• 交互照 Hermes：统一 rail 混排（缩略图降采样队列）、chip 三态（上传中/完成/失败点击重试）、
  删除 chip 连带删附件、Esc 取消拖拽、深度计数防闪烁、drop 后焦点回输入框
• 限制（插件 config 可覆盖）：单文件 50 MB、每批 20 个、批量总量 200 MB；超限整批拒绝 + 提示

两层横向拖放 UI + 视觉上下文

• 两层横向列表（与 DSH 同一审美）：
  • 图像层：图片拖到这里 → 走官方图片注入链路（直接进模型上下文）
  • 文件层：任意文件拖到这里 → 走插件文件链路（字节入附件库 + 文本/文件注入）
  • 空白区 drop 按文件类型自动分流（图片 → 图像层，其他 → 文件层）
• 视觉上下文标记：session 含任何直接图片注入（draft image 提交、read_image /
  add_image_to_context 的调用结果）即标记为「需要视觉」；visual_assist（返回文本）不标记。
• 模型切换限制：当 session 需要视觉时，模型选择器中不支持图片输入的模型置灰不可选；
  从不需要视觉的 session 切换则无限制。

结构

• src/ host 侧：filefix Typert Remote 服务（persistFile / limits / removeFile /
  markPending / unmarkPending / listFiles / checkAvailable + 清理/视觉配置 RPC）+
  附件库（内容寻址）+ 桥（session 事件监听 → 关联表 + pre-step 注入）+
  read_attachment / place_attachment 工具 + 下载路由
• client/ 浏览器侧：document 级 drop/paste 拦截（捕获阶段）＋ rail + 📎 选择按钮 +
  文件气泡（官方 Conversation Node：filefix-files Definition + keyed renderer，
  挂在 conversation.chat.node slot 下）+ 设置页（视觉辅助 / 附件清理）
• scripts/build-client.mjs client bundle 构建（esbuild CJS + __ModuleLoader__ 外壳，zod 内联）
• scripts/repair-sessions.mjs 会话日志修复工具（帧级 zstd 解压 → 清洗 → 重压；曾用于清除
  早期版本误存进日志的 system 角色消息）

已知平台限制（win32）

• dsh spill-policy 阈值 50 KB：纯文本工具结果超过即替换为「头尾预览 + spill 路径」，
  且 spill 定位是 Windows 路径（agent 的 bash 为 Linux 语义读不了）——插件已通过
  48 KB 默认段 + 工作区镜像规避
• 工具集无 shell 执行能力时 agent 无法解压/运行文件（环境问题，非插件）

安装（推荐：npm 官方渠道）

dsh plugin --profile web add dsh-file-fix

装完重启 dsh web 即生效（输入框出现「上传文件」按钮）。

已实测验证的完整生命周期（干净 profile 实测）：

操作	命令	结果
全新安装	dsh plugin --profile web add dsh-file-fix	依赖 + 自动登记 bundles（插件树加载）✅
卸载	dsh plugin --profile web remove dsh-file-fix	依赖 + bundles 登记自动移除 ✅
重装	dsh plugin --profile web add dsh-file-fix	全部恢复 ✅

注意：pnpm 10+ 首次 add 可能报 [ERR_PNPM_IGNORED_BUILDS]（dsh 官方依赖的原生模块构建被拦截，任何插件都如此）——此时再跑一次 add 即可（allowBuilds 已登记后 pnpm 干净退出，dsh 完成登记）。

从源码构建安装

# 1. 构建（需要 deepseek-harness 源码仓库的 node_modules 提供 tsc/esbuild）
npm install        # 或 pnpm install（package-lock 已提交）
npm run build      # host tsc 编译到 lib/ + esbuild 打包 dist/client.js

# 2. 挂载到 dsh profile（以 web profile 为例）
node scripts/mk-junction.cjs node_modules "<你的 dsh profile>/node_modules"
node scripts/mk-junction.cjs "<你的 dsh profile>/web/node_modules/dsh-file-fix" "$PWD"
# 3. 在 profile 的 cordis.patch.yml 里加载本插件（参照 cordis.dev.yml）

开发环境（官方教程路径：源码 checkout + 干净 profile）

一次性准备：

# 1. 源码 checkout（master），pnpm install + build
# 2. profile 保持干净（不 npm install 任何 @deepseek-ai 包）：
#    ~/.dsh/profiles/web/ 里只有 package.json（bundles 声明）+ cordis.patch.yml
#    —— 运行时会由 dsh 自动 heal 出 ~/.dsh/profiles/node_modules 源码链接
# 3. 本项目依赖解析指向 heal 产物（Linux/macOS 用 ln -s）：
ln -s "$DSH_HOME/profiles/node_modules" node_modules  # 或 npm install + 手动链接 @deepseek-ai 包
# 4. 让 profile 能以包名解析本项目（client 插件发现机制需要）：
ln -s "$PWD" "$DSH_HOME/profiles/<profile>/node_modules/dsh-file-fix"

开发循环（在 deepseek-harness 目录跑）：

pnpm dsh web --patch ../dsh-file-fix/cordis.dev.yml --port 3081
# host 改动：npm run build 后重启 dsh（lib/ 是包入口）
# client 改动：npm run build（重建 dist/client.js）+ 刷新页面

npm run typecheck   # host + client 类型检查（用仓库的 tsc：
                    # node <repo>/node_modules/typescript/bin/tsc -p tsconfig.json --noEmit）
npm run build       # tsc 编译宿主侧到 lib/ + esbuild 打包 client bundle

日志约定

[dsh-file-fix] 前缀，全链路可还原：intake(入口/分流统计) → persistFile(校验/拒绝 code/写入路径/耗时) → ref injected(引用注入) → chip removed(删除)，失败带 code（TOO_LARGE / EMPTY / SESSION_NOT_FOUND /
NO_WORKSPACE / WRITE_FAILED / INVALID_PATH / REMOVE_FAILED）。

设计稿

见 docs/design.md（v0.2：完全不保留官方链路 + 照 Hermes 交互）。