deepseek-harness-fnos

DeepSeek Harness for fnOS

把 DeepSeek 官方 Agent 浏览器 UI（DeepSeek Harness / dsh）装成飞牛 fnOS 常驻应用：离线安装免联网，局域网与 FN Connect 直连，自带 28001 管理面板

下载 · 功能 · 快速开始 · 访问方式 · 管理面板 · 配置 · 贡献者致谢 · 更新日志

上游项目：deepseek-ai/deepseek-harness（DeepSeek Harness 开发者预览版，官网 ）。本仓库不 fork 上游代码，只负责 fpk 打包、fnOS 生命周期脚本和少量运行时 / 构建期补丁；应用图标为 DeepSeek 官方黑色鲸鱼 logo。

下载

从 Releases 下载对应架构的 fpk：

架构 · 文件 · 说明 x86 · dsh--iframe-x86.fpk · 推荐：fnOS 桌面窗口内打开 x86 · dsh--x86.fpk · 桌面图标在浏览器新标签页打开 ARM · dsh--iframe-arm.fpk · 推荐：fnOS 桌面窗口内打开 ARM · dsh--arm.fpk · 桌面图标在浏览器新标签页打开

版本号跟随上游 @deepseek-ai/dsh 发行版（目前均为 -rc 预览版本，如 0.1.7-rc.2），本地修复不单独抬版本号。

全部为离线包（内置对应架构的 node_modules），安装时无需联网拉取 dsh；单个 fpk 约 120 MB。0.1.7 起 fpk 超过 Gitee 附件 100 MB 上限，安装包只在 GitHub Release 提供。

依赖应用：安装时 fnOS 自动安装 nodejs_v24 与 bunjs（manifest install_dep_apps）。manifest 未声明最低 fnOS / 应用中心版本。

ARM 版在 manylinux_2_28 容器中编译原生模块，要求系统 glibc ≥ 2.28（fnOS ARM 设备为 Debian 12 / glibc 2.36）。

架构

功能

离线自托管

• 安装免联网：@deepseek-ai/dsh 连同 node_modules 随 fpk 内置；只有离线包缺失时才回退到在线 npm install（单线程 + 512 MB 堆，照顾 1 GB 内存的小设备）
• 双架构：x86 与 ARM 各出 iframe / url 两个变体，均由 GitHub Actions 在线打包
• 常驻服务：以应用专属账号 dsh 运行（run-as: package），由 cmd/main 管理 start / stop / status / restart

访问与安全

• 局域网直连：通过 cordis.patch.yml 把 dsh web 绑定到 0.0.0.0:28000（dsh CLI 本身拒绝 --host 0.0.0.0）
• 信任围栏：/api/* 校验 Host / Origin，只放行回环地址 + --trusted-host 列表（启动时自动探测的本机 IP + fnos.net / 5ddd.com + trusted_hosts.conf 中的域名），其余来源 403
• 桌面免 401：上游 0.1.2 起的浏览器 token 鉴权对静态桌面入口不可用，运行时补丁对已通过围栏的请求放行（等效「围栏即认证」）
• FN Connect / DDNS 远程访问：安装向导或应用设置里填 FN ID / 自定义域名，自动写入信任域，远程访问不再 403
• 设置页 host 模式：构建期补丁让非回环访问（局域网 IP、FN Connect 域名）也能读写服务端配置，插件 / 模型设置不再空白

运维

• 28001 管理面板：服务状态、三路日志、插件启停 / 删除 / 安装、版本检查、一键重启 dsh、一键下载并热安装更新（见 管理面板）
• 启动自愈：启动前把 .credentials.yaml / .env 修正为 600 权限、清理占用 28000 端口的残留进程、修正被 root 误建的 .gitconfig 权限
• 数据保留：升级不动数据区，卸载脚本只清理日志与 pid，都不删除 dsh_home（工作空间、会话、API Key、代理与信任域配置）

Agent 运行环境

• dsh 的 Agent / bash 工具可直接使用 node / npm / npx / pnpm / yarn / corepack / bun（来自依赖应用，启动时自动加入 PATH；见 Agent 环境命令）
• npm 全局安装与 corepack 缓存都指向数据区，不占系统盘

官方插件兼容

• 语音输入（实验性）：官方 @deepseek-ai/dsh-experimental-voice-input-bundle（本地 SenseVoice 转写）在 fpk 下完整可用 —— 模型下载走 proxy.conf 代理，麦克风走 FN Connect HTTPS 入口或浏览器标志位启用；实测记录与局域网方案见 语音输入插件兼容指南

快速开始

安装

1. 从 Releases 下载对应架构的 fpk（推荐 iframe 变体），在 fnOS 应用中心选择手动安装
2. 安装向导（所有项都可留空，之后再配）：

字段 · 说明 DeepSeek API Key · sk- 开头，写入数据区 dsh_home/.env 代理 IP / 代理端口 · 两项都填才生效，拼成 http://IP:端口 写入 proxy.conf；访问 GitHub / 外部 API 超时再填 FN Connect ID · 只填 ID（如 techysy），自动生成 .fnos.net、dsh..fnos.net 信任域；fnos.net 与 5ddd.com（飞牛两条域名后缀）已内置 自定义域名 · 用自己的域名做 DDNS 远程访问时填完整域名（不带 https://），追加到信任域

1. 在 fnOS 桌面打开 DeepSeek Harness 图标进入 UI；或浏览器访问 http://:28000

升级

• 应用中心：下载新版 fpk 后手动安装覆盖，数据区保留
• 管理面板一键更新：http://:28001/ →「一键下载到 NAS」→「安装更新」（需先做一次 sudo 授权，见 管理面板）

卸载

卸载前先停止 dsh 与网关代理，卸载后清理数据区的 *.log / *.pid；dsh_home 不会被卸载脚本删除，重装后数据仍在。

访问方式

入口 · 地址 · 说明 fnOS 桌面图标 · 随 fnOS 访问方式自适应（走统一网关 /app/dsh） · 推荐入口：局域网、DDNS、FN Connect 下都可用，自带 fnOS 登录保护 统一网关 · https:///app/dsh/ · 与访问 fnOS 的域名/协议同源 —— DDNS / 自定义域名的正解入口，免暴露 28000、无混合内容问题 局域网 / Tailscale · http://:28000 · 直连端口；本机所有非回环 IPv4 启动时自动加入信任列表 FN Connect · https://dsh..fnos.net · 需在安装向导 / 应用设置中填写 FN ID；https://.fnos.net、https://fnos.net/ 同样被信任。飞牛 5ddd.com 后缀域名已内置信任，无需填写 自定义域名（DDNS） · https:// · 需在安装向导 / 应用设置中填写自定义域名（28000 直连信任面）；走网关则无需填写 管理面板 · http://:28001/ · 与 dsh 相同的信任面

统一网关细节与打通过程见 docs/dsh-access-and-gateway.md。远程场景推荐网关入口；28000 直连入口保留。

安全机制（0.2.0-rc.2 现状，补丁均为幂等，每次启动 / 安装时自动检查）：

机制 · 实现 · 说明 0.0.0.0 绑定 · cmd/main 写 dsh_home/profiles/web/cordis.patch.yml · 覆盖 webserver 的 host / port 信任围栏 · cmd/main 以单个 --trusted-host 传入全部信任值 · 该参数是 variadic，重复写 flag 只保留最后一个 桌面免 401 · cmd/main 内联补丁 dsh-client-connection 的 isAuthenticated（python3 不可用时用 node 兜底） · 结果写入 app.log；请勿把 28000 / 28001 暴露到不受信任的网络 附件权限隔离 · cmd/main 内联补丁 dsh-attachment-local 的 ensureDurableHome（issue #9） · 限制 durability 同步在 dsh_home 内部，防止越界访问 @appshare 报 EACCES 特权 API 放行 · 同上 · 上游 0.1.2 起已原生修复，补丁自动跳过 设置页 host 模式 · 构建期 cmd/patch_settings_memory.py，安装 / 升级时再补一次 · 非回环访问读写服务端配置

📖 围栏与回环限制详解：docs/dsh-loopback-restriction.md

管理面板

0.1.5-rc.2 起内置独立管理面板（cmd/dashboard.js，零依赖纯 node），随 dsh 自动启动，浏览器打开 `http://:28001/`：

功能 · 说明 总览 · dsh web 进程 / 健康检查 / 运行时长、网关代理、fpk 与已装 dsh 版本、磁盘占用（数据区 + 语音模型缓存 + update 目录） 日志查看 · app.log（生命周期）/ dsh.log（dsh 输出）/ dashboard.log（面板），关键字一键过滤（error / EADDRINUSE / patch / share:）+ tail 尾部 + 5 秒自动刷新 插件管理 · 数据源合并 bundles ∪ dependencies：第三方插件与官方实验性插件（@deepseek-ai/dsh-experimental-*，如语音输入）禁用 / 启用 / 删除 / 安装（改 profiles/web/package.json 的 bundles，重启 dsh 生效）；官方插件安装时自动钉到已装 dsh 版本（安装前明示确认），默认源失败回退 npmmirror，失败原因可读化；官方插件与 dsh 版本一致性检查 版本检查 · 上游版本优先取 GitHub deepseek-ai/deepseek-harness 的 Release Tag，取不到回退 npmmirror / npmjs；本项目最新 Release 优先 GitHub、Gitee 兜底；fpk 升级后首访显示更新横幅 一键重启 dsh · 经 cmd/main restart 执行，面板自身不受影响 📥 一键更新 · 从 GitHub 直链下载本机架构的 iframe 变体 fpk（实时进度条：百分比 / 速度 / 剩余时间；下载目录可选 —— fnOS ≥ 1.34.0 经开放平台 API读取应用授权目录，老系统回退默认 dsh_home/update/），再点「安装更新」经 appcenter-cli install-fpk 完成安装与重启；sudo 白名单一次配置永久生效（仅限所选目录内的 fpk），面板可探测已授权状态 出站代理 · 面板内配置 GitHub/Gitee 代理（HTTP CONNECT 隧道），与 dsh 主进程共用 proxy.conf，面板立即生效、dsh 重启后生效 界面 · UI 对齐 CreditDaddy 设计语言（视图导航 / panel+toolbar / 卡片 / 胶囊状态 / SVG 图标 / dsh 鲸鱼 logo），日 / 夜主题、中英双语

• 信任面与 dsh 一致：本机 / 局域网 IP、fnos.net / 5ddd.com 及其子域、trusted_hosts.conf 自定义信任域可访问，其余来源 403
• 面板日志写入数据区 dashboard.log；cmd/main stop 不停面板，卸载时由 uninstall_callback 显式停止

启用热更新（一次性，SSH 到 NAS 执行；面板「已下载的更新」卡片会给出跟随当前下载目录的完整命令，直接复制即可）：

# 默认下载目录 (共享工作区) 的白名单示例:
echo 'dsh ALL=(root) NOPASSWD: /usr/local/bin/appcenter-cli install-fpk /vol*/@appshare/dsh/dsh_home/update/*' | sudo tee /etc/sudoers.d/dsh-hotfix
sudo chmod 440 /etc/sudoers.d/dsh-hotfix

白名单是永久生效的精确路径授权：仅允许 appcenter-cli install-fpk 安装该目录内的 fpk，无法执行其他命令。授权状态面板会自动探测显示；若下载目录换到其他授权目录，按面板提示更新白名单路径即可。不授权则按钮提示失败，可改用应用中心手动安装（fpk 已下载在工作区 update/ 或所选下载目录）。

独立桌面窗口应用（DSH 管理面板）

由于 fnOS 架构限制每个 fpk 安装包仅允许注册一个桌面启动图标（desktop_applaunchname），为了让用户在飞牛桌面上拥有独立的 DSH 管理面板 快捷窗口（类似 Hermes Agent），本项目提供了独立的伴生桌面窗口应用：

• 应用标识：dsh-dashboard（桌面名称「DSH 管理面板」）
• 通用架构：纯 Python 标准库网关代理，跨平台兼容（platform = all，单个 fpk 支持 x86_64 与 ARM64）
• 网关集成：支持 fnOS 统一网关（microApp: true）与 DDNS 远程访问，自动将路径重写与 Host 回环映射，透明代理至本机 127.0.0.1:28001
• 独立维护：源码位于本仓库 dashboard-app/ 目录，由独立的 GitHub Actions 工作流（.github/workflows/build-dashboard-app.yml）按需手动打包，无需频繁与上游 dsh 同步

安装主程序 dsh 后，直接在 Releases 下载 dsh-dashboard-v1.0.2.fpk 在应用中心手动安装，即可在飞牛桌面获得独立的管理面板窗口图标。

旧版本 fpk 加装管理面板

把仓库中的 cmd/dashboard.js 与最新 cmd/main 拷到 /var/apps/dsh/cmd/，重启 dsh 即可。从 Windows 拷贝时注意把 CRLF 转成 LF（否则报 $'\r': command not found）。

配置

DeepSeek API Key

• 安装向导填写，或编辑数据区 dsh_home/.env：

DEEPSEEK_API_KEY=sk-xxx

• 也可在 dsh 设置页内直接配置官方 / 自定义提供方的 API Key（改后重启应用生效）
• 应用设置页不含 API Key 字段；.env 权限每次启动自动修正为 600

网络代理（可选）

在安装向导或应用设置页填写代理 IP + 端口，写入 dsh_home/proxy.conf：

PROXY=http://127.0.0.1:7890

启动时据此设置 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY 并写入 git 全局代理，dsh 的出站请求（git / npm / API）走该代理；没有 proxy.conf 或没有 PROXY= 行则不走代理。启动环境已带 HTTP_PROXY 时以环境变量为准；上游 0.1.2 起也遵循 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY。

信任域（FN Connect / 自定义域名）

dsh_home/trusted_hosts.conf，每行一个主机名，# 开头为注释；http(s):// 前缀和结尾 / 会被自动去掉。可在安装向导或应用设置页修改：

• FN Connect ID：重写整个文件为 .fnos.net、dsh..fnos.net、fnos.net
• 自定义域名：追加一行

应用设置页的字段留空表示保留当前值；修改后重启应用生效。

端口与数据区

服务 · 端口 / 路径 · 说明 dsh web · 0.0.0.0:28000 · DeepSeek Harness 浏览器 UI（TRIM_SERVICE_PORT 可覆盖） 管理面板 · 0.0.0.0:28001 · dashboard.js 网关 socket · /var/apps/dsh/target/app.sock → proxy.py · 统一网关 /app/dsh（DDNS / HTTPS 入口，见 访问方式）

数据分两处存放 —— 工作空间放共享目录（文件管理器可见、SMB 可共享、卸载不删），凭据留在数据区（不对外暴露）：

位置 · 路径 · 内容 共享目录 · /vol/@appshare/dsh/dsh_home · dsh 的 HOME：profiles/web/（插件与 cordis.patch.yml）、会话 / 工作空间文件、update/（热更新下载）、.npm-global / .npm / .corepack 数据区 · /vol/@appdata/dsh · 生命周期日志（app.log / dsh.log / proxy.log / dashboard.log）、install.log / config.log、pid、dsh-web-url.txt 数据区 · /vol/@appdata/dsh/dsh_home · 凭据类：.env（API Key）、.credentials.yaml、proxy.conf、trusted_hosts.conf、迁移标记 .migrated-to-share

凭据以软链形式接入共享 HOME（dsh 仍从同一 HOME 读取），真实文件始终留在数据区。

卸载行为：@appshare 是 config/resource 声明的共享目录，fnOS 卸载时不清理——工作空间与会话得以保留；@appdata 会被清理，凭据随之移除（重装后重填，符合预期）。

老版本（数据全部在 @appdata/dsh/dsh_home）首次启动会自动迁移到上述布局：逐文件校验大小，任一文件不符即整体回退旧布局并保留原数据，下次启动重试。

Agent 环境命令

安装后可在 dsh 的 Agent / bash 工具里直接使用以下命令（来自 fnOS 依赖应用，启动时自动加入 PATH）：

命令 · 来源 · 版本验证 · 数据落点 node · nodejs_v24 依赖 · node -v · — npm / npx · nodejs_v24 · npm -v · 全局安装 → 数据区 dsh_home/.npm-global pnpm / yarn · corepack（nodejs_v24） · pnpm --version · corepack 缓存 → 数据区 dsh_home/.corepack bun · bunjs 依赖 · bun --version · — corepack · nodejs_v24 · corepack --version · —

# 一键验证全部命令
node -v && npm -v && pnpm --version && yarn --version && bun --version

完整命令兼容矩阵与实测版本号见 docs/dsh-nodejs-commands.md。

项目结构

deepseek-harness-fnos/
├── app/
│   ├── server/                  package.json 只声明 @deepseek-ai/dsh 版本；打包时 npm install 成离线 node_modules
│   └── ui/                      桌面入口配置 config（iframe / url）与图标
├── cmd/
│   ├── main                     start / stop / status / restart：运行时补丁、信任域、启动 dsh + proxy + 面板
│   ├── install_* · upgrade_*    安装 / 升级：写 .env / proxy.conf / trusted_hosts.conf、settings 补丁、离线包检查
│   ├── config_*                 应用设置页保存（代理 / FN ID / 自定义域名）
│   ├── uninstall_*              停止进程、清理日志与 pid
│   ├── dashboard.js             28001 管理面板
│   ├── proxy.py                 统一网关代理（app.sock → 127.0.0.1:28000）
│   └── patch_settings_memory.py 设置页 memory→host 补丁
├── dashboard-app/               DSH 管理面板独立桌面窗口应用（伴生 fpk 包，platform = all 通用架构）
│   ├── app/ui/config            桌面入口配置（iframe / microApp: true / app.sock）
│   ├── cmd/main · proxy.py      生命周期脚本与网关代理（/app/dsh-dashboard → 127.0.0.1:28001）
│   └── manifest · VERSION       dsh-dashboard 应用清单与版本
├── config/                      privilege（run-as package）· resource（data-share 声明）
├── wizard/                      install（安装向导）· config（应用设置页）
├── scripts/                     离线打包、ARM node_modules 构建、补丁注入、401 热修、Release 通知、临时测试脚本
├── docs/                        打包 / 访问 / 回环限制 / Node 环境 / 上游同步文档，forum-templates/ 论坛发帖模板
├── release-0.1.7-rc.2/          该版本 Release 正文
├── .github/workflows/           build-fpk.yml（在线打包 + 上传 Release）· build-arm-node-modules.yml
├── manifest · VERSION           fpk 清单与版本号
├── ICON.PNG · ICON_256.PNG      应用图标
├── CHANGELOG.md · test log.md   更新日志 / 各版本测试报告
└── LICENSE

开发者：打包、补丁与发版

两条打包路径产出一致的 fpk（url 版 + iframe 版），详见 docs/packaging-fpk.md。