# Gh Publisher

> 把本地文件、技能或项目推送到 GitHub 仓库（无需 git，gh CLI + REST API 脚本一次跑完）。当用户说「发布/推送到 GitHub」「开源这个项目」「更新仓库文件」或输入 /gh-publisher 时使用；支持空仓库初始化、多语言 README、隐私防推与密文扫描。不用于需要完整 git 历史、分支合并或多人协作的版本控制（改用 git）。

- Skill: `tydm2/gh-publisher` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add tydm2/gh-publisher`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tydm2/gh-publisher/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: tydm2 (https://skillmd.com/u/tydm2)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tydm2/gh-publisher

---


# gh-publisher

把一组本地文件推送到 GitHub 仓库（**无需 git**）：用 `gh` CLI 调 GitHub REST API（Contents / Git Database）完成空仓库初始化与批量提交，内置可复用脚本一次跑完——省 token、护隐私、跨平台。变更历史见 `CHANGELOG.md`。

## 何时用 / 何时不用

- **用**：本机无 git；空仓库首次初始化；把技能/文档/项目文件发布成 GitHub 仓库；批量覆盖多文件（含多语言 README）。
- **不用**：需要分支合并、完整 git 历史或多人协作开发——用 `git` 或 `gh repo` 系列命令。

## 四条硬原则（★每次必守）

1. **省 token**：优先跑 `scripts/push.ps1`（一条命令完成全部），不要逐文件手调 API、不要重新推导 blob→tree→commit→ref 流程；翻译走「增量编辑」固定方案，不全文重翻。
2. **隐私与账号安全**：token 永远不写进对话/日志/文件；登录用 `gh auth login`（keyring 托管）；输出一律脱敏；推送前密文扫描；绝不提交密钥。
3. **多 agent 适配**：正文不写死平台专属工具名；脚本用 `pwsh`（PowerShell Core，跨 Win/macOS/Linux），平台映射见 `references/platform-adapter.md`。
4. **个人信息永不外发（★）**：本机专属档案（`local-profile.json` / `config.local.json`）含账号、路径、仓库等个人信息，**任何情况下不推送 GitHub**——push.ps1 检测到即中止（PERSONAL DATA GUARD）。对本机档案的创建/修改/读取、或任何涉及个人信息的动作，必须**特意询问并强调**（⚠️ 本机专有、不发布）后才执行；普通技能/文档推送只需一句确认。

## 脚本用法（首选，省 token）

```powershell
pwsh -ExecutionPolicy Bypass -File scripts/push.ps1 -Source <本地目录> -Repo owner/repo -Message "提交说明" [-Profile <本机档案路径>] [-Branch main] [-GhConfigDir <gh配置目录>] [-GhPath <gh.exe 路径>] [-ForceSecret]
```

- `-ExecutionPolicy Bypass` 可绕开受限机器的脚本执行策略拦截（Windows 常见坑）。
- 脚本**自动探测 `gh` 二进制**（`-GhPath` → PATH → 常见安装路径）并**自动探测 `GH_CONFIG_DIR`**（`-GhConfigDir` → 环境变量 → `%APPDATA%\GitHub CLI`），无需手动改 PATH/配置。
- **本机有 local-profile 时用 `-Profile` 即可**：自动识别 gh 入口、配置目录、仓库（按源目录匹配）与语言（自动检测 README.<lang>.md），`-Repo`/`-Languages`/`-GhPath`/`-GhConfigDir` 均可省略——档案路径见技能目录 `config.local.json` 的 `local_profile` 字段（该文件属本机专有，不存在则手动传各参数）。
- 脚本自动完成：密文扫描 → 个人信息防推检查 → 空仓库检测（空则先初始化）→ 批量提交 → 脱敏输出（只打印「PUSHED N files -> URL」）。
- 密文命中默认**中止**（列出命中位置），确需放行加 `-ForceSecret`。
- 仓库不存在时脚本打印 `gh repo create ... --push` 提示，而非静默失败。
- 参数与退出码见 `scripts/push.ps1` 顶部注释。

## 本机专属档案（local-profile，机制说明）

部署了本机档案的机器（JSON，标记 `"never_publish": true`）可固化：owner 账号、gh 入口（如代理模式 shim）、`GH_CONFIG_DIR`、已知仓库映射、网络与认证说明。机制约定：

- **用法**：`push.ps1 -Profile <档案路径> -Source <目录> -Message "..."` —— 自动识别 gh 入口、配置目录、仓库与语言，不再逐项查找。档案路径部署时登记在 `config.local.json` 的 `local_profile` 字段。
- **个人信息防推（硬规则）**：文件名匹配 `local-profile.json` / `config.local.json` 的文件**永不推送到 GitHub**，push.ps1 检测到即中止；档案只存本机，绝不外发。
- **动作门控**：对本机档案的创建/修改/读取、或任何涉及个人信息的动作，必须**特意询问并强调**（⚠️ 本机专有、不发布）后才执行；普通技能/文档推送只需一句确认。
- **换机迁移**：复制整个档案目录（含档案与 gh 便携版）即可，登记路径随迁。

## 环境自检（首次推送前跑一遍）

1. **gh 可用？** — `Get-Command gh`（脚本也会自动探测安装路径）；缺失时 `winget install GitHub.cli` 或传 `-GhPath <gh.exe 路径>`。
2. **已登录？** — `gh auth status` 须显示已登录账号（token 显示为 `github_pat_***…` 掩码；**绝不**在任何地方粘贴原始 token）。
3. **配置目录？** — 通常自动（`%APPDATA%\GitHub CLI`）；agent 无法写该目录时设 `GH_CONFIG_DIR` 或传 `-GhConfigDir`。
4. **连通性** — 首次推送前 `gh api repos/{owner}/{repo}` 或 `gh repo list` 能返回数据。

## 多语言发布（技能/文档项目的推送默认步骤）

**推送技能或文档类项目到 GitHub 前，6 语言步骤默认执行**（发布语言 en/zh-CN/es/fr/ja/ru，效率说明见 `references/i18n.md`）——只有用户明确说「单语言推送/不用翻译」才跳过。

- **本地工作副本保留你的语言**：已安装技能目录的 `config.local.json` 存 `{"local_lang": "zh"|"en"}`（默认 `zh`）。说「更改本地保留默认语言为英文」即切换——本地 SKILL.md 同步更新。翻译本地文档前先读该配置。
- **发布版 = 6 种发布语言**：`README.<lang>.md` 覆盖 en、zh-CN、es、fr、ja、ru（完整清单 + 翻译规范 + 触发契约注意事项见 `references/i18n.md`）。`SKILL.md` 保持单一主版语言（gh-publisher 用英文；其他项目按自身约定）；所有语言版本 `name` 一致。
- **翻译方式 = 省 token 固定方案**：已有旧译文的语言默认走**增量编辑翻译**——子代理读旧译文 + 新英文源，只用编辑操作修改变化段落，不全文重翻（省 ~70-90% 输出 token、更快、保持术语/风格一致）；无旧译文的语言全文翻译一次并建立术语基线。细则见 `references/i18n.md` §1.5。
- **默认执行流程（除非用户豁免）**：
  1. 检查源目录已有语言文件；缺失/过期的语言文件用并行子代理按「增量编辑翻译」更新（见 i18n.md §1.5）。
  2. 就绪检查：`push.ps1 -Languages en,zh-CN,es,fr,ja,ru`——缺失列 WARN（有 `-Profile` 时自动检测，可省略）。
  3. 硬性把关：加 `-RequireI18n`——缺失语言文件即 **FAIL 中止推送**（exit 1）。
  4. 推送。
- **豁免记忆（per-repo）**：小型/代码类推送可把仓库加入技能目录 `config.local.json` 的 `i18n_exempt_repos: ["owner/repo", …]` 清单——命中清单的仓库默认跳过 6 语言步骤（用户当次要求翻译仍执行）；清单写入前须用户确认。**自动触发协议/语言清单/翻译规范/豁免话术见 `references/i18n.md`**。

## 手动流程（仅脚本不可用时）

1. 确认来源目录、目标 `owner/repo`、提交信息、分支（默认 main）。
2. **密文扫描 + 个人信息检查**（见「安全红线」）。
3. 判空：`gh api repos/{owner}/{repo}` 看 `size`，或 `GET contents` 返回 404 "empty"。
4. 空仓库 → 用 **Contents API** `PUT /contents/{path}` 写首个文件初始化（自动建默认分支）→ 再用 **Git Database API** 批量提交其余文件；非空 → 直接 Git Database API 批量提交（blobs→tree→commit→PATCH ref）。
5. 输出只打印提交数与最终 URL，**不打印任何 token/密钥**。

## 安全红线（逐条自检）

- [ ] 登录走 `gh auth login` / keyring，token 不出现在任何脚本或日志
- [ ] 推送前对全部文件做密文扫描：`github_pat_`、`ghp_`、`gho_`、`ghs_`、`ghr_`、`sk-`、`AKIA…`、`eyJ`（JWT）、`hooks.slack.com`、`-----BEGIN … PRIVATE KEY-----` 命中即中止并提示
- [ ] 输出脱敏：`gh auth status` 里 token 按 `github_pat_***…` 掩码展示
- [ ] 永不把用户粘贴进对话的 token 回显或写入文件
- [ ] 提交信息与文件不含密钥、账号密码、隐私数据
- [ ] **个人信息防推**：`local-profile.json` / `config.local.json` 出现在源目录 → push.ps1 中止（PERSONAL DATA GUARD），绝不发布
- [ ] **动作门控**：涉及本机档案/个人信息的动作先特意询问并强调（⚠️ 本机专有）；普通推送一句确认即可
- [ ] **省 token 翻译**：多语言走增量编辑翻译（不全文重翻）；保留清单（语言栏/徽章 URL/链接/锚点/命令/环境变量/文件名）未破坏

## 参考

- `references/security.md`：隐私与账号安全细则（脱敏、密文扫描清单、密钥轮换处置）
- `references/platform-adapter.md`：DSH / Codex / Claude Code / ZCode 机制映射（GH_CONFIG_DIR、子代理、弹框等价物）
- `references/i18n.md`：多语言发布协议（6 语言清单、省 token 增量编辑翻译、效率要点、翻译规范）
- `CHANGELOG.md`：变更历史