前言¶
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
