dsh-repo-push
Verifieddsh-repo-push · v0.2.1 · MIT
Let DSH agents commit and push a whitelisted git repository from the host process — works inside the Windows workspace-write sandbox
Install
dsh plugin add dsh-repo-push Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
dsh-repo-push
DSH 宿主插件:让 agent 在 workspace-write 会话里照常
在宿主进程里提交并推送 git 仓库。注册一个原生工具 repo_push;典型用途是 agent 自己维护的文档 / 知识库仓库。
为什么需要它
Windows 下 DSH 用「受限令牌 + Low 完整性 + write-restricted SID」隔离子进程。受限进程无法为子进程创建管道
stdio(命名管道 client 端拿不到 restricting SID 授权),而 git 的远端传输——ssh.exe、git-remote-https、
git-receive-pack——全部靠管道:
error: cannot create standard input pipe for ...\System32\OpenSSH\ssh.exe: Permission denied
fatal: unable to fork
这与 SSH、认证、远端无关:换 https:// 报的是 cannot create standard input pipe for remote-https。
本地 add / commit 不受影响,只有跨进程的网络传输会挂。
本插件把 add → commit → push 搬进 DSH 宿主进程(宿主本来就要 spawn MCP 服务器与原生 worker),
会话保持沙箱,推送不再需要审批。
安装
dsh plugin --profile <profile> add dsh-repo-push
本地开发(源码方式):
dsh plugin --profile <profile> add "$DSH_HOME/tools/dsh-repo-push"
# 链接安装的 ESM 不热重载:改完 lib/* 需 disable/enable 该行(或重启 DSH)
插件是一个 bundle 补丁,只插入一行(id: repo-push)。
配置
- id: repo-push
name: dsh-repo-push
config:
repos:
- C:/Users/me/notes # 允许推送的仓库根,可多个
- C:/Users/me/handbook
defaultRepo: C:/Users/me/notes
remote: origin
allowPush: true
allowDefaultRepo: false
timeoutMs: 120000
gitPath: git
| 键 | 类型 | 默认 | 含义 |
|---|---|---|---|
repos |
string[] |
[] |
允许推送的仓库根白名单。绝对路径原样使用;相对路径按会话工作区解析,且只在该子目录存在时生效;~ 展开为用户目录。为空时只允许当前会话工作区;没列出的都禁止。 |
patterns |
string[] |
[] |
额外授权的 glob 模式(见下文)。相对模式比对相对会话工作区的路径,绝对模式比对绝对路径。只负责授权,不参与默认仓库选择。 |
defaultRepo |
string |
"" |
调用未给 repo 时用的仓库;仅在 allowDefaultRepo: true 时生效。 |
remote |
string |
origin |
推送目标远端,必须已存在。 |
sync |
'none' | 'ff-only' | 'rebase' |
'ff-only' |
推送前先 fetch 并与远端对齐(见下文)。 |
allowPush |
boolean |
true |
设为 false 则只提交不推送。 |
allowDefaultRepo |
boolean |
false |
false 时每次调用都必须给 repo;设 true 才允许回落到 defaultRepo / 会话工作区。 |
timeoutMs |
number |
120000 |
单条 git 命令超时。 |
gitPath |
string |
git |
git 可执行文件路径或命令名。 |
配置有错不会阻塞宿主加载:插件照常注册,调用时返回 invalid-config 并列出具体问题。
白名单就是安全边界
repos 是唯一阻止工具往非预期仓库推送的东西——没列出的仓库一律拒绝。调用里的 repo(或解析出的默认值)
会先解析符号链接,必须落在某个配置根内,否则返回 invalid-args。只放文档仓。
一份配置服务多个工作区
相对路径在每次调用时按会话工作区解析,且只有当前工作区里确实存在这个子目录时才生效。这样能适配 “每个工作区把文档仓放在不同位置”的布局:
repos:
- docs/team-notes # 文档仓放在 docs/ 下的工作区命中它
- team-notes # 放在工作区根目录的工作区命中它
只有设了 allowDefaultRepo: true,调用才允许省略 repo,解析顺序是:defaultRepo → 唯一可用根 → 包含会话工作区的那个根。默认 false 时,不给 repo 一律拒绝——工具不会自己挑仓库。若还剩多个候选、
且都不包含工作区,调用直接报错,要求显式传 repo——绝不猜,猜错就会推到别人的仓。
同一个仓库的多份检出(例如同一文档仓在两个工作区各检出一次)如果都列进白名单,两处都能推。 约定只在一处改并推送,另一处
pull对齐;两边各改必分叉。
按目录名匹配
多个工作区里文档仓的目录名不一致时,用 pattern 可以省掉每个工作区一条:
repos:
- docs/team-notes # 省略 repo 时给个默认(需 allowDefaultRepo: true)
- team-notes
- project-notes
- ~/.dsh
patterns:
- '**/*-notes' # 任意工作区里的 *-notes 都放行
** 跨目录分隔符,* 与 ? 不跨。相对模式比对的是相对会话工作区的仓库路径,所以够不到工作区之外;
绝对模式比对绝对路径。
pattern 刻意不做两件事:
- 不参与默认仓库选择:
repo_push({})仍要有具体根(来自repos/defaultRepo)。只配 patterns 时必须传repo。 - 不会回落成"整个工作区":只配
patterns不配repos时的含义是"只有命中的仓",不是"工作区全放行"—— 根目录的仓库依然被拒。
模式要收紧:**/*-notes 也会匹配 old-notes。
用法
repo 默认必填(只有配置 allowDefaultRepo: true 才能省略)。
repo_push({ repo: ".", paths: ["skills/a.md", "README.md"], message: "docs: 更新" }) # 提交并推送
repo_push({ repo: "." }) # 只推送已有提交
repo_push({ repo: "notes", paths: ["daily/2026-11-04.md"], message: "..." }) # 指定另一个仓库
repo_push({ repo: ".", paths: ["x.md"], message: "...", push: false }) # 只提交
paths是相对仓库根的显式路径,逐条校验;绝对路径与..越界都会被拒。- 提交信息走 stdin,中文与多行安全。
- 只提交列出的路径,不碰别人暂存的内容。
- 不做 force push、不改远端与配置。
返回:
{
"ok": true,
"action": "committed-and-pushed",
"repo": "/path/to/repo",
"branch": "main",
"commit": "<sha>",
"pushed": true,
"upToDate": false,
"code": "ok",
"detail": "abc1234..def5678 main -> main",
"output": "..."
}
action:committed-and-pushed / pushed / committed / nothing-to-do / sync-failed /
commit-failed-sync / push-failed / commit-failed-push / failed。
推送前先与远端对齐
沙箱里 git pull 同样跑不了(一样的管道限制),所以这一步由工具代劳:
sync |
行为 |
|---|---|
ff-only(默认) |
git fetch 后,只有本地没有远端缺少的提交时才快进合并;分叉则返回 non-fast-forward,不改历史。 |
rebase |
git fetch 后把本地提交重放到远端之上(--autostash,工作区有未提交改动也能跑)。冲突会 abort,仓库恢复到 rebase 之前。 |
none |
直接推;分叉时返回 non-fast-forward。 |
只会重写尚未推送的本地提交,且只发生在 rebase 模式。工具永不 force push。
fetch 超时或网络抖动不会卡死推送:同步被跳过并在结果里注明,推送照常尝试; 只有 rebase 冲突这类需要人处理的情况才会中止。
失败码
| code | 含义 / 下一步 |
|---|---|
auth |
SSH / HTTPS 凭据被拒。修凭据,别盲目重试。 |
network |
DNS、连接失败或代理问题。 |
non-fast-forward |
远端有你没有的提交。设 sync: rebase,或先 pull --rebase 再推;本工具永不强推。 |
rebase-conflict |
sync: rebase 遇到冲突;已 abort,仓库保持原样,需人工处理。 |
not-a-repo / detached-head |
不是 git 工作区,或 HEAD 处于游离状态。 |
path-not-matched |
paths 里有工作区中不存在的路径。 |
timeout |
超过 timeoutMs;查网络或推送体积。 |
invalid-args / invalid-config |
调用或插件配置有误,没有执行任何命令。 |
安全模型
- 工具刻意在宿主进程执行 git——这才是绕开管道限制的关键。白名单是权限边界:白名单内的仓库, agent 可以推任意内容。
- 只执行
add -- <paths>/commit -F - -- <paths>/push <remote> <branch>;无 force push、 无 remote 改写、无任意 shell。 - 用的是当前用户凭据(
~/.ssh或凭据助手);agent 密钥应无口令,宿主里无法交互输入。
安全
本包在宿主进程里执行 git(这正是它的用途),会读写白名单仓库里的文件,并用你的凭据访问网络。
零运行时依赖、无安装脚本。白名单就是安全边界。
威胁模型与漏洞报告方式见 SECURITY.md。
平台支持
| 平台 | 沙箱机制 | 沙箱内 git push |
本插件 |
|---|---|---|---|
| Windows | 受限令牌(Low 完整性、write-restricted SID) | 被拒——令牌无法为子进程创建管道 stdio(cannot create standard input pipe / unable to fork) |
必需 |
| Linux | bubblewrap / Landlock | 正常 | 可选 |
| macOS | Seatbelt(sandbox-exec) |
正常 | 可选 |
POSIX 后端只限制文件写入,不阻止进程以管道方式启动子进程,所以 git 的传输在那些沙箱里照常工作。 本插件在所有平台都能正常运行(只是把 git 放到宿主进程跑),常开无副作用——只有 Windows 需要它。
CI 在 Linux 与 Windows、Node 20 与 22 上跑测试。
开发
npm test # node test/run.mjs —— 零依赖单进程(不 spawn 子进程)
测试器是普通脚本而非 node --test:后者会为每个文件 spawn 子进程,正好是受限沙箱拒绝的操作。
许可
MIT