GitHub 上传

将用户指定的本地项目上传到正确的 GitHub 仓库和分支，并验证远端提交。默认用中文沟通，尊重会话中已明确的目录、文件范围、目标和授权。

确定范围与工具

从当前请求、会话和仓库配置确定项目路径、GitHub 主机、仓库所有者、仓库名和目标分支。先读取适用的 AGENTS.md。路径缺失时可使用当前工作目录，但先核实它确实是目标项目；多个项目并列时不要上传整个父目录。
已有明确上传请求及目标时，正常检查、提交和推送可直接完成，不重复索要确认。仅询问无法推断且影响结果的信息。只要求检查、准备或写教程时，不创建远端仓库或推送。
新建仓库若未指定可见性，默认 private 并说明；已有仓库保留可见性。公开发布、删除仓库、覆盖历史、更换已有远端或迁移历史须有对应授权。
优先使用已连接且能力合适的 GitHub 工具处理远端查询、建仓和 PR；本地提交及历史推送使用 Git。没有合适的连接工具时使用 gh；用户明确选定的工具优先。不要把逐文件 API 上传当作保留 Git 历史的推送。
Git 是本地版本控制前提，gh 是可选工具。通过 Get-Command git,gh -ErrorAction SilentlyContinue 检查。CLI 路径先用 gh auth status 检查登录；现有 Git 凭据可直接用于已知远端，不因缺少 gh 阻止正常推送。连接器认证与本地 Git 认证分别验证。
缺少认证时，完成不依赖认证的本地准备，再引导用户完成浏览器/设备登录，例如 gh auth login --web。不要索要粘贴令牌、读取凭据文件或输出 token。

检查本地状态

Windows 使用 PowerShell；路径用单引号或变量传参，文件操作使用 LiteralPath。设置正确的工作目录，逐条执行并检查退出码，失败后不要继续依赖该命令的后续操作。

Set-Location -LiteralPath 'D:\项目路径'
git rev-parse --show-toplevel
git status --short --branch
git branch --show-current
git remote -v
git diff --stat
git diff --cached --stat
git ls-files --others --exclude-standard

仅当目录确实未纳入 Git 且是目标项目根目录时，执行 git init -b main。已有仓库保留分支名称，不无故重命名为 main。Git 根目录若是目标文件夹的父目录，先核实范围。
检查暂存区、未提交修改、已有未推送提交、嵌套仓库和子模块。保留用户原有暂存选择，不用批量 reset、clean 或 checkout 丢弃工作。混合了任务外暂存内容时，先准备本次文件清单；不能可靠隔离才询问用户。
遇到 detached HEAD、未完成的 merge/rebase 或冲突，先确定应保留的提交和目标分支，再在授权范围内处理。
从已有配置读取提交身份；身份缺失且无法从上下文确定时，询问姓名和邮箱，使用仓库级配置，不编造身份或修改全局配置。

准备提交内容

检查实际待上传内容和 .gitignore；排除 .env、私钥、凭据文件、依赖目录、构建产物及无关数据，按项目实际情况调整。允许保留不含真实凭据的示例配置。
.gitignore 不会移除已跟踪文件或历史内容。首次推送会发送分支可达历史，更新推送也会发送尚未上传的提交；检查这些内容中的凭据或异常大文件。发现敏感信息时报告文件位置而不复述值，停止发送相关内容，说明需要的清理；不擅自重写历史。
大文件按 GitHub 当前限制检查；超限时说明可选的 Git LFS 或排除方案。不要悄悄删除用户文件、迁移已有历史或将附件另行公开发布。
先查看差异和待暂存文件清单，再用明确路径暂存。只有在全部变更均属于本次上传范围且检查通过时，才使用 git add -A。
提交前检查 git diff --cached --stat、必要的实际差异以及 git diff --cached --check；运行与内容相关且仓库要求的检查。不要因上传动作本身添加无关测试。
使用描述实际变化的提交信息。没有新改动就不创建空提交，但仍检查是否有已有提交等待推送。

连接目标与推送

首次上传

若用户给了已有仓库，先核实主机、所有者、权限和仓库内容。
若请求包含新建仓库，按已确定的名称和可见性创建空仓库，不额外初始化远端 README 或 License。CLI 示例仅适用于已核实 owner/repo、目标尚不存在、origin 名称未占用、且本地提交准备就绪的情况：
```
gh repo create 'owner/repo' --private --source . --remote origin
```
对已存在且还未配置到本地的仓库，可使用 git remote add origin 'https://github.com/owner/repo.git'。origin 已指向其他仓库时，不直接覆盖；按用户目标选用现有正确远端或另设远端名称。
远端非空时，先 fetch 并比较历史，再执行正常快进或保留双方工作所需的集成。历史无关时，不自动 force 或使用 allow-unrelated-histories；先说明可选方案并获取必要决定。

后续更新

沿用已核实的目标远端和分支，通过 git remote get-url REMOTE_NAME 和 git remote get-url --push --all REMOTE_NAME 检查 fetch URL 与全部 push URL；不能把 origin 或 upstream 名称本身当作正确目标的证据。存在多个 push URL 时先核实是否都属于本次上传范围。若 fetch 与 push 指向不同仓库，应针对实际推送地址 fetch 目标分支并比较历史，而不是仅比较 fetch 端。用户范围外的已有提交不能因“工作区干净”就被忽略。

完成检查后，使用明确的目标分支，避免依赖可能不匹配的默认 push 配置：

git push -u REMOTE_NAME HEAD:refs/heads/BRANCH_NAME

上面的大写参数是占位符，必须替换为已核实的远端名称和分支。默认只推送本次目标分支，不使用 --all、--mirror、--force 或顺带推送标签。

non-fast-forward：先 fetch 检查差异，在用户任务授权和仓库惯例内集成；若涉及取舍或不可安全解决的冲突，展示具体问题并询问，不以强推消除错误。
分支保护或权限不足：采用允许的分支/PR 流程或说明所需权限，不绕过规则。仅在用户任务包含 PR 或必须通过 PR 完成且已获得相应授权时创建 PR；在支持附件的 Codex 环境中，将创建的 PR 附加到当前聊天。
推送保护拦截凭据：处理具体暴露内容，不绕过保护。
网络中断：先核实远端是否已经收到提交，再决定是否重试。对于同一故障，只有诊断出可修复原因才重试；持续失败则报告当前状态和下一步，不循环修改远端或认证。

验证和交付

推送命令成功后，用 git rev-parse HEAD 获取本地提交，用 git ls-remote 'ACTUAL_PUSH_URL' refs/heads/BRANCH_NAME 验证实际推送目标的分支。将占位符替换为前面核实的 push URL 和分支；若授权向多个地址推送，逐个验证。比较完整 SHA；必要时结合已连接的 GitHub 工具查询。
SHA 一致才报告目标分支已包含该提交。若验证时出现并发更新，fetch 后检查提交是否被包含；无法验证时明确区分“推送命令已成功”和“远端验证未完成”。
最后提供仓库链接、分支、提交短 SHA、检查结果以及未上传的相关文件或阻碍。不得把“已创建本地提交”说成“已上传成功”。

按需查阅

命令参数、认证或限制不确定时查阅官方来源，不把本文示例当作实时平台限制：