@deepseek-ai/dsh-tool-git

Intelligent Git operations plugin for DeepSeek Harness (DSH).

Plugin Introduction

git_ops is a multi-mode Git tool that integrates into DSH sessions via Cordis. It automates the repetitive, error-prone parts of Git workflows:

• Generate Conventional Commits messages from staged diffs
• Summarize workspace diffs with risk awareness
• Build Markdown changelogs from commit history
• Detect conflict-prone files before merging
• Suggest semver versions and draft release notes

The plugin runs git commands via child_process.execSync inside the session sandbox and returns structured JSON that the model can reason about.

Installation and Registration

1. Install the package

pnpm add @deepseek-ai/dsh-tool-git

2. Register the plugin via Cordis patch

DSH supports plugin registration via cordis.patch.yml. Add the following entry to your project's patch file:

# cordis.patch.yml
- insert:
    - id: tool-git
      name: '@deepseek-ai/dsh-tool-git'
      config:
        gitMaxDiffBytes: 1048576

The patch injects the plugin at load time. gitMaxDiffBytes controls the diff size limit (default: 1 MB).

3. Start DSH

Once registered, the git_ops tool is available in the session tool list. The model can call it directly:

git_ops({"mode":"commit-message"})

Modes

commit-message

Generate a Conventional Commit message based on the current staged or working diff.

JSON call example:

{
  "mode": "commit-message"
}

JSON return example:

{
  "mode": "commit-message",
  "success": true,
  "summary": "feat(auth): update auth controller, middleware",
  "commitMessage": {
    "type": "feat",
    "scope": "auth",
    "description": "update auth controller, middleware",
    "body": "共修改 3 个文件。",
    "breaking": "BREAKING CHANGE: 本次变更可能影响现有行为",
    "isBreaking": true
  }
}

Use the returned commitMessage object to construct the final commit:

git commit -m "$(jq -r '.commitMessage | "\(.type)\(.scope // "" | if . != "" then "(\(.))" else "" end): \(.description)"' <<< result)"

---

diff-summary

Summarize the current workspace diff with per-file intent classification and risk detection.

JSON call example:

{
  "mode": "diff-summary"
}

JSON return example:

{
  "mode": "diff-summary",
  "success": true,
  "summary": "共扫描 4 个文件，新增 87 行，删除 12 行。其中 1 个文件存在较高变更风险。",
  "diffSummary": {
    "totalFiles": 4,
    "totalInsertions": 87,
    "totalDeletions": 12,
    "files": [
      {
        "path": "src/auth/controller.ts",
        "status": "Modified",
        "intent": "Refactor auth middleware",
        "highlights": [
          "+export async function login(req, res) {",
          "-import { oldAuth } from '../legacy'"
        ],
        "highRisk": false,
        "risks": []
      },
      {
        "path": "src/schema/user.sql",
        "status": "Modified",
        "intent": "Schema migration",
        "highlights": ["+ALTER TABLE users ADD COLUMN email_verified"],
        "highRisk": true,
        "risks": ["数据结构变更通常不可自动合并，建议提前对齐"]
      }
    ]
  }
}

---

changelog

Generate a Markdown changelog from a git log range.

JSON call example:

{
  "mode": "changelog",
  "range": "v1.2.0..HEAD"
}

If range is omitted, the last 200 commits are used.

JSON return example:

{
  "mode": "changelog",
  "success": true,
  "summary": "解析 3 条提交，按 2 个类型分组。",
  "changelog": {
    "summary": "解析 3 条提交，按 2 个类型分组。",
    "grouped": {
      "feat": [
        {
          "hash": "a1b2c3d",
          "description": "add export endpoint",
          "scope": "api",
          "type": "feat",
          "date": "2024-05-01",
          "author": "Alice <alice@example.com>"
        }
      ],
      "fix": [
        {
          "hash": "e4f5g6h",
          "description": "fix null pointer in parser",
          "type": "fix",
          "date": "2024-05-02",
          "author": "Bob <bob@example.com>"
        }
      ]
    },
    "markdown": "# Changelog\n\n> Range: v1.2.0..HEAD\n\n## feat\n\n- **api**: add export endpoint `a1b2c3d` - 2024-05-01 (Alice <alice@example.com>)\n\n## fix\n\n- fix null pointer in parser `e4f5g6h` - 2024-05-02 (Bob <bob@example.com>)\n"
  }
}

---

conflict-risk

Analyze workspace status and diff for files likely to cause merge conflicts.

JSON call example:

{
  "mode": "conflict-risk"
}

JSON return example:

{
  "mode": "conflict-risk",
  "success": true,
  "summary": "识别 3 个风险点。其中 2 个需要优先处理。",
  "conflictRisk": {
    "files": [
      {
        "path": "数据模型/迁移文件（见 git status）",
        "riskLevel": "critical",
        "reasons": ["数据结构变更通常不可自动合并，建议提前对齐"]
      },
      {
        "path": "pnpm-lock.yaml",
        "riskLevel": "medium",
        "reasons": ["锁文件通常需要完整重新生成，易引发冲突"]
      },
      {
        "path": "当前工作区",
        "riskLevel": "low",
        "reasons": ["未识别到明显高危变更"]
      }
    ],
    "suggestions": [
      "建议先 pull 或 rebase 到最新上游分支，减少后续冲突概率。",
      "优先合并冲突文件，先处理公共依赖再合并业务代码。",
      "大文件或频繁变动的二进制资源建议放到 LFS 或独立资产目录。"
    ]
  }
}

---

release-prep

Suggest the next semver version and draft release notes based on recent commit history.

JSON call example:

{
  "mode": "release-prep"
}

JSON return example:

{
  "mode": "release-prep",
  "success": true,
  "summary": "建议下一个版本为 1.3.0，基于 minor 级别版本提升。",
  "releasePrep": {
    "suggestedVersion": "1.3.0",
    "changes": [
      "feat: add export endpoint",
      "fix: null pointer in parser",
      "docs: update README"
    ],
    "releaseNotesDraft": "# Release Notes\n\n## 1.3.0\n\n- feat: add export endpoint\n- fix: null pointer in parser\n- docs: update README\n\n---\n\n_Generated by dsh-tool-git._"
  }
}

Error Handling

The tool returns structured errors instead of throwing when possible, so the model can recover.

Git not installed

{
  "mode": "commit-message",
  "success": false,
  "summary": "未检测到 Git 命令，请先安装 Git。",
  "error": "未检测到 Git 命令，请先安装 Git。"
}

Not a Git repository

{
  "mode": "commit-message",
  "success": false,
  "summary": "当前目录不是 Git 仓库，请先初始化或切换到项目目录。",
  "error": "当前目录不是 Git 仓库，请先初始化或切换到项目目录。"
}

Command failure

When a git subcommand fails, the tool reports the failure in summary and error fields:

{
  "mode": "changelog",
  "success": false,
  "summary": "Git 仓库检测失败：fatal: 路径规格 '.' 与仓库 '...' 不匹配",
  "error": "Git 仓库检测失败：fatal: 路径规格 '.' 与仓库 '...' 不匹配"
}

TypeScript Usage

The package ships TypeScript declarations at lib/types/index.d.ts.

import type {
  GitOpsConfig,
  GitOpsResult,
  GitOpsMode,
  GitOpsParams,
  CommitMessageDetails,
  DiffSummaryDetails,
  ChangelogDetails,
  ConflictRiskDetails,
  ReleasePrepDetails,
  GIT_OPS_EXAMPLE_PARAMS
} from "@deepseek-ai/dsh-tool-git";

Runtime import

import { Config, apply, inject, name } from "@deepseek-ai/dsh-tool-git";

// Use with Cordis plugin loader
const plugin = { name, inject, Config, apply };

Parameter typing

const params: GitOpsParams = {
  mode: "commit-message",
  range: "v1.0.0..HEAD",
  context_path: "."
};

Plugin Bootstrap

The plugin exports the standard Cordis plugin interface:

const name = "tool-git";
const inject = ["tools", "fs", "systemPrompt"];
const Config = z.object({});

It injects tools (to register git_ops), fs (for safe file reads if needed), and systemPrompt (to add a system prompt section reminding the model when to use the tool).

Contribution Guide

Contributions are welcome.

1. Fork and clone the repo.
2. Create a feature branch.
3. Run tests:

pnpm test

1. Open a PR with a clear description of the mode or fix.

Please keep mode schemas backward-compatible and update this README and examples.md when adding a new mode.