Git 自动同步 Zou82/dsh-plugin-git-sync

dsh-plugin-git-sync

让 DeepSeek Harness（DSH）的 agent 自动完成 Git + GitHub 全流程的宿主插件：

1. 项目启动询问建仓：新项目开始时，agent 先询问你是否在 GitHub 建仓；仓库名必须经你确认，不满意可直接输入想要的名称，建仓后随时可改名。
2. 每次改代码自动同步：agent 每轮修改后调用 git_sync 提交推送；漏掉时由「回合结束兜底」自动同步（可配置）。
3. 凭据安全：GitHub 令牌存于 DSH 的凭据存储，绝不进入对话、远程 URL、进程命令行或任何输出。

完整设计文档见 DESIGN.md。

功能特性

- git_init：询问建仓 → 确认/自定义仓库名（冲突自动建议 name-2）→ 本地 git init + GitHub 建仓 + 首次提交推送；已有 git 仓库也可一键关联到 GitHub（建仓 + remote + 推送现有内容）
- git_rename：建仓后改名（GitHub 改名 + 本地 remote 同步 + 状态更新，旧链接 301 重定向）
- git_sync：提交并推送（自动 pull --rebase，冲突时列出冲突文件清单并停下交给你，绝不 force push；支持 create_branch 任务分支与 include 定向提交）
- git_status：查看同步状态（分支 / 远端 / 前后端差异 / 未提交文件）
- 回合结束兜底自动同步（autoSync 可配 true / false / "ask"）
- 文件监听（保存即同步）：工作区文件一变化就自动提交推送（可配防抖毫秒、自定义忽略规则；fs.watch 不可用时自动轮询回退）
- 描述性提交信息：兜底提交带变更文件摘要；可引导 agent 使用 Conventional Commits（feat/fix/chore(scope): summary）
- 提交前敏感文件扫描（.env、密钥等）、大文件告警
- 自动设置 git 提交身份（repo-local，不动全局配置）

环境要求

- DeepSeek Harness Desktop（DSH）2.x，profile 基于 Cordis 插件体系
- 本机已安装 Git（git --version 可用）
- 一个 GitHub 账号 + 令牌（见下方「配置令牌」）

安装

1. 构建打包

npm install
npm run build # 产出 lib/
npm pack # 产出 dsh-plugin-git-sync-.tgz

2. 装入 DSH profile

假设你的 profile 目录是 ~/.dsh/profiles/web（在 DSH Desktop 中即 web profile）：

cd ~/.dsh/profiles/web
pnpm add /path/to/dsh-plugin-git-sync-.tgz

3. 注册 bundle

编辑 profile 的 package.json，把插件加入 dsh.profile.bundles：

{
"dsh": {
"profile": {
"bundles": [ "...其它 bundle...", "dsh-plugin-git-sync" ]
}
}
}

4. 重启 DSH Desktop

完全退出并重新打开 DSH Desktop。插件装载后，日志会出现：

[I] [git-sync] git-sync: 插件已加载（GitHub 同步已启用）

新开对话后，agent 就能使用 git_init / git_sync / git_rename / git_status 四个工具。

踩坑提示：如果 bundle 声明或加载失败，DSH 的「启动恢复」机制会把插件自动加入禁用列表（startup-recovery/state.json 的 disabledBundles），表现为「看起来启动正常但插件没加载」。修复问题后，需要手动把插件从该文件的 disabledBundles 中移除再重启。

配置

插件有两类配置：GitHub 令牌（凭据）和插件设置。两者都可以在 DSH 设置界面里改（设置 → 插件 → 插件配置 → GitHub 同步 卡片，0.2.0 起内置），也支持直接编辑文件，效果相同且实时生效（无需重启）。

1. 配置 GitHub 令牌（必须）

位置：~/.dsh/.credentials.yaml（DSH 凭据文件），或在上述设置卡片中直接填写（令牌只写不读，不出现在界面上）。

在 refs: 下添加一行：

version: 1
refs:
DEEPSEEK_API_KEY: 你的-其他-密钥 GITHUB_TOKEN: github_pat_xxxxxxxxxxxx

令牌权限要求（GitHub → Settings → Developer settings → Personal access tokens）：

| 令牌类型 | 需要的权限 |
| Fine-grained PAT（推荐） | Administration: Read and write（建仓）、Contents: Read and write（推送）、Metadata: Read |
| Classic PAT | repo（整个 scope） |

安全提示：令牌创建后只显示一次；请勿把令牌写进任何会被提交到 git 的文件。

2. 配置插件设置（可选，有默认值）

位置：DSH 设置界面 → 插件 → 插件配置 → GitHub 同步卡片；或 ~/.dsh/settings.yaml 的 git-sync: 段（二者等价，实时生效）

git-sync:
github:
username: 你的GitHub用户名 # 建仓 owner；留空则用令牌对应账号 visibility: private # 默认仓库可见性：private / public defaultBranch: main insecureTls: false # 本机 TLS 被拦截时设为 true（见「常见问题」） auth: method: extraheader # git 凭据注入方式：extraheader / askpass git: committerName: "" # 提交作者名；留空用 GitHub 用户名 committerEmail: "" # 提交作者邮箱；留空用 GitHub noreply 邮箱 autoSync: true # 回合结束兜底：true 自动推送 / false 关闭 / "ask" 询问 askBeforeInit: true # 项目启动时是否询问建仓 init: createGitignore: true initialCommitMessage: "chore: initial commit" safety: scanForSecrets: true # 提交前扫描敏感文件并阻止提交 maxFileSizeMb: 50 # 大文件告警阈值（GitHub 上限 100MB）

也可以在 cordis.patch.yml 的 config: 段提供同样的配置（二选一，patch 内配置随包分发、settings 是运行时可改的）。

3. 配置项一览

| 配置项 | 默认值 | 说明 |
| github.username | 空（用令牌账号） | 建仓 owner（个人名或组织名） |
| github.visibility | private | 默认仓库可见性 |
| github.defaultBranch | main | 默认分支名 |
| github.insecureTls | false | 本机 TLS 证书链异常时跳过校验（仅可信网络建议开启） |
| auth.method | extraheader | git 凭据注入方式 |
| git.committerName / committerEmail | 空 | 提交身份，留空自动用 GitHub 账号 + noreply 邮箱 |
| autoSync | true | 回合结束兜底策略 |
| askBeforeInit | true | 是否询问建仓 |
| init.createGitignore | true | 建仓时生成 .gitignore |
| init.initialCommitMessage | chore: initial commit | 首次提交信息 |
| safety.scanForSecrets | true | 敏感文件扫描 |
| safety.maxFileSizeMb | 50 | 大文件告警阈值 |
| commit.conventional | true | 引导 agent 使用 Conventional Commits 提交信息 |
| fileWatcher.enabled | true | 文件监听：保存文件后自动提交推送（需 autoSync: true；忽略 .git/node_modules） |
| fileWatcher.debounceMs | 1500 | 连续变化的防抖毫秒数（合并一次编辑为一次同步） |
| fileWatcher.ignore | dist, build, __pycache__, ... | 额外忽略的目录/文件名（逗号分隔，按路径片段匹配） |
| fileWatcher.pollMs | 5000 | 文件监听不可用时的轮询回退间隔（轻量 git status 检查） |

使用

插件工具在新开对话中可用（当前对话的工具列表是固定的）。典型流程：

① 建仓（含仓库名确认/自定义）

我准备在 D:\my-project 开始一个新项目（目录为空），帮我建 GitHub 仓库并写一个 Python 脚本。

- agent 调用 git_init → 询问「是否建仓」（选私有/公开/暂不）
- 询问「仓库名使用 my-project？」→ 选「自定义名称」输入你想要的名称（不满意可改）
- 名称冲突时自动建议 my-project-2 或让你重输
- 自动完成本地 init + GitHub 建仓 + 首次提交推送

② 改名

把仓库名改成 better-name。

- agent 调用 git_rename → 确认 → GitHub 改名 + 本地 remote 同步（旧链接 301 重定向）

③ 改代码后自动同步

加一个参数解析功能。

- agent 改完代码调用 git_sync 提交推送；漏掉时回合结束自动兜底推送

安全设计

- 令牌零泄露：git 凭据通过 GIT_CONFIG_ 环境变量注入 http.extraheader（Basic auth，x-access-token 用户名），不写 remote URL、不写 .git/config、不进进程命令行；所有 git/API 输出经脱敏
- 绝不 force push：始终 pull --rebase + 普通 push，冲突停下交给你
- 敏感文件防护：提交前扫描 .env、.pem、id_rsa、*.key 等并阻止提交
- 状态目录自动忽略：插件状态存于项目内 .dsh-git-sync/，建仓时自动写入 .gitignore
- 大文件告警：超过阈值（默认 50MB，GitHub 上限 100MB）先确认再提交

插件状态存储

每个项目一个状态文件：/.dsh-git-sync/state.json（仓库名、远程地址、最近同步等），已自动加入项目的 .gitignore，不会进入提交。

常见问题

| 现象 | 原因与解决 |
| 推送报 remote: invalid credentials | GitHub 的 git 协议端点只接受 Basic auth（插件已内置 x-access-token + 令牌的 Basic 注入）；若你手动改过，确保不要用 Bearer |
| 访问 api.github.com 报 UNABLE_TO_VERIFY_LEAF_SIGNATURE / git 报 SEC_E_NO_CREDENTIALS | 本机存在 TLS 证书链拦截（安全软件/代理）。设置 github.insecureTls: true（跳过证书校验 + git 换 openssl 后端），或修复本机证书信任 |
| 插件状态 pending (waiting for services: ...) | 插件 inject 声明了运行时不存在/不该声明的服务。本插件只声明 tools/credentials/userQuestions；logger 是 Cordis 内置、session 事件走 ctx.on |
| 插件「没加载」但启动无报错 | 首次加载失败被「启动恢复」自动禁用：检查 startup-recovery/state.json 的 disabledBundles，移除插件名后重启 |
| 找不到 git 命令 | 先安装 Git 并确保在 PATH 中 |
| 仓库名不合法/被占用 | git_init 会校验命名规则（1–100 字符、- _ .、不能以 . 开头结尾）并在占用时建议后缀或让你重输 |

开发

npm install
npm run typecheck # 类型检查
npm run build # 构建到 lib/

真实令牌冒烟测试（建仓 → 推送 → 改名 → 清理，会在你的 GitHub 上创建临时仓库并自动删除）：

$env:DSH_GITHUB_SMOKE_TOKEN = "github_pat_..."
node scripts/smoke-github.mjs

License

MIT