ben7am1n/dsh-webhook-bridge

dsh-webhook-bridge

DeepSeek Harness 的通用 webhook 接收器 —— 向本地端点发送 POST 请求即可唤醒 dsh agent。CI、监控或任何具备 HTTP 能力的服务都可以通过纯 HTTP 向 harness agent 投递消息。除官方 schema 库外零运行时依赖（仅使用 node:http）。

概述

dsh-webhook-bridge 暴露一个小型本地 HTTP 服务器。每次向 POST /hook/:channel 发起请求都会向该 channel 的 agent 会话投递一条消息；已提交的 assistant 文本可以流式回传到可选的回调 URL。它是 dsh 扩展模型中的协议驱动——与官方 ACP/JSON-RPC 桥接扮演相同角色，但适用于任何能发送 HTTP 的系统。

它适合谁？

- 希望让 agent 分诊构建失败的 CI 流水线。
- 希望让 agent 调查事件的监控/告警系统。
- 需要将 payload 交给 harness agent 的 IM 机器人和 webhook（GitHub、GitLab、通用服务）。
- 想要一份可读的参考实现来编写基于 HTTP 的协议驱动插件的开发者。

它能做什么

- 提供 POST /hook/:channel（Bearer 密钥认证）和 GET /health。
- 将一个 channel 映射到一个 agent 会话；第一条消息创建 agent，后续消息通过 followup() 进入同一会话。
- 按文档化的优先级提取消息文本：JSON message > text > content；非 JSON 请求体按原样使用。
- 请求体中可选的 reply_url：已提交的 assistant 文本会以 {"text": "..."} 的形式 POST 回去。
- 拒绝未授权、格式错误和过大的请求（401/400/413）。

它（目前）不做什么

- 没有 TLS（在反向代理处终止 TLS；端点默认绑定回环地址）。
- 除共享 Bearer 密钥外，没有 webhook 签名验证。
- channel→session 映射不跨重启持久化（内存中；见兼容性）。

兼容性

- 需要 Node.js ≥ 22.19（全局 fetch、node:http）。
- 基于 @deepseek-ai/dsh@0.1.0-rc.6 / @deepseek-ai/cordis@^4.0.1 构建并验证。
- 最后验证： 2026-08-14。
- channel→session 映射保存在内存中：重启 dsh 会丢失已打开的会话（新请求会重新创建它们）。
- dsh 处于开发者预览阶段；harness 更新后请重新验证。

安装 / 卸载

安装到 dsh profile（本地检出）：

cd /path/to/deepseek-harness
pnpm dsh plugin --profile web add /path/to/dsh-webhook-bridge

从 GitHub 安装（源码安装——pnpm 会运行 prepare 脚本，因此需要允许一次）：

pnpm dsh plugin --profile web add github:/dsh-webhook-bridge
pnpm ≥10 会在首次安装时阻止构建脚本；将打印出的 package key
复制到 /pnpm-workspace.yaml 的 allowBuilds 下，然后重新运行。

卸载：

pnpm dsh plugin --profile web remove dsh-webhook-bridge

快速开始

1. 选择一个共享密钥（例如 openssl rand -hex 24），并在 profile 的 cordis.patch.yml 中设置它（或导出 DSH_WEBHOOK_SECRET）：

- id: dsh-webhook-bridge
name: dsh-webhook-bridgeyaml
config:
secret: 'your-shared-secret'

2. 启动 dsh，然后投递一条消息：

sh
curl -X POST http://127.0.0.1:8788/hook/ci \
-H "Authorization: Bearer your-shared-secret" \
-H "Content-Type: application/json" \
-d '{"message": "CI failed on main: run the release pipeline diagnosis"}'

3. 若要接收 agent 的回复：

sh
curl -X POST http://127.0.0.1:8788/hook/incident \
-H "Authorization: Bearer your-shared-secret" \
-d '{"message": "Investigate the 5xx spike", "reply_url": "https://your-service.example/hook/agent-reply"}'

配置

所有键都位于 dsh-webhook-bridge 行的 config 下：

| 键 | 类型 | 默认值 | 含义 |
|---|---|---|---|
| host | string | 127.0.0.1 | 绑定主机。默认仅限回环地址；仅在防火墙/代理之后才绑定 0.0.0.0。 |
| port | number | 8788 | 绑定端口。 |
| secret | string | 环境变量 DSH_WEBHOOK_SECRET | 在 Authorization: Bearer  中为必填。为空 = 拒绝所有请求。 |
| provider | string | — | 所创建 agent 的 provider 路由（回退到 profile 默认值）。 |
| model | string | — | 所创建 agent 的模型（回退到 profile 默认值）。 |
| cwd | string | process.cwd() | 所创建 agent 会话的工作目录。 |
| maxBodyBytes | number | 1048576 | 请求体大小限制；更大的请求体会返回 413。 |

权限与数据

- 网络暴露： 服务器默认绑定 127.0.0.1。如果你绑定到外部地址，请将其置于带 TLS 的反向代理之后；共享密钥是唯一的关卡。
- 认证： 常量时间比较（timingSafeEqual）；未认证的请求会返回 401，且绝不会创建 agent 会话。
- 回复回调： 仅回调到请求体中显式提供的 reply_url，且限制为 http:/https:。
- 文件系统： 该插件不写入任何内容；agent 会话继承 harness 工作区策略。
- 密钥： 切勿将密钥提交到仓库；请使用随附补丁中的环境变量形式。

故障排查

| 症状 | 原因 | 修复方法 |
|---|---|---|
| 每个请求都返回 401 | Authorization 头错误/缺失，或 secret 为空 | 检查 config.secret 和请求头拼写（必须带 Bearer  前缀） |
| 413 payload_too_large | 请求体超过 maxBodyBytes | 调高 maxBodyBytes 或发送更小的负载 |
| 400 empty_message | 没有 message/text/content 字段，且原始请求体为空 | 包含其中一个可识别的字段 |
| 404 not_found | 路径或方法错误 | 使用 POST /hook/；/health 仅支持 GET |
| 回复未到达 | 该 channel 未提供 reply_url | 包含 reply_url；该插件仅在设置了它时才会回调 |
| agent 错误出现在日志中 | harness 中的模型/provider 故障 | 修复 agent 组合；该插件会将请求转发为 500 |

开发
sh
pnpm install
pnpm run typecheck     # tsc --noEmit
pnpm run build         # tsc → lib/
pnpm run test          # vitest：HTTP 行为 200/401/400/413 + 提取辅助函数

结构：

- src/index.ts — 插件入口（name/inject/Config/apply）、会话映射，以及 createBridge（纯 HTTP 传输，可注入消息处理器）。
- tests/ — 集成测试会在临时端口上启动真实服务器，并在不启动完整测试框架的情况下断言 HTTP 契约。

设计说明：

- createBridge(config, deps) 将传输与 agent 逻辑分离：HTTP 层完全可进行单元测试，而 apply 提供 handleMessage 回调，用于创建会话并转发消息。
- 零运行时依赖是一个目标——node:http 和 node:crypto 已覆盖此处所需的一切。

许可证与安全

MIT。请通过仓库的安全公告私下报告安全问题。该桥接本身不执行任何 agent 代码；所有 agent 行为均受测试框架自身的权限和沙箱策略约束。