dsh-zgit

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

工具一览

另有面向人机交互的斜杠命令 /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 生成一个普通目录，外加：

<dir>/
├── .zerogit/
│   ├── meta.json   # 源地址、ref、sha、归档 URL、抓取时间、文件统计
│   └── HEAD        # 固定的提交 sha
└── ...             # 解压出的源码（已去掉单一顶层目录）

zgit_status <dir> 会重新解析固定的 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