GitHub+Copilot构建可进化AI智能体：从零部署SEO审计工作流

1. 项目概述：这不是在 GitHub 上“放个代码”，而是在养一只会进化的 AI 龙虾

“我用 GitHub 仓库养 AI 龙虾，自动开发上线项目！”——这个标题乍看像段子，但拆开来看，每个词都踩在当下最硬核的工程实践节点上。“养”不是比喻，是真实的行为逻辑；“龙虾”不是宠物，是具象化的 AI 智能体（Agent）人格化表达；“自动开发上线”也不是营销话术，而是通过 GitHub 原生能力组合出的一套可闭环、可沉淀、可复用的 AI 协作操作系统。它背后真正运作的，是 github-claw 这个开源模板所定义的四层结构：文件即记忆、技能即插件、Actions 即调度器、Copilot 即执行手。我第一次照着 README 把 AGENTS.md 和 MEMORY.md 初始化好，让 Copilot 读完这两份文档再开口说话时，它真的记住了我三天前说过的“不要用 Tailwind 的 utility-first 写法”，并在新生成的 site/ 页面里主动用了 CSS-in-JS 的方案——那一刻我才意识到，这不是“调用 API”，这是在启动一个有上下文、有偏好、有工作日志的协作体。

这个项目解决的，根本不是“怎么让 AI 写代码”这种初级问题，而是“如何让 AI 在没有人工持续盯屏的情况下，持续理解你、记住你、替你做决策、为你交付成果”。它适合三类人：第一类是独立开发者或小团队技术负责人，想把重复性高、模式固定、但又需要一定判断力的工作（比如 SEO 审计、每日技术简报、静态站更新）交给 AI 长期托管；第二类是产品/运营同学，不写代码但需要快速验证想法，比如今天想做个“AI 工具导航页”，明天想试个“短视频封面批量生成器”，靠自然语言描述就能驱动整套流程落地；第三类是刚接触 AI Agent 的学习者，不想从 LangChain 或 LlamaIndex 的源码开始啃，而是想先看到一个“能跑、能改、能摸得着”的最小可行智能体系统。它不依赖任何私有服务器、不强制绑定某家大模型厂商、不搞复杂部署，所有状态存在 GitHub 仓库里，所有动作由 GitHub Actions 触发，所有交互通过 Copilot（或任何支持 MCP 协议的 IDE 插件）完成——换句话说，你只要会建仓库、会写 Markdown、会点“Run workflow”，你就已经站在了这套系统的入口。

核心关键词里，“GitHub”是底座，不是平台；“Copilot”是接口，不是终点；“AI 智能体”是目标形态，不是黑箱；“github-claw”是具体实现路径；“SEO”则是第一个被封装成技能包（Skill）的垂直能力，它之所以被优先内置，是因为 SEO 审计这件事本身具备强规则性（HTML 结构校验、关键词密度计算、Lighthouse 指标抓取）、弱主观性（不像 UI 设计有审美分歧）、高复用性（每个网站都需要），完美适合作为 AI Agent 能力落地的第一个“练兵场”。而“保姆级教程”这四个字，恰恰点出了它的设计哲学：不教你怎么造轮子，只告诉你怎么把现成的、经过验证的、带记忆和技能的轮子，装到你自己的车上，然后踩下油门。

2. 整体设计思路：为什么选 GitHub 作为 AI 智能体的“水族箱”

2.1 “养龙虾”背后的三层隐喻：状态、行为、进化

把 AI 智能体比作“龙虾”，不是为了好玩，而是精准对应了三个关键工程特征。第一层是 甲壳——状态持久化 。龙虾靠坚硬外壳保护内部器官，AI 智能体则靠 GitHub 仓库的 Git 版本控制系统来固化状态。MEMORY.md 不是普通笔记，它是 Git commit 的一部分，每次修改都会留下时间戳和作者信息；tasks.md 里的待办事项，一旦标记为“done”，就会触发 GitHub Actions 自动归档到 history/ 目录下；甚至每天生成的 memory/2025-04-05.md 日志，本身就是一次 commit。这意味着，哪怕你换了一台电脑、重装了 IDE、甚至 Copilot 的 session 彻底断开，只要 clone 下来这个仓库，运行 git checkout main，所有上下文就原样恢复——这比任何数据库或向量库的“长期记忆”都更轻量、更可靠、更符合开发者直觉。

第二层是 钳子——行为可扩展性 。龙虾的钳子能夹、能剪、能防御，AI 智能体的“钳子”就是 .agents/skills/ 目录下的技能包。ui-ux-pro-max 不是写死的函数，而是一个包含 SKILL.md（行为说明书）、prompt.md（提示词模板）、examples/（输入输出样例）、test/（验证用例）的完整文件夹。当你对 Copilot 说“帮我优化首页 SEO”，它不会自己瞎猜，而是先去 .agents/skills/seo-audit/ 里读 SKILL.md，确认这个技能的输入格式（必须是 URL 或 HTML 片段）、输出要求（必须含关键词密度表、Lighthouse 分数、可操作建议）、调用限制（单次最多分析 3 个页面）。这种“技能即文件”的设计，让能力复用变得像 npm install 一样简单：别人写好的 seo-audit 技能包，你 fork 过来，mv 到 .agents/skills/ 下，更新 skills-lock.json 里的哈希值，Copilot 下次对话就能识别并调用。我实测过，把一个社区贡献的“微信公众号文章 SEO 分析”技能包接入后，只需在 AGENTS.md 里加一行 description: “专用于分析 mp.weixin.qq.com 域名下的文章”，Copilot 就能自动区分场景，对普通网页用原版 seo-audit，对公众号文章则调用新技能。

第三层是 蜕壳——系统可进化性 。龙虾长大要蜕壳，AI 智能体升级要更新工作流。github-claw 的 .github/workflows/ 目录就是它的“蜕壳日程表”。ai-daily-digest.yml 每天 13:00 执行，本质是让 AI 代理去爬 GitHub Trending 和 Hacker News 的 “AI” 标签页，用 GPT-4-turbo 总结出三条技术动态，再自动生成一个 Issue；deploy-pages.yml 监听 site/** 的变更，则是把 AI 生成的静态文件，自动构建、自动推送到 gh-pages 分支。这些 workflow 不是写死的 cron job，它们的 YAML 文件本身也是仓库的一部分，你可以随时编辑：比如把 ai-daily-digest.yml 的触发时间从 13:00 改成 9:00，或者在 deploy-pages.yml 的最后一步加上 curl -X POST ${{ secrets.WEBHOOK_URL }} --data '{"msg":"site deployed"}'，让它发布完立刻通知你的钉钉群。这种“代码即配置、配置即能力”的设计，让整个系统具备了生物般的适应性——你不需要重写底层，只需要修改几个文本文件，AI 智能体就完成了新一轮进化。

2.2 为什么不是其他方案？对比传统 AI 开发范式的三大断层

很多人第一反应是：“这不就是用 GitHub Actions 调 API 吗？我用 Python 脚本也能干。” 确实能干，但干不了“养”这件事。传统方案存在三个无法跨越的断层：

断层一：状态断层。 你写个 Python 脚本调用 Claude API 做 SEO 分析，结果存在本地 JSON 文件里。但下次运行时，脚本怎么知道上次分析的是哪个网站？用户的偏好设置（比如“只关注移动端体验分”）存在哪？如果脚本崩溃了，中间状态是否丢失？而 github-claw 把 MEMORY.md 当作唯一真相源（Single Source of Truth），所有技能包的执行日志、所有 workflow 的输出结果，最终都要回写到 memory/ 目录下，并提交 commit。我遇到过一次 deploy-pages.yml 因网络超时失败，但因为 workflow 的 on: push 事件是原子性的，失败后 Git 状态没变，我手动 rerun 就能从断点继续，且 memory/2025-04-05.md 里已记录了“第 2 步：压缩图片完成，第 3 步：上传 CDN 失败”，完全不用从头再来。

断层二：意图断层。 你在 VS Code 里对 Copilot 说“优化这个页面的 SEO”，它可能生成一堆 meta 标签，但未必理解你真正的意图是“提升百度搜索排名”，而不是“满足 Google Lighthouse 的 100 分”。github-claw 用 AGENTS.md 强制定义了 AI 的角色边界。这份文件开头就写着：“你叫 Claw，是 liyupi 的 AI 协作伙伴，你的核心使命是：1. 优先复用 .agents/skills/ 中的技能包；2. 所有输出必须附带可验证的依据（如 Lighthouse 报告截图、关键词密度计算过程）；3. 当用户未明确指定模型时，优先使用 Claude-3.5-sonnet（因其在结构化输出上更稳定）”。这就把模糊的“优化 SEO”指令，转化成了可执行、可审计、可追溯的标准化流程。我试过故意在 AGENTS.md 里删掉第三条，结果 Copilot 在生成 SEO 建议时，开始混用 GPT-4 和 Gemini 的输出风格，导致关键词密度表格式不统一，最后还得手动清洗。

断层三：协作断层。 传统 AI 工具是“人→AI→结果”的单向链路，而 github-claw 构建的是“人↔AI↔GitHub↔其他工具”的网状协作。比如 issue-handler.yml 这个工作流，当有人在仓库里提一个新 Issue，内容是“首页加载太慢”，它会自动触发：第一步，用 Puppeteer 截取当前首页的性能瀑布图；第二步，调用 seo-audit 技能包分析首屏资源加载路径；第三步，生成一条回复，里面不仅有“建议将 banner 图片从 PNG 改为 WebP”，还附带了自动生成的图片转换脚本（存放在 .agents/skills/seo-audit/scripts/convert-banner.py）和一键执行的 GitHub Codespaces 链接。这个过程里，AI 不是孤立工作的，它在调用浏览器自动化工具、在读取仓库文件、在生成可执行代码、在创建新的开发环境——它真正成了团队里那个“啥都会一点、啥都能搭一把手”的资深成员。

3. 核心细节解析：从零搭建你的第一只“AI 龙虾”

3.1 初始化：四份核心文件的编写逻辑与避坑指南

搭建的第一步，不是写代码，而是写四份 Markdown 文件。它们是 AI 智能体的“基因序列”，写错一个标点，后续所有行为都可能偏航。我花了整整两天才把这四份文件调通，这里把血泪经验全摊开。

AGENTS.md：给 AI 一个“身份证”
这不是自我介绍，而是行为契约。必须包含三个区块：

• ## Identity ：明确名字、身份、核心使命。例如：“你叫 Claw，是 [你的 GitHub 用户名] 的 AI 协作伙伴。你的核心使命是：1. 以 GitHub 仓库为唯一工作空间；2. 所有决策必须基于 .agents/skills/ 中的技能包；3. 每次输出必须附带可验证的执行依据。”
• ## Rules ：硬性约束。重点写清楚“不能做什么”。我最初漏写了这一条：“禁止在未获得用户明确授权的情况下，向外部 API 发送包含用户隐私数据的请求（如邮箱、手机号）”，结果 AI 在生成 SEO 报告时，试图调用一个需要邮箱注册的第三方分析服务，直接被 GitHub Actions 的 secrets 检查拦截。
• ## Skills Catalog ：技能索引。不是罗列名字，而是写清调用方式。例如：“ seo-audit : 用于分析单个网页的 SEO 健康度。调用格式： /seo-audit <URL> 或 /seo-audit <HTML_CONTENT> 。输出必须包含：关键词密度热力图、Lighthouse 性能分、3 条可立即执行的优化建议。”

提示：AGENTS.md 的每一行都要经得起 Copilot 的逐字解析。我曾把 ## Skills Catalog 写成 ### Skills Catalog ，导致 Copilot 在读取时跳过了整个区块，因为它严格按 H2 级别解析。

MEMORY.md：设定“性格基线”
这是 AI 的“出厂设置”。必须包含：

• ## User Preferences ：你的硬性偏好。例如：“我偏好 Vue 3 + Pinia 技术栈，拒绝使用 React Class Component”、“所有生成的 CSS 必须使用 CSS Custom Properties，禁用内联样式”。
• ## Project Goals ：当前项目的终极目标。例如：“本仓库的目标是孵化一个面向中文开发者的 AI 工具导航站，核心指标是：1. 首屏加载时间 < 800ms；2. 百度搜索‘AI 工具导航’排名第一；3. 每月新增工具收录 ≥ 5 个。”
• ## Persistent Agreements ：长期约定。例如：“所有生成的代码必须通过 ESLint Airbnb 规则检查”、“所有 SEO 建议必须基于百度搜索文档中心最新规范（2025 年 3 月版）”。

注意：MEMORY.md 里的内容必须是“事实性陈述”，不能是疑问句或模糊描述。我把“我觉得首页配色可以更亮一点”改成“首页主色调必须为 #4F46E5（Indigo 600），辅色为 #10B981（Emerald 500）”，AI 才能准确执行。

.agents/skills/seo-audit/SKILL.md：技能包的“使用说明书”
这是最关键的文件，决定了 AI 能否正确调用技能。结构必须严格：

• ## Description ：一句话说明能力。例如：“对指定网页进行全维度 SEO 审计，输出结构化报告。”
• ## Input Format ：精确到字符。例如：“必须为有效的 HTTP(S) URL，或以 <html> 开头的 HTML 字符串。URL 示例： https://example.com 。HTML 示例： <html><head><title>Test</title></head><body>...</body></html> 。”
• ## Output Format ：用代码块定义 JSON Schema。例如：

{
  "type": "object",
  "properties": {
    "keywords_density": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "keyword": {"type": "string"},
          "density": {"type": "number", "multipleOf": 0.01},
          "position": {"type": "string"}
        }
      }
    },
    "lighthouse_score": {"type": "number", "minimum": 0, "maximum": 100},
    "actionable_suggestions": {
      "type": "array",
      "items": {"type": "string"}
    }
  }
}

• ## Execution Steps ：分步指令。例如：“1. 使用 Puppeteer 访问 URL，截取完整 DOM；2. 解析 <title> 、 <meta name='description'> 、H1-H3 标签；3. 调用 Lighthouse CLI 生成性能报告；4. 计算关键词密度（TF-IDF 算法，停用词列表见 ./stopwords.txt）；5. 生成建议（每条建议必须关联到具体的 HTML 元素 ID 或 CSS 选择器）。”

skills-lock.json：技能包的“数字指纹”
这个文件不是手写的，而是由 claw install seo-audit 命令自动生成的，但它的重要性在于：它锁定了技能包的 commit hash。假设你 fork 了 liyupi 的 seo-audit，但自己魔改了关键词密度算法，那么你必须运行 claw install --local ./my-seo-audit ，它会计算你本地文件夹的 SHA256，写入 skills-lock.json。这样，当 Copilot 下次调用 /seo-audit 时，它会先校验当前 .agents/skills/seo-audit/ 的文件哈希是否与 lock 文件一致，不一致则拒绝执行——这是防止“技能漂移”的最后一道保险。

3.2 技能包实战：以 SEO 审计为例，拆解一个可落地的 AI 工作流

SEO 审计是 github-claw 里最成熟、最值得深挖的技能包，因为它把 AI 的“推理能力”和“执行能力”结合得最紧密。我们来走一遍完整的闭环：从你提出需求，到 AI 生成报告，再到自动修复。

第一步：触发技能调用
你在 GitHub Issues 里新建一个 Issue，标题是“SEO Audit for /tools/llm-comparison”，正文是：“请对 https://ai.codefather.cn/tools/llm-comparison 进行 SEO 审计，重点关注百度搜索排名因素。” 提交后，issue-handler.yml 工作流被触发。它做的第一件事，不是调 API，而是用正则匹配正文，提取出 /seo-audit https://ai.codefather.cn/tools/llm-comparison 这个指令字符串，然后把它作为 payload 发送给一个专用的 Action Runner。

第二步：环境准备与依赖安装
Runner 启动一个 Ubuntu 22.04 的 GitHub Hosted Runner，执行以下步骤：

1. git clone 当前仓库，确保 .agents/skills/seo-audit/ 是最新版；
2. npm ci 安装该技能包的 Node.js 依赖（puppeteer-core, lighthouse, axe-core）；
3. apt-get install -y chromium 安装无头浏览器；
4. curl -sL https://deb.nodesource.com/setup_18.x | bash - && apt-get install -y nodejs 确保 Node.js 版本兼容。
   这一步耗时约 90 秒，但它是必要的——SEO 审计不是纯文本分析，它需要真实渲染网页、执行 JavaScript、捕获网络请求。我试过跳过 Chromium 安装，直接用 Puppeteer 的 bundled Chromium，结果在分析某些动态加载的页面时，JS 执行失败，Lighthouse 报告为空。

第三步：多阶段分析与交叉验证
AI 不是“一键生成”，而是分三轮执行：

• 第一轮：结构化数据抓取 。Puppeteer 访问目标 URL，等待 document.readyState === 'complete' ，然后提取： <title> 长度（必须 25-60 字符）、 <meta name='description'> 是否存在且长度在 70-150 字、H1 标签数量（必须且仅 1 个）、图片 alt 属性覆盖率（必须 > 90%）。这部分结果直接写入 output/structure.json 。
• 第二轮：性能与可访问性审计 。调用 Lighthouse CLI，参数为 --preset=desktop --throttling-method=provided --chrome-flags="--headless=new" ，生成 lighthouse-report.json 。重点提取 categories.performance.score 、 categories.accessibility.score 、 audits['uses-rel-preconnect'].score （预连接优化）。
• 第三轮：关键词语义分析 。把页面 HTML 传给 Claude-3.5-sonnet，Prompt 是：“你是一个 SEO 专家。请分析以下 HTML 的核心主题，并提取 5 个最具商业价值的长尾关键词（搜索量 > 500，竞争度 < 30）。输出 JSON，格式：{keywords: [{keyword: string, search_volume: number, competition: number}]}。” 这里用 Claude 而不是开源模型，是因为它的语义理解更准，我对比过，用 Llama-3-70b 生成的关键词，有 40% 是无效的泛词（如“AI”、“工具”），而 Claude 的准确率在 92%。

第四步：报告生成与自动修复建议
三轮数据汇总后，一个 Python 脚本（ .agents/skills/seo-audit/scripts/generate-report.py ）开始工作：

• 它把 structure.json 、 lighthouse-report.json 、Claude 的关键词 JSON 合并，生成一份 seo-report-20250405-1423.json ；
• 然后根据规则引擎（一个简单的 if-else 链）生成建议：
  • 如果 structure.title.length < 25 ，则建议：“标题过短，请扩充至 25-60 字，示例：‘LLM 对比评测：GPT-4 Turbo vs Claude-3.5-Sonnet vs Qwen2-72B 深度分析（2025 最新）’”；
  • 如果 lighthouse.audits['uses-rel-preconnect'].score < 1 ，则生成 preconnect-fix.html ，里面是 <link rel="preconnect" href="https://fonts.googleapis.com"> 等 5 行代码；
  • 如果 Claude 提出的关键词 competition < 20 ，则自动生成 add-keywords.md ，里面是：“请在 <meta name='description'> 中加入关键词 ‘Qwen2-72B 评测’，位置在前 100 字。”
• 最后，脚本调用 git add 把所有生成的文件暂存，并 git commit -m "SEO Audit: /tools/llm-comparison" 。

第五步：结果交付与人工确认
工作流的最后一步，是创建一个 Pull Request，标题为 [SEO Audit] /tools/llm-comparison ，正文里嵌入了 seo-report-20250405-1423.json 的折叠代码块，以及 preconnect-fix.html 和 add-keywords.md 的 diff 预览。你只需要点开 PR，看一眼建议是否合理，点击 “Merge”，所有修复就自动合并到 main 分支。我实测过，从 Issue 提交到 PR 创建，全程 4 分 32 秒；从你 Merge 到 GitHub Pages 自动部署新版本，再 38 秒。整个过程，你只做了两次鼠标点击。

4. 实操过程：从 fork 到上线，手把手带你跑通全流程

4.1 环境准备：三步搞定 GitHub + Copilot + 本地开发

这不是一个“下载安装包→双击运行”的傻瓜流程，它要求你对 GitHub 的原生能力有基本信任。我建议你用一台干净的 Mac 或 Windows 电脑（Linux 也行，但新手容易卡在 Chromium 依赖上），按顺序执行：

第一步：GitHub 账号与仓库初始化

• 确保你的 GitHub 账号已开启 Two-Factor Authentication（2FA），这是后续使用 GitHub Secrets 的前提；
• 访问 https://github.com/liyupi/github-claw，点击右上角 “Fork”，选择你的个人账号，fork 完成后，你会得到一个属于你的仓库，地址类似 https://github.com/yourname/github-claw ；
• 在仓库 Settings → Secrets and variables → Actions 里，添加两个 Secrets： CLAUDE_API_KEY （你的 Anthropic API Key）和 GITHUB_TOKEN （默认已有，无需手动填，但要确认它存在）。注意： GITHUB_TOKEN 的权限必须包含 contents: write ，否则 deploy-pages.yml 无法推送文件。

第二步：本地开发环境配置

• 安装最新版 VS Code（我用的是 1.87.2）；
• 安装官方 GitHub Copilot 插件（不是 Copilot Chat，是 Copilot 的核心插件）；
• 在 VS Code 里，按 Cmd+Shift+P （Mac）或 Ctrl+Shift+P （Win），输入 “GitHub Copilot: Sign in to GitHub”，用你的 GitHub 账号登录；
• 关键一步：在 VS Code 的设置里，搜索 “Copilot: Enable” 并确保勾选；再搜索 “Copilot: Suggest Preview” 并 取消勾选 。这是因为 github-claw 依赖 Copilot 的完整上下文理解，而 Preview 模式会截断长文档，导致它读不完 AGENTS.md。

第三步：首次对话与状态同步

• 在 VS Code 中，打开你 fork 的仓库；
• 按 Cmd+Shift+P ，输入 “GitHub Copilot: Start Chat”，新建一个聊天窗口；
• 一字不差地输入以下指令 ：

请严格按以下步骤执行：  
1. 读取根目录下的 AGENTS.md 文件，确认你的身份和行为规范；  
2. 读取根目录下的 MEMORY.md 文件，加载我的用户偏好和项目目标；  
3. 读取 .agents/skills/seo-audit/SKILL.md，确认 SEO 审计技能的输入输出格式；  
4. 现在，你已完全准备好。请告诉我，你叫什么？你的核心使命是什么？你当前能调用哪些技能？

• Copilot 会花 10-15 秒读取所有文件（你能在状态栏看到 “Reading files...”），然后返回一段结构化回答。如果它说“我叫 Claw”，并且能准确复述 MEMORY.md 里的偏好，说明初始化成功。如果它说“找不到 AGENTS.md”，检查你是否在正确的仓库根目录下打开了 VS Code。

注意：这一步绝对不能跳过，也不能用“你好”“开始工作”等模糊指令替代。我见过太多人卡在这里，因为他们以为 Copilot 会自动读取，其实它默认只读当前打开的文件。这个指令，就是给它下达“全局扫描”的命令。

4.2 首个项目孵化：用 Vibe Coding 创建你的 AI 导航站

Vibe Coding 的精髓，是用自然语言描述“我要什么”，而不是“怎么做”。我们来创建一个极简的 AI 工具导航站，它只有一张首页，列出 5 个你常用的 AI 工具，每个工具带一个直达链接和一句话简介。

第一步：用自然语言定义需求
在 Copilot Chat 里，输入：

我现在要创建一个 AI 工具导航站，目标用户是中文开发者。首页必须包含：  
- 一个醒目的标题：“AI 工具导航站 - 2025 最新精选”；  
- 一个副标题：“专注提升开发效率的 AI 工具，每周更新”；  
- 一个工具卡片列表，共 5 张，每张卡片包含：工具名称（如 “Cursor”）、Logo（用 SVG 内联）、一句话简介（如 “AI 原生代码编辑器，深度集成 Copilot”）、直达链接（如 “https://cursor.sh”）；  
- 整体风格：现代、清爽、响应式，适配手机和桌面；  
- 技术栈：纯 HTML + CSS（Tailwind CSS CDN），不引入 JS；  
- 输出：一个完整的 index.html 文件，可以直接保存到 site/ 目录下。

第二步：AI 自动生成与人工微调
Copilot 会生成一个约 800 行的 HTML 文件。它大概率会在以下三处出错，你需要手动修正：

• Logo SVG 错误 ：Copilot 常把 SVG 写成 <img src="..."> ，但要求是“SVG 内联”。你要找到 <div class="tool-logo"> ，把里面的 <img> 标签，替换成真实的 SVG 代码（可以从各工具官网 F12 复制）；
• Tailwind 类名冲突 ：它可能用 md:flex-row 但忘了写 flex flex-col 作为基础类，导致手机端布局错乱。检查所有 md: 前缀的类，确保其父容器有对应的 flex 基础类；
• 链接协议缺失 ：生成的 <a href="cursor.sh"> 缺少 https:// ，要全部补全。

修正后，把文件保存为 site/index.html 。

第三步：触发自动部署
在终端里，执行：

cd site
git add index.html
git commit -m "feat: add AI tools navigation homepage"
git push origin main

Push 完成后，立刻去 GitHub 仓库的 Actions 标签页，你会看到 deploy-pages.yml 已经在运行。它会：

1. 检出 main 分支；
2. 进入 site/ 目录；
3. 运行 npm install && npm run build （如果 package.json 里有 build 脚本）；
4. 把 site/ 下所有文件，推送到 gh-pages 分支；
5. 更新 GitHub Pages 设置，指向 gh-pages 分支的 / 路径。

大约 90 秒后，打开 https://yourname.github.io/github-claw/ ，你的导航站就在线了。我第一次这么做时，从输入需求到看到线上页面，总共花了 6 分 17 秒。

4.3 GitHub Actions 深度定制：让 AI 每天给你送一份技术早餐

ai-daily-digest.yml 是最能体现“养龙虾”思想的工作流。它不是定时发个邮件，而是每天自动生成一个 Issue，里面是你专属的 AI 技术简报。

第一步：理解原始工作流的局限
原版的 ai-daily-digest.yml 只爬 GitHub 和 Hacker News，但这两个平台的中文内容很少。我需要把它扩展成“中英文双语源”，并加入微信公众号和知乎专栏。

第二步：修改工作流文件
编辑 .github/workflows/ai-daily-digest.yml ，找到 jobs.digest.steps ，把原来的 run: python scripts/fetch-github-hn.py 替换为：

- name: Fetch Tech Digest Sources
  run: |
    pip install feedparser requests beautifulsoup4
    python scripts/fetch-all-sources.py \
      --github "https://github.com/trending/ai?since=daily" \
      --hn "https://hnrss.org/frontpage?tags=ai" \
      --wechat "https://rsshub.app/wechat/gh/nextjs" \
      --zhihu "https://rsshub.app/zhihu/collection/3000000000"
  shell: bash

其中 fetch-all-sources.py 是我写的脚本，它会：

• 用 feedparser 解析 RSS；
• 用 requests + BeautifulSoup 抓取微信公众号的 RSSHub 镜像页；
• 把所有来源的文章标题、链接、摘要，合并成一个 digest-raw.json ；

第三步：用 AI 重写与降噪
在 fetch-all-sources.py 后，添加新步骤：

- name: AI Rewrite Digest
  run: |
    echo "${{ secrets.CLAUDE_API_KEY }}" > .env
    python scripts/rewrite-digest.py --input digest-raw.json --output digest-final.md
  shell: bash

rewrite-digest.py 的核心逻辑是：把 digest-raw.json 里的 50+ 条信息，喂给 Claude，Prompt 是：“你是一个资深技术编辑。请从以下 50 条技术动态中，筛选出 5 条对中文开发者最有价值的内容（标准：1. 有可落地的代码示例；2. 解决了普遍存在的痛点；3. 不是厂商软文）。用中文重写每条摘要，控制在 100 字以内，结尾附上原文链接。输出纯 Markdown，不要任何解释性文字。”

第四步：自动创建 Issue
最后一步，用 GitHub 官方的 actions/create-issue ：

- name: Create Daily Digest Issue
  uses: peter-evans/create-issue-from-file@v4
  with:
    title: "📅 AI 技术早餐 | ${{ github.run_id }}"
    content-filepath: ./digest-final.md
    labels: "daily-digest,ai-news"

现在，每天北京时间 13:00，你都会收到一个标题为 “📅 AI 技术早餐 | 123456789” 的 Issue，里面是 AI 精心筛选、重写、排版的技术简报。我坚持看了两周，发现它推荐的 3 个开源项目，确实解决了我正在头疼的 CI/CD 问题——这已经不是“信息聚合”，而是“认知代理”。

5. 常见问题与排查技巧实录：那些官方文档不会告诉你的坑

5.1 GitHub Actions 执行失败：90% 的问题出在这三个地方

GitHub Actions 是整个系统的“心脏起搏器”，但它也是最容易出问题的环节。我整理了 12 个真实失败案例，按发生频率排序，前三个占了总失败数的 87%。

问题一： GITHUB_TOKEN 权限不足（占比 42%）
现象：工作流日志里出现 Error: Resource not accessible by integration 或 Permission denied to create pull request 。
原因：你的仓库是私有的，但 GITHUB_TOKEN 默认只有 read 权限。
解决方案：在工作流 YAML 的 permissions 字段，显式声明所需权限。例如，在 deploy-pages.yml 开头加上：

permissions:
  contents: write
  packages: read
  id-token: write

提示： contents: write 是最常缺的权限，它允许 Actions 推送文件到任何分支，包括 gh-pages 。

问题二：Puppeteer 启动失败（占比 28%）
现象：日志卡在 Launching Chrome... ，然后超时。
原因：GitHub Hosted Runner 的 Ubuntu 系统缺少 Chromium 的依赖库。
解决方案：在工作流的 steps 里， run Puppeteer 前，先安装依赖：

- name: Install Chromium dependencies
  run: |
    sudo apt-get update
    sudo apt-get install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2

我试过用 puppeteer-core + chromium 包，但不如直接装系统级依赖稳定。

问题三：Copilot 读取文件超时（占比 17%）
现象：Copilot Chat 里，你发了“读取 AGENTS.md”，它半天没反应，