publish-project-to-github

将项目发布到 GitHub

将完成的本地项目整理成简洁的公开成果。将创建仓库、设为公开和部署视为彼此独立的关卡；成功推送并不能证明公开网站正常运行。

交付内容

提供适用的项目：

• 范围明确的 Git 仓库
• 有意设为公开或私有的 GitHub 仓库
• 项目专属的 README.md
• 项目具有视觉效果时提供真实的预览图片
• 能带来价值时提供便于移植的构建或 remix 提示词
• 为兼容的 Web 项目配置 GitHub Pages 网站
• 推送后和部署后的回读验证

1. 明确范围和权限

开始编写之前，先检查本地项目、仓库状态、远程地址和本地说明。

确认或安全推断：

• 确切的项目目录和目标文件
• 仓库名称和所有者
• 目标应设为公开还是私有
• 应更新现有仓库还是新建仓库
• 用户需要可访问的网站、仅托管源代码，还是两者都需要

只有用户明确要求公开分享、公开 URL、开源或表达同等意图时，才获准创建公开仓库。否则，在创建之前先询问可见性设置。

绝不要强制推送、覆盖现有远程仓库、更改仓库可见性，或替换现有 Pages 配置，除非获得明确授权。

2. 打包前进行审查

在项目根目录运行附带的审查脚本：

bash /path/to/publish-project-to-github/scripts/audit_public_project.sh .

随后检查审查结果，不要把脚本当作判断的替代品。

遇到以下情况时，禁止发布：

• API 密钥、令牌、私钥、密码或 .env 文件
• 个人数据或客户隐私信息
• 运行时依赖的本地绝对文件系统路径
• 未获许可或属于私有的资源
• 缺少运行时文件
• 对已存在仓库名称的所有权不明确

检查所有外部运行时 URL 和生成的资源。在 README 中注明任何必需的网络依赖。

发布前检查现有许可证。如果用户明确希望他人复用或修改项目，而项目没有许可证，请询问要添加哪种许可证，不要擅自选择。如果用户的目的只是公开展示，缺少许可证不会阻止部署，但要说明项目未明确授予复用权。

3. 选择打包方式

清理现有仓库

如果现有检出目录的远程地址、历史记录和已跟踪文件都符合目标公开项目的要求，就使用它。只暂存用户要求的文件。

混杂或无关的工作区

如果源工作区包含无关实验、删除内容、私有文件或无关历史记录，请新建干净的项目目录或相邻检出目录。只复制目标运行时文件。不要为了方便而发布整个混杂目录。

现有公开仓库

修改之前，检查其默认分支、Pages 来源、README、许可证和远程状态。谨慎拉取或协调，绝不要用强制推送掩盖分歧。

对于静态单文件实验，优先采用以下最简结构：

project-name/
├── index.html
├── README.md
├── PROMPT.md        # optional
├── assets/          # optional previews or runtime assets
└── .gitignore

4. 编写仓库介绍

根据真实项目编写 README。以 assets/README-template.md 为初始结构，而不是直接照搬为最终文案。

请包含：

• 项目名称，以及一句具体说明项目体验的描述
• 靠近顶部的在线演示链接；如果在 GitHub 以外的平台上展示有用，也请提供仓库源代码链接
• 从实际运行的项目中截取的屏幕截图或短 GIF
• 主要交互或功能
• 简明说明架构和不寻常的实现选择
• 准确的本地运行说明
• 项目结构
• 运行时依赖和网络要求
• 如果作品受其他作品启发，请注明原创性、出处或非关联声明

对于由 Agent 构建的项目，可酌情添加官方链接，以及一段便携式提示词，说明如何使用相关编码 Agent 重新构建或改编项目。发布前请核实官方 URL 是否仍然有效。

避免使用“尖端”“惊艳”或“已可用于生产”等泛泛表述。应具体描述精心打磨的细节和实际行为。

5. 在本地验证

使用项目实际的运行时，不要直接从磁盘打开基于模块的站点。

对于静态站点：

python3 -m http.server 4173 --bind 127.0.0.1

请检查：

• 初始渲染
• 主要交互路径
• 主要交互的返回、关闭或恢复路径
• 常规桌面视口，以及项目支持响应式布局时约 390 × 844 的窄视口
• README 中的每条运行命令
• 缺失文件和 404
• 控制台错误和警告
• 仓库子路径（例如 /project-name/）下的相对 URL

请使用用户指定的浏览器或仓库说明要求的浏览器。从已验证的运行环境中截取 README 预览图。

6. 提交并创建仓库

确保已安装 GitHub CLI 并登录经过身份验证的会话：

gh --version
gh auth status

创建仓库前，先检查名称是否可用：

gh repo view OWNER/REPOSITORY

只初始化并提交预期的软件包：

git init -b main
git add -- README.md index.html .gitignore
git diff --cached --check
git commit -m "Publish PROJECT_NAME"

如需添加可选文件，请明确指定；如果工作树中混有其他内容，不要用 git add -A 替换范围有限的 git add。

只有在审查和本地验证均通过后，才创建并推送仓库：

gh repo create OWNER/REPOSITORY \
  --public \
  --source=. \
  --remote=origin \
  --push \
  --description "CONCRETE_DESCRIPTION"

除非已获准公开，否则请使用 --private。如果仓库已存在，请明确配置其远程地址并推送，不要重新创建仓库。

7. 配置公开站点

启用 Pages 前，请先确定项目类型：

• 静态站点根目录： 发布 main 和 /。
• 静态文档目录： 发布 main 和 /docs。
• 框架构建项目： 使用该框架支持的 Pages 输出方式，并遵循最新的官方 GitHub Actions 指南。
• 服务器、数据库或私有运行时： GitHub Pages 不兼容；请说明限制，并仅在用户授权后选择其他托管服务。

更改 Pages 设置前，请阅读 references/github-pages.md。将仓库主页设置为最终公开 URL，并添加少量准确的发现主题。

8. 核实外部状态

读取并确认所有外部更改：

gh repo view OWNER/REPOSITORY \
  --json nameWithOwner,url,visibility,description,homepageUrl,defaultBranchRef

gh api repos/OWNER/REPOSITORY/pages
gh api repos/OWNER/REPOSITORY/pages/builds/latest

等待 Pages 构建状态显示 built 或明确失败。然后打开公开 URL 并验证：

• HTTP 导航成功到达最终 HTTPS URL
• 显示预期的项目 UI
• 一项有代表性的交互会更改应用主要状态，并能正常返回或关闭
• 资源在仓库子路径下正常加载
• 浏览器没有错误或警告
• README 中的链接均可访问

如果公开页面是用户要求交付的内容，请保持页面打开。

9. 准确交付结果

请返回：

• 仓库 URL
• 创建后的公开站点 URL（如有）
• 提交和分支
• Pages 构建状态
• 实际执行的检查
• 仍存在的依赖、许可或部署限制

请明确区分“已推送”“已配置 Pages”“Pages 已构建”和“已验证线上站点”，不要将它们统称为成功。

失败规则

• 保留无关的未提交更改和历史记录。
• 不要发布机密信息；如果机密信息已提交，在推送前将其从历史记录中移除。
• 如果无法根据本地上下文确定，不要猜测 GitHub 所有者或现有仓库目标。
• 不要声称 file:// 预览可以证明与 GitHub Pages 兼容。
• 不要将 CLI 成功退出作为验证外部写入的唯一依据。
• 如果 GitHub Pages 不兼容，不要悄悄改用其他托管服务。

资源

• 打包或发布前，运行 scripts/audit_public_project.sh。
• 配置或排查 Pages 前，阅读 references/github-pages.md。
• 复制 assets/README-template.md，并根据项目证据改写所有占位符。