webhook 配好了,PR 也标记为 ready for review,GitHub 投递记录显示 202,评审却没有出现。 这是最容易误判的一类问题:从「HTTP 成功」到「评审发生」还隔着好几道独立关卡,而文档中的 202 只表示第一道关卡已通过。
本文会逐段拆解整条链路:哪些事件会触发评审、需要安装什么、公网端点应暴露什么、202 到底表示什么、没有看到评审时应按什么顺序排查,以及哪些责任属于部署者、哪些事项文档并未承诺。
一、什么事件会触发评审 Session
官方 GitHub 评审指南介绍的是一个需要为 dsh web 显式启用的 overlay,并非默认常驻功能。示例规则要求以下四个条件同时成立:
来源 primary-github
仓库 deepseek-ai/deepseek-harness
事件 pull_request
动作 ready_for_review
匹配后,规则会在该仓库对应的 Web Workspace 下创建一个带标题的根 Session,并启动只读评审提示词。规则会将精确 head SHA 和选定的 PR 字段一并传给提示词,同时明确将这段 JSON 标记为不受信任的元数据。
几个容易忽略的边界:
- 这是一份具体示例,不会自动监听你的所有仓库。要用于其他仓库,必须主动修改规则。
- 示例禁止修改文件、分支、PR 和 GitHub 状态,并选用
standardagent preset 与read-onlypermission preset。 - webhook 密钥只验证入站数据,不会赋予 agent 任何出站 GitHub 权限。
二、需要安装和配置什么
需要准备三样东西:一个可注册为 Web Workspace 的本地 checkout、一个高熵 webhook 密钥,以及一个能将单个公共 URL 转发到 loopback 监听器的 TLS 反向代理或隧道。
在 GitHub 端订阅 Pull requests 事件,并将 content type 设为 application/json。示例默认使用启动目录和 127.0.0.1:3081,也可以通过 DSH_GITHUB_REVIEW_WORKSPACE 和 DSH_GITHUB_WEBHOOK_PORT 覆盖。
第 1 步:生成密钥
生成高熵密钥并妥善保存。通过 DSH_GITHUB_WEBHOOK_SECRET 在重启后继续使用同一个值。GitHub 端也填入同一个密钥,不要公开。
重启后密钥必须一致——两端使用不同的值,签名验证必然失败,日志表现也很像「规则没匹配」。
第 2 步:装两个实验包
在 Web profile 中安装两个实验包。注意,profile 不会自动安装 peer:
dsh plugin --profile web add @deepseek-ai/dsh-webhook @deepseek-ai/dsh-webhook-github
第 3 步:启动已发布的示例 overlay
将 DSH_GITHUB_REVIEW_WORKSPACE 设为目标 checkout,然后运行:
export DSH_GITHUB_REVIEW_WORKSPACE=/path/to/deepseek-harness
dsh web --patch "${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/@deepseek-ai/dsh-webhook-github/examples/github-review/cordis.yml"
第 4 步:通过 HTTPS 暴露专用监听器
GitHub 的 payload URL 指向公共的 /github 端点,并设置前文提到的 content type、密钥和事件订阅。
第 5 步:触发并分别检查
将 PR 从 draft 转为 ready for review,然后分别检查投递记录和 Web Workspace 中的 Session。
HTTP 成功本身不能证明规则匹配或评审执行。 这两件事要看两个不同的地方。
安装和提供 overlay 是两个步骤
这里需要单独说明:安装包和提供 overlay是两件事。CLI 不随附这些包,也不将它们列为官方插件。
适配器把示例放在 profile 的安装目录中,是为了让规则模块能解析该 profile 安装的 peer。要定制时,指南要求将两个示例文件复制到 profile 的 github-review 目录,修改配置,再让 --patch 指向副本——不要从 profile 外的任意目录运行规则。
三、公网端点应该暴露什么
主 Web UI 和 /api 仍在 3080 端口。overlay 会在隔离 realm 中挂载第二个 WebServer,只注册 POST /github,其他路径一律返回 404。
指南中的 Caddy 示例也只将 /github 转发到 127.0.0.1:3081,其他路径返回 404。
| 部件 | 作用 | 仍需单独考虑 |
|---|---|---|
| TLS 代理或隧道 | 让专用端点可达 | 入站签名验证 |
| Webhook 密钥 | 验证 GitHub 入站数据 | 出站 GitHub 权限 |
| 规则 | 筛选事件并构造评审请求 | 持久投递追踪 |
| Session | 在提示词接纳后拥有工作 | 每次投递是否匹配 |
代理限制暴露范围,但不能代替 webhook 签名验证。 两者是相互独立的两道防线,缺一不可。
公开部署指南还单独说明了浏览器 UI 的发布方式。暴露 webhook 监听器不意味着必须公开 UI——是否公开 UI 可以另行决定。
四、HTTP 202 到底表示什么
它不表示「评审完成了」。
指南定义的 202 表示:签名与 JSON 已被接受,规则调用已在内存中调度。它不表示规则匹配、Session 已创建或 agent 已完成评审。
因此,正确的核对方式是:将 payload 中的事件、动作、仓库与规则逐项比对,再检查 Workspace 和 Session 的实际结果。
runtime 不存储投递或执行状态,因此有三条后果:
- 重复投递会再次运行规则,可能创建另一个 Session。
- 崩溃会丢失尚未接纳提示词的规则调用。
- 提示词被接纳后,工作才由普通的 Session 日志、持久化、Workspace 和 agent 生命周期负责。
因此,不能把 HTTP 成功当作持久队列或去重保证。
第一次匹配的投递会通过 WorkspaceRegistry.create() 在 Workspace 不存在时创建它,后续投递则复用同一个。因此,本地路径必须指向预期的 checkout。有效签名只说明共享密钥下的入站数据通过了验证,并不能证明 checkout 内容正确,也不能证明评审达成了预期结果。
五、没看到评审时按什么顺序排查
沿着链路逐段检查,不要跳步:
- 确认 GitHub 确实将已订阅的事件投递到了预期的公共 URL。
- 确认配置的密钥与运行进程可访问的值一致。
- 检查专用代理的路由和 loopback 监听器是否正常。
- 将 payload 中的事件、动作、来源、仓库与示例规则逐项对照。
- 检查预期的本地 Workspace 和 Session 列表。
第 4 步最容易踩坑:不同仓库的 PR 事件,或者并非文档所述 ready-for-review 转换的事件,即使投递被接受,也可能不匹配该规则。
第 5 步也有一个陷阱:示例在未覆盖时使用启动目录。如果启动位置不符合预期,你可能会在错误的 checkout 下查找结果。
还要避免一个判断错误:不要将 202 解释为完成。应检查 Session 的实际状态和输出。
分享排查材料前应清理敏感信息。 payload 可能包含仓库元数据,密钥更不能出现在工单或诊断记录里。
重试不是无副作用的检查
如果签名和 JSON 已被接受,却没有 Session,应保留当时的匹配条件与结果,不要直接重发。
重复发送可能再次运行规则并创建额外的 Session。先判断第一次事件是否匹配、提示词是否已被接纳,再按实际部署的恢复方式处理——指南没有提供可查询所有场景的持久投递状态。
六、定制规则后,哪些责任会变
指南中的规则是受信任的 JavaScript,可以扩展为查询策略服务,或将仓库映射到本地路径。这种灵活性也意味着,决策责任在部署者身上。
需要审查的内容包括:
- 允许哪些仓库;
- 路径映射如何实现;
- 错误处理是否充分;
- 是否在合适的环境中测试过匹配与不匹配两种情况。
签名验证只确认投递来源,不会让 PR 标题、描述等字段变成可信指令。 修改评审提示词时,应保留示例中「把 PR JSON 视为不受信任元数据」的做法。
某些流程可能需要出站访问,但入站密钥不提供这种能力。哪个组件需要什么权限、如何配置,都要单独决定。
示例禁止修改,因此不能从「Session 已创建」推导出「它会自动评论或修改 PR」——这类行为需要独立设计和授权。
投递可靠性也是独立决策
文档明确说明 runtime 不保存投递或执行状态,重试可能产生另一个 Session。如果业务需要额外的去重或恢复能力,就得在示例假设之外自行设计并验证。
自己的运维记录可以将事件身份与实际评审结果关联起来,但不能声称示例已经实现了恰好一次处理。
两个监听器要分清楚
部署时要区分这两个监听器:
- 专用 webhook 监听器:只注册一个 POST 路由。
- 主 Web UI 和 API:仍在另一个端口。
代理只转发需要接收 GitHub 请求的路径,可以降低意外暴露其他路径的风险。同时还应确认后端监听地址和网络访问规则。不要因为公网入口用了 HTTPS,就忽略代理到监听器之间的实际网络边界。
七、如何确认一次评审针对的是正确版本
示例会把精确 head SHA 传入评审提示词,因此排查时应将投递中的版本与 Session 实际评审的内容对照。
但要注意:签名验证不保证本地 checkout 自动处于该版本,也不证明评审结论已经发布。 指南没有承诺自动同步工作区,也没有承诺自动向 GitHub 发布评论。
因此,部署者必须自行明确两件事:如何准备本地仓库,以及由谁消费结果。
评审完成后,应检查 Session 的输出、涉及的版本和不确定项,再决定由谁处理。如果重复投递产生了多个 Session,要分别核对其来源和结果;不能仅凭其中一个 HTTP 响应推断其他执行的状态。
保留必要的事件与 Session 对照信息,同时避免记录密钥或不必要的敏感 PR 内容。
部署前就该测不匹配的情况
这一步很容易被跳过:主动测试不匹配事件的处理。
例如,确认目标仓库之外的事件不会被误认为评审已经启动,同时确认匹配事件能到达预期的 Workspace。这是在验证实际规则和环境,不会改变文档中 202 的含义。
规则更新后要重新测试,因为仓库映射和提示词可能已经变化。
密钥在重启后要保持一致;更新密钥时,则要协调 GitHub 配置与运行进程,避免两端使用不同的值。配置和日志的访问范围应符合团队要求。
对于他人提交的 PR,即使请求来自可信的 GitHub 投递,内容仍可能包含试图影响评审的文本。 评审提示词和后续人工核对都应守住这一边界。
评审人员还应检查返回内容是否针对目标变更,并保留无法判断的事项。自动创建 Session 可以减少人工启动步骤,但最终结果仍要依据任务要求核对。
每次更改后都应重新核对匹配条件。
八、有哪些限制和安全边界
把边界集中列在这里:
- 密钥是凭据,不应写入公开日志、工单或示例配置。
- 公网只转发专用端点,保护监听器的网络路径,并检查代理配置。
- 规则的
run()是受信任 JavaScript;定制可能增加网络调用或改变仓库到本地路径的映射,因此需要审查代码和部署权限。 - 即使投递签名有效,PR 字段仍是不受信任的输入。
- 「只读」是示例选择的权限 preset 和提示词意图,不能推导出周边所有系统均已隔离。
- 来源没有承诺恰好一次投递,也没有承诺自动发布评审评论。
- 需要出站 GitHub 访问时,必须另行配置。
九、相关术语
- Webhook:GitHub 因订阅事件发起的 HTTP 投递。
- Overlay:向 Web profile 添加示例监听器和规则的配置 patch。
- Workspace:注册的本地 checkout,评审 Session 在其下创建。
- Head SHA:示例规则传入评审提示词的精确 PR 版本。
- 提示词接纳:之后由普通 Session 持久化和生命周期负责工作的节点。
理解「提示词接纳」这个节点很关键——它是责任转移的分界线:在它之前,调用失败意味着工作丢失;在它之后,工作由 Session 生命周期负责。
十、边界说明
- 本文依据官方 GitHub 评审指南、公开部署指南与 Web 服务器参考整理,不是官方支持文档。示例行为可能随版本变化,动手前请以你所在版本的官方文档为准。
202不等于评审完成,签名验证也不等于评审结论正确。这两件事需要分别验证。- 自动评审的产物仍需人工核对,尤其是无法判断的事项。示例不承诺自动评论或修改 PR。
- 不要把重试当成无副作用的检查,重复投递可能创建额外的 Session。
- 本文所有命令与端口示例沿用文档默认值(
127.0.0.1:3081、DSH_GITHUB_WEBHOOK_PORT等);实际部署请按你自己的网络边界调整。
相关阅读
本文依据 DeepSeek Harness 官方 GitHub 评审指南、公开部署指南与 Web 服务器参考整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
插件与文档收录于:https://dsh-plugin.com/zh/blog