Cloudflare 分享的案例显示，Astro 项目通过 AI Agent、GitHub Actions 和人工复核，把 GitHub Issue 数量减少了 85%。这件事的重点不只是“让模型自动写代码”，而是把 Issue 分诊、信息补全、重复问题识别和验证流程接入持续集成，让维护者把时间留给真正需要判断的缺陷。
Issue 分诊为什么适合 Agent
开源项目的 Issue 通常混杂着几类内容：可复现的 bug、功能请求、使用咨询、重复报告和缺少环境信息的问题。人工维护者需要不断重复低价值动作：读取模板、判断类别、查找相似 Issue、请求日志，再把问题分配给合适的人。
这类工作具有几个适合 Agent 的特征：
- 输入主要来自结构化的 Issue 标题、正文、标签和评论。
- 输出可以限制为标签、优先级、补充问题和建议操作。
- 大多数动作可以异步执行，不要求实时响应。
- 高风险决定仍然可以交给维护者确认。
因此，一个可靠的工作流通常不是“Agent 直接关闭 Issue”，而是让 Agent 先生成分诊结果，再由规则和人共同决定是否执行。
一条可控的 Agent 工作流
可以把流程拆成五步：
- GitHub Actions 在新 Issue 或 Issue 更新时触发。
- Agent 读取标题、正文和少量上下文，输出固定格式的 JSON。
- 工作流校验 JSON，只允许预先定义的标签和优先级。
- 对低风险动作自动执行，例如添加标签或评论。
- 对关闭 Issue、修改代码或高优先级判断保留人工确认。
这种设计把模型限制在“提出建议和执行有限动作”的范围内。模型即使判断错误，也不应该拥有无限的仓库写权限。
可以直接改造的最小示例
下面是一个基于 GitHub Actions 的简化示例。它假设你有一个兼容 OpenAI Chat Completions 接口的模型服务，并将地址放在 MODEL_API_URL 中。实际接入时，需要根据模型供应商调整请求格式和认证方式。
先创建 .github/workflows/triage.yml：
name: AI issue triage
on:
issues:
types: [opened, edited]
permissions:
contents: read
issues: write
jobs:
triage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install dependencies
run: python -m pip install requests
- name: Ask the triage agent
env:
ISSUE_TITLE: ${{ github.event.issue.title }}
ISSUE_BODY: ${{ github.event.issue.body }}
MODEL_API_URL: ${{ secrets.MODEL_API_URL }}
MODEL_API_KEY: ${{ secrets.MODEL_API_KEY }}
MODEL_NAME: ${{ vars.MODEL_NAME }}
run: python scripts/triage_issue.py > triage.json
- name: Apply safe triage actions
uses: actions/github-script@v7
env:
TRIAGE_JSON: ${{ env.TRIAGE_JSON }}
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
script: |
const fs = require('fs');
const result = JSON.parse(fs.readFileSync('triage.json', 'utf8'));
const allowed = new Set(['bug', 'documentation', 'question', 'duplicate', 'needs-reproduction']);
const labels = (result.labels || []).filter(label => allowed.has(label));
if (labels.length > 0) {
await github.rest.issues.addLabels({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
labels
});
}
if (result.comment) {
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: `AI triage suggestion:\n\n${result.comment}\n\nPlease verify this suggestion before acting on it.`
});
}
再创建 scripts/triage_issue.py：
import json
import os
import sys
import requests
def ask_agent(title: str, body: str) -> dict:
prompt = f"""
You triage GitHub issues for an open source project.
Return JSON only, using this schema:
{{
"labels": ["bug" | "documentation" | "question" | "duplicate" | "needs-reproduction"],
"priority": "low" | "normal" | "high",
"comment": "a concise request or explanation"
}}
Do not close the issue. Do not invent reproduction steps.
If the report lacks enough information, use needs-reproduction and ask for
runtime version, operating system, reproduction steps, and logs.
Title: {title}
Body:
{body[:12000]}
"""
response = requests.post(
os.environ["MODEL_API_URL"],
headers={
"Authorization": f"Bearer {os.environ['MODEL_API_KEY']}",
"Content-Type": "application/json",
},
json={
"model": os.getenv("MODEL_NAME", "triage-model"),
"temperature": 0,
"messages": [
{"role": "system", "content": "You output valid JSON only."},
{"role": "user", "content": prompt},
],
},
timeout=60,
)
response.raise_for_status()
content = response.json()["choices"][0]["message"]["content"]
result = json.loads(content)
allowed = {"bug", "documentation", "question", "duplicate", "needs-reproduction"}
result["labels"] = [x for x in result.get("labels", []) if x in allowed]
result["priority"] = result.get("priority", "normal")
result["comment"] = str(result.get("comment", ""))[:2000]
return result
if __name__ == "__main__":
result = ask_agent(
os.getenv("ISSUE_TITLE", ""),
os.getenv("ISSUE_BODY", ""),
)
json.dump(result, sys.stdout, ensure_ascii=False)
sys.stdout.write("\n")
这个示例只自动添加有限标签和评论。它没有关闭 Issue，也没有写入仓库内容，适合作为第一阶段的实验版本。生产环境中还应增加重复 Issue 检索、评论去重、超时重试、敏感信息过滤和审计日志。
85% 的关键不在模型本身
从这类案例可以提炼出三个架构判断。
把 Agent 放在流程边界上。 Agent 处理的是 GitHub 事件和维护动作，而不是孤立地运行一个聊天机器人。输入、输出、权限和失败路径都能被 GitHub Actions 记录下来。
用结构化输出替代自由文本。 标签、优先级和评论分别承担不同职责。JSON schema、允许标签集合和长度限制可以减少模型输出直接污染项目流程的风险。
保留 human in the loop。 自动化最适合处理高频、低风险的判断。关闭 Issue、标记安全问题、修改公共 API 或合并代码，都应设置人工审批或额外规则。Agent 的价值是减少维护者面对的噪声，不是消除维护者。
落地时的检查清单
- 先统计 Issue 的类别、重复率和缺少复现信息的比例，再确定自动化目标。
- 为模型建立小而明确的标签集合，避免让它自由创建标签。
- 将 GitHub Token 权限限制为
issues: write，不要默认授予代码写权限。 - 记录原始输入、模型版本、结构化输出和最终人工决策。
- 用历史 Issue 回放测试准确率、误标率和评论质量。
- 对模型不可用、JSON 解析失败和 GitHub API 限流设计降级路径。
- 每隔一段时间抽样复核自动处理结果，检查规则是否需要调整。
Cloudflare 与 Astro 的经验说明，AI Agent 在软件工程中的实际收益，往往来自流程编排、权限控制和自动化验证的组合。模型只是其中一个组件；真正决定效果的是哪些动作允许自动执行，以及哪些判断必须留给人。