装好 gh-aw，写出并编译第一个工作流

第 1 步：检查 GitHub CLI 与登录状态

gh-aw 是 GitHub CLI（gh）的一个扩展。官方要求 gh v2.0.0 以上，并且已经登录，登录时要带上 repo 和 workflow 两个权限范围：

gh --version
gh auth status
gh auth login --scopes repo,workflow

对照结果（gh --version 第一行）：

gh version 2.103.0 (2026-10-21)

gh auth status 显示已登录、且权限范围里有 repo 和 workflow，就可以跳过第三条命令。系统要求是 Linux、macOS，或 Windows 上的 WSL。

第 2 步：安装 gh-aw 扩展

用 GitHub CLI 自带的扩展管理器安装，然后查看版本：

gh extension install github/gh-aw
gh aw version

对照结果：

gh aw version v1.0.1

官方 Quickstart 另给了一条用 curl 下载脚本再交给 bash 执行的安装方式，用于认证出问题时。本课只用 gh extension install：命令来源清楚，升级时运行 gh extension upgrade gh-aw 就行。

第 3 步：在仓库里初始化

在你自己的仓库根目录执行 gh aw init。下面用一个新建的空仓库演示，origin 换成你自己的 GitHub 仓库地址：

mkdir aw-demo && cd aw-demo
git init -b main
git remote add origin https://github.com/your-name/aw-demo.git
gh aw init

对照结果：

→ Welcome to GitHub Agentic Workflows!
This tool will initialize your repository for GitHub Agentic Workflows.
i Setting up repository...
✓ Repository initialized for agentic workflows!
i To create a workflow, see <创建工作流文档链接>
i Or add an example workflow, see <官方示例仓库链接>

最后两行里的链接为了不横向溢出，改写成了中文说明，原文分别是创建工作流文档 https://github.github.com/gh-aw/setup/creating-workflows/ 和官方示例仓库 https://github.com/githubnext/agentics 。

用 git status --short -uall 可以看到它新增了 3 个文件：

想先看一份带全部注释的模板，可以运行 gh aw new daily-hello，它会生成约 140 行、几乎每个字段都有注释的 .github/workflows/daily-hello.md。本课改为手写一个短文件，每一行都会讲到。

第 4 步：写第一个工作流：仓库周报

工作流就是 .github/workflows/ 下的一个 Markdown 文件。两条 --- 之间是 YAML frontmatter，决定什么时候运行、有什么权限、能写什么；下面的正文是写给 AI 代理的自然语言指令。新建 .github/workflows/weekly-summary.md：

---
on:
  schedule: weekly on monday
  workflow_dispatch:
permissions:
  contents: read
  issues: read
  pull-requests: read
safe-outputs:
  create-issue:
    title-prefix: "[周报] "
    max: 1
timeout-minutes: 10
---

# 仓库周报

汇总本仓库过去 7 天的动态：新开和关闭的 Issue、合并的 PR、
主要代码变更。用中文写成一份不超过 300 字的周报，
最后列出最多 3 条下周建议。只根据仓库里能查到的信息写，
不要编造。完成后用 create-issue 发成一个 Issue。

逐项说明：

• schedule: weekly on monday 是 gh-aw 的「模糊日程」写法，编译时会换算成具体的 cron 时间。workflow_dispatch 让你可以手动触发。
• permissions 全部是 read。代理在运行时只能读仓库，不能直接写。
• safe-outputs.create-issue 声明这个工作流「允许产出」一个 Issue，标题自动加 [周报] 前缀，最多 1 个。真正创建 Issue 的是后面一个单独的作业，代理本身拿不到写权限。
• timeout-minutes 限制代理步骤最长运行 10 分钟。
• 没写 engine: 时默认用 GitHub Copilot。第 3 课会讲怎么换成 Claude、Codex 或 Gemini。

第 5 步：编译并看懂 .lock.yml

GitHub Actions 只认 YAML，所以要把 Markdown 编译成 .lock.yml：

gh aw compile weekly-summary

对照结果（省略开头一条关于 copilot-requests 的 info 提示）：

✓ .github/workflows/weekly-summary.md (135.1 KB)
✓ Compiled 1 workflow: 1 succeeded, 0 warnings

实测说明：编译时 gh-aw 要通过 GitHub API 把每个 action 解析成完整的 40 位 commit SHA。本机 gh 没有登录，直接编译报了 5 条 CTR-002: [action-pin] 错误，所以实测时额外加了 --action-mode action --action-tag <完整SHA>。在第 1 步登录过的电脑上直接运行 gh aw compile 即可。

如果没有设置 origin 远程，还会多一条警告：Fuzzy schedule scattering without repository context。模糊日程会按仓库名把运行时间打散，避免很多仓库挤在同一分钟触发，所以需要知道仓库是哪个。

看看生成了什么：

grep -n 'cron' .github/workflows/weekly-summary.lock.yml
grep -nE '^  [a-z_]+:$' .github/workflows/weekly-summary.lock.yml

对照结果（cron 的具体分钟和小时按仓库名生成，你的会不一样）：

54:    - cron: "7 5 * * 1"  # Friendly format: weekly on monday (scattered)
53:  schedule:
55:  workflow_dispatch:
81:  activation:
411:  agent:
1236:  conclusion:
1589:  detection:
1941:  safe_outputs:

20 来行的 Markdown 编译出了 2000 多行 YAML。几个主要作业的分工如下：

最后把两个文件一起提交。官方特别说明：.md 和 .lock.yml 都要提交，Actions 执行的是 lock 文件。

git add .gitattributes .github .vscode
git commit -m "Add weekly summary agentic workflow"

以后改了 frontmatter 就要重新运行 gh aw compile。开发时可以用 gh aw compile --watch，文件一保存就自动重编。

小结

• gh-aw 用 gh extension install github/gh-aw 安装，gh aw init 初始化仓库。
• 工作流由「frontmatter 配置 + Markdown 指令」组成，编译后得到 .lock.yml。
• 代理只有读权限，写操作统一通过 safe-outputs 声明，由独立作业执行。
• 下一课写一个按事件触发的 Issue 分诊工作流，并试一下编译器会拦下哪些不安全的写法。