dsh-zgit
English | 中文
> [!TIP] > 第一个《世界计划》本地化知识库，为同人作者和考据党而生：SekaiSync > **The first Project SEKAI localization knowledge base, built for fan creators and lore enthusiasts: SekaiSync** > > 即将面向 DeepSeek Harness 插件生态针对性适配，欢迎各位豆腐人 Star 和共建。 > Targeted adaptation for the DeepSeek Harness plugin ecosystem is coming soon. Fellow Tofus are welcome to star and contribute!
zgit — a DeepSeek Harness plugin for when the first thought about fetching source code or binary releases from a git host should not be git clone.
dsh-zgit fetches over plain HTTPS, with no git binary and no runtime dependencies:
- Source code → downloaded as a forge archive (codeload-style tar.gz/zip), extracted into a simulated checkout with
.zerogitmetadata — a git-like directory you can inspect,status-check, and refresh. - Binary releases → release assets listed or downloaded straight from GitHub/GitLab/Gitee releases, with sha256 verification against shipped checksum files.
- git, simulated →
zgit_ls_remote,zgit_show,zgit_ls_tree,zgit_log,zgit_diff,zgit_statusreimplement the read side of git over the forge APIs. - Anything else →
zgit_downloadfetches any direct URL (mirrors, toolchains) into the workspace with a byte cap and optional sha256.
dsh plugin --profile web add @zukunftsholz/dsh-zgitTools
| Tool | git analog | What it does |
|---|---|---|
zgit_ls_remote | git ls-remote | Branches, tags, ref→sha resolution, default branch, latest release tag. |
zgit_clone | git clone / git archive | Downloads the source archive at a ref, extracts it into the workspace as a simulated checkout (.zerogit/meta.json), supports subdir sparse extraction and explicit archive URLs (mirrors). |
zgit_fetch_release | gh release download | Lists or downloads release assets (latest or a tag) with glob patterns and sha256 verification. |
zgit_show | git show | Fetches one raw file at a ref (optionally saved into the workspace). |
zgit_ls_tree | git ls-tree | Lists files/dirs at a ref via the forge API. |
zgit_log | git log | Recent commits at a ref. |
zgit_diff | git diff | Compare two refs: changed-files summary or a single-file unified diff. |
zgit_status | git status + git fetch | Checks a simulated checkout against the remote: moved ref, commits behind. |
zgit_download | curl | Any direct HTTPS download into the workspace, capped, with optional sha256. |
Plus the human-plane command /zgit (Web UI slash menu / TUI): clone, get, show, ls, log, diff, resolve, status, download — the same operations without the model in the loop.
Forge support
- GitHub (
github.com+api.github.com+codeload.github.com+raw.githubusercontent.com) - GitLab (
gitlab.com+ API v4), including nested groups - Gitee (
gitee.com+ API v5) - Generic GitHub-style hosts: archive/raw URL guessing works (self-hosted Gitea/GitHub Enterprise); API-backed operations report a clear error — use
archiveUrlorzgit_download.
Repo references accept owner/repo, owner/repo@ref, full https:// URLs (with @ref or /tree/ref), git@host:owner/repo.git, and ssh:// URLs.
Configuration
All config lives in the plugin row ($DSH_HOME/cordis.patch.yml, the profile patch, or an overlay):
- id: zgit
config:
clone: true # per-tool toggles: lsRemote, clone, release, show,
command: true # lsTree, log, diff, status, download, command
timeoutMs: 120000
maxArchiveBytes: 536870912 # 512 MiB clone cap
maxDownloadBytes: 1073741824 # 1 GiB download cap
maxFileBytes: 262144 # 256 KiB zgit_show cap
maxTreeEntries: 5000
maxLogCommits: 30
maxDiffChars: 100000
maxExtractedEntries: 100000
workspaceRoot: '' # fallback root (defaults to process.cwd()); tool calls prefer the calling session workspace
userAgent: dsh-zgit/0.1.1
tokenEnv: { github: GITHUB_TOKEN, gitlab: '', gitee: '' } # env var names
tokens: { github: '', gitlab: '', gitee: '' } # or direct valuesTokens raise API rate limits and enable private repos; the env-var name wins over a direct value.
The simulated checkout
zgit_clone produces a normal directory plus:
<dir>/
├── .zerogit/
│ ├── meta.json # origin, ref, sha, archive URL, fetched-at, file counts
│ └── HEAD # the pinned commit sha
└── ... # the extracted source (root folder stripped)zgit_status <dir> re-resolves the pinned ref remotely and reports how far the checkout fell behind. Refresh with zgit_clone (replace: true).
Safety properties
- Workspace confinement — every write is resolved inside the calling session's workspace (
exec.agent.session.header.cwd), falling back toworkspaceRootfor agentless callers; paths escaping the root are rejected. - Archive hardening — path traversal (
.., absolute paths, Windows reserved names) is rejected; case-insensitive collisions error; entries are capped by count and total bytes; zip entries are CRC32-verified; gzip is decompressed under a hard cap (bomb guard); symlinks are recorded and skipped (not materialized), hardlinks are copied. - Byte caps everywhere — downloads stream with early abort when a cap is exceeded.
- No execution — archives are never executed, only extracted.
Development
The package has zero runtime dependencies (pure Node builtins: node:zlib, node:crypto, node:fs, node:http). Tests run against the installed DSH profile packages:
npm run build # scripts/build.sh (DSH checkout + junctions + tsc) via node wrapper
npm run typecheck
npm test # vitest: parser/glob units, tar.gz+zip extractors, forge fixtures, real-HTTP e2e, Cordis mountLicense
MIT