如何使用 Next.js 和 Jev 构建一个能够自动将错误信息发送到 GitHub 的人工智能支持系统

系统收到的响应并不会被直接视为有效信息。适配器会使用Zod规范来验证这些响应内容，确保所有答案都属于允许的范围，并且会根据Jev给出的各选项的优先级来计算出最终的置信度分数。

如果该概率值缺失，或者不在0到1的范围内，那么该请求将会被拒绝，相应的工单也会继续处于待审核状态，而不会被赋予一个人为设定的数值。

步骤4：代码负责做出最终决策

Jev会推荐一个错误类型和严重程度等级，但它并不会决定工单应该被分配到哪个处理流程中，也不会决定该工单是否应该被提交到GitHub上。这些工作实际上是由`packages/ai/src/policy.ts`文件中的函数来完成的：

export function routeForType(type: TicketType): TicketRoute {
  switch (type) {
    case "bug":
      return "engineering";
    case "feature_request":
      return "product";
    case "spam":
      return "ignore";
    default:
      return "support";
  }
}

export function evaluateGitHubEscalation(input: {
  type: TicketType;
  route: TicketRoute;
  confidence: number;
}): EscalationEvaluation {
  const reasons: string[] = [];
  if (input.type !== "bug") reasons.push(`类型为${input.type}，不属于错误类别`);
  if (input.route !== "engineering") reasons.push(`分配路径为${input.route}，不属于工程处理流程`);
  if (!(input.confidence >= GITHUB_ESCALATION_CONFIDENCE_THRESHOLD)) {
    reasons.push(`置信度为${input.confidence}，未达到最低要求${GITHUB_ESCALATION_CONFIDENCE_threshold}`);
  }
  return { eligible: reasons.length === 0, reasons };
}

routeForType函数会将每种类型的工单分配到相应的处理队列中：错误会被送入工程处理流程，功能请求会进入产品开发环节，垃圾信息会被隔离处理，其余所有工单则会被送往支持部门。由于这是一个普通的`switch`语句，因此你可以直接阅读、测试或修改这些代码，而无需对人工智能系统进行任何调整。

evaluateGitHubEscalation函数会判断某个工单是否具备被提交到GitHub上的条件：该工单必须属于错误类型，且必须处于工程处理队列中，其置信度值也必须至少达到0.9。这个函数并不会直接返回`true`或`false`，而是会列出导致工单无法被提交的理由，这些信息会在控制面板上显示出来，这样你就能清楚地知道为什么“创建GitHub问题”按钮会处于不可使用状态。

0.9这个阈值被设置在一个配置文件中，文件中明确说明这是一个未经校准的初始值，并非实际测得的准确数值。我在代码中明确写明了这一点：即使模型的评分达到了0.99，也不意味着它的预测准确率真的有99%。

步骤5：在控制面板中进行人工审核

每张工单都会被记录在一个私有的控制面板中。项目页面会显示每种状态下的工单数量：

每个项目都有一份带有筛选功能的工单列表，这些筛选条件涵盖状态、处理路径、类型、严重程度以及参考信息：

打开某张工单后，系统会显示访客提交的报告、当前的人工智能分类结果、完整的分类历史记录，以及所有相关事件的时间线。你可以重新进行问题优先级评估，解决该工单，或者记录下某种决策——这种决策可能会改变问题的处理路径、状态或GitHub上的推荐方案。

有一点我很在意：人类做出的决策会被存储在专门的表格中，其中会注明决策者以及做出决策的原因。人工智能的处理记录永远不会被篡改。即使你覆盖了Jev的判断结果，仍然可以清楚地看到Jev当初说了什么、什么时候说的，这一点在想要了解该模型的实际表现时非常重要。

控制面板采用了Better Auth进行保护，所有的读写操作都局限于特定的工作空间范围内。进行任何修改都需要使用相同的来源请求，而且只有工作空间的所有者才能将内容发布到GitHub上。

步骤6：从缺陷报告转化为GitHub问题

当某张工单符合相关规则时，控制面板会显示即将创建的问题的预览版本：

仔细观察这张截图就会发现：访客虽然留下了自己的姓名和电子邮件地址，但这些信息在上面的控制面板中确实显示出来了，但在问题的预览版本中却完全看不到。

这绝非巧合。在任何问题被创建之前，相关报告都会先通过packages/github/src/privacy.ts文件中的隐私审核机制。该机制会检查报告中是否包含电子邮件地址、电话号码、银行卡号、私钥、API令牌、JSON Web令牌或密码等信息。同时，系统还会将报告中的信息与访客提交的联系详情进行比对，这样就可以确保“嗨，我是Sam访客”这样的表述不会导致访客的姓名被泄露到公开的问题中。如果发现任何违规内容，问题的预览版本就会被阻止显示，相应的内容也不会被发布。

当你点击创建GitHub问题按钮时，还会有一些额外的安全措施被触发：

• 使用GitHub应用而非个人令牌：该应用仅会被安装在你选择的仓库上，它只拥有编写问题内容和读取元数据的权限，没有其他任何功能。

• 先进行声明，然后再创建问题：在真正调用GitHub接口之前，系统会先将工单的状态标记为creating，因此即使点击两次按钮，也不会创建两个重复的问题。

• 隐藏的标识符：每个问题的内容结尾都会包含一个与该问题相关联的HTML注释。如果某个请求超时且结果未知，IssueRelay会先在自己的应用中搜索仓库中是否存在这个特定的标识符，然后再尝试再次处理该问题。它绝不会盲目地重复尝试已经创建过的问题。

这是IssueRelay根据访问者的报告，在我的项目代码库的公共仓库中创建的一个真实问题。这个问题是由应用程序的机器人生成的，被标记为bug，其中包含了报告内容以及人工智能给出的分类结果，但并没有联系方式：

步骤7：保持GitHub与数据看板之间的同步

最后这个环节完成了整个流程。当你在GitHub上关闭某个问题时，GitHub会向IssueRelay发送一个webhook信号，此时该问题的状态就会变为“已解决”。如果重新打开这个问题，它又会重新进入处理队列。

按照定义，webhook端点是公开的，因此它的首要功能就是验证请求确实来自GitHub。这是packages/github/src/webhook-auth.ts文件中实现的验证逻辑：

export function verifyWebhookSignature(input: {
  secret: string;
  rawBody: Uint8Array;
  signatureHeader: string | null;
}): boolean {
  const { secret, rawBody, signatureHeader } = input;
  if (!secret || !signatureHeader?.startsWith("sha256=")) {
    return false;
  }
  const hex = signatureHeader.slice("sha256=".length);
  if (!/^[0-9a-f]{64}$/.test(hex)) return false;
  const expected = createHmac("sha256", secret).update(rawBody).digest();
  const actual = Buffer.from(hex, "hex");
  if (expected.length !== actual.length) return false;
  return timingSafeEqual(expected, actual);
}

GitHub会使用只有它自己和你的平台才知道的密钥来为每一条传输信息生成签名，并将这个签名放在X-Hub-Signature-256头部字段中。而这个函数则会根据原始请求数据字节重新计算出一个HMAC SHA256签名，然后对比这两个签名是否一致。

有两条细节很容易被忽略或弄错：首先，签名必须是根据GitHub实际发送的原始数据字节来计算的，任何形式的JSON解析都会改变这些字节的内容；其次，进行比较时使用了timingSafeEqual这个函数，无论第一个字节还是最后一个字节有所不同，这个函数计算所需的时间都是相同的，因此攻击者无法通过测量响应时间来逐个字符地猜测签名内容。此外，这个函数在遇到任何错误时都会返回false，而不会具体说明是哪种错误，这样一来就没有任何信息会被泄露。

在完成签名验证后，IssueRelay会为每一条传输记录保存一个唯一的ID，这样重复的传输请求就会被忽略。它只会更新与特定应用程序安装版本和代码库相关的问题，并且会按照这些问题在GitHub上实际发生的顺序来处理它们，而不是按照接收到的顺序。

如何部署你自己的IssueRelay

你可以在大约15分钟内通过Vercel和Neon来部署你自己的IssueRelay。包括故障排除在内的完整操作指南请参见docs/SELF_hosting.md。以下是简要说明。

步骤1：部署

推荐的做法是使用README文件中的通过Vercel进行部署选项。该选项会将代码仓库复制到你的GitHub账户中，同时创建一个Neon数据库，并要求你提供三个随机生成的密钥。

第一次构建时会故意出现错误，因为Vercel的克隆界面没有设置“根目录”的选项，所以你需要在项目设置中将“根目录”设置为apps/web，然后再重新进行部署。这样，在生产环境中构建时，系统会自动为你创建所有的数据库表。

指南中还提到了另一种分支并导入的方法，这种方法可以让你以后只需点击一次按钮就能完成更新操作，但这种方法目前还没有经过全面测试。

步骤2：运行设置页面

在新建的网站中打开/setup路径。这个页面只有在数据库中还没有任何账户信息，并且你输入了在部署过程中生成的SETUP_TOKEN时才会生效。这样，如果有人先找到了你的网站地址，也无法占用你的平台资源。该流程会为你创建所有者账户和第一个项目，同时还会显示你的插件密钥以及可以直接粘贴使用的插件代码。

站点地址字段的格式为http://localhost:3000，这是因为Next.js应用是在你的计算机上运行的。你也可以添加你的实际域名，比如https://my-site.vercel.app。如果你忘记了设置这个地址，插件会向访问者显示“我们无法发送您的消息”，因此当报告没有按时到达时，首先检查这个地址是非常重要的。

步骤3：创建GitHub应用

手动配置GitHub应用的过程中很容易出现一些错误。最常见的问题就是忘记订阅“Issues”事件，我在测试过程中就犯过这个错误。因此，IssueRelay提供了一个命令，可以帮助你根据配置文件自动创建GitHub应用：

pnpm github:create-app --platform https://your-issuerelay.vercel.app

执行这条命令后，GitHub会自动在浏览器中打开相关页面，所有必要的信息都已经填好：这个应用是私有的，具有提交问题以及查看元数据的权限，并且已经订阅了“Issues”事件，其Webhook也会指向你的平台。

你只需点击创建GitHub应用按钮，GitHub就会将你重定向到由该命令启动的临时本地服务器上。此时，系统会把应用ID、私钥以及Webhook密钥写入一个git不会识别的文件中，这些信息永远不会在终端窗口中显示出来。之后，终端会提示你进入下一步设置环节。

步骤4：添加密钥并重新部署

将GitHub应用所需的三个参数以及你的TYPESAFE_API_KEY添加到Vercel项目的环境变量中，然后重新部署。对于处理GitHub问题而言，Jev是必不可少的；如果没有它，报告仍然会显示在仪表板上，但这些报告无法被转化为正式的问题。

步骤5：连接你的仓库

将该应用安装在托管 Widget 的网站的仓库中，然后打开仪表板中项目的设置页面进行连接。系统会询问GitHub，哪个安装版本以及哪个仓库ID与当前名称对应，这样就能确保不会错误地链接到错误的仓库。

步骤6：安装Widget

使用设置页面中的代码将Widget安装在你的网站上，然后发送第一份报告。

为了确保后续使用的副本始终是最新的版本，请从主仓库拉取最新的变更。本指南主要介绍了使用“部署”按钮创建副本时所需进行的一次性操作，因为这些副本并不是GitHub上的分支。

在真实网站上运行它

虽然演示只是为了说明功能，但我还是决定真正将IssueRelay应用到实际项目中。现在，这个Widget已经在我个人网站andrewbaisden.com上的作品集中开始运行了：

网站的设计可能会发生变化，因此如果你在未来阅读这篇文章，之前发布的版本可以在我的GitHub仓库中找到。

在安装和测试这个Widget的过程中，我学到了一些东西。我的作品集在测试时仍然使用的是React 18，而应用路由系统已经使用了React 19。因此，我首先将作品集升级到了React 19，并确保所有现有的测试都能通过，之后才添加了Widget。这个Widget能够适应网站的不同主题设置，会显示在页面的右下角，并且在我的作品集仓库中还有针对它的单元测试和浏览器测试。

随后，我像普通用户一样测试了这个Widget。我从实际运行的网站上发送了三份报告：一份是疑问，一份是漏洞报告，还有一份是功能需求请求。Jev对这三份报告的分类完全符合我的预期，评分都在0.95到1.00之间，系统也正确地将它们分派到了相应的支持团队、工程团队和产品开发团队。其中那份漏洞报告在我的公开作品集仓库中被标记为问题#3，也就是之前截图中显示的那个问题。我在报告中附上了自己的姓名和电子邮件地址，但这些信息并没有出现在公开的issue页面上。

端到端测试及其收获

我并不想要一个只在我的机器上才能正常运行的项目，因此测试是每个开发阶段的必备环节，而不是被留到最后才进行的事情。

我们的测试套件包含多个层次：

• 单元测试涵盖了组件、API接口、人工智能相关逻辑、隐私保护机制以及设置页面等功能。这些测试一共有180个，而且其中没有任何一个需要使用数据库。

• 数据库集成测试是在专门的PostgreSQL测试数据库上进行的，其中包括一些并发性测试，用于确保用户两次点击操作不会导致在GitHub上创建两个问题。

• 使用Playwright进行的浏览器测试：这些测试会在不同的端口上启动独立的服务器，并且每次运行都会重新创建数据库，因此测试过程永远不会接触到真实数据。其中有一台服务器会使用空数据库来测试初始设置页面的功能。

• 包检查：该步骤会生成精确的npm压缩包，并将其安装到遵循严格内容安全策略的Vite项目中，同时也安装在Next.js项目中。这些操作都是在单独的仓库之外进行的，完成后会在每个项目中生成相应的报告。

• 实时运行流程测试：这项测试会针对真实的GitHub应用以及临时创建的仓库进行20项检查。包括提交报告、问题分类处理、预览结果、创建问题记录、确认没有私人信息被公开披露、在GitHub上关闭问题记录，然后等待Webhook通知，重新打开问题页面并检查整个流程是否正常。

我总共进行了三次这样的实时运行流程测试：第一次是在本地机器上通过隧道连接进行的；第二次是在生产环境中进行的；最后一次则是使用仅按照设置指南创建的全新副本进行的。三次测试都通过了全部20项检测。

不过，比测试是否通过更有趣的是，每个测试阶段所暴露出来的问题：

• “Issues事件”容易被忽略：当我第一次手动创建GitHub应用时，没有配置任何事件订阅机制，因此GitHub从未向IssueRelay发送过问题关闭的通知。正是这个错误导致了create-app命令的存在。

• 访问者会在报告中提到自己的名字：如果有人名叫Sarah却提交了“页面出错了”这样的报告，那么她的名字就会出现在公开的 issue 中。现在，隐私保护机制会将每份报告与其中提供的联系信息进行比对。

• Zod框架与严格的内容安全策略在浏览器中无法兼容：Zod 4会在运行时尝试使用new Function函数，而那些采用严格内容安全策略的网站会将这种行为视为违规。我最终去掉了组件中的Zod框架，转而编写了简单的验证代码，并通过测试确认这些验证代码与服务器上的Zod架构是匹配的。

• Vercel的部署流程中没有“根目录”选项，且框架的选择只能进行一次：我的两次全新部署尝试都失败了：第一次是因为Vercel错误地构建了仓库的根目录结构；第二次则是因为框架设置仍然被选为“其他”。现在，我们在vercel.json文件中明确指定了要使用的Next.js框架，而且指南中也对这种可能导致的错误进行了提示。

• 部署按钮生成的副本并不是分支版本：直接从主仓库执行git pull操作是无法完成合并操作的，因此现在指南中提供了专门的命令，用于将副本与主仓库连接起来。

• ：最初我将Jev插件设置为可选选项，但经过仔细检查后发现，如果没有这个插件，就无法生成满足要求的测试报告。现在，指南和设置页面都明确指出了这一点。

• <日志信息中的冗余内容也会影响测试结果

  ：每次数据库连接操作都会在错误级别记录SSL警告信息，这使得正常的部署过程看起来似乎出现了问题。为了解决这个问题，我们明确了驱动程序实际使用的SSL模式，这样一来，警告信息虽然仍然会出现，但证书验证的过程却没有任何变化。

最让我印象深刻的一点是：严格按照自己的文档进行部署，往往能够发现那些测试程序无法发现的错误。上面提到的所有部署问题，在自动化测试中都是无法被检测出来的；而只有当真正有人按照文档中的步骤来操作时，这些问题才会暴露出来。

开发过程：阶段划分与人工智能辅助开发

IssueRelay是分阶段开发的，每个阶段在开始下一个阶段之前都会进行书面交接：

我的开发环境配置

我大部分工作都是在终端中完成的。我的开发环境配置如下：

• 使用Ghostty作为终端工具，同时运行Claude Code、Codex和OpenCode程序

• 使用Cursor作为代码编辑器

• 同时使用ChatGPT、Claude和OpenCode的原生桌面应用程序

在开发IssueRelay的过程中，我主要使用了Claude Opus 5.5模型。在进行代码审查或在某个阶段结束前进行最终确认时，我还使用了其他模型，包括GPT-6 Sol和Grok，以及其他一些前沿的免费模型。

使用另一个模型重新审视相同的代码，往往能够发现一些实际存在的问题。例如，在对第7和第8阶段代码进行Grok审查时，共发现了15个问题；其中7个问题是确实存在的，包括在问题创建过程中的竞争机制以及一些可以被猜测出来的问题标记；我在继续开发之前修复了这7个问题。另外3个问题部分成立，还有5个问题因为有合理的解释而被暂时搁置。

Anthropic新发布的Sonnet 5.5模型和OpenAI的GPT-6.1 Sol模型并没有被用于这个项目。

更好的提示语如何提升了代码质量

代码质量的提升并非源于使用了更智能的模型，而是源于为这些模型提供了更明确的指令以及更合理的开发结构。以下是一些有效的做法：

• 一次只处理一个阶段：每个指令都要求仅完成一个具有明确结果的阶段，在我批准之前，AI不得开始下一阶段。对于那些规模较小、易于审查的修改来说，进行检查要容易得多，而试图修改一个复杂的功能则会带来巨大的麻烦。

• 在编写代码之前先制定计划：对于规模较大的项目阶段，我会要求先制定一份计划（“先制定计划，待我批准后再开始执行”）。阅读一份计划只需要两分钟，而纠正一个错误的实现方案却可能需要花费一整个下午的时间。

• 将规则明确记录在代码仓库中：`AGENTS.md`文件中明确了项目的各项规则，例如“在外部AI或GitHub发起请求之前，必须先处理已接受的请求”、“永远不要将联系信息发布到GitHub上”，以及“对于那些描述模糊的GitHub问题，切勿盲目尝试重新提交”。每次AI运行时都会读取这些规则，因此这些规则不会因为我忘记提醒而失效。

• 如实汇报结果：相关说明明确规定，绝不能将未执行的检查报告为通过结果，而且每次交接工作时都会记录实际执行的命令及其真实结果，包括失败情况。

• 明确提交代码的条件：像“当测试通过且没有其他问题时再提交代码”这样的要求，意味着在任何代码被推送到主分支之前，都必须先运行完整的测试套件。

• 要求提供证据而非空口承诺：我不会直接问“自我托管功能是否可行？”，而是会让AI按照新的部署指南来验证这一功能。正是这个简单的请求，帮助我们发现了七处与文档或配置相关的问题。

• 将实际使用中的反馈纳入开发流程：

  当我自己部署测试环境并记录下所有遇到的问题时，这些信息都会被直接添加到指南、设置页面中。