lucky8197/dsh-git-hygiene

dsh-git-hygiene（Git 卫生巡检）

DeepSeek Harness 的 Git 卫生检查器。
一个只读的 DSH 插件，用于检查仓库的卫生状况：已合并但未删除的分支、
数月无提交的过期分支、体积过大的已跟踪文件、未跟踪文件以及未提交的工作——
然后输出一份带清理建议的健康报告。它绝不会自动删除或修改任何内容。
安装命令：dsh plugin --profile web add "github:lucky8197/dsh-git-hygiene#main"。

仓库用久了会"长胖"：功能分支合并后没人删、几个月不动的老分支堆积、不小心提交了
几十 MB 的二进制、未跟踪文件散落一地。dsh-git-hygiene 用只读 git 命令给仓库
做一次"体检"，把这些问题量化成带清理建议的报告。

特性

| 维度 | 说明 | 发现类型 | 严重度 |
| --- | --- | --- | --- |
| 已合并分支 | 已合并到当前分支但未删除的分支（git branch --merged） | merged_branch | medium |
| 过期分支 | 超过 N 天（默认 90）无提交的分支（for-each-ref committerdate） | stale_branch | low |
| 大文件 | 跟踪文件超过阈值（默认 5 MB），提示用 LFS/filter-repo 处理 | large_file | low |
| 未跟踪文件 | git status --porcelain 的 ?? 条目 | untracked | low |
| 未提交修改 | 工作区 dirty 状态（M/A/D 等） | dirty_worktree | low |

快速安装

dsh plugin --profile web add "github:lucky8197/dsh-git-hygiene#main"

工具用法

git_hygiene
参数：
cwd?: string          仓库目录（默认当前会话工作目录）
staleDays?: number    过期分支阈值（天，默认 90）
maxFileBytes?: number 大文件阈值（字节，默认 5MB）
输出：canonical JSON 报告（渲染为分节文本）

canonical JSON

{
"tool": "git_hygiene",
"version": 1,
"cwd": "/path/to/repo",
"repo": { "isRepo": true, "root": "/path/to/repo", "branch": "main",
"head": "abc1234…", "remotes": ["origin"], "sizeBytes": 4211000, "objectCount": 1200 },
"findings": [
{ "severity": "medium", "kind": "merged_branch",
"detail": "2 个分支已合并到当前分支，可以安全删除：feature-a、feature-b",
"evidence": "feature-a, feature-b",
"fix": "对每个已合并分支执行 git branch -d （-d 安全删除，未合并会拒绝）" }
],
"stats": { "findingCount": 1, "byKind": { "merged_branch": 1 } },
"suggestions": [ { "severity": "medium", "text": "…" } ]
}

配置（cordis 配置节）

- insert:
- id: git-hygiene
name: 'dsh-git-hygiene'
config:
staleDays: 90          # 过期分支阈值（天）
maxFileBytes: 5242880  # 大文件阈值（字节）
maxList: 30            # 各清单最大展示条数

安全边界（硬性要求）

- 只执行白名单只读 git 子命令（src/git.ts WHITELIST 全量枚举：status --porcelain /
branch --merged / for-each-ref / ls-files / count-objects -v / remote -v / rev-parse /
log -1 / symbolic-ref）；白名单外的一律拒绝（含 checkout/reset/clean/delete/push）；
- 不自动删除/修改任何分支或文件——只输出建议，清理动作由用户执行；
- 文件体积用只读 node:fs stat，报告不含任何文件内容；
- 非 git 目录返回 isRepo: false，不报错不猜测。

防误报设计

- 当前分支自动从"已合并"清单排除（* 标记剥离）；
- detached HEAD 正常处理（branch 为空，不崩溃）；
- 文件缺失/不可读静默跳过。

工程结构

dsh-git-hygiene/
├── package.json          # name=dsh-git-hygiene, main=./lib/index.js, dsh.bundle.patch
├── cordis.patch.yml      # - insert: [{ id: git-hygiene, name: 'dsh-git-hygiene' }]
├── scripts/              # setup-dsh-deps / build.sh / build-win.mjs（纯 tsc 构建）
├── src/
│   ├── index.ts          # apply(ctx)：注册 git_hygiene 工具 + 配置读取
│   ├── audit.ts          # 编排：只读 git 命令序列 + 大文件 stat
│   ├── git.ts            # 白名单执行器（破坏性命令一律拒绝）
│   ├── scan.ts           # git 输出解析 + 严重度/建议/渲染
│   └── types.ts          # canonical 类型 + 配置
└── tests/                # node --test（22 用例，真实 git 临时仓库端到端）

开发 / 测试 / 构建

npm install && npm run setup
npm test                # node --test（22 用例，含真实 git 建仓）
npm run build:win       # Windows 构建；POSIX 用 npm run build

构建产物 lib/ 入库提交（GitHub 源安装免构建）。

License

BSD-3-Clause。见 LICENSE。