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 过期时，对应落盘文件同步删除；
• 隐私注意：落盘文件包含文件解析后的文本，目录需受控（建议仅本机可读）。

开发与验证

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 未提取到文本”。