前言¶

DeepSeek Harness（DSH）把智能体能力按模块拆分成插件。在用 DSH 写自动化或代理应用时，常会遇到需要与 GitHub 仓库保持一致的场景：本地代码要推到远端，远端变更要拉下来合并，CI 流水线要自动触发和监控，这些操作分散在 git 命令、GitHub API 调用和 CI 配置里，容易在多仓库、多分支下出问题。

dsh-github-sync 插件提供一套统一的仓库同步与 CI 监控能力。它把双向 git 同步、Actions/CI 监控、仓库管理、本地文件浏览这些能力同时暴露给 Agent 工具、Web 面板和定时器，让这些操作可以在一个地方完成。

这是什么¶

dsh-github-sync 是一个 DSH 插件，用于 GitHub 仓库的双向同步、Actions/CI 流水线监控、仓库增删改名、本地文件浏览与推送前检查。插件本身零运行时依赖，需要 dsh 自带的 pnpm。

插件维护者是 wzw4429-crypto，归类为「联网工具」。

核心功能¶

双向同步¶

插件对每个仓库执行以下步骤：

1. fetch 远端变更
2. 计算本地与远端的关系（ahead/behind）
3. 合并入远端（支持快进 / merge / rebase，冲突时回滚）
4. 运行推送前检查
5. push 到远端

同步结果分为几种状态：up-to-date、pulled、pushed、synced 表示成功；dirty、diverged-report、conflict、checks-blocked 表示因工作树状态或检查未通过而停住；error 表示 git 或环境失败。

冲突策略¶

插件支持多种冲突处理策略：

• report（默认）：只报告冲突，不执行合并操作
• merge：尝试合并
• rebase：尝试变基
• prefer-remote：以远端为准
• prefer-local：以本地为准

无论哪种策略，任何冲突都会中止操作并回滚，不会留下半合并状态。

推送前检查¶

可以为仓库配置一组 shell 检查命令。每个检查可以指定失败时的行为：

• block：阻止推送
• warn：记一笔日志后继续

检查未单独声明 onFail 时，使用全局默认配置 onCheckFailure。

Actions/CI 监控¶

插件会自动补全或更新 .github/workflows/dsh-ci.yml（默认路径）。工作流支持通过 workflow_dispatch 手动触发，也支持在同步后自动触发 CI 并轮询运行状态。

在 Web 面板中可以查看仓库的 Actions 运行列表、某次运行的 jobs 与每一步的结论，并提供跳转到 GitHub 对应页面的链接。

Web 面板¶

侧栏「GitHub Sync」面板提供以下功能：

• 仓库卡片：显示状态、最近同步时间、CI runs
• 文件浏览器：直接读取本地克隆磁盘的目录/文件树与文本预览（文本 ≤128KB，二进制只显示元数据）
• 一键操作：同步仓库、触发 CI、补 CI 文件
• 全部仓库列表：显示所有已注册仓库，支持一键加入同步、手动添加、移除
• 15 秒自动刷新

仓库管理¶

插件会缓存用户的 /user/repos 列表（5 分钟）。要列出全部仓库，需要在配置中提供 PAT。

「加入同步」会将仓库克隆到 cloneRoot/<owner>/<name>（可指定本地路径；若是已存在的 git 仓库路径，则直接注册为同步对象）。运行时加入的仓库会持久化在状态文件里。「移除」只从列表中删除，不会删除磁盘上的文件。

改名同步¶

在面板或通过 Agent 工具对仓库改名后，插件会调用 GitHub PATCH /repos API（需要 admin 权限）更新远端，并在本地执行 git remote set-url。配置文件中的仓库改名记录会保存在状态文件的映射里，不改动 cordis.patch.yml。历史提交与 CI 缓存会跟随新的仓库名。

活跃仓库置顶¶

插件根据以下指标对仓库排序：

• 未提交的改动（权重 1000）
• 顶层文件最新修改时间（权重 100）
• 最近提交时间（权重 60）

活跃仓库会自动排在前面的位置，卡片上会显示「使用中 / N 分钟前」的徽章。

Agent 工具¶

插件暴露一组工具供 Agent 调用：

• github_sync：执行同步
• github_status：查看仓库状态
• github_ci：查看 CI runs / checks / status / run-detail
• github_workflow：列出或触发工作流
• github_repos：列出、添加、移除、改名仓库
• github_files：浏览本地或 GitHub 上的文件（默认 source: local）

定时同步¶

在配置中设置 intervalMinutes，插件会按周期自动同步全部仓库。设置 runOnStart: true 会在启动 5 秒后先跑一轮同步。

安装与启用¶

插件可以从 GitHub 直接安装：

dsh plugin --profile <profile> add https://github.com/wzw4429-crypto/dsh-github-sync

安装后重启 dsh 使配置生效。也可以在插件发布到 npm 后用包名安装：

dsh plugin --profile <profile> add dsh-github-sync

配置方式¶

插件的 cordis.patch.yml 只声明插件模块，不带任何配置。你的 token、仓库列表、定时周期等需要写在 profile 自己的 patch 层里，按 id + 模块名覆盖：

- id: github-sync
  name: dsh-github-sync
  config:
    token: 'ghp_...'
    repos:
      - name: my-repo
        path: D:\path\to\repo

这样密钥与机器路径不会进插件仓库，插件升级也不会覆盖你的配置。面板和工具运行时加入的仓库会保存在状态文件里，无需修改配置文件。

认证¶

支持两种认证方式，二选一（token 优先）：

1. 环境变量（推荐）：设置 GITHUB_TOKEN=<PAT> 或通过 tokenEnv 指向别的变量名。PAT 需要 repo 权限（访问私有仓库）和 workflow 权限（触发 Actions / 写入 workflow 文件）。
2. 配置直填：在 config.token 中填写 PAT。

插件不会在日志、工具输出、面板或错误消息中显示 token（redactedConfig 会脱敏）。git 的 fetch/push 通过环境注入 http.extraheader 使用 PAT，不会出现在进程参数中。无 token 或非 github.com https 远端时，会回退到系统凭据助手或 SSH 密钥。

配置项¶

在 profile patch 层的 github-sync.config 中可以配置：

- id: github-sync
  name: 'dsh-github-sync'
  config:
    enabled: true            # 总开关
    runOnStart: false        # 启动 5s 后先跑一轮
    intervalMinutes: 30      # 定时周期
    tokenEnv: 'GITHUB_TOKEN'
    notifyAgent: true
    notifyOn: [conflict, error, checks, pipeline]   # 事件：conflict/error/checks/pipeline/pull/push
    autoCommit: false        # 同步前把脏工作树自动提交
    conflictPolicy: 'report' # report/merge/rebase/prefer-remote/prefer-local
    onCheckFailure: 'block'  # 检查未单独声明 onFail 时的默认：block/warn
    repos:
      - name: my-repo
        path: D:\path\to\repo
        remote: origin        # 默认 origin
        branch: ''            # 默认当前分支
        mode: bidirectional   # bidirectional/pull/push
        githubRepo: ''        # 可选显式 owner/name；缺省从 remote URL 推断
        workflowFile: ''      # 可选，补 CI 文件名，默认 .github/workflows/dsh-ci.yml
        checks:
          - name: test
            run: 'npm test'
            onFail: block     # block/warn
    pipeline:
      triggerCi: true         # 同步后 dispatch CI
      waitCi: true            # 轮询到 run 完成
      waitTimeoutMinutes: 10
      pollIntervalSeconds: 20

状态与数据¶

状态文件保存在 <profile>/github-sync-state.json，每个仓库包含：

• lastSync：最近同步时间
• lastPipeline：最近 CI 运行时间
• history：尾 20 条历史记录
• ci：CI 缓存信息

适用场景¶

适合需要在 DSH 中统一管理 GitHub 仓库同步与 CI 监控的开发者或团队，尤其是需要：

• 对多个仓库进行双向同步
• 在同步前后执行检查
• 监控 CI 状态并在需要时阻断推送
• 通过 Web 面板或 Agent 工具统一操作仓库

插件以当前 dsh 进程的权限运行。安装前建议检查源码与许可证。

短结尾¶

dsh-github-sync 把 GitHub 仓库的同步、CI 监控与文件浏览能力统一到 DSH 的插件体系里，通过 Agent 工具和 Web 面板都可以调用。安装后按 profile 配置 token 与仓库列表，重启 dsh 即可使用。

插件目录页：https://www.skillhub.cn/plugins/wzw4429-crypto/dsh-github-sync
GitHub 仓库：https://github.com/wzw4429-crypto/dsh-github-sync