前言¶

在 DeepSeek Harness（DSH）里做智能体或项目开发，工作区往往已经落在 Git 仓库上，但日常改文件、暂存、提交、拉取和推送，仍要切到终端或外部 GUI。DSH Web 右侧栏若已有 Better Sidebar，缺的是一块与当前 workspace 绑定的版本控制面板：能看清本地变更、可控地暂存与提交，并在写操作前给出可读的预览与确认。下面介绍社区插件 dsh-knj-version-control（维护者 yangdongzhen590），它在 Web 侧注册 Version Control 标签页，把 Local Changes、Commit、Update、Push 和切换分支收进同一工作台，且 Git 失败时输出可展开、可复制的主机错误码与 git 原文。

这是什么¶

dsh-knj-version-control 属于 KNJ 家族插件，定位为 DSH Web 上的 KNJ version-control workbench：本地变更列表、单文件与多文件暂存、经确认的 commit / update / push，以及可读的 Git 失败详情。实现上通过公共 API dsh-better-sidebar.registerTab() 集成，不导入、也不修改 Better Sidebar 的私有 UI、状态或 Git 代码。分类为客户端；package.json 中版本为 2026.9.200，仓库见 GitHub，目录页见 SkillHub。

宿主与前置条件¶

Better Sidebar（可选 peer）

• peerDependencies 要求 dsh-better-sidebar >= 0.15.2，并标记为 optional。
• 宿主缺少 Better Sidebar 或版本更低时，安装不会被阻断；运行时会自检，在控制台告警后优雅退出，不影响其他插件。
• 本插件不对 sidebar 做精确版本钉；若 profile 需要统一 sidebar 版本，可在 profile 的 pnpm-workspace.yaml 里自行 overrides。

运行环境（来自 package.json）

• Node：>= 22.19.0
• DSH：>= 0.1.0-rc.6
• 客户端注入：betterSidebar，平台 web

Git 与工作区

• 主机 PATH 上须已安装并可执行 git。
• 当前 DSH 会话需要 workspace；非 Git 工作区仍可打开，界面会显示非仓库状态。
• 提交身份（user.name / user.email 等）须用户事先配置；插件不会修改 identity、remote、credential 或其他 Git 配置。

核心功能（v1）¶

工作台在侧栏以图标注册 Version Control 标签，带变更数量 badge，并采用 single 策略（再次打开会聚焦已有标签）。标签内主要区域如下。

工具栏与状态

• 分支胶囊：当前分支及 ↑ahead / ↓behind；可刷新；Update（fetch + 条件允许时 fast-forward pull，带预览）。
• 状态行：HEAD 分支、upstream、干净或 N change(s)。

Local Changes

• 按类型分组：Modified / Added / Deleted / Untracked / Conflicted，含每组数量、折叠、状态芯片与勾选框。
• 暂存：在仓库支持 staging 时，非冲突行有「暂存」/「取消暂存」；多选区有「暂存所选 (N)」/「取消暂存所选 (N)」；组头有「全部暂存」/「全部取消暂存」。已进 index 的行标 已暂存；冲突行 deliberately 不提供暂存（冲突解决应在工作台外完成）。
• 点击文件行进入独立 diff 页（优先工作区 diff，否则 staged）；并排 diff 为后续阶段预留。

分支与提交

• 点击分支胶囊：列出本地与远程分支并支持搜索；本地分支经预览确认后 git switch；远程分支在 v1 仅提示预留行为。
• Commit 框：说明提交范围（git commit --only 作用于勾选文件，避免把 index 状态误当成提交内容）；支持 Commit 与 Commit and Push…（先 commit 确认再 push 确认）。Amend 预留。
• 可选 「提交前暂存已选」（默认关闭）：启用时顺序为 stage → preview → confirm。

视图预留

• Changes 为默认；Log、Console 在 v1 为占位，不加载数据。

失败反馈

• commit、push、update、切换分支或暂存失败时，弹出可关闭的失败详情对话框：映射摘要、主机 failure code、可展开/选中/复制的 Git 输出；确认流程内的失败会替换确认框，而不是静默 toast。

安全与更新策略（设计要点）¶

• 不提供任意命令输入：Git 调用均为 execFile('git', fixedArgs)。
• Commit、Push、分支 switch 先产生 preview token，再需显式确认；token 与根路径、操作、参数、fingerprint、过期绑定，仓库状态变化会使 token 失效，有效 token 一次性消费。
• Update：总是先 fetch。可 fast-forward 时用 git pull --ff-only（仍受 fingerprint 约束；Git 拒绝覆盖未提交变更时会展示拒绝原因）。历史分叉时按 merge 拉取（git pull --no-rebase），需确认并提示可能冲突；不自动 resolve、不 auto-stash、不 rebase、不 force-push、不自动重试 push。
• v1 中暂存走同源 /stage 端点（无 preview token），仅改可逆的 index；失败同样带 code 与 Git 输出。
• 暂存与提交勾选联动：暂存会勾选该路径，取消暂存会取消勾选，避免「已暂存却未纳入提交意图」的 silent 遗漏。
• 首版 仅 Git；SVN 等为后续边界（README 中 SVN 段在截断处说明 Git-only）。

进行中的刷新、预览、确认、暂存或 update 时，状态行显示 spinner，工具栏按钮禁用，同一时刻只允许一个 Git 写操作在飞。

安装与启用¶

在 DSH 安装目录/checkout 中，通过 DSH 的 plugin/profile 路径添加本地包（README 明确：不要直接把文件拷进 node_modules）。官方示例为 Windows 本地路径：

dsh plugin --profile web add D:\workspace\iobs_pro\plugins\dsh-knj-version-control

将路径换成你本机 clone 或下载后的插件目录即可；具体是否从 GitHub 拉源码由你自行决定，本文不给出 git clone 步骤。

随后按你所用 DSH 版本要求重启或 rebuild/reload 相关 Web 产物，再在浏览器刷新已有 GUI（README 示例地址为 http://127.0.0.1:3080）。

注意：package.json 须为 UTF-8 无 BOM；DSH 用裸 JSON.parse 读 profile 与插件元数据，BOM 可能导致启动失败。

典型用法（可复现流程）¶

1. 确认主机已装 git，且当前 DSH 会话绑定了 Git workspace；在 Web GUI 打开 Better Sidebar 的 Version Control 标签。
2. 在 Changes 查看分组后的本地变更；对需要纳入下次提交的文件勾选，并按需使用行级或批量「暂存」/「取消暂存」。
3. 需要看差异时点击文件行，在 diff 页查看（v1 说明为「工作区 vs HEAD」；部分暂存文件展示的是未 staged 的 delta）。
4. 填写 commit message，使用 Commit；若需推送，用 Commit and Push… 完成两段确认。
5. 同步远程：工具栏 Update 执行 fetch；fast-forward 可直接 pull；存在分叉时需阅读确认框中的 merge 警告后再确认。
6. 切换本地分支：点分支胶囊，选择本地分支，在预览确认通过后再执行 switch；工作区脏时确认框会提示，是否继续由 Git 决定。
7. 任一步失败：阅读失败详情对话框中的 Git 原文，在工作区或外部工具中处理冲突或配置问题后，再刷新重试。

适用场景与注意¶

适合谁

• 已在 DSH Web + Better Sidebar 环境中开发，希望把「看变更 → 暂存 → 提交 → 拉取/推送 → 切分支」留在浏览器侧栏完成的人。
• 重视写操作前预览确认、以及失败时保留完整 Git 输出，而不是只看一闪而过的提示。

务必知晓

• 插件以当前 DSH 进程权限在主机上执行 git；安装前请自行审阅 源码与许可证，确认符合你的安全与合规要求。
• 社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系；DSH 生态是「一切皆插件」，本文介绍的是社区维护的客户端插件。
• README 截断处仍强调 Git-only 与 host workflow 概念分离；不要指望 v1 提供完整 Log 控制台或 SVN。

结尾¶

dsh-knj-version-control 把 Git 日常操作收进 DSH Web 右侧 Version Control 工作台：结构化 Local Changes、可控暂存、带 token 的 commit/push/switch/update 确认，以及失败时的可读 Git 输出。若你的 profile 已启用 Web 与 Better Sidebar，可按 README 的安装路径接入本地包并刷新 GUI 试用。

• 目录页：https://www.skillhub.cn/plugins/yangdongzhen590/dsh-knj-version-control
• GitHub：https://github.com/yangdongzhen590/dsh-knj-version-control