用 GitHub Projects 和 Actions 管理 AI Agent 开发的反馈、迭代和发布
让 AI agent 写代码以后,写代码这一步快了,但是有两个事情会逐渐多起来:
- 发现问题以后,怎么把它交代清楚给 agent。
- agent 改完以后怎么上线、怎么确认,上线后又发现的问题怎么再回到 agent 手里。
这篇按「反馈 → 迭代 → 发布」这个循环,整理一套把三步串起来的做法。用到的是 GitHub 自带的 Issues、Projects 看板、PR 和 Actions,再加几个小脚本和一份写给 agent 看的 AGENTS.md。
整个循环
flowchart TD
subgraph S3 [发布]
direction LR
G[测试版本] --> H[正式版本]
end
subgraph S2 [迭代]
direction LR
C[开发] --> D[检查和评审] --> E[合并]
D -.->|不通过| C
end
subgraph S1 [反馈]
direction LR
A[发现问题或需求] --> B[记录下来,确定范围]
end
S1 --> S2 --> S3
S3 -->|投入使用| S1
下表是每一步用到的功能,后面逐个讲。
| 阶段 | 功能 | 用到什么 |
|---|---|---|
| 反馈 | 需求写成卡片,用脚本建卡和挪卡 | Issues、Projects 看板、Github 命令行工具 |
| 迭代 | 提交前的检查、PR 关联卡片、卡片状态跟着 PR 走 | git 钩子、PR 模板、Actions |
| 发布 | 合并后自动出测试包、发版 PR、发版流水线 | Actions、tag、GitHub Release |
| 回到反馈 | 从版本号查回原话、把教训写回规则 | 版本号、Release 说明、AGENTS.md |
人做的事集中在几处。
- 开工前决定做什么、确认范围,
- 开 PR 后 review 和合并,
- 攒够改动后决定什么时候发版,
- 最后在应用平台上提交审核。
每一步谁来做、用什么命令,写在仓库根目录的 AGENTS.md 里,coding agent 开工前会读它。
反馈:需求写成卡片
卡片里写什么
每个改动都对应看板上的一张卡片,也就是一个 GitHub issue。没有卡片,agent 不开工。
反馈有两种进来的方式。一种是自己直接在 Github Project 看板上写一张卡片(正文描述可以先空置,一般也可以当做临时想法的记录),另一种是在对话里直接跟 agent 说,由 agent 建卡。agent 建卡时,正文先贴原话,再写做什么、不做什么,比如:
原话:列表能不能搜索
做:
- 列表页顶部加搜索框,按标题搜索
- 没有结果时显示空状态
不做:
- 按内容全文搜索原话要原样保留。agent 理解的范围可能有偏差,事后对照原话才看得出来。不做的部分也要写,免得 agent 顺手多做。
后面的讨论和决定,也都补进这张卡片:
- 需求不清楚时,先和 agent 讨论,列出有几种做法时,并可以让 agent 把讨论的过程或者结果记录在卡片上。
- 做的过程中有了新反馈,也补进同一张卡片(或者也可以单独写一个卡片)。
- 如果最后决定不做,也在卡片下写明原因。过一阵子,翻卡片就知道当时为什么没做。
卡片的状态
看板的 Status 字段用 GitHub 模板自带的五个选项。每个状态由谁来挪,事先定好:
| 状态 | 含义 | 谁来挪 |
|---|---|---|
| Backlog | 记下来,暂时不做 | 人 |
| Ready | 确定要做,可以开工 | 人 |
| In progress | 正在做 | agent 开工时挪,同时指派给自己 |
| In review | 开了 PR,等 review | agent 开 PR 后挪 |
| Done | PR 已经合并 | 只能由合并触发 |
agent 只做 Ready 列的卡片。人在对话里直接提的需求算作开工指令,卡片建好就是 In progress。Done 不能手动挪,所以看板上的 Done 就表示代码已经合进 develop。几个人共用一个看板时,看负责人就知道每张卡片在谁手里。
用脚本建卡和挪卡
agent 可以直接用 Github 命令行工具 gh 操作看板,但要带上看板 ID、Status 字段 ID 和各个选项的 ID,命令很长,也容易填错。可以写一个小脚本,把常用操作包成几个命令:
npm run card -- new "[feat] 列表支持搜索" --body "原话 + 范围" # 建卡,默认 In progress
npm run card -- move 42 "In review" # 挪卡
npm run card -- list Ready # 看某一列的卡片规则也可以放进脚本里:
- 不写正文不让建卡。
- 挪到 In progress 时,把卡片指派给自己。
- 不能挪到 Done。
- 设完状态等几秒再读一次。看板如果开了「加到看板时设一个默认状态」的自动化,它和脚本几乎同时写状态,后写的生效。读到状态被改了就重设。
看板 ID 和字段 ID 用 gh 查,查之前先给 gh 加上 project 权限:
gh auth refresh -s project
gh project view 1 --owner your-name --format json # 看板 ID,PVT_ 开头
gh project field-list 1 --owner your-name --format json # Status 字段 ID 和各选项的 ID这些 ID 在 AGENTS.md 里也记一份,方便 agent 在脚本之外直接用 gh。再写一个测试检查两边一致,换看板时就不会只改了一边。
迭代:从卡片到合并
改界面先改设计稿
改界面的需求,可以在写代码前多一道确认。agent 先改设计稿,截图给人看,确认以后才写代码,这期间卡片一直是 In progress。在设计稿上改几轮,通常比代码写完再改省事。设计稿和代码放在同一个 PR 里提交。
如果项目有设计规范文档,再加一条规矩。改了颜色、尺寸或组件写法,在同一个 PR 里更新这份文档。
对于设计稿,建议直接让 agent 画 HTML,并且直接在项目中用 git 管理,做到设计即代码,这样一方面避免设计工具的 MCP 次数限制,另一方面提高了设计资源的可回溯性、可交互性以及可管理性。
提交前的检查
人看到 PR 之前,agent 先要过几道检查。检查失败时,报错直接回给 agent。
| 检查 | 什么时候跑 | 查什么 |
|---|---|---|
| commit-msg 钩子 | 每次提交 | 提交信息是否符合 Conventional Commits(type(scope): 描述 这种格式) |
| pre-push 钩子 | 每次推送 | 不能直接推到 develop 和 main,提交信息、类型检查、单元测试,需要的话还有 E2E |
| 自测 | 提交前 | 让 agent 在 浏览器/模拟器/真机 上把改到的页面点一遍,截图写进 PR |
| CI | 开 PR 和之后每次推送 | 提交信息、PR 标题、Refs #卡号、类型检查、单元测试 |
前两项是本地的 git 钩子。「不能直接推到 develop 和 main」放在 pre-push 钩子里,是因为 GitHub 免费版的私有仓库用不了分支保护。git 会把要推送的分支通过标准输入传给钩子,每行一个,命中就拒绝:
const PROTECTED_BRANCHES = ['develop', 'main']
// 每行是:<本地 ref> <本地 sha> <远端 ref> <远端 sha>,删除远端分支也会出现在这里
export function protectedTargets(stdin: string): string[] {
return stdin
.split('\n')
.map(line => line.trim().split(/\s+/)[2])
.filter((ref): ref is string =>
!!ref && PROTECTED_BRANCHES.some(branch => ref === `refs/heads/${branch}`))
}紧急情况设 ALLOW_PROTECTED_PUSH=1 放行。另外几点:
- 测试在钩子和 CI 里都查,因为
git commit --no-verify能跳过本地的 git 钩子。 - 报错信息写成给 agent 的下一步提示,告诉它该做什么。
- 需要特殊环境的测试,比如要登录桌面开发工具的 E2E,GitHub 提供的机器跑不了,只能放在本地的 pre-push 钩子里。
- 在 commit 的钩子中你可以关联本地另一个 agent,让另外的 agent 来帮你 review 代码,并反馈给当前 agent 进行必要的修改
PR 关联卡片
PR 正文按模板写,第一行是 Refs #42,接着写改了什么、怎么验证的(截图路径),有部署或设计稿改动的话也写上。
关联卡片用 Refs,不用 GitHub 自带的 Closes。官方文档写明,Closes 这类关键词只在 PR 发往默认分支时生效:
The special keywords in a pull request description are interpreted only when the pull request targets the repository’s default branch. If the pull request targets any other branch, then these keywords are ignored, no links are created, and merging the PR has no effect on the issues.
这套流程里,日常的 PR 都发往 develop,默认分支是 main,写 Closes 没有用。CI 会检查发往 develop 的 PR 有没有写 Refs #编号,没写就报错,并告诉 agent 先去建卡:
- name: PR 关联需求卡
if: github.event_name == 'pull_request' && github.base_ref == 'develop'
env:
BODY: ${{ github.event.pull_request.body }}
run: |
if ! printf '%s\n' "$BODY" | grep -qE '(^|[[:space:]])Refs #[0-9]+'; then
echo "::error::PR 正文要写 Refs #<需求卡编号>。还没有卡就先用 npm run card -- new 建卡"
exit 1
fi同一个 CI 任务还检查 PR 标题。功能 PR 用 squash 合并(把 PR 里的提交压成一个),合并后 PR 标题就是 develop 上的提交信息,后面生成版本说明也用它,所以标题也要符合提交信息的格式:
- name: PR 标题
if: github.event_name == 'pull_request' && github.base_ref == 'develop'
env:
TITLE: ${{ github.event.pull_request.title }}
NUMBER: ${{ github.event.pull_request.number }}
run: printf '%s (#%s)\n' "$TITLE" "$NUMBER" | npx commitlint --verboseCI 的触发事件里加上 edited,改了 PR 标题或补上 Refs 以后会重新检查。
卡片状态跟着 PR 走
再加一个工作流,按 PR 事件同步卡片:
name: 看板同步
on:
pull_request:
branches: [develop]
types: [opened, reopened, ready_for_review, closed]
permissions:
contents: read
issues: write
jobs:
card:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
cache: npm
- run: npm ci
- name: 按 PR 事件挪卡
env:
GH_TOKEN: ${{ github.token }}
PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
run: npm run card -- pr-eventcard pr-event 读 Actions 提供的事件文件(路径在环境变量 GITHUB_EVENT_PATH 里),按下表处理:
| PR 事件 | 处理 |
|---|---|
| 打开、重新打开、草稿转为可 review | 卡片挪到 In review(需要 PROJECT_TOKEN) |
| 合并 | 关闭 Refs 的 issue,留一条评论说明是哪个 PR 合并的 |
| 没合并就关闭 | 不动卡片 |
发往其他分支,或正文没有 Refs | 不处理 |
判断的部分写成一个不调用 gh 的函数,输入是事件,输出是要做的动作,方便写测试。
合并时关闭 issue,不直接改状态。issue 一关,看板的 Item closed 自动化把卡片挪到 Done。
review 和返工
review 意见在同一个分支上改,推送后 CI 重新跑,卡片一直是 In review。合并由人来做,agent 只在人明确说「合并」时才合并。
PR 也可能没合并就关掉。这时卡片挪回 In progress 或 Ready,或者在卡片下写明原因后关掉。
review 时记得让 agent 把返工的原因写进卡片,值得记住的再写进 AGENTS.md。
发布:合并之后
合并后自动出测试包
每次合并到 develop,CI 跑完检查,就自动部署到测试环境,并出一个测试包:
- 版本号带后缀,比如
0.3.2-dev.128,dev.后面是提交数。页面有显示版本号的地方,测试包另外标上「测试环境」。 - 连测试环境的后端和数据库。仓库里提交的配置永远指向测试环境,只在打正式包时临时换成生产配置,打完换回来。
部署成功后,把 tag deployed/develop 移到当前提交。还没有这个 tag 时全部部署。当前提交比 tag 记录的还旧,比如重跑了旧的流水线,或者两次合并的流水线结束顺序反了,就什么都不部署,测试包也不上传,免得退回旧版本。手动运行工作流时可以选「全部重新部署」,放弃一个 PR 以后,用它把测试环境换回 develop 的代码。
发版 PR
develop 上攒够改动以后发版。版本号只有一个来源,比如根目录 package.json 的 version,页面显示的版本号从它生成。版本号只用发版脚本改,再写个测试检查各处一致。
发版脚本 release:prepare 做这几件事:
- 检查当前在 develop 上,工作区干净,并且和远端一致。
- 升级版本号,从 develop 拉出
release/v0.3.2分支,提交chore(release): v0.3.2。 - 推送这个分支。推送会触发 pre-push 钩子,把要发的代码完整测一遍。
- 开一个发往 main 的 PR,正文列出上个版本以来的提交。
- 切回 develop。
这个脚本也可以放进工作流,在 GitHub 网页上选 develop、填版本号运行。
发版 PR 上的 CI 检查版本号,需要做到这个版本还没发过(没有对应的 v* tag),并且比上一版高。也可以用生产配置把包编译一遍,检查有没有缺页面、包有没有超过平台的大小限制。
发版 PR 用 merge commit 合并,不用 squash。它从 release 分支开,不直接从 develop 开,有两个原因。一是发版内容要固定,从 develop 开的话,PR 开着的时候合进 develop 的改动都会跟进来。二是如果仓库开了合并后自动删除源分支的设置(Automatically delete head branches),源分支是 develop 时,合并后删掉的就是 develop。
发版流水线
main 上每多一个提交,发版工作流按顺序做这几件事:
- 跑类型检查、lint 和单元测试。
- 把后端部署到生产环境,然后上传正式包,或者触发构建。
- 打 tag
v<版本>,建 GitHub Release。 - 把 main 合回 develop。
GitHub Release 的说明由脚本生成,内容是上个 tag 以来的提交标题,去掉 chore(release) 那一条:
自 v0.3.1 以来的改动:
- feat(client): 列表支持搜索
- fix(client): 设置页开关没反应提交信息的格式统一,这份说明不用再整理。
流水线重跑时,要能判断该不该上传。上传前看版本号对应的 tag:
// tag 不存在:上传。tag 就在当前提交上:重跑,跳过。tag 在别的提交上:版本号没升级,报错
export function uploadDecision(version: string, tagCommit: string | null, head: string): 'upload' | 'released' {
if (!tagCommit)
return 'upload'
if (tagCommit === head)
return 'released'
throw new Error(`main 上的版本 ${version} 已经发过:发版要先升级版本号`)
}构建失败要重来时,在 main 上手动运行发版工作流,加一个 rebuild 选项,对同一个提交重新构建。
最后一步把 main 合回 develop,因为升级版本号的提交只在发版分支上。这个任务要有 contents: write 权限:
- name: 把 main 合回 develop
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git fetch origin develop
git switch -C develop origin/develop
git merge --no-edit -m "Merge branch 'main' into develop" "$GITHUB_SHA"
git push origin develop能快进就快进,重跑时已经合过就什么也不做。CI 里不装 git 钩子(HUSKY: 0),这次推送不会被「不能直接推 develop」拦住。
正式版本就走平台的审核、发布。这些版本用起来发现的问题,同样回到第一步建卡。
回到反馈
从版本号查回原话
一条反馈从提出到上线,中间留下的记录能一路查回去。比如使用中发现一个问题,想知道是哪个版本带进来的,或者想确认某个改动上线了没有:
- App 的「关于」页显示版本号。测试包是
0.3.2-dev.128,标着「测试环境」,正式包只显示0.3.2。 - 平台上每次上传的备注带着提交号,比如
v0.3.2(a1b2c3d)。 - 正式版对应一个 tag 和一个 GitHub Release,Release 里列着上个版本以来的提交标题。
- 在 GitHub 上打开提交,能看到它来自哪个 PR。squash 合并的提交,标题末尾本身就带着 PR 编号,比如
(#43)。 - PR 正文第一行是
Refs #42,点过去就是卡片。 - 卡片正文是当初的原话和范围,评论里是中间的讨论和决定。
反过来,从一张卡片能找到对应的 PR,从 PR 的合并提交能看到它被哪些 tag 包含,也就知道它在哪个版本上线。
这条链里有一环靠的是约定。功能 PR 要用 squash 合并,用 merge commit 或 rebase 合并的话,PR 标题不会成为提交信息,版本说明里也就没有 PR 编号。
把教训写回规则
AGENTS.md 是 agent 每次开工都会读的规则。出过的问题修好以后,把原因写进去,下次开工的 agent 就能读到。
流程本身也按这个循环改。对流程有意见,同样写成卡片,走一遍分支、PR 和合并:
- 「先建卡再开发」本身就是一张卡片。
- 「开 PR 后卡片进 In review,合并后自动 Done」也是一张卡片。它的 PR 合并时,新加的看板同步工作流已经生效,这张卡片成了第一张被自动挪到 Done 的卡片。
- 发版原来要等构建跑完。提成卡片以后改成触发构建就结束。
流程靠工作流文件、钩子和脚本实现,agent 改它们时也可能改坏。可以给这些文件写测试,检查工作流的触发条件、步骤顺序和权限,PR 模板必须用 Refs,脚本里的看板 ID 和 AGENTS.md 一致。比如:
test('PR 模板:关联需求用 Refs,不用会自动关 issue 的 Closes / Fixes', () => {
const template = read('.github/pull_request_template.md')
assert.match(template, /^Refs #$/m)
assert.doesNotMatch(template, /^(Closes|Fixes|Resolves) #/im)
})总结
这套做法里,反馈记在卡片上,迭代记在 PR 上,发布记在 tag 和 GitHub Release 上。三者之间靠 Refs #卡号、提交信息和版本号连起来。从一个版本号,能查回当初的原话。从一张卡片,也能查到它在哪个版本上线。
决定做什么和做到哪一步,决定什么时候合并和发版,这些由人来做。其他交接交给脚本和 Actions,漏掉的步骤由钩子和 CI 拦住,出过的问题写回 AGENTS.md。

