前言¶

在 DSH（DeepSeek Harness）里让 Agent 读分支、看 diff、甚至改工作区，常见做法是自己在会话里贴命令输出，或把令牌写进环境变量——前者信息零散，后者权限边界难控。社区插件 @zjj/dsh-git-panel（仓库 zjj1769404838/dsh-git-panel）把账号接入、范围闸门、图形化工作台和 8 个 git_* Agent 工具收进同一套插件：配置集中在 DSH 设置页的 Git 分节，输入框下方用 opencode 风格的分支 chip 作唯一入口。下面介绍它解决什么问题、怎么装、以及使用前必须配好的授权范围。

这是什么¶

@zjj/dsh-git-panel 是 DSH 桌面端插件（npm 包名 @zjj/dsh-git-panel，当前资料中版本 0.1.0，MIT 许可证），维护者为 zjj1769404838。定位是：Git 账号接入 + 受控仓库操作——OAuth 设备码或个人访问令牌（PAT）连接 GitHub / GitLab / Gitea，令牌 AES-256-GCM 落盘且界面与接口不回显明文；本地 git 与平台 REST 走统一闸门（allowedRoots、allowedRepos、账号级 full / read / none）；同时提供 Git 工作台 UI 与 Agent 可调工具。

DSH 生态是「一切皆插件」；插件目录页在 skillhub.cn，与 DeepSeek / 幻方无官方从属关系，本文仅依据仓库 README 与 package.json 说明能力。

核心功能¶

界面入口与 Git 工作台¶

• 设置页：宿主左侧导航新增 Git 分节（settings.section，order: 20），含账号、仓库范围、写开关、界面偏好等。
• 输入区 chip：会话输入框下方左侧显示分支状态（如 ⎇ main ↑2 3*）；非 Git 目录时灰化 Git 入口；点击弹出分组菜单（未初始化 → 初始化向导；已初始化 → 工作台 / 刷新 / 分支详情 / 打开目录 / Git 设置）。状态不在后台轮询，仅在 cwd 变化、窗口获焦、页面可见、打开菜单等时机刷新。
• Git 工作台：居中模态，顶部页签为改动 / 历史 / 文件 / 标签 / 贮藏；改动页双栏（左列表 + 右就地 diff）；历史支持关键词搜索与泳道拓扑；差异模块支持行号、四种布局、词级高亮、Prism 语法高亮等。
• 初始化：未初始化目录可走单页表单 + 右侧执行计划，支持选已有远程、新建远程仓库或手工 owner/repo，执行端为 POST /repo/bootstrap（本地操作，不自动 push）。

账号与权限¶

• 接入方式：OAuth 设备码（需自备各平台 OAuth App Client ID）或 PAT。
• 账号 → 仓库：每个账号卡片内联平台侧全部远程仓库；每行三档 完整 / 只读 / 无权限，点选即 POST /repo/permission 提交。
• 全局范围（必须配置，否则 Agent 拒绝一切操作）：
• allowedRepos：每行 owner/repo，* 表示不限远程仓库白名单。
• allowedRoots：本机绝对路径白名单，* 表示不限制目录。
• allowWrite：默认关闭；开启后仍默认 requireConfirm 二次确认。
• 远端写操作：fetch / pull / push / remotes-add 等按 remote 的 owner/repo 校验账号是否为 full，否则 403。

Agent 工具（8 个）¶

约束要点：未授权路径不泄露「是否为 git 仓库」；git_write 在 requireConfirm 开启时先返回 pending 与 confirmToken，确认前状态不变；执行走 execFile('git', args)，拒绝危险参数注入。README 注明写操作白名单不含 push / reset --hard / clean -fdx，需人工处理时可自行在终端操作。

凭据与数据路径¶

安装与启用¶

从 Git 源安装（仓库已含 lib/ 构建产物）：

dsh plugin --profile desktop add github:zjj1769404838/dsh-git-panel

本地开发时先构建再以 link 安装：

npm install --include=dev
node scripts/build.mjs
dsh plugin --profile desktop add link:/absolute/path/to/dsh-git-panel

装完后重启 DSH 桌面端（node 侧路由与工具在启动时加载）；若只改 client 模块，在 GUI 中 Ctrl+Shift+R 硬刷新即可。

卸载：

dsh plugin --profile desktop remove @zjj/dsh-git-panel

典型用法¶

1. 连接账号¶

打开 设置 → Git → 账号，点「连接账号」：

• OAuth（本机有人点浏览器）：选平台 → 接入方式 OAuth → 填写 Client ID → 连接；GitHub 走设备码流程，浏览器输入 8 位代码后轮询换令牌。
• PAT（CI / 最小权限）：接入方式选 PAT → 粘贴令牌 → 连接；可在平台侧限制 scope 或 fine-grained 仓库范围。

多账号时可指定默认账号，Agent 侧优先使用。

2. 配置仓库范围（必做）¶

在 设置 → Git → 仓库范围 填写：

• 允许的远程仓库（例：myorg/my-app，或一行 *）。
• 允许的本机目录（例：/home/you/projects/my-app 的绝对路径）。
• 按需开启「允许写操作」；建议保持「写操作需要二次确认」为开启。

范围为空时策略为 fail-closed（全部拒绝）。路径按段匹配，D:\repo-evil 不会命中 D:\repo。

3. 从 chip 进入日常工作流¶

在已授权且已初始化的项目会话中：

1. 看输入框下 chip 的分支与 dirty 状态。
2. 点 chip → Git 工作台，在「改动」页暂存、写提交信息（可用「AI 生成」，依赖宿主 ctx.llm）、提交；右栏查看 diff。
3. 需要 push 且无上游时，界面会提示「发布分支」（git push -u），仍受写开关与远端 full 权限约束。

未初始化目录：菜单选 初始化 Git 项目，左侧选账号与远程，右侧看计划清单后提交；目录须已通过 allowedRoots 授权。

4. Agent 侧受控写入¶

在开启 allowWrite 且 Agent 被允许调用插件工具的前提下，写操作典型路径为：

1. Agent 调用 git_write（例如 add + commit）。
2. 若 requireConfirm 为真，得到 summary 与 confirmToken，用户或 Agent 再调 git_confirm 才真正执行。

未配置授权范围或写开关关闭时，工具与 HTTP 写端点会直接拒绝。

适用场景与注意¶

适合：在 DSH 桌面端统一管 GitHub/GitLab/Gitea 账号；希望 Agent 只读查状态、diff、log，或在明确闸门与二次确认下做有限写操作；需要内置工作台而不反复切终端。

注意：

• 插件以当前 DSH 进程权限运行，安装前请自行审阅 源码与 LICENSE，勿把超出需要的 PAT 或过宽的 allowedRoots（如整盘 *）交给生产环境。
• OAuth 需自备 Client ID；插件不分发 Client Secret，也不做 OAuth 回调服务器。
• node 半边改动需重启 DSH；client 改动硬刷新即可。
• git_remote_info 受平台 API 限流影响，限流时返回 429 提示。

结尾¶

@zjj/dsh-git-panel 把 Git 账号、目录与远程仓库三道闸门、图形工作台和 Agent 工具放在同一插件里，默认偏安全（不写盘、不泄露未授权路径、写操作可确认）。若要在目录里试用，可从社区页了解收录信息：https://www.skillhub.cn/plugins/zjj1769404838/dsh-git-panel；安装与细节以 GitHub 仓库为准：https://github.com/zjj1769404838/dsh-git-panel。