前言¶

在 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