GitHub 的 webhook 返回 202,评审却没跑起来:问题不在签名上

简介: DeepSeek Harness 可以通过签名 GitHub webhook 自动创建只读评审 Session。流程包括安装实验性 webhook 包、应用评审 overlay,并通过 TLS 暴露专用端点。但 `202` 只表示签名和 JSON 已被接受、规则调用已调度,**不代表规则匹配、Session 已创建或 agent 已完成评审**。本文说明整条链路各环节的实际语义,以及没有看到评审时应按什么顺序排查。

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 状态,并选用 standard agent preset 与 read-only permission 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 不存储投递或执行状态,因此有三条后果:

  1. 重复投递会再次运行规则,可能创建另一个 Session。
  2. 崩溃会丢失尚未接纳提示词的规则调用。
  3. 提示词被接纳后,工作才由普通的 Session 日志、持久化、Workspace 和 agent 生命周期负责。

因此,不能把 HTTP 成功当作持久队列或去重保证。

第一次匹配的投递会通过 WorkspaceRegistry.create() 在 Workspace 不存在时创建它,后续投递则复用同一个。因此,本地路径必须指向预期的 checkout。有效签名只说明共享密钥下的入站数据通过了验证,并不能证明 checkout 内容正确,也不能证明评审达成了预期结果。

五、没看到评审时按什么顺序排查

沿着链路逐段检查,不要跳步:

  1. 确认 GitHub 确实将已订阅的事件投递到了预期的公共 URL。
  2. 确认配置的密钥与运行进程可访问的值一致。
  3. 检查专用代理的路由和 loopback 监听器是否正常。
  4. 将 payload 中的事件、动作、来源、仓库与示例规则逐项对照。
  5. 检查预期的本地 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

目录
相关文章
|
18天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
7950 58
|
3天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1505 0
|
5天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
19天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5707 68
|
6天前
|
云安全 人工智能 安全
|
13天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
2948 9
|
5天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
3天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
2247 0
|
11天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1883 1

热门文章

最新文章