版本控制工作台 yangdongzhen590/dsh-knj-version-control

dsh-knj-version-control

KNJ 家族插件：在 DSH Web 右侧栏提供 Version Control 工作台（Git Local Changes / Commit / Update / Push / 切换分支，全部走预览确认的安全流程）。通过公共 dsh-better-sidebar.registerTab() API 集成，不导入也不修改 Better Sidebar 私有 UI/状态/Git 代码。

宿主兼容性

- Better Sidebar：peerDependencies: { "dsh-better-sidebar": ">=0.15.2" }，并标记为 optional。
实测 registerTab(descriptor: TabDescriptor): () => void 的签名与 TabDescriptor 字段在 0.15.2 / 0.16.1 / 0.17.1 / 0.18.0 间完全一致（0.19.1 仅新增可选字段 description），本插件只使用 id / title / icon / order / single / badge / component。
peer 标 optional 意味着：宿主缺少 Better Sidebar 或版本更低时，安装不会被阻断，插件运行时会自检并在控制台告警后优雅退出（不影响其他插件）。
- 不锁死宿主版本：本插件不对 dsh-better-sidebar 施加精确版本钉（不使用 overrides）。若你的 profile 需要统一某个 sidebar 版本，请在 profile 的 pnpm-workspace.yaml 里用 overrides 自行决定。

Install for the Web profile

From the DSH install checkout, add this local package through the DSH plugin/profile path (do not copy files directly into node_modules):

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

Restart or rebuild/reload the affected DSH Web artifacts as required by your installed DSH version, then refresh the existing GUI at http://127.0.0.1:3080.

package.json is UTF-8 without BOM. DSH reads profile and plugin metadata with bare JSON.parse; adding a BOM can prevent startup.

Prerequisites

- Git must be installed and available as git on the DSH host PATH.
- The active DSH session needs a workspace. A non-Git workspace remains readable and shows a non-repository state.
- Git commit identity must be preconfigured by the user; this plugin never changes identity, remote, credential, or other Git configuration.

Workbench layout (v1)

The Version Control tab registers with an icon, a change-count badge on the sidebar tab, and a single instance policy (reopening focuses the existing tab). Inside the tab:

- Toolbar — branch pill (current branch + ↑ahead ↓behind), refresh, and Update (fetch + fast-forward pull with preview).
- Status line — HEAD branch, upstream, and clean/N change(s) state.
- View tabs — Changes (default), plus Log and Console entries that are reserved for phase two (they render a reserved state and load no data in v1).
- Local Changes — changed files grouped by type (Modified / Added / Deleted / Untracked / Conflicted) with per-group counts, collapse toggles, status chips, and selection checkboxes.
- 暂存（单文件、多文件或整组） — 仓库声明支持 Git 暂存时，每个无冲突行都带自己的「暂存」/「取消暂存」操作，选择区提供「暂存所选 (N)」/「取消暂存所选 (N)」，可对任意多文件暂存；每个分组头提供「全部暂存」和「全部取消暂存」，只要组内还有已暂存路径就一直显示。带索引变更的行标记为 已暂存（部分暂存的行同时显示两个操作）。冲突行刻意不提供暂存操作：对冲突路径执行 git add 等于声明冲突已解决，冲突的解决留在工作台之外处理。
- 独立 diff 页面 — 激活文件行会打开独立 diff 视图（优先工作区 diff，回退到已暂存 diff），并带返回控件。并排视图暂未开放。
- 分支选择器 — 点击分支胶囊会列出本地和远程分支，支持搜索。本地分支通过预览并确认的流程切换；远程分支显示预留提示（后续阶段需要本地跟踪分支）。
- 提交框 — 消息区、主按钮 Commit，以及 Commit and Push…，后者串联一次提交确认和一次新的 Push 确认。Amend 暂未开放。提交框会说明提交范围（对勾选文件执行 git commit --only），避免把索引状态误当成提交内容。
- 确认弹窗在任何写入之前，准确报告将要执行的内容（目标分支/远程、传入/传出提交、工作区脏状态警告、pre-commit 暂存）。
- 失败详情对话框 — 提交、推送、更新、切换分支或暂存操作失败时，打开可关闭的对话框，显示映射后的摘要、宿主失败码和 Git 自身的输出（可展开、可选择、可复制），而不是一闪而过的 toast。已确认操作内部抛出的失败会替换确认对话框，而不是随对话框一起关闭。

安全行为

- 不接受任意命令输入：所有 Git 调用都使用 execFile('git', fixedArgs)。
- Local Changes、Diff、Log 和分支列表都是结构化 Git 操作。
- 暂存/取消暂存只影响选中的、经过校验的相对路径；它们只改动 Git 索引（绝不改动工作区内容），并可通过相反操作撤销。
- Commit、Push 和分支 switch 先产生预览 token，再要求显式确认。切换分支执行普通的 git switch；工作区脏状态会在确认前报告，由 Git 决定是带冲突继续还是拒绝。
- token 绑定根、操作、参数、指纹和过期时间；仓库状态变化会让 token 失效，有效 token 只能消费一次。
- 更新（支持合并）： 拉取始终先执行。快进式更新——无论工作区干净还是有改动——收到请求后直接运行 git pull --ff-only，不弹确认对话框（仍受指纹绑定的预览 token 保护；Git 拒绝覆盖未提交的改动，任何拒绝都会显示出来）。历史已经分叉时，更新会标记为合并（git pull --no-rebase），需要显式确认，并警告可能产生冲突，还会报告冲突路径供你在外部解决——它绝不自动解决、自动暂存、变基、强制推送或重试。
- 插件绝不自动暂存、合并、变基、强制推送、配置凭据，也不重试被拒绝的推送。

忙碌反馈

工具栏操作会显示进行中状态：快照刷新、预览、确认、暂存或更新运行期间，状态行显示 spinner 和一条短消息，工具栏按钮禁用（当前活跃的那个转圈）。行级和选区级的暂存操作在同一时间窗口内禁用，因此同一时刻只有一个 Git 写入在进行。

v1 已知行为说明（有意设计）

- 暂存直接走同源 /stage 端点，不经过预览 token：这个版本里 Git 暂存没有预览界面（预览类型只有 commit/update/push/switch），该端点受同源和工作区根目录保护，而且这个操作只改动可逆的 Git 索引。需要确认的操作仍受指纹保护。暂存写入被拒绝时，会报告其 code 和 Git 自身的输出。
- 暂存与提交选择联动： 暂存某个路径时也会勾选它用于提交，取消暂存则清除勾选，因此已暂存的文件绝不会在提交中悄悄缺失。提交本身仍以勾选的路径为范围——已对照 Git 验证：a.txt 和 b.txt 都已暂存并又有新改动时，git commit --only -- a.txt 提交了 a.txt 的工作区内容，b.txt 的已暂存内容仍留在暂存区未提交，索引状态从未改变提交包含的内容。
- 「提交前暂存已选」是真实选项，默认关闭。 启用后，流程为 /stage（勾选的路径）→ /preview → 确认 → /confirm。暂存写入必须先于预览，因为暂存会改变仓库指纹，从而使已签发的预览 token 失效；确认对话框会报告这次写入是否会执行。
- Diff 标题写的是「工作区 vs HEAD」。对于部分暂存的文件，显示的 diff 是未暂存的增量；已暂存的 hunk 会在后续阶段纳入。
- 没有操作历史。 失败详情对话框是 Git 诊断信息唯一且必须的展示界面；关闭它会丢弃文本（预留的 Console 视图仍是第二阶段占位）。仓库加载失败则保留常驻提示卡片，不弹模态框。

SVN 边界

本次是首个版本，只支持 Git。宿主工作流把常见的 status/diff/commit/update/history 概念与 Git 独有的暂存能力分开，这样以后就能接入真正的 SVN 适配器，而不必把暂存变成通用要求。