kamilhzn/dsh-file-upload

dsh-file-uploader

dsh 的文件能力插件：上传本地文件（txt、md、各类代码文件、Word、Excel、PDF）与 @ 引用目录文件
（仿 Claude Code / Codex）：上传的文件与 @ 引用的文件都会解析为文本后随下一条消息注入给模型。

功能

- 一键上传按钮：输入框工具行的回形针按钮，点击直接打开系统文件选择框（多选），
与 Trae / Kimi 的上传入口一致。
- 拖拽上传：把文件拖进窗口任意位置即可加入（非图片文件；纯图片拖放仍走内置图片条带）。
- 文件条带：待发送文件以 chip 显示在输入框上方（名称 / 大小 / 解析状态 / 字符数），
可单个删除；发送后自动清空。
- @ 引用目录文件：在输入框输入 @ 弹出候选菜单，默认即当前对话框会话的工作区目录
（dsh 会话创建时记录在 Session.header.cwd，经 ?session= 按会话解析），按文件名
（相对路径）列候选并即时过滤；选中后在消息中插入引用，发送时把该文件解析文本内联进
用户消息（[引用文件] path\n），语义与上传一致。根目录优先级为
当前会话工作区 > rootDir > 宿主进程 cwd，多会话相互隔离。
- 多格式解析：txt / md / 代码与配置文件（按扩展名或内容嗅探，编码自动检测：
UTF-8 / GBK / GB18030 / UTF-16，按 BOM 与字节特征回退）、
docx（Word 文本抽取）、xlsx / xls（SheetJS 逐工作表转 CSV）、pdf（pdf-parse 文本抽取）。
- 内容注入：文件解析文本在下一轮第一步作为独立「上传文件」消息注入模型，
与用户消息一起进入会话日志（模型可见 ⟺ 已记录），并在注入后取走（attach-once）。

安装

dsh plugin --profile web add dsh-file-uploader
dsh web

重启后浏览器会通过 /plugins/dsh-file-uploader/client.js 拉取客户端 bundle（dsh.client
扫描 + window.__DSH_BOOT__ 注入），宿主行 dsh-file-uploader 从 profile 解析 node 半。
卸载：dsh plugin --profile web remove dsh-file-uploader。

配置

行 dsh-file-uploader 的 config 全部可由 cordis.yml 覆盖（见 cordis.patch.yml）：

| 键 | 默认 | 说明 |
| --- | --- | --- |
| maxFileBytes | 10485760 (10MB) | 单个文件大小上限 |
| maxTotalBytes | 52428800 (50MB) | 单会话待发送文件总大小上限 |
| maxFilesPerMessage | 20 | 单条消息最多附带文件数 |
| maxCharsPerFile | 200000 | 单个文件解析文本字符上限（超出截断） |
| maxCharsPerMessage | 500000 | 一次注入的文件内容总字符上限 |
| ttlMs | 1800000 (30min) | 上传文件内存保留时长，到期自动清理 |
| authToken | "" (空) | 上传路由鉴权令牌；空 = 仅同源校验（本机/局域网信任）。设置后除 /dsh-file-upload/config 外所有路由要求 x-auth-token 头匹配 |
| persistDir | "" (空) | 可选持久化目录；空 = 仅内存（TTL 后清理）。设置后待发送文件落盘，宿主重启/插件重载不丢（取走即删除） |
| rootDir | "" (空) | @ 引用的回退根目录；仅当会话无工作区目录（Session.header.cwd 缺失）时生效。空 = 回退到宿主进程 process.cwd()。列出/读取被严格限制在解析出的根目录内（路径穿越会被拒绝） |
| refMaxDepth | 6 | @ 列举时目录递归最大深度（根以下） |
| refMaxEntries | 2000 | @ 列举的可引用文件条数上限（超出截断） |

部署示例（局域网 / 服务器）

profile cordis.patch.yml 覆盖行（按 id 整体替换 config）
- id: dsh-file-uploader
config:
authToken: "change-me-to-a-long-random-string"
persistDir: "/var/lib/dsh-file-uploader"
rootDir: "/path/to/your/project"   # @ 的回退引用根（会话无工作区目录时）
maxFileBytes: 20971520

安全

上传路由 /dsh-file-upload/ 的鉴权分两档：

- 默认（未配置 authToken）：同源校验——请求带 Origin 头时必须与请求 Host 同源，
否则 403。这挡住浏览器 CSRF（恶意网页借用户浏览器向本地服务上传），适用于本机/局域网信任环境。
- 配置 authToken：所有路由（除 /config 引导端点）要求 x-auth-token 头匹配，否则 401。
令牌经 GET /dsh-file-upload/config 下发，客户端启动时拉取并附带。令牌模式兼容反向代理部署
（Origin 与内部 Host 不一致时仍可用）。

边界：令牌经同源端点下发，凡能访问服务者均可取到——它防的是「非页面客户端/偶然访问」，
不是强秘密。跨源网页因浏览器同源策略无法读取令牌响应，天然防 CSRF。真正的多用户/公网部署应在
反向代理层做认证（如 nginx basic auth / OAuth），并把 authToken 作为共享密钥配合使用。

持久化

默认待发送文件仅暂存于宿主内存（TTL 后清理，宿主重启即丢）。配置 persistDir 后：

- 每个会话一个 JSON 文件落盘，宿主重启/插件重载自动恢复；
- 文件被取走（发送注入）、清空或 TTL 过期时，对应落盘文件同步删除；
- 隐私注意：落盘文件包含文件解析后的文本，目录需受控（建议仅本机可读）。

开发与验证

bash
pnpm install                 # 安装依赖（esbuild 构建脚本需放行：pnpm-workspace.yaml 已声明）
pnpm build                   # esbuild 产出 lib/index.js（宿主）+ lib/client.js（浏览器 bundle）
npx tsc --noEmit             # 类型检查

解析逻辑验证（构造 txt/md/docx/xlsx/pdf 样例断言）
node node_modules/esbuild/bin/esbuild scripts/test-parse.mjs --bundle --format=esm --platform=node --external:fflate --external:xlsx --external:pdf-parse --outfile=.test/test-parse.mjs --log-level=warning
node .test/test-parse.mjs

宿主集成验证（真实 cordis Context + 桩 webServer：上传路由 / pre-step 注入 / attach-once / 删除 / 鉴权 / 持久化 / @ 引用路由）
node node_modules/esbuild/bin/esbuild scripts/test-integration.mjs --bundle --format=esm --platform=node --external:fflate --external:xlsx --external:pdf-parse --external:@deepseek-ai/ --outfile=.test/test-integration.mjs --log-level=warning
node .test/test-integration.mjs

@ 引用目录数据源验证（列举 / 忽略规则 / 深度与条数截断 / 路径穿越防护）
node node_modules/esbuild/bin/esbuild scripts/test-dir.mjs --bundle --format=esm --platform=node --external:fflate --external:xlsx --external:pdf-parse --external:@deepseek-ai/* --outfile=.test/test-dir.mjs --log-level=warning
node .test/test-dir.mjs

组合配置验证（不启动服务）
dsh web --dump-config | Select-String dsh-file-uploader

浏览器 bundle 格式与官方 @deepseek-ai/dsh-client-* 一致：window.__ModuleLoader__.load({ id, factory })，
平台模块（react / cordis / ui-slots / ui-primitives / client-runtime）经 factory 的 require 从模块表解析。

已知限制

- 二进制/图片文件不解析：非文本类型的文件上传会得到明确错误；混合拖放批次中的图片会被跳过
（纯图片批次仍走内置图片条带）。@ 引用只列出可解析（text/docx/xlsx/pdf）的文件，不可解析的
不会出现在候选里。
- @ 引用限制在解析出的根目录内：根为当前会话工作区（Session.header.cwd），
会话无工作区时才回退到 rootDir / 进程 cwd；/dir、/file 均做路径穿越防护
（.. / 绝对路径被拒），默认忽略 .git / node_modules / dist / build / coverage
/ .next / .nuxt 与点文件点目录，并按 refMaxDepth / refMaxEntries 封顶。
- 扫描件 PDF（图片型）无法抽取文本，上传会返回“PDF 未提取到文本”。