前言¶
在 DeepSeek Harness（DSH）裏跑智能體，常見做法是本機一個實例：工單、策略、評估和會話都在同一進程裏。當你有多臺機器——公司筆記本、宿舍電腦、一臺常駐服務器——希望「在一個地方說話、在對應機器的工作區裏幹活」，而又不想在每臺設備上各維護一套賬本，就會遇到路由與狀態一致性的問題。
下面介紹社區插件 dsh-foreman（維護者 niechao136）。它在服務器側保留唯一賬本（Engine、SQLite、Policy、Tickets、Evals、設備表），通過 Hub 與 Selector 把工單派到遠端設備上完整運行的 DSH；設備側用配套的 dsh-foreman-node 只接單、本地執行並回報，不建工單、不持策略、不打開數據庫。項目標註爲早期開發中，MIT 許可；不是 DeepSeek 官方產品。
這是什麼¶
一句話定位（摘自項目 README）：一個常駐的主 loop，把工單派給多臺在線設備上各自完整運行的 DSH，賬本只有一份。
架構上，服務器跑 dsh-foreman，每臺個人機器裝 dsh-foreman-node；設備通過 wss 主動連 Hub。本機也可 target.kind === 'local'，行爲與不接設備時相同。
當前 package 版本爲 0.5.1（以倉庫 package.json 爲準）。運行時要求 Node ^22.19.0 || >=24.0.0，DSH ^0.2.1-alpha.2。
核心功能¶
單賬本與雙層角色¶
服務器側集中持有工單、策略與評估；每個項目一條主會話入口，操作者在此對話，主會話負責路由，Worker 在具體工作區目錄執行。設備側插件不承擔賬本職責。
Selector 與派單時機¶
accept 工單時，prepareTicket 即選定設備並寫入 Ticket.target，再由 newAssignment 複製到 Assignment.target——不是 Executor 選型（Executor 沒有寫庫通道）。
- 遠端目標：以
assign幀發給對應設備；設備不在線則報blocked，不僞造 failed，也不悄悄改成本機跑。 - 本地目標：交給本機
DshExecutor。
斷線不會自動重派（避免同活執行兩遍）；超時轉爲 blocked，由人處理。
已落地的模塊（項目自述）¶
README 寫明：設備註冊表、Selector、ForemanExecutor、Hub、回報規則、設備側插件、文本渲染、遷移腳本、面板設備頁、飛書羣路由等已實現，測試 1332 項。設計、實現計劃與交接見倉庫內 docs/superpowers/ 與 HANDOFF.md。
與上游的關係¶
代碼以 dsh-superagent-local 爲起點，思想來自 DeepSeek Harness 團隊的 Super-agent 原型與研究文檔；本項目在多設備與遷移方向上做重寫與擴展，並對文中未解問題（如 A2A、安全）採用明確取捨，而非聲稱已全部解決。
安裝與啓用¶
dsh-foreman 在 npm 上以包名 dsh-foreman 發佈，並在 package.json 中聲明 dsh.bundle（profile bundle）。安裝前請確認本機 pnpm 在 PATH 中；社區插件以當前 DSH 進程權限運行，安裝前建議自行審閱源碼與許可證。
裝入 web profile（常見本機 / 面板場景）¶
生態目錄 dsh.works 給出的安裝方式爲：
dsh plugin --profile web add dsh-foreman
安裝或更新 bundle 後需重啓對應 profile 的 DSH Web。可用下列命令確認 bundle 層已生效（以你實際使用的 profile 名爲準）：
dsh --profile web --dump-config
輸出中應能看到 dsh-foreman 相關 bundle 層。
獨立主 loop 實例（服務器部署示例）¶
若要把主 loop 與原有 DSH 實例隔離（獨立 DSH_HOME、profile、端口），倉庫 runbook docs/deploy-loop-instance.md 建議在主 loop 所在 profile安裝 foreman，不要在同一實例混裝 node 包。示例：
export DSH_HOME=/home/ubuntu/.dsh-loop
dsh --profile loop --dump-config > /dev/null
dsh plugin --profile loop add "github:niechao136/dsh-foreman"
驗收時，--dump-config 裏應只有 dsh-foreman，不應出現 dsh-foreman-node：
dsh --profile loop --dump-config | grep foreman
設備側¶
被派活的筆記本、宿舍電腦等應安裝 dsh-foreman-node（npm 包名 dsh-foreman-node）。設備側安裝命令見 dsh-foreman-node 目錄條目（示例：dsh plugin --profile web add dsh-foreman-node）。服務器主 loop 實例上只裝 foreman，不裝 node。
與本插件相關的配置項（獨立實例 runbook）¶
將 examples/profile.cordis.patch.yml 複製到目標 profile 的 cordis.patch.yml 後，runbook 中與 foreman 直接相關的鍵包括：
- id: dsh-foreman
config:
stateDir: /home/ubuntu/.dsh-loop/state/superagent
hubPort: 8790 # 設備連入的環回端口；0 表示不開 Hub，工單僅本機
hubIdleMs: 600000 # 設備無心跳多久視爲 blocked
hubPort 默認只監聽 127.0.0.1；對外常配合隧道（如 cloudflared）使用穩定域名。遷機與更多部署細節見 docs/migration.md。
典型用法¶
1. 在主 loop 登記設備¶
runbook 推薦在 Web 面板「設置 › 設備」中登記 id、顯示名、可接項目及該機器上的路徑，獲取 url、deviceId、token（令牌僅展示一次）。
headless 環境可用倉庫腳本（路徑以 runbook 爲準）：
cd /path/to/dsh-foreman
export DSH_HOME=/home/ubuntu/.dsh-loop
node scripts/add-device.mjs add --home "$DSH_HOME" --id laptop --name 公司筆記本 --label intranet --root shop='D:\工作\shop'
2. 在設備上配置 node 並連通 Hub¶
在設備 DSH 的「設置 › 插件 › dsh-foreman-node」中配置 SSH 隧道或 wss:// 樞紐地址，填入主 loop 下發的 deviceId 與 token，映射項目路徑後保存並重啓設備側 DSH。主 loop 側無需因登記而重啓。
3. 接受工單時的行爲預期¶
工單 accept 後，若目標設備離線或超時，狀態爲 blocked，不會自動改派或靜默回落本機。確認設備未在執行後，再由人工重試。
4. 飛書羣路由（可選）¶
整臺服務器可配置一個飛書機器人，用羣區分項目；Policy 中 routing.chats 可同時約束工作區與設備 labels，Selector 只選帶匹配標籤的設備，選不到則 blocked。示例結構見 runbook 中的 JSON 片段。
適用場景與注意¶
適合誰： 需要在多臺機器上保留各自工作區與執行環境，又希望工單、策略、評估與主會話入口集中在一臺（或一組）主 loop 上的 DSH 用戶；需求主要來自本機操作者主會話，而非僅 GitHub/飛書觸發（雖也支持飛書羣路由等能力）。
注意事項：
- 項目處於早期開發，API 與部署方式可能變動；重大部署前閱讀
HANDOFF.md與設計文檔。 - 同一 DSH 實例不宜同時裝 foreman 與 foreman-node 作爲主 loop 驗收標準所描述的那樣混用；多實例應使用不同
DSH_HOME。 - 插件與 node 均爲第三方代碼，安裝即在本機執行；請覈對 MIT 許可與倉庫源碼。
- SkillHub、dsh.works 等目錄爲社區站點，與 DeepSeek / 幻方無官方從屬關係；星標在目錄快照中可能爲 0，不代表質量結論。
結尾¶
dsh-foreman 把「一個主 loop、一份賬本、多臺 Worker」落到可部署的 bundle：派單在 accept 時寫入 target，遠端不在線則明確 blocked，斷線不重派。若你要從單機構型擴展到多設備協同，可從 npm 或 GitHub 安裝 foreman，再按 runbook 配 Hub 與設備表。
