dsh-zgit
English | 中文
dsh-zgit（/zgit 插件）是一个 DeepSeek Harness（dsh）插件：当需要从 git 仓库拉取源代码或二进制发行版时，第一想法不再是 git clone，而是更敏捷的纯 HTTPS 方案（甚至直接"模拟 git"）。
它无需 git 二进制、零运行时依赖：
文档： https://zukunftsholz.github.io/dsh-zgit/
- 源代码 → 直接下载代码托管平台的源码归档（codeload 风格的 tar.gz/zip），解压成带
.zerogit元数据的模拟检出目录（simulated checkout），可以查看、status检查、随时刷新。 - 二进制发行版 → 从 GitHub / GitLab / Gitee 的 Releases 直接列出或下载产物，支持 sha256 校验（自动识别随包发布的校验文件）。
- 模拟 git →
zgit_ls_remote、zgit_show、zgit_ls_tree、zgit_log、zgit_diff、zgit_status用托管平台 API 重新实现了 git 的"读"侧。 - 其他一切 →
zgit_download把任意直链（镜像、工具链）下载进工作区，带字节上限与可选 sha256。
dsh plugin --profile web add dsh-zgit
# ……或从 Git 安装（不需要 npm 账号）：
# dsh plugin --profile web add github:zukunftsholz/dsh-zgit
# ……或本地检出目录：
# dsh plugin --profile web add ./dsh-zgit
工具一览
| 工具 | 对应 git | 功能 |
|---|---|---|
zgit_ls_remote |
git ls-remote |
分支、标签、ref→sha 解析、默认分支、最新 release 标签。 |
zgit_clone |
git clone / git archive |
按 ref 下载源码归档并解压为模拟检出（.zerogit/meta.json），支持 subdir 稀疏检出与显式归档 URL（镜像）。 |
zgit_fetch_release |
gh release download |
列出或下载发行版产物（最新或指定 tag），支持 glob 匹配与 sha256 校验。 |
zgit_show |
git show |
按 ref 拉取单个原始文件（可选保存到工作区）。 |
zgit_ls_tree |
git ls-tree |
通过平台 API 列出某 ref 下的文件/目录。 |
zgit_log |
git log |
某 ref 的最近提交。 |
zgit_diff |
git diff |
比较两个 ref：变更文件汇总，或单个文件的 unified diff。 |
zgit_status |
git status + git fetch |
检查模拟检出与远端是否同步：ref 是否移动、落后多少提交。 |
zgit_download |
curl |
任意 HTTPS 直链下载进工作区，带上限与可选 sha256。 |
另有面向人机交互的斜杠命令 /zgit（Web 输入栏 / TUI）：clone、get、show、ls、log、diff、resolve、status、download —— 不经过模型，直接执行同样的操作。
平台支持
- GitHub（
github.com+api.github.com+codeload.github.com+raw.githubusercontent.com） - GitLab（
gitlab.com+ API v4），支持嵌套分组 - Gitee（
gitee.com+ API v5） - 通用 GitHub 风格自建主机（Gitea / GHE 等）：归档/原始文件 URL 可用；依赖 API 的操作会给出明确报错——改用
archiveUrl或zgit_download。
仓库引用支持 owner/repo、owner/repo@ref、完整 https:// URL（可带 @ref 或 /tree/ref）、git@host:owner/repo.git 与 ssh:// URL。
配置
配置写在插件行上（$DSH_HOME/cordis.patch.yml、profile patch 或 overlay）：
- id: zgit
config:
clone: true # 各工具开关：lsRemote, clone, release, show,
command: true # lsTree, log, diff, status, download, command
timeoutMs: 120000
maxArchiveBytes: 536870912 # clone 归档上限 512 MiB
maxDownloadBytes: 1073741824 # 下载上限 1 GiB
maxFileBytes: 262144 # zgit_show 上限 256 KiB
maxTreeEntries: 5000
maxLogCommits: 30
maxDiffChars: 100000
maxExtractedEntries: 100000
workspaceRoot: '' # 兜底根（默认 process.cwd()）；工具调用优先使用调用方会话工作区
userAgent: dsh-zgit/0.2.3
tokenEnv: { github: GITHUB_TOKEN, gitlab: '', gitee: '' } # 环境变量名
tokens: { github: '', gitlab: '', gitee: '' } # 或直接填 token
Token 可提高 API 限流配额并支持私有仓库；环境变量名优先于直接配置值。
模拟检出（simulated checkout）
zgit_clone 生成一个普通目录，外加：
/
├── .zerogit/
│ ├── meta.json # 源地址、ref、sha、归档 URL、抓取时间、文件统计
│ └── HEAD # 固定的提交 sha
└── ... # 解压出的源码（已去掉单一顶层目录）
zgit_status 会重新解析固定的 ref，报告检出落后了多少提交；用 zgit_clone (replace: true) 刷新。
安全特性
- 工作区约束 —— 所有写入都解析在调用方会话工作区（
exec.agent.session.header.cwd）之内，无会话调用回退到workspaceRoot；越界路径直接拒绝。 - 归档加固 —— 拒绝路径穿越（
..、绝对路径、Windows 保留名）；大小写不敏感冲突报错；条目数与总字节数双重上限；zip 条目做 CRC32 校验；gzip 解压设有硬上限（防解压炸弹）；符号链接只记录不落地，硬链接复制内容。 - 处处有字节上限 —— 下载采用流式读取，超限立即中止。
- 绝不执行 —— 归档只解压，从不运行。
开发
本包零运行时依赖（只用 Node 内置模块：node:zlib、node:crypto、node:fs 等），面向 DSH 0.1.7-rc.2（cordis 4.0.4、schemastery 3.18.4），同时兼容 0.1.5-rc.2。测试针对项目自身锁定的 @deepseek-ai/* devDependencies 运行（即本包声明、CI 安装的版本）：
npm run build # scripts/build.sh（DSH checkout + junction + tsc），由 node 包装器调用
npm run typecheck
npm test # vitest：解析/glob 单测、tar.gz+zip 解压、平台 fixture、真实 HTTP 端到端、Cordis 挂载
常见问题（FAQ）
dsh-zgit 是什么？
dsh-zgit（zgit）是一个 DeepSeek Harness 插件，通过纯 HTTPS 从 git 仓库拉取源码归档与发行版产物，不需要 git 二进制，也不引入运行时依赖。
需要先装 git 吗？
不需要。全部走托管平台的归档、原始文件与 Release 接口。
支持哪些平台？
GitHub、GitLab（API v4，支持嵌套分组）、Gitee（API v5）。通用 GitHub 风格自建主机（Gitea、GitHub Enterprise）的归档/原始文件 URL 可用；依赖 API 的操作会明确报错，可改用 archiveUrl 或 zgit_download。
怎么安装？
dsh plugin --profile web add dsh-zgit（npm 已发布）。也可以用 Git 形式 github:zukunftsholz/dsh-zgit，或本地检出目录 ./dsh-zgit。
它能替代 git 吗？
它用平台 API 重新实现了 git 的"读"侧（ls-remote、show、ls-tree、log、diff、status），外加发行版产物下载；不做写操作、不 push。
下载会校验吗？
发行版产物与 zgit_download 支持按随包校验文件做 sha256 校验；zip 条目做 CRC32 校验；gzip 解压设硬上限（防解压炸弹）。
面向哪个 DSH 版本？
DSH 0.1.7-rc.2（cordis 4.0.4、schemastery 3.18.4），同时兼容 0.1.5-rc.2。
许可证？
MIT。
License
MIT
