前言¶

DSH 插件开发者需要将代码发布到 GitHub。dsh-github-sync 插件将本地工作区的 DSH 插件作为“干净副本”推送到独立的 GitHub 仓库。它按需触发，平时不注入系统提示词，且 Token 仅存本地一次。

核心设计¶

安全机制¶

插件采用双阶段安全确认机制（Tool Guard）。Token 存放在 %USERPROFILE%\.dsh\github-sync\config.，绝不进 git，密钥扫描会阻断敏感文件上传。Token 权限需配置正确：经典 Token 需勾 repo，细粒度 Token 需 Contents: Read and write 和 Administration: write。

干净副本与增量同步¶

自动排除运行时文件（.git、node_modules、cache、dist、.env* 等）。符号链接不跟随。智能增量同步对比工作树与干净副本，未变动文件不擦写磁盘，避免 Windows 文件句柄占用冲突（EBUSY）。

标准 Git 流程¶

每个插件一个本地镜像仓库，存放在 %USERPROFILE%\.dsh\github-sync\mirrors。支持增量提交、真实历史和普通 push。不强制覆盖远端，远端有冲突会如实报错。force 选项保留为显式操作，用于替换远端历史。

安装与配置¶

DSH 插件加载时会自动生成配置模板。编辑用户配置文件（不在任何仓库里）：
%USERPROFILE%\.dsh\github-sync\config.json

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

提交署名默认按 token 所属账号派生，使用 GitHub noreply 邮箱。若使用自定义邮箱，需确保该邮箱已在 GitHub 账号里验证过。

典型用法¶

命令与工具¶

• /git：快捷触发入口，留空只读调查，带意图发起同步。
• github_sync_status：只读查看配置、token 来源、目标清单与判定结果。
• github_sync_plan：试运行（Dry Run），列出将提交/排除的文件与原因。
• github_sync_push：真正执行推送，需 confirm: true 确认参数或前置授权。

自然语言驱动¶

支持自然语言表达同步意图，无需死板地连发两次特定 /git 语法。

注意事项¶

• 插件自身绝不自动上传，也没有任何后台轮询/保存即上传的钩子。
• 单文件大小上限为 100 MiB，超过 GitHub 硬上限会阻断。
• 提交的作者署名默认关联到你的头像，但前提是邮箱已验证。
• 若插件目录含 .github/workflows/*.yml，推送时需额外勾选 Token 权限中的 workflow。