gxinxing/dsh-tool-git

@deepseek-ai/dsh-tool-git

面向 DeepSeek Harness（DSH）的智能 Git 操作插件。

插件简介

git_ops 是一个多模式 Git 工具，通过 Cordis 集成到 DSH 会话中。它自动化了 Git 工作流中重复且易出错的部分：

- 根据暂存的 diff 生成 Conventional Commits 消息
- 以风险感知的方式总结工作区 diff
- 根据提交历史构建 Markdown 变更日志
- 在合并前检测易冲突的文件
- 建议 semver 版本并起草发布说明

该插件在会话沙箱内通过 child_process.execSync 运行 git 命令，并返回模型可推理的结构化 JSON。

安装与注册

1. 安装包

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

2. 通过 Cordis patch 注册插件

DSH 支持通过 cordis.patch.yml 注册插件。将以下条目添加到项目的 patch 文件中：

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

该 patch 会在加载时注入插件。gitMaxDiffBytes 控制 diff 大小限制（默认：1 MB）。

3. 启动 DSH

注册完成后，git_ops 工具即可在会话工具列表中使用。模型可以直接调用它：

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

模式

commit-message

根据当前暂存或工作区的 diff 生成 Conventional Commit 消息。

JSON 调用示例：

{
"mode": "commit-message"
}

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
}
}

使用返回的 commitMessage 对象来构造最终的提交：

git commit -m "$(jq -r '.commitMessage | "\(.type)\(.scope // "" | if . != "" then "(\(.))" else "" end): \(.description)"' "
}
],
"fix": [
{
"hash": "e4f5g6h",
"description": "fix null pointer in parser",
"type": "fix",
"date": "2024-05-02",
"author": "Bob "
}
]
},
"markdown": "# Changelog\n\n> Range: v1.2.0..HEAD\n\n## feat\n\n- api: add export endpoint a1b2c3d - 2024-05-01 (Alice )\n\n## fix\n\n- fix null pointer in parser e4f5g6h - 2024-05-02 (Bob )\n"
}
}

conflict-risk

分析工作区状态和 diff，找出可能引发合并冲突的文件。

JSON 调用示例：

{
"mode": "conflict-risk"
}

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

根据最近的提交历史，建议下一个 semver 版本并起草发布说明。

JSON 调用示例：

{
"mode": "release-prep"
}

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._"
}
}

错误处理
该工具在可能的情况下返回结构化错误，而不是抛出异常，以便模型能够恢复。

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

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

命令失败

当某个 git 子命令失败时，该工具会在 summary 和 error 字段中报告失败：
json
{
"mode": "changelog",
"success": false,
"summary": "Git 仓库检测失败：fatal: 路径规格 '.' 与仓库 '...' 不匹配",
"error": "Git 仓库检测失败：fatal: 路径规格 '.' 与仓库 '...' 不匹配"
}

TypeScript 用法

该包在 lib/types/index.d.ts 中提供 TypeScript 声明。
ts
import type {
GitOpsConfig,
GitOpsResult,
GitOpsMode,
GitOpsParams,
CommitMessageDetails,
DiffSummaryDetails,
ChangelogDetails,
ConflictRiskDetails,
ReleasePrepDetails,
GIT_OPS_EXAMPLE_PARAMS
} from "@deepseek-ai/dsh-tool-git";

运行时导入
ts
import { Config, apply, inject, name } from "@deepseek-ai/dsh-tool-git";

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

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

插件引导

该插件导出标准的 Cordis 插件接口：
ts
const name = "tool-git";
const inject = ["tools", "fs", "systemPrompt"];
const Config = z.object({});

它注入 tools（用于注册 git_ops）、fs（在需要时用于安全读取文件）以及 systemPrompt（用于添加一个系统提示部分，提醒模型何时使用该工具）。

贡献指南

欢迎贡献。

1. Fork 并克隆仓库。
2. 创建一个功能分支。
3. 运行测试：
bash
pnpm test

4. 提交一个 PR，并清晰描述该模式或修复内容。

在添加新模式时，请保持模式 schema 向后兼容，并更新本 README 和 examples.md。