前言¶
在 DSH（DeepSeek Harness）生態中，文件處理通常依賴插件分發。當需要處理本地媒體文件時，直接將大文件轉換爲 Base64 字符串會佔用大量內存，而依賴外部鏈接又存在穩定性和隱私風險。dock-media 插件解決了這一痛點，它直接在瀏覽器端通過 HTTP Range 請求流式讀取本地文件，實現音頻和視頻的即時播放。
它是什麼¶
dock-media 是一個運行在 DSH Web 環境下的客戶端插件，由維護者 AKS1st 開發。它爲 dock-files 文件域註冊了 media 文件查看器，能夠識別音頻和視頻文件，並通過自有的 /dock-media/source 主機路由提供流式傳輸服務。
核心功能¶
-
雙模式播放
插件根據文件類型自動切換視圖：純音頻文件（如 MP3、WAV）進入音樂播放器模式，展示旋轉唱片和均衡器動畫；視頻文件（如 MP4、WebM）則調用原生全屏播放器。 -
流式傳輸
不依賴整文件 Base64 編碼，而是通過 HTTPRange請求（狀態碼 206）分片返回文件字節。這支持大文件秒開、進度條拖拽定位，以及邊下載邊播放。 -
音樂播放器控制
音樂播放器提供完整的播放控制：播放/暫停、進度拖動、當前/總時長顯示、音量調節、靜音、播放速度調節（0.5x–2x）以及單曲循環功能。 -
元數據與徽章
通過/dock-media/probe接口（POST 請求）可獲取文件大小與媒體種類。播放器頭部會實時顯示文件格式徽章與大小信息。 -
優雅降級與安全
- 降級：對於瀏覽器無法解碼的封裝或編碼（如 AVI、FLV、WMV、MIDI、WMA），插件會給出明確提示，而非黑屏。
- 安全：媒體解碼完全交給原生
<audio>和<video>標籤，不使用innerHTML或危險 DOM 注入方式。
安裝與啓用¶
該插件依賴 dock 和 dock-files 插件。在安裝前，請確保這兩個插件已就緒。
dsh plugin --profile web add dock-base
dsh plugin --profile web add dock-files
dsh plugin --profile web add dock-media
典型用法¶
- 在
dock-files文件域中瀏覽文件列表。 - 點擊 MP3、WAV、FLAC 等音頻文件，或 MP4、WebM、MOV 等視頻文件。
- 系統會自動識別文件類型並打開對應的播放器。
- 通過
/dock-media/source路由訪問媒體流，支持 HTTP Range 請求。
安全與注意事項¶
- 路由安全：
/dock-media路由僅接受受信任來源的請求，包括迴環地址（localhost）以及通過trustedHosts配置的域名，並進行同源檢查。 - 文件訪問：讀取路徑僅需爲絕對路徑，不限定在當前會話工作區內，也不限定讀寫權限（僅限只讀）。
- 格式限制：
.ts文件由dock-editor處理，dock-media不接管。 - 解碼能力：瀏覽器能否解碼頭由解碼器決定，插件無法繞過瀏覽器限制播放所有格式（如 AVI、FLV 在多數瀏覽器中無法解碼）。
結尾¶
dock-media 提供了一種輕量級、內存友好的方式在 DSH 工作臺內播放本地媒體。通過 HTTP Range 流式傳輸和原生標籤渲染，它兼顧了性能與安全性，適合需要頻繁處理本地音視頻資源的場景。
- 文檔與目錄：dock-media Catalog
- 源碼倉庫：github.com/AKS1st/dock-media
