前言¶

在 DSH（DeepSeek Harness）里跑智能体时，外部系统——CI、Issue 跟踪、监控告警——往往希望「推一条 HTTP 请求就能触发一次会话」，而不是为每个服务单独写桥接代码。常见做法是自建小服务转发到本地 API，或手工复制粘贴 payload，运维和权限边界都容易变复杂。

下面介绍社区插件 dsh-webhook-dispatcher（维护者 xuan25，分类：联网工具）：它在 profile 的 webServer 上注册精确路由，外部调用到达端点后，由插件Admission 并 spawn 一次全新的、隔离的 agent 会话 处理投递内容。目录页：skillhub.cn/plugins/xuan25/dsh-webhook-dispatcher；源码与说明：github.com/xuan25/dsh-webhook-dispatcher。SkillHub 为独立社区目录，与 DeepSeek / 幻方无官方从属关系。

这是什么¶

dsh-webhook-dispatcher 是 DSH 的 out-of-tree 插件（package 版本 0.1.0，许可证 MIT）。一句话定位：为 dsh 部署提供 inbound webhook dispatch——HTTP 调用方命中插件配置的 endpoint 后，由框架拉起新的 agent session 处理 body 中的内容；CI、Issue 系统、监控工具等可直接驱动 DSH 会话，无需按服务写专用桥接。

Endpoint 挂在 profile webServer 服务的 精确路径 上（web profile 由 Web GUI 提供；其他 profile 需自行 compose @deepseek-ai/dsh-host-webserver，见后文）。对外是否可达由操作者的反向代理决定。

核心功能¶

端点与准入¶

每个 endpoint 可单独配置：id / path / name、token 鉴权（通过环境变量名引用 token 值）、policy 文本、工作目录 cwd、sandbox、model、reasoning effort、以及 maxConcurrent / maxQueue / maxBodyBytes 等资源与队列限制。

每次被接纳的投递都会 spawn 新的 agent session；超过并发或队列容量时返回 429，并带 Retry-After 做背压。

配置方式¶

插件 不创建配置文件；endpoint 通过两条等价通道声明，字段合并到同一契约，优先级为：cordis config layer > 环境变量 > 内置默认。

1. cordis：在 profile 的 cordis.patch.yml 中 targeting 插件 id dsh-webhook-dispatcher（热更新：patch 变更会重建插件条目并重读两路配置）。
2. 环境变量：WEBHOOK_<ENDPOINT_ID>_<FIELD> 形式（id 转大写、连字符变下划线，例如 ci-run → WEBHOOK_CI_RUN_*）。

缺少 PATH、越界值、或声明了 AUTH 但对应 token 环境变量未设置时，插件在 启动阶段 fail-closed 失败；未知 config key 会被拒绝（防拼写错误）；path 不得与框架自有路由冲突。

观测：webhook status¶

Agent 侧可用工具 webhook { verb: "status" } 查看 live 路由、队列深度、近期投递历史，以及生效的（非密钥）endpoint 配置。完整参考见插件 bundled 的 dsh-webhook-dispatcher skill。

Session offload¶

Webhook 触发会在框架 session store 留下磁盘日志；高频 endpoint 下 store 可能无限增长。插件按 每分钟 扫描：对已 settled、且超过该 endpoint sessionRetention 窗口的 trigger session 做归档，使 store 有界（只移动、不删 store；仍在运行的 session 等到 settled 再处理）。offload 相关状态位于 $DSH_HOME/dsh-webhook-dispatcher/（含 retention-log.jsonl、archived-sessions/ 等）。可选 env WEBHOOK_OFFLOAD_BATCH（默认 50）限制单次 sweep 处理量。

安装与启用¶

在目标 profile 上安装（命令来自官方 README）：

dsh plugin --profile <name> add dsh-webhook-dispatcher

安装后通过 WEBHOOK_* 环境块 和/或 cordis config layer 配置 endpoints。

非 web profile：挂载 webServer¶

Endpoint 注册在 profile 的 webServer 上。web profile 自带 Web GUI 的 webServer；sdk、acp 或自定义 bundle 需在 composition 中插入 webServer 提供方。headless 等一次性 surface 无法常驻监听，不能托管本插件。

示例（摘自 README，$DSH_HOME/profiles/<name>/cordis.patch.yml）：

- insert:
    - id: webserver
      name: '@deepseek-ai/dsh-host-webserver'
      config:
        host: <host>
        port: <port>  # 空闲固定端口；port 0 会在每次重启时重新解析绑定地址

典型用法：配置一个 endpoint¶

方式一：cordis config layer¶

- id: dsh-webhook-dispatcher
  config:
    endpoints:
      - id: <name>
        path: /<path>
        policy: "Treat the content as a task description and act on it."
        # name: <name>           (default: the id)
        # cwd: /abs/path         (default: $DSH_HOME/dsh-webhook-dispatcher)
        # auth: <TOKEN_ENV>           (env var NAME holding the token value; empty = open endpoint)
        # sandbox: workspace-write    (read-only | workspace-write | danger-full-access)
        # model: some/model           (default: the default selection ladder)
        # reasoningEffort: low        (closed set off|minimal|low|medium|high|xhigh|max)
        # maxConcurrent: 1            (default)
        # maxQueue: 100               (default)
        # maxBodyBytes: 262144        (default)
        # sessionRetention: 24h       (absent/0 = retain in the store)

方式二：环境变量¶

与上表字段对应，例如：

WEBHOOK_<NAME>_PATH=/<path>
WEBHOOK_<NAME>_POLICY="Treat the content as a task description and act on it."
WEBHOOK_<NAME>_AUTH=<TOKEN_ENV>   # 存放 token 值的环境变量「名称」
WEBHOOK_<NAME>_MODEL=some/model
WEBHOOK_<NAME>_REASONING_EFFORT=low
<TOKEN_ENV>=...

常用字段默认值（资料原文）：cwd 默认 $DSH_HOME/dsh-webhook-dispatcher；maxConcurrent 默认 1；maxQueue 默认 100；maxBodyBytes 默认 262144；auth 为空则 endpoint 开放；policy 为空则走 free-policy fallback。

外部系统对 https://<你的反向代理>/<path> 发起 HTTP 请求（需满足插件的 method gate、鉴权与 body 预算）；成功后即进入队列并由新 session 按 policy 处理 payload。

运行中可在会话里调用 webhook { verb: "status" } 核对路由与队列，而不必猜配置是否生效。

适用场景与注意¶

适合谁：已有 HTTP 出站能力的系统（CI、GitHub/GitLab webhook、监控、工单），希望 一条 webhook 对应一次 DSH 任务，且需要 per-endpoint 的模型、沙箱、并发与队列策略。

务必注意：

1. 插件以 当前 dsh 进程权限 运行；安装前请阅读 GitHub 源码 与 MIT 许可证，自行评估 token、开放 endpoint 与 sandbox 组合的风险。
2. 对外暴露 endpoint 前应配置 auth（AUTH 指向已设置的环境变量名）并限制 body 大小；开放 endpoint 仅适合受控网络。
3. 高频 webhook 建议设置 sessionRetention 并关注 offload 相关日志；无效 retention 会 warn 并按 0（不归档）处理，不会导致启动失败。
4. 需要常驻 HTTP 路由的 profile 必须提供 webServer；仅 headless 的一次性部署无法使用本插件。

结尾¶

dsh-webhook-dispatcher 把「外部 HTTP 事件 → 隔离 agent 会话」收成可声明的 endpoint 与统一背压，减少 per-service 桥接代码。安装命令为 dsh plugin --profile <name> add dsh-webhook-dispatcher；配置与行为以 README 为准。

• 目录页：https://www.skillhub.cn/plugins/xuan25/dsh-webhook-dispatcher
• GitHub：https://github.com/xuan25/dsh-webhook-dispatcher