前言¶
DeepSeek Harness（DSH）提供多種運行 profile，其中只有 web 能在進程不退出的前提下長期承載會話。dsh web 自帶的 /api 面向瀏覽器：需要啓動 token、簽名 cookie，以及 Host/Origin 信任邊界，從 shell 或遠端腳本直接調用並不順手。
DSH bundle 插件可以通過 ctx.webServer 註冊一等 HTTP 路由，這些路由落在上面的瀏覽器圍欄之外。dsh-ctl 利用這一機制，在環回地址上暴露一套小型的 JSON API；再配合 SSH，可以在不向外網暴露端口的情況下，遠程列出、創建、注入 prompt、跟蹤輸出並取消會話。
下面介紹該插件的定位、能力、安裝方式與典型用法。
這是什麼¶
dsh-ctl 是維護者 StarChen-Cycler 發佈的 DSH 工作流類插件（社區目錄分類：工作流）。它爲長期運行的 DeepSeek Harness dsh web 進程提供 Loopback HTTP control plane：在本地 HTTP 服務上掛載 /ctl/* 接口，並用倉庫內 scripts/ 下的 ctl 輔助腳本包裝 curl，使具備 SSH 權限的機器用 ssh <host> ctl ... 即可完成運維式操控。
插件當前版本爲 0.1.4（MIT 許可證），與資料中聲明的 DSH 0.1.5-rc.2 做過驗證。
核心功能¶
資料中可覈實的操作麪包括：
- 健康與索引：
GET /ctl/health查看版本、端口、pid、平臺、Node、運行時長等；GET /ctl爲路由索引。 - 會話生命週期：列出會話（可按
running=1篩出正在執行的）、創建會話（可指定cwd、預設權限等）、單會話查詢、重命名、取消當前 turn。 - 驅動與觀測：向會話注入 prompt（
queue等待當前 turn 結束再投遞，steer切入當前 turn）；tail讀取歷史快照與實時幀；inspect讀持久化狀態且不喚醒 agent；control查看 live 隊列與運行統計。 - 擴展能力：會話綁定 schedule（cron、daily、weekly 等）；
hypo-checkpoint與dsh-hypo-before-compact相關的 memory checkpoint 開關；presets查詢 profile 暴露的權限預設；調試用的debug/shape只讀 schema 內省。
GET /ctl/sessions?running=1 反映進程內 live 狀態而非磁盤歸檔，資料稱在 prompt 後約 300 ms 內 running 會變爲 true，turn 結束後回到 false。判斷會話是否在跑應依賴 running 等 live 信號，不宜僅憑 lastUserInputAt 時間戳推斷。
環境與依賴¶
- DSH
0.1.5-rc.2或更新（dsh --version自檢）。 - 使用基於
@deepseek-ai/dsh-web-app的 profile（官方web模板或派生模板）。 - Node.js 18+（DSH 自帶運行時，一般無需系統 Node）。
安裝與啓用¶
先基於默認 web 模板創建專用 profile，再以 link 方式安裝插件（安裝命令須與 README 一致，勿憑倉庫名臆造 github: 寫法）：
# 從官方 web 模板創建 profile
dsh --profile fleet --from-default-profile web
# 安裝插件（路徑、tarball 或發佈後的 npm 均可）
dsh plugin --profile fleet add link:/absolute/path/to/dsh-ctl
dsh plugin 會在 profile 目錄內轉發給 pnpm 並記錄 bundle，無需手改 package.json。安裝完成後 profile 的 bundles 中會包含 dsh-base、dsh-web-app、dsh-ctl。
啓動常駐服務時關閉自動打開瀏覽器，端口可自行選擇，綁定地址保持默認環回：
dsh --profile fleet --port 17390 --no-open
長期運行可交給本機服務管理器（Linux 上可用 systemd，macOS 可用 launchd 等）。README 給出了 macOS LaunchAgents 的 ProgramArguments 示例，核心即爲上述 dsh --profile fleet --port 17390 --no-open。
典型用法¶
凡能 SSH 到宿主機的機器均可執行下列命令，無需端口轉發或額外 tunnel（README 原文表述）。
# 健康檢查
ssh <host> ctl health
# 會話列表，最新在前
ssh <host> ctl sessions --limit 20
# 僅當前正在執行的會話
ssh <host> ctl sessions --running
# 在指定工作區創建會話
ssh <host> ctl create --cwd /srv/work
# 注入任務
ssh <host> ctl prompt <session-id> "summarise the failing tests"
# 讀取輸出（歷史快照 + 最長 N 秒 live 幀）
ssh <host> ctl tail <session-id>
# 停止當前 turn
ssh <host> ctl cancel <session-id>
對已在跑的會話，可先 ctl control 看隊列，用 ctl inspect 讀持久化狀態；注入時選用 --mode queue（進入下一輪）或 --mode steer（切入當前輪）。兩種模式在送達前都會先返回，在 control 裏觀察隊列，而不是在落地前指望 tail。
可將 scripts/ 中的 ctl 拷到目標主機，或在本地用 --host 指定遠程。
更完整的請求/響應形狀見倉庫 docs/API.md。
適用場景與注意¶
適合誰：需要在單機或內網保留一個 dsh web 進程，又從 CI、跳板機或其它節點用 SSH 編排 agent 會話的團隊；希望避免把 DSH Web UI 的 cookie/token 流程硬塞進 shell 腳本的場景。
權限與安全：插件路由掛在同一 dsh web 進程上，以該進程的權限訪問工作區與工具能力。安裝前應閱讀源碼與 MIT 許可證，確認 link: 路徑可信；控制面默認在 loopback，對外暴露仍取決於你如何部署 SSH 與主機加固。
生態說明：DSH 強調「一切皆插件」；SkillHub 等社區目錄爲獨立站點，與 DeepSeek / 幻方並無官方從屬關係，本文不以「官方應用商店」口吻描述。
結尾¶
dsh-ctl 把常駐 dsh web 翻譯成一套可通過 SSH 調用的環回 JSON API，補上「只有 web profile 能保活會話、但瀏覽器 API 難腳本化」之間的縫隙。
- 社區目錄頁：https://www.skillhub.cn/plugins/StarChen-Cycler/dsh-ctl
- 源碼與 README：https://github.com/StarChen-Cycler/dsh-ctl
