@local/dsh-github-sync

快速配置使用

1. 填写 GitHub 账号与 Token（只需一次）

编辑用户配置文件（不在任何仓库里）： %USERPROFILE%\.dsh\github-sync\config.json （插件首次加载会自动生成带注释的模板，所以通常直接打开改就行。）

{
  "github": {
    "owner": "你的GitHub用户名",
    "token": "ghp_xxxx 或 github_pat_xxxx",
    "topics": ["dsh-plugin"],
    "license": "MIT",
    "copyright": "你的署名或组织名"
  }
}

owner 也可以写在插件目录的 sync.config.json 里；用户文件里的空字符串不会覆盖插件目录里已填的值（留空即"未指定"，要清空请写 null）。 github.license 留空表示不自动生成（只在状态里告警）；github.copyright 留空则用 github.owner。 想让提交署自己的名字/邮箱，再加一段 "git": { "userName": "你的名字", "userEmail": "你的邮箱" }；该邮箱要先在 GitHub 账号里验证过才会关联到你的头像。留空则自动用账号的 noreply 邮箱（可关联、且不公开真实邮箱）。

Token 权限要求（依据 GitHub REST 官方文档核实）

经典 Token（Classic）— 只勾 repo 就够：

• repo 已包含 public_repo，所以勾了它就同时覆盖公开仓库与私有仓库。
• POST /user/repos（在自己账号下建仓）官方原文：need the public_repo or repo scope to create a public repository, and repo scope to create a private repository. → repo 一个就够。
• POST /orgs/{org}/repos（在组织下建仓）官方原文同上，但额外要求：The authenticated user must be a member of the organization.
• repo 同时给到代码读写，所以推送也用它。
• 勾 repo 时 UI 会自动带上 repo:status、repo_deployment、public_repo、repo:invite，无害，不用管。security_events、delete_repo、write:packages 都不需要。
• 唯一例外：若某插件目录含 .github/workflows/*.yml，需要额外勾 workflow（授予"添加和更新 Actions 工作流文件"）。首次推送到空仓库时不存在"同名同内容的旧分支"，那条豁免不成立。

细粒度 Token（Fine-grained）：

• 推送代码：Contents: Read and write。
• 自动新建仓库：Administration: write 或 Repository creation: write（官方为"满足其一"）。
• 打 topics：Administration: write。
• 组织启用了 SAML SSO 时，token 需单独授权给该组织，否则 403。

权限不足时不用猜：报错会直接打出 HTTP 状态码与对应提示（401 认证失败 / 403 权限不足 / 404 看不到）。分支保护导致推送被拒时会明确说是分支保护，而不是伪装成别的错误。

2. 在会话中触发

/git

或带上意图：

/git 把 github-sync 插件推到 GitHub

3. 命令与工具说明

• /git [要求]：触发同步意图，注入当轮说明并授权当轮推送。
• github_sync_status：只读查看配置、token 来源、git 可用性、插件清单、协议与镜像位置（只读，不联网）。
• github_sync_plan：试运行（Dry Run），列出将提交/排除的文件与原因、会打的 topic、协议是沿用还是生成。verbose 可看全部排除项（只读，不提交也不推送）。
• github_sync_push：真正的提交与推送。默认增量提交 + 普通 push；force: true 才会用单次快照替换远端历史。仓库不存在时按 visibility 自动创建，随后打 topics。仅在被 /git 授权的那一轮可用。

---