前言¶

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（宿主半边在启动时装载）。

典型用法¶

1. 在 DSH 插件列表里找到「飞牛 NAS」条目（标题与图标来自 locale/ 与 icon.png），进入详情页。
2. 点击「授权」按钮，在打开的浏览器页面粘贴一次性授权码。
3. 在对话输入框左侧点击飞牛图标，打开文件选择浮层，下钻到目标目录并选中文件。
4. 对文件执行 Ctrl + 点击，即可在对话中插入 @文件名 引用。
5. Agent 可直接调用 fnos 技能，通过插件提供的接口进行文件与目录操作。

适用场景与注意¶

适合需要在 AI 对话中直接操控 fnOS NAS 的场景，例如通过 Agent 完成批量文件整理、目录结构更新等任务。使用前需注意：插件以当前 DSH 进程权限运行，建议在安装前检查源码与许可证；网络受限时，不建议使用远程 URL 安装，避免因 GitHub 下载超时导致插件安装卡住或其它插件无法安装。

总结¶

dsh-fnos 把 fnOS 的 trim-cli 能力封装进 DSH 插件体系，通过授权、目录树选择器和技能注册，让 Agent 能在对话中直接访问 NAS 文件系统。目录缓存与主题跟随保证了使用体验的流畅与美观。完整文档与排错指引参见：https://github.com/MeetoHub/dsh-fnos