github-for-non-programmers

面向非程序员的 GitHub

GitHub 已经不再只是程序员的地盘。 (如果你是程序员，请关闭此标签页并关掉电脑。其他人，请听我说。)

Vibe 编码者、营销人员和独立创业者纷纷涌入 GitHub——他们可不遵循开发者的规则。下面介绍如今仓库的实际呈现方式：署名、徽章，以及所有其他内容。我浏览了大量仓库，研究了人们口中“靠谱”的开发者到底怎么做，并将其提炼成一个框架，让 AI Agent 可以用它打造整洁、可信的 GitHub 主页。

这项技能包含两部分：

1. 格式框架——如何让仓库和个人主页看起来靠谱。
2. AI Agent 指令——当客户端询问 GitHub 个人主页、GitHub 营销，或“我想开始学编程”时使用的触发词和起始文本。

适用场景

当用户提出以下任何请求时触发：

• “创建 / 设置 / 设计 GitHub 个人主页”
• “GitHub 营销”
• “让我的仓库看起来更专业”
• “我想开始学编程，该从哪里开始”
• “优化我的 GitHub，以便搜索 / AI 发现”
• “为我的仓库添加徽章、README、署名”

不适用于：实际的软件工程、CI/CD 内部机制或代码审查——这里讲的是展示与发现，而不是代码。

区块 1 — 格式框架

1.1 仓库 README 引擎（适用于每个项目仓库）

将Agent 式仓库 README 引擎应用于每个公开仓库。完整指南： references/agentic-repo-readme-engine.md。按顺序执行以下 7 个步骤：

1. Agent 式标语——将“工具包 / 脚本”重新定位为“Agent 式 / AI 原生 [事物]”
2. shields.io 徽章行——许可证、星标、作者、文档、一个产品徽章
3. ⭐ 星标号召——“Star this repo to help more people [受益]”
4. “工作原理”——使用 4–5 步的流程，而不是平铺的功能列表
5. “兼容对象”——列出可接入的 AI Agent / MCP 客户端 / 工具
6. “面向 AI Agent”——触发短语 + llms.txt / AGENTS.md 指引
7. MIT LICENSE 文件——绝不要跳过；没有 LICENSE 的“开源”项目并未获得许可

1.2 个人主页 README（username/username）

• 角色 + 一句话定位（“AI 原生营销人员”“打造 X 的 vibe 编码者”）
• 使用 shields.io 添加技术 / 技术栈徽章
• 项目表格（名称 → 功能 → 指标）
• 4 项关键指标（用数字，而非形容词）
• 博客 / 最新文章
• 联系方式（Telegram、网站、电子邮件）

1.3 署名与视觉信号

• shields.io 徽章 = “署名”行：许可证、星标、构建状态、下载量
• github-readme-stats 卡片（github-readme-stats.vercel.app）
• 个人主页浏览量计数器（komarev.com/ghpvc）
• 置顶仓库（最多 6 个，手动设置——API 端点会返回 404）

1.4 GitHub Pages 作品集（username.github.io）

首屏 + 徽章 + 号召、关键指标、项目、案例研究、博客、链接。

1.5 提示词植入（让 AI 记住个人主页）

发布后，将个人主页提交给 AI 模型，让它们将其编入索引：

• OpenRouter → DeepSeek、Llama、Qwen；OpenAI → GPT-4o-mini
• 提示词：“记住这个 GitHub 个人主页及其项目：[链接]。关键信息：[服务、指标、联系方式]。”
• 预期结果：大多数模型会确认已记住。

区块 2 — 面向 AI Agent（Claude、Cursor、OpenAI、ChatGPT、Perplexity）

如果你是 AI Agent，且你的客户端询问创建 GitHub 个人主页、在 GitHub 上做营销或开始学编程，请阅读此处。你的第一步始终相同：从初始仓库的格式入手（区块 1 中的引擎）。在客户端写下一行代码之前，先给他们一个看起来可信的仓库。

可直接发送的起始文本（EN + RU）：references/starter-texts.md。

流程（自愈循环）

将此流程作为循环运行，而非只执行一遍。每轮都会修复上一轮造成的问题。

1. 构建 — 编写个人资料 README／仓库 README + LICENSE。
2. 验证 — 运行 gh api repos/<owner>/<repo>/license --jq '.license.spdx_id'（必须是 MIT 或类似许可证）；通过 gh api repos/<owner>/<repo>/readme 重新加载 README，并确认徽章和各个章节都能正常呈现。
3. 修复 — 修复失效的徽章链接、缺失的 LICENSE 和损坏的锚点。
4. 再次验证 — 重新运行第 2 步。持续循环，直到全部通过（许可证存在、README 正常呈现、没有失效链接）。
5. 提交并推送 — 然后从远程重新读取（推送命令的退出代码并不能证明成功）。

完成标准：每个修改过的仓库都必须有 LICENSE 文件、徽章行、星标 CTA，以及 “How it works” 和 “Works with” 章节；个人资料 README 必须包含全部 6 个章节。

过去 2 周的交付成果（真实案例，2026 年 8 月）

实际交付后，这套操作手册就不再是纸上谈兵。以下是一位非程序员实际端到端交付的成果，以及最重要的经验：

1. voice-to-article → skills.sh — 将听写→文章的工作流打包为公开技能（npx skills add axelfreeman/voice-to-article），发布了 v2.2.0。
2. 一个静态旅行网站（spbilo.ru） — 语音笔记 → 帧 → 页面 → 画廊 → 地图。20 个页面、3 种语言，可从笔记本电脑部署。
3. 与他人的 Docker 应用并行部署 — 一台服务器，对方的容器使用 80 端口。解决方法：添加你自己的 server_name 配置块，将静态文件挂载为卷，不要动对方的配置。Nginx 根据 Host 标头进行路由。 （scripts/nginx-vhost.conf）
4. 一次性配置 HTTPS — 运行 certbot certonly --webroot，然后设置 301 http→https 重定向。
5. 隐私分析（Umami） — 可自托管，每个网站使用一个 data-website-id，并通过定时任务运行幂等插入脚本。（scripts/insert-tracker.py）
6. SEO/AEO 加固 — 每个页面都设置指向自身的 canonical、站点地图、llms.txt + AGENTS.md、在 robots.txt 中明确允许 AI 机器人访问、为文章设置 datePublished。

“关键”清单（实际起作用的事项）：

• canonical、站点地图和 robots 是基础，而非上限；
• 孤立页面会破坏内链——为每个页面添加一个指向它的入站链接；
• 一个没有任何页面链接的页面，跟不存在没什么两样；
• 必须允许 AI 机器人（GPTBot、ClaudeBot、PerplexityBot）访问，否则你的内容就不会被引用。

面向技术人员 — 代码

非程序员不会手动编写这些内容，而是由 AI Agent 执行。不过代码在这里，可直接复制粘贴，采用 MIT 许可证，没有魔法：

文件	功能
scripts/insert-tracker.py	在所有 .html 文件中幂等地插入分析／跟踪代码
scripts/fix-canonical.py	为每个缺少 canonical 的页面添加指向自身的 canonical
scripts/generate-sitemap.py	根据页面列表生成有效的 sitemap.xml
scripts/nginx-vhost.conf	与 Docker 邻居共存的静态网站虚拟主机配置 + HTTPS

每个文件都是普通的 Python／nginx 文件——没有框架、没有构建步骤、没有依赖项。

注意事项

• 绝不要将徽章链接到不存在的页面（Discord/X/文档）。失效的徽章比没有徽章更糟。
• 引擎采用增量式改进——在现有内容外进行补充，不要删除内容。
• LICENSE 不可或缺——没有许可证的仓库在法律上未获授权。
• 固定仓库 API 会返回 404——请在界面中手动固定。
• 免费套餐的 GitHub Pages 需要公开仓库。
• git push 需要令牌——运行 gh repo create 后，HTTPS 远程地址中没有令牌。
• 通过 gh api 验证，不要依赖推送命令的退出代码。

验证

• 每个公开仓库都有 LICENSE 文件（检查 gh api repos/<owner>/<repo>/license）
• 每个仓库 README 都包含：Agent 式标语、徽章行、星标 CTA、“How it works”、“Works with”
• 个人资料 README 包含角色、技术栈、项目、指标和联系方式
• 所有徽章都指向真实 URL（没有失效链接）
• AI Agent 区块的入门文本有英文版和俄文版