前言¶

在 DSH 裏做智能體開發，往往只有「這一臺機器上的會話」；若主 loop 在別處選任務、記賬本、做策略，執行端仍需有人把任務落到具體目錄、跑模型、把進度回傳。把整套 foreman 邏輯裝進每檯筆記本既不合適，也讓 NAT 後的設備難以被穩定訪問。dsh-foreman-node 是 foreman 體系的設備側插件：本機主動連出去接單，在本地建受限會話幹活，用統一協議回報狀態，工單與決策仍留在主 loop 的 dsh-foreman 一側。

這是什麼¶

• 名稱與維護者：GitHub 倉庫 niechao136/dsh-foreman-node，作者 niechao136；非 DeepSeek 官方產品。
• 定位：裝在「要被主 loop 派活」的機器上（公司筆記本、宿舍電腦等）。不做工單、評估、決策、策略、數據庫或 SQLite；「這事該不該做」由主 loop 判斷。
• 當前狀態：README 標明早期開發中；協議、連接、接單與回報工具已落地，測試 15 項。package.json 版本爲 0.6.1，許可 MIT。

主 loop 與設備的關係可概括爲：主 loop 負責賬本與下發；設備通過出站 WebSocket 連接，在本地維護 job-<assignmentId> 會話並回報。

┌──────────── 主 loop（另一臺機器）────────────┐
│  dsh-foreman：唯一賬本、選設備、下發、收回報     │
└────────────────────┬─────────────────────────┘
                     │  設備主動外連（wss）
                     ▼
     ┌───────────────────────────────┐
     │  dsh-foreman-node（本機）      │
     │  job-<id> 會話，權限受限       │
     │  你自己的 DSH 一切照常         │
     └───────────────────────────────┘

核心功能¶

下面按 README 描述的三件事說明插件在設備上實際做什麼。

連出去¶

設備側通過 wss 連到主 loop 提供的穩定域名，斷線後指數退避重連。連接方向是出站，公司 NAT 後面一般也能用。若配置了 SSH 隧道，插件會自行拉起 ssh -N -L 並在斷開時自動重連，無需再手開 ssh -L。

接單¶

收到 assign 後，在幀裏指定的目錄創建或複用會話 job-<assignmentId>，把渲染好的任務文本作爲用戶消息投入；requestId 保證冪等，重投不會產生 duplicate 消息。會話會掛上 foreman_report 工具，供模型回報進度。主 loop 在收到 accepted 後才把 assignment 記爲 started。

接單時會話權限爲 workspace-write（不是主 loop 常用的 danger-full-access）：無人值守機器上彈審批容易卡死；需要越界時設備側不報彈窗，而是通過 blocked 由人決定放寬 root 或換設備。

回報¶

在 job 會話上註冊的 foreman_report 支持 progress、ready、blocked、failed 及可選提問，轉成 report 幀發回主 loop。協議約定 report 的 state 不含 dropped——那是主 loop 的判斷，設備沒有判斷權。

協議要點¶

幀定義在倉庫 src/protocol.ts，README 稱該文件爲協議唯一權威；主 loop 包 dsh-foreman 從 dsh-foreman-node/protocol 導入，避免兩側漂移。約定包括：一條 WebSocket 文本消息一個 JSON 幀，v 爲協議版本並在握手時校驗；單幀上限 256 KiB；帶副作用的幀帶 frameId 供去重。

安裝與啓用¶

DSH 生態裏插件常以 profile 的 cordis.patch.yml 聲明。README 給出的裝法如下：在本機 profile 中加入插件條目並填好連接與項目路徑，然後重啓本機 DSH。主 loop 無需因設備表變更而重啓（設備表在主 loop 數據庫，不在其插件配置裏）。

# 本機 profile 的 cordis.patch.yml
- id: dsh-foreman-node
  config:
    url: wss://foreman.example.com     # 主 loop 的穩定域名（隧道後面）
    deviceId: laptop                   # 主 loop 上 scripts/add-device.mjs 登記的那個 id
    token: <登記時打印的那一枚>
    roots:
      - project: shop
        path: 'D:\工作\shop'            # 本機自己的絕對路徑，原樣寫

裝進 profile 後，設置裏會出現「設置 › 設備連接」：可從本機 ~/.ssh 選密鑰、填樞紐主機與用戶、點「測試連接」，再把樞紐登記設備時給出的 deviceId、token 與項目名到本機路徑的映射填齊。插件詳情頁不再單獨提供配置入口。

也可直接編輯 cordis.patch.yml 寫全量配置，例如開啓 SSH 隧道：

- id: dsh-foreman-node
  config:
    url: wss://foreman.example.com   # 隧道開着時不參與連接
    deviceId: laptop
    token: <樞紐登記設備時給出的令牌>
    roots:
      - project: shop
        path: 'D:\工作\shop'
    ssh:
      enabled: true
      host: 203.0.113.10
      port: 22
      user: ubuntu
      keyPath: /home/me/.ssh/id_ed25519

「默認對話策略」爲下拉框，選項來自本機權限服務 permissionPresets.catalog()，不要手填名字；未知預設名保存後頁面會標出，任務下發時可能退回 workspace-write 並僅警告。

SSH 限制：不支持密碼登錄（自動重連依賴 BatchMode=yes），也不支持帶口令的私鑰，請把密鑰放進 ssh-agent。

運行環境：package.json 要求 Node ^22.19.0 || >=24.0.0，DSH 引擎 ^0.2.1-alpha.2。

典型用法：從配置到接單¶

1. 在主 loop 側用 scripts/add-device.mjs 登記設備，記下 deviceId 與 token。
2. 在本機 profile 寫入上述 cordis.patch.yml（或用設置頁等價配置），roots 裏 project 與主 loop 任務裏用到的項目名一致，path 爲本機絕對路徑。
3. 重啓本機 DSH，確認 wss（或 SSH 隧道）連通。
4. 主 loop 下發 assign 後，側欄出現 job-<assignmentId>；在會話內照常使用 DSH，模型通過 foreman_report 更新狀態。
5. 遇到權限邊界，用 blocked 回報，由人在主 loop 或策略側處理，而不是在本機強行開全權限。

適用場景與注意¶

適合誰：已有或計劃部署 dsh-foreman 主 loop，希望多臺機器以「出站連接 + 本地 workspace-write 會話」方式接任務、回傳進度的團隊或個人。

設計邊界：設備側故意不承載賬本與策略，避免把領域內核鋪到每檯筆記本；架構思想 README 歸因於 DeepSeek Harness 團隊《Super-agent 設計探索》中的「計算與執行環境分離」，實現參考了 dsh-superagent-local 與 dsh-superagent-prototype（均爲 MIT）。

安全與信任：插件在本機 DSH 進程權限下運行，安裝與啓用前應閱讀倉庫源碼與 MIT 許可證，確認 token、SSH 密鑰與 roots 路徑符合你的安全策略。社區目錄 SkillHub 插件頁 與 GitHub 爲獨立信息來源，與 DeepSeek / 幻方無官方從屬關係。

結尾¶

dsh-foreman-node 把「連出去、接單、回報」收攏成設備側最小閉環，與主 loop 的 dsh-foreman 分工明確。若要查配置字段與協議細節，以倉庫 README 與 src/protocol.ts 爲準。

• 目錄頁：https://www.skillhub.cn/plugins/niechao136/dsh-foreman-node
• GitHub：https://github.com/niechao136/dsh-foreman-node