前言¶

在 DeepSeek Harness（dsh）裏跑協調型智能體時，常見做法是：當前回合把任務交給外部沙箱、遠程主機、容器或長時間腳本，等對方做完再回來繼續。協調端既不能一直佔着 WebSocket，也不適合靠輪詢猜結果。若缺少一條「對方完成後主動通知本會話」的通道，智能體要麼假睡要麼反覆查狀態，體驗和可靠性都差一截。

dsh-tmp-hook 面向這類異步完成場景：由會話內的智能體調用工具拿到單次有效、帶 TTL 的 HTTPS 回調地址，外部 worker 用 POST 把結果送回來一次，載荷會作爲用戶消息寫入原會話並喚醒智能體；同一 URL 第二次 POST 會返回 410。下面介紹插件定位、安裝配置與 HTTP 約定。

這是什麼¶

• 名稱：dsh-tmp-hook（npm 包名與倉庫名一致）
• 維護者：Arcadia822（GitHub：Arcadia822/dsh-tmp-hook）
• 分類：聯網工具（社區目錄 SkillHub 歸類）
• 版本（package.json）：0.1.0，許可證 MIT
• 一句話：爲 dsh 會話提供一次性臨時 webhook——mint 單次回調 URL，外部 POST 載荷後喚醒發起請求的那條 agent 會話。

協調端與 worker 的大致關係如下（與 README 示意一致）：

coordinator ──request_tmp_hook──▶ https://dsh.example.com/api/tmp-hooks/<token>
    │
    │  （把 URL 交給沙箱 / 遠程 worker）
    ▼
worker ──POST 結果 JSON──▶ dsh-tmp-hook ──sessionController.prompt()──▶ coordinator 被喚醒

核心功能¶

智能體工具 request_tmp_hook¶

模型側說明何時使用：在把活交給「當前回合之後纔會結束」、且無法在本回合內 await 的對象之前——例如沙箱 worker、容器、AgentOS 任務、CI、長腳本、派發的子智能體，或人在環外回覆。不適用：本回合內就能完成的工作、本來就要輪詢的結果、或 worker 已有專用通道的情況。

可選參數：

• purpose：簡短說明在等什麼；回調消息裏會回顯，便於同一會話等多路回調時區分。
• ttl_seconds：存活時間，會被限制在配置的 [minTtlSeconds, maxTtlSeconds] 內。

返回字段包括 url、token、session_id、expires_at、expires_in_seconds。交給外部 worker 的應主要是 url。

HTTP 回調¶

• 地址：POST <baseUrl><pathPrefix>/<token>，body 可選，類型不限。
• 成功投遞：200，{"received":true}。響應只表示已進入會話收件箱，不表示模型已跑完一輪。
• 未知 token：404；TTL 過期或已用過：410；非 POST：405；body 超過 maxBodyBytes（默認 262144）：413；讀 body 失敗：400；寫入會話失敗：502。
• 在消息尚未成功寫入會話前的失敗（如 400、413、502）會釋放 token， oversized 或瞬時主機錯誤不會白白燒掉唯一一次通知；只有投遞成功才消耗 token。

載荷展示規則：空 body 顯示 (empty)；合法 JSON pretty-print（裸 JSON 字符串如 "done" 則顯示爲 done）；其它原樣；Content-Type 會寫在消息裏。展示上限約 64 KiB，避免撐爆上下文。

認證與能力 URL¶

回調 URL 本身是能力：token 爲隨機 UUID，worker 只需知道 URL。默認 allowUnauthenticated: true 時，若安裝了 dsh-auth-gate，插件會在 gate 上爲自家路徑前綴放行，其餘仍走原 gate；未裝 auth 插件則不做這層組合。設爲 false 則整站仍在 auth 之後，回調前綴需單獨 ingress（如 nginx location 指到 dsh 端口）。

安裝與啓用¶

DSH 生態裏插件通過 profile 與 bundle 註冊；本包聲明瞭 dsh.bundle.patch，dsh plugin add 會協調 dsh.profile.bundles。

在 web profile 下從 registry 安裝（README 原文命令）：

dsh plugin --profile web add dsh-tmp-hook

本地 checkout 試用（不經過 registry）：

dsh plugin --profile web add /path/to/dsh-tmp-hook

配置寫在 profile 自己的 patch 層（$DSH_HOME/profiles/<name>/cordis.patch.yml），在 bundle 層之後生效。示例：

- id: tmp-hook
  config:
    baseUrl: https://dsh.example.com   # 可選：覆蓋自動推導的對外 origin

baseUrl 是外部 worker 實際訪問的公網 origin。多數情況下可不寫：控制台若已在反向代理後用 --trusted-host <domain> 聲明公網域名，插件會從同一聲明推導 origin。僅在僅綁定 IP/迴環、或需覆蓋 scheme 時再顯式設置。既無 baseUrl 也無法推導時，request_tmp_hook 會明確失敗，而不是給出不可達的 URL。

配置項（節選）¶

未知鍵或非法值在加載時拒絕，壞配置會導致啓動失敗而非第一次回調才報錯。

運行環境（package.json）：Node ^22.19.0 || >=24.0.0，peer 依賴 @deepseek-ai/cordis ^4.0.1。

典型用法¶

1. 協調智能體在派活前調用 request_tmp_hook，填寫 purpose（必要時調整 ttl_seconds）。
2. 把返回的 url 寫進給 worker 的任務說明（不要把 token 等額外字段當必需依賴）。
3. worker 完成後對 url 發一次 POST，body 可以是 JSON、純文本或構建日誌等。
4. 會話收到形如下面的用戶消息，智能體繼續處理：

[dsh-tmp-hook] One-time callback received at 2026-09-18T11:02:21.513Z.
Token: 523a6527-77f0-44c2-b2fc-db7b9cf36a6a
Purpose: e2e-verify
Content-Type: application/json

Payload:
{
  "status": "done",
  "spec_url": "https://taco.example/spec/42"
}

5. 若 worker 誤 POST 兩次，第二次得到 410（token already used）。

適用場景與注意¶

適合：需要在 dsh 裏編排「外部異步完成 → 單次喚醒原會話」的開發者；與沙箱、遠程執行、CI、長任務、人在環外回覆等組合。

注意：

• 插件在當前 dsh 進程權限下運行；安裝前請自行查看 GitHub 源碼 與 MIT 許可證，確認符合你的部署與合規要求。
• 回調 URL 即憑證，應通過任務通道交給可信 worker；TTL 與 body 上限按配置約束。
• 公網可達性依賴你的 baseUrl / --trusted-host / 反向代理與 TLS；README 指出限流、TLS、DNS、代理等屬於部署側職責（文檔在抓取處截斷，細節以倉庫 README 爲準）。
• 社區目錄 SkillHub 插件頁 與 GitHub 由社區維護，與 DeepSeek / 幻方無官方從屬關係。

結尾¶

dsh-tmp-hook 用「一次性 HTTPS webhook + 會話內用戶消息」補上協調智能體與外部 worker 之間的完成通知，避免常駐連接或盲目輪詢。安裝使用 dsh plugin --profile web add dsh-tmp-hook，在 profile 的 cordis.patch.yml 裏按需配置 tmp-hook。

• 目錄頁：https://www.skillhub.cn/plugins/Arcadia822/dsh-tmp-hook
• 倉庫：https://github.com/Arcadia822/dsh-tmp-hook