dsh-fnos

---

为什么需要它

飞牛 fnOS 提供了官方 CLI（trim-cli），能力很全 —— 但它是个终端工具。想在 AI 对话里让 Agent 帮你操作 NAS，你得反复：

trim-cli login                 # 打开浏览器、粘一次性授权码
trim-cli file ls /vol1/1000    # 一层层翻目录找路径
# 然后手动把路径复制进对话

dsh-fnos 把这三步搬进 DSH 界面：

• 授权变成插件详情页里的一个按钮
• 翻目录变成输入框旁边的浮层，点两下就到
• 引用文件变成 Ctrl + 点击，路径自动变成 @文件名

对 Agent 来说，它还同时注册了 fnOS 技能，Agent 知道该调哪些命令、参数怎么填。

---

界面预览

文件 / 文件夹选择器 输入框左侧飞牛图标点开即目录树，文件夹可下钻；Ctrl + 点击 直接以 @文件 引用插入，不用先打 /

插件详情页 主机 / 端口 / 协议 / 证书校验都写在插件自己的页面里，授权状态一目了然，不污染全局设置

---

功能

	能力	说明
🔐	授权登录	走 trim-cli 的 OAuth 设备码流程，插件页里点一下 → 打开浏览器 → 粘回授权码。结论只认 system info，不会被"静默退出"骗过
📂	文件 / 文件夹选择器	目录树浮层，文件夹可下钻、文件可选中，Ctrl/Cmd + 点击 直接插入引用
⚡	目录缓存	内存直读 + 落盘快照，打开恒为毫秒级；冷启动实测 3366 ms → 3–81 ms
🎨	主题跟随	全部用 --dsw-alias-* 变量 + 毛玻璃，跟随 DSH 皮肤，深色/浅色都不破相
🧠	技能自动注册	插件激活即向 DSH 注册 fnos 技能，Agent 立刻知道怎么用 NAS
🩺	自检探针	GET /fnos/probe 返回服务可用性、CLI 路径、缓存规模，排障不用猜

---

安装

三种方式，都不需要 clone、不需要构建 —— lib/ 已是可直接运行的代码。

最快（推荐）

在 DSH 里把 Release 的 tgz 地址交给插件管理器。

按你的系统选一个（包里已含本平台的 trim-cli，装完即可用，无需再下载）：

系统	下载量	包名
Windows x64（最常见）	3.1 MB	dsh-fnos-windows-x64.tgz
Windows ARM64	2.8 MB	dsh-fnos-windows-arm64.tgz
macOS Apple 芯片	3.3 MB	dsh-fnos-darwin-arm64.tgz
macOS Intel	3.4 MB	dsh-fnos-darwin-x64.tgz
Linux x64	3.3 MB	dsh-fnos-linux-x64.tgz
Linux ARM64	3.1 MB	dsh-fnos-linux-arm64.tgz
不确定 / 想一次覆盖所有平台	17.5 MB	dsh-fnos.tgz

以 Windows x64 为例：

plugin_manager  install_bundle  target = https://github.com/MeetoHub/dsh-fnos/releases/latest/download/dsh-fnos-windows-x64.tgz

为什么分平台：官方 trim-cli 有 6 个平台的二进制，合计 41 MB。 全部塞进一个包，用户要多下十几 MB 才能用；只装自己那一个，下载量降到 1/5.7。 完整包 dsh-fnos.tgz 仍然保留，兼容不确定自己平台的情况。

粘仓库地址

plugin_manager  install_bundle  target = github:MeetoHub/dsh-fnos

会完整拉取仓库（含 bin/ 二进制），比上一个慢。要固定版本加 #v0.4.0。

⚠️ 必须写成 github:MeetoHub/dsh-fnos（github: 开头，没有 https://）。 直接把浏览器地址栏的 https://github.com/MeetoHub/dsh-fnos 粘进去会装不上—— 那是一个网页地址，pnpm 拿它 clone 只会拿到 HTML，表现为「安装失败 / 无输出」。

⚠️ 网络受限时不要用远程 URL 安装

用 https://…/dsh-fnos-x.y.z.tgz 这类远程 URL 装进 profile 后，pnpm 会把它当作 一条需要联网校验的依赖。之后你安装任何其它插件，pnpm 都会重新解析整张依赖图， 从而再次请求这个 GitHub 地址。

如果该地址不可达（实测部分网络对 GitHub releases 超时 21 秒），表现为 「插件安装中…」一直转圈、新插件装不上，而且很难联想到是 fnos 引起的。

受限网络下的正确做法：

# ① 开发态：本地软链，完全不联网
plugin_manager  install_bundle  target = /path/to/dsh-fnos

# ② 离线安装：先把 tgz 下到本地，再用文件路径
plugin_manager  install_bundle  target = file:/path/to/dsh-fnos-0.2.2.tgz

# ③ 确认 profile 里没有残留的远程依赖
grep 'https\?://' "$DSH_PROFILE_DIR/package.json"

源码开发态

cd "$DSH_PROFILE_DIR"
pnpm add link:/path/to/dsh-fnos

改代码即时生效（宿主侧在插件管理器里关/开一次，客户端侧刷新页面）。

装完需重启一次 DSH（宿主半边是 Node 模块，启动时装载）。

完整步骤、前置条件、卸载与排错见 docs/INSTALL.md。

---

它怎么工作

插件由两个半边组成：

半边	文件	职责
客户端	lib/client.js	输入框图标、文件选择浮层、插件详情页配置。跑在 Web UI
宿主	lib/impl.js · lib/auth.js	HTTP 路由、授权状态机、目录缓存。跑在 DSH 主进程

两者只通过 DSH 自己的 HTTP 路由通信（/fnos/auth/*、/fnos/files、/fnos/probe）， 不使用任何私有 IPC —— 所以插件升级不会因为 DSH 内部变动而失效。

对 NAS 只有一种依赖：官方 trim-cli，按三级顺序查找：

FNO_TRIM_CLI 环境变量  →  包内 bin/  →  系统 PATH

三级都没有时报一条可操作的中文错误，而不是拿不存在的路径去 spawn。

---

性能

目录读取走内存 + 落盘快照，打开永远不阻塞：

场景	耗时
冷启动（实时调 NAS）	3366 ms
缓存命中	3 – 81 ms
DSH 重启后（从磁盘恢复）	9 – 67 ms

后台刷新默认关闭：spawnTerminal 每次调用在本平台会残留约 11 个句柄， 而打开目录树本来就靠 peek() 走内存。需要更新鲜的数据时带 ?fresh=1 强制刷新， 或设 FNO_BACKGROUND_REFRESH=1 打开自调度刷新（20 秒 / 每轮 1 条 / 不重叠）。

这一条来自一次真实事故 —— 详见 docs/PITFALLS.md 第 9 条。

---

技能与 CLI 的更新

官方技能包是带版本号的 zip（含 SKILL.md、entries/、reference/、bin/trim-cli）， 版本与 SHA256 公布在官网下载页。本插件启动时会非阻塞地检查并同步最新版：

步骤	说明
检查	抓 fnnas.com/download，解析官方公布的 {version, url, sha256}
下载	① 直连官方 CDN → ② Release 镜像
校验	SHA256 必须一致，否则整包丢弃
安装	解压到 ~/.dsh/fnos-skill/v{ver}/，成功后原子切换 current.json
兜底	失败静默，已装版本继续可用；装坏可回退
清理	装成功后立即删除原始 zip，版本目录只留当前 + 上一个，不会越攒越多

CLI 查找顺序随之升级为四级：

FNO_TRIM_CLI  →  官方技能包 bin/  →  插件内 bin/  →  系统 PATH

技能内容也优先取同步下来的官方版本（source: runtime），所以文档不会随插件发版而落后。

官方 CDN 被墙时

部分网络对 iso.liveupdate.fnnas.com 直接返回 403（实测 curl / Node / 真实浏览器内核均被挡）。 这时把官方 zip 放进下面这个目录，重载插件即自动安装（文件名任意，.zip 结尾即可）：

~/.dsh/fnos-skill/incoming/fnos-skill.zip

安装成功后原始 zip 会被立即删除（回滚点由保留下来的上一个版本目录提供），不会重复安装，也不会长期占用空间。

关闭自动同步：设环境变量 FNO_SKILL_SYNC=0。

---

安全与隐私

• 凭据不出本机：授权状态由 trim-cli 自己管理，插件不落盘任何 token
• 不做外发：除你的 NAS 地址外，插件不向任何第三方发起请求
• 自签证书：默认容忍设备的自签证书（tlsInsecure），仅影响该 NAS 的 TLS 校验
• 可审计：全部逻辑在 lib/（约 1.6k 行），无混淆、无压缩产物

---

常见问题

装完看不到图标？

首次安装新包必须重启 DSH，仅刷新页面不够（宿主半边在启动时装载）。

授权一直失败 / 授权页报「参数异常」？

海外版 FygoOS 固件的 OAuth 端点不识别 trim-cli 的 client_id，属设备侧限制，插件无法绕过。国内版 fnOS 正常。

提示找不到 trim-cli？

按提示任选一种：放进插件 bin/ 目录、加入系统 PATH、或用 FNO_TRIM_CLI 指定绝对路径。

从 GitHub 地址安装时报 NPM_EPERM？

说明该插件已经以本地软链形式装着，同一个包名不能两种装法并存。 先 remove_bundle，再装，或继续用软链（开发态更适合）。

---

参与开发

文档	内容
docs/DEVELOPMENT.md	开发循环、分支与版本约定、发版流程、三道安全防线
docs/PITFALLS.md	10 条踩坑记录（含一起内存泄漏事故的完整复盘）
docs/INSTALL.md	三种安装方式的完整说明与排错

新克隆仓库后请先启用敏感内容扫描（防把内网地址带进公开历史）：

git config core.hooksPath scripts/hooks

发版只要三步：

npm version patch --no-git-tag-version
git commit -am "chore: release vX.Y.Z" && git push
git tag vX.Y.Z && git push origin vX.Y.Z     # CI 自动建 Release 并附 tgz

---

许可

自有代码 MIT，见 LICENSE。

bin/ 下是飞牛官方 trim-cli 预编译产物（六个平台，约 41 MB），版权归飞牛 fnOS 所有， 仅随本插件分发作运行依赖 —— 不构成对本项目的授权。详见 NOTICE。