企业官网建设流程全解析

GitHub Agentic Workflows（简称 gh-aw）是一种"用 Markdown 定义 AI 自动化"的新范式：不再用 YAML 和脚本描述流水线，而是用一个 Markdown 文件——YAML 头部声明触发条件、权限与护栏，正文用自然语言给 AI 下达任务——让 AI 智能体在 GitHub 上自动分诊 Issue、修 Bug、更新文档。开源项目agentics则是一份开箱即用的 GitHub Agentic Workflows 样本库，收录了 50+ 个可直接安装到仓库的 AI 自动化工作流，是理解这套 Markdown 驱动 AI 自动化机制的最佳入口。

📖 GitHub Agentic Workflows 是什么？

一句话概括：它是 GitHub Actions 的"AI 升级版"。传统 Actions 用 YAML 编排固定的构建步骤，而 Agentic Workflows 把"执行者"换成了一个具备工具调用能力的 AI 智能体——你只需要告诉它"做什么、什么边界内做"，具体怎么干由它自主决策。

🧰 agentics：一份 AI 自动化工作流的"样板房"

agentics 的定位非常直接：A sample pack of GitHub Agentic Workflows!仓库中每个工作流都遵循统一结构——可执行源码放在 workflows/ 目录，配套说明文档放在 docs/ 目录，完整清单见 README.md。按用途大致分为：

🔍 底层原理：一个 Markdown 工作流如何跑起来

1️⃣ 文件结构：YAML 头部 + 自然语言正文

以 workflows/issue-triage.md 为例，文件被一条---分成两半：

on: issues: types: [opened, reopened] reaction: eyes

头部声明触发时机（Issue 创建或重新打开时）、所需权限、可用工具与输出护栏；而头部下方的正文就是一篇写给 AI 的"岗位说明书"：先收集上下文、再评估信息完整性、接着分类打标签、最后查找重复项并发布结构化分诊报告。AI 读取后按自然语言指令自主执行，不需要你写一行执行逻辑。

定时触发同理，workflows/repo-assist.md 声明每 12 小时自动运行一次，同时支持手动派发、/repo-assist斜杠命令和"点眼睛表情"触发——同一个 Markdown 文件，多种唤醒方式。

2️⃣ safe-outputs：给 AI 套上"缰绳"

这套机制的安全核心不是"希望 AI 别乱来"，而是safe-outputs字段——声明式地规定 AI 能写回什么、上限多少。例如 Issue Triage 被限制为最多打 4 个标签、最多发 1 条评论（workflows/issue-triage.md），标签还必须来自白名单。

Repo Assist 的护栏更严格（workflows/repo-assist.md）：

• 每次运行最多创建 4 个草稿PR，且标题必须带[repo-assist]前缀；
• 触碰CHANGELOG.md、README.md等受保护文件时，自动转为"请求人工 Review"；
• 全程只读仓库，从不合并 PR——合并权永远留给人类维护者。

3️⃣ gh aw compile：Markdown 就是"源代码"

编辑完 Markdown 后运行gh aw compile，编译器会把它生成一份可直接执行的.lock.yml（GitHub Actions 工作流），例如 .github/workflows/import-workflow.md 对应的 import-workflow.lock.yml。锁文件做了三件关键事：

1. 记录哈希：文件头写入frontmatter_hash、body_hash与编译器版本，任何 Markdown 改动都会让哈希失配、触发重新编译；
2. 全量锁定：所有 actions 与容器镜像都固定到具体 SHA/摘要，杜绝供应链漂移；
3. 统一索引：项目级锁文件 .github/aw/actions-lock.json 集中登记所有引用的 actions。

所以正确的理解是：Markdown 是源代码，.lock.yml是编译产物——这正是"Markdown 驱动"的字面含义。Makefile 还封装了make compile一步完成根目录与workflows/目录的编译。

4️⃣ 运行时：防火墙沙箱 + 声明式工具集

AI 智能体并不直接跑在宿主机上，而是运行在 gh-aw 的防火墙容器中（agent、api-proxy、squid 三个镜像协作），网络出口受network:白名单约束。它能用哪些工具，完全取决于tools:字段的声明，例如 workflows/plan.md 只开放了bash的只读命令（cat、grep、head…）和 GitHub 工具集。

更妙的是repo-memory：workflows/repo-assist.md 声明了一个带JSON Schema 校验的记忆分支memory/repo-assist-memory，让工作流把notes.json（处理过的 Issue 游标、修复记录、优先级队列）持久化到仓库里——下一次运行时先读记忆再干活，从而跨运行保持状态、避免重复劳动。这是"AI 自动化"区别于"一次性脚本"的关键能力。

🧩 组合复用：Shared Workflow Fragments

agentics 把公共能力抽成了共享片段，其他工作流用imports: [shared/name.md]一行引入：

• MCP 服务器：arxiv.md（检索论文）、markitdown.md（PDF/Word/PPT 转 Markdown）、mcp/microsoft-docs.md；
• 工具安装：ffmpeg.md（音视频处理）、sq.md（用类 jq 语法查询 CSV/Excel/SQL）；
• 输出规范：reporting.md 要求报告中所有 workflow run ID 必须渲染为可点击链接，formatting.md 统一了报告的章节结构。

这相当于工作流世界的"npm 包管理"——声明依赖、统一版本、按需引入。

🏆 深度案例：Repo Assist 的一天

workflows/repo-assist.md 是仓库里最完整的样例，值得拆解：

1. 确定性前置步骤（非 AI）：先拉取 Issue/PR 数据，按当前仓库状态计算 10 类任务（打标签、调查、修复、依赖升级、性能、测试……）的加权概率，随机但可复现地挑出 3 个任务；
2. AI 执行：智能体读取任务选择结果与记忆文件，执行调查、修 Bug、建草稿 PR、更新月度活动汇总 Issue；
3. 护栏收尾：所有产出受safe-outputs上限约束，60 分钟超时自动终止，concurrency防止定时任务互相踩踏。

这一设计体现了 agentics 的核心理念：AI 负责推进工作，人类保留最终决策权。

🚀 如何快速上手 GitHub Agentic Workflows

三步把 agentics 中的工作流装进你的仓库：

# 1. 安装 gh aw 命令行扩展 gh extension install github/gh-aw # 2. 通过 add-wizard 从 agentics 一键安装（以 Issue Triage 为例） gh aw add-wizard githubnext/agentics/issue-triage # 3. 本地开发/修改后重新编译 gh aw compile

想浏览全部样本，可把 agentics 克隆到本地：

git clone https://gitcode.com/gh_mirrors/ag/agentics

后续升级用gh aw upgrade（升级引擎）+gh aw update（更新已安装的工作流）即可，它会自动应用 codemod 并重新编译所有工作流。

💡 小结

• Markdown 即工作流：YAML 头部管"何时触发、能用什么、边界在哪"，自然语言正文管"做什么"，gh aw compile负责把二者编译成锁定版本的可执行 Actions；
• 护栏先于信任：safe-outputs、最小权限、网络白名单、受保护文件与草稿 PR，让 AI 自动化在生产仓库中"可控地聪明"；
• agentics 是最好的教材：50+ 个按场景分类的样本工作流 + 共享片段机制，覆盖了从 Issue 分诊到安全扫描的完整 AI 自动化版图。如果你正在评估 AI 自动化如何落地，从 docs/issue-triage.md 这类轻量工作流起步，是成本最低的探索路径。