把编码 Agent 放进 CI 里跑,最难处理的从来不是「它会不会写代码」,而是它会不会在你没看见的时候直接改仓库、花掉一整天的额度。GitHub Agentic Workflows(命令行叫 gh aw)给出的答案是:你只写一个 Markdown 文件,前面用 YAML 声明触发条件、可用工具、能申请哪些写操作、每天最多花多少 AI 额度,GitHub 把它编译成一份带固定版本的 Actions 工作流,Agent 在沙箱里读、把想做的写操作作为「申请」提交,再由另一个拥有窄权限的作业真正执行。
gh)、仓库允许运行 Actions、以及一个可用的引擎账号(默认 Copilot,也可换 Claude、Codex、Pi)。整个过程不需要你在本地跑模型。四条先记住的边界:① 工作流跑在 GitHub Actions 里,会同时消耗 Actions 分钟和 AI 额度,一次配置失误可能连跑几十次;② safe-outputs 不是人工审批,而是「按类型和条数限额的申请通道」,你声明了 create-pull-request,Agent 就有权申请开 PR;③ 只改 Markdown 正文不必重编译,改 frontmatter 必须重编译,否则运行的还是旧配置;④ 从别人仓库 gh aw add 工作流前,先读完它的触发条件、权限、工具与安全输出,它会在你的仓库里以你的额度运行。
动手之前把清单过一遍,缺哪一项都会卡在中途,而且报错信息通常不会直接告诉你缺什么。
| 前置项 | 怎么确认 | 缺失后的典型表现 |
|---|---|---|
| GitHub CLI 已登录 | gh auth status 显示已登录且有 repo scope | gh aw 子命令报认证或 403 |
| 仓库允许 Actions | 仓库 Settings 里 Actions 未被禁用 | 工作流能编译但永远不触发 |
| 引擎凭据可用 | 按引擎文档配好令牌,或确认组织已开通对应额度 | 运行启动后立即在激活阶段失败 |
| 默认分支可推送 | 有写权限,或准备走 --create-pull-request | --push 被分支保护拒绝 |
| 测试仓库 | 不要拿生产仓库做第一次尝试 | 试错成本直接从「一条评论」变成「一堆 PR」 |
先弄清:Markdown 是源文件,lock.yml 才是真正跑的东西
gh-aw 的心智模型只有一句话:你写的是「给 Agent 的任务书 + 一张权限清单」,编译产物才是 Actions 认识的 YAML。两者必须一起提交,因为 Actions 只读 lock 文件。
| 概念 | 位置 | 作用 | 改动后要不要重编译 |
|---|---|---|---|
| 工作流源文件 | .github/workflows/<name>.md | YAML frontmatter 定权限,正文是 Agent 指令 | 改正文不用;改 frontmatter 要 |
| 编译产物 | .github/workflows/<name>.lock.yml | 带固定提交 SHA 的 Actions 工作流,标注「自动生成,请勿编辑」 | 由 gh aw compile 生成 |
| 元数据头 | lock 文件第一行 | gh-aw-metadata 记录 schema 版本、frontmatter 哈希、strict 与引擎 | 随编译刷新 |
| 依赖清单 | lock 文件头部注释 | 列出用到的 secrets 与被固定的外部 action 版本 | 随编译刷新 |
「Agent 只读、写操作另起作业」不是一句口号,它由六层叠起来。理解分层的好处是:出问题能判断该改配置,还是该换运行环境。
| 层 | 拦什么 | 你能调的地方 |
|---|---|---|
| 编译期校验 | schema 错误、非法表达式、未固定的 action | gh aw compile --strict |
| 隔离沙箱 | Agent 直接接触宿主凭据与文件系统 | 运行环境选择(Docker、自托管 runner) |
| 完整性过滤 | 不可信来源的内容进入推理 | 按作者信任度与合并状态设置策略 |
| 网络出口 | Agent 任意外联导致的泄密 | network.allowed 白名单 |
| 威胁检测 | 可疑输出(提示注入痕迹、越权意图) | 拦截或转人工复核的策略 |
| 安全输出 | 未声明的写操作 | safe-outputs 的类型、条数、对象约束 |
「默认安全」有前提:这六层保护的是「按默认模型跑、只用内置工具」的场景。一旦你在 steps 里塞自定义脚本、或用 jobs 挂自定义安全输出,就等于自己在那条链上开了口子——这部分需要单独评审,不能指望默认策略兜住。
Step 1:装扩展、初始化仓库、看清它写了哪些文件
官方有两条安装路线:作为 gh 扩展安装,或跑安装脚本。装完先验证版本,再初始化——init 会往仓库里写五类文件,值得逐一确认再提交。
# 路线 A:作为 gh 扩展安装(可固定 tag 或 SHA)
gh extension install github/gh-aw
gh aw version
# 路线 B:官方安装脚本(装到 ~/.local/share/gh/extensions/gh-aw/)
curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash
# 初始化当前仓库
gh aw init
# 看清楚它动了什么,再提交
git status
gh aw init 的产物包括:把 .lock.yml 标记为生成文件的 .gitattributes、给编码 Agent 用的调度技能 .github/skills/agentic-workflows/SKILL.md、.vscode/settings.json、gh-aw 的 MCP 配置 .github/mcp.json,以及 .github/workflows/copilot-setup-steps.yml。如果你的引擎不是 Copilot,加 --engine claude 可跳过 Copilot 专属产物。
先别急着 push:init 会在仓库里新增 MCP 配置与技能文件,这些东西会改变编码 Agent 在你仓库里的行为。团队仓库建议走 gh aw init --create-pull-request,让别人有机会看一眼再合并。
命令不多,但每个的边界要清楚。下面这张表按「从零到能跑」的顺序排,遇到不确定时先查它,别去猜参数。
| 命令 | 作用 | 本教程用到的地方 |
|---|---|---|
gh aw init | 初始化仓库:gitattributes、调度技能、MCP 配置、setup 工作流 | Step 1 |
gh aw new | 按模板生成一份新的 .md,可用 --engine 注入引擎 | 没有现成模板时 |
gh aw add | 从其他仓库引入工作流,支持 @v1.0.0 固定版本 | 复用社区工作流 |
gh aw compile | 把 .md 编译成 .lock.yml,可加 --strict、--dry-run | Step 3 |
gh aw run | 手动触发,--dry-run 只预览,--push 顺带提交 | Step 6 |
gh aw status / logs | 看启用状态与历史运行,logs 可只要用量或轨迹 | Step 6 |
gh aw fix / upgrade | 跑 codemod 修语法;upgrade 还会重编译全部工作流 | 版本升级后 |
Step 2:写第一份工作流,frontmatter 只留最小集
下面这份文件放在 .github/workflows/issue-triage.md。上半部分是配置,下半部分是自然语言指令;指令里可以直接引用 Actions 上下文,例如 issue 编号。
---
on:
issues:
types: [opened]
permissions:
contents: read
issues: read
engine: copilot
tools:
github:
toolsets: [issues]
bash: ["gh issue view"]
network: defaults
safe-outputs:
add-comment:
max: 1
max-turns: 10
---
# Issue 初诊
读取 issue #${{ github.event.issue.number }}。
1. 用一句话复述用户到底想解决什么问题。
2. 判断它更像 bug、功能请求还是使用问题,并说明依据。
3. 列出你需要用户补充的两条信息。
只输出一段 Markdown 评论,不要复述原文,不要承诺修复时间。
| 字段 | 这份配置里的取值 | 为什么这么写 |
|---|---|---|
on | issues: types: [opened] | 只在新建 issue 时跑,避免评论触发自己形成循环 |
permissions | 只给 contents: read 与 issues: read | Agent 阶段不需要写权限,写走 safe-outputs |
engine | copilot(省略也是默认) | 可换 claude、codex、pi;gemini 已弃用,agy 为实验性 |
tools | 只开 issues 工具集与一条 bash | 工具越少,选错工具的概率越低,攻击面也越小 |
safe-outputs | add-comment: max: 1 | 一次运行最多发一条评论,防刷屏 |
max-turns | 10 | 默认 500,对简单任务太宽松 |
safe-outputs 时,编译器会自动注入一条 create-issue(上限 1 条)。这意味着「我什么都没声明」并不等于「Agent 什么都不能写」,所以要把真正需要的输出类型写清楚。触发条件与权限是最容易写成「能跑但跑错」的两处。先把常见的三组搭配记住,再按业务改:
| 想做的事 | on 写法 | permissions 最小集 |
|---|---|---|
| 新 issue 自动初诊 | issues: types: [opened] | contents: read、issues: read |
| PR 失败后查原因 | workflow_run: workflows: ["CI"], types: [completed] | contents: read、actions: read、pull-requests: read |
| 每天整理一次文档 | schedule: cron: "0 1 * * *" | contents: read(写走安全输出) |
权限只读不代表安全输出能写:两者是两套机制。Agent 阶段的 permissions 决定它能读什么;真正落库的写操作由独立作业带着自己的窄权限执行,来源是你在 safe-outputs 里声明的类型。把 permissions 写成 write 不会让安全输出更宽松,只会让 Agent 本身多出写能力。
等这条单智能体工作流跑顺了,再考虑拆角色:官方文档说明,工作流文件可以在正文之后追加内联子智能体(inline sub-agents)定义,把「查原因」和「写结论」拆成两个角色。本教程不展开它的语法,因为那属于另一页参考,凭印象写层级很容易编译失败——先用单体版本把触发、权限、输出跑通,收益更直接。
Step 3:编译,然后读 lock 文件的头部三件事
编译不只是格式转换,它会在生成前做 schema 校验、表达式白名单检查和 action 固定版本处理。加 --strict 让不合规的写法直接失败,而不是降级放行。
# 编译单条工作流,严格模式
gh aw compile .github/workflows/issue-triage.md --strict
# 只校验、看差异、不落盘(适合 CI 里跑)
gh aw compile --dry-run --strict
# 看生成的产物
Get-Content .github/workflows/issue-triage.lock.yml -TotalCount 25
打开 lock 文件,先看三处:第一行的 # gh-aw-metadata: {...}(含 schema 版本、frontmatter 哈希、strict 与引擎标识);Secrets used 列表(这次运行会碰哪些密钥);Custom actions used 列表(每个外部 action 都钉在具体 SHA 上,后面用注释标版本)。三处都对,才把 .md 与 .lock.yml 一起提交。
最常犯的错:改了 frontmatter 里的 safe-outputs 或 permissions,但忘了重编译,于是线上跑的还是旧权限。判断规则很简单——两个 --- 之间的改动都要重编译;正文改动直接生效。另外 lock 文件第一行是机器可读元数据,不要手工编辑。
Step 4:用 safe-outputs 把「写权限」收窄成一张申请单
默认安全模型是「读、提议、检查、应用」:Agent 在隔离沙箱里读仓库,把要做的写操作作为结构化输出提交;另一个独立作业带着窄权限执行,中间还有内容清洗与威胁检测。你声明的每个输出类型都有自己的上限。
| 输出类型 | 默认上限 | 适用场景 |
|---|---|---|
create-issue | 1 | 把发现的问题立成待办;未声明任何输出时会自动注入 |
add-comment | 1 | 在 issue / PR / discussion 下回一条结论 |
create-pull-request | 1 | 带代码变更提 PR,让人评审后合并 |
add-labels / remove-labels | 5 / 3 | 打标签分诊,可用 allowed 限定可写标签 |
update-issue | 1 | 改写标题/正文,operation 可选 append、replace 等 |
dispatch-workflow | 3 | 触发另一条工作流,串成流水线 |
safe-outputs:
add-comment:
max: 2
required-labels: [needs-triage]
hide-older-comments: true
add-labels:
allowed: [bug, question, area/*]
max: 3
create-pull-request:
max: 1
allowed 与 required-labels 这类约束比「把上限调小」更有用:它们限制的是「能对什么对象做什么」,而不是「能做几次」。给 Agent 的写操作加上对象级前置条件,比事后看日志省力得多。Step 5:预算与频率闸门,别让一次配置失误烧掉一天额度
gh-aw 的额度单位是 AI Credits(AIC)。三层的分工是:max-ai-credits 管一次运行,max-daily-ai-credits 管同一条工作流 24 小时累计,user-rate-limit 管「同一个人能触发几次」。
max-ai-credits: 500 # 单次运行的额度上限(默认 1000)
max-daily-ai-credits: 2000 # 24 小时累计上限,超了直接跳过 Agent
max-turns: 12 # 单次对话轮次上限(默认 500)
user-rate-limit:
max-runs-per-window: 3 # 每个用户每窗口最多 3 次(1-10)
window: 60 # 窗口长度,分钟(默认 60,最大 180)
events: [issues, issue_comment]
ignored-roles: [admin, maintain]
默认值有两处口径不一,务必自己显式写死:首页写「max-daily-ai-credits 默认 5,000 AIC」,而 frontmatter 参考页写该字段「默认禁用」。两处说法冲突时,以你在 gh aw compile 后的实际校验结果为准——把值显式写进 frontmatter,就不会受默认值口径影响。同理,max-turns 默认 500,对绝大多数任务都过于宽松。
还有一处容易忽略的成本来源:--repeat 3 表示在首次之外再跑 3 次,也就是总共 4 次。调提示词时用 gh aw run <name> --dry-run 先看会触发什么,别直接 --repeat 试探。
额度怎么估才不至于拍脑袋?按「轮次 × 单轮成本」粗算:每轮要把工具结果再读一遍,轮次越多,重复上下文越多。所以压成本的顺序是先压轮次,再压工具返回体积,最后才考虑换便宜模型。
| 现象 | 说明问题在哪 | 优先动作 |
|---|---|---|
| 轮次远高于预期 | 任务描述含糊,Agent 在反复试探 | 正文里写清步骤与「不要做什么」,并调低 max-turns |
| 轮次正常但单轮很贵 | 工具返回太大(整文件、整页日志) | 收窄工具集,或让 Agent 先摘要再读细节 |
| 同一条工作流每天烧很多 | 触发条件太宽(例如每次评论都跑) | 加 user-rate-limit,或改成标签/指派触发 |
| 偶发一次特别贵 | 失败重试或长日志导致上下文爆炸 | 用 max-ai-credits 兜住单次上限 |
Step 6:干跑、首跑、复盘,形成闭环
第一次运行建议手动触发,而不是等 issue 事件。把推送与触发拆开看,出问题时容易定位。
# 1) 先干跑:只预览会触发什么,不真的执行
gh aw run issue-triage --dry-run
# 2) 提交并推送,然后手动分发一次
gh aw run issue-triage --push
# 3) 看状态(enabled/disabled、上次结果)
gh aw status
# 4) 复盘这次运行:只要用量与 Agent 轨迹
gh aw logs issue-triage --artifacts usage,agent
# 5) 升级 CLI 或语法踩坑后批量修复
gh aw fix --write
gh aw logs 的 --timeout 是整数分钟(写 --timeout 5),这一点与 audit 用的 Go duration 写法不同,别混。若某次运行失败,把失败链接交给编码 Agent 并附上官方调试提示 https://raw.githubusercontent.com/github/gh-aw/main/debug.md,让它按日志定位,比人肉翻 Actions 页面快。
做到哪一步算成功
| 检查项 | 期望现象 | 对应步骤 |
|---|---|---|
| 扩展可用 | gh aw version 有输出,gh aw init 生成五类文件 | Step 1 |
| 源文件合规 | gh aw compile --strict 通过,无警告降级 | Step 2、3 |
| 产物可审计 | lock 文件首行有 metadata,头部列出 secrets 与固定 action 版本 | Step 3 |
| 写权限受控 | Agent 只产出申请,评论/PR 数量不超过 max | Step 4 |
| 预算生效 | 额度用尽时该次运行跳过 Agent,而不是继续烧 | Step 5 |
| 可复盘 | gh aw logs --artifacts usage,agent 能看到轮次与用量 | Step 6 |
safe-outputs 的类型与对象约束,而不是直接给 Agent 开写权限。常见问题速查
| 现象 | 大概率原因与处理 |
|---|---|
| 改了配置但线上行为没变 | 改的是 frontmatter 却没重编译;跑 gh aw compile <file> 后再提交 lock 文件 |
| 编译报 schema 错误 | 字段名或层级写错;对照 frontmatter 参考逐个核,别凭记忆写 safe_outputs 这种下划线形式 |
| Agent 一上线就开了个 issue | 没有声明 safe-outputs 时自动注入 create-issue;显式写 create-issue: false 或声明真正需要的类型 |
| 运行被跳过,没有日志 | 先看是否触到 max-daily-ai-credits 或 user-rate-limit;两者都会在预算耗尽时跳过 Agent |
用了 staged: true 却没效果 | 该字段只见于首页说明,frontmatter 参考页未收录;先 gh aw compile 校验,别照抄不确定的键 |
| 换引擎后认证失败 | 不同引擎要不同凭据,缺失会导致激活失败;先按 Authentication 文档配好再切 engine |
从别处 gh aw add 的工作流行为异常 | 它的触发条件与安全输出是按原仓库设计的;加 @v1.0.0 固定版本,并逐项改造后再启用 |
| 升级后大量文件被改 | gh aw upgrade 会跑 codemod 并重编译;先 git diff -- .github/workflows/ 审阅再提交 |