硬核移植实录：在 FreeBSD 15.1 上从零跑起 DeepSeek 智能体 harness（附完整踩坑手册）
关键词：FreeBSD · DeepSeek · AI Agent · dsh · 移植踩坑
适用版本：FreeBSD 14.3 / 15.1 ｜ deepseek-harness（fork 版）
repo仓库:deepseek-harness:基于 Cordis 生态的智能体框架项目 - AtomGit
0. 背景：为什么又是 FreeBSD？
DeepSeek 开源的 agent harness（dsh）官方支持 Linux / macOS / Windows，不支持 FreeBSD。但实际业务里有一大批 FreeBSD 服务器(这句话26年前对,现在真的没有一大堆了)，它们同样需要一个能写代码、能调试、能自运维的 AI 助手。
本文给出一套经过验证、可照做 的方案，把 dsh web（带 Web UI + 持久终端）在 FreeBSD 15.1 上跑起来，并重点讲清三个"反直觉"的坑------这些都是官方文档里找不到、但每个 FreeBSD 用户都会撞上的。
仓库（FreeBSD 可用版，未合入上游前请克隆此 fork）：
https://gitcode.com/skywalk163/deepseek-harness.git
https://github.com/skywalk163/deepseek-harness.git完整手册在仓库根目录：FREEBSD.md / FREEBSD.zh.md。
一、前置认知（必读，否则后面会卡）
- Web UI 只绑
127.0.0.1:3080。这是 harness 写死的信任围栏（防 confused-deputy / DNS-rebinding）。用局域网 IP 直接开 UI 会收到HTTP 403，只有 SSH 隧道能进。这不是 bug，是安全设计。 - FreeBSD 无沙箱后端 。confinement 只支持 Linux/macOS/Windows，所以必须以
danger-full-access运行（非隔离）。只在你信任的机器上这样跑。 - 代码还没合入上游，FreeBSD 可用版请从上面的 fork 取，不要克隆 deepseek-ai 官方仓库（那没有 FreeBSD 补丁）。
二、从零安装（一条线）
# 1. 系统依赖
pkg install node24 npm-node24 gmake python3 pkgconf bash
# 2. pnpm ------ 关键：用 npm 装，禁用 corepack
npm install -g pnpm@11.7.0
# 校验：which pnpm 应指向 /usr/local/lib/node_modules/pnpm/bin/pnpm.cjs（纯 JS 启动器）
# 3. gmake shim（node-gyp 需要 GNU make，FreeBSD 自带的是 bmake）
mkdir -p ~/bin
ln -s /usr/local/bin/gmake ~/bin/make
# 把 ~/bin 放到 PATH 最前（写进 ~/.shrc / ~/.bashrc）：
export PATH="$HOME/bin:$PATH"
# 4. clone（从 fork）
git clone https://gitcode.com/skywalk163/deepseek-harness.git
cd deepseek-harness
# 5. 安装 + 构建
pnpm install
pnpm run build # 含 build:lib + build:web
# 6. 启动（FreeBSD 专属脚本 = dsh + --expose-internals）
DSH_PERMISSION_MODE=danger-full-access pnpm dsh:freebsd web
# 也可以直接启动,进入交互界面后,再手工选完全控制模式
pnpm dsh:freebsd web启动后本地访问需要隧道（见第四节）。
三、三个"反直觉"的坑（本文重点）
坑 1：bash 是硬依赖，不是 sh
FreeBSD 默认 /bin/sh 是 ash 系，不认识 bash 专有的 PROMPT_COMMAND 。终端模块原来会静默回退到不存在的路径，报一个看不懂的 PTY shell exited during startup。
对策 ：代码里已加校验------shellPath 非 bash 会直接提示 pkg install bash。你只要确保装了 bash 即可。
坑 2：pnpm 不能用 corepack，否则 @pnpm/exe.freebsd-x64 校验失败
15.1 上若用 corepack enable 或 standalone 装的 pnpm，会报：
[ERROR] Cannot verify the identity of the @pnpm/exe.freebsd-x64 native binary:
it is missing from pnpm-lock.yaml根因 ：pnpm v10/v11 把自身打包成平台原生二进制 @pnpm/exe-<os>-<arch>，走原生路径时会拿 lockfile 校验身份；而本仓库 lockfile 在其它平台生成，含 80 处 freebsd 字样却 0 条 @pnpm/exe 条目，FreeBSD 一查"查无此二进制"就拒绝。
对策 ：npm install -g pnpm@11.7.0。npm 装的是纯 JS 启动器 pnpm.cjs，运行在 node 上，不触发该校验------14.3 机器就是这样跑通的。
坑 3：Web UI 必须走 SSH 隧道，局域网 IP 直接 403
# 在本机执行，把远端 3080 映射到本地
ssh -L 3080:127.0.0.1:3080 workbuddy@192.168.1.5
# 然后浏览器开 http://localhost:3080原因：harness 的 /api 信任围栏要求 host 类 RPC 的 Host 必须是 loopback，否则 HTTP 403。这是防 DNS-rebinding 的故意设计，配置无法绕过。
四、开机自启（rc.d 守护）
把 web 服务做成标准 BSD 守护脚本后，可像 nginx 一样托管：
# 安装（root）
cp /home/workbuddy/dsh_web.rcd /usr/local/etc/rc.d/dsh_web
chmod 555 /usr/local/etc/rc.d/dsh_web
sysrc dsh_web_enable=YES
# 日常管理
service dsh_web start | stop | restart | status日志和 pidfile 特意放在 home 目录、避开会被清的
/tmp，重启不丢状态。
五、git 与钩子（多人协作 / 二次开发用）
仓库配了三个远端：gitcode（origin）、github、自托管 gitea。提交时 lefthook 的 pre-commit/pre-push 钩子因 @anthropic-ai/claude-agent-sdk-linux-x64 在 FreeBSD 必然失败，需绕过：
git commit --no-verify
git -c core.hooksPath=/tmp/nohooks push <remote> <branch>六、小结
| 项目 | 结论 |
|---|---|
| 核心依赖 | node24 npm-node24 gmake python3 pkgconf bash |
| pnpm 安装 | 必须 npm -g，禁用 corepack |
| 启动命令 | DSH_PERMISSION_MODE=danger-full-access pnpm dsh:freebsd web |
| 访问方式 | SSH 隧道 ssh -L 3080:127.0.0.1:3080 → localhost:3080 |
| 沙箱 | FreeBSD 无后端，必须 danger-full-access（fail-closed 否则） |
| 开机自启 | rc.d 守护脚本 |
把上面三条咒语 + 三个坑记牢，FreeBSD 上跑 DeepSeek 智能体基本就稳了。所有细节（含排错表、已验证清单）都在仓库 FREEBSD.md 里，新手照抄即可。
让 AI 助手，也学会说 BSD 的语言。
仓库：gitcode.com/skywalk163/deepseek-harness ｜ 完整手册：仓库内 FREEBSD.md / FREEBSD.zh.md
如果本文帮你省下了半夜排错的时间，欢迎点赞收藏，也欢迎来仓库提 issue。