前言¶
DeepSeek Harness（DSH）採用「一切皆插件」的架構，插件運行在 DSH 進程權限下。飛牛 fnOS 提供了官方 CLI（trim-cli），能力很全，但它是一個終端工具。想在 AI 對話裏讓 Agent 幫你操作 NAS，你通常要反覆在終端與瀏覽器之間切換：先登錄、再翻目錄找路徑、再把路徑複製到對話。dsh-fnos 把這套流程搬到 DSH 插件體系裏：授權、目錄瀏覽、文件引用，都通過插件界面完成，不打開終端。
它是什麼¶
dsh-fnos 是 MeetoHub 維護的 DSH 插件，定位爲飛牛 fnOS 的接入層。插件負責與 fnOS 的 trim-cli 協作，把文件系統操作、授權流程、目錄樹緩存等能力暴露給 DSH 的 Agent。它運行在 DSH 進程內，依賴官方 trim-cli，不存儲憑據、不向第三方發起請求。
核心功能¶
- 授權登錄：走
trim-cli的 OAuth 設備碼流程，在插件詳情頁點擊授權按鈕，打開瀏覽器、粘貼一次性授權碼。插件只通過system info判斷狀態，避免被靜默退出誤導。 - 文件 / 文件夾選擇器：輸入框左側飛牛圖標打開目錄樹浮層，支持下鑽與選中；
Ctrl/Cmd + 點擊直接以@文件格式插入引用，無需先手動輸入路徑。 - 目錄緩存：內存直讀 + 落盤快照，打開操作通常在毫秒級（冷啓動約 3366 ms，緩存命中 3–81 ms，DSH 重啓後恢復 9–67 ms）。
- 主題跟隨：使用
--dsw-alias-*變量與毛玻璃效果，跟隨 DSH 皮膚，適配深色與淺色主題。 - 技能自動註冊：插件激活時向 DSH 註冊
fnos技能，Agent 可直接調用相關命令與參數。 - 自檢探針：提供
GET /fnos/probe接口，返回服務可用性、CLI 路徑、緩存規模，便於排查問題。
安裝與啓用¶
插件通過三種方式安裝，無需 clone 或構建（lib/ 已是可運行代碼）。
最快方式（推薦）：在 DSH 插件管理器裏把 Release 的 tgz 地址交給插件管理器。以 Windows x64 爲例：
plugin_manager install_bundle target = https://github.com/MeetoHub/dsh-fnos/releases/latest/download/dsh-fnos-windows-x64.tgz
包內已含當前平臺的 trim-cli，安裝後即可使用，無需額外下載。
粘倉庫地址：
plugin_manager install_bundle target = github:MeetoHub/dsh-fnos
會完整拉取倉庫（含 bin/ 二進制），比上一個方式慢。如需固定版本，可在末尾加 #v0.4.0。注意必須寫成 github:MeetoHub/dsh-fnos（github: 開頭，不帶 https://），直接粘貼瀏覽器地址欄的 HTTPS 鏈接會導致安裝失敗或無輸出。
源碼開發態：
cd "$DSH_PROFILE_DIR"
pnpm add link:/path/to/dsh-fnos
修改代碼後，在插件管理器裏重啓插件或刷新頁面即可生效。安裝完成後需重啓一次 DSH（宿主半邊在啓動時裝載）。
典型用法¶
- 在 DSH 插件列表裏找到「飛牛 NAS」條目（標題與圖標來自
locale/與icon.png），進入詳情頁。 - 點擊「授權」按鈕，在打開的瀏覽器頁面粘貼一次性授權碼。
- 在對話輸入框左側點擊飛牛圖標，打開文件選擇浮層，下鑽到目標目錄並選中文件。
- 對文件執行
Ctrl + 點擊，即可在對話中插入@文件名引用。 - Agent 可直接調用
fnos技能，通過插件提供的接口進行文件與目錄操作。
適用場景與注意¶
適合需要在 AI 對話中直接操控 fnOS NAS 的場景，例如通過 Agent 完成批量文件整理、目錄結構更新等任務。使用前需注意：插件以當前 DSH 進程權限運行，建議在安裝前檢查源碼與許可證；網絡受限時，不建議使用遠程 URL 安裝，避免因 GitHub 下載超時導致插件安裝卡住或其它插件無法安裝。
總結¶
dsh-fnos 把 fnOS 的 trim-cli 能力封裝進 DSH 插件體系，通過授權、目錄樹選擇器和技能註冊，讓 Agent 能在對話中直接訪問 NAS 文件系統。目錄緩存與主題跟隨保證了使用體驗的流暢與美觀。完整文檔與排錯指引參見：https://github.com/MeetoHub/dsh-fnos
