目标

Objectives

把 GitHub/Git 的“基础操作”与常见协作流程固化为：

清晰的命令速查（解释 + 何时用）
可执行的一键脚本（避免重复手工步骤）
常用输出尽量“带编号”，方便你直接回复编号选择（例如：仓库列表）

Solidify GitHub/Git "basic operations" and common collaboration workflows into:

Clear command quick reference (explanation + when to use)
Executable one-click scripts (avoid repeated manual steps)
Add numbers to common outputs as much as possible to facilitate your direct reply with number selection (e.g., repository list)

安全与约束（必须遵守）

Security and Constraints (Must Follow)

序号	规则	原因
1	不要输出 Token：任何命令都不得把 `$GITHUB_TOKEN` echo/print 到 stdout	防止泄露
2	危险操作二次确认：删分支、清空目录、强制覆盖、强推、直推 main	可逆性差
3	默认用“分支 + PR”协作；只有用户明确要求才“直推 main”	降低对主分支破坏
4	push/pull 前先 `git status`	防止误提交/误覆盖

No.	Rule	Reason
1	Do not output Token: No command shall echo/print `$GITHUB_TOKEN` to stdout	Prevent leakage
2	Secondary confirmation for dangerous operations: Delete branch, empty directory, force overwrite, force push, push directly to main	Poor reversibility
3	Use "branch + PR" collaboration by default; only push directly to main when explicitly requested by the user	Reduce damage to the main branch
4	Run `git status` before push/pull	Prevent accidental commits/overwrites

运行方式

Execution Method

脚本入口：

sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh <command> [options]

脚本在“当前 git 仓库目录”下运行（必须在仓库内）。

Script Entry:

sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh <command> [options]

The script runs in the "current git repository directory" (must be inside the repository).

Git/GitHub 基础操作速查（解释 + 对应脚本）

Git/GitHub Basic Operations Quick Reference (Explanation + Corresponding Script)


init
clone
remotes/add-remote/add-upstream/set-remote-url/remove-remote
branches/create-branch/delete-branches
checkout
status/diff/log
add
commit
fetch/pull/push/push-main
merge/rebase
stash
tag
submodule
gh-issues-list

序号	类别	操作	一句话解释	常用命令	脚本支持
1	初始化	init	把当前目录变成 git 仓库	`git init`	`init`
2	获取代码	clone	从远端下载仓库到本地	`git clone <url>`	`clone`
3	远端	remote	管理 origin/upstream 等远端	`git remote -v/add/set-url/remove`	`remotes/add-remote/add-upstream/set-remote-url/remove-remote`
4	分支	branch	查看/创建/删除分支	`git branch -a/-d/-D`	`branches/create-branch/delete-branches`
5	切换	checkout/switch	切换到某分支	`git switch <b>`	`checkout`
6	查看变更	status/diff/log	看工作区改动/差异/历史	`git status` `git diff` `git log`	`status/diff/log`
7	暂存	add	把改动加入暂存区	`git add -A`	`add`
8	提交	commit	把暂存区打包成一次提交	`git commit -m "..."`	`commit`
9	同步	fetch/pull/push	拉取/合并/推送提交	`git fetch` `git pull` `git push`	`fetch/pull/push/push-main`
10	合并	merge/rebase	合并分支历史	`git merge` `git rebase`	`merge/rebase` （谨慎）
11	暂存栈	stash	临时收起未提交改动	`git stash`	`stash`
12	标签	tag	给提交打版本号	`git tag`	`tag`
13	子模块	submodule	管理子仓库依赖	`git submodule`	`submodule`
15	GitHub 平台	issues/labels/milestones/releases/actions	通过 GitHub API 管理平台对象	（API）	`gh-issues-list` 等（见下方）

注：脚本的定位是“把常用基础操作变成可复用命令”。遇到复杂 rebase/冲突，仍建议用交互式终端处理。


init
clone
remotes/add-remote/add-upstream/set-remote-url/remove-remote
branches/create-branch/delete-branches
checkout
status/diff/log
add
commit
fetch/pull/push/push-main
merge/rebase
stash
tag
submodule
gh-issues-list

No.	Category	Operation	One-sentence Explanation	Common Commands	Script Support
1	Initialization	init	Turn the current directory into a git repository	`git init`	`init`
2	Get Code	clone	Download repository from remote to local	`git clone <url>`	`clone`
3	Remote	remote	Manage remotes like origin/upstream	`git remote -v/add/set-url/remove`	`remotes/add-remote/add-upstream/set-remote-url/remove-remote`
4	Branch	branch	View/create/delete branches	`git branch -a/-d/-D`	`branches/create-branch/delete-branches`
5	Switch	checkout/switch	Switch to a certain branch	`git switch <b>`	`checkout`
6	View Changes	status/diff/log	View workspace changes/differences/history	`git status` `git diff` `git log`	`status/diff/log`
7	Stage	add	Add changes to the staging area	`git add -A`	`add`
8	Commit	commit	Package the staging area into a commit	`git commit -m "..."`	`commit`
9	Sync	fetch/pull/push	Pull/merge/push commits	`git fetch` `git pull` `git push`	`fetch/pull/push/push-main`
10	Merge	merge/rebase	Merge branch history	`git merge` `git rebase`	`merge/rebase` (use with caution)
11	Stash	stash	Temporarily store uncommitted changes	`git stash`	`stash`
12	Tag	tag	Add version number to a commit	`git tag`	`tag`
13	Submodule	submodule	Manage sub-repository dependencies	`git submodule`	`submodule`
15	GitHub Platform	issues/labels/milestones/releases/actions	Manage platform objects via GitHub API	(API)	`gh-issues-list` etc. (see below)

Note: The script is positioned to "turn common basic operations into reusable commands". For complex rebase/conflicts, it is still recommended to use interactive terminal processing.

GitHub 平台操作（API）

GitHub Platform Operations (API)

统一要求：需要 env
GITHUB_TOKEN
。

序号	command	作用
1	`gh-issues-list --repo <owner/repo> [--state open	closed
2	`gh-issue-create --repo <owner/repo> --title <t> [--body <b>]`	创建 Issue
3	`gh-issue-close --repo <owner/repo> --number <n>`	关闭 Issue
4	`gh-labels-list --repo <owner/repo>`	列出 labels
5	`gh-label-create --repo <owner/repo> --name <n> [--color <rrggbb>] [--description <d>]`	创建 label
6	`gh-milestones-list --repo <owner/repo> [--state open	closed
7	`gh-milestone-create --repo <owner/repo> --title <t> [--description <d>] [--due <YYYY-MM-DD>]`	创建 milestone
8	`gh-releases-list --repo <owner/repo>`	列出 releases
9	`gh-release-create --repo <owner/repo> --tag <vX.Y.Z> --name <n> [--body <b>] [--draft true	false] [--prerelease true
10	`gh-actions-list --repo <owner/repo>`	列出 workflows
11	`gh-actions-dispatch --repo <owner/repo> --workflow <id_or_file> [--ref <branch>] [--inputs <json>]`	手动触发 workflow_dispatch

Unified requirement: Requires env
GITHUB_TOKEN
.

No.	Command	Function
1	`gh-issues-list --repo <owner/repo> [--state open	closed
2	`gh-issue-create --repo <owner/repo> --title <t> [--body <b>]`	Create Issue
3	`gh-issue-close --repo <owner/repo> --number <n>`	Close Issue
4	`gh-labels-list --repo <owner/repo>`	List labels
5	`gh-label-create --repo <owner/repo> --name <n> [--color <rrggbb>] [--description <d>]`	Create label
6	`gh-milestones-list --repo <owner/repo> [--state open	closed
7	`gh-milestone-create --repo <owner/repo> --title <t> [--description <d>] [--due <YYYY-MM-DD>]`	Create milestone
8	`gh-releases-list --repo <owner/repo>`	List releases
9	`gh-release-create --repo <owner/repo> --tag <vX.Y.Z> --name <n> [--body <b>] [--draft true	false] [--prerelease true
10	`gh-actions-list --repo <owner/repo>`	List workflows
11	`gh-actions-dispatch --repo <owner/repo> --workflow <id_or_file> [--ref <branch>] [--inputs <json>]`	Manually trigger workflow_dispatch

脚本命令清单（gh_sync.sh）

Script Command List (gh_sync.sh)


clone --url <url> [--dir <path>]
remotes
add-remote --name <n> --url <url>
set-remote-url --name <n> --url <url>
remove-remote --name <n>
add-upstream --upstream <owner/repo>
git status --porcelain
diff [--staged]
log [--n <k>]
branches
create-branch --name <b> [--from <ref>]
checkout --name <b>
delete-branches --keep <branch>
git add
git commit
fetch [--remote <n>]
pull [--remote <n>] [--branch <b>]
push [--remote <n>] [--branch <b>]
push-main
empty-dir --dir <path>
restore-dir --src <path> --dst <path>
pr --upstream <owner/repo> --head <owner:branch> --base <branch> --title <t> --body <b>
gh-issues-list ...

序号	command	作用
2	`clone --url <url> [--dir <path>]`	clone 仓库到指定目录
3	`remotes`	显示当前 remotes
4	`add-remote --name <n> --url <url>`	添加远端
5	`set-remote-url --name <n> --url <url>`	修改远端 URL
6	`remove-remote --name <n>`	删除远端
7	`add-upstream --upstream <owner/repo>`	添加 upstream remote
8	`status`	`git status --porcelain` + 简要提示
9	`diff [--staged]`	查看差异
10	`log [--n <k>]`	查看最近提交
11	`branches`	列出本地与远程分支
12	`create-branch --name <b> [--from <ref>]`	创建分支
13	`checkout --name <b>`	切换分支
14	`delete-branches --keep <branch>`	删除除 keep 外的本地/远程分支
15	`add --path <p>`	`git add`
16	`commit --message <m>`	`git commit`
17	`fetch [--remote <n>]`	拉取远端更新
18	`pull [--remote <n>] [--branch <b>]`	拉取并合并
19	`push [--remote <n>] [--branch <b>]`	推送
20	`push-main`	push 当前 main 到 origin（使用 token 非交互）
21	`empty-dir --dir <path>`	清空仓库内某目录但保留目录（用 .gitkeep）
22	`restore-dir --src <path> --dst <path>`	用本机目录覆盖恢复到仓库目录（会先删除 dst 内容）
23	`pr --upstream <owner/repo> --head <owner:branch> --base <branch> --title <t> --body <b>`	通过 GitHub API 创建 PR
24	`gh-issues-list ...` 等	GitHub 平台对象操作（issues/labels/milestones/releases/actions）


clone --url <url> [--dir <path>]
remotes
add-remote --name <n> --url <url>
set-remote-url --name <n> --url <url>
remove-remote --name <n>
add-upstream --upstream <owner/repo>
git status --porcelain
diff [--staged]
log [--n <k>]
branches
create-branch --name <b> [--from <ref>]
checkout --name <b>
delete-branches --keep <branch>
git add
git commit
fetch [--remote <n>]
pull [--remote <n>] [--branch <b>]
push [--remote <n>] [--branch <b>]
push-main
empty-dir --dir <path>
restore-dir --src <path> --dst <path>
pr --upstream <owner/repo> --head <owner:branch> --base <branch> --title <t> --body <b>
gh-issues-list ...

No.	Command	Function
2	`clone --url <url> [--dir <path>]`	Clone repository to the specified directory
3	`remotes`	Display current remotes
4	`add-remote --name <n> --url <url>`	Add remote
5	`set-remote-url --name <n> --url <url>`	Modify remote URL
6	`remove-remote --name <n>`	Delete remote
7	`add-upstream --upstream <owner/repo>`	Add upstream remote
8	`status`	`git status --porcelain` + brief tips
9	`diff [--staged]`	View differences
10	`log [--n <k>]`	View recent commits
11	`branches`	List local and remote branches
12	`create-branch --name <b> [--from <ref>]`	Create branch
13	`checkout --name <b>`	Switch branch
14	`delete-branches --keep <branch>`	Delete local/remote branches except the kept one
15	`add --path <p>`	`git add`
16	`commit --message <m>`	`git commit`
17	`fetch [--remote <n>]`	Pull remote updates
18	`pull [--remote <n>] [--branch <b>]`	Pull and merge
19	`push [--remote <n>] [--branch <b>]`	Push
20	`push-main`	Push current main to origin (non-interactive using token)
21	`empty-dir --dir <path>`	Empty a directory in the repository but keep the directory (using .gitkeep)
22	`restore-dir --src <path> --dst <path>`	Overwrite and restore to the repository directory using local directory (will delete dst content first)
23	`pr --upstream <owner/repo> --head <owner:branch> --base <branch> --title <t> --body <b>`	Create PR via GitHub API
24	`gh-issues-list ...` etc.	GitHub platform object operations (issues/labels/milestones/releases/actions)

典型工作流（示例）

Typical Workflows (Examples)

1）直推 main：清空目录 → 恢复目录 → push（你刚刚那套）

1) Push directly to main: Empty directory → Restore directory → Push (the set you just used)

bash

sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh empty-dir --dir self-improving-agent
sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh restore-dir --src /var/minis/skills/self-improving-agent --dst self-improving-agent
sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh commit --message "restore(self-improving-agent): sync from local"
sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh push-main

bash

sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh empty-dir --dir self-improving-agent
sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh restore-dir --src /var/minis/skills/self-improving-agent --dst self-improving-agent
sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh commit --message "restore(self-improving-agent): sync from local"
sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh push-main

4）仅替换仓库目标文件内容（保留原路径/文件名），然后提交并推送

4) Only replace the content of target files in the repository (retain original path/file name), then commit and push

适用场景：用户要求“只内容替换”“只替换里面的 worker”“保留仓库原文件名/路径”，本意是：只覆盖目标文件内容，不新增上传源文件名，不改仓库中的目标路径。

推荐执行顺序：

bash

undefined

Applicable scenarios: When users request "only content replacement", "only replace the worker inside", "retain original file name/path in the repository", it means: Only overwrite the content of the target file, do not upload the source file name, do not modify the target path in the repository.

Recommended execution sequence:

bash

undefined

1. 拉取/刷新仓库

1. Pull/refresh the repository

repo_dir=/var/minis/workspace/<repo> if [ -d "$repo_dir/.git" ]; then cd "$repo_dir" && git fetch --all --prune && git reset --hard origin/main else gh repo clone <owner/repo> "$repo_dir" fi

2. 仅内容覆盖：用源文件内容覆盖仓库目标文件

2. Only content overwrite: Overwrite the target file in the repository with the source file content

cp <source_file> "$repo_dir/<target_path>"

3. 如未配置 Git 身份，优先复用 GitHub 登录名，并使用 GitHub noreply 邮箱

3. If Git identity is not configured, prioritize reusing GitHub login name and use GitHub noreply email

cd "$repo_dir" git config user.name '<GitHub显示名>' git config user.email '<login>@users.noreply.github.com'

cd "$repo_dir" git config user.name '<GitHub Display Name>' git config user.email '<login>@users.noreply.github.com'

4. 提交并直推 main（仅在用户明确要求提交/推送时执行）

4. Commit and push directly to main (only execute when the user explicitly requests commit/push)

git add <target_path> git commit -m 'replace <target_path> content' git push origin main


执行要点：
- 用户说“只内容替换”时，统一理解为：**保留仓库中的原文件路径与文件名，仅覆盖内容**。
- 不要把源文件名直接放进仓库；目标仍应是仓库里原本那个文件（例如 `worker.js`）。
- 若目标路径已知，直接覆盖该路径；若未知，先在仓库中定位目标文件再替换。
- 提交前若报 `Author identity unknown`，可在当前仓库写入：
  - `git config user.name '<GitHub显示名>'`
  - `git config user.email '<login>@users.noreply.github.com'`
- 默认先 `git fetch` + `git reset --hard origin/main`，避免在旧工作树上误提交。
- 若用户已经明确要求“提交”“推送”，可直接继续执行，无需重复确认。

git add <target_path> git commit -m 'replace <target_path> content' git push origin main


Execution points:
- When the user says "only content replacement", it is uniformly understood as: **Retain the original file path and file name in the repository, only overwrite the content**.
- Do not directly put the source file name into the repository; the target should still be the original file in the repository (e.g., `worker.js`).
- If the target path is known, directly overwrite the path; if unknown, locate the target file in the repository first before replacement.
- If `Author identity unknown` is reported before commit, write the following in the current repository:
  - `git config user.name '<GitHub Display Name>'`
  - `git config user.email '<login>@users.noreply.github.com'`
- By default, run `git fetch` + `git reset --hard origin/main` first to avoid accidental commits on the old working tree.
- If the user has explicitly requested "commit" or "push", you can continue execution directly without repeated confirmation.

5）删除除 main 外的所有分支（本地+远程）

5) Delete all branches except main (local + remote)

bash

sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh delete-branches --keep main

bash

sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh delete-branches --keep main

6）不建分支，fork:main → upstream:main 直接开 PR

6) No branch creation, directly open PR from fork:main → upstream:main

bash

sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh pr \
  --upstream OpenMinis/MinisSkills \
  --head mowenyun:main \
  --base main \
  --title "sync: ..." \
  --body "..."

仓库列表输出必须使用 Markdown 表格，并包含
```
编号
```
列，便于用户直接回复编号选择。

字段建议：

编号 | 仓库(owner/repo) | 可见性 | Fork | 默认分支 | 最近更新 | URL

交互建议：表格后提示“回复编号即可继续（clone/pull/提交推送/只内容替换等）”。

备注：若用户需要更多字段（description、language、stars），再加
--json ...
扩展。

序号	现象	处理
1	push 报 `could not read Username`	需要 env `GITHUB_TOKEN` ，脚本会用 `GIT_ASKPASS` 非交互认证
2	API 401/403	token 权限不足（repo/public_repo）或过期
3	`not inside a git repo`	先 `cd` 到仓库目录（或用 `clone` / `init` ）

bash

sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh pr \
  --upstream OpenMinis/MinisSkills \
  --head mowenyun:main \
  --base main \
  --title "sync: ..." \
  --body "..."

Repository list output must use Markdown table and include a
```
No.
```
column to facilitate users to directly reply with numbers for selection.

Recommended fields:

No. | Repository(owner/repo) | Visibility | Fork | Default Branch | Last Updated | URL

Interaction suggestion: After the table, prompt "Reply with the number to continue (clone/pull/commit and push/only content replacement, etc.)".

Note: If users need more fields (description, language, stars), add
--json ...
to expand.

No.	Phenomenon	Solution
1	Push reports `could not read Username`	Requires env `GITHUB_TOKEN` , the script will use `GIT_ASKPASS` for non-interactive authentication
2	API 401/403	Insufficient token permissions (repo/public_repo) or expired
3	`not inside a git repo`	First `cd` to the repository directory (or use `clone` / `init` )

github-sync-helper

Original

Translation

目标

Objectives

安全与约束（必须遵守）

Security and Constraints (Must Follow)

运行方式

Execution Method

Git/GitHub 基础操作速查（解释 + 对应脚本）

Git/GitHub Basic Operations Quick Reference (Explanation + Corresponding Script)

GitHub 平台操作（API）

GitHub Platform Operations (API)

脚本命令清单（gh_sync.sh）

Script Command List (gh_sync.sh)

典型工作流（示例）

Typical Workflows (Examples)

1）直推 main：清空目录 → 恢复目录 → push（你刚刚那套）

1) Push directly to main: Empty directory → Restore directory → Push (the set you just used)

4）仅替换仓库目标文件内容（保留原路径/文件名），然后提交并推送

4) Only replace the content of target files in the repository (retain original path/file name), then commit and push

1. 拉取/刷新仓库

1. Pull/refresh the repository

2. 仅内容覆盖：用源文件内容覆盖仓库目标文件

2. Only content overwrite: Overwrite the target file in the repository with the source file content

3. 如未配置 Git 身份，优先复用 GitHub 登录名，并使用 GitHub noreply 邮箱

3. If Git identity is not configured, prioritize reusing GitHub login name and use GitHub noreply email

4. 提交并直推 main（仅在用户明确要求提交/推送时执行）

4. Commit and push directly to main (only execute when the user explicitly requests commit/push)

5）删除除 main 外的所有分支（本地+远程）

5) Delete all branches except main (local + remote)

6）不建分支，fork:main → upstream:main 直接开 PR

6) No branch creation, directly open PR from fork:main → upstream:main