本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

dsh-file-upload

— 源: plugin_wiki.wiki_content

安装与验证

dsh plugin --profile web add dsh-file-upload

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

关键要点

• 上传:composer 回形针按钮 + 全局拖拽(拖动文件到窗口任意位置 → "松开以添加文件"遮罩 → 松开即上传),多文件支持。
• 附件卡片:按类型着色的徽标卡(PDF 红 / DOC 蓝 / XLS 绿 / TXT 灰 / ZIP 紫 / JSON 金),显示名称与大小,可移除。
• Codex 风格文件引用:上传的文件在消息中呈现为 @相对路径 引用(与 OpenAI Codex 一致),不会把全文塞进输入框;agent 用 read_document 读取(按需转 Markdown)。
• Codex 风格 @ 引用:上传后在输入框输入 @ 即可按相对路径选择已上传文件,以 mention 形式插入。
• 图片自动讲解(文本模型也能看懂):上传图片后自动通过视觉发现链生成图片描述("讲解图片"),纯文本的 DeepSeek API 也能基于图片内容推理:显式 visionEndpoint → 本地 Ollama(如 DeepSeek-VL2,零配置)→ OpenAI 兼容端点(DSH 凭据 key)。多模态模型/视觉桥接则走官方 read_image。

— 源: plugin_wiki.readme_zh (fallback readme_raw)

常见问题

上传后原始文件内容会进输入框吗？

不会。上传后界面只插入一个 Codex 风格的 @相对路径 引用，原始字节不被内联进草稿；Agent 按需调用 read_document <path> 读取，PDF/DOCX/XLSX 会按需转 Markdown 并支持分页。

上传后文本模型（比如 DeepSeek API）为什么能"读懂"我发的图片？

上传时插件会探测当前会话路由的模型：多模态模型走官方 read_image；否则触发"讲解图片"自动生成描述，按"显式 visionEndpoint → 本地 Ollama VL 模型 → OpenAI 标准端点"的顺序自动发现，描述随消息一起发出。

上传的文件存哪里？安全吗？

存在当前会话工作区的 .dsh-uploads/<sessionId>/ 下，按会话隔离、未授权会话返回 403；HTTP 仅监听 loopback 主机、上传时同源校验、文件名做清洗、相同内容用 sha256 去重、并发数超限返 429，超过 TTL 的目录会被后台清扫。

必须安装 Python 或 markitdown CLI 吗？

不必。MarkItDown 能力已作为 markitdown-node 依赖打进插件（覆盖 PDF/DOCX/PPTX/XLSX/HTML/CSV/JSON/XML/ZIP/Jupyter 等 20+ 格式，含图片 OCR），完全本地离线运行；若机器上已经有官方 markitdown CLI，插件会自动改用它来支持 EPUB 等更多格式。

文件上传后多久会被自动删除？

默认 7 天（uploadTtlMs=604800000 毫秒）。后台每 1 小时扫一次（sweepIntervalMs=3600000 毫秒），扫描每个会话工作区下的 .dsh-uploads/<sessionId>/，整目录超时即清；把 sweepIntervalMs 设为 0 可关闭定期清扫。

安装后界面没出现回形针按钮，怎么办？

客户端 bundle 只在全新页面加载时挂载。先 dsh plugin --profile web add github:HongMing-Huang/dsh-file-upload，再重启 DSH Web 服务，最后在浏览器做硬刷新（Cmd/Ctrl+Shift+R）。

单个文件最大能传多大？能限制扩展名吗？

默认上限 24 MB（uploadMaxBytes），可在配置中改大；allowedExtensions 留空表示不限制，填入小写扩展名数组（如 ["pdf","docx","png"]）后其他扩展名会被 415 拒绝。

DSH 卸载 / 升级这个插件的命令是什么？

升级：dsh plugin --profile web update github:HongMing-Huang/dsh-file-upload；卸载：dsh plugin --profile web remove github:HongMing-Huang/dsh-file-upload；之后同样要重启 Web 服务并硬刷新浏览器。

— 源: plugin_wiki.faq_json

兼容性

• DSH: 0.1.0-rc.6+
• Node: >=22.6.0

— 源: plugin_wiki.compatibility_json

踩坑提醒

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则