dsh-git-helper

dsh-git-helper

安全优先的 Git 工具插件（dsh-git-helper v0.3.0）：只读的状态/差异/历史/分支查询、标签管理与分支对比，加上一个带三重防护的提交工具。

安装

npm install dsh-git-helper

工具列表

git_status

查看工作区状态：当前分支、与上游的领先/落后、已暂存/未暂存/未跟踪/冲突文件分类列表。无参数。

git_diff

查看差异，支持三种范围：

参数	类型	说明
scope	string	unstaged（默认）/ staged / commit
commit	string	scope=commit 时必填，如 "a1b2c3d"、"HEAD~1"
path	string	可选，限定文件或目录
context_lines	number	可选，上下文行数 0–10，默认 3

输出附带变更摘要（文件数/±行数）；超过 8000 字符自动截断并提示缩小范围。

git_log

提交历史，格式 短哈希 | 作者 | 日期 | 标题。

参数	类型	说明
limit	number	1–50，默认 10
author	string	按作者过滤
since	string	如 "2026-09-01"、"2 weeks ago"
oneline_only	boolean	默认 true；false 时附带变更文件统计

git_branch

分支概览（只读）：当前分支标记、各分支最近提交、与上游的领先/落后。

参数	类型	说明
include_remote	boolean	默认 false

git_commit

受控提交，三重防护：

• 前置校验：暂存区为空且未指定暂存方式时拒绝提交并列出可提交文件；存在合并冲突时拒绝。
• 提交信息规范：非空、首行 ≤72 字符，详细说明放到空行后的正文。
• 后置确认：返回提交哈希 + 变更统计。

参数	类型	说明
message	string	必填
files	string[]	可选，指定要提交的文件（先 add 再提交）
add_all	boolean	默认 false；true 时 git add -A

git_tag

标签管理与查询。

参数	类型	说明
action	string	list（默认）/ create / delete
name	string	create/delete 必填，标签名（如 v1.2.0、dsh-foo@0.3.0）
message	string	可选（create），填写则创建附注标签，省略为轻量标签
commit	string	可选（create），目标提交，默认 HEAD
pattern	string	可选（list），glob 过滤，如 dsh-foo@*
limit	number	可选（list），条数 1-100，默认 20
push	boolean	可选，是否同步操作 origin，默认 false（仅本地）

list 按创建时间倒序输出名称、附注/轻量、日期与说明；create 校验重名与非法名称（含空白、以 - 开头）；delete 只删本地标签。远端发布需要标签先推送——不传 push 时返回结果会附上 git push origin <tag> 的提示，这是 tag 触发 CI 发布的关键一步。

git_branch_diff

两个分支/修订的对比摘要，默认两点比较（base..target）。

参数	类型	说明
base	string	必填，对比基准（如 main）
target	string	可选，对比目标，默认 HEAD
mode	string	stat（默认，文件级摘要）/ files（变更文件清单）/ patch（完整差异，自动截断）
three_dot	boolean	可选，改用三点比较 base...target，只看 target 侧引入的变更
path	string	可选，限定文件或目录
limit	number	可选，files 模式条数 1-200，默认 50

输出包含双向提交差（base 独有 / target 独有），files 模式把状态码翻译成中文（新增/修改/删除/重命名）。两点比较看的是"两端快照差异"，要排除 base 侧新增带来的反向差异时用 three_dot: true。

安全边界

本插件不提供 push、branch 删除、rebase/merge、checkout 丢弃改动、stash、amend 等破坏性操作；唯一例外是 git_tag 的 push=true（显式传参才会推送标签，默认仅操作本地）。git 命令通过 execFile 调用（无 shell 注入面），超时 15 秒。

测试

npm test

测试在临时 git 仓库中运行，覆盖状态识别、差异截断、历史过滤、提交防护与正常路径、标签创建/过滤/重名与非法名校验/删除、分支对比三种模式与三点切换、非仓库目录报错，共 56 项断言。

版本历史

0.3.0（2026-09-30）

• 新增 git_tag 工具：标签列表（pattern 过滤、附注/轻量标注）、创建（附注/轻量、指定目标提交）、删除；push=true 可同步 origin
• 新增 git_branch_diff 工具：两点/三点分支对比，输出双向提交差与 stat/files/patch 三种视图
• 测试扩展到 56 项断言

0.2.0（2026-09-13）

• 新增 git_blame 工具：行级追溯 + 作者分布统计（兼容 boundary 提交）
• 新增 check_commit_message 工具：提交信息体检（长度/CC 格式/正文分段）
• git_commit 新增 strict_cc 参数：Conventional Commits 强校验

Roadmap（v0.4 候选）

• git stash / restore 支持
• 提交历史筛选（按文件、按区间统计作者贡献）

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-git-helper
• npm：https://www.npmjs.com/package/dsh-git-helper

典型场景

1. 提交前检查

用户：帮我看看现在有哪些改动，准备提交

git_status + git_diff 快速了解工作区状态与改动内容。

2. 提交信息规范校验

用户：我的 commit message 符合规范吗

check_commit_message（支持 strict_cc 严格 Conventional Commits）逐项给出检查结论。

3. 追溯某行的来龙去脉

用户：这一行为什么这么写

git_blame 定位作者与提交（已兼容首笔提交的 boundary hash）。

4. 分支与历史梳理

用户：这个分支从哪切的、最近谁改了什么

git_branch + git_log 组合查看。

5. 生成提交

用户：把这次改动提交了

git_commit 生成提交（提交信息建议先过 check_commit_message）。

其他插件集成说明

协作插件	集成方式
dsh-text-diff	用 diff_text 得到统一差异，与本插件 git_diff 输出互相印证
dsh-hash-checksum	对关键文件取摘要，确认提交前后内容一致
dsh-workspace-journal	把提交记录写入工作区日志，形成变更时间线
dsh-fs-inspector	提交前用 recent_files 确认没有意外改动的大文件
dsh-todo-audit（二期 D13）	提交前扫描 TODO/FIXME，避免把未完成标记带入主干

FAQ

Q：git_commit 会自动 push 吗？ 不会，只做本地提交。推送需显式执行，且注意凭据助手（Windows 下建议 -c credential.helper=manager）。

Q：blame 首笔提交为什么特殊？ Git 对 boundary 提交的 hash 会加 ^ 前缀，本插件已兼容解析，不会漏掉最后一行。

Q：能在无 tty 环境用吗？ 可以，所有 git 调用均以非交互方式执行，不会卡在等待输入。

Q：会修改我的仓库吗？ 只有 git_commit 会写（产生提交）；其余工具均为只读查询。