@deepseek-ai/dsh-tool-git

Readme

# @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](https://www.conventionalcommits.org/) 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

```bash
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:

```yaml
# 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:**

```json
{
  "mode": "commit-message"
}
```

**JSON return example:**

```json
{
  "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:**

```json
{
  "mode": "diff-summary"
}
```

**JSON return example:**

```json
{
  "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:**

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

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

**JSON return example:**

```json
{
  "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:**

```json
{
  "mode": "conflict-risk"
}
```

**JSON return example:**

```json
{
  "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:**

```json
{
  "mode": "release-prep"
}
```

**JSON return example:**

```json
{
  "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

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

### Not a Git repository

```json
{
  "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:

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

## TypeScript Usage

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

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

### Runtime import

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

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

### Parameter typing

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

## Plugin Bootstrap

The plugin exports the standard Cordis plugin interface:

```ts
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:

```bash
pnpm test
```

4. 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.